@lostgradient/cinder 0.2.0 → 0.3.0

package/src/components/chip/chip.svelte

@@ -111,6 +111,16 @@
     }
     return result;
   });
+
+  // A bare `role="group"` needs an accessible name, so removable mode names the
+  // group with its `label` by default. But `aria-label` flows through `rest` for
+  // display/removable modes (see above), so a consumer-supplied `aria-label`
+  // must win. Resolve to the consumer's value when present, falling back to
+  // `label` — and apply it explicitly so it can't be clobbered by the spread.
+  const removableAriaLabel = $derived.by(() => {
+    const forwarded = rest['aria-label'];
+    return typeof forwarded === 'string' && forwarded.trim().length > 0 ? forwarded : label;
+  });
 </script>
 
 {#if mode === 'toggle'}
@@ -141,6 +151,8 @@
 {:else if mode === 'removable'}
   <span
     {...rest}
+    role="group"
+    aria-label={removableAriaLabel}
     data-cinder-mode="removable"
     data-cinder-variant={variant}
     data-cinder-size={size}

package/src/components/chip/chip.types.ts

@@ -11,12 +11,18 @@ export type ChipMode = 'display' | 'toggle' | 'removable';
  */
 export type ChipDensity = 'toolbar';
 export type ChipDisplayProps = Omit<HTMLAttributes<HTMLSpanElement>, 'class'> & {
+  /** Rendering and interaction mode. Default `"display"`. */
   mode?: 'display';
+  /** Visible text content of the chip. */
   label: string;
+  /** Color variant applied to the chip. Default `"neutral"`. */
   variant?: ChipVariant;
+  /** Size of the chip. Default `"md"`. */
   size?: ChipSize;
+  /** When set to `"toolbar"`, opts the chip into compact toolbar sizing to align with sibling toolbar controls. */
   density?: ChipDensity;
   leadingIcon?: Snippet;
+  /** Additional class names merged onto the chip element. */
   class?: string;
   // Cross-variant sentinel props: present as `never` so the union is destructurable in chip.svelte,
   // and consumers get a compile-time error if they pass toggle/removable-only props to display mode.
@@ -35,30 +41,46 @@ export type ChipToggleProps = Omit<
   HTMLButtonAttributes,
   'class' | 'disabled' | 'aria-pressed' | 'type'
 > & {
+  /** Rendering and interaction mode. Must be `"toggle"` for this variant. */
   mode: 'toggle';
+  /** Visible text content of the chip. */
   label: string;
+  /** Color variant applied to the chip. Default `"neutral"`. */
   variant?: ChipVariant;
+  /** Size of the chip. Default `"md"`. */
   size?: ChipSize;
+  /** When set to `"toolbar"`, opts the chip into compact toolbar sizing to align with sibling toolbar controls. */
   density?: ChipDensity;
   leadingIcon?: Snippet;
+  /** Additional class names merged onto the chip element. */
   class?: string;
+  /** Toggle mode only. Whether the chip is currently in the pressed (selected) state. Reflected as `aria-pressed`. */
   pressed: boolean;
   onpressedchange?: (pressed: boolean) => void;
+  /** Toggle mode only. When true, disables the toggle button and prevents interaction. */
   disabled?: boolean;
   // Cross-variant sentinel props
   onremove?: never;
   removeAriaLabel?: never;
 };
 export type ChipRemovableProps = Omit<HTMLAttributes<HTMLSpanElement>, 'class'> & {
+  /** Rendering and interaction mode. Must be `"removable"` for this variant. */
   mode: 'removable';
+  /** Visible text content of the chip and fallback accessible name for the remove button. */
   label: string;
+  /** Color variant applied to the chip. Default `"neutral"`. */
   variant?: ChipVariant;
+  /** Size of the chip. Default `"md"`. */
   size?: ChipSize;
+  /** When set to `"toolbar"`, opts the chip into compact toolbar sizing to align with sibling toolbar controls. */
   density?: ChipDensity;
   leadingIcon?: Snippet;
+  /** Additional class names merged onto the chip element. */
   class?: string;
   onremove?: () => void;
+  /** Removable mode only. When true, disables the remove button and prevents removal. */
   disabled?: boolean;
+  /** Removable mode only. Accessible label for the remove button. Defaults to `Remove` followed by the chip's `label`. */
   removeAriaLabel?: string;
   // Cross-variant sentinel props
   pressed?: never;

package/src/components/choice-grid/README.md

@@ -44,8 +44,8 @@ Responsive grid of large selectable choices with roving keyboard focus, selectio
 | `multiple`       | `boolean`                                  | no       | —       | When true the grid allows multiple simultaneous selections and reads/writes `values` instead of `value`. The ARIA role switches to `group` (items become `checkbox`); single-select uses `radiogroup` (items become `radio`). |
 | `value`          | `string` \| `null`                         | no       | —       | The currently selected value (single-select mode). Bindable. Pass `null` or omit to start with no selection.                                                                                                                  |
 | `values`         | `string`[]                                 | no       | —       | Currently selected values (multi-select mode). Bindable. Only used when `multiple` is `true` — set `multiple` explicitly to switch modes; binding `values` alone does NOT enable multi-select.                                |
-| `children`       | `(opaque)`                                 | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                    |
-| `class`          | `(opaque)`                                 | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                       |
+| `children`       | `(opaque)`                                 | yes      | —       | `ChoiceGridItem` children. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                         |
+| `class`          | `(opaque)`                                 | no       | —       | Additional class names merged with `.cinder-choice-grid`. Not expressible in JSON Schema; see the component types for the signature.                                                                                          |
 
 <!-- generated:props:end -->
 

package/src/components/choice-grid-item/README.md

@@ -20,7 +20,7 @@ composed snippet. The flat `@lostgradient/cinder/choice-grid-item` subpath remai
 | `disabled` | `boolean`                                                  | no       | —       | When true this item cannot be selected or focused.                                                                                                 |
 | `state`    | `"neutral"` \| `"correct"` \| `"incorrect"` \| `"pending"` | no       | —       | Feedback state for assessment / quiz usage. Defaults to `'neutral'`. Layout dimensions do NOT change across states (stable cell sizing guarantee). |
 | `value`    | `string`                                                   | yes      | —       | The value this item represents. Used as the key for selection state, roving tabindex registration, and ARIA attributes.                            |
-| `children` | `(opaque)`                                                 | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                         |
+| `children` | `(opaque)`                                                 | yes      | —       | Item content — label text, an icon, or richer markup. Not expressible in JSON Schema; see the component types for the signature.                   |
 
 <!-- generated:props:end -->
 

package/src/components/click-away-listener/README.md

@@ -24,12 +24,12 @@ Headless utility that calls a function when the user clicks or taps outside a su
 
 <!-- generated:props:start -->
 
-| Prop          | Type       | Required | Default | Description                                                                                                                |
-| ------------- | ---------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `class`       | `string`   | no       | —       | Additional class names merged with the root element.                                                                       |
-| `enabled`     | `boolean`  | no       | —       | When false the document listener is detached and `onClickAway` is never called. Defaults to `true`.                        |
-| `children`    | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `onClickAway` | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
+| Prop          | Type       | Required | Default | Description                                                                                                                                                                                                                                                           |
+| ------------- | ---------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `class`       | `string`   | no       | —       | Additional class names merged with the root element.                                                                                                                                                                                                                  |
+| `enabled`     | `boolean`  | no       | —       | When false the document listener is detached and `onClickAway` is never called. Defaults to `true`.                                                                                                                                                                   |
+| `children`    | `(opaque)` | yes      | —       | Content rendered inside the root element. Required. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                        |
+| `onClickAway` | `(opaque)` | yes      | —       | Called with the triggering PointerEvent (or MouseEvent/TouchEvent on browsers that do not support the Pointer Events API) when the user presses a pointer device outside the root element. Not expressible in JSON Schema; see the component types for the signature. |
 
 <!-- generated:props:end -->
 

package/src/components/code-block/README.md

@@ -1,6 +1,8 @@
 # CodeBlock
 
-Renders syntax-highlighted source code with optional copy and line display controls.
+Renders preformatted source code with optional client-side syntax highlighting and copy controls.
+The first paint may be the escaped plain-code fallback; when highlighting resolves, the block keeps
+the same layout metrics.
 
 ## Usage
 
@@ -16,14 +18,14 @@ Renders syntax-highlighted source code with optional copy and line display contr
 
 <!-- generated:props:start -->
 
-| Prop          | Type       | Required | Default | Description                                                                                                                                                                                                                                                                                                                       |
-| ------------- | ---------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `class`       | `string`   | no       | —       | Additional class names merged with `.cinder-code-block`.                                                                                                                                                                                                                                                                          |
-| `code`        | `string`   | yes      | —       | The code to render.                                                                                                                                                                                                                                                                                                               |
-| `copyable`    | `boolean`  | no       | —       | When true, render a copy button in the header.                                                                                                                                                                                                                                                                                    |
-| `highlight`   | `boolean`  | no       | —       | Whether to highlight. Defaults to `true` whenever `language` is set. `highlight={false}` is an absolute off switch: it disables ALL highlighting — including an explicit `highlighter` prop — and triggers no Shiki import. The block renders the escaped plain `<pre><code>` fallback while keeping the `language` header label. |
-| `language`    | `string`   | no       | —       | Optional language label rendered in the header; also selects the grammar for highlighting.                                                                                                                                                                                                                                        |
-| `highlighter` | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                        |
+| Prop          | Type       | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| ------------- | ---------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `class`       | `string`   | no       | —       | Additional class names merged with `.cinder-code-block`.                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `code`        | `string`   | yes      | —       | The code to render.                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `copyable`    | `boolean`  | no       | —       | When true, render a copy button in the header.                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `highlight`   | `boolean`  | no       | —       | Whether to highlight. Defaults to `true` whenever `language` is set. `highlight={false}` is an absolute off switch: it disables ALL highlighting — including an explicit `highlighter` prop — and triggers no Shiki import. The block renders the escaped plain `<pre><code>` fallback while keeping the `language` header label. When highlighting is enabled, client-side colorization may appear after first paint, but the block keeps stable layout metrics. |
+| `language`    | `string`   | no       | —       | Optional language label rendered in the header; also selects the grammar for highlighting.                                                                                                                                                                                                                                                                                                                                                                        |
+| `highlighter` | `(opaque)` | no       | —       | Custom highlighter for this instance, used in place of the bundled Shiki default. Receives `(code, language)` and returns an HTML string (sync or async). When provided, the default highlighter is never imported. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                    |
 
 <!-- generated:props:end -->
 

package/src/components/code-block/code-block.css

@@ -3,12 +3,17 @@
   /* ========================================
  * CODE BLOCK
  * Preformatted code with optional language label and copy button.
- * Syntax highlighting is opt-in via the `highlighter` prop. Highlighter
- * output replaces the __pre/__code markup entirely. Shiki pre output is
- * normalized here so highlighted and plain blocks share the same chrome.
+ * Syntax highlighting lazy-loads on the client when a language is set.
+ * Highlighted and plain states share one scroll viewport and identical
+ * inner <pre> metrics so colorization does not move surrounding layout.
  * ======================================== */
 
   .cinder-code-block {
+    --_cinder-code-block-code-surface: light-dark(
+      var(--cinder-surface-raised),
+      var(--cinder-surface-inset)
+    );
+
     background: var(--cinder-surface-inset);
     border: 1px solid var(--cinder-border);
     border-radius: var(--cinder-radius-md);
@@ -34,15 +39,22 @@
     letter-spacing: var(--cinder-tracking-wide);
   }
 
+  /* Stable scroll viewport shared by the first-paint plain fallback and the
+   * client-side highlighted state. It owns keyboard focus and overflow so the
+   * inner pre elements can stay metrically identical. */
+  .cinder-code-block__viewport {
+    display: block;
+    overflow-x: auto;
+    background: var(--_cinder-code-block-code-surface);
+  }
+
   .cinder-code-block__pre,
-/* Highlighter output (e.g. Shiki) replaces __pre with its own markup
- * (typically <pre class="shiki ...">). Match it so the highlighted variant
- * inherits the same padding / font / line-height as the plain variant —
- * this is what Issue 6 was supposed to fix originally. */
-.cinder-code-block > pre {
+  .cinder-code-block :where(pre.shiki) {
     margin: 0;
     padding: var(--cinder-space-4);
-    overflow-x: auto;
+    width: max-content;
+    min-width: 100%;
+    overflow-x: clip;
     font-family: var(--cinder-font-mono);
     font-size: var(--cinder-text-sm);
     line-height: var(--cinder-leading-relaxed);
@@ -50,28 +62,33 @@
     /* Use near-white in light mode so github-light token colors (e.g. #d73a49
      * keyword red) clear 4.5:1 WCAG AA. In dark mode keep the deep inset so
      * github-dark tokens maintain contrast on a very dark surface. */
-    background: light-dark(var(--cinder-surface-raised), var(--cinder-surface-inset));
-  }
-
-  .cinder-code-block__code {
-    font-family: inherit;
-    font-size: inherit;
+    background: var(--_cinder-code-block-code-surface);
   }
 
+  /* Shiki writes inline background styles on its generated <pre>; keep the
+   * highlighted state visually and metrically identical to the plain fallback. */
   .cinder-code-block :where(pre.shiki) {
     margin: 0 !important;
-    padding: var(--cinder-space-3) var(--cinder-space-4) !important;
-    font-family: var(--cinder-font-mono);
-    font-size: var(--cinder-text-sm);
-    line-height: var(--cinder-leading-relaxed);
-    /* Same light/dark split as the plain __pre — near-white in light for
-     * github-light contrast, deep inset in dark for github-dark contrast. */
-    background: light-dark(var(--cinder-surface-raised), var(--cinder-surface-inset)) !important;
+    padding: var(--cinder-space-4) !important;
+    background: var(--_cinder-code-block-code-surface) !important;
   }
 
+  .cinder-code-block__code,
   .cinder-code-block :where(pre.shiki code) {
     font-family: inherit;
     font-size: inherit;
+    line-height: inherit;
+    /* Shiki paints a surface on the generated <code> (and can on line spans)
+     * that differs from the <pre> we force to the inset surface, so in dark mode
+     * each highlighted region reads as its own lighter band over the panel.
+     * Keep the code element and any line wrapper transparent so the single
+     * <pre> surface shows through as one uniform field. (Token foreground colors
+     * are handled separately by the dual-theme `color` swap below.) */
+    background: transparent !important;
+  }
+
+  .cinder-code-block :where(pre.shiki code .line, pre.shiki code span) {
+    background: transparent !important;
   }
 
   /* ── Dark-theme Shiki dual-theme fix ─────────────────────────────────────
@@ -122,17 +139,34 @@
     }
   }
 
-  /* Compact, borderless copy button when nested inside a code block header.
+  /* Compact copy button when nested inside a code block header. It reads as a
+ * real button — a square hit target with a subtle resting chip background — not
+ * a bare floating glyph crammed against the panel edge. The chip is a faint
+ * raised surface so the button is discoverable at rest without competing with
+ * the code content; hover deepens it (rule below).
+ *
+ * Hit target: 1.75rem (28px) square clears the WCAG 2.5.8 AA 24px floor with
+ * margin. The icon stays centered via inline-flex.
+ *
  * Specificity bump (`.cinder-code-block .cinder-code-block__header .cinder-copy-button`)
  * is required because copy-button.css imports AFTER code-block.css in components.css;
  * with equal specificity the later import would win and the bordered default would
  * leak through. Scoped so the standalone CopyButton keeps its bordered default
  * everywhere else in the app. */
   .cinder-code-block .cinder-code-block__header .cinder-copy-button {
-    border: none;
-    background: transparent;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    inline-size: 1.75rem;
+    min-block-size: 1.75rem;
+    border: 1px solid transparent;
+    border-radius: var(--cinder-radius-sm);
+    background: var(--cinder-surface-raised);
     padding: var(--cinder-space-1);
-    color: var(--cinder-text-subtle);
+    color: var(--cinder-text-muted);
+    transition:
+      background-color var(--cinder-duration-fast) var(--cinder-ease-standard),
+      color var(--cinder-duration-fast) var(--cinder-ease-standard);
   }
 
   .cinder-code-block .cinder-code-block__header .cinder-copy-button:focus-visible {
@@ -158,30 +192,26 @@
 
   /* Stable wrapper that anchors {@html highlighted} for Svelte 5 reconciliation —
    Svelte appends new nodes alongside the old when an `{@html}` value changes
-   between two non-null strings unless it sits inside a stable parent element.
-   This div is also the keyboard-accessible scroll container for the highlighted
-   code (tabindex="0" is set in the template). The inner shiki <pre> must NOT
-   independently scroll — overflow is owned here so keyboard users reach the
-   scroll region via a single focusable element. */
+   between two non-null strings unless it sits inside a stable parent element. */
   .cinder-code-block__highlighted {
     display: block;
-    overflow-x: auto;
   }
 
-  /* The shiki <pre> must NOT own a scroll port — the parent
-   .cinder-code-block__highlighted is the single keyboard-reachable scroll
-   region (axe scrollable-region-focusable wants one, not a nested pair). But it
-   MUST still contribute its full content width to the parent's scrollable
-   overflow, or long lines get clipped and become unreachable. So: let the pre
-   grow to its intrinsic width (`width: max-content`, floored at `min-width:
-   100%` so short code still fills the box) and clip its own (now non-existent)
-   overflow. Because the element is sized to its content, `clip` is a no-op on
-   the pre itself, while the wider-than-viewport pre makes the PARENT scroll.
-   (Plain `overflow-x: clip` alone clipped the overflow out of existence so the
-   parent never became scrollable — verified in-browser.) */
-  .cinder-code-block__highlighted :where(pre.shiki) {
-    width: max-content;
-    min-width: 100%;
-    overflow-x: clip;
+  /* .cinder-code-block has `overflow: hidden`, so an OUTSET ring from the
+   * foundation.css :focus-visible fallback is clipped to the top edge only.
+   * Use Strategy B-inset: single-band inset box-shadow contained within the
+   * element's own border box so the parent overflow can never clip it.
+   * tabindex="0" is set in code-block.svelte on the stable viewport. */
+  .cinder-code-block__viewport:focus-visible {
+    outline: var(--cinder-ring-width) solid transparent;
+    box-shadow: inset 0 0 0 var(--cinder-ring-width) var(--cinder-ring-color);
+  }
+
+  @media (forced-colors: active) {
+    .cinder-code-block__viewport:focus-visible {
+      outline: var(--cinder-ring-width) solid ButtonText;
+      outline-offset: calc(var(--cinder-ring-width) * -1);
+      box-shadow: none;
+    }
   }
 }

package/src/components/code-block/code-block.examples.json

@@ -9,6 +9,12 @@
       "description": "Multi-line preformatted code.",
       "code": "<script lang=\"ts\">\n  import { CodeBlock } from '@lostgradient/cinder/code-block';\n  const code = `function greet(name: string): string {\n  return \\`Hello, \\${name}!\\`;\n}\n\nconst message = greet('world');`;\n</script>\n\n<CodeBlock {code} />\n"
     },
+    {
+      "id": "delayed-highlighting",
+      "title": "Delayed highlighting",
+      "description": "Colorization can resolve after first paint while the code block keeps its dimensions.",
+      "code": "<script lang=\"ts\">\n  import { CodeBlock } from '@lostgradient/cinder';\n\n  const code = `SELECT id, name, created_at, email_address, account_status, last_seen_at, billing_plan, feature_flags\nFROM users\nWHERE active = true\nORDER BY created_at DESC\nLIMIT 10;`;\n\n  const highlightedHtml = `<pre class=\"shiki\" style=\"background-color:#fff;color:#24292e\"><code>${escapeHtml(\n    code,\n  )}</code></pre>`;\n\n  type LayoutHighlighterWindow = Window & {\n    cinderCodeBlockLayoutHighlighterReady?: boolean;\n    resolveCinderCodeBlockLayoutHighlight?: () => void;\n  };\n\n  if (typeof window !== 'undefined') {\n    (window as LayoutHighlighterWindow).cinderCodeBlockLayoutHighlighterReady = false;\n  }\n\n  function escapeHtml(value: string): string {\n    return value\n      .replaceAll('&', '&amp;')\n      .replaceAll('<', '&lt;')\n      .replaceAll('>', '&gt;')\n      .replaceAll('\"', '&quot;')\n      .replaceAll(\"'\", '&#39;');\n  }\n\n  function highlighter(): Promise<string> {\n    return new Promise((resolve) => {\n      if (typeof window === 'undefined') return;\n      const target = window as LayoutHighlighterWindow;\n      target.resolveCinderCodeBlockLayoutHighlight = () => resolve(highlightedHtml);\n      target.cinderCodeBlockLayoutHighlighterReady = true;\n    });\n  }\n</script>\n\n<CodeBlock {code} language=\"sql\" {highlighter} />\n"
+    },
     {
       "id": "with-language",
       "title": "With language label and copy",

package/src/components/code-block/code-block.svelte

@@ -36,9 +36,10 @@
   // Two-phase render contract: the server (and the first client paint) emits
   // the plain `<pre><code>` fallback because `$effect` never runs during SSR.
   // The effect below — client-only by definition — enhances the block to the
-  // highlighted HTML once the highlighter resolves. Keeping the Shiki boundary
-  // a dynamic import inside this effect is what keeps Shiki out of the SSR
-  // bundle and the consumer's entry chunk.
+  // highlighted HTML once the highlighter resolves. The outer viewport stays
+  // mounted across both phases so syntax colorization cannot move surrounding
+  // layout. Keeping the Shiki boundary a dynamic import inside this effect is
+  // what keeps Shiki out of the SSR bundle and the consumer's entry chunk.
   $effect(() => {
     // `highlight={false}` is an absolute off switch: it disables ALL
     // highlighting — including an explicit `highlighter` prop — and triggers
@@ -109,38 +110,32 @@
       {/if}
     </header>
   {/if}
-  <!-- The svelte:boundary catches errors thrown during render of {@html highlighted}
-       (e.g. a malformed HTML string that breaks Svelte's reconciliation). Sync/async
-       errors from the highlighter ITSELF are caught above; this is the secondary net. -->
-  <!-- `{@html}` reconciliation across string→string transitions strands the
-       previous DOM nodes when they're emitted as direct children of an
-       `{#if}` branch (Svelte 5: the prior nodes share the same parent and
-       no anchor scopes them). Wrap the `{@html}` output in a stable
-       container `<div>` so the previous render is contained inside an
-       element Svelte can replace in place. -->
-  <svelte:boundary>
-    {#if highlighted !== null}
-      <!-- tabindex="0" makes this scroll container keyboard-reachable so
-           keyboard-only users can scroll long highlighted code snippets
-           (WCAG 2.1 SC 2.1.1; axe scrollable-region-focusable). The div
-           owns overflow-x: auto in CSS; the inner shiki <pre> is clipped
-           so there is exactly one focusable scroll region. No role="region":
-           a landmark per code block would flood landmark navigation with
-           identically-named "Code" regions on docs pages with many snippets —
-           tabindex alone satisfies the keyboard-scroll requirement. -->
-      <div class="cinder-code-block__highlighted" tabindex="0">
-        {@html highlighted}
-      </div>
-    {:else}
-      <!-- tabindex="0" makes the plain-code scroll container keyboard-reachable. -->
-      <pre class="cinder-code-block__pre" tabindex="0"><code class="cinder-code-block__code"
-          >{code}</code
-        ></pre>
-    {/if}
-    {#snippet failed()}
-      <pre class="cinder-code-block__pre" tabindex="0"><code class="cinder-code-block__code"
-          >{code}</code
-        ></pre>
-    {/snippet}
-  </svelte:boundary>
+  <!-- One stable, focusable scroll viewport is shared by plain, highlighted,
+       and fallback states. Keep tabindex unconditional so overflowing snippets
+       are keyboard-scrollable before measurement. -->
+  <div class="cinder-code-block__viewport" tabindex="0">
+    <!-- The svelte:boundary catches errors thrown during render of {@html highlighted}
+         (e.g. a malformed HTML string that breaks Svelte's reconciliation). Sync/async
+         errors from the highlighter ITSELF are caught above; this is the secondary net. -->
+    <!-- `{@html}` reconciliation across string→string transitions strands the
+         previous DOM nodes when they're emitted as direct children of an
+         `{#if}` branch (Svelte 5: the prior nodes share the same parent and
+         no anchor scopes them). Wrap the `{@html}` output in a stable
+         container `<div>` so the previous render is contained inside an
+         element Svelte can replace in place. -->
+    <svelte:boundary>
+      {#if highlighted !== null}
+        <div class="cinder-code-block__highlighted">
+          {@html highlighted}
+        </div>
+      {:else}
+        <pre class="cinder-code-block__pre"><code class="cinder-code-block__code">{code}</code
+          ></pre>
+      {/if}
+      {#snippet failed()}
+        <pre class="cinder-code-block__pre"><code class="cinder-code-block__code">{code}</code
+          ></pre>
+      {/snippet}
+    </svelte:boundary>
+  </div>
 </div>

package/src/components/code-block/code-block.types.ts

@@ -9,11 +9,12 @@ import type { Highlighter } from '../../utilities/highlighter.ts';
  * Syntax highlighting is automatic: when `language` is set, CodeBlock
  * lazy-loads the bundled `@lostgradient/cinder/highlighters/shiki` adapter on the client and
  * enhances the block once it resolves. The server (and the first client paint)
- * always emits the plain `<pre><code>` fallback — highlighting is a two-phase,
- * client-only enhancement, so there is a brief flash before the highlighted
- * HTML swaps in. Pass `highlight={false}` to keep `language` semantics (the
- * header label) with zero highlighting and zero Shiki import. Pass a custom
- * `highlighter` to override the bundled default per instance.
+ * always emits the plain `<pre><code>` fallback. Highlighting is a two-phase,
+ * client-only enhancement: colorization may appear after first paint, but the
+ * stable viewport keeps the block's layout from moving. Pass
+ * `highlight={false}` to keep `language` semantics (the header label) with
+ * zero highlighting and zero Shiki import. Pass a custom `highlighter` to
+ * override the bundled default per instance.
  */
 export type CodeBlockProps = {
   /** The code to render. */
@@ -26,7 +27,9 @@ export type CodeBlockProps = {
    * `highlight={false}` is an absolute off switch: it disables ALL
    * highlighting — including an explicit `highlighter` prop — and triggers no
    * Shiki import. The block renders the escaped plain `<pre><code>` fallback
-   * while keeping the `language` header label.
+   * while keeping the `language` header label. When highlighting is enabled,
+   * client-side colorization may appear after first paint, but the block keeps
+   * stable layout metrics.
    */
   highlight?: boolean;
   /**

package/src/components/collapsible/README.md

@@ -49,13 +49,15 @@ For multiple coordinated sections where opening one may close others, use [`Acco
 
 <!-- generated:props:start -->
 
-| Prop       | Type      | Required | Default | Description                                                                         |
-| ---------- | --------- | -------- | ------- | ----------------------------------------------------------------------------------- |
-| `class`    | `string`  | no       | —       | Additional classes merged onto the root element.                                    |
-| `disabled` | `boolean` | no       | `false` | When true, the trigger cannot be toggled.                                           |
-| `idBase`   | `string`  | no       | —       | Base used to derive the trigger and panel ARIA ids. Auto-generated when omitted.    |
-| `open`     | `boolean` | no       | `false` | Bindable open state. Without binding, the initial value the component then manages. |
-| `trigger`  | `string`  | yes      | —       | Trigger label text. (The snippet form is template-only; see the type above.)        |
+| Prop       | Type       | Required | Default | Description                                                                                                                                                      |
+| ---------- | ---------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `class`    | `string`   | no       | —       | Additional classes merged onto the root element.                                                                                                                 |
+| `disabled` | `boolean`  | no       | `false` | When true, the trigger cannot be toggled.                                                                                                                        |
+| `idBase`   | `string`   | no       | —       | Base used to derive the trigger and panel ARIA ids. Auto-generated when omitted.                                                                                 |
+| `open`     | `boolean`  | no       | `false` | Bindable open state. Without binding, the initial value the component then manages.                                                                              |
+| `trigger`  | `string`   | yes      | —       | Trigger label text. (The snippet form is template-only; see the type above.)                                                                                     |
+| `children` | `(opaque)` | yes      | —       | Panel content shown when open. Not expressible in JSON Schema; see the component types for the signature.                                                        |
+| `onToggle` | `(opaque)` | no       | —       | Fired on every successful toggle with the next open state. Not called while disabled. Not expressible in JSON Schema; see the component types for the signature. |
 
 <!-- generated:props:end -->
 

package/src/components/color-field/README.md

@@ -77,7 +77,7 @@ Moving the component across forms at runtime is not supported in v1.
 | `readonly`       | `boolean`                                 | no       | —       | Render the inner `<input>` as read-only.                                                                                                                                                                                                                                                                                                    |
 | `required`       | `boolean`                                 | no       | —       | Mark the input as required for form submission and a11y.                                                                                                                                                                                                                                                                                    |
 | `value`          | `string`                                  | no       | —       | Controlled value as a hex string. One-way: parent sets, child reads. Not bindable — use `onchange` to observe commits. Accepts any color string the configured `formats` allow when set externally.                                                                                                                                         |
-| `onchange`       | `(opaque)`                                | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                                                                                                                                  |
+| `onchange`       | `(opaque)`                                | no       | —       | Fires on successful blur-time commit when the canonical hex actually changes. Value callback by repo convention — not forwarded to the inner native `<input>`. Not expressible in JSON Schema; see the component types for the signature.                                                                                                   |
 
 <!-- generated:props:end -->
 

package/src/components/color-field/color-field.examples.json

@@ -7,7 +7,7 @@
       "id": "basic",
       "title": "Basic color field",
       "description": "An uncontrolled color field that accepts hex, rgb(), and hsl() strings and normalizes them to hex on commit.",
-      "code": "<script lang=\"ts\">\n  import { ColorField } from '@lostgradient/cinder/color-field';\n\n  let committed = $state('');\n</script>\n\n<div style=\"display: flex; flex-direction: column; gap: 0.5rem; max-width: 20rem;\">\n  <label for=\"color-field-basic\" style=\"font-size: 0.875rem; font-weight: 500;\">\n    Brand color\n  </label>\n  <ColorField\n    id=\"color-field-basic\"\n    defaultValue=\"#3b82f6\"\n    onchange={(value) => {\n      committed = value;\n    }}\n  />\n  {#if committed}\n    <p style=\"font-size: 0.75rem; color: var(--cinder-text-muted);\">Committed: {committed}</p>\n  {/if}\n</div>\n"
+      "code": "<script lang=\"ts\">\n  import { ColorField } from '@lostgradient/cinder/color-field';\n\n  let committed = $state('');\n</script>\n\n<div style=\"display: flex; flex-direction: column; gap: 0.5rem; max-width: 20rem;\">\n  <label for=\"field\" style=\"font-size: 0.875rem; font-weight: 500;\"> Brand color </label>\n  <ColorField\n    id=\"field\"\n    defaultValue=\"#3b82f6\"\n    onchange={(value) => {\n      committed = value;\n    }}\n  />\n  {#if committed}\n    <p style=\"font-size: 0.75rem; color: var(--cinder-text-muted);\">Committed: {committed}</p>\n  {/if}\n</div>\n"
     },
     {
       "id": "states",

package/src/components/color-picker/README.md

@@ -26,8 +26,8 @@ Full-featured input for selecting a color via hue, saturation, lightness, and he
 | `name`         | `string`   | no       | —       | Form field name. When set, a hidden input mirrors the current value for form submission.                                                                                                                                   |
 | `swatches`     | `string`[] | no       | —       | Optional palette of preset colors rendered below the picker.                                                                                                                                                               |
 | `value`        | `string`   | no       | —       | Bindable value. Reading the value yields a hex string (`#rrggbb`, or `#rrggbbaa` when `alpha` is true). Setting the value accepts hex, `rgb()`, `rgba()`, `hsl()`, or `hsla()` input; invalid input is normalized to `''`. |
-| `onchange`     | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                 |
-| `oninput`      | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                                                                                                 |
+| `onchange`     | `(opaque)` | no       | —       | Fired on commit (pointer up, swatch click, slider key). Not expressible in JSON Schema; see the component types for the signature.                                                                                         |
+| `oninput`      | `(opaque)` | no       | —       | Fired on every intermediate update (drag, slider key, swatch click). Not expressible in JSON Schema; see the component types for the signature.                                                                            |
 
 <!-- generated:props:end -->