@kerfjs/ui 5.0.0-beta.110 → 5.0.0-beta.112

package/README.md

@@ -273,6 +273,8 @@ interchangeable. `ListItem` and `ListActionRow` deliberately expose no raw
 | `LoadingSpinner`                                             | `@kerfjs/ui/loading-spinner`            | `@kerfjs/ui/loading-spinner.css`         |
 | `Skeleton`                                                   | `@kerfjs/ui/skeleton`                   | `@kerfjs/ui/skeleton.css`                |
 | `SunkenPanel`                                                | `@kerfjs/ui/sunken-panel`               | `@kerfjs/ui/sunken-panel.css`            |
+| `ValuePreview`                                               | `@kerfjs/ui/value-preview`              | `@kerfjs/ui/value-preview.css`           |
+| `EditorFrame`                                                | `@kerfjs/ui/editor-frame`               | `@kerfjs/ui/editor-frame.css`            |
 | `BackdropImage`                                              | `@kerfjs/ui/backdrop-image`             | `@kerfjs/ui/backdrop-image.css`          |
 | `Select`                                                     | `@kerfjs/ui/select`                     | `@kerfjs/ui/select.css`                  |
 | `SegmentedControl`                                           | `@kerfjs/ui/segmented-control`          | `@kerfjs/ui/segmented-control.css`       |
@@ -908,6 +910,7 @@ The detailed rationale lives in the theme contract.
 - [Apple HIG translation](./docs/apple-hig.md)
 - [Writing interface copy](./docs/writing.md)
 - [Accessibility and keyboard contracts](./docs/accessibility.md)
+- [Button current-step semantics](./docs/button.md)
 - [Component and integration contract](./docs/component-contract.md)
 - [Spacing and application layout](./docs/layout.md)
 - [Web Awesome theme contract](./docs/webawesome-theme.md)

package/ai/component-catalog.json

@@ -1726,7 +1726,8 @@
         "progressive blur from a once-filtered copy or an app-supplied blurred asset, with an optional dim",
         "fade into a color that also paints below",
         "bottom or full scrim under overlay content",
