@adukiorg/anza 0.2.0

package/src/sw/strategies.js

@@ -0,0 +1,247 @@
+/**
+ * src/sw/strategies.js
+ *
+ * Caching Strategies.
+ * Implements standard service worker request interception strategies:
+ * CacheFirst, NetworkFirst, StaleRevalidate, CacheThenNetwork, NetworkOnly, CacheOnly,
+ * and OfflineFallback, featuring configurable timeouts and dynamic response TTLs.
+ *
+ * Source: doc 13 — Offline and Background §3
+ */
+
+/**
+ * Clones a response, modifying or appending a custom TTL expires header if requested.
+ */
+async function cloneWithExpiry(response, ttl) {
+  if (!ttl) return response;
+
+  // Read body as blob to prevent stream lockups
+  const blob = await response.clone().blob();
+  const headers = new Headers(response.headers);
+  headers.set('x-expires-at', (Date.now() + ttl).toString());
+
+  return new Response(blob, {
+    status: response.status,
+    statusText: response.statusText,
+    headers
+  });
+}
+
+/**
+ * Serves shell assets eagerly from cache; falls back to network on miss.
+ */
+export class CacheFirst {
+  constructor(cacheName, options = {}) {
+    this.cacheName = cacheName;
+    this.options = options;
+  }
+
+  async handle(request) {
+    const cache = await caches.open(this.cacheName);
+    const cachedResponse = await cache.match(request);
+
+    if (cachedResponse) {
+      const expiresAt = parseInt(cachedResponse.headers.get('x-expires-at') ?? '0', 10);
+      if (!expiresAt || expiresAt > Date.now()) {
+        return cachedResponse;
+      }
+    }
+
+    try {
+      const response = await fetch(request);
+      if (response && response.ok) {
+        const storedRes = await cloneWithExpiry(response, this.options.ttl);
+        await cache.put(request, storedRes);
+      }
+      return response;
+    } catch (err) {
+      if (cachedResponse) return cachedResponse; // Return expired fallback if offline
+      throw err;
+    }
+  }
+}
+
+/**
+ * Consults network first; falls back to cache on failure or configurable timeout.
+ */
+export class NetworkFirst {
+  constructor(cacheName, options = {}) {
+    this.cacheName = cacheName;
+    this.options = options;
+    this.timeout = options.timeout ?? 4000; // default 4-second timeout
+  }
+
+  async handle(request) {
+    const cache = await caches.open(this.cacheName);
+    const cachedResponse = await cache.match(request);
+
+    const timeoutPromise = new Promise((resolve) => {
+      setTimeout(() => resolve(null), this.timeout);
+    });
+
+    try {
+      const networkResponse = await Promise.race([
+        fetch(request),
+        timeoutPromise
+      ]);
+
+      if (networkResponse && networkResponse.ok) {
+        const storedRes = await cloneWithExpiry(networkResponse, this.options.ttl);
+        await cache.put(request, storedRes);
+        return networkResponse;
+      }
+    } catch (err) {
+      // Fall through to cache on direct network failure
+    }
+
+    if (cachedResponse) {
+      return cachedResponse;
+    }
+
+    // Global navigation fallback page check
+    if (request.mode === 'navigate' && this.options.fallbackUrl) {
+      const fallback = await caches.match(this.options.fallbackUrl);
+      if (fallback) return fallback;
+    }
+
+    throw new Error(`NetworkFirst: failed to fetch "${request.url}" and no cached copy was available.`);
+  }
+}
+
+/**
+ * Serves cache instantly, executing a parallel background revalidation.
+ */
+export class StaleRevalidate {
+  constructor(cacheName, options = {}) {
+    this.cacheName = cacheName;
+    this.options = options;
+  }
+
+  async handle(request) {
+    const cache = await caches.open(this.cacheName);
+    const cachedResponse = await cache.match(request);
+
+    const fetchPromise = (async () => {
+      try {
+        const response = await fetch(request);
+        if (response && response.ok) {
+          const storedRes = await cloneWithExpiry(response, this.options.ttl);
+          await cache.put(request, storedRes);
+        }
+        return response;
+      } catch (err) {
+        console.warn(`StaleRevalidate background fetch failed for "${request.url}":`, err);
+        throw err;
+      }
+    })();
+
+    if (cachedResponse) {
+      // Catch error in background to prevent unhandled rejection crashes
+      fetchPromise.catch(() => {});
+      return cachedResponse;
+    }
+
+    return fetchPromise;
+  }
+}
+
+/**
+ * Two-pass caching strategy. Returns cache instantly, background fetches the network update,
+ * and posts the new payload to open window contexts via postMessage.
+ */
+export class CacheThenNetwork {
+  constructor(cacheName, options = {}) {
+    this.cacheName = cacheName;
+    this.options = options;
+  }
+
+  async handle(request) {
+    const cache = await caches.open(this.cacheName);
+    const cachedResponse = await cache.match(request);
+
+    const fetchPromise = (async () => {
+      try {
+        const response = await fetch(request);
+        if (response && response.ok) {
+          const storedRes = await cloneWithExpiry(response, this.options.ttl);
+          await cache.put(request, storedRes);
+
+          // Dispatch update event to all controlled clients
+          const clientsList = await self.clients.matchAll();
+          if (clientsList.length > 0) {
+            let payload = null;
+            const contentType = response.headers.get('content-type') ?? '';
+            if (contentType.includes('application/json')) {
+              try {
+                payload = await response.clone().json();
+              } catch {}
+            }
+
+            for (const client of clientsList) {
+              client.postMessage({
+                type: 'cache-update',
+                url: request.url,
+                payload
+              });
+            }
+          }
+        }
+        return response;
+      } catch (err) {
+        console.warn(`CacheThenNetwork background fetch failed for "${request.url}":`, err);
+        throw err;
+      }
+    })();
+
+    if (cachedResponse) {
+      fetchPromise.catch(() => {});
+      return cachedResponse;
+    }
+
+    return fetchPromise;
+  }
+}
+
+/**
+ * Bypasses caches, direct network execution.
+ */
+export class NetworkOnly {
+  async handle(request) {
+    return fetch(request);
+  }
+}
+
+/**
+ * Restricts queries purely to cache entries.
+ */
+export class CacheOnly {
+  constructor(cacheName) {
+    this.cacheName = cacheName;
+  }
+
+  async handle(request) {
+    const cache = await caches.open(this.cacheName);
+    const cachedResponse = await cache.match(request);
+    if (!cachedResponse) {
+      throw new Error(`CacheOnly: response for "${request.url}" not found in cache "${this.cacheName}"`);
+    }
+    return cachedResponse;
+  }
+}
+
+/**
+ * Intercepts failing navigations, returning a pre-cached fallback webpage.
+ */
+export class OfflineFallback {
+  constructor(fallbackUrl) {
+    this.fallbackUrl = fallbackUrl;
+  }
+
+  async handle(request, error) {
+    if (request.mode === 'navigate') {
+      const fallback = await caches.match(this.fallbackUrl);
+      if (fallback) return fallback;
+    }
+    throw error || new Error('Request failed and offline fallback page was not available.');
+  }
+}

