@adukiorg/anza 0.2.0 → 0.2.3

package/src/core/state/missing.md

@@ -1,165 +0,0 @@
-# State Missing Support
-
-This document tracks remaining support, runtime bugs, type mismatches, and performance optimization work for `src/core/state`. Implemented behavior belongs in `usage.md` (or core documentation); unsupported, untyped, or under-tested behavior belongs here until it is built and verified.
-
----
-
-## 0. Toolchain and Naming Rules
-
-Heavy validation, static analysis, and code generation belong in `tools/`, not in browser runtime modules.
-
-Current toolchain state support requirements:
-- Analyze `state` initialization and usage patterns statically.
-- Detect mutations violating the immutability discipline.
-- Generate unified type definitions for state domains.
-
-Naming rules for state support:
-- Prefer one-word files: `store.js`, `derived.js`, `persist.js`, `sync.js`, `index.js`.
-- Plural folders: `tests/`, `types/`.
-- Single-word methods: `get`, `set`, `batch`, `sync`, `derived`, `clear`, `reset`, `estimate`, `persist`.
-- Single-word events: `change`, `hydrate`, `quota`, `error`.
-- Avoid compound names where single words carry full meaning in context.
-
----
-
-## 1. Critical Runtime and Type Gaps
-
-### 1.1. Storage Type Mismatches
-- **Status**: Critical mismatch.
-- **Files**:
-  - `types/core/state/index.d.ts`
-  - `src/core/state/persist.js`
-- **Problem**:
-  The type declaration file defines `storage` with `persist(store, options)` and `hydrate(store, name)`. The actual runtime `storage` export is an instance of `PlatformStorage` exposing CRUD and system queries: `get(store, key)`, `set(store, key, val)`, `delete(store, key)`, `query(store, filter)`, `estimate()`, `persist()`, and `isPersisted()`.
-- **Expected Support**:
-  - Align `types/core/state/index.d.ts` to expose the true `PlatformStorage` interface.
-  - Implement helper hooks in the store or `persist.js` to simplify store-wide persistence if required, but maintain structural parity.
-
-### 1.2. Writable Store Event and Helper Omissions
-- **Status**: Runtime gap.
-- **Files**:
-  - `src/core/state/store.js`
-  - `src/core/state/index.js`
-- **Problem**:
-  The State Management specification (§15) defines `store.broadcast(channelName)` as a method directly on the store instance for cross-tab replication. Currently, this functionality is decoupled into a standalone `sync(store, keys, channelName)` function. Similarly, `store.derived(keys, compute)` is specified but not present on the store instance class.
-- **Expected Support**:
-  - Add a delegate helper `broadcast(channelName, keys?)` to `ReactiveStore` mapping directly to the `sync` utility.
-  - Add a delegate helper `derived(keys, compute)` to `ReactiveStore` mapping to `derived(compute)` with key-bound invalidation if preferred, or clean up the API specification.
-
----
-
-## 2. Persistence Gaps (Storage Quota and Eviction)
-
-### 2.1. Proactive Eviction and Quota Warnings
-- **Status**: Planned but missing.
-- **File**:
-  - `src/core/state/persist.js`
-- **Problem**:
-  The storage engine does not monitor available quota or execute proactive eviction. Large applications risk throwing unhandled `QuotaExceededError` exceptions when writing data.
-- **Expected Support**:
-  - Implement a quota check wrapper on `set()`.
-  - Establish a warning threshold (80% of estimated quota).
-  - Add proactive eviction stages:
-    1. Prune expired cache records based on TTL metadata.
-    2. Evict low-recency records (LRU) using a `lastAccessed` timestamp.
-  - Dispatch a global `quota` warning event if space remains critical.
-
-### 2.2. Write-Through and Write-Ahead Transaction Queues
-- **Status**: Missing support.
-- **File**:
-  - `src/core/state/persist.js`
-- **Problem**:
-  Mutating state is not atomic. A crash between memory writing and database writing leaves inconsistent schemas.
-- **Expected Support**:
-  - Add a transaction-safe queue to handle write-ahead serialization (log first, modify memory on confirmation).
-  - Implement retry logic in the write queue on transient storage lockups or quota exceptions.
-
----
-
-## 3. Reactivity Performance and Deep Store Support
-
-### 3.1. Deep Reactive Stores
-- **Status**: Enhancement.
-- **File**:
-  - `src/core/state/store.js`
-- **Problem**:
-  `ReactiveStore` only intercepts top-level properties (shallow). Mutating nested objects (e.g., `store.get('user').name = 'alice'`) bypasses reactive traps. Manual structural sharing (e.g., `store.set('user', { ...user, name: 'alice' })`) is error-prone.
-- **Expected Support**:
-  - Add opt-in deep reactivity configuration on store instantiation.
-  - Recursively wrap accessed nested object fields in reactive `Proxy` instances, returning mapped pathways.
-  - Validate that circular references do not crash proxy wrappers.
-
-### 3.2. Optimized Snapshots
-- **Status**: Performance enhancement.
-- **File**:
-  - `src/core/state/store.js`
-- **Problem**:
-  `store.snapshot()` falls back to `JSON.parse(JSON.stringify(...))` when `structuredClone` is missing or if non-serializable objects (like `Map` or `Set`) are stored. This degrades speed in performance-sensitive contexts.
-- **Expected Support**:
-  - Use custom fast-cloning paths for pure data objects.
-  - Delegate serialization for custom collection types within the store configuration.
-
----
-
-## 4. Build-Time Static Analysis
-
-### 4.1. Immutability Violation Scan
-- **Status**: Planned.
-- **Files**:
-  - `tools/src/extract/runner.rs`
-- **Problem**:
-  In-place mutations of objects retrieved from reactive stores (e.g. `store.get('user').name = 'bob'`) bypasses the `Object.is` check and stops reactive updates. This is hard to debug at runtime.
-- **Expected Support**:
-  - Implement a AST-based checker in `anza` to scan JavaScript sources for store retrieval variables followed by mutation assignments.
-  - Log lint warnings during `scan` and `dev` runs.
-
-### 4.2. Schema Type Generation
-- **Status**: Enhancement.
-- **Files**:
-  - `tools/src/extract/runner.rs`
-- **Expected Support**:
-  - Statically analyze store initializations to output a typed state manifest schema (`state.d.ts`).
-
----
-
-## 5. Test Coverage Gaps
-
-### 5.1. No Persistence Tests
-- **Status**: Missing coverage.
-- **File**:
-  - `tests/core/state/persist.test.js`
-- **Needed Coverage**:
-  - Database instantiation and migrations.
-  - CRUD operations (`get`, `set`, `delete`, `query`).
-  - Quota estimate mock and persistence hooks.
-  - Eviction stages validation.
-
-### 5.2. Tab Sync Robustness
-- **Status**: Weak coverage.
-- **File**:
-  - `tests/core/state/sync.test.js`
-- **Needed Coverage**:
-  - Re-entrancy and circular echo avoidance.
-  - Proper disposal of broadcast channels.
-
----
-
-## 6. Suggested Implementation Order
-
-1. Align `types/core/state/index.d.ts` with runtime `PlatformStorage`.
-2. Add `tests/core/state/persist.test.js` to cover basic IndexedDB CRUD operations.
-3. Expose `store.broadcast()` and `store.derived()` delegate methods.
-4. Implement recursive deep proxy wrapper options in `ReactiveStore`.
-5. Implement quota warning thresholds and basic recency-based eviction.
-6. Add build-time immutability violation scanner to `anza`.
-
----
-
-## 7. Done Criteria
-
-This missing-support list is complete when:
-- Type declarations for `storage` match runtime methods.
-- Persistent local store has comprehensive tests covering IndexedDB operations.
-- Deep reactive stores are optionally configurable and verified.
-- Static scanning tools warn developers of inline store mutations.
-- Eviction and warning systems prevent silent quota failures.

