@czap/astro 0.1.0

package/src/quantize.ts

@@ -0,0 +1,173 @@
+/**
+ * Quantize component helpers -- server-side initial state resolution.
+ *
+ * Maps {@link ServerIslandContext} (user agent, client hints, detected
+ * tier) to the best initial boundary state for SSR and server islands.
+ *
+ * @module
+ */
+
+import type { Boundary, CapLevel, Quantizer } from '@czap/core';
+import { VIEWPORT } from '@czap/core';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Server-only context that {@link resolveInitialState} consumes. Astro
+ * builds this from the incoming request (user agent + Client Hints)
+ * and the tier detected by the edge middleware.
+ */
+export interface ServerIslandContext {
+  /** Raw `User-Agent` header. */
+  readonly userAgent: string;
+  /** Flat Client Hints header map. */
+  readonly clientHints: Record<string, string>;
+  /** Tier detected by `@czap/edge`. */
+  readonly detectedTier: CapLevel;
+}
+
+/**
+ * Props accepted by the `Quantize` Astro component and by
+ * {@link resolveInitialState}.
+ */
+export interface QuantizeProps<B extends Boundary.Shape = Boundary.Shape> {
+  /** Boundary to quantize. */
+  readonly boundary: B;
+  /** Optional explicit quantizer definition. */
+  readonly quantizer?: Quantizer<B>;
+  /** Explicit initial state (skips resolution). */
+  readonly initialState?: string;
+  /** Final fallback if resolution fails. */
+  readonly fallback?: string;
+  /** Extra CSS class names. */
+  readonly class?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Client Hint Parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a viewport width from client hints.
+ * Supports Sec-CH-Viewport-Width and Sec-CH-Width headers.
+ */
+function parseViewportWidth(clientHints: Record<string, string>): number | undefined {
+  const raw =
+    clientHints['sec-ch-viewport-width'] ??
+    clientHints['Sec-CH-Viewport-Width'] ??
+    clientHints['sec-ch-width'] ??
+    clientHints['Sec-CH-Width'];
+
+  if (raw === undefined) return undefined;
+  const parsed = parseInt(raw, 10);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+/**
+ * Parse prefers-reduced-motion from client hints.
+ */
+function parsePrefersReducedMotion(clientHints: Record<string, string>): boolean | undefined {
+  const raw = clientHints['sec-ch-prefers-reduced-motion'] ?? clientHints['Sec-CH-Prefers-Reduced-Motion'];
+
+  if (raw === undefined) return undefined;
+  return raw === 'reduce';
+}
+
+// ---------------------------------------------------------------------------
+// User Agent Heuristics
+// ---------------------------------------------------------------------------
+
+/**
+ * Estimate a viewport width from user agent string for common device classes.
+ */
+function estimateViewportFromUA(ua: string): number {
+  const lower = ua.toLowerCase();
+
+  if (lower.includes('mobile') || lower.includes('android') || lower.includes('iphone')) {
+    return VIEWPORT.mobile;
+  }
+  if (lower.includes('tablet') || lower.includes('ipad')) {
+    return VIEWPORT.tablet;
+  }
+  return VIEWPORT.desktop;
+}
+
+// ---------------------------------------------------------------------------
+// Tier-Based Heuristic
+// ---------------------------------------------------------------------------
+
+const TIER_ORDINALS: Record<CapLevel, number> = {
+  static: 0,
+  styled: 1,
+  reactive: 2,
+  animated: 3,
+  gpu: 4,
+};
+
+/**
+ * Map a CapLevel tier to a synthetic viewport-like value for boundary evaluation.
+ * This bridges between the capability tier system and viewport-based boundaries.
+ */
+function syntheticValueFromTier(tier: CapLevel): number {
+  const ord = TIER_ORDINALS[tier];
+  // Map tier ordinal to viewport-like breakpoints: 320, 640, 960, 1280, 1920
+  return 320 + ord * 320;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the initial boundary state for server-side rendering.
+ *
+ * Priority:
+ *   1. Use viewport width from client hints if available
+ *   2. Estimate viewport from user agent
+ *   3. Fall back to tier-based synthetic value
+ *
+ * Evaluates the boundary thresholds to find the matching state.
+ */
+export function resolveInitialState<B extends Boundary.Shape>(boundary: B, context: ServerIslandContext): string {
+  const stateNames = boundary.states as readonly string[];
+  const thresholds = boundary.thresholds as readonly number[];
+
+  if (stateNames.length === 0) return '';
+  if (stateNames.length === 1) return stateNames[0]!;
+
+  // Determine the signal value to evaluate against the boundary
+  let value: number;
+
+  // Check client hints first (most accurate)
+  const hintWidth = parseViewportWidth(context.clientHints);
+  const reducedMotion = parsePrefersReducedMotion(context.clientHints);
+
+  if (hintWidth !== undefined) {
+    value = hintWidth;
+  } else if (context.userAgent) {
+    value = estimateViewportFromUA(context.userAgent);
+  } else {
+    value = syntheticValueFromTier(context.detectedTier);
+  }
+
+  // If reduced motion is detected and the tier suggests limited capability,
+  // bias toward the lowest state
+  if (reducedMotion === true && TIER_ORDINALS[context.detectedTier] <= 1) {
+    return stateNames[0]!;
+  }
+
+  // Evaluate against boundary thresholds to find the matching state.
+  // thresholds[i] is the lower bound for state[i].
+  // Walk backwards from the highest threshold to find the first match.
+  for (let i = stateNames.length - 1; i >= 0; i--) {
+    const threshold = thresholds[i];
+    if (threshold !== undefined && value >= threshold) {
+      return stateNames[i]!;
+    }
+  }
+
+  // Fallback to first state
+  return stateNames[0]!;
+}

package/src/runtime/boundary.ts

@@ -0,0 +1,263 @@
+/**
+ * Client-runtime helpers for parsing serialized boundaries out of
+ * `data-czap-boundary` attributes, attaching viewport observers,
+ * evaluating boundaries live, and applying the resulting state to a
+ * satellite element.
+ *
+ * Consumed by the Astro `client:satellite` / `client:worker` directives
+ * when they hydrate a server-rendered `<div data-czap-boundary="...">`.
+ *
+ * @module
+ */
+import { Boundary } from '@czap/core';
+
+/**
+ * JSON shape produced on the server by `satelliteAttrs()` and read back
+ * on the client via {@link parseBoundary}. Every field corresponds
+ * directly to a {@link Boundary.Shape} input.
+ */
+export interface SerializedBoundary {
+  /** Optional stable boundary id (becomes the runtime `name`). */
+  readonly id?: string;
+  /** Signal key this boundary consumes (e.g. `"viewport.width"`). */
+  readonly input: string;
+  /** Ordered ascending thresholds (`thresholds[i]` lower bound of `states[i]`). */
+  readonly thresholds: readonly number[];
+  /** Non-empty ordered state labels. */
+  readonly states: readonly [string, ...string[]];
+  /** Optional hysteresis band applied during evaluation. */
+  readonly hysteresis?: number;
+}
+
+/**
+ * Client-side representation of a parsed boundary plus its resolved
+ * runtime name, ready to be evaluated against a live signal.
+ */
+export interface RuntimeBoundary {
+  /** Resolved boundary name (defaults to `"default"`). */
+  readonly name: string;
+  /** Signal key this boundary consumes. */
+  readonly input: string;
+  /** Fully-constructed `Boundary.Shape` ready for evaluation. */
+  readonly boundary: Boundary.Shape<string, readonly [string, ...string[]]>;
+}
+
+/**
+ * Normalised boundary-state payload used for `CustomEvent` dispatch and
+ * DOM application. CSS keys are filtered to `--czap-*`; ARIA keys to
+ * `role` / `aria-*`.
+ */
+export interface BoundaryStateDetail {
+  /** Discrete state per quantizer name. */
+  readonly discrete: Record<string, string>;
+  /** Whitelisted `--czap-*` CSS variable map. */
+  readonly css: Record<string, string | number>;
+  /** GLSL uniform map (`u_*`). */
+  readonly glsl: Record<string, number>;
+  /** Whitelisted ARIA attribute map. */
+  readonly aria: Record<string, string>;
+}
+
+function isAllowedBoundaryCssProperty(property: string): boolean {
+  return property.startsWith('--czap-');
+}
+
+// NOTE: This logic is intentionally duplicated from `isValidAriaKey` in
+// packages/compiler/src/aria.ts. @czap/astro does not depend on @czap/compiler,
+// so the check cannot be shared without introducing a new dependency. Keep the
+// two implementations in sync if either changes.
+function isAllowedBoundaryAttribute(attribute: string): boolean {
+  return attribute === 'role' || attribute.startsWith('aria-');
+}
+
+function parseBoundaryPayload(boundaryJson: string): Partial<SerializedBoundary> | null {
+  let parsed: Partial<SerializedBoundary> | null = null;
+  let malformed = false;
+
+  try {
+    parsed = JSON.parse(boundaryJson) as Partial<SerializedBoundary>;
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      malformed = true;
+    } else {
+      throw error;
+    }
+  }
+
+  return malformed ? null : parsed;
+}
+
+/**
+ * Parse a JSON-serialised boundary (as produced by
+ * `satelliteAttrs()`) into a {@link RuntimeBoundary}. Returns `null`
+ * for malformed or structurally invalid payloads so callers can fall
+ * back cleanly rather than throwing mid-hydration.
+ */
+export function parseBoundary(boundaryJson: string | null): RuntimeBoundary | null {
+  if (!boundaryJson) {
+    return null;
+  }
+
+  const parsed = parseBoundaryPayload(boundaryJson);
+  if (!parsed) {
+    return null;
+  }
+
+  if (
+    typeof parsed.input !== 'string' ||
+    !Array.isArray(parsed.thresholds) ||
+    parsed.thresholds.length === 0 ||
+    !Array.isArray(parsed.states) ||
+    parsed.states.length === 0 ||
+    !parsed.thresholds.every((value) => typeof value === 'number') ||
+    !parsed.states.every((value) => typeof value === 'string')
+  ) {
+    return null;
+  }
+
+  const states = parsed.states as readonly [string, ...string[]];
+  const first = [parsed.thresholds[0]!, states[0]] as const;
+  const rest = parsed.thresholds.slice(1).map((threshold, index) => [threshold, states[index + 1]!] as const);
+  const at = [first, ...rest] as const;
+
+  return {
+    name: parsed.id ?? 'default',
+    input: parsed.input,
+    boundary: Boundary.make({
+      input: parsed.input,
+      at,
+      ...(typeof parsed.hysteresis === 'number' ? { hysteresis: parsed.hysteresis } : {}),
+    }),
+  };
+}
+
+/**
+ * Attach a ResizeObserver on `document.documentElement` that calls `callback`
+ * whenever the viewport resizes, but only when `input` is a viewport signal
+ * (i.e. starts with `"viewport."`) and `ResizeObserver` is available.
+ *
+ * Returns a cleanup function that disconnects the observer, or `null` when no
+ * observer was attached (non-viewport input or no ResizeObserver support).
+ *
+ * Centralises the identical `observeIfNeeded` blocks that previously lived in
+ * satellite.ts and worker.ts.
+ */
+export function attachViewportObserver(input: string, callback: () => void): (() => void) | null {
+  if (!input.startsWith('viewport.') || typeof ResizeObserver === 'undefined') {
+    return null;
+  }
+
+  const observer = new ResizeObserver(callback);
+  observer.observe(document.documentElement);
+  return () => observer.disconnect();
+}
+
+/**
+ * Read the current numeric value for a signal `input` (e.g.
+ * `"viewport.width"`). Returns `undefined` for unknown inputs; returns
+ * `0` in non-DOM environments so callers can treat SSR and malformed
+ * signals uniformly.
+ */
+export function readSignalValue(input: string): number | undefined {
+  if (typeof window === 'undefined') return 0;
+
+  if (!input.startsWith('viewport.')) {
+    return undefined;
+  }
+
+  const axis = input.slice('viewport.'.length);
+  return axis === 'height' ? window.innerHeight : window.innerWidth;
+}
+
+/**
+ * Evaluate a {@link RuntimeBoundary} against a signal value, applying
+ * hysteresis when `previousState` is provided and the boundary has a
+ * hysteresis band.
+ */
+export function evaluateBoundary(boundary: RuntimeBoundary, value: number, previousState?: string): string {
+  if (previousState && boundary.boundary.hysteresis) {
+    return Boundary.evaluateWithHysteresis(boundary.boundary, value, previousState);
+  }
+
+  return Boundary.evaluate(boundary.boundary, value);
+}
+
+/**
+ * Merge `state.*` and `state.outputs.*` fields into a single
+ * {@link BoundaryStateDetail}, filtering CSS keys to `--czap-*` and
+ * ARIA keys to `role` / `aria-*`. Used as the `detail` of the
+ * `czap:state` custom event.
+ */
+export function normalizeBoundaryState(state: {
+  readonly discrete?: Record<string, string>;
+  readonly css?: Record<string, string | number>;
+  readonly glsl?: Record<string, number>;
+  readonly aria?: Record<string, string>;
+  readonly outputs?: {
+    readonly css?: Record<string, string | number>;
+    readonly glsl?: Record<string, number>;
+    readonly aria?: Record<string, string>;
+  };
+}): BoundaryStateDetail {
+  const css = { ...(state.outputs?.css ?? {}), ...(state.css ?? {}) };
+  const aria = { ...(state.outputs?.aria ?? {}), ...(state.aria ?? {}) };
+
+  return {
+    discrete: { ...(state.discrete ?? {}) },
+    css: Object.fromEntries(Object.entries(css).filter(([property]) => isAllowedBoundaryCssProperty(property))),
+    glsl: { ...(state.outputs?.glsl ?? {}), ...(state.glsl ?? {}) },
+    aria: Object.fromEntries(Object.entries(aria).filter(([attribute]) => isAllowedBoundaryAttribute(attribute))),
+  };
+}
+
+/**
+ * Apply a normalised state to a satellite element: sets
+ * `data-czap-state`, writes whitelisted CSS variables and ARIA
+ * attributes, and dispatches `eventName` + `czap:uniform-update`
+ * custom events for downstream listeners (GPU/WASM runtimes).
+ */
+export function applyBoundaryState(
+  element: HTMLElement,
+  boundary: RuntimeBoundary,
+  state: {
+    readonly discrete?: Record<string, string>;
+    readonly css?: Record<string, string | number>;
+    readonly glsl?: Record<string, number>;
+    readonly aria?: Record<string, string>;
+    readonly outputs?: {
+      readonly css?: Record<string, string | number>;
+      readonly glsl?: Record<string, number>;
+      readonly aria?: Record<string, string>;
+    };
+  },
+  eventName: string,
+): void {
+  const detail = normalizeBoundaryState(state);
+  const stateName = detail.discrete[boundary.name];
+
+  if (stateName && element.getAttribute('data-czap-state') !== stateName) {
+    element.setAttribute('data-czap-state', stateName);
+  }
+
+  for (const [property, value] of Object.entries(detail.css)) {
+    element.style.setProperty(property, String(value));
+  }
+
+  for (const [attribute, value] of Object.entries(detail.aria)) {
+    element.setAttribute(attribute, value);
+  }
+
+  element.dispatchEvent(
+    new CustomEvent(eventName, {
+      detail,
+      bubbles: true,
+    }),
+  );
+
+  element.dispatchEvent(
+    new CustomEvent('czap:uniform-update', {
+      detail,
+      bubbles: true,
+    }),
+  );
+}

package/src/runtime/globals.ts

@@ -0,0 +1,57 @@
+/**
+ * Safe read/write helpers for named `window` globals used as runtime
+ * handshake points between inline detect scripts and the hydrated
+ * runtime (e.g. `__CZAP_DETECT__`, `__CZAP_SLOTS__`). Works on both
+ * client and server entry paths -- returns `undefined` under SSR.
+ *
+ * @module
+ */
+
+declare global {
+  interface Window {
+    [key: string]: unknown;
+  }
+}
+
+function runtimeWindow(): Window | null {
+  return typeof window === 'undefined' ? null : window;
+}
+
+/**
+ * Read a named `window` global, narrowed through `guard`. Returns
+ * `undefined` under SSR or when the guard rejects the runtime value.
+ */
+export function readRuntimeGlobal<T>(name: string, guard: (v: unknown) => v is T): T | undefined {
+  const win = runtimeWindow();
+  if (!win) return undefined;
+  const raw: unknown = win[name];
+  return guard(raw) ? raw : undefined;
+}
+
+/**
+ * Write a named `window` global as a non-enumerable property.
+ *
+ * `options.writable` defaults to `false` so the value is lock-down by default.
+ * `options.configurable` defaults to `true` so HMR and bootstrap re-runs can
+ * replace the global; security-critical globals (e.g. `__CZAP_RUNTIME_POLICY__`)
+ * should pass `configurable: false` to prevent post-install redefinition by
+ * any later script on the page.
+ */
+export function writeRuntimeGlobal<T>(
+  name: string,
+  value: T,
+  options?: { readonly writable?: boolean; readonly configurable?: boolean },
+): T {
+  const win = runtimeWindow();
+  if (!win) {
+    return value;
+  }
+
+  Object.defineProperty(win, name, {
+    value,
+    configurable: options?.configurable ?? true,
+    enumerable: false,
+    writable: options?.writable ?? false,
+  });
+  return value;
+}