@adia-ai/web-components 0.8.43 → 0.8.45

package/components/text/text.a2ui.json

@@ -96,10 +96,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/components/text/text.d.ts

@@ -25,13 +25,13 @@ export type UITextVariant =
   | 'display'
   /** Annotation under a primary line — smaller + muted. Use for image captions, footnotes. */
   | 'caption'
-  /** Form-control label (above an `<input-ui>` / `<select-ui>` etc). UI-sized + medium-weight. Use for field labels bound to form controls. */
+  /** 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. */
   | 'label'
-  /** Eyebrow text above a `title`. UPPERCASE + small + tracking. Use for content eyebrows (NOT form labels — use `label` for those). */
+  /** 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). */
   | 'kicker'
   /** Sub-title under a `title`. One-line lead, slightly larger than body. Use for the lead sentence after a title. */
   | 'deck'
-  /** Inline form-group / navlist heading (visual rank H4). Small-cap. Use for form group labels, nav list headings. */
+  /** 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. */
   | 'section'
   /** Numeric KPI / big-number stat. Bold + large. Use for dashboard metric numbers. */
   | 'metric'
@@ -47,6 +47,8 @@ export class UIText extends UIElement {
   size: 'sm' | 'md' | 'lg';
   /** When true, applies stronger emphasis (heavier weight + accent color). Styled via :scope[strong] in text.css. Use instead of variant=heading when you want a single emphasized word inline in body copy. */
   strong: boolean;
+  /** Override text alignment. Note: text-ui defaults to display:inline, so this only takes effect when text-ui is block-like (wrapping or parent display:block/grid). Added v0.6.18 (FB-10). Converged onto the global Enum·semantic `[text-align]` physical vocabulary (gh#1335) — `start`/`end` renamed to `left`/`right`; `justify` kept (a genuine physical alignment value, now also supported by the global grammar). */
+  textAlign: 'left' | 'center' | 'right' | 'justify';
   /** Display text content. The main payload field for Text components extracted from HTML. */
   textContent: string;
   /** Single-line truncation with ellipsis. Ignored when `lines` is set. */

package/components/text/text.yaml

@@ -103,10 +103,10 @@ props:
       title: Page title (visual rank H1). Largest under display. Use at the top of an authoritative page or dialog.
       heading: Major page heading (visual rank H2). 16-18px / bold. Use for major sub-section dividers.
       subsection: Sub-landmark within a section (visual rank H3). 14px / semibold. Use for card titles within a section.
-      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.
       caption: Annotation under a primary line — smaller + muted. Use for image captions, footnotes.
-      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. 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.
+      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).
       deck: Sub-title under a `title`. One-line lead, slightly larger than body. Use for the lead sentence after a title.
       metric: Numeric KPI / big-number stat. Bold + large. Use for dashboard metric numbers.
       code: Inline monospace code reference. Use for inline code within prose.

package/components/textarea/textarea.class.js

@@ -18,6 +18,7 @@
  */
 
 import { UIFormElement } from '../../core/form.js';
