@adukiorg/anza 0.2.0 → 0.2.2

package/src/core/events/missing.md

@@ -1,103 +0,0 @@
-# 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/plan.md

@@ -1,177 +0,0 @@
-# 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/offline/missing.md

@@ -1,89 +0,0 @@
-# Offline Missing Support
-
-This document tracks remaining support, runtime gaps, concurrency constraints, serialization enhancements, and state/storage synchronization work for `src/core/offline`. Implemented behavior belongs in `usage.md` (or core documentation); 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 offline support requirements:
-
-- Statically parse and validate serialized HTTP request bodies.
-- Enforce idempotency key annotations on form submissions at build time.
-
-Naming rules for offline support:
-
-- Prefer one-word files: `connectivity.js`, `queue.js`, `sync.js`, `bridge.js`, `clock.js`, `state.js`, `index.js`.
-- Plural folders: `tests/`, `migrations/`.
-- Single-word methods: `check`, `subscribe`, `push`, `list`, `update`, `delete`, `clear`, `register`, `send`, `tick`.
-- Single-word properties in state: `online`, `status`, `pending`, `actor`, `clock`.
-- Avoid compound names where single words carry full meaning in context.
-
----
-
-## 1. State and Storage Synchronization Gaps
-
-### 1.1. Reactive State Integration
-
-- **Status**: Runtime gap.
-- **Files**:
-  - `src/core/offline/connectivity.js`
-  - `src/core/offline/queue.js`
-  - `src/core/offline/state.js` [NEW]
-  - `src/core/offline/index.js`
-- **Problem**:
-  The connectivity monitor evaluates the network state via HEAD probes but does not expose it reactively using the `core.state` system. The offline queue manages deferred tasks inside IndexedDB but does not publish queue metrics (such as the number of pending tasks). Callers cannot bind UI elements (like sync indicators or queue counters) directly to the reactive state layer.
-- **Expected Support**:
-  - Introduce `src/core/offline/state.js` exposing a reactive `state` store containing:
-    - `online`: boolean indicating connectivity.
-    - `status`: `'online' | 'offline' | 'unknown'` representing current reachability.
-    - `pending`: number of elements currently in the sync queue.
-  - Automatically update `online` and `status` in the state store whenever connectivity changes.
-  - Automatically update `pending` in the state store whenever items are pushed, updated, deleted, or cleared in the queue.
-
-### 1.2. Write-Ahead Journaling and Storage Durability
-
-- **Status**: Durability gap.
-- **Files**:
-  - `src/core/offline/queue.js`
-- **Problem**:
-  The offline queue writes directly to a raw IndexedDB connection (`new Database(...)` from `../storage/idb.js`). It bypasses the crash-durable journaling and quota warnings implemented in the unified `storage` gateway. Under sudden tab closure or power failure, queued tasks may fail to commit or corrupt database state.
-- **Expected Support**:
-  - Integrate `OfflineQueue` with `localStorage`-based write-ahead journaling for queue writes.
-  - Automatically recover/replay uncommitted journal records during offline engine initialization.
-  - Listen to `onQuotaWarning` subscriptions to prevent queue pushes and trigger warning events when client storage usage exceeds 80%.
-
----
-
-## 2. Concurrency and Fallback Coordination Gaps
-
-### 2.1. Web Locks for Cross-Tab Fallback Coordination
-
-- **Status**: Concurrency gap.
-- **Files**:
-  - `src/core/offline/sync.js`
-- **Problem**:
-  On browsers without native Background Sync support (Firefox, Safari), the manual fallback listens for `online` transitions and triggers queue replay via custom event dispatch. In a multi-tab session, all open tabs will simultaneously receive the event and execute `replayQueue()`. This causes redundant HTTP requests, database write conflicts, and out-of-order network replay.
-- **Expected Support**:
-  - Coordinate manual sync replay across tabs using an exclusive Web Lock (`navigator.locks.request`) named `"offline:sync"`.
-  - Only the tab that successfully acquires the lock executes the replay loop, preventing concurrent replay attempts.
-
----
-
-## 3. Logical Clocks and Conflict Resolution Gaps
-
-### 3.1. Lamport Logical Clocks Engine
-
-- **Status**: Architectural gap.
-- **Files**:
-  - `src/core/offline/clock.js` [NEW]
-  - `src/core/offline/index.js`
-- **Problem**:
-  To support reliable offline write replication, every queued operation must be stamped with a tuple of `(actor_id, lamport_timestamp, sequence_number)`. This ensures Last-Write-Wins (LWW) and CRDT merges resolve deterministically regardless of wall-clock drift. Currently, there is no implementation of actor registration or Lamport clock management.
-- **Expected Support**:
-  - Implement a logical Lamport clock engine in `clock.js` exporting:
-    - `actor`: a persistent UUID identifying the current client, stored in unified storage.
-    - `tick()`: increments and returns the local logical clock count.
-    - `sync(remoteTime)`: advances the local logical clock count to be greater than any incoming server/peer clock.

