@adukiorg/anza 0.2.0 → 0.2.2

package/src/core/router/transitions.js

@@ -6,9 +6,36 @@
  * falling back instantly to standard synchronous rendering when unsupported
  * or when the user prefers reduced motion.
  *
+ * Injects a token-aware stylesheet on first run so VT timing and backdrop
+ * derive from the semantic token layer.
+ *
  * Source: doc 09 — Routing §8, plan.md §5
  */
 
+let injected = false;
+
+function injectSheet() {
+  if (injected || typeof document === 'undefined') return;
+  injected = true;
+
+  try {
+    const sheet = new CSSStyleSheet();
+    sheet.replaceSync(`
+      ::view-transition-group(root) {
+        animation-duration: var(--transition-duration);
+        animation-timing-function: var(--transition-easing);
+      }
+      ::view-transition-old(root),
+      ::view-transition-new(root) {
+        animation-duration: var(--transition-duration);
+        animation-timing-function: var(--transition-easing);
+        background: var(--transition-bg);
+      }
+    `);
+    document.adoptedStyleSheets.push(sheet);
+  } catch (_) {}
+}
+
 export const transitions = {
   /**
    * Wraps a DOM modification callback in a view transition.
@@ -18,40 +45,40 @@ export const transitions = {
   async run(updateDOM, options = {}) {
     const { sourceElement, name = 'selected-item' } = options;
 
-    const reducedMotion =
+    const reduced =
       typeof window !== 'undefined' &&
       window.matchMedia?.('(prefers-reduced-motion: reduce)').matches;
 
     if (
-      !reducedMotion &&
+      !reduced &&
       typeof document !== 'undefined' &&
       typeof document.startViewTransition === 'function'
     ) {
+      injectSheet();
+
       const hasSource = sourceElement && sourceElement instanceof HTMLElement;
       if (hasSource) {
         sourceElement.style.viewTransitionName = name;
       }
 
-      const transition = document.startViewTransition(() => {
+      const tx = document.startViewTransition(() => {
         const res = updateDOM();
         if (res instanceof Promise) return res;
       });
 
       if (hasSource) {
-        // Clean up the transient style as soon as transition completes or fails
-        transition.finished.finally(() => {
+        tx.finished.finally(() => {
           sourceElement.style.viewTransitionName = '';
         });
       }
 
       try {
-        await transition.finished;
+        await tx.finished;
       } catch (err) {
-        // Silence aborted/superseded view transition errors to preserve router stability
+        // Silence aborted or superseded transition errors to preserve router stability
         console.warn('View Transition was aborted or failed:', err);
       }
     } else {
-      // Graceful fallback for non-supporting browsers or reduced-motion preference
       const res = updateDOM();
       if (res instanceof Promise) await res;
     }

package/src/core/router/trie.js

@@ -0,0 +1,130 @@
+/**
+ * src/core/router/trie.js
+ *
+ * Radix-trie route matcher. Decomposes patterns into '/'-separated segments and
+ * matches a pathname in O(k) where k is the segment count, instead of the O(n)
+ * linear scan over all routes. Static segments beat params beat wildcards, the
+ * same specificity order the URLPattern scan uses.
+ *
+ * Patterns the trie cannot express (regex groups, optional/repeat modifiers)
+ * are rejected by insert() so match.js can keep them on the URLPattern path.
+ *
+ * Source: tasks.md Phase 7
+ */
+
+class Segment {
+  constructor() {
+    this.static = new Map();  // literal -> Segment
+    this.param = null;        // Segment for a :named segment
+    this.wild = null;         // Segment for a * segment
+    this.route = null;        // route entry stored at a terminal node
+    this.key = null;          // param name (when this node is a param child)
+  }
+}
+
+const trie = new Segment();
+
+/** A pattern is trie-expressible only if every segment is plain, :param, or *. */
+export function expressible(pattern) {
+  if (typeof pattern !== 'string') return false;
+  if (pattern.startsWith('http://') || pattern.startsWith('https://')) return false;
+  for (const part of pattern.split('/')) {
+    if (!part) continue;
+    if (part === '*') continue;
+    if (part.startsWith(':')) {
+      // Reject modifiers/regex groups: ':id?', ':id+', ':id(\\d+)'.
+      if (/[?+*(){}]/.test(part)) return false;
+      continue;
+    }
+    // A literal segment must contain no pattern metacharacters.
+    if (/[:*?+(){}]/.test(part)) return false;
+  }
+  return true;
+}
+
+/**
+ * Inserts a route under its pattern.
+ *
+ * @param {string} pattern - e.g. '/members/:id/posts/:post'.
+ * @param {object} route - the route entry to store.
+ * @returns {boolean} true if inserted, false if the pattern is not expressible.
+ */
+export function insert(pattern, route) {
+  if (!expressible(pattern)) return false;
+
+  const parts = pattern.split('/').filter(Boolean);
+  let node = trie;
+
+  for (const part of parts) {
+    if (part === '*') {
+      node.wild ??= new Segment();
+      node = node.wild;
+    } else if (part.startsWith(':')) {
+      node.param ??= new Segment();
+      node.param.key = part.slice(1);
+      node = node.param;
+    } else {
+      if (!node.static.has(part)) node.static.set(part, new Segment());
+      node = node.static.get(part);
+    }
+  }
+
+  node.route = route;
+  return true;
+}
+
+/**
+ * Finds the most specific route for a pathname.
+ *
+ * @param {string} pathname - e.g. '/members/42/posts/7'.
+ * @returns {{ route: object, params: Record<string,string> }|null}
+ */
+export function find(pathname) {
+  const parts = pathname.split('/').filter(Boolean);
+  const params = {};
+  const route = walk(trie, parts, 0, params);
+  return route ? { route, params } : null;
+}
+
+function walk(node, parts, index, params) {
+  if (index === parts.length) return node.route;
+
+  const segment = parts[index];
+
+  // 1. Static — highest specificity.
+  const staticNode = node.static.get(segment);
+  if (staticNode) {
+    const hit = walk(staticNode, parts, index + 1, params);
+    if (hit) return hit;
+  }
+
+  // 2. Param — medium specificity. Backtrack the binding if it fails.
+  if (node.param) {
+    params[node.param.key] = decode(segment);
+    const hit = walk(node.param, parts, index + 1, params);
+    if (hit) return hit;
+    delete params[node.param.key];
+  }
+
+  // 3. Wildcard — lowest specificity, swallows the remainder.
+  if (node.wild) {
+    params['*'] = parts.slice(index).map(decode).join('/');
+    return node.wild.route;
+  }
+
+  return null;
+}
+
+function decode(s) {
+  try { return decodeURIComponent(s); } catch (_) { return s; }
+}
+
+/** Empties the trie. */
+export function clear() {
+  trie.static.clear();
+  trie.param = null;
+  trie.wild = null;
+  trie.route = null;
+}
+
+export { Segment };

package/src/core/security/{usage.md → notes/usage.md}

@@ -19,7 +19,7 @@ import { uuid, hash, generateKey, encrypt, decrypt, seal, unseal, sign, verify,
 ## 1. Choosing an API
 
 | Need | API | Characteristics |
-|---|---|---|
+| --- | --- | --- |
 | Unique correlation ID | `uuid()` | Synchronous, `crypto.randomUUID()`, centralized and mockable |
 | Content hashing | `hash(data, algo)` | `SubtleCrypto.digest`, returns `ArrayBuffer` |
 | AES-GCM encryption | `generateKey`, `encrypt`, `decrypt` | Non-extractable by default, fresh 12-byte IV per encrypt |
@@ -193,7 +193,6 @@ const link = String(sanitize('<a href="javascript:void(0)">click</a>'));
 
 > [!NOTE]
 > The return type is `TrustedHTML | string`. Use `String(sanitize(...))` when you only need the raw string. Pass the raw result directly to DOM sinks that accept `TrustedHTML` under a Trusted Types policy.
-
 > [!WARNING]
 > `sanitize()` is client-side only. It returns the input unchanged when called outside a browser (e.g. Node.js SSR).
 

package/src/core/storage/{usage.md → notes/usage.md}

@@ -19,7 +19,7 @@ import { Database, LRUCache, WeakLRUCache } from '@adukiorg/anza/storage';
 ## 1. Choosing an API
 
 | Need | Tier / API | Characteristics |
-|---|---|---|
+| --- | --- | --- |
 | In-memory caching | `'memory'` | Synchronous, ephemeral, size-bounded LRU |
 | General structured data | `'idb'` (default) | Asynchronous, persistent, transactional, compressed if >64KB |
 | High-performance files | `'opfs'` | Dedicated worker, synchronous I/O access handles, Web Locked |
@@ -36,11 +36,11 @@ the box. Call `storage.configure(...)` once, before first use, to customize it.
 
 ```javascript
 storage.configure({
-  idb:   { name: 'app-db', version: 2, migrations: [
-            (db) => db.createObjectStore('keyval'),
-            (db) => db.createObjectStore('users')
-          ] },
-  lru:   { maxSize: 500 },
+  idb: { name: 'app-db', version: 2, migrations: [
+    (db) => db.createObjectStore('keyval'),
+    (db) => db.createObjectStore('users')
+  ] },
+  lru: { maxSize: 500 },
   cache: { name: 'app-cache' }
 });
 ```

package/src/core/theme/index.js

@@ -0,0 +1,78 @@
+/**
+ * core/theme/index.js
+ *
+ * Automatic theme switching. Attaches to window.theme on import and
+ * restores the saved preference (or respects OS dark mode) without any
+ * manual init call. The user can still import { theme } and call set or
+ * toggle — both update the same global instance.
+ */
+
+const KEY = 'anza-theme';
+
+function root() {
+  return document.documentElement;
+}
+
+function restore() {
+  let saved;
+  try {
+    saved = localStorage.getItem(KEY);
+  } catch (_) {}
+
+  if (saved && saved !== 'auto') {
+    root().dataset.theme = saved;
+    return;
+  }
+
+  const prefersDark =
+    typeof window !== 'undefined' &&
+    window.matchMedia('(prefers-color-scheme: dark)').matches;
+  if (prefersDark) {
+    root().dataset.theme = 'dark';
+  }
+}
+
+export const theme = {
+  /** Return the active theme name: light, dark, contrast, or auto. */
+  get() {
+    const attr = root().dataset.theme;
+    if (attr) return attr;
+    return 'auto';
+  },
+
+  /** Apply a theme name and persist it. */
+  set(name) {
+    const el = root();
+    if (name === 'auto') {
+      delete el.dataset.theme;
+    } else {
+      el.dataset.theme = name;
+    }
+    try {
+      localStorage.setItem(KEY, name);
+    } catch (_) {}
+  },
+
+  /** Toggle between light and dark. */
+  toggle() {
+    const current = this.get();
+    const prefersDark =
+      typeof window !== 'undefined' &&
+      window.matchMedia('(prefers-color-scheme: dark)').matches;
+    const resolved = current === 'auto' ? (prefersDark ? 'dark' : 'light') : current;
+    this.set(resolved === 'dark' ? 'light' : 'dark');
+  }
+};
+
+// Auto-bootstrap on client load.
+if (typeof window !== 'undefined') {
+  if (!('theme' in window)) {
+    Object.defineProperty(window, 'theme', {
+      value: theme,
+      writable: false,
+      enumerable: false,
+      configurable: false
+    });
+  }
+  restore();
+}

package/src/core/ui/define/index.js

@@ -2,8 +2,9 @@ import { define } from './define.js';
 import { element } from './element.js';
 import { container } from './container.js';
 import { initOrchestrator } from './orchestrator.js';
+import { page, dock, view, part } from '../defs/index.js';
 
 // Initialize the global routing orchestrator
 initOrchestrator();
 
-export { define, element, container };
+export { define, element, container, page, dock, view, part };

package/src/core/ui/define/orchestrator.js

@@ -21,12 +21,18 @@ export function initOrchestrator() {
       }
 
       const spec = specRegistry.get(topTag.toLowerCase());
-      if (!spec || !spec.container) return;
+      // Resolve the render target: the last container in the `via` chain, or
+      // the legacy single `container`. Without either there is nothing to mount.
+      const target = (Array.isArray(spec?.via) && spec.via.length)
+        ? spec.via[spec.via.length - 1]
+        : spec?.container;
+      if (!spec || !target) return;
 
-      // Use Advanced Container Registry lookup instead of blind DOM query
-      const containerEl = router.getContainer(spec.container);
+      // Use Advanced Container Registry lookup instead of blind DOM query.
+      // The interceptor's cascade has already ensured the chain is mounted.
+      const containerEl = router.getContainer(target);
       if (!containerEl) {
-        console.warn(`Target container "${spec.container}" not found in DOM for element <${topTag}>`);
+        console.warn(`Target container "${target}" not found in DOM for element <${topTag}>`);
         return;
       }
 

package/src/core/ui/defs/dock.js

@@ -0,0 +1,134 @@
+/**
+ * src/core/ui/defs/dock.js
+ *
+ * `dock(name, config)` — a persistent container shell. It lives across route
+ * changes, registers its position in the hierarchical container graph the
+ * moment it connects, declares its parent dock (for LCA + cascade), and exposes
+ * a `swap` method the router calls to replace child content with a view
+ * transition. Replaces `<route-outlet>`.
+ *
+ * Source: definations.md §4, tasks.md Phase 6
+ */
+
+import { router } from '../../router/index.js';
+import { gate } from '../../router/boot.js';
+import { element } from '../define/element.js';
+import { translate } from './spec.js';
+
+// Element-scoped containment so View Transitions are isolated to the dock.
+const CONTAIN = ':host { contain: layout; display: block; }';
+
+/**
+ * @param {string} name - unique key in the container graph (e.g. 'main').
+ * @param {object} [config]
+ * @param {string} [config.tag] - tag name; defaults to `dock-<name>`.
+ * @param {string} [config.parent='body'] - parent dock key in the graph.
+ * @param {object} [config.template] - { html, css, shadow }.
+ * @param {string} [base] - import.meta.url of the caller (file templates).
+ */
+export function dock(name, config = {}, base) {
+  const tag = config.tag ?? `dock-${name}`;
+  const parent = config.parent ?? 'body';
+
+  const spec = translate(config);
+
+  // Default passthrough template — a dock is a shell around its slotted content.
+  if (spec.template == null) spec.template = '<slot></slot>';
+  // Prepend containment styling to whatever the dock declares.
+  spec.style = spec.style ? `${CONTAIN}\n${spec.style}` : CONTAIN;
+
+  // Register in the graph on connect, unregister on disconnect. Wrap any
+  // user-supplied connect/disconnect rather than clobbering them.
+  const userMount = spec.mount;
+  spec.mount = (ctx) => {
+    router.registerContainer(name, ctx.el, parent);
+    return userMount?.(ctx);
+  };
+  const userUnmount = spec.unmount;
+  spec.unmount = (ctx) => {
+    router.unregisterContainer(name, ctx.el);
+    return userUnmount?.(ctx);
+  };
+
+  element(tag, spec, base);
+  gate(customElements.whenDefined(tag));
+
+  // Install the swap interface used by the orchestrator and cascade.
+  const Cls = customElements.get(tag);
+  if (Cls && !Cls.prototype.swap) {
+    Object.defineProperty(Cls.prototype, 'swap', { value: swap, configurable: true });
+  }
+  // Back-compat alias for the legacy orchestrator/container API.
+  if (Cls && !Cls.prototype.swapView) {
+    Object.defineProperty(Cls.prototype, 'swapView', { value: swap, configurable: true });
+  }
+}
+
+/**
+ * Replaces child content under a view transition. Concurrent-safe: an in-flight
+ * transition is skipped before a new one starts so rapid navigations don't
+ * leave a half-finished animation (RT bug 8.4).
+ */
+async function swap(el, options = {}) {
+  const { direction = 'push' } = options;
+  this.dataset.transitionDirection = direction;
+
+  const go = () => {
+    this.replaceChildren(el);
+    delete this.dataset.transitionDirection;
+  };
+
+  // Abort any transition still running on this dock.
+  if (this._tx && typeof this._tx.skipTransition === 'function') {
+    try { this._tx.skipTransition(); } catch (_) {}
+  }
+
+  // Read directional easing from tokens and temporarily override the root
+  // variable so the injected VT stylesheet picks it up.
+  let prior;
+  if (typeof document !== 'undefined') {
+    const root = document.documentElement;
+    const style = getComputedStyle(root);
+    const easing = direction === 'pop'
+      ? style.getPropertyValue('--transition-pop').trim()
+      : style.getPropertyValue('--transition-push').trim();
+    if (easing) {
+      prior = style.getPropertyValue('--transition-easing').trim();
+      root.style.setProperty('--transition-easing', easing);
+    }
+  }
+
+  function restore() {
+    if (prior !== undefined && typeof document !== 'undefined') {
+      document.documentElement.style.setProperty('--transition-easing', prior);
+    }
+  }
+
+  if (typeof this.startViewTransition === 'function') {
+    try {
+      this._tx = this.startViewTransition({ callback: go });
+      await this._tx.finished;
+    } catch (err) {
+      if (err?.name !== 'AbortError') console.warn('[Native UI] dock scoped VT aborted:', err);
+    } finally {
+      this._tx = null;
+      restore();
+    }
+    return;
+  }
+
+  if (typeof document !== 'undefined' && typeof document.startViewTransition === 'function') {
+    try {
+      const vt = document.startViewTransition(go);
+      await vt.finished;
+    } catch (err) {
+      if (err?.name !== 'AbortError') console.warn('[Native UI] dock document VT aborted:', err);
+    } finally {
+      restore();
+    }
+    return;
+  }
+
+  go();
+  restore();
+}

package/src/core/ui/defs/index.js

@@ -0,0 +1,20 @@
+/**
+ * src/core/ui/defs/index.js
+ *
+ * Definition layer facade. The four first-class UI primitives that supersede
+ * the split `ui.element` + `router.register` pattern and `<route-outlet>`.
+ *
+ *   page  — route-bound navigable unit
+ *   dock  — persistent container shell in the graph
+ *   view  — composable stateful component
+ *   part  — atomic stateless primitive
+ *
+ * Source: definations.md, tasks.md Phase 6
+*/
+
+import { page } from './page.js';
+import { dock } from './dock.js';
+import { view } from './view.js';
+import { part } from './part.js';
+
+export { page, dock, view, part };

package/src/core/ui/defs/page.js

@@ -0,0 +1,89 @@
+/**
+ * src/core/ui/defs/page.js
+ *
+ * `page(route, config, base)` — a route-bound navigable unit. Maps a URL
+ * pattern to a custom element, declares the ordered container chain (`via`) the
+ * router traverses to reach the render target, and gates the boot sequence on
+ * the element's definition so a hard refresh waits for it.
+ *
+ * Source: definations.md §3, tasks.md Phase 6
+ */
+
+import { router } from '../../router/index.js';
+import { gate } from '../../router/boot.js';
+import { element } from '../define/element.js';
+import { specRegistry } from '../define/state.js';
+import { translate } from './spec.js';
+
+/**
+ * @param {string} route - URL pattern, e.g. '/profile/:id'.
+ * @param {object} config - page definition.
+ * @param {string} config.tag - custom element tag (must contain a hyphen).
+ * @param {string[]} [config.via] - ordered container chain, root-to-leaf.
+ * @param {string} [config.container] - single container (back-compat for via).
+ * @param {object} [config.props] - reactive props.
+ * @param {string[]} [config.query] - query params to map onto props.
+ * @param {Function} [config.guard] - route-scoped navigation guard.
+ * @param {object} [config.on] - lifecycle hooks (load, connect, disconnect, change).
+ * @param {string} [base] - import.meta.url of the caller (file templates).
+ */
+export function page(route, config, base) {
+  const tag = config.tag;
+  if (!tag) {
+    console.error(`[Native UI] page('${route}') is missing a 'tag'.`);
+    return;
+  }
+
+  // Normalise the container chain. The render target is the last container.
+  const via = Array.isArray(config.via) && config.via.length
+    ? config.via
+    : (config.container ? [config.container] : []);
+  const target = via.at(-1) ?? null;
+
+  const spec = translate(config, { visual: true });
+  // Carry routing metadata on the spec so the orchestrator can resolve the
+  // render target and cast query params (specRegistry is populated by element()).
+  spec.via = via;
+  spec.container = target;
+  if (config.query) spec.query = config.query;
+
+  element(tag, spec, base);
+
+  // Register the route. Keep both `via` (full chain) and `container` (target)
+  // in meta so the interceptor cascade and orchestrator both work.
+  router.register(route, tag, {
+    ...config.meta,
+    via,
+    container: target
+  });
+
+  // Hold the initial match until this element is defined (hard-refresh safety).
+  if (typeof customElements !== 'undefined') {
+    gate(customElements.whenDefined(tag));
+  }
+
+  // Route-scoped guard: only runs when the destination matches this route.
+  if (typeof config.guard === 'function') {
+    registerGuard(route, config.guard);
+  }
+}
+
+/** Adds a global guard that delegates to `fn` only for matching destinations. */
+function registerGuard(route, fn) {
+  let pattern = null;
+  const Pattern = typeof URLPattern !== 'undefined' ? URLPattern : null;
+  if (Pattern) {
+    try {
+      pattern = route.startsWith('http') ? new Pattern(route) : new Pattern({ pathname: route });
+    } catch (_) { pattern = null; }
+  }
+
+  router.guard(async (destination, controller) => {
+    if (pattern) {
+      let url = destination?.url;
+      try { url = new URL(url, globalThis.location?.href).href; } catch (_) {}
+      if (!pattern.test(url)) return null; // not this route — allow
+    }
+    return fn(destination, controller);
+  });
+}

package/src/core/ui/defs/part.js

@@ -0,0 +1,28 @@
+/**
+ * src/core/ui/defs/part.js
+ *
+ * `part(tag, config, base)` — an atomic, stateless UI primitive (buttons,
+ * icons, badges, chips). Configurable through props, but carries no reactive
+ * `on.change` re-render loop. If you reach for `on.change`, promote to a `view`.
+ *
+ * Source: definations.md §6, tasks.md Phase 6
+ */
+
+import { element } from '../define/element.js';
+import { translate } from './spec.js';
+
+/**
+ * @param {string} tag - custom element tag name (must contain a hyphen).
+ * @param {object} config - part definition (props, template, optional on.connect).
+ * @param {string} [base] - import.meta.url of the caller; required when
+ *   template/style are file paths.
+ */
+export function part(tag, config, base) {
+  if (config?.on?.change) {
+    console.warn(`[Native UI] <${tag}> is a 'part' but declares on.change. Parts are stateless — promote it to a 'view' if it needs reactive re-rendering.`);
+  }
+  const spec = translate(config);
+  // Parts never run a reactive update loop, even if on.change slipped through.
+  delete spec.update;
+  element(tag, spec, base);
+}