+import { syncAutoAriaLabel } from '../../core/a11y.js';
 
 export class UITextarea extends UIFormElement {
   static labelDeprecated = false;  // §170 (v0.5.4): label is first-class per textarea.yaml
@@ -32,6 +33,10 @@ export class UITextarea extends UIFormElement {
   static template = () => null;
 
   #textEl = null;
+  // gh#1647: tracks the aria-label VALUE this element itself last derived
+  // from `label`/`placeholder` (undefined when none) — value-tracking
+  // guard ported from tag.class.js/select.class.js (gh#1644/#1646).
+  #lastAutoAriaLabel = undefined;
 
   connected() {
     super.connected();
@@ -82,7 +87,10 @@ export class UITextarea extends UIFormElement {
     const label = this.querySelector('[slot="label"]');
     if (label && this.label) label.setAttribute('label', this.label);
 
-    this.setAttribute('aria-label', this.label || this.placeholder || '');
+    // A11y (gh#1647): never clobber a consumer's own aria-label
+    // (value-tracking guard, gh#1644/#1646).
+    const ariaSource = this.label || this.placeholder || '';
+    this.#lastAutoAriaLabel = syncAutoAriaLabel(this, this.#lastAutoAriaLabel, ariaSource);
   }
 
   #onInput = () => {

package/components/tour/tour.d.ts

@@ -43,10 +43,20 @@ export class UITour extends UIElement {
 the spotlight + popover; setting to `false` tears down.
  */
   active: boolean;
+  /** Start the tour automatically when the element connects. Useful for
+first-run flows gated by a storage flag on the consumer side.
+ */
+  autoStart: boolean;
   /** Current step index (0-based). Setting this property advances the
 tour to that step (updating spotlight + popover position).
  */
   step: number;
+  /** Optional localStorage key. When set, the tour records its
+completion state (`"done"`) to that key on finish/skip — and
+refuses to auto-start on subsequent loads if the key is "done".
+Useful for "show this tour once per user" flows.
+ */
+  storageKey: string;
 
   addEventListener(type: 'tour-finish', listener: (ev: TourFinishEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'tour-skip', listener: (ev: TourSkipEvent) => unknown, options?: boolean | AddEventListenerOptions): void;

package/core/a11y.d.ts

@@ -0,0 +1,22 @@
+/**
+ * core/a11y.js — shared accessible-name authorship guard.
+ *
+ * See the runtime module's own JSDoc for the full contract and the usage
+ * pattern (gh#1644 / gh#1646 / gh#1647).
+ */
+
+/**
+ * Reconcile an auto-derived `aria-label` against a possible consumer
+ * override, using a value-tracking guard rather than a plain boolean flag.
+ *
+ * @param el - the host element.
+ * @param lastAuto - the value this component wrote last time (`undefined`
+ *   = no active auto-derived value, either never set or consumer-owned).
+ * @param source - the label this render would derive; falsy = no auto name.
+ * @returns the new `lastAuto` to store back in the caller's own field.
+ */
+export function syncAutoAriaLabel(
+  el: HTMLElement,
+  lastAuto: string | undefined,
+  source: string,
+): string | undefined;

package/core/a11y.js

@@ -0,0 +1,64 @@
+/**
+ * core/a11y.js — shared accessible-name authorship guard.
+ *
+ * Ports the value-tracking guard proven on `tag.class.js`'s
+ * `#syncAccessibleName` (gh#1644 / PR #1645) and `select.class.js`'s
+ * `labeledElsewhere` variant (gh#1646 / PR #1648) into one shared helper,
+ * so every primitive that derives its own `aria-label` doesn't need to
+ * reimplement the compare-against-what-we-last-wrote logic (gh#1647).
+ *
+ * A plain boolean "did we ever set it" flag isn't enough: a consumer can
+ * overwrite `aria-label` directly via `setAttribute` at any point BETWEEN
+ * renders, bypassing the flag entirely. This guard instead compares the
+ * CURRENT attribute value against the value THIS component last wrote —
+ * a mismatch means a consumer has taken ownership, and auto-derivation
+ * stops until the source value the caller passes in changes again.
+ *
+ * Per-component gating (e.g. select-ui's `labeledElsewhere` — don't
+ * auto-name when a visible `label` or `aria-labelledby` already names the
+ * element, or don't auto-name off a default/placeholder-only value) is
+ * the CALLER's job: resolve the source string to '' when no auto name
+ * should apply this render, and pass the real derived string otherwise.
+ * This helper only ever reconciles "what we'd write" against "what's
+ * there now, and did we write it" — it carries no per-component policy.
+ *
+ * Usage (per component):
+ *
+ *   import { syncAutoAriaLabel } from '../../core/a11y.js';
+ *
+ *   #lastAutoAriaLabel = undefined;
+ *
+ *   #syncAccessibleName() {
+ *     const source = <derive the label this render, or '' for none>;
+ *     this.#lastAutoAriaLabel = syncAutoAriaLabel(this, this.#lastAutoAriaLabel, source);
+ *   }
+ *
+ * Call `#syncAccessibleName()` early in `render()`, before any other
+ * aria-* bookkeeping that might read the (possibly just-changed)
+ * `aria-label` attribute.
+ *
+ * @param {HTMLElement} el
+ * @param {string | undefined} lastAuto - the value this component wrote
+ *   last time (`undefined` = the component has never derived a name for
+ *   the CURRENT attribute value, either because it never has, or because
+ *   a consumer has since taken ownership).
+ * @param {string} source - the label the component would derive right
+ *   now. Empty string (or any other falsy value) means "no auto name" —
+ *   any auto-set label is removed.
+ * @returns {string | undefined} the new `lastAuto` value — store this
+ *   back into the caller's own private field.
+ */
+export function syncAutoAriaLabel(el, lastAuto, source) {
+  const current = el.getAttribute('aria-label');
+  if (lastAuto !== undefined && current !== lastAuto) {
+    lastAuto = undefined; // a consumer took ownership between renders
+  }
+  const authored = current !== null && lastAuto === undefined;
+  if (authored) return lastAuto;
+  if (source) {
+    if (current !== source) el.setAttribute('aria-label', source);
+    return source;
+  }
+  if (current !== null) el.removeAttribute('aria-label');
+  return undefined;
+}

package/core/anchor.js

@@ -127,11 +127,15 @@ function anchorNative(anchor, popover, { placement, gap, matchWidth }) {
   };
 }
 
-// Resolve a --popover-max-height declaration to px. The convention's consumers
-// declare px (JS-measured caps) or rem (stylesheet defaults); anything else
-// (calc, var chains, empty) returns NaN and the caller falls back to content
-// height. Kept deliberately narrow — this feeds a fit DECISION, not layout.
-function resolveLengthPx(raw) {
+// Resolve a px/rem CSS custom-property declaration to px. Originally scoped
+// to --popover-max-height (consumers declare px, JS-measured caps, or rem,
+// stylesheet defaults); exported (ADR-0076, table-toolbar-ui's stage-
+// resolution breakpoints, PLAN step 7) since a second, unrelated consumer
+// needs the identical px/rem-only resolution — anything else (calc, var
+// chains, empty) returns NaN and the caller falls back to its own default.
+// Kept deliberately narrow — this feeds a classification DECISION, not
+// layout, in both consumers.
+export function resolveLengthPx(raw) {
   const v = String(raw || '').trim();
   if (!v) return NaN;
   const m = /^(-?\d+(?:\.\d+)?)(px|rem)$/.exec(v);

package/core/data-stream.js

@@ -37,6 +37,14 @@
  *   stream-load   — first signal value received for this element
  *   stream-update — each subsequent value, detail.data = the new value
  *   stream-error  — transport-level error, detail.error = message
+ *
+ * Opting out (gh#1760):
+ *   `data-stream-managed="false"` tells the document-level observer to
+ *   never claim this element, even though it carries `data-stream-src`.
+ *   For elements that own their own imperative fetch (e.g. the billing
+ *   composites' `refresh()`) and must not also be claimed by this module —
+ *   never mix an imperative fetch with an unmanaged `data-stream-src` on
+ *   the same element (data-stream-protocol.md §10.1).
  */
 
 import { signal, effect, untracked } from './signals.js';
@@ -54,6 +62,11 @@ const ATTRS = {
   merge:     'data-stream-merge',
   format:    'data-stream-format',
   id:        'data-stream-id',
+  // gh#1760 — opt-out for elements that carry `data-stream-src` but manage
+  // their own fetch (e.g. the billing composites' hand-rolled `refresh()`).
+  // `"false"` tells the document-level observer to never claim this element,
+  // so exactly one owner (the element's own imperative fetch) ever runs.
+  managed:   'data-stream-managed',
 };
 
 const STREAMS = new Map();           /* streamId → { signal, refs, transport, opts } */
@@ -386,6 +399,7 @@ function applyData(el, raw, opts) {
 export function start(el) {
   stop(el);
   if (!el.isConnected) return;
+  if (attr(el, 'managed') === 'false') return; // gh#1760 — self-managed opt-out
   const src = attr(el, 'src');
   if (!src) return;
 
@@ -442,7 +456,8 @@ export function stop(el) {
 const ATTR_FILTER = Object.values(ATTRS);
 
 function isStreamingEl(node) {
-  return node && node.nodeType === 1 && node.hasAttribute && node.hasAttribute(ATTRS.src);
+  return !!(node && node.nodeType === 1 && node.hasAttribute && node.hasAttribute(ATTRS.src)
+    && node.getAttribute(ATTRS.managed) !== 'false');
 }
 
 function visitSubtree(root, fn) {
@@ -476,11 +491,31 @@ const observer = typeof MutationObserver !== 'undefined'
 
 function bootstrap() {
   if (typeof document === 'undefined') return;
+  // Register the observer synchronously — no live mutation is missed.
   observer?.observe(document.documentElement, {
     childList: true, subtree: true,
     attributes: true, attributeFilter: ATTR_FILTER,
   });
-  document.querySelectorAll(`[${ATTRS.src}]`).forEach(start);
+  // gh#1760 — defer the INITIAL sweep of already-present markup by one
+  // microtask. Without this, a page whose entry module imports the core
+  // barrel (this module) BEFORE a self-managed composite's own module
+  // (which sets `data-stream-managed="false"` synchronously from its
+  // upgrade-triggered `connectedCallback`) races: this sweep would claim
+  // pre-existing SSR markup before the composite ever gets a chance to
+  // opt out. Deferring to a microtask lets the rest of the SAME
+  // synchronous module-evaluation phase — including every sibling
+  // module's own top-level side effects — finish first, so by the time
+  // this sweep runs, every already-loaded composite has already set its
+  // marker. (A composite loaded asynchronously — a dynamic `import()` —
+  // after this microtask has already fired is not covered by this
+  // deferral alone; its own `connected()` marker-set plus the observer's
+  // live attribute-mutation handling still tears down a wrongly-started
+  // stream, bounding the damage to at most one extra fetch.)
+  queueMicrotask(() => {
+    document.querySelectorAll(`[${ATTRS.src}]`).forEach((el) => {
+      if (isStreamingEl(el)) start(el);
+    });
+  });
 }
 
 if (typeof document !== 'undefined') {

package/core/element.js

@@ -91,7 +91,7 @@ function reflect(el, a, v, t) {
 }
 
 const parseAttr = (v, t) =>
-  t === Boolean ? v !== null : t === Number ? (v === null ? null : +v) : v;
+  t === Boolean ? v !== null && v !== 'false' : t === Number ? (v === null ? null : +v) : v;
 
 function adoptStyles(ctor) {
   if (Object.hasOwn(ctor, '_sa')) return;

package/core/index.d.ts

@@ -9,6 +9,7 @@ export * from './template.js';
 export * from './element.js';
 export * from './form.js';
 export * from './register.js';
+export * from './store.js';
 // Mirror the explicit re-export in core/index.js — `streams` + `whenStream`
 // (the public surface of the data-stream attribute-driven ingestion module).
 // `export *` from data-stream.js would also expose internals; keep the

package/core/index.js

@@ -18,6 +18,7 @@ export * from './signals.js';
 export * from './template.js';
 export * from './register.js';
 export * from './controller.js';
+export * from './store.js';
 export * from './provider.js';
 export * from './anchor.js';
 export * from './icons.js';

package/core/provider.d.ts

@@ -1,7 +1,8 @@
 /**
  * `<router-ui>` provider — declarative + imperative client-side
- * routing built on {@link RouteController} (re-declared here for
- * historical reasons; the canonical export lives in `core/controller.js`).
+ * routing built on {@link RouteController} (re-exported here for
+ * back-compat — gh#1766 — the canonical implementation lives in
+ * `core/controller.js`).
  *
  * Two consumer paths:
  *
@@ -25,22 +26,17 @@
  */
 
 import { UIElement } from './element.js';
-import type { Route, RouteCommands, RouteState, ControllerSchema, RouteControllerOptions } from './controller.js';
-import { BaseController } from './controller.js';
+import type { Route } from './controller.js';
+import { RouteController } from './controller.js';
 
 /**
- * Routing-state controller. Re-declared from `core/controller.js` for
- * historical compatibility — both files define the same class shape;
- * consumers can import either. New code should prefer
+ * Routing-state controller, re-exported from `core/controller.js`
+ * (gh#1766) for back-compat — consumers can import either path.
+ * New code should prefer
  * `import { RouteController } from '@adia-ai/web-components/core/controller'`
  * for the canonical path.
  */
-export class RouteController extends BaseController {
-  static schema: ControllerSchema;
-  constructor(options?: RouteControllerOptions);
-  getState(): RouteState;
-  commands: RouteCommands;
-}
+export { RouteController };
 
 /**
  * Optional async transform applied to fetched route content before

package/core/provider.js

@@ -1,8 +1,10 @@
 /**
  * AdiaUI Router — Self-contained vanilla JS bundle.
- * Includes: RouteController + router-ui component.
+ * Includes: router-ui component; re-exports `RouteController` for
+ * back-compat (gh#1766 — the canonical definition lives in
+ * `core/controller.js`, alongside its `BaseController` superclass).
  *
- * Depends on: core.js (UIElement), controllers.js (BaseController)
+ * Depends on: element.js (UIElement), controller.js (RouteController)
  *
  * Usage:
  *   import { UIElement } from './core.js';
@@ -24,7 +26,7 @@
 
 import { UIElement } from './element.js';
 import { defineIfFree } from './register.js';
-import { BaseController } from './controller.js';
+import { RouteController } from './controller.js';
 import { viewTransition } from '../traits/view-transition/view-transition.js';
 
 // ═══════════════════════════════════════════════════════════════
@@ -46,118 +48,12 @@ class UIProvider extends UIElement {
 }
 
 // ═══════════════════════════════════════════════════════════════
-// ROUTE CONTROLLER
+// ROUTE CONTROLLER — re-exported for back-compat (gh#1766); the
+// canonical definition lives in `core/controller.js`, which is
+// where `BaseController` (its own superclass) already lives.
 // ═══════════════════════════════════════════════════════════════
 
-export class RouteController extends BaseController {
-  static schema = {
-    name: 'route',
-    state: { path: 'string', params: 'object', route: 'object', previous: 'string' },
-    commands: ['navigate', 'replace', 'back', 'forward', 'setRoutes'],
-    attributes: ['data-route-path'],
-  };
-
-  #routes = [];
-  #path = '';
-  #previous = '';
-  #params = {};
-  #route = null;
-  #historySync = true;
-  #boundPopState = null;
-
-  constructor({ routes = [], initial, historySync = true } = {}) {
-    super();
-    this.#routes = routes;
-    this.#historySync = historySync;
-    this.#path = initial ?? location.pathname;
-    this.#match();
-  }
-
-  getState() {
-    return {
-      path: this.#path,
-      params: { ...this.#params },
-      route: this.#route,
-      previous: this.#previous,
-    };
-  }
-
-  reflect() {
-    const host = this.host;
-    if (!host) return;
-    host.setAttribute('data-route-path', this.#path);
-  }
-
-  onConnect(host) {
-    if (this.#historySync) {
-      this.#boundPopState = () => {
-        this.#previous = this.#path;
-        this.#path = location.pathname;
-        this.#match();
-        this.notify();
-      };
-      window.addEventListener('popstate', this.#boundPopState);
-    }
-  }
-
-  onDisconnect() {
-    if (this.#boundPopState) {
-      window.removeEventListener('popstate', this.#boundPopState);
-      this.#boundPopState = null;
-    }
-  }
-
-  #match() {
-    this.#params = {};
-    this.#route = null;
-    for (const route of this.#routes) {
-      const match = this.#matchPath(route.path, this.#path);
-      if (match) {
-        this.#params = match.params;
-        this.#route = route;
-        return;
-      }
-    }
-  }
-
-  #matchPath(pattern, path) {
-    const patternParts = pattern.split('/').filter(Boolean);
-    const pathParts = path.split('/').filter(Boolean);
-    if (!pattern.includes(':')) return pattern === path ? { params: {} } : null;
-    if (patternParts.length !== pathParts.length) return null;
-    const params = {};
-    for (let i = 0; i < patternParts.length; i++) {
-      if (patternParts[i].startsWith(':')) params[patternParts[i].slice(1)] = pathParts[i];
-      else if (patternParts[i] !== pathParts[i]) return null;
-    }
-    return { params };
-  }
-
-  commands = {
-    navigate: (path) => {
-      if (path === this.#path) return;
-      this.#previous = this.#path;
-      this.#path = path;
-      this.#match();
-      if (this.#historySync) history.pushState(null, '', path);
-      this.notify();
-    },
-    replace: (path) => {
-      this.#previous = this.#path;
-      this.#path = path;
-      this.#match();
-      if (this.#historySync) history.replaceState(null, '', path);
-      this.notify();
-    },
-    back: () => { if (this.#historySync) history.back(); },
-    forward: () => { if (this.#historySync) history.forward(); },
-    setRoutes: (routes) => {
-      this.#routes = routes;
-      this.#match();
-      this.notify();
-    },
-  };
-}
+export { RouteController };
 
 // ═══════════════════════════════════════════════════════════════
 // ROUTER-UI — content fragment renderer

package/core/store.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Shared app store — the blessed R2 primitive. Signal-backed, with a
+ * Set-of-listeners-compatible `subscribe()` channel for imperative
+ * (non-`effect()`) consumers.
+ *
+ * @see ./store.js (runtime SoT)
+ * @see ../USAGE.md
+ */
+
+/**
+ * A `signal()`-backed store. `.value` composes with `computed()`/`effect()`
+ * exactly like a plain signal; `subscribe()` is the extra imperative
+ * channel the seven hand-rolled app-layer stores already share (see
+ * `store.js`'s header for the full rationale and the rejected
+ * BaseController alternative).
+ */
+export interface Store<T> {
+  /** Tracked read/write, same semantics as `Signal<T>.value`. */
+  value: T;
+  /** Read without subscribing the surrounding `effect()`. */
+  peek(): T;
+  /**
+   * Subscribe to changes. `cb` receives the new value on every write that
+   * doesn't fail the `Object.is` no-notify guard. Returns an unsubscribe
+   * function — safe to call more than once. Compatible with
+   * `UIElement`'s `controller` setter (`element.controller = store`).
+   */
+  subscribe(cb: (value: T) => void): () => void;
+}
+
+/**
+ * Create a shared app store.
+ *
+ * @example
+ *   const count = createStore(0);
+ *   const stop = count.subscribe((v) => console.log('count is', v));
+ *   count.value = 1;   // logs "count is 1"
+ *   count.value = 1;   // no-op — Object.is guard, no log
+ *   stop();
+ *
+ * @example Controller-setter interop
+ *   class MyEl extends UIElement {}
+ *   const el = new MyEl();
+ *   el.controller = createStore({ ready: false }); // re-renders on change
+ */
+export function createStore<T>(initial: T): Store<T>;

package/core/store.js

@@ -0,0 +1,89 @@
+/**
+ * AdiaUI shared app store — the blessed R2 primitive.
+ *
+ * A signal-backed replacement for the Set-of-listeners pub/sub pattern
+ * hand-rolled across the app layer: plan-store, data-client, patient-visit
+ * record, persona store, task-service, a2ui BaseController, a2ui Surface
+ * watchers (reactivity review, .claude/docs/reports/2026-08-20-reactivity-
+ * review/03-app-layer-stores.md §4). Doctrine's pattern menu row 1 says
+ * reactive state -> signals; `createStore` is `signal()` plus the one thing
+ * those seven stores actually needed on top of it: an imperative
+ * `subscribe(cb) -> unsubscribe` channel for consumers that are closures or
+ * classes rather than `effect()` bodies.
+ *
+ * `.value` reads/writes pass straight through to a real `signal()`, so a
+ * store composes with `computed()`/`effect()` exactly like any other signal
+ * (tracked reads, `Object.is` no-notify, microtask-batched effect re-runs).
+ * `subscribe()` is the separate, synchronous, imperative channel the seven
+ * hand-rolled stores already share — same shape, so migrating one onto this
+ * primitive is a mechanical swap (opportunistic, later, per store; this
+ * primitive lands with NO migration).
+ *
+ * Interops with `UIElement`'s `controller` setter (`core/element.js`)
+ * out of the box: `element.controller = store` wires `store.subscribe(fn)`
+ * into the element's own render-trigger machinery — the setter calls
+ * `c.connect?.(this)` / `c.subscribe?.(...)` / `c.disconnect?.(this)`, all
+ * optional-chained, and `subscribe()` alone satisfies that contract.
+ *
+ * Rejected alternative: promoting/absorbing `BaseController`
+ * (`core/controller.js`) into this role, per the reactivity review's F5.
+ * BaseController's `connect()` bakes in schema/`getState()` validation
+ * (dev-warns without a static `schema`, dev-errors without an overridden
+ * `getState()`) that exists to serve DOM-reflecting UI controllers
+ * (`RouteController`'s attributes/commands surface) — semantics a plain
+ * data store has no use for and would either have to satisfy with a dummy
+ * schema or suppress. The one thing BaseController actually offers this
+ * role — the `subscribe(fn) -> unsubscribe` shape the controller setter
+ * expects — costs nothing to reimplement directly on `signal()`, and doing
+ * so keeps the store from inheriting a validation path built for a
+ * different kind of thing. BaseController stays as-is; still one consumer
+ * (`RouteController` / `<router-ui>`), still F5's to resolve separately.
+ *
+ * @see ../USAGE.md
+ * @see ./element.js (the `controller` setter this interops with)
+ * @see ./controller.js (BaseController — the rejected alternative above)
+ */
+
+import { signal } from './signals.js';
+
+export function createStore(initial) {
+  const s = signal(initial);
+  const listeners = new Set();
+
+  return {
+    get value() {
+      return s.value;
+    },
+    set value(next) {
+      // Object.is no-notify guard — matches persona-store's proven
+      // behavior (packages/llm/persona/src/store.ts) and the underlying
+      // signal's own equality cutoff. Checked here, not inferred from
+      // signal()'s silent no-op, so an identical write never reaches
+      // `listeners` either.
+      const changed = !Object.is(s.peek(), next);
+      s.value = next;
+      if (changed) {
+        // Pass the captured `next`, never re-read `s.peek()` here — a
+        // listener that re-entrantly writes `store.value` during this
+        // loop would otherwise make every later listener observe THAT
+        // write's value instead of this one's, silently skipping the
+        // value this write actually delivered.
+        for (const cb of listeners) cb(next);
+      }
+    },
+    /** Read without subscribing the surrounding `effect()`. */
+    peek() {
+      return s.peek();
+    },
+    /**
+     * Set-of-listeners-compatible subscribe. `cb` receives the new value;
+     * callers that only care that *something* changed (the
+     * `UIElement.controller` setter among them) simply ignore the
+     * argument. Returns an unsubscribe function.
+     */
+    subscribe(cb) {
+      listeners.add(cb);
+      return () => listeners.delete(cb);
+    },
+  };
+}