package/src/sw/sync.js

@@ -0,0 +1,80 @@
+/**
+ * src/sw/sync.js
+ *
+ * Background Sync Queue Replayer.
+ * Replays persistent IndexedDB tasks chronologically, re-executes serialized Requests,
+ * coordinates retries, handles dead-letter limits, and broadcasts results.
+ *
+ * Source: doc 13 — Offline and Background §5
+ */
+
+import { queue } from '../core/offline/queue.js';
+import { deserializeRequest } from './queue.js';
+
+/**
+ * Replays all queued offline tasks chronologically in FIFO order.
+ */
+export async function replayQueue() {
+  const list = await queue.list();
+
+  for (const entry of list) {
+    if (entry.failed) continue; // Skip permanently failed items in the DLQ
+
+    try {
+      const request = deserializeRequest(entry.payload);
+      const response = await fetch(request);
+
+      if (response && response.ok) {
+        // Success: evict from queue
+        await queue.delete(entry.id);
+
+        // Broadcast success to all controlled clients
+        const clientsList = await self.clients.matchAll();
+        for (const client of clientsList) {
+          client.postMessage({
+            type: 'sync-success',
+            id: entry.id,
+            task: entry.task
+          });
+        }
+      } else {
+        // Server returned a failure (e.g. 5xx)
+        await requeueFailed(entry, new Error(`Server returned HTTP status ${response.status}`));
+      }
+    } catch (err) {
+      // Network failure (device went offline again or timeout)
+      await requeueFailed(entry, err);
+      // Halt execution immediately to preserve causal ordering of subsequent actions
+      throw err;
+    }
+  }
+}
+
+/**
+ * Increments task retry counts and transitions them to dead-letter states at the limit.
+ */
+export async function requeueFailed(entry, error) {
+  entry.retries = (entry.retries ?? 0) + 1;
+  const maxRetries = entry.maxRetries ?? 5;
+
+  if (entry.retries >= maxRetries) {
+    // Dead Letter Queue transition
+    entry.failed = true;
+    entry.error = error?.message || 'Maximum sync retries exceeded';
+    await queue.update(entry);
+
+    // Broadcast permanent failure to controlled clients
+    const clientsList = await self.clients.matchAll();
+    for (const client of clientsList) {
+      client.postMessage({
+        type: 'sync-failed',
+        id: entry.id,
+        task: entry.task,
+        error: entry.error
+      });
+    }
+  } else {
+    // Update incremented retries
+    await queue.update(entry);
+  }
+}

