Style becomes a declaration block (TrackStyle / SectionStyle)

[puckey]

Summary

Presentation stops accreting as flat fields in two competing shapes — core style strings (Section.style: 'list' | 'grid' | 'rail', Track.style / Track.childrenStyle) and platform-prefixed hints (carPlay*) — and becomes one CSS-adjacent declaration block:

interface TrackStyle {
  display?: 'list' | 'grid'                      // positional: this holder's own children (never inherited)
  accessorySymbol?: string                       // ┐ inherited item properties:
  artworkRendering?: 'original' | 'stencil'      // │ track ?? section ?? page ?? default
  imageShape?: 'circular' | 'rounded-rectangle'  // │
  cardTint?: string                              // │
  cardImage?: 'normal' | 'background'            // ┘
}
interface SectionStyle extends TrackStyle {
  gridWrap?: boolean                             // ┐ container properties (scope override):
  gridTile?: 'plain' | 'card' | 'condensed'      // ┘ section ?? page ?? default
}

Section.style?: SectionStyle
Track.style?: TrackStyle
ResolvedTrack.style?: SectionStyle   // a page is a Track that is also the container

Full specification: docs/section-styling-design.html (schema with JSDocs, resolution rules, property ledger, rendering matrix, rejected-shapes log). Decision record: ADR 0011. SDK evidence: docs/carplay-sdk-audit.html.

The rules, compressed: declarations are aspirational (each surface renders what it understands, the rest is inert — never an error); item properties are inherited within a page, never across resolution (a handle's block styles the handle); container properties resolve by scope override (page declares for its scope, a section overrides for its own children); display is positional; style is presentation-only — no style property affects queue scope, playback, or navigation; degradation drops decorations before layout.

Breaking

String styles, 'rail', and Track.childrenStyle are deleted — no string shorthand, no dialect normalization. Nothing has shipped, so there is no migration; the wire is flat nested structs.

Checklist (design doc §7)

• Spec: TrackStyle / SectionStyle extends TrackStyle as Nitro structs (named exported unions — inline string unions don't codegen); ResolvedTrack.style widens to SectionStyle; codegen + web-stub mirrors. Ship with the flip: display, gridWrap; other properties land with their features (no dead fields).
• Resolution: one resolver per platform — item properties track ?? section ?? page ?? default; container properties section ?? page ?? default; display on an explicit positional deny-list.
• Spec-level tests: inheritance-completeness (every TrackStyle key read by every resolver, in precedence order; positional keys provably excluded — Nitro erases extends, so types can't enforce it).
• Dev-mode inert-declaration diagnostic (warn when a declaration can never render — gridWrap on a list section, cardTint with no card treatment): InertStyleDiagnostic on both platforms, called from each resolveUncached — structural inertness only, judged per declaring level; the narrower promise-less all-grid page warning (Android) stays as its own check.
• iOS: section presentation keys off display + gridWrap (+ gridTile when it lands); pre-26 degradation — treatment drops, layout survives (gridWrap: false → legacy image row; wrapping grid → list).
• Android: tile detection from resolved display; delete childrenStyle and re-source the parent-level content-style hint from the browsable handle's declared display (the page-layout promise: declared or it doesn't exist, plus a targeted dev warning when a served grid page sits under a promise-less parent). Per-item hints derive from the section resolution.
• Tolerant decoding in both native decoders (decode-to-nil on mismatch — a stale payload must never kill a page or persisted playback state); persisted queues keep style and disabled.
• Track.disabled content fact (see Track.disabled — unavailable items (grayed where drawable, hidden elsewhere) #126): never plays anywhere; grayed where the surface can draw it, hidden where it can't.
• ResolvedTrack → Track projection drops container properties explicitly.
• Docs/guides updated to block authoring; example phone UI may honor gridWrap: false as a horizontal scroller (intended usage).

Follow-ups that land with their features (not this issue)

• style.accessorySymbol — SF Symbol accessory as an inherited style property #125 — style.accessorySymbol
• style.imageShape — tile artwork shape (circular | rounded-rectangle) #131 — style.imageShape
• gridTile: 'card' | 'condensed', cardTint, cardImage — designed in the audit/design doc; no issues until their features land (no dead fields).

[puckey]

Status: all three follow-ups have landed on next — #131 (imageShape) and #125 (accessorySymbol) close with the feat commit, and the card/condensed family (gridTile: 'plain' | 'card' | 'condensed', cardTint, cardImage) shipped with it, completing the ledger's vocabulary. The no-dead-fields rule held throughout: every property landed with a renderer reading it.

Remaining on this issue: only the dev-mode inert-declaration diagnostic (the unchecked item above) — now easier to specify, since the vocabulary is closed and the full set of inert combinations is knowable.

[puckey]

The last unchecked item has landed: the dev-mode inert-declaration diagnostic ships as InertStyleDiagnostic on both platforms (ios/Browser/InertStyleDiagnostic.swift, android/.../browser/InertStyleDiagnostic.kt), called from each resolveUncached.

Where — the resolve funnel, not a renderer: every page passes there whatever its source (static config, route callback, fetched browse JSON), before the blocks are folded, so each finding is attributable to the level that declared it. It runs only on a content-cache miss, so a mistake is reported once per resolution rather than once per serve.

What it reports — only structural inertness, i.e. a declaration the resolved block itself makes unreadable, on every surface:

declaration	inert when
gridWrap, gridTile	effective display isn't 'grid'
cardTint, cardImage	the scope doesn't render gridTile: 'card'
imageShape	not a grid, or a card (cards have no shape)
accessorySymbol	a card grid (no accessory slot)
display	on a track rendered playable (opens no page)
artworkRendering	never — named in the "no condition" list

Surface inertness is never reported: imageShape on Android Auto, or a card treatment pre-26, is the aspirational rule working, not an authoring mistake. That line is what keeps the diagnostic platform-independent — one rule set, mirrored, rather than per-renderer capability tables.

Judged per level. A section-level declaration is checked against its own effective context (section ?? page ?? default); a page-level one against every section it reaches — live in any of them is live, so a page-wide cardTint with one card section stays silent. Shadowed values (every section overrides the page's) aren't reported: the diagnostic answers "can never render", not "is never reached". Track-level findings aggregate per section (2 tracks in section 'Results' declare …).

Sample line, self-contained by design (path, owner, rule, effective style, fix):

Inert style declaration on page '/home': section 'Featured' declares
`style.gridWrap`, which never renders: `gridWrap` renders only in a grid,
but its effective style is display 'list'. Declare `display: 'grid'` on the
section or the page, or drop `gridWrap`.

Held by the spec test. src/style-resolution.test.ts gains a second guard beside inheritance-completeness: every key of the block must be named by each platform's diagnostic — by a rule, or by the explicit "no inertness condition" list. Nitro's extends-flattening leaves the diagnostic as untied to the spec as the resolvers were, so a newly added property can't ship with nobody warned about its inert combinations; naming it becomes a decision rather than an omission.

18 tests per platform (ios/Tests/InertStyleDiagnosticTests.swift, android/.../InertStyleDiagnosticTest.kt), mirrored case for case. Docs updated: design doc §7, ADR 0011's consequences, and a browser-guide note showing the log line.