package/src/core/storage/missing.md

@@ -1,165 +0,0 @@
-# Storage Missing Support
-
-This document tracks remaining support, runtime gaps, concurrency constraints, serialization enhancements, and performance optimization work for `src/core/storage`. 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 storage support requirements:
-
-- Analyze storage tier utilization and statically compile Dedicated Web Worker scripts to avoid runtime ObjectURL blobs.
-- Detect synchronous storage access patterns (like `localStorage` or `sessionStorage` usage) outside designated bootstrap paths.
-- Statically validate migration schema progression profiles.
-
-Naming rules for storage support:
-
-- Prefer one-word files: `idb.js`, `lru.js`, `opfs.js`, `quota.js`, `cache.js`, `index.js`.
-- Plural folders: `tests/`, `migrations/`.
-- Single-word methods: `get`, `set`, `delete`, `query`, `list`, `clear`, `estimate`, `persist`, `persisted`, `transaction`.
-- Single-word events: `warning`, `quota`, `blocked`.
-- Avoid compound names where single words carry full meaning in context.
-
----
-
-## 1. Critical Runtime and Type Gaps
-
-### 1.1. Missing Unified Gateway Methods
-
-- **Status**: Runtime gap.
-- **Files**:
-  - `src/core/storage/index.js`
-- **Problem**:
-  The Storage Architecture specification (§15) defines `storage.transaction(stores, mode, fn)`, `storage.persisted()`, and `storage.onQuotaWarning(handler)` as part of the Unified Storage Gateway interface. Currently, these methods are not implemented on the exported `storage` facade.
-- **Expected Support**:
-  - Implement `storage.transaction(stores, mode, fn)` to execute multi-store operations inside a single transactional block.
-  - Implement `storage.persisted()` wrapping `navigator.storage.persisted()`.
-  - Implement `storage.onQuotaWarning(handler)` to subscribe to quota limit checks.
-
-### 1.2. Storage Type Mismatches
-
-- **Status**: Type mismatch.
-- **Files**:
-  - `types/core/storage/index.d.ts`
-- **Problem**:
-  The type declaration file does not align with the public specifications. It is missing declarations for `persisted()`, `transaction()`, and the proper returned structure from `estimate()` (including the `persisted` flag).
-- **Expected Support**:
-  - Align `types/core/storage/index.d.ts` to expose the true interface.
-
----
-
-## 2. Concurrency & Durability Gaps
-
-### 2.1. Web Locks Coordination for OPFS
-
-- **Status**: Critical concurrency gap.
-- **Files**:
-  - `src/core/storage/opfs.js`
-- **Problem**:
-  The OPFS manager does not coordinate file access across different tabs. Concurrent reads and writes to the same virtual file will throw errors or lead to raw binary data corruption.
-- **Expected Support**:
-  - Wrap OPFS operations (`get`, `set`, `delete`) in an exclusive Web Lock (`workers.lock` or `navigator.locks.request`) scoped to the filename to serialize cross-tab operations.
-
-### 2.2. IndexedDB Upgrade Blocking Coordination
-
-- **Status**: Runtime gap.
-- **Files**:
-  - `src/core/storage/idb.js`
-- **Problem**:
-  If a user has multiple tabs open, an IndexedDB database schema upgrade (triggered by opening with a higher version) is blocked indefinitely because the old tabs hold active connections. Currently, the database class does not listen to `onblocked` or `onversionchange` events.
-- **Expected Support**:
-  - Handle the `blocked` event on the database open request, dispatching an event to warn the system of connection locks.
-  - Listen to the `versionchange` event on the active database connection. If triggered, gracefully close the database immediately so that other tabs can proceed with schema upgrades.
-
-### 2.3. Write Journal for Durability
-
-- **Status**: Planned but missing.
-- **Files**:
-  - `src/core/storage/index.js`
-- **Problem**:
-  Transactions can fail to write to disk due to abrupt tab crashes or sudden power losses, leaving memory and disk states inconsistent.
-- **Expected Support**:
-  - Introduce a write journal using crash-durable `localStorage` to buffer pending keys before committing them to IndexedDB.
-  - Verify and replay uncommitted journal operations automatically during client boot.
-
----
-
-## 3. Serialization & Performance Gaps
-
-### 3.1. Transparent Compression for Large Records
-
-- **Status**: Performance enhancement.
-- **Files**:
-  - `src/core/storage/index.js`
-- **Problem**:
-  Writing large objects (>64KB) directly to IndexedDB consumes excess quota, increases serialization/deserialization delay, and degrades storage bandwidth.
-- **Expected Support**:
-  - Implement transparent compression using the browser's native Compression Streams API (`new CompressionStream('gzip')`) when writing values exceeding 64KB.
-  - Inject a metadata envelope (`{ value, compressed: true }`) to identify compressed payloads and decompress them automatically on read.
-
-### 3.2. Worker Script Optimization
-
-- **Status**: Optimization.
-- **Files**:
-  - `src/core/storage/opfs.js`
-- **Problem**:
-  The OPFS manager instantiates its Dedicated Worker using a Blob URL wrapper on an inline string (`URL.createObjectURL(new Blob(...))`). This slows down initial load, blocks minification, and triggers Content Security Policy (CSP) security warnings.
-- **Expected Support**:
-  - Offload worker script extraction to the build-time compiler (`tools/`) to generate a static asset or optimize string injection.
-
----
-
-## 4. Test Coverage Gaps
-
-### 4.1. OPFS Integration Tests
-
-- **Status**: Missing coverage.
-- **Files**:
-  - `tests/core/storage/opfs.test.js` [NEW]
-- **Needed Coverage**:
-  - Dedicated Worker execution offloading.
-  - Parallel reads/writes and verification of data persistence.
-  - Cross-tab change invalidation alerts over BroadcastChannel.
-
-### 4.2. Cache API and TTL Verification
-
-- **Status**: Missing coverage.
-- **Files**:
-  - `tests/core/storage/cache.test.js` [NEW]
-- **Needed Coverage**:
-  - Cache matches and correct header insertion for `x-expires-at`.
-  - Automatic eviction of expired items.
-
-### 4.3. Quota Warning and Eviction Tests
-
-- **Status**: Missing coverage.
-- **Files**:
-  - `tests/core/storage/quota.test.js` [NEW]
-- **Needed Coverage**:
-  - Mocking quota estimate queries.
-  - Verification that warnings fire when threshold usage exceeds 80%.
-
----
-
-## 5. Suggested Implementation Order
-
-1. Align `types/core/storage/index.d.ts` with the full unified storage API.
-2. Add comprehensive tests for `opfs.js`, `cache.js`, and `quota.js`.
-3. Implement Web Locks for OPFS file synchronization.
-4. Implement database blocking and connection version upgrade handlers.
-5. Implement transparent Compression Streams for large values (>64KB).
-6. Implement write journaling for transactional durability.
-
----
-
-## 6. Done Criteria
-
-This missing-support list is complete when:
-
-- TypeScript declarations map the complete unified storage API.
-- OPFS, Cache TTL, and Quota warning components have complete integration tests.
-- Web Locks synchronize multi-tab file writes.
-- DB upgrades are not blocked by connections in sibling tabs.
-- Large records (>64KB) are compressed transparently using native streams.

