@adia-ai/a2ui 0.8.43 → 0.8.45

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog — @adia-ai/a2ui
 
+## [0.8.45] — 2026-08-20
+
+### Added
+- **ADR-0078 ratified: the in-repo a2ui runtime adopts the vendored genui v1.0 data model internally (Cell/Derived reactive primitives, RFC-6901 pointer semantics), install base and dialect wire surface unchanged.** Phased across future cuts — no runtime behavior changes ship in 0.8.45. Tracked in gh#1784.
+- **ADR-0079 ratified: `for=`-carrying components normalize to an events-only interaction contract (gh#1764/#1780).**
+
+### Changed
+- **The three independently-authored path-walker implementations in `path-pointer.js` unified, deliberately preserving each call site's real divergent edge-case semantics (empty-path, primitive mid-path, doubled-slash) rather than silently collapsing them — staging for ADR-0078's migration.**
+
+### Maintenance
+- **`catalog/` touched in this release window** (3 file(s), e.g. `catalog/catalog-a2ui_0_9.json`) — carried by the entries above.
+
+## [0.8.44] — 2026-08-20
+
+### Maintenance
+- **Catalog rules text re-derived (gh#1669).** `input.yaml`'s `a2ui.rules` entry corrected — it falsely claimed an inline `[hint]` prop on `input-ui` (only `field-ui` has one); `catalog-a2ui_0_9_rules.txt` picks up the fix. No protocol/runtime API change.
+
 ## [0.8.43] — 2026-08-18
 
 ### Removed

package/catalog/catalog-a2ui_0_9.json

@@ -5881,6 +5881,16 @@
           "type": "boolean",
           "default": false
         },
+        "ratio": {
+          "description": "Chart 2.0 aspect-ratio bucket (ADR-0074). Unset (default) auto-snaps to the nearest of the three studied ratios by comparing the chart's own live box aspect against two midpoint boundaries (5:4 between 3:2/1:1, 4:5 between 1:1/2:3) — never interpolated; the resolved bucket reflects onto the host as `data-ratio-resolved`. Setting `ratio` explicitly pins that bucket regardless of the box's actual aspect, overriding the auto-snap. Orthogonal to `size` (overall scale) and `type`/`color` (ADR-0064's family axis) — this attribute lands the grammar + snap plumbing only; per-type studied renderings per bucket are later waves (gh#1624 plan steps 2-4).",
+          "type": "string",
+          "enum": [
+            "3:2",
+            "1:1",
+            "2:3"
+          ],
+          "default": ""
+        },
         "seriesEmphasis": {
           "description": "Multi-line only. Names one series key (matching a `y` key) to render at full strength — area fill + full-opacity line. Every other series drops its area fill and renders line-only at --chart-deemphasized-opacity. Empty (default) applies full treatment to every series, unchanged from pre-gh#561 behavior.",
           "type": "string",
@@ -5910,6 +5920,22 @@
           "description": "Y-axis key(s), comma-separated for multi-series",
           "type": "string",
           "default": ""
+        },
+        "yMax": {
+          "description": "Pins the value-axis domain ceiling for cartesian types (bar, line, area, scatter, multi-line, stacked-bar, grouped-bar, composed). Unset (default, null) keeps today's auto-scale ceiling (the data max). Pairs with `yMin` to pin the full domain; either may be set alone. N/A for radial/part-to-whole types — see `yMin` (gh#1690). A datum outside the pinned domain is CLAMPED to the nearest edge for rendering (the value label/tooltip still shows the real value) rather than escaping the plot box.",
+          "type": [
+            "number",
+            "null"
+          ],
+          "default": null
+        },
+        "yMin": {
+          "description": "Pins the value-axis domain floor for cartesian types (bar, line, area, scatter, multi-line, stacked-bar, grouped-bar, composed). Unset (default, null) already floors a positive series at 0 (the pre-1690 behavior, unchanged) — a migrating d3 consumer's own \"pin the floor to 0\" habit is the built-in default, not something to configure. Pin `y-min` explicitly for three OTHER cases: (1) zooming a narrow window — e.g. `y-min=\"0.9\" y-max=\"1\"` magnifies a percent series clustered near 92-95%, which reads flatter against the full auto-scaled [0,1] domain; (2) a mixed-sign series, where the unpinned floor never goes below 0 and negative values clip at the axis; (3) aligning two charts to one shared scale for a fair comparison. N/A for radial/part-to-whole types (pie, donut, radar, radial-bar, gauge, funnel, treemap, sankey, segments, sparkline) — those never read a shared linear value axis, so this prop is a no-op there (gh#1690). A datum outside the pinned domain is CLAMPED to the nearest edge for rendering (the value label/tooltip still shows the real value) rather than escaping the plot box.",
+          "type": [
+            "number",
+            "null"
+          ],
+          "default": null
         }
       },
       "required": [
@@ -6142,7 +6168,7 @@
       ],
       "properties": {
         "items": {
-          "description": "JSON array of {key, label, slot?, pct?} legend items. Takes precedence over [for] when both are provided.",
+          "description": "JSON array of {key, label, slot?, pct?, deemphasized?} legend items. Takes precedence over [for] when both are provided. `deemphasized` (REQ-R-007) mutes the row's swatch/label to the same muted-neutral tier chart-ui's own internal legend uses for a de-emphasized series (e.g. `composed@1:1`'s secondary line) — mirrored automatically from a `[for]`-bound chart's own `.legendData`, or settable explicitly here.",
           "type": "string",
           "default": ""
         },
@@ -6169,7 +6195,7 @@
           "default": "hide"
         },
         "position": {
-          "description": "Layout hint — drives flex-direction. Actual placement follows DOM order.",
+          "description": "Layout hint — drives flex-direction. Actual placement follows DOM order. Superseded by a resolved `ratio` bucket (below) whenever one is in effect; this is the pre-ADR-0074 fallback for a legend with neither an explicit `ratio` nor a `[for]`-bound chart.",
           "type": "string",
           "enum": [
             "top",
@@ -6179,6 +6205,16 @@
           ],
           "default": "bottom"
         },
+        "ratio": {
+          "description": "Chart 2.0 legend layout bucket (ADR-0074, gh#1624 plan step 5, REQ-R-005): 3:2 renders a horizontal row, 1:1 a wrapped 2-column grid, 2:3 a vertical stacked list. An explicit value PINS the bucket regardless of any bound chart. Unset (default) auto-mirrors the `[for]`-bound chart's own resolved `data-ratio-resolved` bucket — the legend never runs its own container-query classification, since its own box is typically a thin strip with no studied aspect of its own. With neither a pin nor a bound chart, no bucket resolves and `position`'s flex-direction rules apply unchanged. The resolved bucket reflects read-only onto the host as `data-ratio-resolved`, mirroring chart-ui's own convention.",
+          "type": "string",
+          "enum": [
+            "3:2",
+            "1:1",
+            "2:3"
+          ],
+          "default": ""
+        },
         "shape": {
           "description": "Swatch shape. Maps to badge-ui's icon for dot/square variants.",
           "type": "string",
@@ -6227,6 +6263,11 @@
             "a2ui": "[\n  {\n    \"id\": \"legend\", \"component\": \"ChartLegend\",\n    \"shape\": \"dot\",\n    \"items\": \"[{\\\"key\\\":\\\"revenue\\\",\\\"label\\\":\\\"Revenue\\\",\\\"slot\\\":0},{\\\"key\\\":\\\"users\\\",\\\"label\\\":\\\"Users\\\",\\\"slot\\\":1}]\"\n  }\n]",
             "name": "standalone-with-items"
           },
