@adukiorg/anza 0.2.0

package/src/core/platform/platform.d.ts

@@ -0,0 +1,88 @@
+/**
+ * core/platform/platform.d.ts
+ *
+ * TypeScript definitions for the platform module.
+ * Types the supports detection registry, reset function, and guard loader.
+ */
+
+export interface Supports {
+  // --- Routing ---
+  navigationAPI: boolean;
+  urlPattern: boolean;
+
+  // --- Component Model ---
+  declarativeShadowDOM: boolean;
+  customStatePseudo: boolean;
+  formAssociated: boolean;
+
+  // --- Overlay / Popover ---
+  popoverAPI: boolean;
+  anchorPositioning: boolean;
+
+  // --- Animation ---
+  viewTransitions: boolean;
+  scrollTimeline: boolean;
+  viewTimeline: boolean;
+
+  // --- Scheduling ---
+  schedulerPostTask: boolean;
+  schedulerYield: boolean;
+
+  // --- CSS ---
+  contentVisibility: boolean;
+  cssScope: boolean;
+  cssLayer: boolean;
+  cssModuleScripts: boolean;
+
+  // --- Module System ---
+  importMaps: boolean;
+
+  // --- Security ---
+  sanitizerAPI: boolean;
+  trustedTypes: boolean;
+  subtleCrypto: boolean;
+
+  // --- Storage ---
+  opfs: boolean;
+  storageManager: boolean;
+  fileSystemPickers: boolean;
+  compression: boolean;
+  storagePersistence: boolean;
+
+  // --- Networking / Workers ---
+  backgroundSync: boolean;
+  speculationRules: boolean;
+  sharedWorker: boolean;
+  webLocks: boolean;
+  offscreenCanvas: boolean;
+
+  // --- Notifications / Push ---
+  pushAPI: boolean;
+  notificationsAPI: boolean;
+
+  // --- Device ---
+  screenWakeLock: boolean;
+  idleDetection: boolean;
+  webAuthn: boolean;
+}
+
+export const supports: Supports;
+
+export function reset(key: keyof Supports): void;
+
+export function typeGuard(key: keyof Supports, message?: string): void;
+
+export interface Guard {
+  urlPattern(): Promise<typeof URLPattern>;
+  navigation(): Promise<Navigation>;
+  popover(): Promise<void>;
+  shadow(root?: Document | ShadowRoot): Promise<void>;
+  anchor(floating: HTMLElement, anchorEl: HTMLElement, options?: object): Promise<void>;
+  sanitizer(): Promise<{ sanitizeToString(input: string): string }>;
+  scheduler(): Promise<Scheduler>;
+  yield(): Promise<void>;
+}
+
+declare const guard: Guard;
+
+export default guard;

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

