@poodle64/ui 2026.8.15 → 2026.9.0

package/dist/styles.css

@@ -63,7 +63,7 @@
 @custom-variant dark (&:is(.dark *));
 
 /* ─────────────────────────────────────────────────────────────────────────────
-   The bits-ui open/closed variants.
+   The bits-ui `data-state` variants.
 
    Same defect as `dark` above, one attribute along. This package writes ~47
    `data-open:` / `data-closed:` utilities across the dialogue, alert-dialogue,
@@ -76,18 +76,58 @@
    matches — which is why four of the five adopting apps shipped with dead
    overlay transitions and none of them noticed.
 
-   Only these two need declaring. The other five shorthand data-variants this
-   package writes — `data-selected`, `data-highlighted`, `data-disabled`,
-   `data-placeholder` (bits-ui, all emitted as empty-string-or-undefined) and
-   `data-inset` (set by this package's own menu items) — are BARE attributes, so
-   Tailwind's default `&[data-x]` already matches them and a declaration here
-   would only restate it. `src/test/data-state-variants.test.ts` is what keeps
-   that distinction honest: it enumerates every shorthand data-variant the built
-   package ships and fails on any one whose compiled selector is not the
-   attribute the DOM actually carries, so a new unowned variant cannot ship.
+   `data-state` is ONE attribute carrying a dozen-odd values, and declaring two
+   of them left every other value as the same trap one value along.
+   `data-checked:` and `data-active:` compile to `&[data-checked]` /
+   `&[data-active]`, and bits-ui emits `data-state="checked"` and
+   `data-state="active"` — so a checked checkbox painted no fill and a selected
+   tab was indistinguishable from its neighbours, in exactly the silence
+   described above. Both were found in a consuming app, in a browser, months
+   after they shipped.
+
+   So the whole value set is declared, not the two that had already been
+   caught: `open`/`closed` (dialogue, menu, popover, tooltip, select),
+   `checked`/`unchecked`/`indeterminate` (checkbox, switch, menu checkbox item)
+   and `active`/`inactive` (tabs). That is a table with one rule — one
+   declaration per value bits-ui can put in `data-state` on a component this
+   package ships — rather than a growing list of exceptions, and it is the
+   whole point of fixing this at the mapping: the NEXT component to reach for
+   `data-checked:` gets a rule that matches instead of rediscovering this.
+
+   `data-active` is the one union, and it is not defensiveness. bits-ui emits
+   BOTH forms under that name: `data-state="active"` on a tabs trigger, and a
+   bare `data-active` on a navigation-menu link, a slider thumb and a pin-input
+   cell — and this package's own AppNav writes `data-active="true"` on every
+   nav row. A single-selector declaration would therefore have fixed tabs by
+   breaking the four surfaces that were already working. The other values have
+   no bare form in bits-ui 2.18.x, so they get one selector each.
+
+   `data-state="delayed-open"` (tooltip) and `data-state="selected"` (this
+   package's own table rows) keep the bracketed long form at their call sites
+   and get NO shorthand. `delayed-open` has no plausible shorthand spelling,
+   and `data-selected` is ALREADY a bare bits-ui attribute on menu and calendar
+   items — pointing that name at `[data-state='selected']` would take those
+   with it. Where a name means two things, the long form is what says which.
+
+   The remaining five shorthand data-variants this package writes —
+   `data-selected`, `data-highlighted`, `data-disabled`, `data-placeholder`
+   (bits-ui, all emitted as empty-string-or-undefined) and `data-inset` (set by
+   this package's own menu items) — are BARE attributes, so Tailwind's default
+   `&[data-x]` already matches them and a declaration here would only restate
+   it. `src/test/data-state-variants.test.ts` is what keeps that distinction
+   honest: it enumerates every shorthand data-variant the built package ships
+   and fails on any one whose compiled selector is not the attribute the DOM
+   actually carries, so a new unowned variant cannot ship. It also mounts a
+   real checkbox, switch and tab strip and reads the attributes back, so the
+   table above is pinned to bits-ui rather than to this paragraph.
    ───────────────────────────────────────────────────────────────────────────── */
 @custom-variant data-open (&[data-state='open']);
 @custom-variant data-closed (&[data-state='closed']);