+          {
+            "description": "Standalone legend pinned to the 1:1 (2-col grid) layout bucket.",
+            "a2ui": "[\n  {\n    \"id\": \"legend\", \"component\": \"ChartLegend\",\n    \"ratio\": \"1:1\",\n    \"items\": \"[{\\\"key\\\":\\\"revenue\\\",\\\"label\\\":\\\"Revenue\\\",\\\"slot\\\":0},{\\\"key\\\":\\\"users\\\",\\\"label\\\":\\\"Users\\\",\\\"slot\\\":1},{\\\"key\\\":\\\"churn\\\",\\\"label\\\":\\\"Churn\\\",\\\"slot\\\":2},{\\\"key\\\":\\\"nps\\\",\\\"label\\\":\\\"NPS\\\",\\\"slot\\\":3}]\"\n  }\n]",
+            "name": "ratio-pinned-grid"
+          },
           {
             "description": "Legend mirrors a named chart's series data.",
             "a2ui": "[\n  {\n    \"id\": \"root\", \"component\": \"Column\",\n    \"children\": [\"chart\", \"legend\"]\n  },\n  {\n    \"id\": \"chart\", \"component\": \"Chart\",\n    \"type\": \"multi-line\", \"x\": \"month\", \"y\": \"revenue,users\"\n  },\n  {\n    \"id\": \"legend\", \"component\": \"ChartLegend\",\n    \"for\": \"chart\",\n    \"shape\": \"line\",\n    \"position\": \"bottom\"\n  }\n]",
@@ -8367,6 +8408,9 @@
           "--combobox-match-bg": {
             "description": "Background for `<mark>` spans that highlight matched substrings"
           },
+          "--combobox-min-width": {
+            "description": "Intrinsic min-width floor on the host (default `20ch`, matching input-ui's own `--input-min-width` UA-baseline derivation) so a combobox in a shrinking flex/grid cell doesn't crush to unusable width. Set to `0` to opt back into full collapse (gh#1633)."
+          },
           "--combobox-option-bg-active": {
             "description": "Background for the currently active (arrow-navigated) option"
           },
@@ -8852,7 +8896,7 @@
     },
     "ContextMenu": {
       "title": "ContextMenu",
-      "description": "Right-click activated menu — the OS-native context-menu pattern as a\nweb component. Distinct from `menu-ui` (which is button-triggered):\nsame item shape (`menu-item-ui` children), different trigger surface\n(`contextmenu` event), and pointer-anchored positioning instead of\nelement-anchored. Pattern: WAI-APG Menu.\n\nTwo binding modes:\n **A. Wrap.** Default-slot child becomes the target:\n `<context-menu-ui><my-table>...</my-table>...items</context-menu-ui>`.\n **B. Selector.** Point at one or more existing elements via [for]:\n `<context-menu-ui for=\"#my-table\">...items</context-menu-ui>`.\n\nOn `contextmenu` event on a target: `preventDefault()`, position the\nmenu at the pointer coords, show via Popover API. Touch long-press\n(configurable via [long-press-ms]) does the same. Shift+F10 / Menu\nkey opens at the focused target's center for keyboard users.\n",
+      "description": "Right-click activated menu — the OS-native context-menu pattern as a\nweb component. Distinct from `menu-ui` (which is button-triggered):\nsame item shape (`menu-item-ui` children), different trigger surface\n(`contextmenu` event), and pointer-anchored positioning instead of\nelement-anchored. Pattern: WAI-APG Menu.\n\nTwo binding modes:\n **A. Wrap.** Default-slot child becomes the target:\n `<context-menu-ui><my-table>...</my-table>...items</context-menu-ui>`.\n **B. Selector.** Point at one or more existing elements via\n [target-selector]:\n `<context-menu-ui target-selector=\"#my-table\">...items</context-menu-ui>`.\n\nOn `contextmenu` event on a target: `preventDefault()`, position the\nmenu at the pointer coords, show via Popover API. Touch long-press\n(configurable via [long-press-ms]) does the same. Shift+F10 / Menu\nkey opens at the focused target's center for keyboard users.\n",
       "type": "object",
       "allOf": [
         {
@@ -8867,7 +8911,7 @@
           "const": "ContextMenu"
         },
         "for": {
-          "description": "CSS selector(s) for target element(s). Empty = use default-slot child.",
+          "description": "DEPRECATED alias for [target-selector] — still a CSS selector, NOT an id-ref. Honored when [target-selector] is unset, with a one-shot console.warn pointing consumers at the replacement. New authoring should use [target-selector].",
           "type": "string",
           "default": ""
         },
@@ -8880,6 +8924,11 @@
           "description": "Programmatic open state. Set true to open at target center.",
           "type": "boolean",
           "default": false
+        },
+        "targetSelector": {
+          "description": "CSS selector(s) for target element(s). Empty = use default-slot child. Ratified name (gh#1764/#1780, ADR-0079) for what [for] used to carry — [for] means an id-ref everywhere else in AdiaUI (table-toolbar-ui, chart-legend-ui, tooltip-ui); context-menu-ui's own selector meaning predates that convention and was a same-name/ different-contract collision (ADR-0053's no-shadowing doctrine).",
+          "type": "string",
+          "default": ""
         }
       },
       "required": [
@@ -8889,7 +8938,7 @@
       "x-adiaui": {
         "anti_patterns": [
           {
-            "fix": "Wrap a target: `<context-menu-ui><my-target></my-target>...items</context-menu-ui>` OR point at one: `<context-menu-ui for=\"#my-target\">...items</context-menu-ui>`.",
+            "fix": "Wrap a target: `<context-menu-ui><my-target></my-target>...items</context-menu-ui>` OR point at one: `<context-menu-ui target-selector=\"#my-target\">...items</context-menu-ui>`.",
             "why": "No target binding — the menu never opens.",
             "wrong": "<context-menu-ui>...just items...</context-menu-ui>"
           }
@@ -12931,6 +12980,11 @@
         "component": {
           "const": "Heatmap"
         },
+        "data": {
+          "description": "Cell data as a JSON array of `{ r, c, v, label? }` objects, or set the `.data` property directly with an already-parsed array. Parsed on connect if the attribute is present and `.data` hasn't already been set programmatically.",
+          "type": "string",
+          "default": ""
+        },
         "noLegend": {
           "description": "Hide the Less/More legend strip",
           "type": "boolean",
@@ -13888,7 +13942,7 @@
           },
           {
             "fix": "{\"component\": \"CalendarPicker\", \"precision\": \"minute\"}\n",
-            "why": "Same gap as \"date\" — no native datetime picker rendered. Use\nCalendarPicker with precision=\"minute\" for combined date + time\ninput (DatetimePicker was a deprecated thin alias, cut in 0.8.43,\ngh#1617 — CalendarPicker is the sole tag now).\n",
+            "why": "Same gap as \"date\" — no native datetime picker rendered. Use\nCalendarPicker with precision=\"minute\" for combined date + time\ninput (DatetimePicker was a deprecated thin alias, cut in 0.8.43,\ngh#1617 — CalendarPicker is the sole A2UI component now).\n",
             "wrong": "{\"component\": \"Input\", \"type\": \"datetime-local\"}\n"
           },
           {
@@ -13908,7 +13962,7 @@
           },
           {
             "fix": "{\"component\": \"ColorInput\"}\n",
-            "why": "No native color swatch/picker rendered — just a plain text\nsurface. Use ColorInput for a compact form-bearing swatch +\npopover, or ColorArea directly for the full OKLCH picker surface\n(ColorPicker was a deprecated thin alias, cut in 0.8.43, gh#1617 —\nColorArea is the sole tag now).\n",
+            "why": "No native color swatch/picker rendered — just a plain text\nsurface. Use ColorInput for a compact form-bearing swatch +\npopover, or ColorArea directly for the full OKLCH picker surface\n(ColorPicker was a deprecated thin alias, cut in 0.8.43, gh#1617 —\nColorArea is the sole A2UI component now).\n",
             "wrong": "{\"component\": \"Input\", \"type\": \"color\"}\n"
           },
           {
@@ -16946,7 +17000,7 @@
           "default": false
         },
         "heading": {
-          "description": "Optional kicker label. Section variant renders it via ::before; primary uses it as aria-label only.",
+          "description": "Optional kicker label. Section variant renders it via ::before; primary uses it as aria-label only. For a VISIBLE kicker inside a primary-variant rail — or more than one kicker per <nav-ui> — hand-place <span data-nav-label> in the default slot instead; see slots below.",
           "type": "string",
           "default": ""
         },
@@ -17027,7 +17081,7 @@
         ],
         "slots": {
           "default": {
-            "description": "Primary slot — accepts <nav-group-ui> + <nav-item-ui> children, plus <hr data-nav-divider> for hand-placed dividers."
+            "description": "Primary slot — accepts <nav-group-ui> + <nav-item-ui> children, plus <hr data-nav-divider> for hand-placed dividers and <span data-nav-label> for hand-placed group-label kickers (titled runs of items/groups that aren't wrapped in a <nav-group-ui>). <span data-nav-label> renders with the same uppercase/tracking/muted kicker treatment as the [heading] ::before kicker, and is hidden alongside dividers whenever the primary-variant rail collapses ([collapsed] or ≤96px container width)."
           }
         },
         "states": [
@@ -17369,11 +17423,6 @@
           "type": "boolean",
           "default": false
         },
-        "port-size": {
-          "description": "Port indicator dot size in pixels",
-          "type": "number",
-          "default": 10
-        },
         "portSize": {
           "description": "Port indicator size",
           "type": "number",
@@ -17384,21 +17433,11 @@
           "type": "boolean",
           "default": false
         },
-        "show-ports": {
-          "description": "Show port indicator dots. Defaults to true when editable",
-          "type": "boolean",
-          "default": false
-        },
         "showPorts": {
           "description": "Show port indicators",
           "type": "boolean",
           "default": false
         },
-        "stroke-width": {
-          "description": "Stroke width in pixels",
-          "type": "number",
-          "default": 2
-        },
         "strokeWidth": {
           "description": "Line stroke width",
           "type": "number",
@@ -22411,6 +22450,11 @@
           "type": "string",
           "default": ""
         },
+        "label-hidden": {
+          "description": "When true, [label] still sets the accessible name (aria-label) but the visible `::before` text is suppressed via the canonical sr-only technique (gh#1748, mirrors check-ui's [label-hidden], gh#1010). Use when a sibling/ancestor composition already conveys the same name visually (e.g. a scope/view-switcher select in a table-toolbar-ui [slot=\"scope\"], where the toolbar's own title already names the view) and a second visible \"Scope\"-style label would paint it twice.",
+          "type": "boolean",
+          "default": false
+        },
         "mark": {
           "description": "Renders the Adia brand mark (`<adia-mark-ui>`) as the leading visual — takes precedence over avatar and icon. Token-driven (light/dark handled internally), so it fits a scheme-switching workspace/app switcher where a static logo URL can't invert. Per-option `mark` on an `<option>`/options-array entry works the same way, scoped to that row.",
           "type": "boolean",
@@ -22646,7 +22690,11 @@
           ]
         },
         "tag": "select-ui",
-        "tokens": {},
+        "tokens": {
+          "--select-min-width": {
+            "description": "Intrinsic min-width floor on the host (default `20ch`, matching input-ui's own `--input-min-width` UA-baseline derivation) so a select in a shrinking flex/grid cell doesn't crush to unusable width. Set to `0` to opt back into full collapse (gh#1633)."
+          }
+        },
         "traits": [],
         "version": 1
       }
