@adukiorg/anza 0.2.0

package/src/core/offline/sync.js

@@ -0,0 +1,106 @@
+/**
+ * src/core/offline/sync.js
+ *
+ * Background Sync Manager.
+ * Registers Service Worker Background Sync descriptors for Chromium-based browsers,
+ * falling back to custom window online-event triggers on Safari and Firefox.
+ *
+ * Source: doc 13 — Offline and Background §4
+ */
+
+import { queue } from './queue.js';
+import { state } from './state.js';
+
+export class SyncManager {
+  constructor() {
+    if (
+      typeof navigator !== 'undefined' &&
+      'serviceWorker' in navigator
+    ) {
+      navigator.serviceWorker.addEventListener('message', async (event) => {
+        const data = event.data;
+        if (data && (data.type === 'sync-success' || data.type === 'sync-failed')) {
+          try {
+            const list = await queue.list();
+            state.set('pending', list.length);
+          } catch (err) {
+            console.error('Failed to sync pending task count on service worker message:', err);
+          }
+        }
+      });
+    }
+  }
+
+  /**
+   * Registers a sync tag with the Service Worker Background Sync API, falling back
+   * to manual online triggers if unsupported.
+   */
+  async register(tag) {
+    if (
+      typeof navigator !== 'undefined' &&
+      'serviceWorker' in navigator
+    ) {
+      try {
+        const registration = await navigator.serviceWorker.ready;
+        if (registration.sync) {
+          await registration.sync.register(tag);
+          return true;
+        }
+      } catch (err) {
+        console.warn('Background Sync registration failed; falling back to listener:', err);
+      }
+    }
+
+    // Resilient fallback for Safari and Firefox
+    if (typeof window !== 'undefined') {
+      const trigger = () => {
+        window.removeEventListener('online', trigger);
+        // Dispatch a custom event detailing the pending tag
+        const event = new CustomEvent('core:sync-fallback', { detail: { tag } });
+        window.dispatchEvent(event);
+      };
+
+      window.addEventListener('online', trigger);
+    }
+    return false;
+  }
+
+  /**
+   * Subscribes to manual sync fallback triggers (useful for executing queue replays on Safari/Firefox).
+   */
+  onSyncFallback(fn, signal) {
+    if (signal?.aborted || typeof window === 'undefined') return () => {};
+
+    const listener = async (event) => {
+      // Coordinated fallback execution using Web Locks
+      if (typeof navigator !== 'undefined' && navigator.locks) {
+        try {
+          await navigator.locks.request('offline:sync', async () => {
+            await fn(event.detail.tag);
+          });
+        } catch (err) {
+          console.error('Failed to execute fallback sync under Web Lock:', err);
+        }
+      } else {
+        await fn(event.detail.tag);
+      }
+    };
+    window.addEventListener('core:sync-fallback', listener);
+
+    const dispose = () => {
+      window.removeEventListener('core:sync-fallback', listener);
+      if (signal) {
+        signal.removeEventListener('abort', dispose);
+      }
+    };
+
+    if (signal) {
+      signal.addEventListener('abort', dispose, { once: true });
+    }
+
+    return dispose;
+  }
+}
+
+export const sync = new SyncManager();
+

package/src/core/offline/usage.md

