CBDF Specification: Styles Section

1. Overview

The Styles section defines all visual formatting used in the document. It sits between the first FS (end of Meta) and the second FS (start of Text). After the FS marker:

[Length: 4 bytes LE]
[LayoutID: 2 bytes LE]
[Page background: optional BG record | omitted if next byte is GS]
GS [sub-tables...]

The 4-byte length counts section content only (after the length field). If Meta key 32 (Default Style Set) is ≥ 1, the section may be empty of records (LayoutID + empty GS markers, or delta overrides only).

Click diagram to open full size

Layout catalogue (humans + machines): see 10-Layout-Catalogue and download cbdf-layout-catalog-v1.json.

2. LayoutID (2 bytes LE)

Replaces the Phase II draft 1-byte layout bitfield as the primary layout selector. The client holds a layout catalogue (like the font table): the wire carries only the ID. Each catalogue entry includes a pane index table (which index is header/left/main/right/footer/overlay) and a mobile pair layout id.

2A. Legacy bitfield (low byte of compatibility page)

Legacy 1-byte encoding (bits 0–3 panels, 4–5 cols, 6–7 rows) — used when LayoutID is in 0x0000–0x00FF

Main is always implied.

2B. Catalogue entries (LayoutID ≥ 0x0100)

Each catalogue entry defines topology and default geometry: pane existence, full-height left/right asides (past header and/or beside footer), centered modal-like islands, grid splits, and default margin/padding/width hints. Fine styling remains in style sub-tables; catalogue metrics are defaults overridden by explicit styles and user themes.

Encoders that require exact catalogue layout fidelity SHOULD set Required Features bit 11 (catalog layout).

2C. Pane index order (canonical)

Every catalogue entry declares a pane index table. Default / general rule:

1. Header (if present)
2. Left aside (if present)
3. Main cells, row-major (left→right, top→bottom)
4. Right aside (if present)
5. Footer (if present)

Full-height asides keep reading-order position. A centered overlay/island pane indexes last (plain-text extraction after normal flow). Only existing panes consume indices.

2D. Unknown LayoutID

If the client lacks a catalogue entry for the ID, it also lacks that layout's pane index table — it cannot know the pane count, order, or special panes. This is registry version skew, not necessarily corruption. The client's response depends on the encoder's declared intent:

• Required Features bit 11 set (exact catalogue layout required): fail closed — do not attempt a styled render; show the labeled plain-text extraction with a notice that the document requires a newer layout catalogue.
• Bit 11 not set: render as LayoutID 0x0000 (single main flow, content in stream order) with a user-visible notice that the intended layout is unavailable.

Clients MUST implement exactly this policy pair (no silent fallback, no invented pane geometry). Phase II clients implement a small subset of IDs; the number space is reserved.

3. Sub-Table Header Byte

Each sub-table begins with one header byte:

All records in a sub-table share the same tier (fixed size). Non-tiered tables force tier bits = 00.

4. Sub-Table Order

Sub-tables appear in fixed order, separated by GS (0x1D):

Empty sub-table = bare GS (parsers also accept header with count 0).

5. Packed Records (no RS)

sub-table := GS [Header:1] [record × count]
record_ptr(i) = table_start + 1 + i * record_size(tier)

There is no RS between fixed-size style records. RS is reserved for table rows in the Text section only.

6. Record Formats (normative byte layouts)

Record sizes (unchanged):

The per-byte layouts below are normative (completed 2026-07-18; they finalize the layouts the prior revision deferred to "prior Phase II detail"). Conventions: all multi-byte integers little-endian; all colors R5G6B5 or transparency codes per 08-Color-System; extended/rare tiers extend the smaller tier without moving its fields; every byte marked reserved MUST be written 0 and ignored on read. Optional style-index reference fields use 255 = no reference (valid record indexes are 0–62; 255 never collides).

6.1 Text Style (tiers 8 / 12 / 16 B)

6.2 Background (tiers 6 / 12 / 20 B)

6.3 Border (9 B)

Line style is solid in Phase II; dashed/dotted are reserved for a future tier.

6.4 Spacing (4 B)

Nibble semantics: 0 = explicit zero; 15 = inherit-from-left (the nibble to its left in the same byte pair order top→right→bottom→left; top inheriting = inherit from default); 1–14 = value × 4 px (4–56 px).

6.5 Shadow (4 B)

6.6 Composite (5 B)

6.7 Font Effect (4 B) and effect registry

