@adukiorg/anza 0.2.0

package/src/core/storage/opfs.js

@@ -0,0 +1,190 @@
+/**
+ * src/core/storage/opfs.js
+ *
+ * Origin Private File System Façade.
+ * Offloads OPFS operations to an inline dedicated Web Worker to leverage
+ * high-performance synchronous file access handles (`createSyncAccessHandle`).
+ * Broadcasts cross-tab invalidations via standard BroadcastChannel.
+ *
+ * Source: doc 22 — Storage Architecture §4
+ */
+import { supports } from '../platform/index.js';
+import { uuid } from '../security/index.js';
+const workerCode = `
+  self.onmessage = async (e) => {
+    const { id, op, key, value } = e.data;
+    try {
+      const root = await navigator.storage.getDirectory();
+
+      if (op === 'set') {
+        const fileHandle = await root.getFileHandle(key, { create: true });
+        const accessHandle = await fileHandle.createSyncAccessHandle();
+        const encoder = new TextEncoder();
+        const buffer = encoder.encode(JSON.stringify(value));
+
+        accessHandle.truncate(0);
+        accessHandle.write(buffer);
+        accessHandle.close();
+
+        self.postMessage({ id, success: true });
+      } else if (op === 'get') {
+        try {
+          const fileHandle = await root.getFileHandle(key);
+          const accessHandle = await fileHandle.createSyncAccessHandle();
+          const size = accessHandle.getSize();
+
+          if (size === 0) {
+            accessHandle.close();
+            self.postMessage({ id, success: true, value: null });
+            return;
+          }
+
+          const buffer = new Uint8Array(size);
+          accessHandle.read(buffer);
+          accessHandle.close();
+
+          const decoder = new TextDecoder();
+          const parsed = JSON.parse(decoder.decode(buffer));
+          self.postMessage({ id, success: true, value: parsed });
+        } catch (err) {
+          if (err.name === 'NotFoundError') {
+            self.postMessage({ id, success: true, value: null });
+          } else {
+            throw err;
+          }
+        }
+      } else if (op === 'delete') {
+        try {
+          await root.removeEntry(key);
+          self.postMessage({ id, success: true });
+        } catch (err) {
+          if (err.name === 'NotFoundError') {
+            self.postMessage({ id, success: true });
+          } else {
+            throw err;
+          }
+        }
+      } else if (op === 'clear') {
+        for await (const name of root.keys()) {
+          await root.removeEntry(name);
+        }
+        self.postMessage({ id, success: true });
+      } else if (op === 'list') {
+        const list = [];
+        for await (const name of root.keys()) {
+          list.push(name);
+        }
+        self.postMessage({ id, success: true, value: list });
+      }
+    } catch (err) {
+      self.postMessage({ id, success: false, error: err.message });
+    }
+  };
+`;
+
+class OpfsManager {
+  #worker = null;
+  #pending = new Map();
+  #channel = null;
+
+  constructor() {
+    if (typeof window !== 'undefined' && supports.opfs) {
+      const blob = new Blob([workerCode], { type: 'application/javascript' });
+      this.#worker = new Worker(URL.createObjectURL(blob));
+      this.#channel = new BroadcastChannel('core:opfs-invalidation');
+
+      this.#worker.onmessage = (e) => {
+        const { id, success, value, error } = e.data;
+        const promise = this.#pending.get(id);
+        if (promise) {
+          this.#pending.delete(id);
+          if (success) {
+            promise.resolve(value);
+          } else {
+            promise.reject(new Error(error));
+          }
+        }
+      };
+    }
+  }
+
+  #lock(name, callback) {
+    if (typeof navigator !== 'undefined' && navigator.locks) {
+      return navigator.locks.request(name, callback);
+    }
+    return callback();
+  }
+
+  #send(op, key, value) {
+    if (!this.#worker) return Promise.reject(new Error('OPFS not supported in this context'));
+
+    const id = uuid();
+    return new Promise((resolve, reject) => {
+      this.#pending.set(id, { resolve, reject });
+      this.#worker.postMessage({ id, op, key, value });
+    });
+  }
+
+  /**
+   * Reads a file entry from OPFS.
+   */
+  get(key) {
+    return this.#lock(`opfs:${key}`, () => this.#send('get', key));
+  }
+
+  /**
+   * Writes a file entry to OPFS and broadcasts an invalidation.
+   */
+  set(key, value) {
+    return this.#lock(`opfs:${key}`, () => this.#send('set', key, value).then(() => {
+      this.#channel?.postMessage({ op: 'set', key });
+    }));
+  }
+
+  /**
+   * Deletes a file entry from OPFS.
+   */
+  delete(key) {
+    return this.#lock(`opfs:${key}`, () => this.#send('delete', key).then(() => {
+      this.#channel?.postMessage({ op: 'delete', key });
+    }));
+  }
+
+  /**
+   * Clears all entries in OPFS.
+   */
+  clear() {
+    return this.#lock('opfs:global', () => this.#send('clear').then(() => {
+      this.#channel?.postMessage({ op: 'clear' });
+    }));
+  }
+
+  /**
+   * Lists all entry names in OPFS.
+   */
+  list() {
+    return this.#send('list');
+  }
+
+  /**
+   * Subscribes to write invalidations.
+   */
+  onChange(fn, signal) {
+    if (signal?.aborted) return () => {};
+
+    const listener = (event) => fn(event.data);
+    this.#channel?.addEventListener('message', listener);
+
+    const dispose = () => {
+      this.#channel?.removeEventListener('message', listener);
+    };
+
+    if (signal) {
+      signal.addEventListener('abort', dispose);
+    }
+
+    return dispose;
+  }
+}
+
+export const opfs = new OpfsManager();