@@ -24934,8 +24982,13 @@
         }
       ],
       "properties": {
+        "clickable-rows": {
+          "description": "Renders body rows with `cursor: pointer`. `row-click` fires unconditionally whether or not a listener is attached, so the cursor can't be inferred from listener presence — set this explicitly when row-click behavior is wired up (master-detail, open-flyout, navigation) so rows read as actionable.",
+          "type": "boolean",
+          "default": false
+        },
         "columns": {
-          "description": "Column definitions. Array of {key, label, type?, width?, minWidth?, maxWidth?, flex?, sortable?, resizable?, filterable?, pinned?, hidden?, wrap?, valign?, accessor?, format?, render?, sortFn?, filterType?, meta?}. `valign` ('top'|'center') overrides the host [valign] for that column's body cells only — header cells always stay centered. Alternative to declarative <col-def> children (<col-def valign=\"top\">); col-def also accepts `meta` as a JSON attribute (gh#925) — e.g. <col-def type=\"badge\" meta='{\"variants\":{\"Online\":\"success\"}}'> — so cell-type meta (badge variant maps, currency codes) is expressible in static HTML.",
+          "description": "Column definitions. Array of {key, label, type?, width?, minWidth?, maxWidth?, flex?, sortable?, resizable?, filterable?, pinned?, hidden?, wrap?, valign?, accessor?, format?, render?, sortFn?, filterType?, meta?}. `valign` ('top'|'center') overrides the host [valign] for that column's body cells only — header cells always stay centered. Alternative to declarative <col-def> children (<col-def valign=\"top\">); col-def also accepts `meta` as a JSON attribute (gh#925) — e.g. <col-def type=\"badge\" meta='{\"variants\":{\"Online\":\"success\"}}'> — so cell-type meta (badge variant maps, currency codes) is expressible in static HTML. Truncation contract for `render` cells (gh#1681) — a `render(value, row, cell, dataIndex)` function's returned markup isn't guaranteed to be a bare <span>/<a> the way built-in cell types are, so single-line ellipsis truncation isn't automatic; set `data-truncate` on whichever rendered element (any tag, including a custom element) should single-line-ellipsis to opt it into the same contract built-in cells get for free. `[wrap]` (host) / `[data-wrap]` (per-column) override it back to multi-line, matching built-in cells.",
           "$ref": "#/$defs/DynamicStringList"
         },
         "component": {
@@ -25671,7 +25724,7 @@
     },
     "TableToolbar": {
       "title": "TableToolbar",
-      "description": "Header / companion bar for a sibling table-ui. Renders an optional leading [slot=\"scope\"] region, title + count badge, an optional \"Showing X–Y of N\" range summary, filter / sort / columns popovers, a search input, an optional page-size select, and a trailing [slot=\"actions\"] region — all wired to the target table via an [for] id-ref. Modeled on chart-legend-ui's [for] binding pattern. Drop next to (or above) any table-ui to add the standard data-grid toolbar without re-implementing search, filter, sort, column visibility, or pagination summary/page-size. Filter rows auto-pick a primitive per column: ≤ 50 distinct values → multi-select (searchable when ≥ 12 options), id-like keys → free-text contains. The column descriptor's `filter` field overrides the auto-detect: `'select'` forces multi-select even on high-cardinality columns; `'text'` forces a contains input even on small enums.",
+      "description": "Header / companion bar for a sibling table-ui. Renders an optional leading [slot=\"scope\"] region, title + count badge, an optional \"Showing X–Y of N\" range summary, filter / sort / columns popovers, a search input, an optional [slot=\"actions-leading\"] region, an optional page-size select, and a trailing [slot=\"actions\"] region — all wired to the target table via an [for] id-ref. Modeled on chart-legend-ui's [for] binding pattern. Drop next to (or above) any table-ui to add the standard data-grid toolbar without re-implementing search, filter, sort, column visibility, or pagination summary/page-size. Filter rows auto-pick a primitive per column: ≤ 50 distinct values → multi-select (searchable when ≥ 12 options), id-like keys → free-text contains. The column descriptor's `filter` field overrides the auto-detect: `'select'` forces multi-select even on high-cardinality columns; `'text'` forces a contains input even on small enums.",
       "type": "object",
       "allOf": [
         {
@@ -25682,6 +25735,11 @@
         }
       ],
       "properties": {
+        "chromeOnly": {
+          "description": "Suppress all four native controls/search at once (filter, sort, columns, search) as additive sugar over noFilter/noSort/noColumns/ noSearch (ADR-0076, ADIA2-9123). Precedence is pure, absolute OR — while set, all four stay off regardless of any individual no-* attribute's own value, with no partial re-enable path; to re-enable one control, remove chrome-only entirely and set the other three no-* attributes explicitly instead. The four granular attributes are not deprecated or removed — they remain the independently-addressable shipped API; chrome-only never replaces them, it's a convenience preset on top.",
+          "type": "boolean",
+          "default": false
+        },
         "component": {
           "const": "TableToolbar"
         },
@@ -25744,6 +25802,18 @@
           "type": "number",
           "default": 0
         },
+        "stage": {
+          "description": "Explicit compaction-stage override (ADR-0076). Unset (the default, empty string) means auto-snap: the toolbar's own inline-size container query picks the nearest stage from its live width against the three --table-toolbar-bp-* breakpoints, snapping discretely, never interpolating. Setting stage explicitly pins that stage's rendering regardless of the container's actual width — overriding the container query, mirroring chart-ui's ratio override shape. Primary use: visual-eval fixtures that need a deterministic stage without resizing a real container, and a consumer embedding the toolbar inside a known-narrow panel who wants to skip auto-detection entirely. All four stages' CSS is now live (ADR-0076): search-tight steps the search field down (step 2); icon-only drops control labels and compacts/hides the range summary (steps 3+4); overflow collapses Filter/Sort/Columns into one \"More\" trigger routed through the same menu-ui/menu-item-ui pattern used elsewhere in the corpus (step 5). The resolved stage — the pin if set, otherwise the live width classification — also reflects onto the host as `data-stage-resolved` (step 7, informational only, mirrors chart-ui's `data-ratio-resolved` convention — never drives table-toolbar's own rendering, which stays 100% CSS-driven).",
+          "type": "string",
+          "enum": [
+            "",
+            "full",
+            "search-tight",
+            "icon-only",
+            "overflow"
+          ],
+          "default": ""
+        },
         "text": {
           "description": "Title text shown on the left.",
           "type": "string",
@@ -25774,6 +25844,7 @@
           "field-ui",
           "select-ui",
           "input-ui",
+          "menu-ui",
           "menu-item-ui",
           "icon-ui",
           "check-ui"
@@ -25793,6 +25864,21 @@
           },
           "sort-change": {
             "description": "Sort state changed. Detail: { sortState }."
+          },
+          "toolbar-columns-set": {
+            "description": "gh#1764/#1780, ADR-0079 — dispatched directly at the resolved [for] target in place of the pre-#1780 direct `target.columns =` write. table-ui listens for this on itself. Detail: { columns }."
+          },
+          "toolbar-filter-clear": {
+            "description": "gh#1764/#1780, ADR-0079 — dispatched directly at the resolved [for] target in place of the pre-#1780 direct `target.clearFilters()` call. table-ui listens for this on itself. No detail."
+          },
+          "toolbar-filter-set": {
+            "description": "gh#1764/#1780, ADR-0079 — dispatched directly at the resolved [for] target in place of the pre-#1780 direct `target.setFilter()` call. table-ui listens for this on itself. Detail: { key, value, op }; a null `value` clears that one column's filter."
+          },
+          "toolbar-paginate": {
+            "description": "gh#1764/#1780, ADR-0079 — dispatched directly at the resolved [for] target in place of the pre-#1780 direct `target.paginate =` write. table-ui listens for this on itself. Detail: { pageSize }."
+          },
+          "toolbar-search": {
+            "description": "gh#1764/#1780, ADR-0079 (events-only interaction contract) — dispatched directly at the resolved [for] target (not bubbled from this element) in place of the pre-#1780 direct `.search =` write. table-ui listens for this on itself. Detail: { value }."
           }
         },
         "examples": [
@@ -25802,8 +25888,8 @@
             "name": "members-toolbar"
           },
           {
-            "description": "The ratified adiav2 list-page toolbar row (ADIA2-9123): scope menu, range summary, filter/columns triggers, page-size select, and a primary CTA — search and sort dropped per that contract.",
-            "a2ui": "[\n  {\"id\": \"root\", \"component\": \"Column\", \"gap\": \"3\", \"children\": [\"bar\", \"card\"]},\n  {\"id\": \"bar\", \"component\": \"TableToolbar\", \"for\": \"accounts\", \"no-sort\": true, \"no-search\": true, \"range-start\": 1, \"range-end\": 25, \"range-total\": 320, \"page-size\": 25, \"page-size-options\": [10, 25, 50, 100]},\n  {\"id\": \"card\", \"component\": \"Card\", \"children\": [\"sec\"]},\n  {\"id\": \"sec\", \"component\": \"Section\", \"bleed\": true, \"children\": [\"tbl\"]},\n  {\"id\": \"tbl\", \"component\": \"Table\", \"id\": \"accounts\", \"sortable\": true, \"raw\": true}\n]",
+            "description": "The ratified adiav2 list-page toolbar row (ADIA2-9123, gh#1649): scope menu, range summary, app-owned Filter/Columns triggers (their own filter drawer, not the native popovers — [no-filter]/[no-columns]/ [no-sort]/[no-search] drop the native affordances), page-size select, and a primary CTA — [slot=\"actions-leading\"] carries the Filter/Columns triggers so they land BEFORE the page-size select, while [slot=\"actions\"] carries the CTA so it lands after.",
+            "a2ui": "[\n  {\"id\": \"root\", \"component\": \"Column\", \"gap\": \"3\", \"children\": [\"bar\", \"card\"]},\n  {\"id\": \"bar\", \"component\": \"TableToolbar\", \"for\": \"accounts\", \"no-filter\": true, \"no-sort\": true, \"no-columns\": true, \"no-search\": true, \"range-start\": 1, \"range-end\": 25, \"range-total\": 320, \"page-size\": 25, \"page-size-options\": [10, 25, 50, 100], \"children\": [\"btn-filter\", \"btn-columns\", \"btn-new\"]},\n  {\"id\": \"btn-filter\", \"component\": \"Button\", \"text\": \"Filter\", \"variant\": \"ghost\", \"slot\": \"actions-leading\"},\n  {\"id\": \"btn-columns\", \"component\": \"Button\", \"text\": \"Columns\", \"variant\": \"ghost\", \"slot\": \"actions-leading\"},\n  {\"id\": \"btn-new\", \"component\": \"Button\", \"text\": \"New account\", \"variant\": \"primary\", \"slot\": \"actions\"},\n  {\"id\": \"card\", \"component\": \"Card\", \"children\": [\"sec\"]},\n  {\"id\": \"sec\", \"component\": \"Section\", \"bleed\": true, \"children\": [\"tbl\"]},\n  {\"id\": \"tbl\", \"component\": \"Table\", \"id\": \"accounts\", \"sortable\": true, \"raw\": true}\n]",
             "name": "adiav2-list-page-toolbar-row"
           }
         ],
