@adia-ai/web-components 0.8.44 → 0.8.45

package/components/table-toolbar/table-toolbar.class.js

@@ -29,11 +29,22 @@
  * Popovers use the platform Popover API + core/anchor.js, the same primitives
  * that menu-ui / popover-ui / toolbar-ui already use in this package.
  *
- * State flow:
- *   search        → table.search       (string property)
- *   filters       → table.setFilter()  (per-key)
- *   sort          → simulated click on table's [data-sort-key] header
- *   column hidden → table.columns =    (clone with hidden flag flipped)
+ * State flow — events-only interaction contract (gh#1764/#1780, ADR-0079;
+ * mirrors chart-legend-ui↔chart-ui's own bubbling-CustomEvent model). The
+ * toolbar never writes a property or calls a method on the bound table
+ * directly — every command is a `toolbar-*` CustomEvent dispatched AT the
+ * resolved target, which table.class.js listens for in its own
+ * connected()/disconnected() and applies via its existing public surface:
+ *   search        → `toolbar-search`        { value }          → table.search =
+ *   filters       → `toolbar-filter-set`    { key, value, op }  → table.setFilter()
+ *   filters clear → `toolbar-filter-clear`  {}                  → table.clearFilters()
+ *   sort          → simulated click on table's [data-sort-key] header (already
+ *                   event-shaped — a real DOM event dispatched at the target,
+ *                   not a property write; left as-is, see gh#1780's PR notes)
+ *   column hidden → `toolbar-columns-set`   { columns }         → table.columns =
+ *   page size     → `toolbar-paginate`      { pageSize }        → table.paginate =
+ * The table→toolbar direction (`sort`, `filter-change` listened on #target)
+ * was already events-only and is unchanged.
  */
 
 import { UIElement } from '../../core/element.js';
@@ -846,11 +857,16 @@ export class UITableToolbar extends UIElement {
   #onPageSizeChange = (e) => {
     const pageSize = Number(e.detail?.value ?? this.querySelector(':scope [data-page-size]')?.value) || 0;
     this.pageSize = pageSize;
-    // Applied directly to the bound table's own [paginate] (rows-per-page)
-    // prop — the same "mirror to URL/analytics via the event, but the
-    // toolbar already wires the change into the target" pattern
-    // columns-change/sort-change already use.
-    if (this.#target) this.#target.paginate = pageSize;
+    // gh#1764/#1780 (events-only interaction contract, ADR-0079) — the
+    // bound table applies its own [paginate] through the `toolbar-paginate`
+    // command event rather than a direct property write; table.class.js
+    // listens for it in connected() and sets `this.paginate` itself.
+    if (this.#target) {
+      this.#target.dispatchEvent(new CustomEvent('toolbar-paginate', {
+        bubbles: true,
+        detail: { pageSize },
+      }));
+    }
     this.dispatchEvent(new CustomEvent('page-size-change', {
       bubbles: true,
       detail: { pageSize },
@@ -902,7 +918,15 @@ export class UITableToolbar extends UIElement {
 
   #onSearch = (e) => {
     const value = e.detail?.value ?? '';
-    if (this.#target) this.#target.search = value;
+    // gh#1764/#1780 (events-only interaction contract, ADR-0079) —
+    // `toolbar-search` replaces the direct `.search =` write; table.class.js
+    // listens for it in connected() and sets `this.search` itself.
+    if (this.#target) {
+      this.#target.dispatchEvent(new CustomEvent('toolbar-search', {
+        bubbles: true,
+        detail: { value },
+      }));
+    }
     this.dispatchEvent(new CustomEvent('search', {
       bubbles: true,
       detail: { value },
@@ -1044,8 +1068,14 @@ export class UITableToolbar extends UIElement {
         }
         sel.addEventListener('change', () => {
           const v = sel.value || '';
-          if (v) target.setFilter(col.key, v, 'select');
-          else target.setFilter(col.key, null);
+          // gh#1764/#1780 (events-only interaction contract, ADR-0079) —
+          // `toolbar-filter-set` replaces the direct target.setFilter()
+          // call; table.class.js applies it synchronously in its own
+          // listener, so `target.filters` below already reflects it.
+          target.dispatchEvent(new CustomEvent('toolbar-filter-set', {
+            bubbles: true,
+            detail: { key: col.key, value: v || null, op: 'select' },
+          }));
           this.dispatchEvent(new CustomEvent('filter-change', {
             bubbles: true,
             detail: { filters: target.filters },
@@ -1061,8 +1091,12 @@ export class UITableToolbar extends UIElement {
         if (current?.op === 'contains') input.value = current.value ?? '';
         input.addEventListener('input', () => {
           const v = input.value;
-          if (v) target.setFilter(col.key, v, 'contains');
-          else target.setFilter(col.key, null);
+          // gh#1764/#1780 (events-only interaction contract, ADR-0079) —
+          // see the select-filter handler above for the same normalization.
+          target.dispatchEvent(new CustomEvent('toolbar-filter-set', {
+            bubbles: true,
+            detail: { key: col.key, value: v || null, op: 'contains' },
+          }));
           this.dispatchEvent(new CustomEvent('filter-change', {
             bubbles: true,
             detail: { filters: target.filters },
@@ -1078,7 +1112,11 @@ export class UITableToolbar extends UIElement {
 
     if (Object.keys(filters).length) {
       const clear = this.#mkPopoverAction('Clear all filters', () => {
-        target.clearFilters();
+        // gh#1764/#1780 (events-only interaction contract, ADR-0079) —
+        // `toolbar-filter-clear` replaces the direct target.clearFilters()
+        // call; table.class.js applies it synchronously in its own
+        // listener before #refreshFilterPanel() re-reads target.filters.
+        target.dispatchEvent(new CustomEvent('toolbar-filter-clear', { bubbles: true }));
         this.dispatchEvent(new CustomEvent('filter-change', {
           bubbles: true,
           detail: { filters: {} },
@@ -1227,7 +1265,13 @@ export class UITableToolbar extends UIElement {
         const next = target.columns.map((c) => (
           c.key === col.key ? { ...c, hidden: !check.hasAttribute('checked') } : { ...c }
         ));
-        target.columns = next;
+        // gh#1764/#1780 (events-only interaction contract, ADR-0079) —
+        // `toolbar-columns-set` replaces the direct target.columns= write;
+        // table.class.js applies it synchronously in its own listener.
+        target.dispatchEvent(new CustomEvent('toolbar-columns-set', {
+          bubbles: true,
+          detail: { columns: next },
+        }));
         this.dispatchEvent(new CustomEvent('columns-change', {
           bubbles: true,
           detail: { hiddenColumns: next.filter((c) => c.hidden).map((c) => c.key) },

package/components/table-toolbar/table-toolbar.css

@@ -163,6 +163,40 @@
     width: var(--button-height);
   }
 
+  /* ═══════ Actions-leading icon-only reduction ═══════ (gh#1748) — extends
+     the SAME icon-only collapse above to a plain <button-ui> a consumer
+     slots into [slot="actions-leading"] (gh#1649, e.g. the app-owned
+     Filter/Columns triggers on the ratified adiav2 row), so it reads as
+     part of the same toolbar affordance cluster rather than staying
+     full-width while its native siblings compact. A separate rule block
+     (rather than folding into [data-toolbar-btn]'s own selector list above)
+     keeps that block's literal text byte-identical for its own
+     source-assertion tests. Same breakpoint/pin pair, same
+     aria-label-survives guarantee (button-ui's own REQ-X-001 stamp,
+     unaffected here) — light-DOM real insertion point (no shadow
+     boundary), so a plain descendant tag selector reaches it directly, no
+     `::slotted()` needed. Literal `40rem` bound to
+     --table-toolbar-bp-icon-only's default, same as the native block. */
+  @container table-toolbar (max-width: 40rem) {
+    :scope:is(:not([stage]), [stage=""]) [data-actions-leading] button-ui[text]::after {
+      content: none;
+    }
+    :scope:is(:not([stage]), [stage=""]) [data-actions-leading] button-ui {
+      --button-px: 0;
+
+      width: var(--button-height);
+    }
+  }
+
+  :scope:is([stage="icon-only"], [stage="overflow"]) [data-actions-leading] button-ui[text]::after {
+    content: none;
+  }
+  :scope:is([stage="icon-only"], [stage="overflow"]) [data-actions-leading] button-ui {
+    --button-px: 0;
+
+    width: var(--button-height);
+  }
+
   /* ═══════ Range-summary conditional compact/hide ═══════ (ADR-0076
      REQ-S-003, step 4) — at the SAME icon-only breakpoint as above:
        - [data-page-size] present AND visible (no [hidden]) → its own

package/components/table-toolbar/table-toolbar.d.ts

@@ -17,6 +17,11 @@ export type TableToolbarFilterChangeEvent = CustomEvent<unknown>;
 export type TableToolbarPageSizeChangeEvent = CustomEvent<unknown>;
 export type TableToolbarSearchEvent = CustomEvent<unknown>;
 export type TableToolbarSortChangeEvent = CustomEvent<unknown>;
+export type TableToolbarToolbarColumnsSetEvent = CustomEvent<unknown>;
+export type TableToolbarToolbarFilterClearEvent = CustomEvent<unknown>;
+export type TableToolbarToolbarFilterSetEvent = CustomEvent<unknown>;
+export type TableToolbarToolbarPaginateEvent = CustomEvent<unknown>;
+export type TableToolbarToolbarSearchEvent = CustomEvent<unknown>;
 
 export class UITableToolbar extends UIElement {
   /** 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. */
@@ -57,6 +62,11 @@ export class UITableToolbar extends UIElement {
   addEventListener(type: 'page-size-change', listener: (ev: TableToolbarPageSizeChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'search', listener: (ev: TableToolbarSearchEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'sort-change', listener: (ev: TableToolbarSortChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'toolbar-columns-set', listener: (ev: TableToolbarToolbarColumnsSetEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'toolbar-filter-clear', listener: (ev: TableToolbarToolbarFilterClearEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'toolbar-filter-set', listener: (ev: TableToolbarToolbarFilterSetEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'toolbar-paginate', listener: (ev: TableToolbarToolbarPaginateEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'toolbar-search', listener: (ev: TableToolbarToolbarSearchEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
     listener: (this: UITableToolbar, ev: HTMLElementEventMap[K]) => unknown,

package/components/table-toolbar/table-toolbar.yaml

@@ -199,6 +199,33 @@ events:
     description: "Column visibility changed. Detail: { hiddenColumns }."
   page-size-change:
     description: "Page-size select changed. 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 }.
+  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-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-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-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 }.
 slots:
   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.
@@ -322,15 +349,20 @@ a2ui:
       EXPLICIT range-total="0" — omitting range-* entirely (loading) never
       shows it.
     - >-
-      Read the host's [data-stage-resolved] attribute (ADR-0076 REQ-M-005,
-      ADIA2-9123 S4-ii) to compact a consumer's own [slot="actions-leading"]
-      content in sympathy with table-toolbar's native regions, 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.
+      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.
 anti_patterns: []
 examples:
   - name: members-toolbar

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/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>;