-        "image running beneath clear or overlay chrome (underChrome)"
+        "image running beneath clear or overlay chrome (underChrome)",
+        "opt-in deferOffscreen hero paint deferral for dense image feeds without changing reserved height"
       ],
       "accessibility": [
         "alt describes a meaningful image; pass an empty alt for a decorative one. A tiled image with alt text is exposed as role=\"img\". Parallax and the progressive blur run only with prefers-reduced-motion: no-preference and scroll-driven animation support, and are off under data-kui-effects=\"static\" and on slow-update displays, leaving a static, sharp image; the blurred copy is decorative and aria-hidden. Reduced transparency or increased contrast replaces the fade with a hard edge on solid fadeTo and puts overlay content on a solid fadeTo band. Overlay text needs a scrim or fade color that keeps it at AA."
@@ -2151,6 +2152,7 @@
         "A modal task needs a dialog: render a DialogSurface with a label (or labelledBy plus a heading), its body as children, and its buttons as footer, then open it with openDialog() and close it with closeDialog(), the close button, or any element with data-dialog-close. A raw Web Awesome dropdown that needs a list-compatible menu inset uses PopupSurface.",
         "A dialog body should compose rows, sections, or aligned bare prose through List and ListInsetText.",
         "A modal needs a typed preferred width, viewport gutter, or dynamic viewport-bounded height cap while retaining native body scrolling and footer actions.",
+        "A dialog needs a less prominent built-in close control: closeEmphasis=\"quiet\" softens the glyph while keeping the native button target and close behavior.",
         "A dialog that must leave the page interactive and close on Escape or an outside press uses PopoverDialogSurface; one that fills its body with a SplitView or Pane uses height and bodyLayout=\"fill\".",
         "A chat-style dialog floats its composer over the transcript with footerPresentation=\"floating\" and keeps a heading or notice above one scrolling transcript with bodyLayout=\"fill-last\".",
         "A phone-first task (compose, quick edit, a picker) should rise from the bottom edge as a sheet the person can resize: presentation=\"bottom-sheet\" with height, and resizable with minHeight / maxHeight bounds.",
@@ -2190,12 +2192,14 @@
         "core kerfjs/overlay confirm/prompt/form/choice as a bottom sheet styled by @kerfjs/ui/overlay-sheet.css",
         "resizable core kerfjs/overlay bottom sheet: the kui-overlay-sheet-resizable class plus wireOverlaySheets adds the resizable DialogSurface sheet grabber",
         "header with label text or heading content, headerActions, a close button, and an optional footer; withoutHeader for content that owns its heading and close control",
+        "normal (default) or quiet closeEmphasis on the built-in close button",
         "accessible description by describedBy: the heading ToolbarText descriptionId or app-owned body summary copy",
         "light dismiss (a backdrop press closes; otherwise the panel pulses)"
       ],
       "accessibility": [
         "DialogSurface is a native <dialog> opened modally (showModal): it is in the top layer, the rest of the page is inert, focus stays inside, and it returns to the opener on close. Focus starts on an autofocus element, otherwise on the panel.",
         "Name it with label (also its title text) or labelledBy (the id of a heading, such as a ToolbarText). The close button is named Close (closeLabel) and Escape asks to close; the cancelable kui-request-close event reports source close-button, escape, or backdrop.",
+        "closeEmphasis=\"quiet\" uses a smaller, quiet-colored close glyph inside the same 40px target; hover, focus ring, forced colors, accessible naming, and close requests remain available.",
         "Name a PopoverDialogSurface with label or labelledBy. Describe either surface with describedBy (rendered as aria-describedby on the dialog root), usually the heading ToolbarText descriptionId or app-owned summary copy in the body; rootAttributes accepts only data-* attributes, so it never sets aria-describedby.",
         "A floating header's title uses the normal text color, which keeps WCAG AA over the 80% raised chrome material on any content; the material turns opaque under prefers-reduced-transparency, prefers-contrast: more, forced colors, or without backdrop-filter.",
         "A resizable bottom sheet's grabber is a focusable horizontal separator (\"Resize sheet\") with aria-valuemin, aria-valuenow, and aria-valuemax in visible px; the arrow keys, Page Up/Down, Home, and End resize it, and its slide motion is skipped under prefers-reduced-motion.",
@@ -3046,6 +3050,147 @@
         "recipe": "docs/component-selection.md#ambiguous-choices"
       }
     },