@@ -25832,7 +25918,13 @@
         ],
         "slots": {
           "actions": {
-            "description": "Trailing action area — primary buttons (e.g. \"New row\") rendered after the search input."
+            "description": "Trailing action area — primary buttons (e.g. \"New row\") rendered after the search input, [slot=\"actions-leading\"], and the page-size select."
+          },
+          "actions-leading": {
+            "description": "Region rendered AFTER the search input and BEFORE the native page-size select (gh#1649) — for app-owned trigger buttons (e.g. custom Filter / Columns triggers that open the consumer's own drawer instead of the native filter/columns popovers) that must land ahead of the page-size select rather than after it, unlike [slot=\"actions\"]. Same real-insertion-point pattern as [slot=\"scope\"] / [slot=\"actions\"] — positioning is CSS by DOM order, not a template stamp. Empty (the default) has zero footprint on existing consumers."
+          },
+          "empty": {
+            "description": "Renders in place of the range-summary text — the same [data-summary] region — when [range-total] is EXPLICITLY present and equal to \"0\" (checked via hasAttribute, never the computed value alone, so an unset range-total during loading never flashes this content; ADR-0076, REQ-E-001). Mutually exclusive with a positive [range-total]: the normal \"Showing X-Y of N\" text always wins whenever range-total is a positive number. Empty (the default) preserves today's exact behavior — [data-summary] hides on a confirmed range-total=\"0\" exactly as before this slot existed. Plain author-supplied markup (text, an empty-state-ui composite, an icon+text pair) — table-toolbar does not template or constrain its shape. Naming matches chart-ui's own existing `empty` slot convention."
           },
           "scope": {
             "description": "Leading region rendered BEFORE the [text]/[count] title cluster — e.g. a scope/view-switcher menu (an org's teams, a saved view). Positioning is CSS by DOM order, mirroring how [slot=\"actions\"] is a real, author-fillable insertion point rather than template-stamped content."
@@ -26705,10 +26797,10 @@
             "deck": "Sub-title under a `title`. One-line lead, slightly larger than body. Use for the lead sentence after a title.",
             "display": "Top-level hero / brand display. Tallest visual rank. Use for page-level hero one-liners.",
             "heading": "Major page heading (visual rank H2). 16-18px / bold. Use for major sub-section dividers.",
-            "kicker": "Eyebrow text above a `title`. UPPERCASE + small + tracking. Use for content eyebrows (NOT form labels — use `label` for those).",
-            "label": "Form-control label (above an `<input-ui>` / `<select-ui>` etc). UI-sized + medium-weight. Use for field labels bound to form controls.",
+            "kicker": "Eyebrow text above a `title`. UPPERCASE + small + tracking, mono font stack at regular (400) weight. Use for content eyebrows (NOT form labels — use `label` for those).",
+            "label": "Form-control label (above an `<input-ui>` / `<select-ui>` etc). UI-sized, mono font stack at regular (400) weight. Use for field labels bound to form controls.",
             "metric": "Numeric KPI / big-number stat. Bold + large. Use for dashboard metric numbers.",
-            "section": "Inline form-group / navlist heading (visual rank H4). Small-cap. Use for form group labels, nav list headings.",
+            "section": "Inline form-group / navlist heading (visual rank H4). Mono font stack at medium (500) weight, normal casing. Use for form group labels, nav list headings.",
             "subsection": "Sub-landmark within a section (visual rank H3). 14px / semibold. Use for card titles within a section."
           }
         },

