@adukiorg/anza 0.2.0

package/src/core/events/index.js

@@ -0,0 +1,26 @@
+/**
+ * src/core/events/index.js
+ *
+ * Public event architecture entry point.
+ * Aggregates EventBus dispatchers, Shadow-DOM composed delegation, single-event awaits,
+ * progressive passive listener registrations, and standardized system event names.
+ *
+ * Source: doc 10 — Event Architecture §1, §9
+ */
+
+import { bus, EventBus } from './bus.js';
+import { delegate } from './delegate.js';
+import { once } from './once.js';
+import { listen } from './listen.js';
+import { names } from './types/index.js';
+
+export const events = {
+  emit: (type, detail) => bus.emit(type, detail),
+  on: (type, fn, signal) => bus.on(type, fn, signal),
+  delegate,
+  once,
+  listen,
+  names
+};
+
+export { bus, EventBus, delegate, once, listen, names };

package/src/core/events/listen.js

@@ -0,0 +1,50 @@
+/**
+ * src/core/events/listen.js
+ *
+ * High-performance, memory-safe event listener aggregator.
+ * Enforces touch/wheel events to passive: true by default to protect INP performance,
+ * while seamlessly supporting AbortSignal-gated cleanups and disposer patterns.
+ *
+ * Source: doc 10 — Event Architecture §2, §3, §13
+ */
+
+/**
+ * Attaches a memory-safe event listener to a target.
+ * Automatically defaults touch/wheel events to passive: true unless explicitly overridden.
+ *
+ * @param {EventTarget} target - The target element, window, document, or global bus.
+ * @param {string} type - The event name to subscribe to.
+ * @param {Function} handler - The listener callback function.
+ * @param {Object} [options={}] - Standard addEventListener options.
+ * @returns {Function} A disposer function that unregisters the listener.
+ */
+export function listen(target, type, handler, options = {}) {
+  const signal = options.signal;
+  if (signal?.aborted) return () => {};
+
+  // Automatically default touch and wheel events to passive: true to prevent scroll blocking
+  const isPassiveTarget = ['touchstart', 'touchmove', 'wheel', 'mousewheel'].includes(type);
+  const listenerOpts = {
+    passive: isPassiveTarget ? true : undefined,
+    ...options
+  };
+
+  const listener = (event) => {
+    handler(event);
+  };
+
+  target.addEventListener(type, listener, listenerOpts);
+
+  const dispose = () => {
+    target.removeEventListener(type, listener, listenerOpts);
+    if (signal) {
+      signal.removeEventListener('abort', dispose);
+    }
+  };
+
+  if (signal) {
+    signal.addEventListener('abort', dispose, { once: true });
+  }
+
+  return dispose;
+}

package/src/core/events/missing.md