Effect IDs: 0 none · 1 drop shadow · 2 outer glow · 3 pulsing glow · 4 linear gradient · 5 multi-gradient · 6 outline/stroke · 7 emboss/bevel · 8 glitter · 9 flames · 10 neon · 11 3D extrude · 12 reflection · 13 frosted glass · 14 metallic · 15 custom (deterministic parameters via this sub-table — never AI; AI styling has AI_PROMPT). Animated effects render a static representative frame outside the editor detail panel; reduced-motion preferences always win. Text rare byte 12 references effects by the 4-bit ID. The Font Effect sub-table is keyed by Effect ID: at most one record per Effect ID; a second record with the same ID makes the Styles section invalid (strict-parse reject). A Text style referencing an effect with no matching Font Effect record uses that effect's deterministic defaults (intensity from Text rare byte 12; parameters 0).

6.8 Nav Bar (12 B)

6.9 Table (6 B)

6.10 Image Definition (8 B)

6.11 Frame Definition (8 B)

General notes: Hover/event fields are declarative appearance only in Phase II (actions = Phase III Logic). Decoders MUST accept any record whose reserved fields are non-zero (ignore them) but encoders MUST write zeros — reserved bytes are the compatibility headroom of each record.

7. Layer Registry (composite layer_id)

8. Page Background

Immediately after LayoutID, before the first GS: optional single BG record for the page (layer 0). If the next byte is GS, page background is default/transparent.

9. Minimum Styles Section

Length = 14 (0x0E 00 00 00)
LayoutID = 0x0000
GS × 12 (empty sub-tables)

Plus outer FS before the length when framed in the document.

10. Default Style Sets

Meta key 32: 0 = explicit styles; 1 = client default theme (section may hold deltas by index); 2–255 = named style sets (open registry). User themes override rendering locally but never redefine a named set ID.

11. Future / Post-Phase-II Container Background Extensions (non-normative)

Status: exploratory. NOT part of Phase II. Nothing here is implemented, encoded, or decoded today. This section records candidate future styling for containers (panels and other regions that hold text, images, tables, and nav). It reserves design intent so the wire format leaves room for it: the Background record (§6.2) still has reserved bytes 11 and 18–19 and unused tiers, the Composite record (§6.6) is 5 B with obvious extension room, and every decoder already ignores non-zero reserved bytes (§6 general notes) — so any of the below can be added later as an extended/rare tier without breaking existing documents. These are capabilities, not committed byte layouts; exact bytes are assigned when (and if) a feature is scheduled.

11.1 Container transparency ("glass")

Let a container background be semi-transparent so content painted behind the panel shows through — a frosted/glass panel over the page background or a lower layer. The Background record already carries a color opacity (§6.2 byte 4); this extends the idea to the container's whole background fill (color + image + gradient composited), i.e. a panel-level alpha applied to the composited background before content is drawn over it. Interacts with the layer system (§7): a transparent layer-1 panel reveals layer-0 (page background). Candidate home: a Composite-record extended byte (container background alpha 0–255), or a Background rare byte. Renderer note: correct only with back-to-front layer compositing; the SDL_Renderer fallback may approximate (flatten to the page background) — permitted under the optional-feature model.

11.2 Backdrop blur

When a container is transparent (§11.1), optionally blur what is behind it (a "frosted glass" backdrop, distinct from the text-only frosted glass font effect ID 13 in §6.7). A blur radius (e.g. 0–15, matching the 4-bit blur fields already used by Shadow §6.5 and Text-shadow §6.1) would sample the already-composited content behind the panel and Gaussian-blur it before the panel's own (semi-transparent) fill is applied. Candidate home: a Composite extended byte (backdrop-blur radius), gated on the container being transparent. Renderer note: this is a GPU-pipeline feature — it needs a fragment-shader pass sampling the framebuffer/prior render target, so it depends on the deferred SDL_GPU renderer path (see 00-Overview / master-plan §3); the SDL_Renderer fallback would omit blur (transparent-but-unblurred) with no data loss. Security: blur only samples already-rendered in-document content — never anything outside the document surface.

11.3 Animated container backgrounds

Idea parked for the future. Allow a container's background image (§6.2 background image / gradient) to animate: the whole background image could scroll (pan, e.g. a slow parallax drift), zoom (Ken-Burns-style scale over time), and/or rotate behind the container's content, with the content on top held still. This parallels the animated font effects (§6.7 — pulsing glow, flames, neon), which likewise render a static representative frame outside the editor and honor reduced-motion. A future encoding might add an animation descriptor to the Background record (motion type: none/scroll/zoom/rotate/combination; direction/axis; speed; loop mode) in a new rare/extended tier. Same universal rules would apply: reduced-motion preferences always win (static representative frame when motion is suppressed), animation is an optional feature (fallback renders the first frame), and it is declarative appearance only (no scripting; Phase III Logic remains fenced). GPU-pipeline feature, like §11.2.

These three are complementary: 11.1 (transparency) is the prerequisite for 11.2 (backdrop blur), and 11.3 (animation) is independent and the largest — all three are post-Phase-II and most naturally land after the SDL_GPU renderer and MSDF work exist. Recorded here at author request (2026-07-19) so the design intent and the reserved wire headroom are captured before the records are frozen.