package/catalog/catalog-a2ui_0_9_rules.txt

@@ -168,6 +168,7 @@
 - Standalone legend primitive — a row of <badge-ui>+<swatch-ui> chips that are keyboard-focusable and click-toggleable.
 - Pairs with <chart-ui> via [for] id-ref (auto-bidirectional series toggling) or via items= for standalone use.
 - position attribute (top|bottom|left|right) places legend relative to its chart; interactive="false" disables interactivity.
+- ratio attribute (3:2|1:1|2:3, ADR-0074) selects the legend layout shape (row/grid/list); left unset it auto-mirrors a [for]-bound chart's own resolved ratio.
 
 ## Chart
 - Declarative SVG chart supporting 18 types via the type attribute (bar, line, pie, donut, radar, area, ...).
@@ -231,7 +232,7 @@
 ## ContextMenu
 - Use <context-menu-ui> for right-click menus on a target (table row, file item, canvas object). For button-triggered menus use <menu-ui>; for popover content that is not a menu use <popover-ui> directly.
 - Items are <menu-item-ui> children inside the default slot — same shape as <menu-ui> items.
-- Bind target via wrap (default-slot first non-menu-item-ui child) OR [for] selector. The selector form is useful for whole-table or whole-canvas menus where wrapping isn't practical.
+- Bind target via wrap (default-slot first non-menu-item-ui child) OR [target-selector]. The selector form is useful for whole-table or whole-canvas menus where wrapping isn't practical. [for] still works as a deprecated alias but new authoring should use [target-selector] (gh#1764/#1780, ADR-0079).
 
 ## DateRangePicker
 - DateRangePicker.value MUST be `{from, to}` with both ISO 8601 dates, OR null. Either side null is invalid mid-state and the validator should reject it (use `input` event for partial state).