@@ -0,0 +1,273 @@
+# Offline & Background Capabilities Usage Guide
+
+The Native Offline layer provides tools for building local-first, network-resilient web applications. It encapsulates reactive connectivity state tracking, crash-resilient IndexedDB task queuing with write-ahead journaling, Web Lock-coordinated manual sync fallbacks, direct Service Worker bridge communication, and monotonic logical Lamport clocks for conflict-free replication.
+
+Import from the offline entry point:
+
+```javascript
+import { offline } from '@adukiorg/anza/offline';
+```
+
+Or import individual components directly:
+
+```javascript
+import { check, subscribe, queue, sync, bridge, state, clock } from '@adukiorg/anza/offline';
+```
+
+---
+
+## 1. Choosing an API
+
+| Need | Use |
+|---|---|
+| Query network connectivity | `check` |
+| Subscribe to network status events | `subscribe` |
+| Get current network/queue state | `state.get` or `state.snapshot` |
+| Subscribe to reactive state updates | `state.subscribe` |
+| Enqueue a background sync task | `queue.push` |
+| List chronological tasks in the queue | `queue.list` |
+| Update task status or retry count | `queue.update` |
+| Evict a resolved task from the queue | `queue.delete` |
+| Clear the entire offline queue | `queue.clear` |
+| Register background sync tags | `sync.register` |
+| Coordinate manual fallback sync | `sync.onSyncFallback` |
+| Send messages to Service Worker | `bridge.send` or `offline.send` |
+| Retrieve client persistent actor ID | `clock.actor` |
+| Monotonically tick local clock counter | `clock.tick` |
+| Sync local clock against remote time | `clock.sync` |
+| Generate logical clock stamp | `clock.stamp` |
+
+---
+
+## 2. Connectivity & State Tracking
+
+The connectivity module handles network status monitoring and reachability checks.
+
+### Checking Connectivity
+The `check(force?)` function checks network reachability. It automatically rate-limits HEAD probes to `/favicon.ico` (cached for 10 seconds) to avoid thrashing the network. Pass `true` to bypass throttling.
+
+```javascript
+// Perform a throttled connectivity check
+const online = await check();
+
+// Force an immediate probe, bypassing the 10s throttling window
+const absoluteOnline = await check(true);
+```
+
+### Event Subscriptions
+Use `subscribe(callback, signal?)` to listen to connectivity status changes. You can pass an optional `AbortSignal` for automated unsubscription.
+
+```javascript
+const controller = new AbortController();
+
+const dispose = subscribe((online) => {
+  console.log(online ? 'Connected' : 'Disconnected');
+}, controller.signal);
+
+// Unsubscribe manually
+dispose();
+
+// Or automatically clean up by aborting the controller
+controller.abort();
+```
+
+### Reactive State Store
+The `state` store is a fine-grained `ReactiveStore` keeping track of network connectivity metrics and task queue length:
+* `online` (boolean): Whether the client is currently online.
+* `status` (string): `'online' | 'offline' | 'unknown'`.
+* `pending` (number): Monitored count of uncompleted tasks in the queue.
+
+```javascript
+// Subscribe to reactive key mutations
+state.subscribe('pending', (count) => {
+  console.log(`Pending offline tasks: ${count}`);
+});
+
+// Access current state snapshot
+const snapshot = state.snapshot();
+console.log(`Status: ${snapshot.status}, Online: ${snapshot.online}`);
+```
+
+---
+
+## 3. Persistent Task Queue (`OfflineQueue`)
+
+The offline queue is backed by IndexedDB (`platform-offline-queue` / `tasks`). It preserves causal chronological sequencing (FIFO) and is protected by write-ahead journaling.
+
+### Enqueuing Tasks
+Use `queue.push(taskName, payload?, options?)` to add tasks to the offline queue. If local client storage usage exceeds 80%, the write is blocked and throws a `QuotaExceededError`.
+
+```javascript
+try {
+  const taskId = await queue.push(
+    'order:submit',
+    { itemId: 42, quantity: 2 },
+    {
+      idempotencyKey: 'order-c104', // Optional: defaults to a random UUID
+      maxRetries: 3                  // Optional: defaults to 5
+    }
+  );
+  console.log('Task buffered with ID:', taskId);
+} catch (err) {
+  if (err.name === 'QuotaExceededError') {
+    console.error('Storage full. Clear space before enqueuing.');
+  }
+}
+```
+
+### Managing Tasks
+Retrieve, update, and delete tasks from the queue as they are processed:
+
+```javascript
+// List all queued tasks sorted chronologically (oldest first)
+const tasks = await queue.list();
+
+for (const task of tasks) {
+  if (task.failed) {
+    console.warn(`Task permanently failed: ${task.error}`);
+    await queue.delete(task.id); // Evict from queue
+    continue;
+  }
+
+  try {
+    // Process the task...
+    await queue.delete(task.id);
+  } catch (err) {
+    task.retries++;
+    if (task.retries >= task.maxRetries) {
+      task.failed = true;
+      task.error = err.message;
+    }
+    await queue.update(task); // Persist updated state
+  }
+}
+
+// Clear the entire queue
+await queue.clear();
+```
+
+---
+
+## 4. Background Sync & Fallbacks
+
+The `sync` manager coordinates queue replays using native browser Background Sync or event-driven fallbacks.
+
+### Registering Sync Events
+Register sync tags with the Service Worker Background Sync API. On browsers without Background Sync support (e.g. Safari, Firefox), the manager registers a custom window-level online fallback listener.
+
+```javascript
+const registered = await sync.register('pending');
+if (registered) {
+  console.log('Native service worker background sync registered.');
+} else {
+  console.log('Safari/Firefox fallback online listener registered.');
+}
+```
+
+### Web Lock Coordinated Fallback
+When a fallback online event fires in multi-tab sessions, all tabs simultaneously receive the event. To prevent concurrent database access and duplicate HTTP requests, the callback is automatically coordinated under an exclusive Web Lock named `"offline:sync"`.
+
+Only one active tab will acquire the lock and execute the sync handler:
+
+```javascript
+const controller = new AbortController();
+
+const dispose = sync.onSyncFallback(async (tag) => {
+  // Awaiting Web Lock 'offline:sync' is handled internally
+  console.log(`Replaying queue for tag: ${tag}`);
+  
+  // Replay tasks chronologically...
+}, controller.signal);
+```
+
+---
+
+## 5. Service Worker Bridge
+
+The `bridge` facilitates direct message dispatch to the active Service Worker controller using native `MessageChannel` instances for response routing.
+
+```javascript
+// Dispatch a task to the service worker and wait for a response
+try {
+  const result = await bridge.send('cache:precache', {
+    urls: ['/index.html', '/styles.css']
+  });
+  console.log('Precached files successfully:', result);
+} catch (err) {
+  console.error('Service worker message failed:', err.message);
+}
+
+// Shorthand syntax using the offline facade
+await offline.send('sync:force');
+```
+
+---
+
+## 6. Logical Lamport Clocks
+
+Distributed local-first applications cannot rely on physical clocks due to device clock drift. The `clock` manager implements logical Lamport clocks to stamp offline mutations, ensuring Last-Write-Wins (LWW) resolution is perfectly deterministic.
+
+```javascript
+import { clock } from '@adukiorg/anza/offline';
+
+// 1. Retrieve the local client's persistent actor UUID
+const clientUUID = await clock.actor();
+
+// 2. Monotonically increment and get the local logical clock
+const time = await clock.tick();
+
+// 3. Sync the local clock when observing a remote logical counter (e.g. from server response headers)
+// Automatically advances the local clock to be greater than the observed remote counter
+const syncedTime = await clock.sync(120);
+
+// 4. Generate a combined logical stamp tuple
+const stamp = await clock.stamp();
+// Returns: { actor: "b9a2-...", clock: 121 }
+```
+
+### Deterministic LWW Resolution
+Compare logical stamps during data conflict merges:
+* The stamp with the higher `clock` counter wins.
+* If `clock` counters are equal, the lexicographically greater `actor` UUID acts as the tiebreaker.
+
+---
+
+## 7. Web Component Integration
+
+The offline modules integrate seamlessly with the declarative `@adukiorg/anza` UI elements framework. The component's `mount` hook receives an `AbortController` (`ctrl`) that is automatically aborted when the element is disconnected from the DOM, resolving all subscriber memory safety concerns.
+
+```javascript
+import { ui } from '@adukiorg/anza/ui';
+import { check, queue, sync, state } from '@adukiorg/anza/offline';
+
+ui.element('offline-status-banner', {
+  template: `
+    <div class="banner">
+      <span class="message"></span>
+      <span class="count"></span>
+    </div>
+  `,
+  style: `
+    .banner { display: none; padding: 1rem; text-align: center; }
+    .banner.active { display: block; }
+  `,
+
+  mount({ el, ctrl }) {
+    const { signal } = ctrl;
+    const container = el.shadowRoot.querySelector('.banner');
+    const message = el.shadowRoot.querySelector('.message');
+    const countSpan = el.shadowRoot.querySelector('.count');
+
+    // Subscribe to connectivity status changes reactively
+    state.subscribe('online', (online) => {
+      container.classList.toggle('active', !online);
+      message.textContent = online ? '' : 'You are working offline.';
+    }, signal);
+
+    // Track pending queue count reactively
+    state.subscribe('pending', (count) => {
+      countSpan.textContent = count > 0 ? `(${count} changes pending)` : '';
+    }, signal);
+  }
+});
+```