package/src/core/storage/plan.md

@@ -0,0 +1,69 @@
+# Storage Engine Architecture Plan
+
+This document outlines the blueprint for the local-first Multi-Tier Storage Gateway within `core.storage`, mapping memory LRU, IndexedDB, Cache API, and Origin Private File System (OPFS) under a unified tiered facade.
+
+---
+
+## 1. Architectural Architecture & Requirements
+
+We will structure `core.storage` to provide:
+1. **Tiered Storage Architecture:** Clean separation of data structures into Memory LRU (transient, near-instant), IndexedDB (default transactional storage), Cache API (Request/Response persistence), and OPFS (high-performance synchronous file systems).
+2. **Synchronous Storage Ban:** Prevent performance-degrading synchronous operations (like blocking localStorage reads) in user interaction loops to keep the Interaction to Next Paint (INP) score pristine.
+3. **Dedicated Web Worker Offloading:** Route heavy OPFS synchronous file operations (using `FileSystemSyncAccessHandle`) to a background Dedicated Web Worker to eliminate main thread contention.
+4. **Cross-Tab Invalidation:** Broadcast storage mutations across tabs in real-time utilizing a native `BroadcastChannel` named `core:opfs-invalidation` or namespace channels.
+5. **Quota Governance & Self-Healing:** Integrate the browser's native `StorageManager` to monitor space estimates, query persistence, request persistent storage (`navigator.storage.persist()`), and fire events on 80% quota usage limits.
+
+---
+
+## 2. Directory Layout & Core Components
+
+Following `RULE[user_global]`, the storage components are flat and named using lowercase:
+
+```
+src/core/storage/
+├── index.js          # Unified Storage Gateway Entry (core.storage)
+├── idb.js            # Promise-wrapped transactional IndexedDB client
+├── lru.js            # Least-Recently-Used & WeakRef memory caching stores
+├── opfs.js           # Dedicated Web Worker coordinator for OPFS access
+├── quota.js          # StorageManager quota checks and persistence control
+└── plan.md           # This planning blueprint
+```
+
+---
+
+## 3. Technical Blueprint & Multi-Tier Mapping
+
+### Tier Performance Matrix
+
+| Tier | API Backend | Performance | Thread Scoped | Use Case |
+|---|---|---|---|---|
+| `memory` | Map / WeakRef | Sub-microsecond | Main / Worker | Ephemeral/transient cache |
+| `idb` | IndexedDB | 1ms – 5ms | Main / Worker | Structured user/document databases |
+| `cache` | Cache API | 2ms – 10ms | Main / Worker | Offline Request/Response caching |
+| `opfs` | OPFS Access Handle | Sub-millisecond | Dedicated Worker | Large sequential writes, SQLite storage |
+
+### Unified Storage Gateway Contracts
+
+```javascript
+// src/core/storage/index.js
+export const storage = {
+  async get(key, tier = 'idb') { ... },
+  async set(key, value, tier = 'idb', ttl = null) { ... },
+  async delete(key, tier = 'idb') { ... },
+  async list(tier = 'idb') { ... },
+  async clear(tier = 'all') { ... }
+};
+```
+
+---
+
+## 4. Verification Plan
+
+### Automated Verification
+- Verify database migrations run sequentially on database opening without skipping steps.
+- Validate that WeakRef memory cache recovers objects when available and handles garbage collection gracefully under memory pressure.
+- Confirm background Dedicated Worker file operations complete correctly without stalling the main thread.
+- Assert that cross-tab signals are successfully broadcasted and received during file operations.
+
+### Quota Checks
+- Validate that the quota manager detects when usage climbs past 80% and fires an eviction warning event.