@@ -0,0 +1,103 @@
+# Event Missing Support
+
+This document tracks remaining support, runtime gaps, type mismatches, and state/storage synchronization improvements for `src/core/events`. Implemented behavior belongs in `usage.md`; unsupported, under-tested, or performance-gated behavior belongs here until it is built and verified.
+
+---
+
+## 0. Toolchain and Naming Rules
+
+Heavy compilation, static analysis, and code generation belong in `tools/`, not in browser runtime modules.
+
+Current toolchain event requirements:
+- Statically verify event name strings inside `dispatchEvent` to ensure they are registered in the names registry.
+- Detect event listeners registered on `window` or `document` that do not supply an `AbortSignal`.
+
+Naming rules for event support:
+- Prefer one-word files: `bus.js`, `delegate.js`, `once.js`, `listen.js`, `index.js`.
+- Plural folders: `tests/`, `types/`.
+- Single-word methods: `on`, `emit`, `delegate`, `once`, `listen`.
+
+---
+
+## 1. Critical Runtime and Type Gaps
+
+### 1.1. Native EventTarget Base Composition for EventBus
+- **Status**: Runtime gap & design code smell.
+- **Files**:
+  - `src/core/events/bus.js`
+- **Problem**:
+  The `EventBus` class is implemented as a custom subscriber registry utilizing a private Map. The architectural specifications state that the event bus must compose the browser's native `EventTarget` interface. By making `EventBus` extend `EventTarget`, we inherit native performance optimizations and DOM-standard listener registration, while maintaining backward-compatible helper wrappers.
+- **Expected Support**:
+  - Refactor `EventBus` in `bus.js` to extend `EventTarget`.
+  - Compose standard `EventTarget` capabilities, implementing `on()` and `emit()` as simple, clean wrappers on top of `addEventListener()` and `dispatchEvent()`.
+
+### 1.2. Missing TypeScript Declarations
+- **Status**: Type mismatch.
+- **Files**:
+  - `types/core/events/index.d.ts`
+- **Problem**:
+  The TypeScript definitions for events do not export the `listen` function or the `names` namespace registry, even though both are public exports in `src/core/events/index.js`. Additionally, the declaration of the `EventBus` class does not denote its native `EventTarget` inheritance.
+- **Expected Support**:
+  - Declare and export `listen` and `names` inside `types/core/events/index.d.ts`.
+  - Update `EventBus` type definition to extend `EventTarget`.
+
+---
+
+## 2. State & Storage Synchronization Gaps
+
+### 2.1. Missing Connectivity Broadcasts on the Event Bus
+- **Status**: Synchronization gap.
+- **Files**:
+  - `src/core/offline/connectivity.js`
+- **Problem**:
+  When network connectivity transitions between online and offline states, the connectivity monitor correctly updates the reactive state store but does not broadcast matching events to the global Event Bus. Consumers listening on the bus for `connectivity:online` and `connectivity:offline` are never notified.
+- **Expected Support**:
+  - Synchronize connectivity updates by importing the global `bus` and dispatching `connectivity:online` or `connectivity:offline` events using standard naming constants.
+
+### 2.2. Offline Sync Queue Broadcasts
+- **Status**: Synchronization gap.
+- **Files**:
+  - `src/core/offline/sync.js`
+- **Problem**:
+  Sync queue completion, replays, or failures are handled silently. Parent application views cannot react to queue status changes.
+- **Expected Support**:
+  - Emit synchronization telemetry events on the Event Bus when tasks are successfully replayed or if they fail permanently.
+
+---
+
+## 3. Test Coverage Gaps
+
+### 3.1. Single Event Awaiter Verification
+- **Status**: Test gap.
+- **Files**:
+  - `tests/core/events/once.test.js` [NEW]
+- **Needed Coverage**:
+  - Test that `once()` resolves immediately upon event firing.
+  - Test that `once()` cleans up the registered listener after firing.
+  - Test that `once()` rejects with an AbortError when its signal is aborted.
+
+### 3.2. Listener Aggregation Edge Cases
+- **Status**: Test gap.
+- **Files**:
+  - `tests/core/events/listen.test.js`
+- **Needed Coverage**:
+  - Verify that options like `once: true` or `capture: true` are correctly passed through to the native target.
+
+---
+
+## 4. Suggested Implementation Order
+
+1. Refactor `EventBus` to extend `EventTarget` inside `src/core/events/bus.js`.
+2. Add connectivity event emission inside `src/core/offline/connectivity.js`.
+3. Create the type declarations for `listen` and `names` in `types/core/events/index.d.ts`.
+4. Add the unit test suite `tests/core/events/once.test.js`.
+
+---
+
+## 5. Done Criteria
+
+This missing-support list is complete when:
+- `EventBus` extends `EventTarget` and passes all existing/new test cases.
+- Connectivity status transitions emit corresponding events on the `bus`.
+- All public exports of the events module are fully typed.
+- `once()` and `listen()` are thoroughly covered by tests.

package/src/core/events/once.js