package/src/core/platform/guard.js

@@ -0,0 +1,104 @@
+/**
+ * core/platform/guard.js
+ *
+ * Feature-gate wrapper and lazy polyfill loader.
+ * Ensures caller experiences uniform APIs regardless of native vs polyfill support.
+ * Source: doc 18 §12, library2.md §Phase 1-A
+ */
+
+import { supports } from './supports.js';
+
+export async function urlPattern() {
+  if (supports.urlPattern) {
+    return globalThis.URLPattern;
+  }
+  const { default: polyfill } = await import('./polyfills/urlpattern.js');
+  return polyfill;
+}
+
+export async function navigation() {
+  if (supports.navigationAPI) {
+    return globalThis.navigation;
+  }
+  await import('./polyfills/navigation.js');
+  return globalThis.navigation;
+}
+
+export async function popover() {
+  if (supports.popoverAPI) return;
+  await import('./polyfills/popover.js');
+}
+
+export async function shadow(root = document) {
+  if (supports.declarativeShadowDOM) return;
+  const { apply } = await import('./polyfills/shadow.js');
+  apply(root);
+}
+
+export async function anchor(floating, anchorEl, options = {}) {
+  if (supports.anchorPositioning) {
+    // Native CSS Anchor positioning handles this; no script action needed.
+    return;
+  }
+  const { position } = await import('./polyfills/anchor.js');
+  position(floating, anchorEl, options);
+}
+
+export async function sanitizer() {
+  if (supports.sanitizerAPI && typeof globalThis.Sanitizer === 'function') {
+    try {
+      const s = new globalThis.Sanitizer();
+      if (typeof s.sanitize === 'function') {
+        return {
+          sanitizeToString(input) {
+            const temp = document.createElement('div');
+            temp.innerHTML = input;
+            const fragment = s.sanitize(temp);
+            const wrapper = document.createElement('div');
+            wrapper.appendChild(fragment);
+            return wrapper.innerHTML;
+          }
+        };
+      }
+    } catch {
+      // Fallback if construction fails
+    }
+  }
+  // Lightweight DOMPurify / Sanitizer standard fallback
+  return {
+    sanitizeToString(input) {
+      if (typeof DOMPurify !== 'undefined') {
+        return DOMPurify.sanitize(input);
+      }
+      // Fail-safe simple string sanitizer
+      const temp = document.createElement('div');
+      temp.textContent = input;
+      return temp.innerHTML;
+    }
+  };
+}
+
+export async function scheduler() {
+  if (supports.schedulerPostTask) {
+    return globalThis.scheduler;
+  }
+  await import('./polyfills/scheduler.js');
+  return globalThis.scheduler;
+}
+
+export async function yieldTask() {
+  const s = await scheduler();
+  return s.yield();
+}
+
+export default {
+  urlPattern,
+  navigation,
+  popover,
+  shadow,
+  anchor,
+  sanitizer,
+  scheduler,
+  yield: yieldTask
+};
+

