@kerfjs/ui 5.0.0-beta.34 → 5.0.0-beta.35

package/README.md

@@ -4,6 +4,15 @@ Accessible, composable UI primitives for [kerf](https://github.com/brianwestphal
 
 Start interface work with the [need-first component selection matrix](./docs/component-selection.md). It distinguishes direct reuse, composition, thin application adapters, and genuinely custom semantics, with imports, required wiring, application ownership, alternatives, and recipes for every public primitive.
 
+When adding a first-party public component, follow the
+[component integration workflow](./docs/component-integration.md). The catalog
+entry drives one validator across package, build, barrel, CSS, demo, route, and
+AI signature projections, with a non-mutating dry-run report.
+
+Browser verification always builds current source: both `npm run test:e2e`
+and direct focused Playwright commands run the catalog/conformance preflights
+and production build before preview. See the [UX catalog contract](./docs/ux-demo.md).
+
 When authoring a component gallery, follow the single
 [Catalog demo authoring contract](./docs/catalog.md#catalog-demo-authoring-contract)
 for focused-versus-composition modes, helper nesting, specimen selection,
@@ -132,7 +141,7 @@ defaults to left/full alignment, the `xs` gap, and `wrap={false}`; List keeps
 its existing full/top alignment and zero-gap defaults.
 
 The same property-specific boundary applies beyond spacing: use `flex()` (or a
-finite keyword) for `List.flex`; length builders and intrinsic-size keywords for
+finite keyword) for `Row.flex` and `List.flex`; length builders and intrinsic-size keywords for
 `Skeleton.width`/`height`; length builders for `Skeleton.radius`; and
 `uiColor()` or `colorVar()` for `SelectChoice.color`. These grammars are not
 interchangeable. `ListItem` and `ListActionRow` deliberately expose no raw

package/ai/component-catalog-v2.json

@@ -1424,7 +1424,7 @@
           "required": false
         },
         {
-          "id": "typed gap overrides",
+          "id": "typed gap and flex choices",
           "owner": "application",
           "required": false
         }
@@ -1438,7 +1438,7 @@
           "border": "none",
           "padding": "none",
           "notes": [
-            "Row adds no margin, border, or padding; it owns only flex alignment, wrapping, and the gap between children."
+            "Row adds no margin, border, or padding; it owns only flex participation, alignment, wrapping, and the gap between children."
           ]
         }
       },
@@ -1463,6 +1463,16 @@
             "gap={space(\"m\")}",
             "gap={calc(plus(rem(0.25), pct(10)))}"
           ]