package/src/tokens/index.css

@@ -0,0 +1,26 @@
+/**
+ * tokens/index.css
+ *
+ * Master design token system import entry.
+ * Strict cascade loading order: Primitives -> Registered -> Semantic
+ * Source: doc 26 §7
+ */
+
+/* 1. Primitives (Fixed Scale Decision Scales) */
+@import './primitives/colors.css';
+@import './primitives/spacing.css';
+@import './primitives/typography.css';
+@import './primitives/motion.css';
+@import './primitives/radius.css';
+@import './primitives/shadow.css';
+@import './primitives/zindex.css';
+
+/* 2. Registered (Houdini Typed Properties for Animation) */
+@import './registered/colors.css';
+@import './registered/dimensions.css';
+
+/* 3. Semantic (Meaning and Intent-based Mappings) */
+@import './semantic/light.css';
+@import './semantic/dark.css';
+@import './semantic/contrast.css';
+@import './semantic/components.css';

package/src/tokens/primitives/colors.css

@@ -0,0 +1,54 @@
+/**
+ * tokens/primitives/colors.css
+ *
+ * Perceptually uniform brand, neutral, and status color scales using OKLCH.
+ * Equal numerical differences correspond to equal visual differences.
+ * Source: doc 26 §3
+ */
+
+:root {
+  /* Brand palette — 12-step perceptual scale in OKLCH */
+  --color-brand-50:  oklch(97% 0.05 250);
+  --color-brand-100: oklch(92% 0.08 250);
+  --color-brand-200: oklch(85% 0.12 250);
+  --color-brand-300: oklch(76% 0.16 250);
+  --color-brand-400: oklch(66% 0.20 250);
+  --color-brand-500: oklch(55% 0.22 250);
+  --color-brand-600: oklch(46% 0.20 250);
+  --color-brand-700: oklch(38% 0.18 250);
+  --color-brand-800: oklch(30% 0.14 250);
+  --color-brand-900: oklch(22% 0.10 250);
+  --color-brand-950: oklch(14% 0.06 250);
+
+  /* Neutral palette */
+  --color-neutral-0:    oklch(100% 0 0);
+  --color-neutral-50:   oklch(97% 0 0);
+  --color-neutral-100:  oklch(94% 0 0);
+  --color-neutral-200:  oklch(88% 0 0);
+  --color-neutral-300:  oklch(78% 0 0);
+  --color-neutral-400:  oklch(64% 0 0);
+  --color-neutral-500:  oklch(50% 0 0);
+  --color-neutral-600:  oklch(38% 0 0);
+  --color-neutral-700:  oklch(27% 0 0);
+  --color-neutral-800:  oklch(18% 0 0);
+  --color-neutral-900:  oklch(10% 0 0);
+  --color-neutral-950:  oklch(6% 0 0);
+  --color-neutral-1000: oklch(0% 0 0);
+
+  /* Status palette */
+  --color-success-50:  oklch(97% 0.02 145);
+  --color-success-500: oklch(63% 0.19 145);
+  --color-success-600: oklch(53% 0.17 145);
+  
+  --color-warning-50:  oklch(98% 0.02 65);
+  --color-warning-500: oklch(75% 0.18 65);
+  --color-warning-600: oklch(67% 0.16 65);
+  
+  --color-error-50:    oklch(96% 0.02 25);
+  --color-error-500:   oklch(58% 0.22 25);
+  --color-error-600:   oklch(48% 0.20 25);
+  
+  --color-info-50:     oklch(97% 0.02 230);
+  --color-info-500:    oklch(60% 0.18 230);
+  --color-info-600:    oklch(50% 0.16 230);
+}

