@adukiorg/anza 0.2.0

package/src/core/ui/watch.md

@@ -0,0 +1,346 @@
+# Scoped Mutation Observation API: `watch`
+
+`watch` is the component-scoped mutation observation helper injected alongside `tags`, `refs`, and `on`. It wraps `MutationObserver` with lifecycle cleanup, shadow-root scoping, selector/direct-ref targeting, one-shot handlers, and mutation-specific handler signatures.
+
+## 1. Injection Shape
+
+```javascript
+mount({ el, ctrl, tags, on, refs, watch }) {}
+
+update({ el, ctrl, tags, on, refs, watch, name, val, prev }) {}
+```
+
+`watch` is created once per connected lifecycle. If the component disconnects, `ctrl.abort()` disconnects the shared observer and removes every registration.
+
+## 2. API Summary
+
+```javascript
+watch.attr(target, attrName, handler, signalOrOptions?)
+watch.attr(target, attrNames, handler, signalOrOptions?)
+watch.attr(target, '*', handler, signalOrOptions?)
+
+watch.kids(target, handler, signalOrOptions?)
+watch.kids(target, { deep: true }, handler, signalOrOptions?)
+
+watch.text(target, handler, signalOrOptions?)
+
+watch.tree(target, handler, signalOrOptions?)
+
+watch.attr.once(...)
+watch.kids.once(...)
+watch.text.once(...)
+watch.tree.once(...)
+```
+
+`target` can be:
+
+- A selector string scoped to the component shadow root.
+- A direct `Element` reference from `refs.*` or `tags.one(...)`.
+
+The final argument can be:
+
+- An `AbortSignal`.
+- An options object: `{ signal, once }`.
+- Omitted, in which case `ctrl.signal` is used.
+
+Every call returns a disposer function.
+
+```javascript
+const stop = watch.attr(refs.submit, 'disabled', handler);
+stop();
+```
+
+## 3. Attribute Watching: `watch.attr`
+
+Observe one, many, or all attributes.
+
+```javascript
+watch.attr('button', 'disabled', (attr, next, prev, el) => {})
+watch.attr('.card', ['aria-expanded', 'data-state'], handler)
+watch.attr('.card', '*', handler)
+watch.attr(refs.submit, 'disabled', handler)
+watch.attr(tags.one('#toggle'), 'aria-pressed', handler)
+watch.attr.once('details', 'open', handler)
+```
+
+Handler:
+
+```javascript
+(attrName, newValue, oldValue, element) => void
+```
+
+Example:
+
+```javascript
+mount({ refs, watch }) {
+  watch.attr(refs.submit, 'disabled', (attr, next, prev, button) => {
+    button.dataset.wasDisabled = String(prev !== null);
+  });
+}
+```
+
+Notes:
+
+- `newValue` is read with `element.getAttribute(attrName)`, so removed attributes produce `null`.
+- `oldValue` comes from the mutation record and is always requested internally.
+- Boolean attributes usually have `''` when present and `null` when absent.
+
+## 4. Child Watching: `watch.kids`
+
+Observe child additions and removals.
+
+```javascript
+watch.kids('ul', ({ added, removed }, list) => {})
+watch.kids(refs.list, handler)
+watch.kids('ul', { deep: true }, handler)
+watch.kids.once('ul', handler)
+```
+
+Handler:
+
+```javascript
+({ added, removed }, element) => void
+```
+
+Example:
+
+```javascript
+mount({ refs, watch }) {
+  watch.kids(refs.list, ({ added }) => {
+    for (const node of added) {
+      if (node.nodeType === Node.ELEMENT_NODE) {
+        node.classList.add('entry-new');
+      }
+    }
+  });
+}
+```
+
+Rules:
+
+- `added` and `removed` are arrays, never `NodeList`.
+- Without `{ deep: true }`, only direct child mutations on the target match.
+- With `{ deep: true }`, descendant child mutations inside the target subtree match.
+
+## 5. Text Watching: `watch.text`
+
+Observe text-node changes inside a target.
+
+```javascript
+watch.text('.label', (next, prev, el) => {})
+watch.text(refs.counter, handler)
+watch.text.once('.status', handler)
+```
+
+Handler:
+
+```javascript
+(newText, oldText, element) => void
+```
+
+Example:
+
+```javascript
+mount({ refs, watch }) {
+  watch.text(refs.counter, (next, prev, el) => {
+    const direction = Number(next) > Number(prev) ? 'up' : 'down';
+    el.dataset.direction = direction;
+  });
+}
+```
+
+Notes:
+
+- `newText` is the current `textContent` of the watched element.
+- `oldText` is the previous text node value from the mutation record.
+- Multiple text nodes may produce multiple records in the same microtask batch.
+
+## 6. Subtree Watching: `watch.tree`
+
+Observe all mutation types under a target and receive raw records.
+
+```javascript
+watch.tree('.editor', (records) => {})
+watch.tree(refs.canvas, handler)
+watch.tree.once('.editor', handler)
+```
+
+Handler:
+
+```javascript
+(records, element) => void
+```
+
+Example:
+
+```javascript
+mount({ refs, watch }) {
+  watch.tree(refs.editor, (records) => {
+    for (const record of records) {
+      if (record.type === 'childList') syncOutline();
+      if (record.type === 'attributes') syncToolbar();
+    }
+  });
+}
+```
+
+`watch.tree` is the escape hatch. Prefer `attr`, `kids`, or `text` when the mutation type is known.
+
+## 7. Scoping Rules
+
+`watch` never observes outside the component shadow root.
+
+- Selector targets are resolved with `shadowRoot.querySelectorAll`.
+- Direct element targets must satisfy `shadowRoot.contains(element)`.
+- A selector with no matches returns a no-op disposer and warns in development.
+- A direct target outside the shadow root throws in development and returns a no-op disposer in production.
+- Cross-component observation must use `CustomEvent`, shared state, or parent-owned refs.
+
+## 8. Shared Observer Model
+
+Each component instance owns one `MutationObserver`.
+
+Registrations are stored internally:
+
+```javascript
+{
+  id,
+  kind,
+  target,
+  selector,
+  attrs,
+  deep,
+  handler,
+  signal,
+  once
+}
+```
+
+When a registration is added or removed, the observer options are recomputed:
+
+```javascript
+{
+  attributes: hasAttrWatch || hasTreeWatch,
+  attributeOldValue: hasAttrWatch || hasTreeWatch,
+  attributeFilter: unionOfSpecificAttrsOrUndefined,
+  childList: hasKidsWatch || hasTreeWatch,
+  characterData: hasTextWatch || hasTreeWatch,
+  characterDataOldValue: hasTextWatch || hasTreeWatch,
+  subtree: true
+}
+```
+
+If any `watch.attr(..., '*', ...)` or `watch.tree(...)` registration exists, `attributeFilter` is omitted.
+
+## 9. Matching Rules
+
+Attribute records:
+
+- Match `record.type === 'attributes'`.
+- Match when `record.target === registration.target`.
+- For selector targets with multiple elements, match any registered target element.
+- Attribute name must be included in `attrs`, unless `attrs === '*'`.
+
+Child records:
+
+- Match `record.type === 'childList'`.
+- Without `deep`, match only `record.target === registration.target`.
+- With `deep`, match `registration.target.contains(record.target)`.
+
+Text records:
+
+- Match `record.type === 'characterData'`.
+- Use `record.target.parentElement` as the element.
+- Match if the parent is the registration target or is contained by it.
+
+Tree records:
+
+- Match any record where the mutation target is the watched element or inside it.
+- Handler receives the filtered record batch.
+
+## 10. Cleanup
+
+Cleanup must be deterministic:
+
+- Default signal is the component `ctrl.signal`.
+- A custom signal removes only that registration.
+- `.once` removes only that registration after the first matching mutation.
+- Component abort disconnects the shared observer and clears the registry.
+- The mutation callback checks `defaultSignal.aborted` before dispatching because queued observer callbacks can still run after `disconnect()`.
+
+## 11. Implementation Pseudocode
+
+```javascript
+export function createMutationWatcher(shadowRoot, defaultSignal) {
+  const registry = new Map();
+  let observer = null;
+  let nextId = 0;
+
+  function add(kind, args, once = false) {
+    const reg = normalizeRegistration(kind, args, once, defaultSignal, shadowRoot);
+    if (!reg) return () => {};
+
+    registry.set(reg.id, reg);
+    reg.signal?.addEventListener('abort', () => remove(reg.id), { once: true });
+    refreshObserver();
+
+    return () => remove(reg.id);
+  }
+
+  function remove(id) {
+    registry.delete(id);
+    refreshObserver();
+  }
+
+  function refreshObserver() {
+    if (observer) observer.disconnect();
+    if (!registry.size || defaultSignal.aborted) return;
+    observer ||= new MutationObserver(dispatch);
+    observer.observe(shadowRoot, computeOptions(registry.values()));
+  }
+
+  function dispatch(records) {
+    if (defaultSignal.aborted) return;
+    for (const reg of registry.values()) {
+      const matches = filterRecords(records, reg);
+      if (!matches.length) continue;
+      callHandler(matches, reg);
+      if (reg.once) remove(reg.id);
+    }
+  }
+
+  defaultSignal.addEventListener('abort', () => {
+    observer?.disconnect();
+    registry.clear();
+  }, { once: true });
+
+  return createWatchProxy(add);
+}
+```
+
+## 12. Usage with `tags`, `refs`, and `on`
+
+```javascript
+mount({ refs, tags, on, watch }) {
+  const toggle = refs.toggle ?? tags.one('[data-toggle]');
+  const panel = refs.panel;
+
+  watch.attr(toggle, 'aria-expanded', (attr, next) => {
+    panel.hidden = next !== 'true';
+  });
+
+  on.click('[data-toggle]', (event, target) => {
+    const open = target.getAttribute('aria-expanded') === 'true';
+    target.setAttribute('aria-expanded', String(!open));
+  });
+}
+```
+
+The click mutates an attribute. `watch.attr` reacts without any manual event dispatch.
+
+## 13. What `watch` Is Not
+
+- It is not cross-component state management.
+- It is not a replacement for `on` for user interactions.
+- It is not a render scheduler. Heavy handlers should schedule work with `ui.schedule` or `ui.scheduleFrame`.
+- It is not for slotted light DOM changes. Use `slotchange` on a `<slot>` element for that.