package/src/core/offline/plan.md

@@ -1,143 +0,0 @@
-# Offline & Background Capabilities Architecture Plan
-
-This document outlines the design, implementation, and optimization specifications for the resilient Offline and Background Capabilities engine under `core.offline` and the Service Worker runtime in the `@adukiorg/anza` library.
-
----
-
-## 1. Architectural Strategy & Core Requirements
-
-Our offline-first architecture rests on the principle that **network absence is a normal mode of operation, not an error state**. The architecture decouples the initiation of an operation from its network execution, guaranteeing consistency, durability, and a highly responsive user experience under any connectivity condition.
-
-### Key Pillars
-
-1. **HEAD-Probe Connectivity Monitor (`connectivity.js`):** Resilient monitoring extending browser `navigator.onLine` with debounced, throttled (10s) HEAD probes using cache-busting headers. Support for memory-safe `subscribe` patterns utilizing the dual-cleanup pattern for `AbortSignal` listeners.
-2. **IndexedDB Tasks Journal (`queue.js`):** Chronicled persistent queue leveraging IndexedDB to buffer and serialize background tasks when offline. We will enhance the deserialization module to gracefully stringify plain object payloads when `Content-Type: application/json` is specified, resolving a critical integration mismatch.
-3. **Background Sync & Fallback (`sync.js`):** Native `SyncManager` registrations for Chromium-based browsers, paired with immediate event-driven fallbacks on `online` and custom triggers for Firefox and Safari. Memory-safe `onSyncFallback` listener registrations.
-4. **Service Worker Message Bridge (`bridge.js`):** High-concurrency message corridors utilizing native `MessageChannel` for direct request/response dispatching to the active Service Worker controller.
-5. **FIFO Replay Loop & Dead-Letter Management (`src/sw/sync.js`):** Chronological, sequential task processing with transaction safety, automatic retry limits (max 5), Dead-Letter Queue (DLQ) transitions, and tab-wide success/failure broadcasts.
-6. **Conflict Resolution Architecture:** Standardized conflict resolution guidelines using logical Lamport timestamps `(actor_id, lamport_timestamp, sequence_number)` instead of physical wall clocks, supporting Last-Write-Wins (LWW) registers and Grow-Only (G-Set) or Observed-Remove (OR-Set) CRDT configurations.
-
----
-
-## 2. Component Blueprint & Files Layout
-
-All files inside the offline module strictly adhere to the `RULE[user_global]` lowercase, single-word naming structure:
-
-```
-src/core/offline/
-├── index.js          # Public offline entry point & unified facade
-├── connectivity.js   # Resilient connectivity check and listener subscriptions
-├── queue.js          # Persistent IndexedDB offline task journal
-├── sync.js           # Chromium Background Sync manager & Safari/Firefox online listeners
-├── bridge.js         # Bidirectional MessageChannel Service Worker corridor
-└── plan.md           # This planning document
-```
-
----
-
-## 3. Detailed Component Designs
-
-### 3.1. Resilient Connectivity Prober (`connectivity.js`)
-
-* **HEAD Probe with Cache-Busting:** Performs a rate-limited `fetch` request using the `HEAD` method to the local favicon or a health-check path (`/favicon.ico?_probe=Date.now()`) with `mode: 'no-cors'` and `cache: 'no-store'`.
-* **Shared In-Flight Promise:** Share single active in-flight check promise to prevent redundant parallel network requests.
-* **Leak-Free Dual Abort Cleanup:**
-
-  ```javascript
-  export function subscribe(fn, signal) {
-    if (signal?.aborted) return () => {};
-    listeners.add(fn);
-    fn(isOnline);
-
-    const dispose = () => {
-      listeners.delete(fn);
-      if (signal) {
-        signal.removeEventListener('abort', dispose);
-      }
-    };
-
-    if (signal) {
-      signal.addEventListener('abort', dispose, { once: true });
-    }
-
-    return dispose;
-  }
-  ```
-
-### 3.2. Idempotent Offline Queue (`queue.js`)
-
-* **IndexedDB-Backed Buffer:** Uses the `Database` client from `../storage/idb.js` under the store `tasks` inside `platform-offline-queue`.
-* **JSON Body Deserialization Fix:** In `src/sw/queue.js` (used during SW replay), if the serialized request `body` is not a string, Blob, or ArrayBuffer (e.g. is a plain object written by `ui-form`), it must be stringified if the header is `application/json`.
-
-  ```javascript
-  export function deserializeRequest(serialized) {
-    const options = {
-      method: serialized.method,
-      headers: new Headers(serialized.headers)
-    };
-
-    if (serialized.body) {
-      const isJson = options.headers.get('content-type')?.includes('application/json');
-      if (isJson && typeof serialized.body === 'object' && !(serialized.body instanceof ArrayBuffer) && !(serialized.body instanceof Blob)) {
-        options.body = JSON.stringify(serialized.body);
-      } else {
-        options.body = serialized.body;
-      }
-    }
-
-    return new Request(serialized.url, options);
-  }
-  ```
-
-### 3.3. Background Sync & Fallback Coordinator (`sync.js`)
-
-* **Sync API Registration:** Enqueues a sync tag (e.g., `'pending'`) with the browser's Background Sync API if supported.
-* **Browser-Safe Event Fallbacks:** Hooks into the window's `online` state on Safari/Firefox and dispatches a custom event (`core:sync-fallback`) detailed with the pending tag.
-* **Leak-Free `onSyncFallback`:** Applies the dual-cleanup unsubscription pattern for the `core:sync-fallback` abort listener to prevent memory accumulation in long-lived client tabs.
-
-### 3.4. Service Worker Messaging Corridor (`bridge.js`)
-
-* **Response Channel Routing:** Utilizes transferable `MessageChannel` ports to match worker-side responses back to origin promises, avoiding race conditions in concurrent request dispatching.
-* **State Check:** Gracefully rejects with informative errors if the browser does not support Service Workers or if `navigator.serviceWorker.controller` is absent.
-
----
-
-## 4. Conflict Resolution & Idempotency Guidelines
-
-To resolve concurrent offline edits reliably:
-
-1. **Logical Clocks (Lamport):** Every offline operation writes a tuple `(actor_id, lamport_timestamp, sequence_number)`.
-   * `actor_id`: Persisted UUID of the current device.
-   * `lamport_timestamp`: Monotonically increasing logical count that advances locally and synchronizes on remote data delivery.
-2. **Merge Semantics:**
-   * **LWW-Register:** Scalar fields use Last-Write-Wins based on Lamport comparisons (lexicographical actor ID as a final tiebreaker).
-   * **G-Set & OR-Set:** Collections (e.g. logs, attachment list mutations) use CRDT merge rules to ensure complete commutative, associative, and idempotent finality.
-3. **Idempotency Keys:** Every queued task has an `idempotencyKey` UUID. The replay engine re-submits this key to the server which returns cached responses for duplicates, securing absolute safety across multiple retries.
-
----
-
-## 5. Verification & Testing Strategy
-
-### 5.1. Automated Unit Testing (`tests/core/offline/`)
-
-We will create a comprehensive suite of unit tests validating the offline capabilities:
-
-1. **`connectivity.test.js`**:
-   * Verify rate-limiting and cached status returns within the 10-second window.
-   * Assert `subscribe` triggers immediate callback feed.
-   * Assert that manual disposal and signal abort both clean up correctly without memory leaks.
-2. **`queue.test.js`**:
-   * Assert FIFO ordering on `list()`.
-   * Assert push and delete operations execute successfully on IndexedDB.
-   * Verify that `deserializeRequest` successfully stringifies plain object JSON payloads.
-3. **`sync.test.js`**:
-   * Verify Background Sync registers successfully if supported.
-   * Assert that Safari/Firefox manual online trigger successfully dispatches the `core:sync-fallback` custom event.
-   * Assert `onSyncFallback` correctly registers listeners and cleans up its abort hooks seamlessly.
-4. **`bridge.test.js`**:
-   * Assert that bridge messages throw when controller is absent.
-
-### 5.2. Manual & Network Validation
-
-* Simulating offline states via DevTools and verifying that submissions to `<ui-form>` with the `offline` attribute are correctly buffered inside the IndexedDB queue.
-* Verifying that as soon as the network state recovers, the replayer is triggered and sequentially processes tasks, broadcasting `sync-success` events back to the UI element.