package/src/core/storage/quota.js

@@ -0,0 +1,69 @@
+/**
+ * src/core/storage/quota.js
+ *
+ * Storage Quota Manager.
+ * Wraps browser StorageManager API, providing space estimations,
+ * persistence requests, and an active 80% usage eviction warning trigger.
+ *
+ * Source: doc 22 — Storage Architecture §6
+ */
+
+import { supports } from '../platform/index.js';
+
+export class QuotaManager {
+  #listeners = new Set();
+
+  /**
+   * Subscribes a handler to quota warning events.
+   */
+  onQuotaWarning(handler) {
+    this.#listeners.add(handler);
+    return () => {
+      this.#listeners.delete(handler);
+    };
+  }
+
+  /**
+   * Fetches the current storage usage and quota estimates.
+   */
+  async estimate() {
+    if (supports.storageManager && navigator.storage?.estimate) {
+      return navigator.storage.estimate();
+    }
+    return { usage: 0, quota: 0 };
+  }
+
+  /**
+   * Requests the browser to allow persistent storage (avoiding auto-eviction).
+   */
+  async persist() {
+    if (supports.storagePersistence) {
+      return navigator.storage.persist();
+    }
+    return false;
+  }
+
+  /**
+   * Assesses usage against the threshold. Calls trigger hook if capacity > 80%.
+   */
+  async check(onEvictionWarning) {
+    const { usage, quota } = await this.estimate();
+    if (quota > 0 && usage / quota > 0.8) {
+      const data = { usage, quota };
+      if (typeof onEvictionWarning === 'function') {
+        onEvictionWarning(data);
+      }
+      for (const listener of this.#listeners) {
+        try {
+          listener(data);
+        } catch (err) {
+          console.error('Error invoking quota warning listener:', err);
+        }
+      }
+      return true;
+    }
+    return false;
+  }
+}
+
+export const quota = new QuotaManager();

package/src/core/storage/usage.md