@@ -366,7 +367,7 @@
 
 ## Input
 - <input-ui> is the canonical single-line text input. The host IS the contenteditable surface — NEVER wrap a native <input>. The sole exception is type="password", which internally uses a real <input type="password"> for masking (per ADR-0025).
-- Wrap <input-ui> in <field-ui label="…" hint="…" error="…"> for the canonical stacked label / hint / error chrome. The inline [label] / [hint] / [error] props are also supported on the primitive for compact use.
+- Wrap <input-ui> in <field-ui label="…" hint="…" error="…"> for the canonical stacked label / hint / error chrome. input-ui itself only supports inline [label] / [error] (gh#1669 — [hint] is a field-ui-only prop; input-ui has no equivalent) — use field-ui when a hint line is needed.
 - Form participation is implicit via UIFormElement. Set [name] for FormData submission; [required] / [disabled] / [readonly] reflect; listen for `change` (blur or Enter commit) and `input` (per keystroke). `submit` event fires when Enter commits the value (used by <chat-composer>'s `composer-submit` forwarding).
 - For numeric input use [type="number"] with [min] [max] [step] [precision] [prefix] / [suffix] — this stamps a contenteditable surface + <button-ui> / <icon-ui> stepper column with ARIA spinbutton semantics. Read `el.valueAsNumber` for the parsed Number. Never substitute a native <input type="number">.
 - Inside <chat-composer>, the canonical inner input is <chat-input-ui> (chat variant subclass — adds the send button + model picker + paste-to-attach plumbing). The plain <input-ui> primitive ALSO fires a bubbling `submit` event on Enter (unconditional, no opt-in attribute); <chat-input-ui> simply builds on that semantic.
@@ -479,7 +480,8 @@
 - Authoring options: default stamping renders icon+text+badge from attributes. Named slots `icon`, `text`, `trailing` are also supported for custom content (e.g. a `<kbd slot="trailing">⌘K</kbd>` shortcut hint on a command-trigger item — see the admin-shell playground). Do NOT nest <nav-item-ui> inside another <nav-item-ui>.
 
 ## Nav
-- Composition: place <nav-ui> inside <admin-sidebar slot="leading"> wrapped in <section-ui> for app sidebars; inside an <aside data-subnav> with variant="section" for section / subnav rails; standalone on docs / auth pages. Children: <nav-group-ui>, <nav-item-ui>, optional <hr data-nav-divider>.
+- Composition: place <nav-ui> inside <admin-sidebar slot="leading"> wrapped in <section-ui> for app sidebars; inside an <aside data-subnav> with variant="section" for section / subnav rails; standalone on docs / auth pages. Children: <nav-group-ui>, <nav-item-ui>, optional <hr data-nav-divider>, optional <span data-nav-label> (hand-placed titled section header).
+- Titled nav-item groups: hand-place <span data-nav-label>Text</span> directly in the default slot, before a run of <nav-item-ui> / <nav-group-ui> children, to render a section-header kicker — the same uppercase/tracking/muted treatment as the [heading] ::before kicker on variant="section", but usable anywhere in the child list (not limited to one kicker per <nav-ui>) and always visually rendered, unlike [heading] which is aria-only on variant="primary". Hidden automatically whenever the primary-variant rail collapses ([collapsed] or ≤96px container width), same as <hr data-nav-divider>.
 - Variants: variant="primary" (default) — app sidebar; ResizeObserver collapses to icon-only ≤96px; collapsible groups open as a popover when collapsed. variant="section" — subnav rail; quieter chrome; optional [heading] kicker rendered via ::before.
 - Section-variant cascade (ADR-0015 § Nav consolidation): variant="section" on <nav-ui> cascades visually to direct <nav-group-ui> / <nav-item-ui> descendants via CSS `:not([variant])`. Children's JS state is NOT mutated; the cascade is purely visual. Explicit [variant] on a child always wins — use it to escape the cascade or style a standalone group/item.
 - Decision rule: if the user navigates AWAY (different page, route, or anchor) → <nav-ui>. If the user switches VIEWS within the same logical page → <tabs-ui>. Never use <nav-ui> as an in-page section switcher.
@@ -706,10 +708,14 @@
 - Use slot="action" (or [slot="actions"]) for trailing primary buttons (Invite, Export, +New). Use [text] / [count] props for the left cluster, or slotted [slot="title"] / [slot="count"] when content is markup (a <span> + <badge-ui>, etc.).
 - Listen for toolbar events (`search`, `filter-change`, `sort-change`, `columns-change`, `page-size-change`) only to mirror state to URL / persistence / analytics. The toolbar already wires its changes into the bound table — you don't need to manually update the table.
 - Use [slot="scope"] for a leading scope/view switcher (an org's teams, a saved view) rendered before [text]/[count]. Use [range-start] / [range-end] / [range-total] together for a "Showing X–Y of N" summary — it renders independently of, and alongside, [text]/[count], never in place of them. Use [page-size] + [page-size-options] for a rows-per-page select; it applies directly to the bound table's [paginate] prop the same way filter/sort/columns changes apply directly to the target.
+- Use [slot="actions-leading"] (gh#1649) for app-owned trigger buttons that must land BEFORE the page-size select — e.g. custom Filter / Columns triggers that open the consumer's own drawer instead of the native filter/columns popovers (drop [no-filter] [no-columns] to hide the native ones when doing this). [slot="actions"] stays the trailing region AFTER the page-size select, for a primary CTA.
+- Use [chrome-only] (ADR-0076, ADIA2-9123) instead of stacking [no-filter] [no-sort] [no-columns] [no-search] individually when an app owns ALL FOUR affordances itself (its own drawer/menu). Pure OR, absolute while set — clearing an individual no-* attribute does NOT re-enable that one control; drop [chrome-only] entirely and set the three you still want off explicitly instead. Combine with [slot="actions-leading"] for the app's own Filter/Columns triggers.
+- Use <span slot="empty"> (or any markup) inside a table-toolbar-ui that also sets [range-total="0"] to show a "no results" message in the range-summary's own position, without a layout shift versus the normal "Showing X-Y of N" text (ADR-0076, REQ-E). Only fires on an EXPLICIT range-total="0" — omitting range-* entirely (loading) never shows it.
+- A plain <button-ui> slotted into [slot="actions-leading"] (e.g. the app-owned Filter/Columns triggers above) already collapses to icon-only at the SAME breakpoint as the native Filter/Sort/Columns buttons (gh#1748) — no consumer JS/CSS required. Read the host's [data-stage-resolved] attribute (ADR-0076 REQ-M-005, ADIA2-9123 S4-ii) only for compaction BEYOND plain icon-only reduction — e.g. hiding a slotted button entirely at the overflow stage, or reacting to the stage in a consumer's own drawer/menu — without re-deriving the same breakpoints yourself. Informational only — mirrors the CSS-decided compaction stage (full | search-tight | icon-only | overflow), never drives table-toolbar's own rendering. Reports the pinned [stage] value when set, the live width classification otherwise; updates on both a live resize and a [stage] attribute change.
 
 ## Table
 - Canonical composition: wrap <table-ui> in <card-ui><section bleed> for edge-to-edge tables. The [bleed] removes section padding so columns span the full card width (see apps/saas/members, billing, admin-dashboard).
-- Pair with <table-toolbar-ui for="<table-id>"> for any table that needs search / filter / sort / columns visibility. Do NOT re-implement those affordances in the card header — the toolbar auto-wires search/filter/sort/columns changes into the bound table.
+- Pair with <table-toolbar-ui for="<table-id>"> for any table that needs search / filter / sort / columns visibility. Do NOT re-implement those affordances in the card header — the toolbar auto-wires search/filter/sort/columns changes into the bound table via `toolbar-*` CustomEvents (gh#1764/#1780, ADR-0079 — events-only interaction contract; table-ui listens for toolbar-search/toolbar-filter-set/toolbar-filter-clear/ toolbar-columns-set/toolbar-paginate on itself). Any consumer, not only table-toolbar-ui, may dispatch these events directly at a table-ui instance.
 - Cells truncate single-line by default (v0.6.21 §403 truncate-default). Opt out per-table with [wrap] for whole-table multiline, or per-cell with [data-wrap] on a single column / cell.
 - [raw] is a visual-and-lifecycle chrome reset for consumer-owned body markup — render()'s early return (`if (this.raw) return;`) is unconditional: no header injection, no .data/.columns reconciliation, no empty/loading overlays, no aggregation or pagination footers, even if .columns and .data are set. Reach for it only when the consumer authors 100% of the body (spreadsheet / inline-edit style patterns wrapping a native <table>) — never to "keep the data lifecycle but skip demo seeding."
 - Listen for the `sort` event with detail.key + detail.dir (NOT .column / .direction). `cell-click` detail carries {key, row, value, dataIndex}. Per ADR-0027, table-ui composes check-ui, icon-ui, progress-ui, pagination-ui, skeleton-ui, badge-ui — consumer pages must explicitly import the ones they use.

package/catalog/tier-index.json

@@ -1,9 +1,9 @@
 {
-  "catalogId": "adia.tiers@0.8.43",
+  "catalogId": "adia.tiers@0.8.45",
   "description": "Tier index of the AdiaUI catalog contract (ADR-0050). L0-L4 ladder; every tier-N entry is a declared composition of tier-(N-1) entries. L1 `composes` edges speak A2UI component TYPE names — the R-C7 catalogs’ `components` keys (genui-system SPEC R-C13). Derived — regenerate with `npm run build:catalog-tiers`, never hand-edit.",
   "extends": {
     "catalogId": "adia.base",
-    "version": "0.8.43"
+    "version": "0.8.45"
   },
   "tiers": {
     "L0": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/a2ui",
-  "version": "0.8.43",
+  "version": "0.8.45",
   "description": "The A2UI protocol — runtime (renderer, registry, streams, surface manifest, wiring primitives, dockable base classes) plus protocol-side validation. Framework-agnostic and dependency-free; pairs with any A2UI-conformant component set. Folded from @adia-ai/a2ui-runtime + the protocol half of @adia-ai/a2ui-validator (ADR-0048).",
   "type": "module",
   "exports": {

package/path-pointer.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Shared `/`-delimited path-walking helpers consolidating renderer.js,
+ * surface.js, and wiring-registry.js's originally-separate get/set
+ * implementations — see path-pointer.js for the per-function edge-case
+ * divergences each export preserves.
+ */
+
+/** renderer.js's original getByPath: root/falsy path returns `obj` itself;
+ *  no type guard mid-traversal. */
+export declare function getByPath(obj: object, path?: string): unknown;
+
+/** renderer.js's original updateDataModel write helper: mutates `obj` in
+ *  place, creating missing intermediate objects; no-op on a root/falsy
+ *  path (the caller handles whole-model replacement itself). */
+export declare function setByPath(obj: object, path: string | undefined, value: unknown): void;
+
+/** surface.js's original getPath: same root handling as getByPath, but a
+ *  looser splitter that doesn't drop empty segments (trailing/doubled
+ *  `/` behaves differently than getByPath for the same input). */
+export declare function getPath(obj: object, path?: string): unknown;
+
+/** surface.js's original setPath — see getPath's splitter note. */
+export declare function setPath(obj: object, path: string | undefined, value: unknown): void;
+
+/** wiring-registry.js's original getModelValue: an empty-string path
+ *  returns `undefined` (not `model`, unlike getByPath/getPath), and
+ *  traversal stops at the first non-object `current`, returning
+ *  `undefined` instead of falling through to primitive property access. */
+export declare function getModelValue(model: object | null | undefined, path?: string): unknown;

package/path-pointer.js

@@ -0,0 +1,129 @@
+/**
+ * Shared `/`-delimited path-walking helpers for `packages/gen-ui/a2ui`.
+ *
+ * Consolidates three independently-authored get/set implementations
+ * (reactivity review corpus, axis 3/4, R4 — gh#1763): renderer.js's
+ * `#getByPath`/`#updateDataModel`, surface.js's `getPath`/`setPath`, and
+ * wiring-registry.js's `getModelValue`. This is a MECHANICAL extraction —
+ * no call site's observable behavior changes. The three implementations
+ * disagreed on a few real edge cases (see per-function notes below); each
+ * disagreement is preserved here rather than silently unified, so this
+ * module exports one function PER call site's original semantics instead
+ * of a single "canonical" walker.
+ *
+ * Direction, not conformance: the vendored runtime
+ * (`packages/genui/renderer/dist/data-model.js`) implements full RFC 6901 —
+ * `~0`/`~1` escaping, `""`/`"/"` both meaning "whole document", immutable
+ * structural-sharing writes. None of the three functions below do any of
+ * that (no escaping, and the three don't even agree on what an empty path
+ * means), and this ticket does not add it — that would be a behavior
+ * change, and app-layer stores migrating to the vendored model is tracked
+ * separately. This module only stops the same non-conformant walk from
+ * being typed out three times.
+ */
+
+/** True for a path that addresses the whole document under every one of
+ *  the three original implementations: absent, `""`, or `"/"`. */
+function isRootPath(path) {
+  return !path || path === '/';
+}
+
+/** renderer.js's and wiring-registry.js's original splitter: drops every
+ *  empty segment, so a leading `/`, a trailing `/`, and a doubled `//` are
+ *  all forgiving — `"/a//b/"` walks `['a', 'b']`. */
+function splitPath(path) {
+  return path.split('/').filter(Boolean);
+}
+
+/** surface.js's original splitter: strips exactly one leading `/`, then
+ *  splits on every `/` WITHOUT dropping empty segments — a trailing or
+ *  doubled slash produces a `''` segment that looks up `undefined` rather
+ *  than being skipped. Kept verbatim; it's a real divergence from
+ *  {@link splitPath} (see `getPath`/`setPath` below), not a bug this
+ *  ticket fixes. */
+function splitPathLoose(path) {
+  return path.replace(/^\//, '').split('/');
+}
+
+// ── renderer.js semantics: getByPath / setByPath ───────────────────────
+//
+// Root/falsy path returns (or, for the setter, is left to the caller to
+// handle — see updateDataModel's own root branch) the object itself.
+// Traversal relies on optional chaining with no type guard, so indexing
+// past a primitive mid-path (e.g. `/name/length` where `name` is a string)
+// returns that primitive's own property instead of `undefined` — this
+// differs from `getModelValue` below, which blocks that case explicitly.
+
+/** @param {object} obj @param {string} path */
+export function getByPath(obj, path) {
+  if (isRootPath(path)) return obj;
+  return splitPath(path).reduce((o, k) => o?.[k], obj);
+}
+
+/** Mutates `obj` in place along `path`, creating missing intermediate
+ *  objects. No-op on a root/falsy path — renderer.js's `#updateDataModel`
+ *  handles whole-model replacement itself (`surface.dataModel = value ??
+ *  {}`), since that reassigns a variable this function has no reach to. */
+export function setByPath(obj, path, value) {
+  if (isRootPath(path)) return;
+  const parts = splitPath(path);
+  let cur = obj;
+  for (let i = 0; i < parts.length - 1; i++) {
+    if (cur[parts[i]] == null) cur[parts[i]] = {};
+    cur = cur[parts[i]];
+  }
+  cur[parts[parts.length - 1]] = value;
+}
+
+// ── surface.js semantics: getPath / setPath ────────────────────────────
+//
+// Same root-path handling as getByPath/setByPath, but walks with
+// splitPathLoose — so a trailing or doubled slash resolves differently
+// than getByPath/setByPath/getModelValue for the same input string.
+
+/** @param {object} obj @param {string} path */
+export function getPath(obj, path) {
+  if (isRootPath(path)) return obj;
+  const keys = splitPathLoose(path);
+  let current = obj;
+  for (const key of keys) {
+    if (current == null) return undefined;
+    current = current[key];
+  }
+  return current;
+}
+
+/** @param {object} obj @param {string} path @param {unknown} value */
+export function setPath(obj, path, value) {
+  if (isRootPath(path)) return;
+  const keys = splitPathLoose(path);
+  let current = obj;
+  for (let i = 0; i < keys.length - 1; i++) {
+    const key = keys[i];
+    if (current[key] == null) current[key] = {};
+    current = current[key];
+  }
+  current[keys[keys.length - 1]] = value;
+}
+
+// ── wiring-registry.js semantics: getModelValue ────────────────────────
+//
+// Two real divergences from getByPath: (1) an empty-string path (falsy,
+// but not `"/"`) returns `undefined` here — getByPath/getPath return the
+// object itself for ANY falsy path, including `""`. (2) traversal
+// type-guards: once `current` is a non-null value that isn't an `object`,
+// this returns `undefined` immediately rather than continuing property
+// access, so `/name/length` on a string model value reads as `undefined`
+// here vs. the string's own `.length` in getByPath/getPath.
+
+/** @param {object} model @param {string} path — JSON Pointer (e.g. "/patient/name") */
+export function getModelValue(model, path) {
+  if (!path || !model) return undefined;
+  const segments = splitPath(path);
+  let current = model;
+  for (const seg of segments) {
+    if (current == null || typeof current !== 'object') return undefined;
+    current = current[seg];
+  }
+  return current;
+}

package/renderer.js

@@ -9,6 +9,7 @@
 
 import { resolveTag, registry } from './registry.js';
 import { applyResolvedProp, toAttr } from './prop-apply.js';
+import { getByPath, setByPath } from './path-pointer.js';
 
 export class A2UIRenderer {
   #container;
@@ -479,16 +480,11 @@ export class A2UIRenderer {
     if (typeof value !== 'object') return value;
     if (value.path) {
       const surface = surfaceId ? this.#surfaces.get(surfaceId) : null;
-      return surface ? this.#getByPath(surface.dataModel, value.path) : value.path;
+      return surface ? getByPath(surface.dataModel, value.path) : value.path;
     }
     return value;
   }
 
-  #getByPath(obj, path) {
-    if (!path || path === '/') return obj;
-    return path.split('/').filter(Boolean).reduce((o, k) => o?.[k], obj);
-  }
-
   // ── updateDataModel ──
 
   #updateDataModel({ surfaceId, path, value }) {
@@ -498,13 +494,7 @@ export class A2UIRenderer {
     if (!path || path === '/') {
       surface.dataModel = value ?? {};
     } else {
-      const parts = path.split('/').filter(Boolean);
-      let cur = surface.dataModel;
-      for (let i = 0; i < parts.length - 1; i++) {
-        if (cur[parts[i]] == null) cur[parts[i]] = {};
-        cur = cur[parts[i]];
-      }
-      cur[parts[parts.length - 1]] = value;
+      setByPath(surface.dataModel, path, value);
     }
 
     for (const [compId, comp] of surface.bindings) {

package/surface.js

@@ -10,6 +10,8 @@
  * their lifecycle and provides a shared context.
  */
 
+import { getPath, setPath } from './path-pointer.js';
+
 // ── Dock order (lowest docks first, undocks last) ──
 const DOCK_ORDER = { provider: 0, controller: 1, source: 2, action: 3, lifecycle: 4 };
 
@@ -195,28 +197,3 @@ export class Surface {
     }));
   }
 }
-
-// ── JSON Pointer helpers (simplified, "/" delimited) ────────
-
-function getPath(obj, path) {
-  if (!path || path === '/') return obj;
-  const keys = path.replace(/^\//, '').split('/');
-  let current = obj;
-  for (const key of keys) {
-    if (current == null) return undefined;
-    current = current[key];
-  }
-  return current;
-}
-
-function setPath(obj, path, value) {
-  if (!path || path === '/') return;
-  const keys = path.replace(/^\//, '').split('/');
-  let current = obj;
-  for (let i = 0; i < keys.length - 1; i++) {
-    const key = keys[i];
-    if (current[key] == null) current[key] = {};
-    current = current[key];
-  }
-  current[keys[keys.length - 1]] = value;
-}

package/wiring-registry.js

@@ -12,6 +12,8 @@
  * A healthcare app registers CheckinController; a CRM registers PipelineController.
  */
 
+import { getModelValue } from './path-pointer.js';
+
 // ═══════════════════════════════════════════════════════════════
 // REGISTRY
 // ═══════════════════════════════════════════════════════════════
@@ -293,23 +295,6 @@ function extractValue(descriptor, ctx) {
   }
 }
 
-/**
- * Get a value from a data model by JSON Pointer path.
- * @param {object} model
- * @param {string} path — JSON Pointer (e.g., "/patient/name")
- * @returns {unknown}
- */
-function getModelValue(model, path) {
-  if (!path || !model) return undefined;
-  const segments = path.split('/').filter(Boolean);
-  let current = model;
-  for (const seg of segments) {
-    if (current == null || typeof current !== 'object') return undefined;
-    current = current[seg];
-  }
-  return current;
-}
-
 // ═══════════════════════════════════════════════════════════════
 // DEFAULT RESOLVERS
 // ═══════════════════════════════════════════════════════════════