package/src/tokens/primitives/motion.css

@@ -0,0 +1,34 @@
+/**
+ * tokens/primitives/motion.css
+ *
+ * Durations and easing curves for transitions and animations.
+ * Features central global prefers-reduced-motion token-layer overrides.
+ * Source: doc 26 §4
+ */
+
+:root {
+  /* Durations */
+  --duration-instant: 50ms;
+  --duration-fast:    100ms;
+  --duration-normal:  200ms;
+  --duration-slow:    300ms;
+  --duration-slower:  500ms;
+
+  /* Easing curves */
+  --ease-default:   cubic-bezier(0.4, 0, 0.2, 1);
+  --ease-in:        cubic-bezier(0.4, 0, 1, 1);
+  --ease-out:       cubic-bezier(0, 0, 0.2, 1);
+  --ease-in-out:    cubic-bezier(0.4, 0, 0.6, 1);
+  --ease-spring:    cubic-bezier(0.34, 1.56, 0.64, 1);
+  --ease-linear:    linear;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  :root {
+    --duration-instant: 0ms;
+    --duration-fast:    0ms;
+    --duration-normal:  0ms;
+    --duration-slow:    0ms;
+    --duration-slower:  0ms;
+  }
+}

package/src/tokens/primitives/radius.css

@@ -0,0 +1,16 @@
+/**
+ * tokens/primitives/radius.css
+ *
+ * Border radius scale from none to full pill/circle shapes.
+ * Source: doc 26 §4
+ */
+
+:root {
+  --radius-none: 0px;
+  --radius-sm:   0.125rem;   /* 2px */
+  --radius-md:   0.375rem;   /* 6px */
+  --radius-lg:   0.5rem;     /* 8px */
+  --radius-xl:   0.75rem;    /* 12px */
+  --radius-2xl:  1rem;       /* 16px */
+  --radius-full: 9999px;     /* Pill / Circle */
+}

package/src/tokens/primitives/shadow.css

@@ -0,0 +1,34 @@
+/**
+ * tokens/primitives/shadow.css
+ *
+ * Elevation shadows using modern ambient + key light OKLCH alpha models.
+ * Dark mode shadows automatically increase opacity to counteract low contrast.
+ * Source: doc 26 §4
+ */
+
+:root {
+  --shadow-xs:   0 1px 2px 0 oklch(0% 0 0 / 0.05);
+  --shadow-sm:   0 1px 3px 0 oklch(0% 0 0 / 0.1), 0 1px 2px -1px oklch(0% 0 0 / 0.1);
+  --shadow-md:   0 4px 6px -1px oklch(0% 0 0 / 0.1), 0 2px 4px -2px oklch(0% 0 0 / 0.1);
+  --shadow-lg:   0 10px 15px -3px oklch(0% 0 0 / 0.1), 0 4px 6px -4px oklch(0% 0 0 / 0.1);
+  --shadow-xl:   0 20px 25px -5px oklch(0% 0 0 / 0.1), 0 8px 10px -6px oklch(0% 0 0 / 0.1);
+  --shadow-none: 0 0 #0000;
+}
+
+[data-theme="dark"] {
+  --shadow-xs:   0 1px 2px 0 oklch(0% 0 0 / 0.15);
+  --shadow-sm:   0 1px 3px 0 oklch(0% 0 0 / 0.3), 0 1px 2px -1px oklch(0% 0 0 / 0.3);
+  --shadow-md:   0 4px 6px -1px oklch(0% 0 0 / 0.3), 0 2px 4px -2px oklch(0% 0 0 / 0.3);
+  --shadow-lg:   0 10px 15px -3px oklch(0% 0 0 / 0.3), 0 4px 6px -4px oklch(0% 0 0 / 0.3);
+  --shadow-xl:   0 20px 25px -5px oklch(0% 0 0 / 0.3), 0 8px 10px -6px oklch(0% 0 0 / 0.3);
+}
+
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme="light"]) {
+    --shadow-xs:   0 1px 2px 0 oklch(0% 0 0 / 0.15);
+    --shadow-sm:   0 1px 3px 0 oklch(0% 0 0 / 0.3), 0 1px 2px -1px oklch(0% 0 0 / 0.3);
+    --shadow-md:   0 4px 6px -1px oklch(0% 0 0 / 0.3), 0 2px 4px -2px oklch(0% 0 0 / 0.3);
+    --shadow-lg:   0 10px 15px -3px oklch(0% 0 0 / 0.3), 0 4px 6px -4px oklch(0% 0 0 / 0.3);
+    --shadow-xl:   0 20px 25px -5px oklch(0% 0 0 / 0.3), 0 8px 10px -6px oklch(0% 0 0 / 0.3);
+  }
+}