+@custom-variant data-checked (&[data-state='checked']);
+@custom-variant data-unchecked (&[data-state='unchecked']);
+@custom-variant data-indeterminate (&[data-state='indeterminate']);
+@custom-variant data-active (&[data-state='active'], &[data-active]);
+@custom-variant data-inactive (&[data-state='inactive']);
 
 /* ─────────────────────────────────────────────────────────────────────────────
    The shadcn semantic surface.
@@ -198,7 +238,16 @@
 	--color-secondary: var(--secondary, var(--ds-color-surface-1));
 	--color-secondary-foreground: var(--secondary-foreground, var(--ds-color-foreground));
 	--color-muted: var(--muted, var(--ds-color-surface-1));
-	--color-accent: var(--accent, var(--ds-color-surface-2));
+	/* A SELECTION tint, not a surface rung (design-system#24). It was
+	   --ds-color-surface-2 — the same rung --color-card resolves to — which made
+	   `hover:bg-accent/50` on a card a no-op BY CONSTRUCTION: mixing a colour at
+	   any opacity over a ground it is identical to cannot change a pixel. It also
+	   left the menu/select/command highlight, the only thing this package's own
+	   components use `bg-accent` for, at 1.03:1 against the popover it sits on in
+	   light mode. A translucent tint of the accent composites over whatever
+	   ground it lands on, so one value serves both, and it is the idiom this
+	   package already ships for the SearchResults match highlight. */
+	--color-accent: var(--accent, color-mix(in oklch, var(--ds-color-primary) 12%, transparent));
 	--color-accent-foreground: var(--accent-foreground, var(--ds-color-foreground));
 	--color-input: var(--input, var(--ds-color-border));
 
@@ -303,6 +352,87 @@
 	--ds-shell-measure-wide: 120rem;
 }
 