+        },
+        {
+          "path": "flex",
+          "grammar": "flex",
+          "helpers": ["flex"],
+          "shorthands": ["none", "auto", "initial"],
+          "canonicalShorthands": ["none", "auto", "initial"],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": ["flex", "flex=\"none\"", "flex={flex(1, 1, rem(20))}"]
         }
       ],
       "boundaries": {

package/ai/component-catalog.json

@@ -1642,7 +1642,7 @@
     "category": "Structure",
       "kind": "component",
       "source": "kerf",
-      "description": "A horizontal flex row with physical-axis alignment, a typed xs gap by default, and opt-in wrapping.",
+      "description": "A horizontal flex row with physical-axis alignment, a typed xs gap by default, flex participation, and opt-in wrapping.",
       "uses": [],
       "purpose": "Arrange related content horizontally with consistent spacing and explicit left/center/right/full plus top/middle/bottom/full alignment instead of application-owned flex wrappers.",
     "publicExports": ["Row"],
@@ -1657,16 +1657,27 @@
           "exceptionalShorthands": ["s", "xl"],
           "rawPolicy": "forbid",
           "examples": ["gap=\"xs\"", "gap={space(\"m\")}", "gap={calc(plus(rem(0.25), pct(10)))}"]
+        },
+        {
+          "path": "flex",
+          "grammar": "flex",
+          "helpers": ["flex"],
+          "shorthands": ["none", "auto", "initial"],
+          "canonicalShorthands": ["none", "auto", "initial"],
+          "exceptionalShorthands": [],
+          "rawPolicy": "forbid",
+          "examples": ["flex", "flex=\"none\"", "flex={flex(1, 1, rem(20))}"]
         }
       ],
       "useWhen": [
         "Arrange a group of sibling components horizontally.",
         "Choose physical horizontal distribution and vertical alignment without writing one-off flex CSS.",
+        "Use a finite flex keyword or the flex() builder when Row participates in a flexible parent layout.",
         "Allow a bounded group to wrap while retaining the same typed gap and alignment contract."
       ],
       "avoidWhen": [
         "Do not use Row when content belongs in a semantic list or when a named-zone component such as Toolbar owns the composition.",
-        "Do not pass raw CSS strings to gap or use s/xl spacing steps without a deliberate exception.",
+        "Do not pass raw CSS strings to gap or flex, mix their distinct grammars, or use s/xl spacing steps without a deliberate exception.",
         "Do not use alignment to replace semantic grouping or responsive relocation."
       ],
     "alternatives": [
@@ -1684,13 +1695,14 @@
       "appOwns": [
         "child semantics and content",
         "alignment and wrapping policy",
-        "typed gap overrides"
+        "typed gap and flex choices"
       ],
       "variants": [
         "left/center/right/full horizontal alignment with l/c/r/f and flex aliases",
         "top/middle/bottom/full vertical alignment with t/m/c/b/f and flex aliases",
         "named none/2xs/xs/s/m/l/xl token gap",
         "typed CssLength gap",
+        "boolean, finite-keyword, or typed CssFlex flex",
         "nowrap or wrapping"
       ],
       "accessibility": [
@@ -1702,7 +1714,7 @@
         "border": "none",
         "padding": "none",
         "notes": [
-          "Row adds no margin, border, or padding; it owns only flex alignment, wrapping, and the gap between children."
+          "Row adds no margin, border, or padding; it owns only flex participation, alignment, wrapping, and the gap between children."
         ]
       },
       "delivery": {

package/ai/public-api-signatures-v1.md

@@ -1,6 +1,6 @@
 # Public API signatures for the UI authoring corpus
 
-Generated from emitted declarations for `@kerfjs/ui@5.0.0-beta.34` and `kerfjs@5.0.0-beta.34`. This bounded reference covers only APIs used by the seven-task corpus. It is interface evidence, not an implementation or runtime guarantee.
+Generated from emitted declarations for `@kerfjs/ui@5.0.0-beta.35` and `kerfjs@5.0.0-beta.35`. This bounded reference covers only APIs used by the seven-task corpus. It is interface evidence, not an implementation or runtime guarantee.
 
 ## `@kerfjs/ui/css-values`
 
@@ -1940,3 +1940,81 @@ declare function delegateActions<E extends Element = Element>(root: HTMLElement,
 
 export { type ActionHandler, type DelegateActionsOptions, action, delegateActions };
 ```
+
+## `@kerfjs/ui/lucide-icon`
+
+```ts
+import * as kerfjs from 'kerfjs';
+import { IconNode } from 'lucide';
+
+type LucideNode = IconNode;
+interface LucideIconProps {
+    icon: LucideNode;
+    name: string;
+    className?: string;
+    label?: string;
+}
+/** Render a Lucide-compatible icon node without copying icon SVG strings. */
+declare function LucideIcon({ icon, name, className, label }: LucideIconProps): kerfjs.SafeHtml;
+
+export { LucideIcon, type LucideIconProps, type LucideNode };
+```
+
+## `@kerfjs/ui/surface-scaffold`
+
+```ts
+import * as kerfjs from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+
+type DialogSurfaceSize = 'small' | 'medium' | 'large';
+type DialogSurfacePresentation = 'modal' | 'side-sheet' | 'fullscreen';
+type SurfaceInset = 'none' | 'compact' | 'comfortable';
+interface DialogSurfaceProps {
+    children: KerfUiContent;
+    size?: DialogSurfaceSize;
+    presentation?: DialogSurfacePresentation;
+    bodyInset?: SurfaceInset;
+    footerInset?: SurfaceInset;
+    className?: string;
+}
+/** Configure recurring Web Awesome dialog geometry without consumer ::part() CSS. */
+declare function DialogSurface({ children, size, presentation, bodyInset, footerInset, className, }: DialogSurfaceProps): kerfjs.SafeHtml;
+type PopupSurfaceInset = 'standard' | 'compact' | 'list-zero';
+interface PopupSurfaceProps {
+    children: KerfUiContent;
+    inset?: PopupSurfaceInset;
+    className?: string;
+}
+/** Configure recurring Web Awesome dropdown-menu geometry without consumer ::part() CSS. */
+declare function PopupSurface({ children, inset, className, }: PopupSurfaceProps): kerfjs.SafeHtml;
+
+export { DialogSurface, type DialogSurfacePresentation, type DialogSurfaceProps, type DialogSurfaceSize, PopupSurface, type PopupSurfaceInset, type PopupSurfaceProps, type SurfaceInset };
+```
+
+## `@kerfjs/ui/row`
+
+```ts
+import * as kerfjs from 'kerfjs';
+import { UiSpaceName, CssLength, CssFlexKeyword, CssFlex } from './css-values.js';
+import { H as HorizontalAlignment, V as VerticalAlignment } from './flex-alignment-CF8NLj7i.js';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+
+interface RowProps {
+    children?: KerfUiContent;
+    /** Horizontal distribution. Defaults to left. */
+    hAlign?: HorizontalAlignment;
+    /** Vertical alignment and wrapped-line distribution. Defaults to full. */
+    vAlign?: VerticalAlignment;
+    /** A named UI spacing token or typed CSS length. Defaults to xs. */
+    gap?: UiSpaceName | CssLength;
+    /** Allow this row to grow/shrink, use a keyword, or supply a typed CSS flex shorthand. */
+    flex?: boolean | CssFlexKeyword | CssFlex;
+    /** Allow children to wrap onto additional lines. */
+    wrap?: boolean;
+    className?: string;
+}
+/** A horizontal flex row with explicit physical-axis alignment and spacing. */
+declare function Row({ children, hAlign, vAlign, gap, flex, wrap, className, }: RowProps): kerfjs.SafeHtml;
+
+export { CssFlex, CssFlexKeyword, CssLength, HorizontalAlignment, Row, type RowProps, UiSpaceName, VerticalAlignment };
+```

package/ai/webawesome-jsx-signatures-v1.md

@@ -1,6 +1,6 @@
 # Web Awesome JSX signatures for the UI authoring corpus
 
-Generated from the emitted `@kerfjs/ui@5.0.0-beta.34` declaration boundary. Import `@kerfjs/ui/webawesome` for type effects when authoring direct `wa-*` JSX. The module emits no runtime behavior and does not register custom elements.
+Generated from the emitted `@kerfjs/ui@5.0.0-beta.35` declaration boundary. Import `@kerfjs/ui/webawesome` for type effects when authoring direct `wa-*` JSX. The module emits no runtime behavior and does not register custom elements.
 
 ```ts
 import { KerfCustomElement } from 'kerfjs/jsx-runtime';

package/dist/{chunk-OKRCKIVO.js → chunk-QHCBZTDK.js}

@@ -16,10 +16,16 @@ function Row({
   hAlign = "left",
   vAlign = "full",
   gap = "xs",
+  flex = false,
   wrap = false,
   className = ""
 }) {
   const gapValue = spaceNames.includes(gap) ? space(gap) : gap;
+  const flexValue = flex === true ? "1 1 auto" : flex || void 0;
+  const style = [
+    `--_kui-row-gap:${gapValue}`,
+    flexValue ? `--_kui-row-flex:${flexValue}` : ""
+  ].filter(Boolean).join(";");
   return /* @__PURE__ */ jsx(
     "div",
     {
@@ -27,8 +33,9 @@ function Row({
       "data-component": "row",
       "data-h-align": horizontalAlignment(hAlign),
       "data-v-align": verticalAlignment(vAlign),
+      "data-flex": String(Boolean(flex)),
       "data-wrap": String(wrap),
-      style: `--_kui-row-gap:${gapValue}`,
+      style,
       children
     }
   );
@@ -36,4 +43,4 @@ function Row({
 
 export { Row };
 
-//# sourceMappingURL=chunk-OKRCKIVO.js.map
+//# sourceMappingURL=chunk-QHCBZTDK.js.map

package/dist/chunk-QHCBZTDK.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/row.tsx"],"names":[],"mappings":";;;;AAeA,IAAM,UAAA,GAAqC;AAAA,EACzC,MAAA;AAAA,EACA,KAAA;AAAA,EACA,IAAA;AAAA,EACA,GAAA;AAAA,EACA,GAAA;AAAA,EACA,GAAA;AAAA,EACA;AACF,CAAA;AAkBO,SAAS,GAAA,CAAI;AAAA,EAClB,QAAA;AAAA,EACA,MAAA,GAAS,MAAA;AAAA,EACT,MAAA,GAAS,MAAA;AAAA,EACT,GAAA,GAAM,IAAA;AAAA,EACN,IAAA,GAAO,KAAA;AAAA,EACP,IAAA,GAAO,KAAA;AAAA,EACP,SAAA,GAAY;AACd,CAAA,EAAa;AACX,EAAA,MAAM,WAAW,UAAA,CAAW,QAAA,CAAS,GAAkB,CAAA,GACnD,KAAA,CAAM,GAAkB,CAAA,GACxB,GAAA;AACJ,EAAA,MAAM,SAAA,GAAY,IAAA,KAAS,IAAA,GAAO,UAAA,GAAa,IAAA,IAAQ,MAAA;AACvD,EAAA,MAAM,KAAA,GAAQ;AAAA,IACZ,kBAAkB,QAAQ,CAAA,CAAA;AAAA,IAC1B,SAAA,GAAY,CAAA,gBAAA,EAAmB,SAAS,CAAA,CAAA,GAAK;AAAA,GAC/C,CACG,MAAA,CAAO,OAAO,CAAA,CACd,KAAK,GAAG,CAAA;AAEX,EAAA,uBACE,GAAA;AAAA,IAAC,KAAA;AAAA,IAAA;AAAA,MACC,KAAA,EAAO,CAAA,QAAA,EAAW,SAAS,CAAA,CAAA,CAAG,IAAA,EAAK;AAAA,MACnC,gBAAA,EAAe,KAAA;AAAA,MACf,cAAA,EAAc,oBAAoB,MAAM,CAAA;AAAA,MACxC,cAAA,EAAc,kBAAkB,MAAM,CAAA;AAAA,MACtC,WAAA,EAAW,MAAA,CAAO,OAAA,CAAQ,IAAI,CAAC,CAAA;AAAA,MAC/B,WAAA,EAAW,OAAO,IAAI,CAAA;AAAA,MACtB,KAAA;AAAA,MAEC;AAAA;AAAA,GACH;AAEJ","file":"chunk-QHCBZTDK.js","sourcesContent":["import {\n  type CssFlex,\n  type CssFlexKeyword,\n  type CssLength,\n  space,\n  type UiSpaceName,\n} from './css-values.js';\nimport {\n  type HorizontalAlignment,\n  horizontalAlignment,\n  type VerticalAlignment,\n  verticalAlignment,\n} from './flex-alignment.js';\nimport type { KerfUiContent } from './semantic-content.js';\n\nconst spaceNames: readonly UiSpaceName[] = [\n  'none',\n  '2xs',\n  'xs',\n  's',\n  'm',\n  'l',\n  'xl',\n];\n\nexport interface RowProps {\n  children?: KerfUiContent;\n  /** Horizontal distribution. Defaults to left. */\n  hAlign?: HorizontalAlignment;\n  /** Vertical alignment and wrapped-line distribution. Defaults to full. */\n  vAlign?: VerticalAlignment;\n  /** A named UI spacing token or typed CSS length. Defaults to xs. */\n  gap?: UiSpaceName | CssLength;\n  /** Allow this row to grow/shrink, use a keyword, or supply a typed CSS flex shorthand. */\n  flex?: boolean | CssFlexKeyword | CssFlex;\n  /** Allow children to wrap onto additional lines. */\n  wrap?: boolean;\n  className?: string;\n}\n\n/** A horizontal flex row with explicit physical-axis alignment and spacing. */\nexport function Row({\n  children,\n  hAlign = 'left',\n  vAlign = 'full',\n  gap = 'xs',\n  flex = false,\n  wrap = false,\n  className = '',\n}: RowProps) {\n  const gapValue = spaceNames.includes(gap as UiSpaceName)\n    ? space(gap as UiSpaceName)\n    : gap;\n  const flexValue = flex === true ? '1 1 auto' : flex || undefined;\n  const style = [\n    `--_kui-row-gap:${gapValue}`,\n    flexValue ? `--_kui-row-flex:${flexValue}` : '',\n  ]\n    .filter(Boolean)\n    .join(';');\n\n  return (\n    <div\n      class={`kui-row ${className}`.trim()}\n      data-component=\"row\"\n      data-h-align={horizontalAlignment(hAlign)}\n      data-v-align={verticalAlignment(vAlign)}\n      data-flex={String(Boolean(flex))}\n      data-wrap={String(wrap)}\n      style={style}\n    >\n      {children}\n    </div>\n  );\n}\n\nexport type {\n  CssFlex,\n  CssFlexKeyword,\n  CssLength,\n  UiSpaceName,\n} from './css-values.js';\nexport type {\n  HorizontalAlignment,\n  VerticalAlignment,\n} from './flex-alignment.js';\n"]}

package/dist/index.js

@@ -10,7 +10,7 @@ export { DialogSurface, PopupSurface } from './chunk-WSXUPSID.js';
 export { TabBar } from './chunk-ZPWZIVI6.js';
 export { ToolbarText } from './chunk-V6GQKOX2.js';
 export { ResizableRegion, clampRegionSize, resizeRegionFromPointer } from './chunk-CAB6NQ2T.js';
-export { Row } from './chunk-OKRCKIVO.js';
+export { Row } from './chunk-QHCBZTDK.js';
 export { SegmentedControl } from './chunk-E34TE2ZI.js';
 export { FloatingToolbar } from './chunk-DYBPI5O2.js';
 export { ListActionRow } from './chunk-DAO2VFTT.js';

package/dist/row.d.ts

@@ -1,5 +1,5 @@
 import * as kerfjs from 'kerfjs';
-import { UiSpaceName, CssLength } from './css-values.js';
+import { UiSpaceName, CssLength, CssFlexKeyword, CssFlex } from './css-values.js';
 import { H as HorizontalAlignment, V as VerticalAlignment } from './flex-alignment-CF8NLj7i.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 
@@ -11,11 +11,13 @@ interface RowProps {
     vAlign?: VerticalAlignment;
     /** A named UI spacing token or typed CSS length. Defaults to xs. */
     gap?: UiSpaceName | CssLength;
+    /** Allow this row to grow/shrink, use a keyword, or supply a typed CSS flex shorthand. */
+    flex?: boolean | CssFlexKeyword | CssFlex;
     /** Allow children to wrap onto additional lines. */
     wrap?: boolean;
     className?: string;
 }
 /** A horizontal flex row with explicit physical-axis alignment and spacing. */
-declare function Row({ children, hAlign, vAlign, gap, wrap, className, }: RowProps): kerfjs.SafeHtml;
+declare function Row({ children, hAlign, vAlign, gap, flex, wrap, className, }: RowProps): kerfjs.SafeHtml;
 
-export { CssLength, HorizontalAlignment, Row, type RowProps, UiSpaceName, VerticalAlignment };
+export { CssFlex, CssFlexKeyword, CssLength, HorizontalAlignment, Row, type RowProps, UiSpaceName, VerticalAlignment };

package/dist/row.js

@@ -1,4 +1,4 @@
-export { Row } from './chunk-OKRCKIVO.js';
+export { Row } from './chunk-QHCBZTDK.js';
 
 
 

package/dist/styles/row.css

@@ -5,6 +5,7 @@
   min-width: 0;
   min-height: 0;
   box-sizing: border-box;
+  flex: var(--_kui-row-flex, initial);
   flex-direction: row;
   flex-wrap: nowrap;
   align-items: stretch;

package/docs/component-contract.md

@@ -269,7 +269,8 @@ Logical-edge separator lines are independently opt-in and default off.
 geometry classes.
 `List` is the corresponding layout-only vertical stack: its children stretch by
 default, while `gap`, `flex`, and `scrollable` opt into typed spacing,
-flex growth, and vertical scroll ownership. `dividerSides` accepts canonical
+flex growth, and vertical scroll ownership. `Row.flex` uses the same typed flex
+participation contract on the horizontal counterpart. `dividerSides` accepts canonical
 physical top/right/bottom/left combinations such as `tr` and `trbl`; the stack
 adds no list semantics, margin, or padding of its own. Use a direct finite
 spacing shorthand such as `gap="2xs"`, or pass a `CssLength` created by the
@@ -280,7 +281,7 @@ length. Raw CSS strings and source-only `remify(4px)` are not valid runtime
 props. The `CssLength` name intentionally includes percentages for UI dimension
 props. Its opaque string brand improves authoring correctness; it is not a CSS
 sanitizer or security boundary.
-`List.flex` likewise accepts its boolean default, finite keywords, or `CssFlex`
+`Row.flex` and `List.flex` likewise accept their boolean default, finite keywords, or `CssFlex`
 from `flex(grow, shrink, basis)`. `Skeleton` width/height use `CssSize`, radius
 uses `CssLength`, and `SelectChoice.color` uses `CssColor` from `uiColor()` or
 `colorVar()`. Never exchange these property grammars. List rows expose

package/docs/component-integration.md

@@ -0,0 +1,63 @@
+# Public component integration workflow
+
+The canonical `ai/component-catalog.json` is also the integration manifest for
+first-party public components. Every entry with `source: "kerf"` and
+`kind: "component"` projects into the package, build, root API, catalog demo,
+and AI authoring surfaces. This keeps a new List-like primitive from reaching a
+late build or release gate before an omitted surface is discovered.
+
+Author the implementation, CSS, catalog facts, demo, and behavior tests first.
+Then run:
+
+```bash
+npm run component-integrations:dry-run
+```
+
+The dry run reports every mismatched projection together, using diff-like
+`expected` and `actual` lines without changing files or failing the command.
+Resolve the complete report, build the package, regenerate signatures with
+`npm run ai:signatures:sync`, and refresh reviewed compatibility digests with
+`npm run ai:compatibility:sync`. `npm run check:component-integrations` runs the
+same validator in failing CI mode, and the package `check` gate includes it.
+
+For each catalog component, the validator checks:
+
+- the source module and stylesheet;
+- the tsup entry and typed package subpath, including the browser-conditioned
+  entry when the catalog declares `browserImport`;
+- the CSS package export;
+- root-barrel exposure for browser-conditioned components;
+- the stable catalog route, demo module, and exhaustive demo registry; and
+- inclusion of the public subpath in the generated AI signature reference.
+
+The existing catalog sync and compatibility gates remain responsible for the
+typed catalog projections, catalog count/order, and artifact digests. Public
+API signatures derive component subpaths from the catalog, so a newly cataloged
+component can no longer be silently omitted from that corpus.
+
+Non-component helpers, wiring modules, compositions, recipes, and development
+tools remain explicit package surfaces. They do not masquerade as visual
+components merely to enter this workflow.
+
+## Change-local verification and bundle review
+
+Run `npm run check:change` after changing a public component. It synchronizes
+both catalog projections, declarations, AI signatures, and compatibility
+digests; names every checked-in projection changed by that synchronization;
+runs the catalog/component contracts, unit coverage, consumer bundle tests,
+source and packed type contracts; builds the production catalog; and reports
+the exact gzip byte delta from the last reviewed baseline. The broader
+`npm run check` remains the release gate.
+
+Intentional bundle changes use the same workflow with an explicit review
+reason:
+
+```bash
+npm run check:change -- --update-bundle-budget \
+  --reason "Added the reviewed List detail states and keyboard behavior"
+```
+
+That mode writes `demo-bundle-budget.json`, records the previous and new exact
+measurements and budgets with the reason and timestamp, and rounds the total
+budget to the next 100 bytes. Do not edit the budget or add a history comment
+by hand.

package/docs/component-selection.md

@@ -66,7 +66,7 @@ contract lands before the 5.0 stable release so misspelled tokens and incomplete
 expressions fail during typechecking rather than in the browser.
 
 Other CSS-valued props use distinct contracts: `flex()` creates `CssFlex` for
-`List.flex`; `Skeleton` dimensions take typed lengths (plus finite intrinsic
+`Row.flex` and `List.flex`; `Skeleton` dimensions take typed lengths (plus finite intrinsic
 keywords for width/height); and `uiColor()`/`colorVar()` create `CssColor` for
 `SelectChoice.color`. Do not substitute one brand for another. Row components
 have no declaration-string `style` prop; use `className`, documented public

package/docs/layout.md

@@ -136,6 +136,13 @@ items, while applying the requested distribution to `align-content` when a
 Row wraps. Prefer the descriptive values in application code; the short and
 CSS-shaped aliases are provided for compact or migrated call sites.
 
+`Row.flex` and `List.flex` share one typed participation contract. Omit the prop
+for the CSS initial value, pass `true` for `1 1 auto`, select the finite
+`"none"`, `"auto"`, or `"initial"` keyword, or use
+`flex(grow, shrink, basis)` from `@kerfjs/ui/css-values` for a complete branded
+shorthand. A `CssLength` is not a flex shorthand, and arbitrary strings are
+rejected by the type contract.
+
 `--kui-space-s` (12px) and `--kui-space-xl` (32px) exist but are **off the
 canonical rhythm** — reach for them only as a deliberate exception, never as a
 default step. Prefer the five canonical tokens so spacing stays legible and

package/docs/ux-demo.md

@@ -2,6 +2,16 @@
 
 Run `npm run dev` from `ui/`. The catalog is a development and review surface, not a second implementation. The development server allows repo-owned assets used by the catalog, and its production bundle uses relative asset URLs so the complete catalog remains intact below preview and proxy paths.
 
+Every Playwright entry point builds current source before the preview server
+starts. `npm run test:e2e -- tests/browser/row.spec.ts` and a direct focused
+`npx playwright test tests/browser/row.spec.ts` both run catalog generation and
+demo-conformance preflights, build the package and production catalog, then
+launch Chromium, Firefox, and WebKit. The build emits
+`source-freshness.json`; browser coverage compares it with an independent hash
+of the current `src/` and `ux-demo/` inputs, so a stale `dist-demo` cannot pass
+after a route or component edit. `npm run demo:serve` remains a preview-only
+command for an already-built catalog.
+
 Seven lazy production-composition routes live under the `Recipes` category.
 Each `?component=recipe-*` route uses public package primitives, real wiring,
 deterministic state, and semantic layout owners from the [recipe guide](./recipes.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kerfjs/ui",
-  "version": "5.0.0-beta.34",
+  "version": "5.0.0-beta.35",
   "description": "Accessible, composable UI primitives for kerf applications.",
   "type": "module",
   "license": "MIT",
@@ -329,11 +329,15 @@
     "dev": "npm run build && vite --config ux-demo/vite.config.ts",
     "demo:build": "npm run build && vite build --config ux-demo/vite.config.ts && node scripts/check-demo-bundle.mjs",
     "demo:serve": "vite preview --config ux-demo/vite.config.ts",
+    "test:e2e:serve": "npm run check:catalog && npm run check:demo-conformance && npm run demo:build && npm run demo:serve",
     "format": "prettier --write . --ignore-unknown",
     "format:css": "prettier --write \"src/**/*.css\" \"ux-demo/**/*.css\"",
     "check:format": "prettier --check . --ignore-unknown",
     "catalog:sync": "node scripts/sync-component-catalog.mjs && node scripts/sync-component-catalog-v2.mjs",
     "catalog:v2:sync": "node scripts/sync-component-catalog-v2.mjs",
+    "check:component-integrations": "node scripts/check-component-integrations.mjs",
+    "component-integrations:dry-run": "node scripts/check-component-integrations.mjs --dry-run",
+    "check:change": "node scripts/check-ui-change.mjs",
     "check:catalog": "node scripts/sync-component-catalog.mjs --check && node scripts/sync-component-catalog-v2.mjs --check && node scripts/check-component-catalog.mjs",
     "check:profile": "node scripts/check-application-ui-profile.mjs",
     "check:demo-conformance": "node scripts/check-catalog-demo-conformance.mjs",
@@ -341,6 +345,8 @@
     "check:ai-regressions": "node scripts/check-ai-regressions.mjs && node scripts/audit-ai-regression-results.mjs && node scripts/audit-ai-regression-results-v3.mjs",
     "check:ai-signatures": "node scripts/sync-ai-public-signatures.mjs --check",
     "ai:signatures:sync": "npm run build && node scripts/sync-ai-public-signatures.mjs",
+    "check:ai-compatibility": "node scripts/sync-ai-compatibility.mjs",
+    "ai:compatibility:sync": "node scripts/sync-ai-compatibility.mjs --write",
     "ai:regressions:compile": "node scripts/compile-ai-regression-response.mjs",
     "ai:regressions:prepare": "node scripts/prepare-ai-regression.mjs",
     "ai:regressions:record": "node scripts/record-ai-regression-run.mjs",
@@ -360,8 +366,8 @@
     "test:contract-types:source": "node node_modules/typescript7/bin/tsc -p tests/consumer-types/contracts/tsconfig.source.json",
     "test:contract-types:packed": "node scripts/check-packed-type-contracts.mjs",
     "test:consumer-types": "npm run test:contract-types:source && npm run build && node node_modules/typescript7/bin/tsc -p tests/consumer-types/webawesome/tsconfig.json && npm run test:contract-types:packed",
-    "test:e2e": "npm run demo:build && playwright test",
-    "check": "npm run check:catalog && npm run check:profile && npm run check:demo-conformance && npm run check:recipes && npm run check:guidance && npm run check:ai-regressions && npm run lint && npm run typecheck && npm test && npm run test:consumer-types && npm run check:ai-signatures && npm run demo:build && npm run check:design-templates && npm pack --dry-run",
+    "test:e2e": "playwright test",
+    "check": "npm run check:catalog && npm run check:component-integrations && npm run check:profile && npm run check:demo-conformance && npm run check:recipes && npm run check:guidance && npm run check:ai-compatibility && npm run check:ai-regressions && npm run lint && npm run typecheck && npm test && npm run test:consumer-types && npm run check:ai-signatures && npm run demo:build && npm run check:design-templates && npm pack --dry-run",
     "prepublishOnly": "npm run check",
     "check:design-templates": "node scripts/check-design-templates.mjs",
     "check:design-templates:drift": "node scripts/check-design-templates-drift.mjs",

package/dist/chunk-OKRCKIVO.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/row.tsx"],"names":[],"mappings":";;;;AASA,IAAM,UAAA,GAAqC;AAAA,EACzC,MAAA;AAAA,EACA,KAAA;AAAA,EACA,IAAA;AAAA,EACA,GAAA;AAAA,EACA,GAAA;AAAA,EACA,GAAA;AAAA,EACA;AACF,CAAA;AAgBO,SAAS,GAAA,CAAI;AAAA,EAClB,QAAA;AAAA,EACA,MAAA,GAAS,MAAA;AAAA,EACT,MAAA,GAAS,MAAA;AAAA,EACT,GAAA,GAAM,IAAA;AAAA,EACN,IAAA,GAAO,KAAA;AAAA,EACP,SAAA,GAAY;AACd,CAAA,EAAa;AACX,EAAA,MAAM,WAAW,UAAA,CAAW,QAAA,CAAS,GAAkB,CAAA,GACnD,KAAA,CAAM,GAAkB,CAAA,GACxB,GAAA;AAEJ,EAAA,uBACE,GAAA;AAAA,IAAC,KAAA;AAAA,IAAA;AAAA,MACC,KAAA,EAAO,CAAA,QAAA,EAAW,SAAS,CAAA,CAAA,CAAG,IAAA,EAAK;AAAA,MACnC,gBAAA,EAAe,KAAA;AAAA,MACf,cAAA,EAAc,oBAAoB,MAAM,CAAA;AAAA,MACxC,cAAA,EAAc,kBAAkB,MAAM,CAAA;AAAA,MACtC,WAAA,EAAW,OAAO,IAAI,CAAA;AAAA,MACtB,KAAA,EAAO,kBAAkB,QAAQ,CAAA,CAAA;AAAA,MAEhC;AAAA;AAAA,GACH;AAEJ","file":"chunk-OKRCKIVO.js","sourcesContent":["import { type CssLength, space, type UiSpaceName } from './css-values.js';\nimport {\n  type HorizontalAlignment,\n  horizontalAlignment,\n  type VerticalAlignment,\n  verticalAlignment,\n} from './flex-alignment.js';\nimport type { KerfUiContent } from './semantic-content.js';\n\nconst spaceNames: readonly UiSpaceName[] = [\n  'none',\n  '2xs',\n  'xs',\n  's',\n  'm',\n  'l',\n  'xl',\n];\n\nexport interface RowProps {\n  children?: KerfUiContent;\n  /** Horizontal distribution. Defaults to left. */\n  hAlign?: HorizontalAlignment;\n  /** Vertical alignment and wrapped-line distribution. Defaults to full. */\n  vAlign?: VerticalAlignment;\n  /** A named UI spacing token or typed CSS length. Defaults to xs. */\n  gap?: UiSpaceName | CssLength;\n  /** Allow children to wrap onto additional lines. */\n  wrap?: boolean;\n  className?: string;\n}\n\n/** A horizontal flex row with explicit physical-axis alignment and spacing. */\nexport function Row({\n  children,\n  hAlign = 'left',\n  vAlign = 'full',\n  gap = 'xs',\n  wrap = false,\n  className = '',\n}: RowProps) {\n  const gapValue = spaceNames.includes(gap as UiSpaceName)\n    ? space(gap as UiSpaceName)\n    : gap;\n\n  return (\n    <div\n      class={`kui-row ${className}`.trim()}\n      data-component=\"row\"\n      data-h-align={horizontalAlignment(hAlign)}\n      data-v-align={verticalAlignment(vAlign)}\n      data-wrap={String(wrap)}\n      style={`--_kui-row-gap:${gapValue}`}\n    >\n      {children}\n    </div>\n  );\n}\n\nexport type { CssLength, UiSpaceName } from './css-values.js';\nexport type {\n  HorizontalAlignment,\n  VerticalAlignment,\n} from './flex-alignment.js';\n"]}