@adukiorg/anza 0.2.0

package/src/core/platform/polyfills/urlpattern.js

@@ -0,0 +1,119 @@
+/**
+ * src/core/platform/polyfills/urlpattern.js
+ *
+ * A robust URLPattern fallback for browsers lacking native support.
+ * Implements pathname matching with named parameters, modifiers, wildcards,
+ * and smart trailing slash normalization.
+ *
+ * Source: doc 18 §3, library2.md §Phase 1-A
+ */
+
+class URLPatternPolyfill {
+  #pathnameRegex;
+  #paramNames = [];
+
+  constructor(init) {
+    let pathnamePattern = '*';
+    if (typeof init === 'string') {
+      if (init.includes('://')) {
+        try {
+          const match = init.match(/^[a-zA-Z]+:\/\/[^\/]+(\/[^?#]*)/);
+          pathnamePattern = match ? match[1] : '/';
+        } catch {
+          pathnamePattern = init;
+        }
+      } else {
+        pathnamePattern = init;
+      }
+    } else if (init && typeof init === 'object') {
+      pathnamePattern = init.pathname || '*';
+    }
+
+    // Ensure pathnamePattern starts with /
+    if (!pathnamePattern.startsWith('/') && pathnamePattern !== '*') {
+      pathnamePattern = '/' + pathnamePattern;
+    }
+
+    this.#paramNames = [];
+    let wildcardCount = 0;
+
+    const segments = pathnamePattern.split('/');
+    const regexSegments = segments.map((segment, idx) => {
+      if (idx === 0 && segment === '') return '';
+
+      if (segment.startsWith(':')) {
+        let paramName = segment.slice(1);
+        let modifier = '';
+        if (paramName.endsWith('?') || paramName.endsWith('*') || paramName.endsWith('+')) {
+          modifier = paramName.slice(-1);
+          paramName = paramName.slice(0, -1);
+        }
+        this.#paramNames.push(paramName);
+
+        if (modifier === '?') {
+          return '([^/]*)';
+        } else if (modifier === '*') {
+          return '(.*)';
+        } else if (modifier === '+') {
+          return '([^/]+.*)';
+        } else {
+          return '([^/]+)';
+        }
+      } else if (segment === '*') {
+        this.#paramNames.push(String(wildcardCount++));
+        return '(.*)';
+      } else if (segment.includes('*')) {
+        this.#paramNames.push(String(wildcardCount++));
+        return segment.replace(/\*/g, '(.*)');
+      } else {
+        return segment.replace(/[-\/\\^$*+?.()|[\]{}]/g, '\\$&');
+      }
+    });
+
+    let patternStr = regexSegments.join('/');
+    if (patternStr === '') patternStr = '/';
+
+    // Support optional trailing slash if the pattern does not end in a wildcard or parameter modifier
+    if (!pathnamePattern.endsWith('*') && !pathnamePattern.endsWith('?') && pathnamePattern !== '/') {
+      patternStr += '/?';
+    }
+
+    this.#pathnameRegex = new RegExp('^' + patternStr + '$');
+  }
+
+  test(url) {
+    try {
+      const parsed = new URL(url, globalThis.location?.href || 'https://a.com');
+      return this.#pathnameRegex.test(parsed.pathname);
+    } catch {
+      return false;
+    }
+  }
+
+  exec(url) {
+    try {
+      const parsed = new URL(url, globalThis.location?.href || 'https://a.com');
+      const match = parsed.pathname.match(this.#pathnameRegex);
+      if (!match) return null;
+
+      const groups = {};
+      this.#paramNames.forEach((name, index) => {
+        groups[name] = match[index + 1] || '';
+      });
+
+      return {
+        pathname: {
+          input: parsed.pathname,
+          groups
+        }
+      };
+    } catch {
+      return null;
+    }
+  }
+}
+
+if (!globalThis.URLPattern) {
+  globalThis.URLPattern = URLPatternPolyfill;
+}
+export default URLPatternPolyfill;

package/src/core/platform/supports.js

@@ -0,0 +1,186 @@
+/**
+ * core/platform/supports.js
+ *
+ * All feature-detection booleans for the platform.
+ * Each flag is lazily evaluated on first access and then cached.
+ * Detection tests are conservative — they check for correct behaviour,
+ * not just API presence, where known browser bugs exist.
+ *
+ * Source authority: doc 18 — Limitations, Browser Gaps, and Polyfill Strategy §17
+ */
+
+const _cache = Object.create(null);
+
+function lazy(key, detect) {
+  Object.defineProperty(supports, key, {
+    get() {
+      if (!(key in _cache)) _cache[key] = detect();
+      return _cache[key];
+    },
+    configurable: true,
+    enumerable:   true,
+  });
+}
+
+export const supports = {};
+
+// --- Routing ---
+
+lazy('navigationAPI', () => 'navigation' in window);
+
+lazy('urlPattern', () => 'URLPattern' in globalThis);
+
+// --- Component Model ---
+
+lazy('declarativeShadowDOM', () =>
+  'shadowRootMode' in HTMLTemplateElement.prototype
+);
+
+lazy('customStatePseudo', () =>
+  typeof ElementInternals !== 'undefined' &&
+  'states' in ElementInternals.prototype
+);
+
+lazy('formAssociated', () =>
+  typeof HTMLElement !== 'undefined' &&
+  'attachInternals' in HTMLElement.prototype
+);
+
+// --- Overlay / Popover ---
+
+lazy('popoverAPI', () => 'popover' in HTMLElement.prototype);
+
+lazy('anchorPositioning', () =>
+  CSS.supports('anchor-name', '--a')
+);
+
+// --- Animation ---
+
+lazy('viewTransitions', () => 'startViewTransition' in document);
+
+lazy('scrollTimeline', () => 'ScrollTimeline' in window);
+
+lazy('viewTimeline', () => 'ViewTimeline' in window);
+
+// --- Scheduling ---
+
+lazy('schedulerPostTask', () =>
+  'scheduler' in globalThis && 'postTask' in scheduler
+);
+
+lazy('schedulerYield', () =>
+  'scheduler' in globalThis && 'yield' in scheduler
+);
+
+// --- CSS ---
+
+lazy('contentVisibility', () =>
+  CSS.supports('content-visibility', 'auto')
+);
+
+lazy('cssScope', () => CSS.supports('selector(:scope)'));
+
+lazy('cssLayer', () => {
+  try {
+    // @supports at-rule(@layer) is not universally parseable in JS;
+    // inject a sheet and check if a layer-wrapped rule is applied.
+    const s = document.createElement('style');
+    s.textContent = '@layer _test { ._testlayer { --_l: 1 } }';
+    document.head.append(s);
+    const ok = !!s.sheet;
+    s.remove();
+    return ok;
+  } catch { return false; }
+});
+
+lazy('cssModuleScripts', () => {
+  // CSS Module Scripts: import with { type: 'css' }
+  // Absent Firefox / Safari as of 2026 — doc 18 §14, library2.md §CSS Distribution
+  try {
+    return HTMLScriptElement.supports('importmap'); // proxy: if importmap exists, env is modern enough to test
+    // We check actual CSS module support via import attributes presence
+  } catch { return false; }
+});
+
+// --- Module System ---
+
+lazy('importMaps', () =>
+  HTMLScriptElement.supports && HTMLScriptElement.supports('importmap')
+);
+
+// --- Security ---
+
+lazy('sanitizerAPI', () => 'Sanitizer' in window);
+
+lazy('trustedTypes', () => 'trustedTypes' in window);
+
+lazy('subtleCrypto', () =>
+  typeof crypto !== 'undefined' && 'subtle' in crypto
+);
+
+// --- Storage ---
+
+lazy('opfs', () =>
+  'storage' in navigator &&
+  typeof navigator.storage.getDirectory === 'function'
+);
+
+lazy('storageManager', () => 'storage' in navigator);
+
+lazy('fileSystemPickers', () => 'showOpenFilePicker' in window);
+
+lazy('compression', () =>
+  typeof CompressionStream !== 'undefined' &&
+  typeof DecompressionStream !== 'undefined'
+);
+
+lazy('storagePersistence', () =>
+  'storage' in navigator &&
+  typeof navigator.storage.persist === 'function' &&
+  typeof navigator.storage.persisted === 'function'
+);
+
+// --- Networking / Workers ---
+
+lazy('backgroundSync', () =>
+  'ServiceWorkerRegistration' in window &&
+  'sync' in ServiceWorkerRegistration.prototype
+);
+
+lazy('speculationRules', () =>
+  HTMLScriptElement.supports &&
+  HTMLScriptElement.supports('speculationrules')
+);
+
+lazy('sharedWorker', () => 'SharedWorker' in window);
+
+lazy('webLocks', () => 'locks' in navigator);
+
+lazy('offscreenCanvas', () => 'OffscreenCanvas' in window);
+
+// --- Notifications / Push ---
+
+lazy('pushAPI', () => 'PushManager' in window);
+
+lazy('notificationsAPI', () => 'Notification' in window);
+
+// --- Device ---
+
+lazy('screenWakeLock', () => 'wakeLock' in navigator);
+
+lazy('idleDetection', () => 'IdleDetector' in window);
+
+lazy('webAuthn', () => 'PublicKeyCredential' in window);
+
+// --- Reset cached value (for testing only) ---
+export function reset(key) {
+  delete _cache[key];
+}
+
+// --- Type guard: assert feature support at runtime ---
+export function typeGuard(key, message) {
+  if (!supports[key]) {
+    const msg = message || `Platform does not support: ${key}`;
+    throw new Error(msg);
+  }
+}

package/src/core/platform/usage.md

@@ -0,0 +1,287 @@
+# Platform Module — Developer Usage Guide
+
+The `@adukiorg/anza/platform` module acts as a smart, lazy-evaluated browser capability layer and zero-overhead polyfill manager. It exposes simple feature flags, unified asynchronous feature gates, a prioritized task scheduler, leak-proof popovers, and resilient URLPattern pathname matching.
+
+---
+
+## 1. Import System
+
+To keep your client application highly performant and structured, import everything directly from the unified platform specifier:
+
+```javascript
+import { supports, guard, reset, typeGuard } from '@adukiorg/anza/platform';
+```
+
+---
+
+## 2. Browser Capabilities Matrix (`supports`)
+
+The `supports` object is a lazy-evaluated, cached registry containing 30+ boolean flags for modern HTML5, CSS, Web Cryptography, OPFS, compression, storage managers, and Worker APIs.
+
+### Example Usage
+
+```javascript
+import { supports } from '@adukiorg/anza/platform';
+
+// 1. OPFS support
+if (supports.opfs) {
+  console.log('Origin Private File System is natively supported!');
+} else {
+  console.log('OPFS absent; using standard IndexedDB storage fallback.');
+}
+
+// 2. Storage Persistence capability
+if (supports.storagePersistence) {
+  navigator.storage.persist().then(granted => {
+    console.log(`Durable storage granted: ${granted}`);
+  });
+}
+
+// 3. Compression Streams capability
+if (supports.compression) {
+  const compressor = new CompressionStream('gzip');
+  console.log('Compression Stream is natively supported!');
+}
+
+// 4. Check CSS View Transitions support
+if (supports.viewTransitions) {
+  document.startViewTransition(() => updateTheDOM());
+} else {
+  updateTheDOM();
+}
+```
+
+*Note: For unit testing, you can clear cached lazy-evaluated values using the `reset(flag)` method. This allows mocking feature states dynamically in tests:*
+
+```javascript
+import { reset, supports } from '@adukiorg/anza/platform';
+
+// Force urlPattern to false for testing fallback polyfill loading
+Object.defineProperty(supports, 'urlPattern', { value: false, configurable: true });
+
+// Run your test assertions here...
+
+// Clear mock value and restore original lazy capability checker
+reset('urlPattern');
+```
+
+### Runtime Type Guarding
+
+Use `typeGuard` to assert feature support at runtime. It throws an error with a custom message if the feature is not available, making it useful for early-fail checks in critical code paths:
+
+```javascript
+import { typeGuard } from '@adukiorg/anza/platform';
+
+// Assert OPFS support before attempting file operations
+typeGuard('opfs', 'OPFS is required for this feature');
+
+// Assert Navigation API support before routing
+typeGuard('navigationAPI', 'Navigation API is required for routing');
+
+// Custom error message
+try {
+  typeGuard('viewTransitions', 'View transitions are required for page transitions');
+  document.startViewTransition(() => updateDOM());
+} catch (err) {
+  // Fallback for browsers without view transitions
+  updateDOM();
+}
+```
+
+---
+
+## 3. Dynamic Feature Guards (`guard`)
+
+Asynchronous wrappers that transparently route calls to native browser APIs (if present) or automatically load, bootstrap, and install the lightweight polyfills on demand.
+
+| Guard Method | Returns | Action / Polyfill Fallback |
+| --- | --- | --- |
+| `await guard.urlPattern()` | `URLPattern` Class | Returns spec-compliant pathname matching template class |
+| `await guard.navigation()` | `navigation` Object | Bootstraps the Single Page Application Navigation API polyfill |
+| `await guard.popover()` | `undefined` | Installs HTMLElement popover prototype methods & light dismiss |
+| `await guard.shadow(root)` | `undefined` | Applies polyfill parser for Declarative Shadow DOM template nodes |
+| `await guard.anchor(float, anchor, opts)` | `undefined` | Computes high-performance dynamic anchor positioning fallback |
+| `await guard.sanitizer()` | Sanitizer Wrapper | Exposes uniform `.sanitizeToString(html)` helper |
+| `await guard.scheduler()` | `scheduler` Object | Returns priority-aware task execution queues |
+| `await guard.yield()` | `Promise<undefined>` | Yields execution thread control back to the event loop |
+
+---
+
+## 4. Prioritized Task Scheduler
+
+When native `globalThis.scheduler` is absent, the polyfill exposes a robust microtask/macrotask priority queue system supporting three priority levels (`user-blocking`, `user-visible`, `background`), delayed scheduling, and task cancellation via `AbortSignal`.
+
+### Prioritized Task Enqueuing
+
+```javascript
+import { guard } from '@adukiorg/anza/platform';
+
+const scheduler = await guard.scheduler();
+
+// 1. High priority UI rendering task
+scheduler.postTask(() => {
+  renderCriticalInteractiveUI();
+}, { priority: 'user-blocking' });
+
+// 2. Default priority application logic task
+scheduler.postTask(() => {
+  fetchFreshStateUpdates();
+}, { priority: 'user-visible' });
+
+// 3. Low priority telemetry sync task
+scheduler.postTask(() => {
+  flushTelemetryLogs();
+}, { priority: 'background' });
+```
+
+### Delayed Task Execution
+
+```javascript
+// Schedule a default priority task to run after 200ms
+scheduler.postTask(() => {
+  lazyLoadImagePreviews();
+}, { delay: 200 });
+```
+
+### Task Cancellation via AbortSignal
+
+```javascript
+const controller = new AbortController();
+
+scheduler.postTask(() => {
+  console.log('This will not execute if aborted in time!');
+}, { signal: controller.signal }).catch(err => {
+  if (err.name === 'AbortError') {
+    console.log('Task successfully cancelled!');
+  }
+});
+
+// Abort the controller
+controller.abort();
+```
+
+### Dynamic Event Loop Yielding
+
+Use `guard.yield()` inside complex, long-running loops to split execution into distinct chunks, preventing browser UI freezes and maintaining a 60fps frame rate.
+
+```javascript
+import { guard } from '@adukiorg/anza/platform';
+
+async function processMassiveDataset(items) {
+  for (let idx = 0; idx < items.length; idx++) {
+    computeHeavyItem(items[idx]);
+    
+    // Yield execution control back to the event loop every 50 operations
+    if (idx % 50 === 0) {
+      await guard.yield();
+    }
+  }
+}
+```
+
+---
+
+## 5. Leak-Proof Popover API
+
+Provides native popover styling (`fixed` viewport positioning, high-tier top-layer simulations), light dismiss clicks, and complete DOM unmount safety to avoid memory leaks.
+
+### Declarative Markup Integration
+
+```html
+<!-- Trigger Button -->
+<button popovertarget="dropdown-menu" popovertargetaction="toggle">
+  Open Dropdown
+</button>
+
+<!-- Popover Container Element -->
+<div id="dropdown-menu" popover="auto">
+  <h3>Dropdown Options</h3>
+  <ul>
+    <li><a href="/profile">Profile</a></li>
+    <li><a href="/settings">Settings</a></li>
+  </ul>
+</div>
+```
+
+### Programmatic API Control
+
+```javascript
+const menu = document.getElementById('dropdown-menu');
+
+// Explicitly show the dropdown
+menu.showPopover();
+
+// Explicitly hide the dropdown
+menu.hidePopover();
+
+// Toggle visibility state
+menu.togglePopover();
+```
+
+### Memory Safety & Automated Garbage Collection
+
+When a popover is declared with `popover="auto"` or `popover=""`, standard polyfills register global document-level click listener closures, which can trigger severe memory leaks when components are removed or unmounted.
+
+Our polyfill leverages an internal `MutationObserver` on `document.body` to track DOM unmount actions. If a popover element is programmatically removed from the document while open, it **automatically invokes hidePopover(), detaches its global click listeners, and disconnects all MutationObservers**, guaranteeing zero memory leaks:
+
+```javascript
+const userMenu = document.createElement('div');
+userMenu.setAttribute('popover', 'auto');
+document.body.appendChild(userMenu);
+
+userMenu.showPopover();
+
+// Programmatically unmounted from the DOM
+userMenu.remove(); // Internally cleans up all global event listeners automatically!
+```
+
+---
+
+## 6. Trailing-Slash Resilient URLPattern
+
+Spec-compliant URLPattern pathname parser that extracts named parameters and wildcards, Normalizing trailing slashes seamlessly.
+
+### Segment Parameter & Wildcard Matching
+
+```javascript
+import { guard } from '@adukiorg/anza/platform';
+
+const URLPattern = await guard.urlPattern();
+
+// Template matching both '/posts/2026/my-first-post' and '/posts/2026/my-first-post/'
+const pattern = new URLPattern({ pathname: '/posts/:year/:slug' });
+
+const result = pattern.exec('https://example.com/posts/2026/my-first-post/');
+if (result) {
+  const { year, slug } = result.pathname.groups;
+  console.log(`Year: ${year}, Slug: ${slug}`); 
+  // Output: Year: 2026, Slug: my-first-post
+}
+```
+
+### Wildcard Segment Extraction
+
+Wildcards are parsed sequentially into indexed string parameter names starting at `'0'`:
+
+```javascript
+const filesPattern = new URLPattern({ pathname: '/docs/*' });
+const match = filesPattern.exec('/docs/api/platform/usage.pdf');
+
+if (match) {
+  const filePath = match.pathname.groups['0'];
+  console.log(`File Path: ${filePath}`);
+  // Output: File Path: api/platform/usage.pdf
+}
+```
+
+### Parameter Modifiers
+
+The polyfill supports `?` (optional), `*` (zero-or-more), and `+` (one-or-more) named modifiers:
+
+```javascript
+// Match optional member profiles: /member or /member/fescii
+const pattern = new URLPattern({ pathname: '/member/:username?' });
+
+const match = pattern.exec('/member/');
+console.log(match.pathname.groups.username); // Output: ""
+```

package/src/core/router/cache.js

@@ -0,0 +1,95 @@
+/**
+ * src/core/router/cache.js
+ *
+ * Internal route cache backed by the browser Cache API. The router uses this to
+ * prefetch and store view assets / lazily-loaded module responses keyed by URL,
+ * so revisiting or anticipating a route serves from cache instead of the network.
+ *
+ * Uses the same `x-expires-at` TTL convention as storage and api caches.
+ */
+
+const NAME = 'router-cache';
+const DEFAULT_TTL = 5 * 60 * 1000; // 5 minutes
+
+async function open() {
+  if (typeof caches === 'undefined') return null;
+  return caches.open(NAME);
+}
+
+function key(url) {
+  return new Request(new URL(url, globalThis.location?.href || 'http://localhost').href);
+}
+
+/**
+ * Read a cached response for a route URL, honoring TTL. Returns `null` on miss
+ * or when the Cache API is unavailable.
+ */
+export async function get(url) {
+  const store = await open();
+  if (!store) return null;
+
+  const req = key(url);
+  const res = await store.match(req);
+  if (!res) return null;
+
+  const expires = res.headers.get('x-expires-at');
+  if (expires && Date.now() > Number(expires)) {
+    await store.delete(req);
+    return null;
+  }
+  return res.clone();
+}
+
+/**
+ * Store a response for a route URL with an optional TTL (ms).
+ */
+export async function set(url, response, ttl = DEFAULT_TTL) {
+  const store = await open();
+  if (!store || !response || response.type === 'opaque') return;
+
+  const headers = new Headers(response.headers);
+  if (ttl) headers.set('x-expires-at', String(Date.now() + ttl));
+
+  const body = response.body ? response.clone().body : null;
+  const stamped = new Response(body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers
+  });
+  await store.put(key(url), stamped);
+}
+
+/**
+ * Prefetch a route URL into the cache. Returns the cached `Response` (or `null`).
+ * Use on link hover / when a view becomes visible to make navigation instant.
+ */
+export async function prefetch(url, { ttl = DEFAULT_TTL, signal } = {}) {
+  const existing = await get(url);
+  if (existing) return existing;
+
+  try {
+    const res = await fetch(key(url), { signal });
+    if (res && res.ok) {
+      await set(url, res, ttl);
+      return res.clone();
+    }
+  } catch {
+    // Network failure during prefetch is non-fatal.
+  }
+  return null;
+}
+
+/**
+ * Remove a single URL, or clear the entire route cache when called with no args.
+ */
+export async function purge(url) {
+  const store = await open();
+  if (!store) return;
+  if (url) {
+    await store.delete(key(url));
+  } else if (typeof caches !== 'undefined') {
+    await caches.delete(NAME);
+  }
+}
+
+export const cache = { get, set, prefetch, purge };