@adia-ai/web-components 0.5.12 → 0.5.13

package/CHANGELOG.md

@@ -11,6 +11,69 @@ runtime ships in the sibling `@adia-ai/a2ui-runtime` package
 
 _No pending changes._
 
+## [0.5.13] - 2026-05-15
+
+### v0.5.13 §310 — `apcaContrast` soft-clamp constant fix (FEEDBACK-35; P2 correctness)
+
+`@adia-ai/web-components/color`'s `apcaContrast()` was using `APCA_LO_CLAMP = 0.06` for the soft-clamp threshold where the canonical APCA spec (`apca-w3@0.1.9`'s `SAPC_BLACK_THRESHOLD`) calls for `0.022`. The cubic-root soft-clamp `Math.pow(threshold - Y, 1.414)` operating on the wrong threshold lifted near-black luminance too aggressively. Pre-fix `apcaContrast('#000','#fff')` returned 99.49; post-fix returns 106.04 — matches canonical reference within ±0.01 Lc across all 8 reference pairs. Consumers using `<swatch-ui auto-contrast>` (which transitively calls `pickContrastingFg → apcaContrast`) silently got wrong contrast verdicts for any swatch with `Y < 0.06`.
+
+#### Fixed — `color/`
+
+- `color/index.js` `apcaContrast()` soft-clamp now uses `APCA_LO_FG`/`APCA_LO_BG = 0.022` (declared correctly since v0.5.12 but never read). Dead constants (`APCA_NORM_L`, `APCA_REVERSE_FACTOR`, `APCA_NORM_FACTOR`, `APCA_LO_CLAMP`, `APCA_RESCALE`) removed; new `APCA_BLACK_CLAMP = 1.414` factored out for readability.
+
+### v0.5.13 §311 — `@adia-ai/web-components/color` P3 helpers (FEEDBACK-31)
+
+`@adia-ai/web-components/color` (v0.5.12 §301) shipped sRGB-only gamut helpers; the v0.6.0 §301 plan-doc spec lines 121-126 committed both sRGB AND Display-P3. v0.5.13 §311 closes the gap.
+
+#### Added — `color/`
+
+- `inP3Gamut(L, C, H): boolean` — returns true if the OKLCH triple is inside Display-P3 gamut (tolerance `0.001`).
+- `gamutMapChromaP3(L, C, H): number` — 8-iteration chroma bisection in P3 (matches `gamutMapChroma`'s shape).
+- Internal `linearSrgbToLinearP3()` matrix sourced from CSS Color 4 § 12.3 (D65 → D65; no Bradford chromatic adaptation needed).
+- `color/index.d.ts` ships matching declarations.
+
+### v0.5.13 §312 — `<stat-ui>` explicit exports map entries (FEEDBACK-32)
+
+v0.5.12 §253a hand-authored `stat-ui.d.ts` on disk but the package.json wildcard `./components/*` expanded `./components/stat` → `./components/stat/stat.js` (non-existent; actual file is `stat-ui.js`). Consumer TS imports failed at the package-export layer with `TS2882` even though the file exists + Vite resolved at runtime.
+
+#### Changed — `package.json`
+
+- `exports` map adds 2 explicit entries: `./components/stat` + `./components/stat/stat-ui.js` both pointing at `stat-ui.{d.ts,js}`.
+- **Drops at v0.6.0 §303** when the `git mv stat-ui.{js,css,d.ts} → stat.{js,css,d.ts}` rename normalizes the filename + the wildcard naturally covers `stat.{js,d.ts}`.
+
+### v0.5.13 §313 — `<color-input-ui>` constraint pass-through + parsed-detail forwarding (FEEDBACK-33)
+
+`<color-input-ui>` (v0.5.12 §302) composed `<color-picker-ui>` but dropped 5 generation-constraint props (`maxChroma` / `maxL` / `minL` / `hueDriftMax` / `baseHue`) and 3 parsed-OKLCH-channel-scalars (`{l, c, h}`) from the re-emitted event detail. Consumers using L-range constraints or OKLCH-native logic (Tokens Studio's `defaults.Lmin`/`Lmax`) couldn't migrate to `<color-input-ui>` without a UX regression.
+
+#### Added — `components/color-input/`
+
+- `class.js` adds 5 generation-constraint props to `static properties` + sets them on inner picker at `#mount()` + diff-detect re-set on `render()` (Object.is handles NaN-equality for `baseHue`/`hueDriftMax`).
+- `#commit()` re-emits with all 6 detail fields including parsed scalars `l: detail.l, c: detail.c, h: detail.h`.
+- `color-input.yaml` declares the 5 props + 3 new detail fields per `change`/`input` events.
+- `color-input.d.ts` `ColorInputChangeEventDetail` interface gains `l: number; c: number; h: number;` fields; class gains 5 typed prop declarations.
+
+### v0.5.13 §314 — `<swatch-ui>` `[slot="chrome"]` named slot (FEEDBACK-34)
+
+`<swatch-ui>`'s `#stamp()` lifecycle wiped `innerHTML` then funneled surviving children into `#labelEl`. Consumer chrome positioned absolutely against the swatch tile (gamut badges + override/tracked dots per C1.3 dogfood) landed inside the label's text bbox where `position: absolute; top/right/bottom/left` anchored to the small label geometry instead of the tile. v0.5.13 §314 adds a `[slot="chrome"]` named slot whose children survive stamping as direct host siblings of `#tileEl`.
+
+#### Added — `components/swatch/`
+
+- `class.js` `#stamp()` extracts `[slot="chrome"]` children BEFORE the wipe; re-attaches them as direct host siblings IMMEDIATELY after `#tileEl`. The host's `position: relative` anchor (when `shape="block"`) lets consumer absolute-positioning anchor to the tile's geometry.
+- `swatch.yaml` `slots:` block declares the `chrome` named slot + clarifies `default` slot's funnel-into-label behavior.
+
+#### Migration
+
+```diff
+ <swatch-ui shape="block" label-position="overlay" selectable>
+-  <badge-ui class="dts-gamut-badge" ...>P3</badge-ui>
+-  <span class="dts-override-dot"></span>
++  <badge-ui slot="chrome" class="dts-gamut-badge" ...>P3</badge-ui>
++  <span slot="chrome" class="dts-override-dot"></span>
+ </swatch-ui>
+```
+
+Single `slot="chrome"` attribute on each chrome element. Existing absolute-positioning CSS unchanged.
+
 ## [0.5.12] - 2026-05-15
 
 ### v0.5.12 §252 — `package.json` `files` array completion (FB-28 close-out)

package/color/index.d.ts

@@ -87,6 +87,22 @@ export function isOklchInGamut(L: number, C: number, H: number): boolean;
  */
 export function gamutMapChroma(L: number, C: number, H: number): number;
 
+// ── Display-P3 gamut (v0.5.13 §-TBD, FB-31) ──────────────────────────────
+
+/**
+ * Returns true if the OKLCH triple is inside Display-P3 gamut (tolerance
+ * `0.001`). sRGB-linear → P3-linear conversion uses the CSS Color 4 § 12.3
+ * matrix (D65 → D65; no Bradford adaptation needed).
+ */
+export function inP3Gamut(L: number, C: number, H: number): boolean;
+
+/**
+ * Bisect chroma to find the largest value that keeps `(L, _, H)` in
+ * Display-P3 gamut. 8 bisection iterations — same shape as the sRGB
+ * `gamutMapChroma`. Used by P3-aware design tooling.
+ */
+export function gamutMapChromaP3(L: number, C: number, H: number): number;
+
 // ── APCA (advanced perceptual contrast algorithm) ─────────────────────────
 
 /**

package/color/index.js

@@ -154,15 +154,67 @@ export function gamutMapChroma(L, C, H) {
   return lo;
 }
 
+// ── Display-P3 gamut ──────────────────────────────────────────────────────
+//
+// v0.5.13 §-TBD (FB-31). The v0.6.0 §301 plan-doc spec committed
+// `inP3Gamut(o)` + `gamutMapOklch(o, 'p3')`; the v0.5.12 §301 ship dropped
+// both (sRGB-only surface). FB-31 closes the gap with explicit P3 helpers
+// matching the existing scalar-channels signature shape.
+//
+// sRGB-linear → Display-P3-linear matrix sourced from CSS Color 4 § 12.3
+// (assumes both spaces share the D65 white point, which is true post-2018
+// browser implementations; no Bradford chromatic adaptation needed).
+
+function linearSrgbToLinearP3(r, g, b) {
+  return [
+    0.8224621 * r + 0.1775380 * g + 0.0000000 * b,
+    0.0331941 * r + 0.9668058 * g + 0.0000001 * b,
+    0.0170827 * r + 0.0723974 * g + 0.9105199 * b,
+  ];
+}
+
+/** Returns true if the OKLCH triple is inside Display-P3 gamut (tolerance `0.001`). */
+export function inP3Gamut(L, C, H) {
+  const { a, b } = oklchToOklab(L, C, H);
+  const [lr, lg, lb] = oklabToLinearSrgb(L, a, b);
+  const [p3r, p3g, p3b] = linearSrgbToLinearP3(lr, lg, lb);
+  return isInGamut(linearToSrgb(p3r), linearToSrgb(p3g), linearToSrgb(p3b));
+}
+
+/**
+ * Bisect chroma to find the largest value that keeps `(L, _, H)` in
+ * Display-P3 gamut. 8 bisection iterations — same shape as the sRGB
+ * `gamutMapChroma`. Used by P3-aware design tooling (Tokens Studio,
+ * theme designers targeting P3-display laptops + iPads).
+ */
+export function gamutMapChromaP3(L, C, H) {
+  if (inP3Gamut(L, C, H)) return C;
+  let lo = 0, hi = C;
+  for (let i = 0; i < 8; i++) {
+    const mid = (lo + hi) / 2;
+    if (inP3Gamut(L, mid, H)) lo = mid;
+    else hi = mid;
+  }
+  return lo;
+}
+
 // ── APCA (advanced perceptual contrast algorithm) ─────────────────────────
+//
+// Source of truth: Andrew Somers' SACAM specification + apca-w3@0.1.9 (the
+// W3C-pinned reference impl). The soft-clamp threshold is `0.022` for both
+// fg + bg luminance values (per `SAPC_BLACK_THRESHOLD` in apca-w3 source).
+// The 1.414 exponent is the APCA "BLACK_CLAMP" rescale constant.
+//
+// v0.5.13 §-TBD (FB-35): corrected the soft-clamp constant. v0.5.12 ship
+// used 0.06 (declared as APCA_LO_CLAMP) by mistake, producing Lc 99.49 for
+// black-on-white where canonical is 106.04 (-6.5pt bias for any pair
+// involving near-black). Constants APCA_LO_FG / APCA_LO_BG were declared
+// correctly but never read; the 0.06 constant was a stray from an earlier
+// draft. apcaSrgbY() unchanged.
 
-const APCA_NORM_L = 0.027;
 const APCA_LO_BG = 0.022;
 const APCA_LO_FG = 0.022;
-const APCA_REVERSE_FACTOR = 1.14;
-const APCA_NORM_FACTOR = 1.14;
-const APCA_LO_CLAMP = 0.06;
-const APCA_RESCALE = 1.14;
+const APCA_BLACK_CLAMP = 1.414;
 
 function apcaSrgbY(rNorm, gNorm, bNorm) {
   // sRGB → relative luminance via APCA Y (different coefficients than WCAG).
@@ -201,9 +253,10 @@ export function apcaContrast(fgHex, bgHex) {
   let Yfg = apcaSrgbY(fg.r, fg.g, fg.b);
   let Ybg = apcaSrgbY(bg.r, bg.g, bg.b);
 
-  // Soft clamp near black per APCA.
-  if (Yfg < APCA_LO_CLAMP) Yfg += Math.pow(APCA_LO_CLAMP - Yfg, 1.414);
-  if (Ybg < APCA_LO_CLAMP) Ybg += Math.pow(APCA_LO_CLAMP - Ybg, 1.414);
+  // Soft clamp near black per APCA spec — threshold 0.022 per SACAM /
+  // apca-w3@0.1.9 (`SAPC_BLACK_THRESHOLD`).
+  if (Yfg < APCA_LO_FG) Yfg += Math.pow(APCA_LO_FG - Yfg, APCA_BLACK_CLAMP);
+  if (Ybg < APCA_LO_BG) Ybg += Math.pow(APCA_LO_BG - Ybg, APCA_BLACK_CLAMP);
 
   let Lc;
   if (Ybg > Yfg) {

package/components/color-input/class.js

@@ -40,10 +40,20 @@ export class UIColorInput extends UIFormElement {
   static get properties() {
     return {
       ...UIFormElement.properties,
-      value:     { type: String,  default: '#3b82f6', reflect: true },
-      format:    { type: String,  default: 'hex', reflect: true },
-      placement: { type: String,  default: 'bottom-start', reflect: true },
-      open:      { type: Boolean, default: false, reflect: true },
+      value:       { type: String,  default: '#3b82f6', reflect: true },
+      format:      { type: String,  default: 'hex', reflect: true },
+      placement:   { type: String,  default: 'bottom-start', reflect: true },
+      open:        { type: Boolean, default: false, reflect: true },
+      // Generation-constraint props forwarded to the inner <color-picker-ui>.
+      // v0.5.13 §-TBD (FB-33 §1) — full parity with color-picker's 5 constraint
+      // props (`maxChroma` / `maxL` / `minL` / `hueDriftMax` / `baseHue`) so
+      // <color-input-ui> adoption doesn't force a UX regression on consumers
+      // already using L-range / chroma / hue-drift constraints.
+      maxChroma:   { type: Number,  default: Infinity, reflect: true },
+      maxL:        { type: Number,  default: 1, reflect: true },
+      minL:        { type: Number,  default: 0, reflect: true },
+      hueDriftMax: { type: Number,  default: NaN, reflect: true },
+      baseHue:     { type: Number,  default: NaN, reflect: true },
     };
   }
 
@@ -66,8 +76,16 @@ export class UIColorInput extends UIFormElement {
     if (this.#popover && this.#popover.open !== this.open) {
       this.#popover.open = this.open;
     }
-    if (this.#picker && this.#picker.format !== this.format) {
-      this.#picker.format = this.format;
+    if (this.#picker) {
+      if (this.#picker.format !== this.format) this.#picker.format = this.format;
+      // Forward live changes to the 5 generation-constraint props (FB-33 §1).
+      // Object.is handles the NaN-equality case correctly so `baseHue`/
+      // `hueDriftMax` don't reassign on every render.
+      if (!Object.is(this.#picker.maxChroma, this.maxChroma))   this.#picker.maxChroma = this.maxChroma;
+      if (!Object.is(this.#picker.maxL, this.maxL))             this.#picker.maxL = this.maxL;
+      if (!Object.is(this.#picker.minL, this.minL))             this.#picker.minL = this.minL;
+      if (!Object.is(this.#picker.hueDriftMax, this.hueDriftMax)) this.#picker.hueDriftMax = this.hueDriftMax;
+      if (!Object.is(this.#picker.baseHue, this.baseHue))       this.#picker.baseHue = this.baseHue;
     }
     if (this.#button) {
       if (this.disabled) this.#button.setAttribute('disabled', '');
@@ -115,6 +133,13 @@ export class UIColorInput extends UIFormElement {
     picker.setAttribute('slot', 'content');
     picker.setAttribute('format', this.format);
     picker.setAttribute('value', this.value);
+    // Set generation-constraint props directly (numeric — attribute-reflection
+    // would round-trip but properties cover NaN/Infinity correctly).
+    picker.maxChroma = this.maxChroma;
+    picker.maxL = this.maxL;
+    picker.minL = this.minL;
+    picker.hueDriftMax = this.hueDriftMax;
+    picker.baseHue = this.baseHue;
 
     popover.append(button, picker);
     this.append(popover);
@@ -162,10 +187,20 @@ export class UIColorInput extends UIFormElement {
       this.syncValue(next);
     }
     this.#syncFromValue();
+    // Forward the inner picker's parsed OKLCH channel scalars (v0.5.13 §-TBD,
+    // FB-33 §1-adjacent). Consumers writing OKLCH-native logic get the parsed
+    // {l, c, h} for free, matching <color-picker-ui>'s detail shape.
     this.dispatchEvent(new CustomEvent(kind, {
       bubbles: true,
       composed: true,
-      detail: { value: next ?? this.value, hex: detail.hex, oklch: detail.oklch },
+      detail: {
+        value: next ?? this.value,
+        hex: detail.hex,
+        oklch: detail.oklch,
+        l: detail.l,
+        c: detail.c,
+        h: detail.h,
+      },
     }));
   }
 

package/components/color-input/color-input.a2ui.json

@@ -13,6 +13,11 @@
     }
   ],
   "properties": {
+    "baseHue": {
+      "description": "Reference hue (degrees) for the hueDriftMax constraint, forwarded to inner picker. Default NaN — picker falls back to its hue at first commit.",
+      "type": "number",
+      "default": "NaN"
+    },
     "component": {
       "const": "ColorInput"
     },
@@ -30,6 +35,26 @@
       ],
       "default": "hex"
     },
+    "hueDriftMax": {
+      "description": "Generation constraint forwarded to inner picker — maximum allowed signed-shortest-path hue deviation (degrees) from baseHue. Default NaN (no constraint).",
+      "type": "number",
+      "default": "NaN"
+    },
+    "maxChroma": {
+      "description": "Generation constraint forwarded to the inner `<color-picker-ui>` (v0.5.13\n§-TBD, FB-33 §1). Clamp the OKLCH chroma channel to at most this value.\nDefault Infinity (no constraint).\n",
+      "type": "number",
+      "default": "Infinity"
+    },
+    "maxL": {
+      "description": "Generation constraint forwarded to inner picker — clamp OKLCH lightness to at most this value (0..1). Default 1.",
+      "type": "number",
+      "default": 1
+    },
+    "minL": {
+      "description": "Generation constraint forwarded to inner picker — clamp OKLCH lightness to at least this value (0..1). Default 0.",
+      "type": "number",
+      "default": 0
+    },
     "name": {
       "description": "Form field name.",
       "type": "string",
@@ -77,10 +102,22 @@
       "change": {
         "description": "Fired when the color is committed (pointerup / Enter / picker close). Bubbles from inner picker.",
         "detail": {
+          "c": {
+            "description": "Parsed OKLCH chroma scalar.",
+            "type": "number"
+          },
+          "h": {
+            "description": "Parsed OKLCH hue scalar (degrees, NaN ok for achromatic).",
+            "type": "number"
+          },
           "hex": {
             "description": "Hex form (`#rrggbb`).",
             "type": "string"
           },
+          "l": {
+            "description": "Parsed OKLCH lightness scalar (0..1). v0.5.13 §-TBD (FB-33 §1-adjacent).",
+            "type": "number"
+          },
           "oklch": {
             "description": "OKLCH string (`oklch(L C H)`).",
             "type": "string"
@@ -94,9 +131,18 @@
       "input": {
         "description": "Fired during continuous drag of the inner picker. Bubbles from inner picker.",
         "detail": {
+          "c": {
+            "type": "number"
+          },
+          "h": {
+            "type": "number"
+          },
           "hex": {
             "type": "string"
           },
+          "l": {
+            "type": "number"
+          },
           "oklch": {
             "type": "string"
           },

package/components/color-input/color-input.d.ts

@@ -38,6 +38,12 @@ export interface ColorInputChangeEventDetail {
   hex: string;
   /** OKLCH string (`oklch(L C H)`, fixed precision). */
   oklch: string;
+  /** Parsed OKLCH lightness (0..1). v0.5.13 §-TBD (FB-33 §1-adjacent). */
+  l: number;
+  /** Parsed OKLCH chroma. */
+  c: number;
+  /** Parsed OKLCH hue (degrees, NaN ok for achromatic). */
+  h: number;
 }
 export type ColorInputChangeEvent = CustomEvent<ColorInputChangeEventDetail>;
 export type ColorInputInputEvent = CustomEvent<ColorInputChangeEventDetail>;
@@ -55,6 +61,16 @@ export class UIColorInput extends UIFormElement {
   placement: 'top' | 'bottom' | 'left' | 'right' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end';
   /** Reflects the inner popover's open state. Set programmatically to open/close without a click. */
   open: boolean;
+  /** Generation constraint forwarded to inner picker: clamp OKLCH chroma to at most this value. `Infinity` = unconstrained. v0.5.13 §-TBD (FB-33 §1). */
+  maxChroma: number;
+  /** Generation constraint forwarded to inner picker: clamp OKLCH lightness to at most this value (0..1). `1` = unconstrained. */
+  maxL: number;
+  /** Generation constraint forwarded to inner picker: clamp OKLCH lightness to at least this value (0..1). `0` = unconstrained. */
+  minL: number;
+  /** Generation constraint forwarded to inner picker: maximum allowed signed-shortest-path hue drift in degrees from `baseHue`. `NaN` = unconstrained. */
+  hueDriftMax: number;
+  /** Reference hue (degrees) for `hueDriftMax`, forwarded to inner picker. `NaN` = picker falls back to its hue at first commit. */
+  baseHue: number;
 
   /** Open the picker programmatically. */
   showPicker(): void;

package/components/color-input/color-input.yaml

@@ -61,6 +61,34 @@ props:
     type: boolean
     default: false
     reflect: true
+  maxChroma:
+    description: |
+      Generation constraint forwarded to the inner `<color-picker-ui>` (v0.5.13
+      §-TBD, FB-33 §1). Clamp the OKLCH chroma channel to at most this value.
+      Default Infinity (no constraint).
+    type: number
+    default: Infinity
+    reflect: true
+  maxL:
+    description: Generation constraint forwarded to inner picker — clamp OKLCH lightness to at most this value (0..1). Default 1.
+    type: number
+    default: 1
+    reflect: true
+  minL:
+    description: Generation constraint forwarded to inner picker — clamp OKLCH lightness to at least this value (0..1). Default 0.
+    type: number
+    default: 0
+    reflect: true
+  hueDriftMax:
+    description: Generation constraint forwarded to inner picker — maximum allowed signed-shortest-path hue deviation (degrees) from baseHue. Default NaN (no constraint).
+    type: number
+    default: NaN
+    reflect: true
+  baseHue:
+    description: Reference hue (degrees) for the hueDriftMax constraint, forwarded to inner picker. Default NaN — picker falls back to its hue at first commit.
+    type: number
+    default: NaN
+    reflect: true
 events:
   change:
     description: Fired when the color is committed (pointerup / Enter / picker close). Bubbles from inner picker.
@@ -74,6 +102,15 @@ events:
       oklch:
         type: string
         description: OKLCH string (`oklch(L C H)`).
+      l:
+        type: number
+        description: Parsed OKLCH lightness scalar (0..1). v0.5.13 §-TBD (FB-33 §1-adjacent).
+      c:
+        type: number
+        description: Parsed OKLCH chroma scalar.
+      h:
+        type: number
+        description: Parsed OKLCH hue scalar (degrees, NaN ok for achromatic).
   input:
     description: Fired during continuous drag of the inner picker. Bubbles from inner picker.
     detail:
@@ -84,6 +121,12 @@ events:
         type: string
       oklch:
         type: string
+      l:
+        type: number
+      c:
+        type: number
+      h:
+        type: number
 slots: {}
 states:
   - name: idle

package/components/swatch/class.js

@@ -212,8 +212,20 @@ export class UISwatch extends UIElement {
 
   #stamp() {
     if (this.#stamped) return;
+
+    // v0.5.13 §-TBD (FB-34 §1) — `[slot="chrome"]` children are sibling-of-tile
+    // chrome (gamut badges, override/tracked dots, custom indicators) that must
+    // survive stamping as direct host siblings, NOT funnel into #labelEl where
+    // absolute-positioning anchors against the label text bbox. Pull them out
+    // FIRST so the innerHTML='' wipe below doesn't lose them.
+    const chromeSlot = Array.from(this.children).filter(
+      n => n.getAttribute && n.getAttribute('slot') === 'chrome'
+    );
+    for (const n of chromeSlot) n.remove();
+
     // Capture pre-existing default-slot content so consumer-authored
     // children (e.g. <swatch-ui>Forecast</swatch-ui>) survive stamping.
+    // `[slot="chrome"]` children are already removed above, so won't appear here.
     const slotted = Array.from(this.childNodes).filter(n =>
       !(n.nodeType === 1 && n.dataset && (
         n.dataset.tile !== undefined ||
@@ -230,6 +242,14 @@ export class UISwatch extends UIElement {
     this.#tileEl.setAttribute('aria-hidden', 'true');
     this.appendChild(this.#tileEl);
 
+    // Chrome-slot children re-attach IMMEDIATELY after the tile so they can
+    // position absolutely against the host (host carries position: relative
+    // when shape="block" + label-position="overlay" per swatch.css). Keeping
+    // them sibling-of-tile (not descendant-of-tile) lets consumer CSS use
+    // `position: absolute; top: 2px; right: 2px` and anchor against the host's
+    // padding-box, which matches the tile's geometry in the block layout.
+    for (const n of chromeSlot) this.appendChild(n);
+
     // Badge container — holds one or more <span data-badge-variant="..."> children.
     // Multi-badge support added in v0.4.9 §92 (FEEDBACK-04 follow-up).
     this.#badgeEl = document.createElement('span');

package/components/swatch/swatch.a2ui.json

@@ -149,7 +149,10 @@
     ],
     "slots": {
       "default": {
-        "description": "Optional rich label content. When present, replaces the [label] attribute's text."
+        "description": "Optional rich label content. When present, replaces the [label]\nattribute's text. Consumer chrome positioned absolutely against the\nswatch tile should use `[slot=\"chrome\"]` instead — default-slot\nchildren are funneled into the label region.\n"
+      },
+      "chrome": {
+        "description": "§-TBD (v0.5.13, FB-34 §1). Sibling-of-tile chrome — gamut badges,\noverride/tracked dots, custom indicators — that survives stamping as\na direct host sibling rather than being funneled into the label. Pair\nwith consumer-authored CSS `position: absolute` against the host\n(the host carries `position: relative` when `shape=\"block\"`, so\n`top/right/bottom/left` offsets anchor to the tile's geometry).\nCloses the C1.3 dogfood chrome-overlay composition gap.\n"
       }
     },
     "states": [

package/components/swatch/swatch.yaml

@@ -119,7 +119,20 @@ events:
         description: The [label] attribute value.
 slots:
   default:
-    description: Optional rich label content. When present, replaces the [label] attribute's text.
+    description: |
+      Optional rich label content. When present, replaces the [label]
+      attribute's text. Consumer chrome positioned absolutely against the
+      swatch tile should use `[slot="chrome"]` instead — default-slot
+      children are funneled into the label region.
+  chrome:
+    description: |
+      §-TBD (v0.5.13, FB-34 §1). Sibling-of-tile chrome — gamut badges,
+      override/tracked dots, custom indicators — that survives stamping as
+      a direct host sibling rather than being funneled into the label. Pair
+      with consumer-authored CSS `position: absolute` against the host
+      (the host carries `position: relative` when `shape="block"`, so
+      `top/right/bottom/left` offsets anchor to the tile's geometry).
+      Closes the C1.3 dogfood chrome-overlay composition gap.
 states:
   - name: idle
     description: Default, ready for display.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/web-components",
-  "version": "0.5.12",
+  "version": "0.5.13",
   "description": "AdiaUI web components — vanilla custom elements. A2UI runtime (renderer, registry, streams, wiring) lives in @adia-ai/a2ui-runtime.",
   "type": "module",
   "types": "./index.d.ts",
@@ -23,6 +23,14 @@
       "types": "./components/*/*.d.ts",
       "default": "./components/*/*.js"
     },
+    "./components/stat": {
+      "types": "./components/stat/stat-ui.d.ts",
+      "default": "./components/stat/stat-ui.js"
+    },
+    "./components/stat/stat-ui.js": {
+      "types": "./components/stat/stat-ui.d.ts",
+      "default": "./components/stat/stat-ui.js"
+    },
     "./components/*/class": {
       "types": "./components/*/*.d.ts",
       "default": "./components/*/class.js"