+    {
+      "id": "editor-frame",
+      "name": "EditorFrame",
+      "category": "Structure",
+      "kind": "component",
+      "source": "kerf",
+      "description": "A bounded editor surface with a fixed toolbar and one native source or preview scroll owner.",
+      "uses": [
+        "toolbar"
+      ],
+      "purpose": "Own a framed or embedded writing surface while the app owns its native textarea, draft, and rendered preview.",
+      "publicExports": [
+        "EditorFrame"
+      ],
+      "useWhen": [
+        "A standalone Markdown or text editor needs a fixed toolbar above a bounded native textarea or preview.",
+        "An embedded editor needs the same source/preview anatomy without a second frame."
+      ],
+      "avoidWhen": [
+        "Do not use for an ordinary single form field; use TextField.",
+        "Do not replace the app's draft, recovery, focus, or preview behavior."
+      ],
+      "alternatives": [
+        {
+          "id": "text-field",
+          "relationship": "nearest",
+          "when": "Use TextField for a conventional form value without editor toolbar and preview."
+        }
+      ],
+      "appOwns": [
+        "draft value",
+        "editing actions",
+        "preview rendering",
+        "recovery and focus management"
+      ],
+      "variants": [
+        "source and preview modes",
+        "framed and embedded appearances",
+        "padded and flush insets",
+        "expanded overlay",
+        "embedded autosize or restored source height"
+      ],
+      "accessibility": [
+        "Give the editor frame a label when it is a distinct region; the app labels its native textarea and supplies toolbar controls."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
+      },
+      "delivery": {
+        "browserImport": "@kerfjs/ui/editor-frame",
+        "manualCssImport": "@kerfjs/ui/editor-frame.css",
+        "sideEffects": [
+          "browser-condition-css"
+        ]
+      },
+      "wiring": [],
+      "publicClasses": [
+        "kui-editor-frame",
+        "kui-editor-frame__toolbar",
+        "kui-editor-frame__surface"
+      ],
+      "publicTokens": [
+        "--kui-color-neutral-border-normal",
+        "--kui-color-neutral-on-normal",
+        "--kui-color-surface",
+        "--kui-radius-l",
+        "--kui-shadow-l"
+      ],
+      "links": {
+        "catalogRoute": "?component=editor-frame",
+        "documentation": "docs/editor-frame.md",
+        "recipe": "docs/editor-frame.md"
+      }
+    },
+    {
+      "id": "value-preview",
+      "name": "ValuePreview",
+      "category": "Structure",
+      "kind": "component",
+      "source": "kerf",
+      "description": "A bounded, read-only multiline text value with keyboard scrolling.",
+      "uses": [
+        "sunken-panel"
+      ],
+      "purpose": "Display a literal long value with line breaks and long tokens inside a bounded scroll region.",
+      "publicExports": [
+        "ValuePreview"
+      ],
+      "useWhen": [
+        "A read-only value may have multiple lines or long unbroken text and needs bounded scrolling, such as a conflict version."
+      ],
+      "avoidWhen": [
+        "Do not use for editing; use a multiline TextField.",
+        "Do not use for short label/value facts; use ValueTable."
+      ],
+      "alternatives": [
+        {
+          "id": "value-table",
+          "relationship": "nearest",
+          "when": "Use ValueTable for rows of short labelled facts."
+        }
+      ],
+      "appOwns": [
+        "value",
+        "empty wording"
+      ],
+      "variants": [
+        "typed minimum and maximum height"
+      ],
+      "accessibility": [
+        "Give the focusable output a label so keyboard and screen-reader users can identify and scroll it."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "none",
+        "padding": "none"
+      },
+      "delivery": {
+        "browserImport": "@kerfjs/ui/value-preview",
+        "manualCssImport": "@kerfjs/ui/value-preview.css",
+        "sideEffects": [
+          "browser-condition-css"
+        ]
+      },
+      "wiring": [],
+      "publicClasses": [
+        "kui-value-preview"
+      ],
+      "publicTokens": [
+        "--kui-color-text",
+        "--kui-font-xs",
+        "--kui-focus-ring"
+      ],
+      "links": {
+        "catalogRoute": "?component=value-preview",
+        "documentation": "docs/value-preview.md",
+        "recipe": "docs/value-preview.md"
+      }
+    },
     {
       "id": "value-table",
       "name": "ValueTable",
@@ -3221,14 +3366,15 @@
       "category": "Structure",
       "kind": "component",
       "source": "kerf",
-      "description": "A selectable, focusable summary of one item as a list row or a board card, with a state rail, a clamped title, trailing meta, and a metadata line.",
+      "description": "A selectable option or static diagnostic group as a list row or board card, with a state rail, a clamped title, trailing meta, and a metadata line.",
       "uses": [],
       "purpose": "Present dense item summaries (tickets, tasks, messages) as selectable list rows or board cards with Kerf-owned selection, hover, focus, rail, clamping, list-edge rounding, and narrow compaction, without app row CSS.",
       "publicExports": [
         "SummaryRow"
       ],
       "useWhen": [
-        "A list or board shows many items as dense, selectable summaries with an identifier, a title, a timestamp, and metadata."
+        "A list or board shows many items as dense, selectable summaries with an identifier, a title, a timestamp, and metadata.",
+        "An unreadable item needs the same summary chrome with a nested recovery action but must be a labeled non-option group."
       ],
       "avoidWhen": [
         "Do not use for navigation rows with a single label; use ListItem.",
@@ -3260,10 +3406,12 @@
         "state rail",
         "list edge start, end, or only",
         "title line budget",
-        "deferred rendering"
+        "deferred rendering",
+        "static labeled group with a nested action (semanticRole=group)",
+        "native draggable option root for list rows and board cards"
       ],
       "accessibility": [
-        "Each SummaryRow is role=option with tabindex=0 and aria-selected; place rows in a labeled role=listbox and move focus with the arrow keys in the app. The rail is decorative; carry its meaning in text."
+        "By default SummaryRow is role=option with tabindex=0 and aria-selected; place options in a labeled role=listbox and move focus with the arrow keys in the app. semanticRole=group requires ariaLabel and omits the root Tab stop and aria-selected, so a nested native action owns focus and activation. The rail is decorative; carry its meaning in text."
       ],
       "geometry": {
         "margin": "none",
@@ -4964,7 +5112,8 @@
         "chat bubble at the start or end of the row (bubble), fit to its content up to 80%",
         "named focus-target region",
         "multi-select rich grid row",
-        "gridRow: a non-selectable row (role=\"row\" with a gridcell) between selectable rows of a multi-select List or Grid"
+        "gridRow: a non-selectable row (role=\"row\" with a gridcell) between selectable rows of a multi-select List or Grid",
+        "image-led feed media with opt-in deferOffscreen hero paint deferral"
       ],
       "accessibility": [
         "An ordinary item adds no role or name; pass ariaLabel only when the item is a distinct named region (it then renders role=\"region\").",
@@ -7580,6 +7729,7 @@
         "A dialog footer, a form, or content needs an action button: tone=\"brand\" for the main action, tone=\"success\" for a positive action such as a pricing check, tone=\"danger\" for a destructive one, and emphasis=\"secondary\" or \"plain\" for the quieter actions beside it.",
         "A form submits or resets: type=\"submit\" or \"reset\" (the default type never submits), with name, value, and form when needed.",
         "An action navigates: href renders a link with the same chrome.",
+        "A setup or progress sequence uses a Button as its current step: currentStep marks that button or link with aria-current=\"step\" without changing its styling.",
         "A single primary action spans its form, sheet, or narrow column: fill makes it span the parent's available inline width, label centered, as SplitButton's fill does."
       ],
       "avoidWhen": [
@@ -7600,6 +7750,7 @@
       ],
       "appOwns": [
         "the label and its delegated action",
+        "which step is current when currentStep marks a sequence",
         "what a press does while loading",
         "form ownership"
       ],
@@ -7612,6 +7763,7 @@
         "leading icon",
         "icon-only square (icon and ariaLabel, no label)",
         "pressed toggle (aria-pressed) on any tone and emphasis",
+        "currentStep marker (aria-current=\"step\") on a button or link",
         "loading",
         "disabled",
         "link (href)",
@@ -7621,7 +7773,8 @@
       "accessibility": [
         "A native <button> (type=\"button\" unless set) or, with href, an <a>; its label names it, or ariaLabel when the label is not enough. Focus shows the standard focus ring 1px outside the box; with focusRingInset it is drawn inside the box, two-tone with a surface-colored line inside the ring color, so it keeps 3:1 contrast on a loud fill of its own hue.",
         "Loading shows a spinner in place of the label, which still names the button, and sets aria-busy=\"true\". A disabled link drops its href and reports aria-disabled=\"true\". Disabled success uses a quiet success fill and readable on-fill text instead of fading the label.",
-        "With pressed, it is a toggle: aria-pressed reports the state, and the pressed look adds a doubled outline (secondary and plain) or a darkened fill with an inset ring (primary), so the state never relies on hue alone; forced-colors mode paints it Highlight. An icon-only Button is named by ariaLabel, and help tags show that name on hover and keyboard focus. A title gives native hover text that says more than the name and replaces the help tag."
+        "With pressed, it is a toggle: aria-pressed reports the state, and the pressed look adds a doubled outline (secondary and plain) or a darkened fill with an inset ring (primary), so the state never relies on hue alone; forced-colors mode paints it Highlight. An icon-only Button is named by ariaLabel, and help tags show that name on hover and keyboard focus. A title gives native hover text that says more than the name and replaces the help tag.",
+        "With currentStep, a native button or link reports aria-current=\"step\" even when disabled; the app owns the step label and which step is current."
       ],
       "geometry": {
         "margin": "none",
@@ -7671,7 +7824,7 @@
       "rootElement": "button",
       "links": {
         "catalogRoute": "?component=button",
-        "documentation": "docs/component-selection.md",
+        "documentation": "docs/button.md",
         "recipe": "docs/component-selection.md#problem-to-component-matrix"
       }
     },

package/ai/component-composition.json

@@ -2059,6 +2059,7 @@
         "obligations": [
           "DialogSurface is a native <dialog> opened modally (showModal): it is in the top layer, the rest of the page is inert, focus stays inside, and it returns to the opener on close. Focus starts on an autofocus element, otherwise on the panel.",
           "Name it with label (also its title text) or labelledBy (the id of a heading, such as a ToolbarText). The close button is named Close (closeLabel) and Escape asks to close; the cancelable kui-request-close event reports source close-button, escape, or backdrop.",
+          "closeEmphasis=\"quiet\" uses a smaller, quiet-colored close glyph inside the same 40px target; hover, focus ring, forced colors, accessible naming, and close requests remain available.",
           "Name a PopoverDialogSurface with label or labelledBy. Describe either surface with describedBy (rendered as aria-describedby on the dialog root), usually the heading ToolbarText descriptionId or app-owned summary copy in the body; rootAttributes accepts only data-* attributes, so it never sets aria-describedby.",
           "A floating header's title uses the normal text color, which keeps WCAG AA over the 80% raised chrome material on any content; the material turns opaque under prefers-reduced-transparency, prefers-contrast: more, forced colors, or without backdrop-filter.",
           "A resizable bottom sheet's grabber is a focusable horizontal separator (\"Resize sheet\") with aria-valuemin, aria-valuenow, and aria-valuemax in visible px; the arrow keys, Page Up/Down, Home, and End resize it, and its slide motion is skipped under prefers-reduced-motion.",
@@ -2708,6 +2709,116 @@
         "composition": "generated-permissive-default"
       }
     },
