@adia-ai/adia-ui-forge 0.8.57 → 0.8.59

package/skills/package-release/scripts/release-pack.mjs

@@ -88,6 +88,26 @@ const DEFAULT_NPM_SCOPE = '@adia-ai';
 const LOCKSTEP_ROSTER = PACKAGE_ROSTER.filter((p) => p.lockstep !== false);
 const PACKAGES = LOCKSTEP_ROSTER.map((p) => p.name);
 
+// Reject a --substantive-packages/--stub-packages name whose roster entry is
+// unknown or lockstep:false, BEFORE Step 1 runs (gh#2894). The 0.8.58 cut
+// passed `adia-plugins` (lockstep:false, gh#1133) in --substantive-packages;
+// promote-unreleased.mjs happily rewrote its CHANGELOG's [Unreleased] header
+// to a version that package doesn't ship, and the cut only caught it at Step
+// 5.6's unstaged-tracked-files guard — AFTER the 34-gate pre-flight had
+// already run. Matches PACKAGE_ROSTER by name form (`adia-plugins`) or dir
+// form minus the `packages/` prefix (`plugins/adia-plugins`).
+function assertLockstepPackages(names) {
+  for (const pkg of names) {
+    const entry = PACKAGE_ROSTER.find(
+      (p) => p.name === pkg || p.dir.replace(/^packages\//, '') === pkg,
+    );
+    if (!entry || entry.lockstep === false) {
+      console.error(`error: --substantive-packages/--stub-packages package "${pkg}" is not lockstep:true in scripts/package-paths.mjs PACKAGE_ROSTER (unknown or class-B) — rejected before Step 1.`);
+      process.exit(2);
+    }
+  }
+}
+
 function parseArgs(argv) {
   const args = {
     version: null, date: null, previous: null, mode: null,
@@ -148,6 +168,12 @@ function parseArgs(argv) {
     console.error(`error: --mode must be cut|from-scratch|handoff (got: ${args.mode})`);
     process.exit(2);
   }
+  // Roster validation (gh#2894), before any mode-specific check below —
+  // applies to BOTH cut and from-scratch (the script's own --help text shows
+  // both flags on a `cut` invocation).
+  if (args.substantivePackages || args.stubPackages) {
+    assertLockstepPackages([...(args.substantivePackages ?? []), ...(args.stubPackages ?? [])]);
+  }
   // Handoff needs the GH-notes body at Step 10 — validate at PARSE time, not
   // there: on the v0.8.10 cut the missing flag surfaced only after tags and
   // npm publish were already irreversible (Step 10 is the LAST step). An arg
@@ -1753,6 +1779,37 @@ async function selftest() {
       process.exit(1);
     }
 
+    // gh#2894 — a --substantive-packages/--stub-packages name whose roster
+    // entry is lockstep:false (or unknown) must die at PARSE time, naming
+    // the roster file, BEFORE Step 1 runs. The 0.8.58 cut passed
+    // `adia-plugins` (lockstep:false) in --substantive-packages and only
+    // caught it at Step 5.6, after the 34-gate pre-flight had already run.
+    const rosterRejectShapes = [
+      { flags: '--substantive-packages adia-plugins', name: 'adia-plugins' },
+      { flags: '--stub-packages totally-unknown-package', name: 'totally-unknown-package' },
+    ];
+    for (const { flags, name } of rosterRejectShapes) {
+      let failed = false;
+      let out = '';
+      try {
+        execSync(
+          `node "${scriptPath}" --mode cut --version 9.9.9 --date 2026-01-01 --previous-version 9.9.8 ${flags} --dry`,
+          { cwd: REPO, encoding: 'utf8' },
+        );
+      } catch (e) {
+        failed = true;
+        out = (e.stdout || '') + (e.stderr || '');
+      }
+      if (!failed || !out.includes(name) || !out.includes('package-paths.mjs PACKAGE_ROSTER')) {
+        console.error(`selftest FAIL: --substantive-packages/--stub-packages "${name}" must hard-reject naming scripts/package-paths.mjs PACKAGE_ROSTER`);
+        process.exit(1);
+      }
+      if (out.includes('=== Step 1') || out.includes('gate roster')) {
+        console.error(`selftest FAIL: the roster guard for "${name}" must fire BEFORE Step 1, not after`);
+        process.exit(1);
+      }
+    }
+
     // gh#765 — from-scratch with substantive-but-no-stub packages must die at
     // PARSE time, naming the ride-alongs, BEFORE any pre-flight gate runs
     // (v0.8.29 burned three ~15-min pre-flight re-runs discovering it at

package/skills/primitive-authoring/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: primitive-authoring
 description: >-
-  Author or modify AdiaUI framework source inside the monorepo — primitives
+  Author or modify AdiaUI framework source inside the monorepo — components
   (packages/web-components), shells/composites (packages/web-modules), yaml
-  SoTs, demos. Use to add a new primitive, fix a prop/slot/attribute/CSS
+  SoTs, demos. Use to add a new component, fix a prop/slot/attribute/CSS
   variant, update a yaml, build or fix a shell (chat-shell, admin-shell,
   editor-shell — sidebar/pane/bespoke-tier composition), promote repeated
   inline content into a shared module, audit a component's four-axis
@@ -100,5 +100,8 @@ then the full sequence — never suppress.
   [authoring-cycle.md](references/authoring-cycle.md) Step 3 are fixed
   immediately; contract-neutral pattern drift is proposed in review, not
   blocked on.
+- **SoT-change / component.md check**: new or changed states or aria
+  behavior on a yaml with a `component.md` sibling → component-md-authoring's
+  authored `screenReader`/`behavioral` sections may need a pass.
 - A one-line bug that touches no props, CSS contract, or lifecycle doesn't
   need this skill's overhead — just read the code and edit.

package/skills/primitive-authoring/agents/openai.yaml

@@ -1,3 +1,3 @@
 interface:
   display_name: "Primitive Authoring"
-  short_description: "Author or modify AdiaUI framework source inside the monorepo — primitives (packages/web-components), shells/composites (packages/web-modules), yaml SoTs, demos."
+  short_description: "Author or modify AdiaUI framework source inside the monorepo — components (packages/web-components), shells/composites (packages/web-modules), yaml SoTs, demos."

package/skills/primitive-authoring/references/anti-patterns.md

@@ -646,6 +646,46 @@ If you author a primitive that programmatically creates another (`document.creat
 
 Source: ADR-0027.
 
+### AP-R2 · Folding two visually-converging widgets into a shared module (ADR-0101)
+
+Two widgets can converge visually — same tab-strip chrome, same header
+band, same "looks like the same component" impression on the catalog page
+— while carrying fundamentally different content models underneath. That
+visual overlap alone is not sufficient reason to extract a shared module
+or fold one into the other.
+
+`inspector-ui` (a live devtools pane: four fixed panes, content pushed in
+imperatively and repeatedly after connect via `update()`/`setHTML()`) and
+`preview-ui` (static docs demo chrome: content captured once on connect,
+shown two fixed ways) look like the same tabbed-view widget. They aren't:
+folding one into the other would force the static-capture component to
+grow a second, incompatible imperative-update mode it doesn't need for the
+job it already does correctly everywhere it's used — added surface, not
+removed surface. Extracting a shared tab-view module was evaluated and
+rejected for the same reason: no common substrate exists beneath the
+visual layer that both widgets could share without also merging their
+different content models (`tabs-ui`'s synthesized strip vs. a hand-rolled
+`role="tablist"` div built for single-panel content-swap semantics).
+
+**The resolution is a mirror, not a merge:** keep both components on their
+own contracts; restyle the trailing one to match the leading one's chrome
+via scoped CSS only (`@scope (inspector-ui)` overrides copying
+`preview-ui`'s header-tab anatomy, tokens, and typography) — no shared
+component, no deprecation. The tradeoff this accepts: because the
+mirroring is duplicated CSS, not a shared module, a future visual change
+to the pattern's source component doesn't automatically propagate: check
+the mirrored block for parallel drift when you next touch the pattern
+that's being mirrored — the same "primitives that compose primitives
+don't auto-import" discipline ADR-0027 already requires (AP-R1, above),
+now applied to a duplicated CSS block instead of a duplicated import.
+
+Before extracting a shared module for two things that "look the same,"
+verify they'd actually share the extracted contract (props, update
+semantics, lifecycle) — not just its rendered chrome. If they wouldn't,
+mirror the chrome and keep both components separate.
+
+Source: ADR-0101.
+
 ---
 
 ## Rapid-fire anti-patterns (mined from incident history)

package/skills/primitive-authoring/references/css-patterns.md

@@ -62,6 +62,18 @@ Every component CSS file has exactly this shape:
 
 When a parent tries to override `--component-bg`, specificity beats them. The zero-specificity layer is the contract.
 
+## Region elements never self-style (2026-09-01, ADR-0105)
+
+Native `<header>`/`<section>`/`<footer>` and `<header-ui>`/`<section-ui>`/`<footer-ui>` (a CSS-only slot-routing anatomy stub — no JS, no events, no `.css` file of its own) are **region elements**, not components in their own right. They carry zero layout CSS. Every grid, gap, sticky rule, and slot-vocabulary variant a region renders is written in the **closest host pattern's** `@scope (host-name)` block — `page-ui`, `card-ui`, `drawer-ui`, `modal-ui`, `anchor-bar`, the shells — matching the region by tag + attribute selector (`:scope > :where(header, header-ui)`, `:has(> [slot="action"])`, etc.), never in a region-owned stylesheet.
+
+**If you're authoring a new host pattern that accepts region children, you MUST ship its `@scope` treatment for every region shape it accepts before it ships.** A host that accepts `<header-ui>` without a matching grid/sticky/slot-vocabulary block is not a lesser-but-valid host — the region element structurally cannot supply the missing layout itself, so the host renders wrong (usually unstyled block flow, or — the observed failure mode — a stale layout that packs content into the wrong shape). gh#2760 is the live example: `page-ui`'s header-band `@scope` block didn't reproduce the retired `admin-page-header`'s action-cluster grid for a multi-item `[slot="action"]` containing a block-level `<tabs-ui>`, so tabs overlapped buttons instead of getting their own row — same markup, incomplete host coverage.
+
+**Bare `<header>` vs `<header-ui>`** — both reach a host's tag-matched rules identically (`:where(header, header-ui, …)` gives them equal zero specificity). They diverge only on rules keyed off a named-slot attribute selector (`:has(> [slot="icon"])`, etc.) — and there the divergence isn't mechanical (`slot=` is decorative everywhere, ADR-0033), it's documentation: `header-ui`'s own yaml is the only place the icon/heading/description/action vocabulary is written down and steered toward by `a2ui.rules`. Use bare `<header>`/`<section>`/`<footer>` only for unstructured default-slot content; use the `-ui` stub whenever content decomposes into the slot vocabulary — that's the only path an author or the A2UI generator discovers it exists.
+
+A region element acquiring its own `.css` file (layout rules scoped to `header-ui` itself, not the host) is the anti-pattern this section exists to name — see ADR-0105 for the full rationale and the corollary above.
+
+Source: [ADR-0105](../../../../../../docs/ops/adr/adr-0105-region-elements-never-self-style.md).
+
 ## Variants vs modes — the decision tree
 
 The rule: **variants change tokens; modes change layout.**

package/skills/primitive-authoring/references/form-control-sizing.md

@@ -31,6 +31,16 @@ Decision Class 1 removes the 20ch-class field-width floor for
 floor, generalizing the `button-ui` keep-square pattern already named below
 to the field-width components.
 
+**[amended 2026-08-31, gh#2534, ADR-0095]** The square-minimum rule governs
+a primitive's own OUTER inline-size floor against its own block-size only —
+it does not reach a component's INTERNAL grid-column sizing. A token like
+`field-ui[inline]`'s `--field-label-inline-min: 10ch` floors the label
+*column* inside the component's internal grid, to keep sibling rows
+aligned — not to prevent the host itself from collapsing — so it is not
+"a `--*-min-width: 20ch`-class floor" in ADR-0095's sense and is not
+retired by the Decision above. Don't apply the square-minimum rule to an
+internal grid-column token by analogy to the field-width class.
+
 *(Historical, pre-ADR-0095 rule — superseded by the retirement above, kept
 only for context on what the old convention was.)* A
 `--*-min-width: 20ch`-class floor (the gh#781/gh#1633 pattern on

package/skills/primitive-authoring/references/shell-patterns.md

@@ -448,6 +448,13 @@ Consumers (CodeMirror layout, canvas redraw, dependent UI) listen on the shell o
 
 ### admin cluster (canonical reference)
 
+**[deprecated 2026-09-01, ADR-0098]** `admin-page`/`admin-page-header`/
+`admin-page-body` are retired deprecate-then-delete; `admin-scroll` is
+renamed wholesale to `page-scroll`. `page-ui[band]` + `page-scroll` are
+now the canonical page-chrome pair — this cluster still describes
+`admin-shell`'s pre-migration internal composition, valid during the
+deprecation window.
+
 - **3 JS-bearing children** — `<admin-shell>` (host coordinator), `<admin-sidebar>` (resize+collapse+persist), `<admin-command>` (Cmd+K palette)
 - **7 CSS-only structural children** — `<admin-content>`, `<admin-topbar>`, `<admin-statusbar>`, `<admin-scroll>`, `<admin-page>`, `<admin-page-header>`, `<admin-page-body>`
 - **CSS bridge** — `packages/web-modules/shell/admin-shell/css/admin-shell.bespoke.css` (~240 LOC)
@@ -547,7 +554,7 @@ When you encounter a legacy reference in old documentation or commit history, th
 
 - [authoring-cycle.md](authoring-cycle.md) — general 5-step authoring procedure; shell-specific rules layer on top
 - [api-contract.md](api-contract.md) — prop naming, reflection policy
-- [css-patterns.md](css-patterns.md) — two-block `@scope`, variants vs modes
+- [css-patterns.md](css-patterns.md) — two-block `@scope`, variants vs modes; §Region elements never self-style (ADR-0105) — a shell that hosts `<header-ui>`/`<section-ui>`/`<footer-ui>` region children (e.g. a bespoke `<X-header>` wrapping one) owns their `@scope` layout the same way `page-ui`/`card-ui`/`drawer-ui`/`modal-ui` do
 - [lifecycle-patterns.md](lifecycle-patterns.md) — teardown patterns; the cleanup-closure pile and document-listener rules above layer on top
 - [token-contract.md](token-contract.md) — zero-raw-color + L3 alias rules apply identically to shells
 - [module-promotion.md](module-promotion.md) — the _different_ activity of lifting a cross-cluster reusable element (theme panel, command palette) into a shared module

package/skills/primitive-authoring/references/token-contract.md

@@ -36,6 +36,23 @@ Every component's `.css` file must follow the **two-block @scope** pattern:
 }
 ```
 
+### `@scope` donor selectors must be tag-independent when a component can swap its own rendered tag (ADR-0102, 2026-09-01)
+
+A `@scope (my-component-ui)` donor selector matches by **literal tag
+name**. That's a live gap for any component whose own contract lets it
+render as a different tag than its own custom-element name — `text-ui`
+already did this coincidentally (`variant="body"` → `<p>`,
+`variant="caption"` → `<small>`), relying on ambient/bare-tag styling
+rather than the component's own `[variant]` rules. ADR-0102 (`text-ui`'s
+`level` prop, promoting the element to a real `<h1>`-`<h6>`) made this a
+first-class case, requiring the donor selector to stay tag-independent —
+e.g. `@scope (text-ui, [data-text])` with the renderer stamping a stable
+marker attribute on every such element regardless of the resolved tag —
+so a promoted `<h2 level="2" variant="heading">` keeps its component
+styling instead of silently falling back to bare-tag `:where(hN)`
+defaults elsewhere in the cascade. Any component that can render under a
+tag other than its own name needs the same tag-independent scope check.
+
 ## Hard rules
 
 1. **Zero raw color values** anywhere in component CSS
@@ -139,7 +156,8 @@ mechanics; never work from this summary alone):
   in a component yaml, check it against the spec's attribute inventory; the
   only sanctioned collisions live in the spec's §11 Global-Attribute Exemption
   List (first entries: `swatch-ui[color]` / `noodles-ui[color]`, ADR-0054;
-  granted since: `qr-code-ui[color]` / `icon-ui[weight]`, ADR-0070).
+  granted since: `qr-code-ui[color]` / `icon-ui[weight]`, ADR-0070;
+  `badge-ui[weight]` → `icon-ui[weight]`, ADR-0100).
 
 Beyond the global grammar, ADR-0063
 (`docs/ops/adr/adr-0063-attribute-grammar-addendum.md`) ratifies seven

package/skills/primitive-authoring/references/yaml-contract.md

@@ -401,6 +401,22 @@ already has). As of this writing `deriveProps()` still synthesizes only the
 three props above and `catalog-validator.js` has no trait-name check —
 gh#2513 tracks the build.
 
+### Sentinel-0 defaults and tag-promoting props (ADR-0102, 2026-09-01)
+
+Not every escape hatch belongs on `CatalogComponentCommon` — a prop scoped
+to one component's own semantics stays on that component's own yaml, even
+when it changes the rendered tag. `text-ui`'s `level` (integer 0-6,
+default `0`) is the worked example: `0` is the sentinel for "no
+promotion, current behavior" — the same `0 = off` convention `text-ui`'s
+own `lines` prop already used (`lines: 0` = no clamp) — and `1`-`6`
+promotes the rendered element to a real native `<h1>`-`<h6>`, independent
+of `variant` (which stays presentational-only: typography tokens, never a
+tag). `deriveProps()` needs no change for this — a per-sidecar prop like
+`level` already flows into the generated catalog schema generically; only
+a `CatalogComponentCommon` universal (`slot`/`hidden`/`ariaLive`/`traits`,
+above) needs a wire-schema edit. See ADR-0102 for the full contract
+(renderer branch, dead-code removal, non-goals).
+
 ### `required: true` field
 
 **When to use**: only for props where omitting them makes the component meaningless or inaccessible.