+/* ─────────────────────────────────────────────────────────────────────────────
+   Control geometry — the density option.
+
+   Button's height and inline padding, as tokens rather than the hard-coded
+   `h-10` / `px-4` they were. No token could reach those classes, so an app
+   wanting a denser control scale had exactly one move available: fork the
+   component. One did, and it cost six directories — `button`, `dialog`,
+   `alert-dialog`, `command`, `input-group` and `form` all stayed vendored
+   there, five of them byte-identical to this package's but for which Button
+   they import. That is the whole defect: a geometry decision with no knob
+   turns into a fork of everything downstream of it.
+
+   The values below reproduce the previous hard-coded classes EXACTLY (2.5rem
+   is h-10, 1rem is px-4, and so on down the ramp), so a consumer that names
+   nothing renders to the same pixel. `harness/additivity.mjs` is what proves
+   that rather than this sentence.
+
+   An app does not set these by hand. It names a density on any ancestor —
+   ordinarily `<html>` — and the preset moves the whole ramp:
+
+       <html data-ds-density="compact">
+
+   Two named values, `comfortable` (the default) and `compact`, and the
+   attribute is honoured wherever it appears, so a single dense toolbar can
+   carry it without the page doing so. Hand-tuning a rung stays possible for
+   the app that must, but it is a deviation rather than the affordance: the
+   sanctioned move is choosing a named density, exactly as choosing a palette
+   rather than a hex value is the sanctioned move for colour.
+
+   `compact` is not a picked number. This package's Input already renders at
+   `h-8` and its Select trigger at `h-8`/`h-7`, so a default-size Button next
+   to an Input has been 8px taller than it for as long as both have shipped.
+   The compact ramp lands `md` on 2rem and `sm` on 1.75rem — the input and the
+   select trigger exactly — so the density an app was hand-pinning on 75 call
+   sites is the one that makes a form row line up.
+
+   `comfortable` shares the `:root` selector rather than restating the ramp;
+   it is there so a subtree can opt back OUT of a compact page. Both density
+   rules carry the same specificity as `:root` and are declared after it, so a
+   page-level attribute wins, and they declare on the element that carries the
+   attribute rather than at `:root`, so a scoped one reaches only its subtree.
+   ───────────────────────────────────────────────────────────────────────────── */
+:root,
+[data-ds-density='comfortable'] {
+	--ds-control-height-xs: 1.75rem;
+	--ds-control-height-sm: 2.25rem;
+	--ds-control-height-md: 2.5rem;
+	--ds-control-height-lg: 2.75rem;
+
+	--ds-control-pad-xs: 0.625rem;
+	--ds-control-pad-sm: 0.875rem;
+	--ds-control-pad-md: 1rem;
+	--ds-control-pad-lg: 1.25rem;
+
+	/* The inline padding on an edge an icon sits against: an icon is already
+	   optical whitespace, so it needs less room beside it than a glyph does. A
+	   separate rung rather than a subtraction from the pad above, because the
+	   trim is not one ratio — sm gives back 0.375rem where md gives back
+	   0.25rem — and folding it into a calc would have changed sm for every
+	   consumer to buy a shorter table. */
+	--ds-control-pad-icon-xs: 0.375rem;
+	--ds-control-pad-icon-sm: 0.5rem;
+	--ds-control-pad-icon-md: 0.75rem;
+	--ds-control-pad-icon-lg: 0.75rem;
+}
+
+[data-ds-density='compact'] {
+	--ds-control-height-xs: 1.5rem;
+	--ds-control-height-sm: 1.75rem;
+	--ds-control-height-md: 2rem;
+	--ds-control-height-lg: 2.25rem;
+	--ds-control-pad-xs: 0.5rem;
+	--ds-control-pad-sm: 0.625rem;
+	--ds-control-pad-md: 0.75rem;
+	--ds-control-pad-lg: 1rem;
+	--ds-control-pad-icon-xs: 0.25rem;
+	--ds-control-pad-icon-sm: 0.375rem;
+	--ds-control-pad-icon-md: 0.5rem;
+	--ds-control-pad-icon-lg: 0.625rem;
+}
+
 @layer base {
 	/**
 	 * The milled edge. Cards read as having depth from a hairline border plus a
@@ -788,22 +918,187 @@
 	   the measure rather than outside it. That is the same arithmetic as the
 	   `mx-auto max-w-4xl px-6` idiom this replaces, and keeping it means one
 	   element rather than a second wrapper nobody asked for. */
-	.ds-shell-measure {
-		margin-inline: auto;
-	}
-
+	/* Two classes, because the MEASURE and the CENTRING are two decisions and
+	   only the shell's content box wants both (design-system#22).
+
+	   `.ds-measure` caps the width and nothing else. It is for a block INSIDE a
+	   page — the paragraph of explanatory prose on a route legitimately set to
+	   `wide`, which would otherwise inherit a 120rem measure and run to ~123
+	   characters a line. `.ds-shell-measure` is that plus `margin-inline: auto`,
+	   which is right for the content box and wrong for a block within a page:
+	   applied to a set of left-anchored paragraphs it indented them ~207px away
+	   from their own label, measured in a consumer and reverted.
+
+	   Same attribute, same custom properties, so a block retunes with the shell
+	   rather than drifting from it. That is the whole point: the alternative an
+	   app reaches for is a local `max-w-prose` or `max-w-[72ch]`, which is a
+	   number typed once that never hears about a retune — four apps had written
+	   ten of them between them, and not one matched this package's own 72ch. */
+	.ds-measure[data-measure='prose'],
 	.ds-shell-measure[data-measure='prose'] {
 		max-width: var(--ds-shell-measure-prose);
 	}
 
+	.ds-measure[data-measure='page'],
 	.ds-shell-measure[data-measure='page'] {
 		max-width: var(--ds-shell-measure-page);
 	}
 
+	.ds-measure[data-measure='wide'],
 	.ds-shell-measure[data-measure='wide'] {
 		max-width: var(--ds-shell-measure-wide);
 	}
 
+	.ds-shell-measure {
+		margin-inline: auto;
+	}
+
+	/* ── The prose face (design-system#32) ────────────────────────────────────
+	   Styling for HTML the app did NOT author — rendered markdown, an extracted
+	   document body, a description field that arrives as rich text.
+
+	   Three consumers had built one of these, by three different mechanisms: a
+	   hand-written token-based block, the Tailwind typography plugin, and a
+	   second hand-written block that one of them had already duplicated inside
+	   itself. Every consumer that renders a document body would otherwise derive
+	   it a fourth time, and typography degrades worse than most things when it
+	   is re-derived per app.
+
+	   The package styles it and does NOT render it: sanitising untrusted HTML is
+	   a security boundary, and a package cannot see the inputs the boundary is
+	   protecting. The app owns the markdown-to-HTML seam and hands the result in.
+
+	   It carries no measure. A reading measure and a reading face are two
+	   decisions, and an app composes them:
+
+	       <div class="ds-prose ds-measure" data-measure="prose">…</div>
+
+	   Nothing here reaches for a colour or a length that is not a --ds-* token,
+	   so a palette or a retune moves the whole face with it. */
+	.ds-prose {
+		color: var(--ds-color-foreground);
+		line-height: 1.7;
+	}
+
+	.ds-prose h1,
+	.ds-prose h2,
+	.ds-prose h3,
+	.ds-prose h4 {
+		font-family: var(--ds-font-display);
+		font-weight: 600;
+		line-height: 1.25;
+		margin-block: var(--ds-spacing-lg) var(--ds-spacing-sm);
+	}
+
+	/* `em` rather than the type scale: these headings sit INSIDE a document, so
+	   they are relative to the body copy around them, not to the page's own
+	   heading ramp. An <h1> in rendered content is not the page's <h1>. */
+	.ds-prose h1 {
+		font-size: 1.5em;
+	}
+
+	.ds-prose h2 {
+		font-size: 1.25em;
+	}
+
+	.ds-prose h3,
+	.ds-prose h4 {
+		font-size: 1.1em;
+	}
+
+	.ds-prose p,
+	.ds-prose ul,
+	.ds-prose ol,
+	.ds-prose blockquote {
+		margin-block: var(--ds-spacing-sm);
+	}
+
+	.ds-prose ul,
+	.ds-prose ol {
+		padding-inline-start: var(--ds-spacing-lg);
+	}
+
+	/* Restored explicitly: the preflight reset strips list markers, and rendered
+	   content is the one place a bullet carries meaning. */
+	.ds-prose ul {
+		list-style: disc;
+	}
+
+	.ds-prose ol {
+		list-style: decimal;
+	}
+
+	.ds-prose a {
+		color: var(--ds-color-primary);
+		text-decoration: underline;
+		text-underline-offset: 2px;
+	}
+
+	.ds-prose strong {
+		font-weight: 600;
+	}
+
+	.ds-prose code {
+		font-family: var(--ds-font-code);
+		font-size: 0.9em;
+	}
+
+	.ds-prose pre {
+		background: var(--ds-color-surface-1);
+		border: 1px solid var(--ds-color-border);
+		border-radius: var(--ds-radius-sm);
+		overflow-x: auto;
+		padding: var(--ds-spacing-sm);
+	}
+
+	.ds-prose blockquote {
+		border-inline-start: 2px solid var(--ds-color-border-strong);
+		color: var(--ds-color-muted-foreground);
+		padding-inline-start: var(--ds-spacing-sm);
+	}
+
+	.ds-prose hr {
+		border: 0;
+		border-block-start: 1px solid var(--ds-color-border);
+		margin-block: var(--ds-spacing-lg);
+	}
+
+	/* A table in an extracted document is routinely wider than the measure around
+	   it. It scrolls in its OWN box rather than pushing the page sideways — the
+	   same rule the library surfaces learned at 390px. */
+	.ds-prose table {
+		border-collapse: collapse;
+		display: block;
+		font-size: 0.9em;
+		margin-block: var(--ds-spacing-md);
+		max-width: 100%;
+		overflow-x: auto;
+	}
+
+	.ds-prose th,
+	.ds-prose td {
+		border: 1px solid var(--ds-color-border);
+		padding: var(--ds-spacing-xs) var(--ds-spacing-sm);
+		text-align: start;
+	}
+
+	.ds-prose th {
+		color: var(--ds-color-muted-foreground);
+		font-weight: 600;
+	}
+
+	/* A figure in a document is evidence, so it gets the surface and border a
+	   plate deserves, and never exceeds its column. */
+	.ds-prose img {
+		background: var(--ds-color-surface-2);
+		border: 1px solid var(--ds-color-border);
+		border-radius: var(--ds-radius-sm);
+		display: block;
+		height: auto;
+		margin-block: var(--ds-spacing-md);
+		max-width: 100%;
+	}
+
 	/* The content texture: the house atmosphere, painted once by the shell on its
 	   own scrolling content region.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poodle64/ui",
-  "version": "2026.8.15",
+  "version": "2026.9.0",
   "description": "Household shared component layer: shadcn-svelte primitives (bits-ui) plus the composed page chrome every app builds its routes from, restyled by each app's @poodle64/design-tokens alias layer. One fix reaches every app.",
   "type": "module",
   "license": "MIT",
@@ -20,6 +20,10 @@
       "types": "./dist/utils.d.ts",
       "svelte": "./dist/utils.js"
     },
+    "./format": {
+      "types": "./dist/format.d.ts",
+      "svelte": "./dist/format.js"
+    },
     "./*": {
       "types": "./dist/components/ui/*/index.d.ts",
       "svelte": "./dist/components/ui/*/index.js"
@@ -27,9 +31,11 @@
   },
   "peerDependencies": {
     "bits-ui": "^2.18.1",
+    "formsnap": "^2.0.1",
     "mode-watcher": "^1.1.0",
     "svelte": "^5.33.0",
-    "svelte-sonner": "^1.1.1"
+    "svelte-sonner": "^1.1.1",
+    "sveltekit-superforms": "^2.30.0"
   },
   "peerDependenciesMeta": {
     "mode-watcher": {
@@ -37,6 +43,12 @@
     },
     "svelte-sonner": {
       "optional": true
+    },
+    "formsnap": {
+      "optional": true
+    },
+    "sveltekit-superforms": {
+      "optional": true
     }
   },
   "dependencies": {
@@ -58,6 +70,7 @@
     "@testing-library/svelte": "^5.4.2",
     "@types/node": "^22.20.1",
     "bits-ui": "^2.18.1",
+    "formsnap": "^2.0.1",
     "jsdom": "^29.1.1",
     "mode-watcher": "^1.1.0",
     "playwright": "^1.62.0",
@@ -65,6 +78,7 @@
     "svelte": "^5.56.2",
     "svelte-check": "^4.6.0",
     "svelte-sonner": "^1.1.1",
+    "sveltekit-superforms": "^2.30.2",
     "tailwindcss": "^4.3.2",
     "typescript": "^6.0.3",
     "vite": "^8.0.16",

package/registry/component-map.json

@@ -1,11 +1,11 @@
 {
 	"meta": {
 		"package": "@poodle64/ui",
-		"version": "2026.8.15",
+		"version": "2026.9.0",
 		"generatedBy": "scripts/generate-registry.mjs",
 		"source": "scripts/situations.json + package source (DO NOT EDIT the outputs by hand)",
-		"componentCount": 54,
-		"situationCount": 14
+		"componentCount": 55,
+		"situationCount": 15
 	},
 	"situations": [
 		{
@@ -155,6 +155,76 @@
 				}
 			]
 		},
+		{
+			"key": "hand-written-form",
+			"title": "A form the app itself describes",
+			"description": "A form whose fields the app writes out itself, validated by superforms and wired for accessibility by Formsnap. These wrappers put the label/description/error rhythm and the ARIA wiring in one place; the schema-described renderer above is for the other case, where the shape arrives at runtime.",
+			"components": [
+				{
+					"name": "FormField",
+					"dir": "form",
+					"import": "@poodle64/ui/form",
+					"props": "form, name, class?",
+					"insteadOf": "a <div class=\"space-y-2\"> you rebuild per field, per app"
+				},
+				{
+					"name": "FormControl",
+					"dir": "form",
+					"import": "@poodle64/ui/form",
+					"props": "children, id?",
+					"insteadOf": "wiring id/aria-describedby/aria-invalid onto the input by hand"
+				},
+				{
+					"name": "FormLabel",
+					"dir": "form",
+					"import": "@poodle64/ui/form",
+					"props": "class?",
+					"insteadOf": "a <Label> that does not turn destructive when its field errors"
+				},
+				{
+					"name": "FormDescription",
+					"dir": "form",
+					"import": "@poodle64/ui/form",
+					"props": "class?",
+					"insteadOf": "helper text the field's aria-describedby never points at"
+				},
+				{
+					"name": "FormFieldErrors",
+					"dir": "form",
+					"import": "@poodle64/ui/form",
+					"props": "class?, errorClasses?",
+					"insteadOf": "hand-rendered {#each errors} blocks, styled differently in each app"
+				},
+				{
+					"name": "FormFieldset",
+					"dir": "form",
+					"import": "@poodle64/ui/form",
+					"props": "form, name, class?",
+					"insteadOf": "a bare <fieldset> with no error state"
+				},
+				{
+					"name": "FormLegend",
+					"dir": "form",
+					"import": "@poodle64/ui/form",
+					"props": "class?",
+					"insteadOf": "a <legend> styled per app"
+				},
+				{
+					"name": "FormElementField",
+					"dir": "form",
+					"import": "@poodle64/ui/form",
+					"props": "form, name, class?",
+					"insteadOf": "hand-indexing into an array field's errors"
+				},
+				{
+					"name": "FormButton",
+					"dir": "form",
+					"import": "@poodle64/ui/form",
+					"props": "children, variant?, size?, disabled?, class?",
+					"insteadOf": "remembering type=\"submit\" on every form's Button — it forwards every Button prop and sets the type"
+				}
+			]
+		},
 		{
 			"key": "server-described-form",
 			"title": "A form the server described",
@@ -220,7 +290,7 @@
 					"name": "PageHeader",
 					"dir": "page-header",
 					"import": "@poodle64/ui/page-header",
-					"props": "title?, eyebrow?, breadcrumbs?, subtitle?, info?, actions?",
+					"props": "title?, eyebrow?, breadcrumbs?, icon?, subtitle?, info?, meta?, actions?",
 					"insteadOf": "a hand-written <h1> and title bar (the drift gate fails this)"
 				},
 				{

package/registry/component-map.md

@@ -1,7 +1,7 @@
 # @poodle64/ui — situation → component map
 
 <!-- GENERATED by scripts/generate-registry.mjs from scripts/situations.json + package source. DO NOT EDIT. -->
-Generated from `@poodle64/ui@2026.8.15`. 54 components, 14 situations.
+Generated from `@poodle64/ui@2026.9.0`. 55 components, 15 situations.
 
 **Read this before writing a `<div>`.** Find the SITUATION you are in below, then compose the component named for it — do not hand-build it from raw `Card` or utility classes. Import is `import { Name } from '<import path>'`. Props marked `?` are optional. This map is the retrieval step the [`frontend-design` skill] makes mandatory; the [CHI 2026 study] measured composing-from-a-registry at 95% design-system compliance against 71% for writing the CSS from a prose style guide.
 
@@ -83,6 +83,22 @@ _The generic titled card every route reaches for — an optional header with ico
 | --- | --- | --- | --- |
 | `Panel` | `@poodle64/ui/panel` | `children, title?, subtitle?, icon?, action?, pad?` | raw Card + CardHeader + CardTitle assembled by hand on every route |
 
+## A form the app itself describes
+
+_A form whose fields the app writes out itself, validated by superforms and wired for accessibility by Formsnap. These wrappers put the label/description/error rhythm and the ARIA wiring in one place; the schema-described renderer above is for the other case, where the shape arrives at runtime._
+
+| Component | Import | Key props | Reach for it instead of |
+| --- | --- | --- | --- |
+| `FormField` | `@poodle64/ui/form` | `form, name, class?` | a <div class="space-y-2"> you rebuild per field, per app |
+| `FormControl` | `@poodle64/ui/form` | `children, id?` | wiring id/aria-describedby/aria-invalid onto the input by hand |
+| `FormLabel` | `@poodle64/ui/form` | `class?` | a <Label> that does not turn destructive when its field errors |
+| `FormDescription` | `@poodle64/ui/form` | `class?` | helper text the field's aria-describedby never points at |
+| `FormFieldErrors` | `@poodle64/ui/form` | `class?, errorClasses?` | hand-rendered {#each errors} blocks, styled differently in each app |
+| `FormFieldset` | `@poodle64/ui/form` | `form, name, class?` | a bare <fieldset> with no error state |
+| `FormLegend` | `@poodle64/ui/form` | `class?` | a <legend> styled per app |
+| `FormElementField` | `@poodle64/ui/form` | `form, name, class?` | hand-indexing into an array field's errors |
+| `FormButton` | `@poodle64/ui/form` | `children, variant?, size?, disabled?, class?` | remembering type="submit" on every form's Button — it forwards every Button prop and sets the type |
+
 ## A form the server described
 
 _A config object whose shape arrives at runtime as a JSON Schema plus a JSON Forms UI Schema — the renderer walks both and dispatches to this package's widgets. Anything it cannot dispatch renders flagged, never blank._
@@ -109,7 +125,7 @@ _The standing chrome — the app shell and its nav, the one page-title treatment
 | Component | Import | Key props | Reach for it instead of |
 | --- | --- | --- | --- |
 | `AppShell` | `@poodle64/ui/app-shell` | `nav, currentPath, brandTitle?, actions?, context?, children` | a bespoke nav rail + header layout per app |
-| `PageHeader` | `@poodle64/ui/page-header` | `title?, eyebrow?, breadcrumbs?, subtitle?, info?, actions?` | a hand-written <h1> and title bar (the drift gate fails this) |
+| `PageHeader` | `@poodle64/ui/page-header` | `title?, eyebrow?, breadcrumbs?, icon?, subtitle?, info?, meta?, actions?` | a hand-written <h1> and title bar (the drift gate fails this) |
 | `ContextColumn` | `@poodle64/ui/context-column` | `stats, statsTitle?, statsInfo?, detail?, ariaLabel?` | a hand-built right-hand <aside> with a stat card and a detail pane |
 
 ## A dialog or overlay