+    {
+      "key": "@kerfjs/ui:editor-frame",
+      "package": "@kerfjs/ui",
+      "id": "editor-frame",
+      "name": "EditorFrame",
+      "kind": "component",
+      "source": "kerf",
+      "parents": { "mode": "any", "entries": [] },
+      "contexts": ["application-ui"],
+      "zones": [],
+      "children": { "mode": "any", "concepts": [], "requiredConcepts": [] },
+      "state": [
+        { "id": "draft value", "owner": "application", "required": false },
+        { "id": "editing actions", "owner": "application", "required": false },
+        {
+          "id": "preview rendering",
+          "owner": "application",
+          "required": false
+        },
+        {
+          "id": "recovery and focus management",
+          "owner": "application",
+          "required": false
+        }
+      ],
+      "wiring": {
+        "required": false,
+        "helpers": [],
+        "obligations": [],
+        "stateAttributes": []
+      },
+      "responsive": { "owner": "not-applicable", "behaviors": [] },
+      "layout": {
+        "roles": ["structure"],
+        "geometry": { "margin": "none", "border": "self", "padding": "self" }
+      },
+      "accessibility": {
+        "obligations": [
+          "Give the editor frame a label when it is a distinct region; the app labels its native textarea and supplies toolbar controls."
+        ]
+      },
+      "cssValueProps": [],
+      "boundaries": {
+        "rootClass": "kui-editor-frame",
+        "publicClasses": [
+          "kui-editor-frame",
+          "kui-editor-frame__toolbar",
+          "kui-editor-frame__surface"
+        ],
+        "publicTokens": [
+          "--kui-color-neutral-border-normal",
+          "--kui-color-neutral-on-normal",
+          "--kui-color-surface",
+          "--kui-radius-l",
+          "--kui-shadow-l"
+        ]
+      },
+      "diagnostics": [],
+      "provenance": {
+        "selection": "ai/component-catalog.json",
+        "composition": "generated-permissive-default"
+      }
+    },
+    {
+      "key": "@kerfjs/ui:value-preview",
+      "package": "@kerfjs/ui",
+      "id": "value-preview",
+      "name": "ValuePreview",
+      "kind": "component",
+      "source": "kerf",
+      "parents": { "mode": "any", "entries": [] },
+      "contexts": ["application-ui"],
+      "zones": [],
+      "children": { "mode": "any", "concepts": [], "requiredConcepts": [] },
+      "state": [
+        { "id": "value", "owner": "application", "required": false },
+        { "id": "empty wording", "owner": "application", "required": false }
+      ],
+      "wiring": {
+        "required": false,
+        "helpers": [],
+        "obligations": [],
+        "stateAttributes": []
+      },
+      "responsive": { "owner": "not-applicable", "behaviors": [] },
+      "layout": {
+        "roles": ["structure"],
+        "geometry": { "margin": "none", "border": "none", "padding": "none" }
+      },
+      "accessibility": {
+        "obligations": [
+          "Give the focusable output a label so keyboard and screen-reader users can identify and scroll it."
+        ]
+      },
+      "cssValueProps": [],
+      "boundaries": {
+        "rootClass": "kui-value-preview",
+        "publicClasses": ["kui-value-preview"],
+        "publicTokens": [
+          "--kui-color-text",
+          "--kui-font-xs",
+          "--kui-focus-ring"
+        ]
+      },
+      "diagnostics": [],
+      "provenance": {
+        "selection": "ai/component-catalog.json",
+        "composition": "generated-permissive-default"
+      }
+    },
     {
       "key": "@kerfjs/ui:value-table",
       "package": "@kerfjs/ui",
@@ -2893,7 +3004,7 @@
       },
       "accessibility": {
         "obligations": [
-          "Each SummaryRow is role=option with tabindex=0 and aria-selected; place rows in a labeled role=listbox and move focus with the arrow keys in the app. The rail is decorative; carry its meaning in text."
+          "By default SummaryRow is role=option with tabindex=0 and aria-selected; place options in a labeled role=listbox and move focus with the arrow keys in the app. semanticRole=group requires ariaLabel and omits the root Tab stop and aria-selected, so a nested native action owns focus and activation. The rail is decorative; carry its meaning in text."
         ]
       },
       "cssValueProps": [],