@@ -0,0 +1,226 @@
+# Native Storage Usage Guide
+
+The Native Storage layer provides a unified, multi-tiered browser storage gateway mapping memory (LRU), IndexedDB (IDB), Origin Private File System (OPFS), and Cache API storage tiers to a single consistent interface. It integrates transparent gzipped compression, write-ahead journaling for crash durability, multi-tab Web Locks serialization, database upgrade upgrade-blocking listeners, and proactive quota estimates.
+
+Import from the storage entry point:
+
+```javascript
+import { storage } from '@adukiorg/anza/storage';
+```
+
+Or import individual adapters directly:
+
+```javascript
+import { Database, LRUCache, WeakLRUCache } from '@adukiorg/anza/storage';
+```
+
+---
+
+## 1. Choosing an API
+
+| Need | Tier / API | Characteristics |
+|---|---|---|
+| In-memory caching | `'memory'` | Synchronous, ephemeral, size-bounded LRU |
+| General structured data | `'idb'` (default) | Asynchronous, persistent, transactional, compressed if >64KB |
+| High-performance files | `'opfs'` | Dedicated worker, synchronous I/O access handles, Web Locked |
+| HTTP request caching | `'cache'` | Response payloads, Cache API, custom headers, TTL support |
+| Check space usage | `storage.estimate()` | Proactive quota assessment, persisted flag |
+| Request persistence | `storage.persist()` | Prevents automatic browser-driven eviction |
+
+---
+
+## 2. Configuration
+
+The default pool (`platform-db`, a 200-entry LRU, `platform-cache`) works out of
+the box. Call `storage.configure(...)` once, before first use, to customize it.
+
+```javascript
+storage.configure({
+  idb:   { name: 'app-db', version: 2, migrations: [
+            (db) => db.createObjectStore('keyval'),
+            (db) => db.createObjectStore('users')
+          ] },
+  lru:   { maxSize: 500 },
+  cache: { name: 'app-cache' }
+});
+```
+
+## 3. Gateway Operations
+
+The primary storage gateway exposes five main methods: `get`, `set`, `delete`, `list`, and `clear`.
+
+### Set
+
+Writes an item to the designated tier. If tier is omitted, writes to `'idb'` (IndexedDB) and caches it in memory. The 2nd argument may be a tier string or an options object `{ tier, ttl }`.
+
+```javascript
+// Simple key-value write (defaults to idb)
+await storage.set('user:session', { token: 'abc' });
+
+// Options object form (preferred when you need a TTL)
+await storage.set('temp:config', { theme: 'dark' }, { tier: 'memory', ttl: 5000 });
+
+// Tier string form
+await storage.set('temp:config', { theme: 'dark' }, 'memory');
+
+// TTL is honored across ALL tiers (memory, cache, idb, opfs)
+await storage.set('draft', payload, { tier: 'idb',  ttl: 60_000 });
+await storage.set('scratch', blob, { tier: 'opfs', ttl: 60_000 });
+
+// OPFS write (no expiry)
+await storage.set('documents/resume.pdf', arrayBuffer, 'opfs');
+
+// Cache API HTTP request caching with TTL
+await storage.set('https://api.example.com/data', apiResponse, { tier: 'cache', ttl: 60000 });
+```
+
+Expired idb/opfs entries are removed transparently on the next read.
+
+### Get
+
+Retrieves an item from the designated tier. If tier is omitted, default reads check memory first, then fall back to IndexedDB.
+
+```javascript
+// Default read (memory -> IndexedDB fallback)
+const session = await storage.get('user:session');
+
+// Tier-specific reads
+const config = await storage.get('temp:config', 'memory');
+const doc = await storage.get('documents/resume.pdf', 'opfs');
+const response = await storage.get('https://api.example.com/data', 'cache');
+```
+
+### Delete
+
+Removes a key from the storage pool.
+
+```javascript
+await storage.delete('user:session');
+await storage.delete('documents/resume.pdf', 'opfs');
+```
+
+### List
+
+Lists keys stored in the requested tier.
+
+```javascript
+const idbKeys = await storage.list('idb');
+const opfsFiles = await storage.list('opfs');
+```
+
+### Clear
+
+Wipes the storage pool for a specific tier or all.
+
+```javascript
+// Wipe all tiers
+await storage.clear('all');
+
+// Wipe a specific tier
+await storage.clear('opfs');
+```
+
+---
+
+## 4. Multi-Store Transactions
+
+For executing multi-store IndexedDB operations inside a single transactional block:
+
+```javascript
+await storage.transaction(['keyval', 'users'], 'readwrite', (store, tx) => {
+  const keyvalStore = store('keyval');
+  const usersStore = store('users');
+
+  keyvalStore.put({ id: 1 }, 'lastActive');
+  usersStore.put({ id: 100, name: 'Alice' }, '100');
+});
+```
+
+> [!WARNING]
+> Transactions auto-commit once control returns to the event loop. Avoid calling slow asynchronous operations (like `await fetch`) inside the transaction callback, as they cause transactions to commit prematurely.
+
+---
+
+## 5. Concurrency Coordination
+
+### Web Locks for OPFS
+The Origin Private File System does not serialize cross-tab operations natively. The storage gateway automatically wraps all OPFS file reads and writes inside exclusive Web Locks:
+- Reads/writes to a file named `report.json` acquire lock `opfs:report.json`.
+- Global operations like `clear()` acquire lock `opfs:global`.
+
+This prevents concurrent write collisions and lock errors across active tabs.
+
+---
+
+## 6. Upgrade Blocking Coordination
+
+When performing schema upgrades, sibling tabs holding active connections can block migrations indefinitely:
+- **Blocked Notification:** If an upgrade is blocked, the gateway dispatches a global `'storage:blocked'` window event.
+- **Graceful Cleanup:** If another tab requests an upgrade, active connections listen for the `'versionchange'` event, immediately close themselves, and dispatch a global `'storage:versionchange'` window event.
+
+```javascript
+window.addEventListener('storage:blocked', (e) => {
+  console.warn(`Database upgrade blocked: ${e.detail.name}`);
+});
+
+window.addEventListener('storage:versionchange', (e) => {
+  console.warn(`Database connection closed to allow upgrade in another tab: ${e.detail.name}`);
+});
+```
+
+---
+
+## 7. Transparent Compression
+
+To conserve quota and reduce serialization overhead, records exceeding the `compressionThreshold` (default: 64KB) are automatically gzipped using the browser's native `CompressionStream` API before writing to IndexedDB:
+
+```javascript
+// Adjust the compression boundary if needed
+storage.compressionThreshold = 32 * 1024; // 32KB
+
+// Large dataset (>64KB) gets compressed automatically
+await storage.set('large:dataset', largePayload, 'idb');
+
+// Reads automatically decompress the record transparently
+const dataset = await storage.get('large:dataset', 'idb');
+```
+
+---
+
+## 8. Write Journaling
+
+To protect transaction commits from unexpected tab crashes or power cuts, IndexedDB writes use a synchronous write-ahead journal stored in `localStorage`:
+1. The payload is written to `localStorage` under `storage:journal:${key}`.
+2. The IndexedDB write executes asynchronously.
+3. Upon completion, the journal entry is deleted from `localStorage`.
+4. On next boot, the system automatically checks for pending journals and replays them to prevent data loss.
+
+---
+
+## 9. Quota warnings
+
+Subscribe to quota alerts to proactively warn users when browser storage utilization exceeds 80%:
+
+```javascript
+const dispose = storage.onQuotaWarning(({ usage, quota }) => {
+  console.warn(`Storage space warning: ${(usage / quota * 100).toFixed(1)}% full.`);
+});
+
+// To unsubscribe
+dispose();
+```
+
+---
+
+## 10. Advanced Queries
+
+Query IndexedDB using indexes, ranges, cursors, direction and limits:
+
+```javascript
+const records = await storage.query('users', {
+  index: 'byAge',
+  range: IDBKeyRange.bound(18, 30),
+  direction: 'prev',
+  limit: 20
+});
+```