@@ -0,0 +1,49 @@
+/**
+ * src/core/events/once.js
+ *
+ * Promise-wrapped single-event listener.
+ * Dynamically resolves a promise upon event completion, utilizing native browser cleanup properties.
+ *
+ * Source: doc 10 — Event Architecture §2, §3
+ */
+
+/**
+ * Awaits a single event occurrence on a given target, resolving with the Event object.
+ */
+export function once(target, type, options = {}) {
+  const { signal, ...listenerOpts } = options;
+
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      return reject(new Error('Operation aborted'));
+    }
+
+    let onAbort;
+
+    const cleanup = () => {
+      if (signal && onAbort) {
+        signal.removeEventListener('abort', onAbort);
+      }
+    };
+
+    const callback = (event) => {
+      cleanup();
+      resolve(event);
+    };
+
+    // Modern browsers support signal natively inside addEventListener options
+    target.addEventListener(type, callback, {
+      once: true,
+      ...listenerOpts,
+      signal
+    });
+
+    if (signal) {
+      onAbort = () => {
+        cleanup();
+        reject(new Error('Operation aborted'));
+      };
+      signal.addEventListener('abort', onAbort, { once: true });
+    }
+  });
+}

package/src/core/events/plan.md

@@ -0,0 +1,177 @@
+# Native-First Event Architecture Spec & Plan
+
+This document establishes the comprehensive architectural plan, technical specifications, and system guidelines for the Native-First Event Architecture inside `src/core/events/`.
+
+---
+
+## 1. Architectural Philosophy & Principles
+
+The event system in this platform relies on the browser's high-performance native event-dispatch loop rather than recreating arbitrary JavaScript Pub/Sub emitters. We treat standard `EventTarget`, `Event`, and `CustomEvent` APIs as primary scheduling primitives:
+
+1. **Zero Library Bloat:** We leverage native rendering engine loops. Subscribing to, firing, and propagating events has zero impact on bundle size.
+2. **Memory Safety by Design:** No event handler should persist past its lifecycle. Every component uses a dedicated, centralized `AbortController` bound to the connection state (`disconnectedCallback`).
+3. **Encapsulated & Composed Boundaries:** Communication boundaries respect the Shadow DOM layout, utilizing retargeting, flat tree propagation, and `composedPath` traversal for seamless cross-shadow event routing.
+4. **Unidirectional Event Flow:**
+   * **Upward Flow:** Custom events bubbled from child to ancestor (`{ bubbles: true, composed: true }`).
+   * **Downward Flow:** Direct property/method invocations from parent to child.
+   * **Decoupled System Flow:** Global Event Bus singleton (`bus.js`) reserved exclusively for out-of-band cross-cutting system telemetry (e.g., Auth, Connectivity, SW).
+
+---
+
+## 2. Review of Current Architecture
+
+The `src/core/events/` module is divided into four highly focused primitives:
+
+```mermaid
+graph TD
+    A[index.js] --> B[bus.js]
+    A --> C[delegate.js]
+    A --> D[once.js]
+    
+    subgraph Core Modules
+        B
+        C
+        D
+      end
+```
+
+### A. The Global Event Bus (`bus.js`)
+
+* **Purpose:** A decoupled central hub for system-wide notifications that do not map naturally to a DOM lineage.
+* **Mechanism:** Leverages an optimized internal `Map<string, Set<{ fn }>>`.
+* **Key Feature:** Highly performant execution with snapshotting (`[...set]`) to avoid runtime list mutations during event dispatch.
+* **Cleanup:** Integrates `AbortSignal` listeners to automatically execute the `dispose()` callback when component lifecycles cancel.
+
+### B. Event Delegation (`delegate.js`)
+
+* **Purpose:** Attaches a single root listener to dynamically handle events from dynamic descendants, minimizing handler creation and memory consumption.
+* **Boundary Traversal:** Traverses through Web Component boundaries by evaluating `event.composedPath()`, checking if descendants match specified queries via `.matches(selector)`.
+* **Cleanup:** Disposes of listeners seamlessly on signal abort.
+
+### C. Single Event Awaiter (`once.js`)
+
+* **Purpose:** Wraps standard event listener triggers in a Promise, allowing asynchronous waiting for one-off user or network events.
+* **Mechanism:** Passes `{ once: true }` down to the browser's `addEventListener` and handles clean early rejection if the abort signal triggers first.
+
+---
+
+## 3. Composed Event Routing (Shadow DOM Integration)
+
+To traverse the Shadow DOM encapsulation without breaking modular boundaries, our event system implements specific propagation combinations:
+
+| Propagation Mode | Configuration | Boundaries Crossed | Target Behavior | Recommended Use Case |
+|---|---|---|---|---|
+| **Fully Encapsulated** | `bubbles: false`, `composed: false` | None | Stays on target element | Internal component state ticks |
+| **Shadow-Local** | `bubbles: true`, `composed: false` | None (Stops at Shadow Root) | Normal bubbling | Internal compound component parts |
+| **Composed Bubbling** | `bubbles: true`, `composed: true` | All boundaries | Retargeted to Shadow Host | Standard child-to-parent callbacks |
+
+```
+[Document Root]
+      ▲
+      │ (Bubbles & Composed)
+[Shadow Host (Component)] ◄─── (Retargeted target appears here to Light DOM)
+  ┌───┴───┐
+  │ Shadow│ (Bubbles inside local tree)
+  │ Root  │
+  └───┬───┘
+      ▲
+      │ (Originates)
+[Shadow Target Element]
+```
+
+### Safe composedPath Traversal
+
+Standard event delegation utilizing `event.target` fails across Shadow DOM limits because of browser-enforced retargeting. `delegate.js` safely bypasses this restriction by reading `event.composedPath()`.
+
+* **Rule:** Always inspect `composedPath()[0]` when you need to resolve the exact physical leaf node that triggered the interaction.
+
+---
+
+## 4. Unidirectional Data Flow & Communication Contract
+
+We enforce highly strict API paths to guarantee components maintain unidirectional, predictable updates:
+
+```mermaid
+sequenceDiagram
+    participant Parent as Parent Component
+    participant Child as Child Component (Shadow DOM)
+
+    rect rgb(20, 20, 30)
+        Note over Parent, Child: 1. Downward Communication
+        Parent->>Child: Direct Property Assignment (child.items = data)
+        Parent->>Child: Imperative Method Call (child.focus())
+    end
+
+    rect rgb(30, 20, 20)
+        Note over Parent, Child: 2. Upward Communication
+        Child-->>Parent: CustomEvent("domain:action", { bubbles, composed })
+    end
+```
+
+* **No Event Sinks Downward:** Never dispatch an event downward on a child element if setting a direct property or method accomplishes the same task.
+* **No Diagonal Bus Calls:** Avoid using the global Event Bus (`bus.js`) to coordinate between nearby siblings. Let their common ancestor mediate their states.
+
+---
+
+## 5. Memory Safety & Garbage Collection (GC) Boundary
+
+Event listeners keep their host components alive in memory because closures bind `this` strongly. The following strategies must be strictly applied:
+
+```
+                  ┌─────────────────────────────────┐
+                  │          Garbage Collector      │
+                  └────────────────┬────────────────┘
+                                   │ (Checks for reference paths)
+                                   ▼
+┌──────────────────┐       ┌──────────────┐       ┌──────────────────┐
+│ Component Target │ ◄──── │  AbortSignal │ ◄──── │  Event Listener  │
+└──────────────────┘       └──────────────┘       └──────────────────┘
+   (Eligible for GC)       (Aborted = Detached)       (Strong Ref broken)
+```
+
+1. **Deterministic Teardown:** Ensure *every* single event listener attached outside the element's local DOM (e.g. on `window`, `document`, or `bus`) is attached with `signal: this.#controller.signal`.
+2. **WeakMap for Auxiliary Metadata:** When maintaining auxiliary state outside the element class scope, store references in a `WeakMap`. This allows components to be GC'd cleanly when removed from the DOM:
+
+   ```javascript
+   const elementStates = new WeakMap();
+   ```
+
+3. **Avoid Dynamic Lambda Closures:** Prefer class methods or statically bound private arrow fields. Generating anonymous arrow functions inside rendering paths causes unnecessary garbage allocations:
+
+   ```javascript
+   // AVOID:
+   this.addEventListener('click', (e) => this.handle(e));
+
+   // PREFER:
+   this.addEventListener('click', this.handle, { signal });
+   ```
+
+---
+
+## 6. Actionable Implementation & Optimization Enhancements
+
+To make our current system even more robust, we will implement three core enhancements:
+
+### 1. Optimize `delegate.js` (Fast Path Selector Matching)
+
+* **Status:** Current implementation iterates through the entire composed path.
+* **Enhancement:** Cache selector match results or stop iteration immediately when traversing past the designated boundaries.
+
+### 2. Standardized Namespace Registry for System Events
+
+* **Status:** Events can be dispatched on the bus using freeform strings.
+* **Enhancement:** Maintain a central, typed list of valid events in `plan.md` and export standard constants to prevent typos (e.g., `events.NAMES.AUTH_SIGNED_IN`).
+
+### 3. Progressive Passive Hooks
+
+* **Status:** Native scroll listeners default to passive, but custom handlers do not.
+* **Enhancement:** Automatically default touch and wheel event listeners inside components to `{ passive: true }` to enforce Interaction to Next Paint (INP) excellence.
+
+---
+
+## 7. Verification & Telemetry Performance Testing
+
+We verify the event architecture through several layers:
+
+* **Automated Unit Tests:** Assert composition properties, event delegation boundary crossing, and AbortSignal detaching.
+* **INP Measurement:** Utilize the `PerformanceObserver` with `type: 'event'` to guarantee that no event handler blocks the main thread for > 50ms.