package/src/core/workers/broadcast.js

@@ -0,0 +1,138 @@
+/**
+ * src/core/workers/broadcast.js
+ *
+ * BroadcastChannel Manager.
+ * Reference-counted channels: open on first subscriber, close when the last
+ * subscriber leaves. Supports explicit close(name) and clear() for lifecycle
+ * control. Cleans up both the message listener and the abort listener on
+ * disposal to prevent memory leaks.
+ *
+ * Source: plan.md Phase 5
+ */
+
+class BroadcastManager {
+  #channels = new Map();  // name → BroadcastChannel
+  #listeners = new Map(); // name → Set<{ wrapped, fn, abortCleanup }>
+
+  /**
+   * Dispatches a message to a named channel.
+   *
+   * BroadcastChannel messages are NOT echoed to the posting instance — only
+   * other channel instances with the same name receive them. So we always post
+   * from a short-lived peer channel and close it immediately. This correctly
+   * delivers to all subscriber channel instances, including the one managed
+   * by this BroadcastManager.
+   *
+   * @param {string} name
+   * @param {any}    payload
+   */
+  broadcast(name, payload) {
+    // Always use a peer sender so the subscriber channel receives the message.
+    // (A BroadcastChannel instance never fires its own onmessage for messages it posts.)
+    const sender = new BroadcastChannel(name);
+    sender.postMessage(payload);
+    // Close asynchronously to allow same-process delivery before cleanup.
+    setTimeout(() => sender.close(), 0);
+  }
+
+  /**
+   * Subscribes to a named channel.
+   * Returns a dispose function that removes the listener and cleans up the
+   * abort listener.
+   *
+   * @param {string}      name
+   * @param {Function}    fn
+   * @param {AbortSignal} [signal]
+   * @returns {() => void} dispose
+   */
+  subscribe(name, fn, signal) {
+    if (signal?.aborted) return () => {};
+
+    // Open channel on first subscriber
+    if (!this.#channels.has(name)) {
+      const ch = new BroadcastChannel(name);
+      ch.onmessageerror = (e) => {
+        console.error(`BroadcastChannel "${name}" deserialization error:`, e);
+      };
+      this.#channels.set(name, ch);
+      this.#listeners.set(name, new Set());
+    }
+
+    const channel = this.#channels.get(name);
+    const group = this.#listeners.get(name);
+
+    const wrapped = (event) => {
+      try {
+        fn(event.data);
+      } catch (err) {
+        console.error(`Error in BroadcastChannel "${name}" subscriber:`, err);
+      }
+    };
+
+    channel.addEventListener('message', wrapped);
+
+    let abortCleanup = null;
+    const entry = { wrapped, fn, abortCleanup };
+    group.add(entry);
+
+    const dispose = () => {
+      channel.removeEventListener('message', wrapped);
+      group.delete(entry);
+
+      // Remove the abort listener we registered
+      if (entry.abortCleanup) {
+        signal?.removeEventListener('abort', entry.abortCleanup);
+        entry.abortCleanup = null;
+      }
+
+      // Auto-close when no listeners remain
+      if (group.size === 0) {
+        channel.close();
+        this.#channels.delete(name);
+        this.#listeners.delete(name);
+      }
+    };
+
+    if (signal) {
+      const onAbort = () => dispose();
+      entry.abortCleanup = onAbort;
+      signal.addEventListener('abort', onAbort, { once: true });
+    }
+
+    return dispose;
+  }
+
+  /**
+   * Closes one named channel and removes all its listeners.
+   *
+   * @param {string} name
+   */
+  close(name) {
+    const channel = this.#channels.get(name);
+    if (!channel) return;
+
+    const group = this.#listeners.get(name) ?? new Set();
+    for (const entry of group) {
+      channel.removeEventListener('message', entry.wrapped);
+      if (entry.abortCleanup) {
+        // We don't have the signal reference here, so just null the cleanup
+        entry.abortCleanup = null;
+      }
+    }
+
+    channel.close();
+    this.#channels.delete(name);
+    this.#listeners.delete(name);
+  }
+
+  /**
+   * Closes all open channels and removes all listeners.
+   */
+  clear() {
+    for (const name of [...this.#channels.keys()]) {
+      this.close(name);
+    }
+  }
+}
+
+export const broadcast = new BroadcastManager();

package/src/core/workers/dedicated.js

@@ -0,0 +1,153 @@
+/**
+ * src/core/workers/dedicated.js
+ *
+ * Dedicated Worker Wrapper.
+ * Manages the lifecycle of standard background dedicated Workers, using
+ * native MessageChannel per request for isolated, concurrent execution corridors
+ * without message cross-contamination.
+ *
+ * Message contract:
+ *   Request  → { task, payload, meta }
+ *   Response → { ok, value, error }
+ *
+ * Source: plan.md Phase 1, Phase 2
+ */
+
+export class Dedicated {
+  #script;
+  #worker;
+  #pending = new Map(); // port1 → { resolve, reject, timer }
+  #closed = false;
+
+  constructor(script) {
+    this.#script = script;
+    this.#worker = new Worker(script, { type: 'module' });
+    this.#worker.addEventListener('error', (e) => this.#fail(e));
+    this.#worker.addEventListener('messageerror', (e) => this.#fail(e));
+  }
+
+  get closed() { return this.#closed; }
+
+  /**
+   * Dispatches a task to the worker.
+   *
+   * Options:
+   *   payload       – data to send (structured-clone safe)
+   *   transferables – Transferable[] transferred with the message
+   *   signal        – AbortSignal to cancel the request
+   *   timeout       – milliseconds before automatic abort
+   *   meta          – arbitrary structured data attached to the request
+   */
+  run(task, options = {}) {
+    if (this.#closed) {
+      return Promise.reject(new Error(`Worker "${this.#script}" is closed`));
+    }
+
+    const {
+      payload = null,
+      transferables = [],
+      signal,
+      timeout,
+      meta
+    } = options;
+
+    // Abort before anything starts
+    if (signal?.aborted) {
+      return Promise.reject(signal.reason ?? new DOMException('Aborted', 'AbortError'));
+    }
+
+    return new Promise((resolve, reject) => {
+      const channel = new MessageChannel();
+
+      // Combine caller signal and optional timeout into one controller
+      let combined = null;
+      let timer = null;
+
+      if (signal || timeout) {
+        combined = new AbortController();
+
+        if (signal) {
+          if (signal.aborted) {
+            combined.abort(signal.reason);
+          } else {
+            signal.addEventListener('abort', () => combined.abort(signal.reason), { once: true });
+          }
+        }
+
+        if (timeout) {
+          timer = setTimeout(
+            () => combined.abort(new Error(`Worker task "${task}" timed out after ${timeout}ms`)),
+            timeout
+          );
+        }
+      }
+
+      const abort = combined?.signal;
+
+      const cleanup = () => {
+        if (timer) clearTimeout(timer);
+        channel.port1.close();
+        this.#pending.delete(channel.port1);
+      };
+
+      const fail = (reason) => {
+        cleanup();
+        reject(reason);
+      };
+
+      this.#pending.set(channel.port1, { resolve, reject: fail });
+
+      channel.port1.onmessage = (e) => {
+        const { ok, value, error } = e.data;
+        cleanup();
+        if (ok) {
+          resolve(value);
+        } else {
+          reject(new Error(error ?? 'Worker task failed'));
+        }
+      };
+
+      channel.port1.onmessageerror = () => {
+        fail(new Error('Deserialization error on message channel'));
+      };
+
+      if (abort) {
+        abort.addEventListener('abort', () => {
+          fail(abort.reason ?? new DOMException('Aborted', 'AbortError'));
+        }, { once: true });
+      }
+
+      this.#worker.postMessage(
+        { task, payload, meta, port: channel.port2 },
+        [channel.port2, ...transferables]
+      );
+    });
+  }
+
+  /** Route a worker-level error into all pending requests. */
+  #fail(event) {
+    const reason = event instanceof ErrorEvent
+      ? new Error(event.message ?? 'Worker error')
+      : new Error('Worker message deserialization error');
+
+    for (const { reject } of this.#pending.values()) {
+      reject(reason);
+    }
+    this.#pending.clear();
+  }
+
+  /** Terminate the worker. Subsequent `run` calls will reject immediately. */
+  terminate() {
+    if (this.#closed) return;
+    this.#closed = true;
+    this.#worker.terminate();
+    const reason = new Error(`Worker "${this.#script}" terminated`);
+    for (const { reject } of this.#pending.values()) {
+      reject(reason);
+    }
+    this.#pending.clear();
+  }
+}
+
+// Compatibility alias
+export { Dedicated as DedicatedWorker };