package/src/core/ui/base.js

@@ -0,0 +1,50 @@
+/**
+ * src/core/ui/base.js
+ *
+ * Web Component HTMLElement Base.
+ * Automatically initializes a unified lifecycle AbortController (`this.ctrl`)
+ * inside connectedCallback and aborts it in disconnectedCallback to secure
+ * all dynamic event and stream subscriptions against memory leaks.
+ *
+ * Source: doc 04 — Web Components §1, §6
+ */
+
+export class BaseElement extends HTMLElement {
+  constructor() {
+    super();
+    this.ctrl = null;
+  }
+
+  /**
+   * Invoked when the element is appended to the DOM.
+   * Async mount rejections are caught to prevent unhandled promise rejections
+   * on raw BaseElement subclasses.
+   */
+  connectedCallback() {
+    this.ctrl = new AbortController();
+    Promise.resolve(this.mount()).catch((err) => {
+      console.error('[Native UI] mount failed:', err);
+    });
+  }
+
+  /**
+   * Invoked when the element is detached from the DOM.
+   */
+  disconnectedCallback() {
+    this.unmount();
+    if (this.ctrl) {
+      this.ctrl.abort();
+      this.ctrl = null;
+    }
+  }
+
+  /**
+   * Lifecycle mount hook. Overridden by child custom elements to bind listeners.
+   */
+  mount() {}
+
+  /**
+   * Lifecycle unmount hook. Overridden by child custom elements to perform cleanups.
+   */
+  unmount() {}
+}

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