package/src/tokens/primitives/spacing.css

@@ -0,0 +1,27 @@
+/**
+ * tokens/primitives/spacing.css
+ *
+ * Fixed spacing scale using rem units based on a 4px increment system.
+ * Source: doc 26 §4
+ */
+
+:root {
+  --space-px:  1px;
+  --space-0:   0px;
+  --space-0-5: 0.125rem;  /* 2px */
+  --space-1:   0.25rem;   /* 4px */
+  --space-1-5: 0.375rem;  /* 6px */
+  --space-2:   0.5rem;    /* 8px */
+  --space-2-5: 0.625rem;  /* 10px */
+  --space-3:   0.75rem;   /* 12px */
+  --space-4:   1rem;      /* 16px */
+  --space-5:   1.25rem;   /* 20px */
+  --space-6:   1.5rem;    /* 24px */
+  --space-8:   2rem;      /* 32px */
+  --space-10:  2.5rem;    /* 40px */
+  --space-12:  3rem;      /* 48px */
+  --space-16:  4rem;      /* 64px */
+  --space-20:  5rem;      /* 80px */
+  --space-24:  6rem;      /* 96px */
+  --space-32:  8rem;      /* 128px */
+}

package/src/tokens/primitives/typography.css

@@ -0,0 +1,46 @@
+/**
+ * tokens/primitives/typography.css
+ *
+ * Typography scales, weights, line-heights, letter-spacings, and font stacks.
+ * Source: doc 26 §4
+ */
+
+:root {
+  /* Modular type scale (1.25 ratio) */
+  --font-size-xs:   0.75rem;   /* 12px */
+  --font-size-sm:   0.875rem;  /* 14px */
+  --font-size-base: 1rem;      /* 16px */
+  --font-size-md:   1.125rem;  /* 18px */
+  --font-size-lg:   1.25rem;   /* 20px */
+  --font-size-xl:   1.5rem;    /* 24px */
+  --font-size-2xl:  1.875rem;  /* 30px */
+  --font-size-3xl:  2.25rem;   /* 36px */
+  --font-size-4xl:  3rem;      /* 48px */
+  --font-size-5xl:  3.75rem;   /* 60px */
+
+  /* Font weights */
+  --font-weight-light:    300;
+  --font-weight-regular:  400;
+  --font-weight-medium:   500;
+  --font-weight-semibold: 600;
+  --font-weight-bold:     700;
+
+  /* Line heights */
+  --line-height-tight:   1.25;
+  --line-height-snug:    1.375;
+  --line-height-normal:  1.5;
+  --line-height-relaxed: 1.625;
+  --line-height-loose:   2;
+
+  /* Letter spacing */
+  --letter-spacing-tight:  -0.025em;
+  --letter-spacing-normal:  0;
+  --letter-spacing-wide:    0.025em;
+  --letter-spacing-wider:   0.05em;
+  --letter-spacing-widest:  0.1em;
+
+  /* Font families */
+  --font-family-sans:  'Outfit', 'Inter', system-ui, -apple-system, sans-serif;
+  --font-family-serif: 'Georgia', 'Times New Roman', serif;
+  --font-family-mono:  'JetBrains Mono', 'Fira Code', monospace;
+}

package/src/tokens/primitives/zindex.css

@@ -0,0 +1,18 @@
+/**
+ * tokens/primitives/zindex.css
+ *
+ * Explicit layer indices to eliminate z-index escalation bugs.
+ * Source: doc 26 §4
+ */
+
+:root {
+  --z-index-base:     0;
+  --z-index-raised:   10;
+  --z-index-dropdown: 100;
+  --z-index-sticky:   200;
+  --z-index-overlay:  300;
+  --z-index-modal:    400;
+  --z-index-popover:  500;
+  --z-index-toast:    600;
+  --z-index-tooltip:  700;
+}