@@ -0,0 +1,79 @@
+/**
+ * core/platform/polyfills/anchor.js
+ *
+ * Lightweight CSS Anchor Positioning positional fallback.
+ * Computes optimal absolute top/left coordinates based on placement rules and viewport collisions.
+ * Source: doc 18 §12, library2.md §Phase 1-A
+ */
+
+export function position(floating, anchor, options = {}) {
+  if (!floating || !anchor) return;
+
+  const placement = options.placement || 'bottom-start';
+  const offset = options.offset || 8;
+
+  const anchorRect = anchor.getBoundingClientRect();
+  const floatRect = floating.getBoundingClientRect();
+
+  const scrollY = globalThis.scrollY || globalThis.pageYOffset || 0;
+  const scrollX = globalThis.scrollX || globalThis.pageXOffset || 0;
+
+  const anchorTop = anchorRect.top + scrollY;
+  const anchorLeft = anchorRect.left + scrollX;
+
+  let top = 0;
+  let left = 0;
+
+  switch (placement) {
+    case 'bottom-start':
+      top = anchorTop + anchorRect.height + offset;
+      left = anchorLeft;
+      break;
+    case 'bottom-end':
+      top = anchorTop + anchorRect.height + offset;
+      left = anchorLeft + anchorRect.width - floatRect.width;
+      break;
+    case 'top-start':
+      top = anchorTop - floatRect.height - offset;
+      left = anchorLeft;
+      break;
+    case 'top-end':
+      top = anchorTop - floatRect.height - offset;
+      left = anchorLeft + anchorRect.width - floatRect.width;
+      break;
+    case 'right-start':
+      top = anchorTop;
+      left = anchorLeft + anchorRect.width + offset;
+      break;
+    case 'left-start':
+      top = anchorTop;
+      left = anchorLeft - floatRect.width - offset;
+      break;
+    default:
+      top = anchorTop + anchorRect.height + offset;
+      left = anchorLeft;
+  }
+
+  // Viewport containment checking
+  const viewportWidth = globalThis.innerWidth || 0;
+  const viewportHeight = globalThis.innerHeight || 0;
+
+  if (left < scrollX) {
+    left = scrollX;
+  }
+  if (left + floatRect.width > scrollX + viewportWidth) {
+    left = Math.max(scrollX, scrollX + viewportWidth - floatRect.width);
+  }
+  if (top < scrollY) {
+    top = scrollY;
+  }
+  if (top + floatRect.height > scrollY + viewportHeight) {
+    top = Math.max(scrollY, scrollY + viewportHeight - floatRect.height);
+  }
+
+  floating.style.position = 'absolute';
+  floating.style.top = `${top}px`;
+  floating.style.left = `${left}px`;
+}
+
+export default { position };

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