package/src/core/events/types/index.js

@@ -0,0 +1,34 @@
+/**
+ * src/core/events/types/index.js
+ *
+ * Centralized System Event Name constants registry.
+ * Maps standard, cross-cutting system telemetry events to prevent typos.
+ *
+ * Source: doc 10 — Event Architecture §10, §11
+ */
+
+export const names = {
+  // Authentication Lifecycle Events
+  auth: {
+    signedin: 'auth:signedin',
+    signedout: 'auth:signedout',
+    refreshed: 'auth:refreshed'
+  },
+
+  // Network Connectivity Lifecycle Events
+  connectivity: {
+    online: 'connectivity:online',
+    offline: 'connectivity:offline'
+  },
+
+  // User Preference Configuration Changes
+  preference: {
+    changed: 'preference:changed'
+  },
+
+  // Service Worker Status and Communication Channels
+  sw: {
+    updated: 'sw:updated',
+    message: 'sw:message'
+  }
+};

package/src/core/events/usage.md

@@ -0,0 +1,107 @@
+# Native Events Usage Guide
+
+The events layer is a thin, memory-safe surface over the platform: a global event
+bus built on `EventTarget`, Shadow-DOM-aware delegation, a promise-based single
+awaiter, a progressive passive listener, and a registry of standard system event
+names. Every subscription supports `AbortSignal` cleanup.
+
+Import from the events entry point:
+
+```javascript
+import { events } from '@adukiorg/anza/events';
+```
+
+Named exports are also available:
+
+```javascript
+import { bus, EventBus, delegate, once, listen, names } from '@adukiorg/anza/events';
+```
+
+## 1. Choosing an API
+
+| Need | Use |
+|---|---|
+| App-wide pub/sub | `events.emit`, `events.on` (or `bus`) |
+| Delegate DOM events | `events.delegate` |
+| Await a single event | `events.once` |
+| Add one passive-safe listener | `events.listen` |
+| Standard event name constants | `events.names` |
+
+## 2. Global bus
+
+```javascript
+const ctrl = new AbortController();
+
+// Subscribe (auto-cleans up when the signal aborts); returns a disposer too.
+const off = events.on('user:purchased', (event) => {
+  const { itemId, price } = event.detail;
+}, ctrl.signal);
+
+events.emit('user:purchased', { itemId: 42, price: 9.99 });
+
+off();          // manual teardown
+ctrl.abort();   // or signal-based teardown
+```
+
+`bus` is an `EventBus extends EventTarget`, so `bus.addEventListener` /
+`bus.dispatchEvent` work too; `bus.on` / `bus.emit` are convenience wrappers.
+
+## 3. Standard names
+
+Use the `names` registry instead of raw strings to avoid typos. Connectivity
+events are emitted automatically by the offline connectivity monitor.
+
+```javascript
+import { events } from '@adukiorg/anza/events';
+
+events.on(events.names.connectivity.offline, () => showOfflineBanner());
+events.on(events.names.connectivity.online,  () => hideOfflineBanner());
+events.on(events.names.auth.signedout,       () => redirectToLogin());
+```
+
+Available groups: `auth` (`signedin`, `signedout`, `refreshed`),
+`connectivity` (`online`, `offline`), `preference` (`changed`),
+`sw` (`updated`, `message`).
+
+## 4. Delegation
+
+`delegate(root, selector, type, handler, options)` attaches a single listener to
+`root` and dispatches to descendants matching `selector`. The handler receives
+`(event, matchedElement)`. Returns a disposer. Crosses Shadow DOM via
+`composedPath()`.
+
+```javascript
+const list = document.querySelector('.users');
+
+const dispose = delegate(list, '.delete', 'click', (event, btn) => {
+  removeUser(btn.dataset.id);
+});
+```
+
+## 5. Single awaiter
+
+`once(target, type, options)` resolves a promise with the next matching event.
+
+```javascript
+await once(dialog, 'close');
+const e = await once(img, 'load', { signal: ctrl.signal });
+```
+
+## 6. Passive-safe listener
+
+`listen(target, type, handler, options)` registers a listener and returns a
+disposer. Scroll-class events (`touchstart`, `touchmove`, `wheel`, `mousewheel`)
+default to `{ passive: true }`; pass `{ passive: false }` to call
+`preventDefault()`.
+
+```javascript
+const stop = listen(window, 'wheel', () => updateParallax());
+listen(el, 'touchmove', onZoom, { passive: false });
+```
+
+## 7. Rules
+
+- Pass `ctrl.signal` (or call the returned disposer) so listeners clean up.
+- Prefer `events.names.*` constants over string literals.
+- Use `delegate` for dynamic lists instead of per-item listeners.
+- Dispatch outward from components with `composed: true` custom events.