package/src/core/platform/index.js

@@ -0,0 +1,42 @@
+/**
+ * core/platform/index.js
+ *
+ * Public platform module entry.
+ * Re-exports supports detection registry and the lazy-load guard,
+ * while eagerly bootstrapping necessary global environment polyfills.
+ * Source: doc 18 §12, library2.md §Phase 1-A
+ */
+
+import { supports, reset, typeGuard } from './supports.js';
+import guard from './guard.js';
+
+// Bootstrapping of critical global environment gaps
+if (typeof window !== 'undefined') {
+  if (!supports.declarativeShadowDOM) {
+    import('./polyfills/shadow.js').catch(err => {
+      console.error('Failed to eagerly bootstrap shadow polyfill:', err);
+    });
+  }
+  if (!supports.popoverAPI) {
+    import('./polyfills/popover.js').catch(err => {
+      console.error('Failed to eagerly bootstrap popover polyfill:', err);
+    });
+  }
+  if (!supports.urlPattern) {
+    import('./polyfills/urlpattern.js').catch(err => {
+      console.error('Failed to eagerly bootstrap URLPattern polyfill:', err);
+    });
+  }
+  if (!supports.navigationAPI) {
+    import('./polyfills/navigation.js').catch(err => {
+      console.error('Failed to eagerly bootstrap Navigation polyfill:', err);
+    });
+  }
+  if (!supports.schedulerPostTask) {
+    import('./polyfills/scheduler.js').catch(err => {
+      console.error('Failed to eagerly bootstrap Scheduler polyfill:', err);
+    });
+  }
+}
+
+export { supports, reset, typeGuard, guard };

package/src/core/platform/missing.md

@@ -0,0 +1,119 @@
+# 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.