@@ -0,0 +1,142 @@
+/**
+ * core/platform/polyfills/navigation.js
+ *
+ * A lightweight History-API based polyfill for the WICG Navigation API.
+ * Provides the event system, navigate interception, and click delegation.
+ * Source: doc 18 §3, library2.md §Phase 1-A
+ */
+
+class NavigationEvent extends Event {
+  constructor(type, init) {
+    super(type, init);
+    this.destination = init.destination;
+    this.navigationType = init.navigationType || 'push';
+    this.signal = init.signal;
+    this.userInitiated = init.userInitiated !== false;
+    this.canIntercept = init.canIntercept !== false;
+    this.hashChange = init.hashChange || false;
+    this.downloadRequest = init.downloadRequest || false;
+    this._intercepted = false;
+    this._handlers = [];
+  }
+
+  intercept(options) {
+    this._intercepted = true;
+    if (options && typeof options.handler === 'function') {
+      this._handlers.push(options.handler);
+    }
+  }
+}
+
+class NavigationPolyfill extends EventTarget {
+  constructor() {
+    super();
+    if (typeof document !== 'undefined') {
+      // Global click delegation for same-origin anchor links
+      document.addEventListener('click', e => {
+        if (e.defaultPrevented || e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
+        const anchor = e.target.closest('a[href]');
+        if (!anchor) return;
+
+        // Skip non-HTTP links and external targets
+        if (anchor.target && anchor.target !== '_self') return;
+        
+        try {
+          const url = new URL(anchor.href, globalThis.location.href);
+          if (url.origin !== globalThis.location.origin) return;
+
+          const event = this._fireNavigate(url.href, { navigationType: 'push' });
+          if (event._intercepted) {
+            e.preventDefault();
+            history.pushState(null, '', url.href);
+            this._runHandlers(event);
+          }
+        } catch {
+          // ignore parsing error, let native navigation handle it
+        }
+      });
+
+      // Browser forward/back traversal support
+      window.addEventListener('popstate', e => {
+        const event = this._fireNavigate(globalThis.location.href, {
+          navigationType: 'traverse',
+          state: e.state
+        });
+        if (event._intercepted) {
+          this._runHandlers(event);
+        }
+      });
+    }
+  }
+
+  get canGoBack() {
+    return true;
+  }
+
+  get canGoForward() {
+    return true;
+  }
+
+  navigate(url, options = {}) {
+    try {
+      const targetUrl = new URL(url, globalThis.location.href).href;
+      const event = this._fireNavigate(targetUrl, {
+        navigationType: options.history === 'replace' ? 'replace' : 'push',
+        state: options.state
+      });
+
+      if (event._intercepted) {
+        if (options.history === 'replace') {
+          history.replaceState(options.state, '', targetUrl);
+        } else {
+          history.pushState(options.state, '', targetUrl);
+        }
+        this._runHandlers(event);
+      } else {
+        globalThis.location.href = targetUrl;
+      }
+    } catch (err) {
+      this.dispatchEvent(new ErrorEvent('navigateerror', { error: err }));
+    }
+  }
+
+  back() {
+    history.back();
+  }
+
+  forward() {
+    history.forward();
+  }
+
+  go(delta) {
+    history.go(delta);
+  }
+
+  _fireNavigate(url, { navigationType, state } = {}) {
+    const controller = new AbortController();
+    const event = new NavigationEvent('navigate', {
+      cancelable: true,
+      destination: { url, state },
+      navigationType,
+      signal: controller.signal
+    });
+    this.dispatchEvent(event);
+    return event;
+  }
+
+  async _runHandlers(event) {
+    try {
+      for (const handler of event._handlers) {
+        await handler();
+      }
+      this.dispatchEvent(new Event('navigatesuccess'));
+    } catch (err) {
+      this.dispatchEvent(new ErrorEvent('navigateerror', { error: err }));
+    }
+  }
+}
+
+if (!globalThis.navigation) {
+  globalThis.navigation = new NavigationPolyfill();
+}
+export default NavigationPolyfill;

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

@@ -0,0 +1,142 @@
+/**
+ * core/platform/polyfills/popover.js
+ *
+ * Popover API polyfill offering showPopover, hidePopover, togglePopover,
+ * light dismiss, popovertarget click wiring, and simulated top-layer overlay.
+ * Source: doc 18 §12, library2.md §Phase 1-A
+ */
+
+class ToggleEvent extends Event {
+  constructor(type, init = {}) {
+    super(type, init);
+    this.oldState = init.oldState || 'closed';
+    this.newState = init.newState || 'closed';
+  }
+}
+
+class PopoverPolyfill {
+  static install() {
+    if ('popover' in HTMLElement.prototype) return;
+
+    Object.defineProperty(HTMLElement.prototype, 'popover', {
+      get() {
+        return this.getAttribute('popover');
+      },
+      set(val) {
+        if (val === null) this.removeAttribute('popover');
+        else this.setAttribute('popover', val);
+      },
+      configurable: true,
+      enumerable: true
+    });
+
+    HTMLElement.prototype.showPopover = function() {
+      if (this.getAttribute('popover') === null) {
+        throw new DOMException("Not a popover", "NotSupportedError");
+      }
+      if (this.hasAttribute('data-popover-open')) return;
+
+      // Clean up previous event listeners or observers if any existed
+      if (this._popoverDismiss) {
+        document.removeEventListener('pointerdown', this._popoverDismiss);
+        this._popoverDismiss = null;
+      }
+      if (this._popoverObserver) {
+        this._popoverObserver.disconnect();
+        this._popoverObserver = null;
+      }
+
+      this.setAttribute('data-popover-open', '');
+      
+      // Simulating top-layer styling
+      this.style.position = 'fixed';
+      this.style.zIndex = '2147483647';
+
+      // Light-dismiss behavior for "auto" popovers
+      const type = this.getAttribute('popover');
+      if (type === 'auto' || type === '') {
+        const dismiss = (e) => {
+          if (!this.contains(e.target) && e.target !== this) {
+            this.hidePopover();
+          }
+        };
+        this._popoverDismiss = dismiss;
+        // Defer attachment to prevent immediate closing during current click event
+        setTimeout(() => {
+          if (this.hasAttribute('data-popover-open')) {
+            document.addEventListener('pointerdown', dismiss);
+          }
+        }, 0);
+      }
+
+      // MutationObserver to automatically clean up when popover is unmounted from DOM while open
+      if (typeof MutationObserver !== 'undefined') {
+        const observer = new MutationObserver(() => {
+          if (!document.contains(this)) {
+            this.hidePopover();
+          }
+        });
+        observer.observe(document.body, { childList: true, subtree: true });
+        this._popoverObserver = observer;
+      }
+
+      this.dispatchEvent(new ToggleEvent('toggle', {
+        oldState: 'closed',
+        newState: 'open'
+      }));
+    };
+
+    HTMLElement.prototype.hidePopover = function() {
+      if (!this.hasAttribute('data-popover-open')) return;
+
+      this.removeAttribute('data-popover-open');
+      this.style.position = '';
+      this.style.zIndex = '';
+
+      if (this._popoverDismiss) {
+        document.removeEventListener('pointerdown', this._popoverDismiss);
+        this._popoverDismiss = null;
+      }
+      if (this._popoverObserver) {
+        this._popoverObserver.disconnect();
+        this._popoverObserver = null;
+      }
+
+      this.dispatchEvent(new ToggleEvent('toggle', {
+        oldState: 'open',
+        newState: 'closed'
+      }));
+    };
+
+    HTMLElement.prototype.togglePopover = function() {
+      if (this.hasAttribute('data-popover-open')) {
+        this.hidePopover();
+      } else {
+        this.showPopover();
+      }
+    };
+
+    // Auto-setup declarative triggers
+    if (typeof document !== 'undefined') {
+      document.addEventListener('click', e => {
+        const trigger = e.target.closest('[popovertarget]');
+        if (!trigger) return;
+        const targetId = trigger.getAttribute('popovertarget');
+        const target = document.getElementById(targetId);
+        if (!target) return;
+
+        const action = trigger.getAttribute('popovertargetaction') || 'toggle';
+        if (action === 'show') {
+          target.showPopover();
+        } else if (action === 'hide') {
+          target.hidePopover();
+        } else {
+          target.togglePopover();
+        }
+      });
+    }
+  }
+}
+
+PopoverPolyfill.install();
+export default PopoverPolyfill;

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

@@ -0,0 +1,194 @@
+/**
+ * src/core/platform/polyfills/scheduler.js
+ *
+ * Priority-Aware Task Scheduling Polyfill.
+ * Implements WICG Prioritized Task Scheduling specification interfaces
+ * (scheduler.postTask and scheduler.yield) for browsers lacking native support.
+ *
+ * Source: doc 19 — Browser Runtime Model §16
+ */
+
+let currentPriority = null;
+
+// Standard Priority Hierarchy
+const Priorities = {
+  'user-blocking': 3,
+  'user-visible':  2,
+  'background':    1
+};
+
+// Queue structures
+const queues = {
+  'user-blocking': [],
+  'user-visible':  [],
+  'background':    []
+};
+
+let activeLoop = false;
+
+// High-speed macrotask queue using MessageChannel (bypasses 4ms setTimeout limit)
+const channel = typeof MessageChannel !== 'undefined' ? new MessageChannel() : null;
+const macrotaskQueue = [];
+
+if (channel) {
+  channel.port1.onmessage = () => {
+    const next = macrotaskQueue.shift();
+    if (next) next();
+  };
+}
+
+function enqueueMacrotask(callback) {
+  if (channel) {
+    macrotaskQueue.push(callback);
+    channel.port2.postMessage('');
+  } else {
+    setTimeout(callback, 0);
+  }
+}
+
+/**
+ * Core loop that processes prioritized tasks.
+ */
+function processQueues() {
+  // Find highest priority non-empty queue
+  let selectedPriority = null;
+  if (queues['user-blocking'].length > 0) {
+    selectedPriority = 'user-blocking';
+  } else if (queues['user-visible'].length > 0) {
+    selectedPriority = 'user-visible';
+  } else if (queues['background'].length > 0) {
+    selectedPriority = 'background';
+  }
+
+  if (!selectedPriority) {
+    activeLoop = false;
+    return;
+  }
+
+  activeLoop = true;
+  const task = queues[selectedPriority].shift();
+
+  const runTask = () => {
+    if (task.signal?.aborted) {
+      task.reject(new DOMException('The user aborted a request.', 'AbortError'));
+      processQueues();
+      return;
+    }
+
+    const previousPriority = currentPriority;
+    currentPriority = selectedPriority;
+
+    try {
+      const result = task.callback();
+      if (result instanceof Promise) {
+        result.then(
+          (val) => {
+            currentPriority = previousPriority;
+            task.resolve(val);
+            processQueues();
+          },
+          (err) => {
+            currentPriority = previousPriority;
+            task.reject(err);
+            processQueues();
+          }
+        );
+      } else {
+        currentPriority = previousPriority;
+        task.resolve(result);
+        processQueues();
+      }
+    } catch (err) {
+      currentPriority = previousPriority;
+      task.reject(err);
+      processQueues();
+    }
+  };
+
+  // Schedule task execution based on its priority
+  if (selectedPriority === 'user-blocking') {
+    queueMicrotask(runTask);
+  } else if (selectedPriority === 'user-visible') {
+    enqueueMacrotask(runTask);
+  } else {
+    // background priority: prefer requestIdleCallback if available
+    if (typeof requestIdleCallback === 'function') {
+      requestIdleCallback(runTask, { timeout: 2000 });
+    } else {
+      setTimeout(runTask, 0);
+    }
+  }
+}
+
+/**
+ * Enqueues a callback at a prioritized task level.
+ */
+export function postTask(callback, options = {}) {
+  const priority = options.priority || 'user-visible';
+  if (!(priority in queues)) {
+    throw new TypeError(`Invalid priority: ${priority}`);
+  }
+
+  const signal = options.signal;
+  if (signal?.aborted) {
+    return Promise.reject(new DOMException('The user aborted a request.', 'AbortError'));
+  }
+
+  return new Promise((resolve, reject) => {
+    const taskDescriptor = {
+      callback,
+      resolve,
+      reject,
+      signal
+    };
+
+    const enqueue = () => {
+      queues[priority].push(taskDescriptor);
+      if (signal) {
+        signal.addEventListener('abort', () => {
+          const idx = queues[priority].indexOf(taskDescriptor);
+          if (idx !== -1) {
+            queues[priority].splice(idx, 1);
+            reject(new DOMException('The user aborted a request.', 'AbortError'));
+          }
+        });
+      }
+      if (!activeLoop) {
+        processQueues();
+      }
+    };
+
+    if (typeof options.delay === 'number' && options.delay > 0) {
+      setTimeout(enqueue, options.delay);
+    } else {
+      enqueue();
+    }
+  });
+}
+
+/**
+ * Yields control back to the browser, returning a promise that resolves
+ * inside a rescheduled task at the current priority context level.
+ */
+export function yieldTask() {
+  const priority = currentPriority || 'user-visible';
+  return new Promise((resolve, reject) => {
+    postTask(resolve, { priority }).then(resolve, reject);
+  });
+}
+
+class SchedulerPolyfill {
+  postTask(callback, options) {
+    return postTask(callback, options);
+  }
+
+  yield() {
+    return yieldTask();
+  }
+}
+
+if (typeof globalThis.scheduler === 'undefined') {
+  globalThis.scheduler = new SchedulerPolyfill();
+}
+
+export default globalThis.scheduler;

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

@@ -0,0 +1,35 @@
+/**
+ * core/platform/polyfills/shadow.js
+ *
+ * Declarative Shadow DOM polyfill converting template[shadowrootmode] elements
+ * into native shadow roots. Runs automatically on DOM ready and supports manual invocation.
+ * Source: doc 18 §4, library2.md §Phase 1-A
+ */
+
+export function apply(root = document) {
+  const templates = root.querySelectorAll('template[shadowrootmode]');
+  for (const tpl of templates) {
+    const mode = tpl.getAttribute('shadowrootmode');
+    const host = tpl.parentNode;
+    if (host && typeof host.attachShadow === 'function') {
+      try {
+        const shadow = host.attachShadow({ mode });
+        shadow.appendChild(tpl.content);
+        tpl.remove();
+      } catch (err) {
+        console.warn('Declarative Shadow DOM polyfill failed for host:', host, err);
+      }
+    }
+  }
+}
+
+// Auto-apply on DOM load completion
+if (typeof document !== 'undefined') {
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', () => apply());
+  } else {
+    apply();
+  }
+}
+
+export default apply;