package/src/core/offline/bridge.js

@@ -0,0 +1,51 @@
+/**
+ * src/core/offline/bridge.js
+ *
+ * Service Worker Message Bridge.
+ * Establishes a highly concurrent messaging corridor between the main window context
+ * and the active Service Worker using native MessageChannel instances for direct response routing.
+ *
+ * Source: doc 13 — Offline and Background §3
+ */
+
+export class ServiceWorkerBridge {
+  /**
+   * Dispatches a message to the active Service Worker controller, returning a promise.
+   */
+  send(task, payload = null) {
+    if (
+      typeof navigator === 'undefined' ||
+      !navigator.serviceWorker ||
+      !navigator.serviceWorker.controller
+    ) {
+      return Promise.reject(new Error('Active Service Worker controller not found'));
+    }
+
+    return new Promise((resolve, reject) => {
+      const channel = new MessageChannel();
+
+      channel.port1.onmessage = (event) => {
+        channel.port1.close();
+        const { success, result, error } = event.data;
+        if (success) {
+          resolve(result);
+        } else {
+          reject(new Error(error || 'Service Worker message task failed'));
+        }
+      };
+
+      channel.port1.onmessageerror = () => {
+        channel.port1.close();
+        reject(new Error('Deserialization error on Service Worker message channel'));
+      };
+
+      // Direct message post using the target port transferable
+      navigator.serviceWorker.controller.postMessage(
+        { task, payload, port: channel.port2 },
+        [channel.port2]
+      );
+    });
+  }
+}
+
+export const bridge = new ServiceWorkerBridge();