@@ -6073,6 +6184,11 @@
           "owner": "application",
           "required": false
         },
+        {
+          "id": "which step is current when currentStep marks a sequence",
+          "owner": "application",
+          "required": false
+        },
         {
           "id": "what a press does while loading",
           "owner": "application",
@@ -6095,7 +6211,8 @@
         "obligations": [
           "A native <button> (type=\"button\" unless set) or, with href, an <a>; its label names it, or ariaLabel when the label is not enough. Focus shows the standard focus ring 1px outside the box; with focusRingInset it is drawn inside the box, two-tone with a surface-colored line inside the ring color, so it keeps 3:1 contrast on a loud fill of its own hue.",
           "Loading shows a spinner in place of the label, which still names the button, and sets aria-busy=\"true\". A disabled link drops its href and reports aria-disabled=\"true\". Disabled success uses a quiet success fill and readable on-fill text instead of fading the label.",
-          "With pressed, it is a toggle: aria-pressed reports the state, and the pressed look adds a doubled outline (secondary and plain) or a darkened fill with an inset ring (primary), so the state never relies on hue alone; forced-colors mode paints it Highlight. An icon-only Button is named by ariaLabel, and help tags show that name on hover and keyboard focus. A title gives native hover text that says more than the name and replaces the help tag."
+          "With pressed, it is a toggle: aria-pressed reports the state, and the pressed look adds a doubled outline (secondary and plain) or a darkened fill with an inset ring (primary), so the state never relies on hue alone; forced-colors mode paints it Highlight. An icon-only Button is named by ariaLabel, and help tags show that name on hover and keyboard focus. A title gives native hover text that says more than the name and replaces the help tag.",
+          "With currentStep, a native button or link reports aria-current=\"step\" even when disabled; the app owns the step label and which step is current."
         ]
       },
       "cssValueProps": [],