@@ -0,0 +1,82 @@
+import { router } from '../../router/index.js';
+import { element } from './element.js';
+
+/**
+ * High-performance declarative routing container factory.
+ * Wraps ui.element with strict layout guard lifecycles and element-scoped view transitions.
+ */
+export function container(tag, spec, base = import.meta.url) {
+  // Inject default contain: layout styling required for element-scoped View Transitions
+  const containerStyle = ':host { contain: layout; display: block; }';
+  spec.style = spec.style ? `${containerStyle}\n${spec.style}` : containerStyle;
+
+  // Intercept mount to strictly register the singleton layout container
+  const originalMount = spec.mount;
+  spec.mount = (ctx) => {
+    const el = ctx.el;
+    const name = el.getAttribute('name') || tag.toLowerCase();
+
+    // Singleton guard: Reject duplicate registration instantly
+    const existing = router.getContainer(name);
+    if (existing && existing !== el) {
+      throw new Error(`ContainerError: Singleton violation — '${name}' is already mounted. A second instance cannot register while the first is active.`);
+    }
+
+    router.registerContainer(name, el);
+    if (originalMount) originalMount(ctx);
+  };
+
+  // Intercept unmount to safely unregister the layout container
+  const originalUnmount = spec.unmount;
+  spec.unmount = (ctx) => {
+    const el = ctx.el;
+    const name = el.getAttribute('name') || tag.toLowerCase();
+    router.unregisterContainer(name, el);
+
+    if (originalUnmount) originalUnmount(ctx);
+  };
+
+  // Define the base element using the standard declarative factory
+  element(tag, spec, base);
+
+  // Dynamically inject the Delegated Swap Interface for route transitions
+  const ElementClass = customElements.get(tag);
+  if (ElementClass && !ElementClass.prototype.swapView) {
+    ElementClass.prototype.swapView = async function(newElement, options = {}) {
+      const { direction = 'push' } = options;
+
+      // Apply directional transition hint via CSS custom property
+      this.dataset.transitionDirection = direction;
+
+      const doSwap = () => {
+        this.replaceChildren(newElement);
+        delete this.dataset.transitionDirection;
+      };
+
+      // Strategy 1: Element-scoped transition (Chrome 147+, concurrent-safe)
+      if (typeof this.startViewTransition === 'function') {
+        try {
+          const vt = this.startViewTransition({ callback: doSwap });
+          await vt.ready;
+        } catch (err) {
+          if (err?.name !== 'AbortError') console.warn('[UI Container] Scoped VT aborted:', err);
+        }
+        return;
+      }
+
+      // Strategy 2: Document-scoped transition (Baseline Oct 2025)
+      if (typeof document.startViewTransition === 'function') {
+        try {
+          const vt = document.startViewTransition(doSwap);
+          await vt.ready;
+        } catch (err) {
+          if (err?.name !== 'AbortError') console.warn('[UI Container] Document VT aborted:', err);
+        }
+        return;
+      }
+
+      // Strategy 3: Synchronous direct swap
+      doSwap();
+    };
+  }
+}

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

@@ -0,0 +1,12 @@
+/**
+ * Registers a custom element with a duplicate-registration safety guard.
+ */
+export function define(tag, Class) {
+  if (typeof customElements !== 'undefined') {
+    if (customElements.get(tag)) {
+      console.warn(`Custom Element "${tag}" is already registered. Skipping duplicate load.`);
+      return;
+    }
+    customElements.define(tag, Class);
+  }
+}