package/src/core/platform/missing.md

@@ -1,119 +0,0 @@
-# Platform Missing Support
-
-This document tracks remaining support, runtime gaps, type mismatches, and storage synchronization improvements for `src/core/platform`. Implemented behavior belongs in `usage.md` (or core documentation); 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 platform support requirements:
-
-- Statically verify polyfill execution branches and eliminate unused polyfills in production builds.
-- Validate lazy-load wrapper targets at build time to prevent dynamic resolution failures.
-- Detect unsupported browser APIs used in application code without corresponding `supports` check.
-
-Naming rules for platform support:
-
-- Prefer one-word files: `supports.js`, `guard.js`, `index.js`.
-- Plural folders: `tests/`, `types/`, `polyfills/`.
-- Single-word methods: `yield` (as `yieldTask`), `urlPattern`, `navigation`, `popover`, `shadow`, `anchor`, `sanitizer`, `scheduler`.
-- Avoid compound names where single words carry full meaning in context.
-
----
-
-## 1. Critical Runtime and Type Gaps
-
-### 1.1. Missing Type Declarations for Guards and Cache Reset
-
-- **Status**: Type mismatch.
-- **Files**:
-  - `types/core/platform/supports.d.ts`
-- **Problem**:
-  The TypeScript definitions are severely limited. They only declare the `supports` object with a small fraction (8 out of 30+) of the actual lazy feature-detection flags. Furthermore, `guard` and `reset` are not typed or exported in the declaration file, despite being public exports in `src/core/platform/index.js`.
-- **Expected Support**:
-  - Complete declarations for all 30+ feature detection keys on `supports`.
-  - Type definitions for `reset(key: string): void`.
-  - Type definitions for the `guard` object, including all feature-gate methods:
-    - `urlPattern(): Promise<typeof URLPattern>`
-    - `navigation(): Promise<Navigation>`
-    - `popover(): Promise<void>`
-    - `shadow(root?: ParentNode): Promise<void>`
-    - `anchor(floating: HTMLElement, anchorEl: HTMLElement, options?: object): Promise<void>`
-    - `sanitizer(): Promise<{ sanitizeToString(input: string): string }>`
-    - `scheduler(): Promise<Scheduler>`
-    - `yield(): Promise<void>`
-
-### 1.2. Missing Critical Storage Feature Flags
-
-- **Status**: Runtime gap.
-- **Files**:
-  - `src/core/platform/supports.js`
-- **Problem**:
-  The `supports` detection registry is missing explicit flags for features utilized by the `storage` gateway, specifically:
-  - `compression`: Checks for `CompressionStream` and `DecompressionStream` (required for transparent record compression in `core/storage`).
-  - `storagePersistence`: Checks for `navigator.storage.persist` and `navigator.storage.persisted` (required for durable storage requests).
-- **Expected Support**:
-  - Implement lazy `compression` detection checking `CompressionStream` and `DecompressionStream` in `globalThis`.
-  - Implement lazy `storagePersistence` detection checking `navigator.storage` properties.
-
----
-
-## 2. Storage Integration & Synchronization Gaps
-
-### 2.1. Direct Browser API Access in Storage Gateway
-
-- **Status**: Code smell & consistency gap.
-- **Files**:
-  - `src/core/storage/index.js`
-  - `src/core/storage/quota.js`
-  - `src/core/storage/opfs.js`
-- **Problem**:
-  The `storage` gateway accesses raw APIs like `CompressionStream`, `localStorage`, and `navigator.storage` directly without consulting the centralized `platform/supports` registry. This creates duplication and makes it impossible to mock feature support in unit tests via `reset()`.
-- **Expected Support**:
-  - Refactor `src/core/storage/index.js` to import `supports` and use `supports.compression` and `supports.storagePersistence`.
-  - Refactor `src/core/storage/quota.js` to rely on `supports.storageManager` and `supports.storagePersistence` instead of doing in-line existence checks.
-  - Refactor `src/core/storage/opfs.js` to verify `supports.opfs` on the main thread prior to worker instantiation, preventing redundant worker start failure.
-
----
-
-## 3. Test Coverage Gaps
-
-### 3.1. Unified Support Matrix & Reset Verification
-
-- **Status**: Test gap.
-- **Files**:
-  - `tests/core/platform/supports.test.js`
-- **Needed Coverage**:
-  - Add assertions for new lazy flags: `compression` and `storagePersistence`.
-  - Verify that mock overrides via `reset()` correctly clear the lazy evaluation cache, permitting feature-detection simulation.
-
-### 3.2. Polyfill Dynamic Loading Fallback Verification
-
-- **Status**: Test gap.
-- **Files**:
-  - `tests/core/platform/guard.test.js`
-- **Needed Coverage**:
-  - Mock supports to `false` for URLPattern, Navigation, and Scheduler.
-  - Call the guards and verify they successfully load the polyfills dynamically and expose functional fallback behaviors.
-
----
-
-## 4. Suggested Implementation Order
-
-1. Implement `compression` and `storagePersistence` lazy detectors in `src/core/platform/supports.js`.
-2. Clean up direct global checks in `src/core/storage/index.js`, `src/core/storage/quota.js`, and `src/core/storage/opfs.js` to use `supports`.
-3. Update `types/core/platform/supports.d.ts` to fully type all `supports`, `guard`, and `reset` methods.
-4. Add verification tests in `tests/core/platform/supports.test.js` and `tests/core/platform/guard.test.js`.
-
----
-
-## 5. Done Criteria
-
-This missing-support list is complete when:
-
-- `supports` exposes `compression` and `storagePersistence` capability flags.
-- `core/storage` uses `supports` instead of direct global feature verification.
-- `types/core/platform/supports.d.ts` is fully populated.
-- Dynamic polyfill fallbacks are tested and pass successfully.