package/ai/components/README.md

@@ -35,6 +35,8 @@ Exact prop and callback types live in [`public-api-signatures-v1.md`](../public-
 - [ToolbarText](./toolbar-text.md) — Extra-large through extra-small toolbar identity text.
 - [Text](./text.md) — Render paragraph semantics by default, h1 through h6 when selected, or geometry-free inline secondary text as a span while independently configuring quiet or danger tone, compact through extra-large size, or monospace font.
 - [Headers](./headers.md) — Page, dialog, and definition-list hierarchy.
+- [EditorFrame](./editor-frame.md) — Own a framed or embedded writing surface while the app owns its native textarea, draft, and rendered preview.
+- [ValuePreview](./value-preview.md) — Display a literal long value with line breaks and long tokens inside a bounded scroll region.
 - [ValueTable](./value-table.md) — Key/value rows with optional icons and aligned separators.
 - [FramedList](./framed-list.md) — Group settings-style rows of arbitrary content (copy, keycaps, controls) in one framed surface with between-row dividers and an optional highlighted row, without app list CSS.
 - [SummaryRow](./summary-row.md) — Present dense item summaries (tickets, tasks, messages) as selectable list rows or board cards with Kerf-owned selection, hover, focus, rail, clamping, list-edge rounding, and narrow compaction, without app row CSS.

package/ai/components/backdrop-image.md

@@ -43,6 +43,7 @@ Exact prop names and types: [`@kerfjs/ui/backdrop-image`](../public-api-signatur
 - fade into a color that also paints below
 - bottom or full scrim under overlay content
 - image running beneath clear or overlay chrome (underChrome)
+- opt-in deferOffscreen hero paint deferral for dense image feeds without changing reserved height
 
 ## Composition
 

package/ai/components/button.md

@@ -13,6 +13,7 @@ Trigger an action from a dialog footer, a form, or content outside any Toolbar,
 - A dialog footer, a form, or content needs an action button: tone="brand" for the main action, tone="success" for a positive action such as a pricing check, tone="danger" for a destructive one, and emphasis="secondary" or "plain" for the quieter actions beside it.
 - A form submits or resets: type="submit" or "reset" (the default type never submits), with name, value, and form when needed.
 - An action navigates: href renders a link with the same chrome.
+- A setup or progress sequence uses a Button as its current step: currentStep marks that button or link with aria-current="step" without changing its styling.
 - A single primary action spans its form, sheet, or narrow column: fill makes it span the parent's available inline width, label centered, as SplitButton's fill does.
 
 **Not when:**
@@ -46,6 +47,7 @@ Exact prop names and types: [`@kerfjs/ui/button`](../public-api-signatures-v1.md
 - leading icon
 - icon-only square (icon and ariaLabel, no label)
 - pressed toggle (aria-pressed) on any tone and emphasis
+- currentStep marker (aria-current="step") on a button or link
 - loading
 - disabled
 - link (href)
@@ -61,7 +63,7 @@ Exact prop names and types: [`@kerfjs/ui/button`](../public-api-signatures-v1.md
 
 ## State and wiring
 
-**The app owns:** the label and its delegated action; what a press does while loading; form ownership.
+**The app owns:** the label and its delegated action; which step is current when currentStep marks a sequence; what a press does while loading; form ownership.
 
 No wiring helper.
 
@@ -74,6 +76,7 @@ Margin: none · border: self · padding: self (layout role: controls). `self` me
 - A native \<button> (type="button" unless set) or, with href, an \<a>; its label names it, or ariaLabel when the label is not enough. Focus shows the standard focus ring 1px outside the box; with focusRingInset it is drawn inside the box, two-tone with a surface-colored line inside the ring color, so it keeps 3:1 contrast on a loud fill of its own hue.
 - Loading shows a spinner in place of the label, which still names the button, and sets aria-busy="true". A disabled link drops its href and reports aria-disabled="true". Disabled success uses a quiet success fill and readable on-fill text instead of fading the label.
 - With pressed, it is a toggle: aria-pressed reports the state, and the pressed look adds a doubled outline (secondary and plain) or a darkened fill with an inset ring (primary), so the state never relies on hue alone; forced-colors mode paints it Highlight. An icon-only Button is named by ariaLabel, and help tags show that name on hover and keyboard focus. A title gives native hover text that says more than the name and replaces the help tag.
+- With currentStep, a native button or link reports aria-current="step" even when disabled; the app owns the step label and which step is current.
 
 ## Styling boundary
 
@@ -90,5 +93,5 @@ Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-
 ## Related
 
 - Components: [LoadingSpinner](./loading-spinner.md), [Button](./wa-button.md), [ToolbarControlGroup](./toolbar-control-group.md).
-- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/component-selection.md#problem-to-component-matrix`](../../docs/component-selection.md#problem-to-component-matrix).
+- Docs: [`docs/button.md`](../../docs/button.md), [`docs/component-selection.md#problem-to-component-matrix`](../../docs/component-selection.md#problem-to-component-matrix).
 - UX catalog route: `?component=button`.

package/ai/components/content-item.md

@@ -53,6 +53,7 @@ Exact prop names and types: [`@kerfjs/ui/content-item`](../public-api-signatures
 - named focus-target region
 - multi-select rich grid row
 - gridRow: a non-selectable row (role="row" with a gridcell) between selectable rows of a multi-select List or Grid
+- image-led feed media with opt-in deferOffscreen hero paint deferral
 
 ## Composition
 

package/ai/components/editor-frame.md

@@ -0,0 +1,80 @@
+# EditorFrame
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:editor-frame` · Kerf UI · component · Structure
+
+A bounded editor surface with a fixed toolbar and one native source or preview scroll owner.
+
+## When to use
+
+Own a framed or embedded writing surface while the app owns its native textarea, draft, and rendered preview.
+
+- A standalone Markdown or text editor needs a fixed toolbar above a bounded native textarea or preview.
+- An embedded editor needs the same source/preview anatomy without a second frame.
+
+**Not when:**
+
+- Do not use for an ordinary single form field; use TextField.
+- Do not replace the app's draft, recovery, focus, or preview behavior.
+
+**Alternatives:**
+
+- [TextField](./text-field.md) (nearest) — Use TextField for a conventional form value without editor toolbar and preview.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/editor-frame` — exports `EditorFrame`.
+- CSS: the browser build of `@kerfjs/ui/editor-frame` pulls its CSS automatically; import `@kerfjs/ui/editor-frame.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/editor-frame`](../public-api-signatures-v1.md#kerfjsuieditor-frame) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- source and preview modes
+- framed and embedded appearances
+- padded and flush insets
+- expanded overlay
+- embedded autosize or restored source height
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [Toolbar](./toolbar.md).
+
+## State and wiring
+
+**The app owns:** draft value; editing actions; preview rendering; recovery and focus management.
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: self · padding: self (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- Give the editor frame a label when it is a distinct region; the app labels its native textarea and supplies toolbar controls.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public class hooks (select for layout placement only, never to change the component's look): `kui-editor-frame`, `kui-editor-frame__toolbar`, `kui-editor-frame__surface`.
+
+Never put `kui-editor-frame`, `kui-editor-frame__toolbar`, `kui-editor-frame__surface` on an element you write; render `EditorFrame` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-color-neutral-border-normal`, `--kui-color-neutral-on-normal`, `--kui-color-surface`, `--kui-radius-l`, `--kui-shadow-l`. Set a token only where its public contract allows; prefer a prop.
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Components: [Toolbar](./toolbar.md), [TextField](./text-field.md).
+- Docs: [`docs/editor-frame.md`](../../docs/editor-frame.md).
+- UX catalog route: `?component=editor-frame`.

package/ai/components/summary-row.md

@@ -4,13 +4,14 @@
 
 `@kerfjs/ui:summary-row` · Kerf UI · component · Structure
 
-A selectable, focusable summary of one item as a list row or a board card, with a state rail, a clamped title, trailing meta, and a metadata line.
+A selectable option or static diagnostic group as a list row or board card, with a state rail, a clamped title, trailing meta, and a metadata line.
 
 ## When to use
 
 Present dense item summaries (tickets, tasks, messages) as selectable list rows or board cards with Kerf-owned selection, hover, focus, rail, clamping, list-edge rounding, and narrow compaction, without app row CSS.
 
 - A list or board shows many items as dense, selectable summaries with an identifier, a title, a timestamp, and metadata.
+- An unreadable item needs the same summary chrome with a nested recovery action but must be a labeled non-option group.
 
 **Not when:**
 
@@ -43,6 +44,8 @@ Exact prop names and types: [`@kerfjs/ui/summary-row`](../public-api-signatures-
 - list edge start, end, or only
 - title line budget
 - deferred rendering
+- static labeled group with a nested action (semanticRole=group)
+- native draggable option root for list rows and board cards
 
 ## Composition
 
@@ -64,7 +67,7 @@ Margin: none · border: self · padding: self (layout role: structure). `self` m
 
 ## Accessibility
 
-- Each SummaryRow is role=option with tabindex=0 and aria-selected; place rows in a labeled role=listbox and move focus with the arrow keys in the app. The rail is decorative; carry its meaning in text.
+- By default SummaryRow is role=option with tabindex=0 and aria-selected; place options in a labeled role=listbox and move focus with the arrow keys in the app. semanticRole=group requires ariaLabel and omits the root Tab stop and aria-selected, so a nested native action owns focus and activation. The rail is decorative; carry its meaning in text.
 
 ## Styling boundary