package/src/core/storage/plan.md

@@ -1,69 +0,0 @@
-# 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/ui/implementation.md

@@ -1,170 +0,0 @@
-# Native UI Implementation Checklist
-
-This checklist is the execution companion to `plan.md`, `watch.md`, and `usage.md`.
-
-Status: **Fully Implemented and Verified**
-
-- All phases (Phase 1 through Phase 7) are completed, optimized, and verified.
-- The runtime helpers, event delegation, mutation watcher, lifecycle injection, Rust scanner, and comprehensive test suite are fully operational and integrated.
-
-## Phase 1: Runtime Helpers
-
-Files:
-
-- `src/core/ui/define/proxy.js`
-- `src/core/ui/define/element.js`
-- optional new `src/core/ui/define/context.js`
-
-Tasks:
-
-- Split `TagsCache` into separate `one` and `all` caches.
-- Add `TagsCache.has(selector)` if desired.
-- Add descriptor-free `refs` fallback scanning.
-- Add duplicate-ref development warnings.
-- Add context builder for `{ el, ctrl, tags, on, refs, watch, internals }`.
-- Install cache invalidation for `replaceChildren` and `innerHTML`.
-- Return stable context objects for mount/update.
-
-Acceptance:
-
-- `tags.one('button')` and `tags.all('button')` can be called in any order.
-- `refs` works with and without `.tags.json`.
-- Existing `ui.element` components continue to mount.
-
-## Phase 2: Event Delegation
-
-File:
-
-- `src/core/ui/define/proxy.js`
-
-Tasks:
-
-- Replace per-binding root listeners with one root listener per event type.
-- Store event registrations in sets keyed by event type.
-- Support `on.click(selector, handler)`.
-- Support `on.click(selector, handler, signal)`.
-- Support `on.click(selector, handler, options)`.
-- Support `on.click.once(selector, handler)`.
-- Return disposer functions.
-- Remove bindings on custom signal abort.
-- Remove all bindings on component signal abort.
-
-Acceptance:
-
-- Dynamically added matching elements work without rebinding.
-- Multiple click handlers do not create multiple native click listeners on the shadow root.
-- `.once` fires once and removes only itself.
-
-## Phase 3: `watch`
-
-File:
-
-- `src/core/ui/define/proxy.js` or new `src/core/ui/define/watch.js`
-
-Tasks:
-
-- Implement `createMutationWatcher(shadowRoot, defaultSignal)`.
-- Support `watch.attr`, `watch.kids`, `watch.text`, `watch.tree`.
-- Support `.once` on each method.
-- Accept selector strings and direct element references.
-- Accept custom `AbortSignal` or options object.
-- Return disposer functions.
-- Recompute observer options from active registrations.
-- Dispatch reshaped handler arguments.
-- Guard callbacks after lifecycle abort.
-
-Acceptance:
-
-- One `MutationObserver` exists per component instance.
-- Attribute, child, text, and tree handlers receive documented arguments.
-- Component disconnect clears all registrations.
-
-## Phase 4: Lifecycle Injection
-
-File:
-
-- `src/core/ui/define/element.js`
-
-Tasks:
-
-- Use the context builder after template/style hydration.
-- Pass `watch` to `spec.mount`.
-- Pass `watch` and `prev` to `spec.update`.
-- Preserve `internals` behavior for form-associated elements.
-- Keep `spec.unmount` shape stable.
-
-Acceptance:
-
-- Existing components using `{ tags, on, refs }` still work.
-- New components can destructure `{ watch }`.
-- Updates receive `prev` consistently.
-
-## Phase 5: Rust Scanner
-
-Files:
-
-- `tools/src/extract/html.rs`
-- `tools/src/extract/runner.rs`
-- `tools/src/watcher/runner.rs`
-- `tools/src/main.rs`
-
-Tasks:
-
-- Refactor scanner into `parse_html`, `parse_file`, `emit_descriptor`, and `parse_and_emit`.
-- Return `Result` instead of silently swallowing errors.
-- Add descriptor `version`.
-- Add duplicate-ref diagnostics.
-- Keep sorted deterministic output.
-- Consider `attrs` and `refTypes` fields.
-- Add subcommands or document current flags until subcommands land.
-- Regenerate descriptors on HTML watcher events.
-- Remove stale descriptors when source HTML is deleted.
-
-Acceptance:
-
-- Build mode emits descriptors for all HTML templates.
-- Dev watcher regenerates a changed template descriptor.
-- Malformed HTML fragments do not panic.
-
-## Phase 6: Tests
-
-JavaScript tests:
-
-- `tags` cache shapes and invalidation.
-- `refs` descriptor and fallback behavior.
-- `on` delegation, custom events, once, signal cleanup.
-- `watch` attr/kids/text/tree, once, direct refs, selector misses, lifecycle abort.
-
-Rust tests:
-
-- Descriptor parsing.
-- Stable JSON ordering.
-- Duplicate refs.
-- Watcher-triggered regeneration.
-
-## Phase 7: Documentation
-
-Files:
-
-- `src/core/ui/plan.md`
-- `src/core/ui/watch.md`
-- `src/core/ui/usage.md`
-- `src/core/ui/implementation.md`
-
-Tasks:
-
-- Keep `plan.md` as the architectural implementation plan.
-- Keep `watch.md` as the `watch` API and internals spec.
-- Keep `usage.md` as the public usage guide.
-- Keep this file as the execution checklist.
-
-## Done Definition
-
-The work is complete when:
-
-- Runtime injects `refs`, `tags`, `on`, and `watch`.
-- All helpers clean up from `ctrl.signal`.
-- Rust emits descriptors deterministically.
-- Dev watcher keeps descriptors current.
-- Usage docs cover every public call shape.
-- Tests prove lifecycle cleanup and cache correctness.