@czap/edge 0.1.0

package/src/host-adapter.ts

@@ -0,0 +1,217 @@
+/**
+ * EdgeHostAdapter -- canonical host-facing edge resolution path.
+ *
+ * Resolves client hints, tiering, optional theme compilation, and optional
+ * boundary compilation cache lookups in a single host-level operation.
+ *
+ * @module
+ */
+
+import type { ContentAddress } from '@czap/core';
+import type { ExtendedDeviceCapabilities } from '@czap/detect';
+import { ClientHints } from './client-hints.js';
+import type { ClientHintsHeaders } from './client-hints.js';
+import { EdgeTier } from './edge-tier.js';
+import type { EdgeTierResult } from './edge-tier.js';
+import { createBoundaryCache } from './kv-cache.js';
+import type { CompiledOutputs, KVNamespace } from './kv-cache.js';
+import { compileTheme } from './theme-compiler.js';
+import type { ThemeCompileConfig, ThemeCompileResult } from './theme-compiler.js';
+
+/**
+ * Detected device context available to host callbacks before compile.
+ *
+ * Pairs the parsed {@link ExtendedDeviceCapabilities} with the resolved
+ * {@link EdgeTierResult} so a host can derive a theme config or compile
+ * decision without re-parsing headers.
+ */
+export interface EdgeHostContext {
+  /** Capabilities parsed from Client Hints. */
+  readonly capabilities: ExtendedDeviceCapabilities;
+  /** Derived tier triple (cap, motion, design). */
+  readonly tier: EdgeTierResult;
+}
+
+/**
+ * Compile-time context passed to {@link EdgeHostCacheConfig.compile}.
+ *
+ * Extends {@link EdgeHostContext} with the already-resolved theme result
+ * (if any) so host compile callbacks can inject theme tokens into the
+ * compiled per-state outputs without recomputation.
+ */
+export interface EdgeHostCompileContext extends EdgeHostContext {
+  /** Pre-compiled theme output, if the adapter resolved one for this request. */
+  readonly theme?: ThemeCompileResult;
+}
+
+/**
+ * Cache configuration for the edge host adapter.
+ *
+ * When set, per-boundary compiled outputs are memoized in the supplied KV
+ * namespace keyed by `(boundaryId, tier)`. `compile` is the user-provided
+ * function that produces the outputs on a cache miss; its result is
+ * written back to KV with the configured `ttl`.
+ */
+export interface EdgeHostCacheConfig {
+  /** KV namespace backing the boundary cache. */
+  readonly kv: KVNamespace;
+  /** Content address of the boundary being compiled. */
+  readonly boundaryId: ContentAddress;
+  /** Compile function invoked on cache miss. */
+  readonly compile: (context: EdgeHostCompileContext) => Promise<CompiledOutputs> | CompiledOutputs;
+  /** Cache entry TTL in seconds. */
+  readonly ttl?: number;
+  /** Optional KV key prefix. */
+  readonly prefix?: string;
+}
+
+/**
+ * Configuration for {@link createEdgeHostAdapter}.
+ *
+ * `theme` may be a static {@link ThemeCompileConfig}, a per-request
+ * resolver function, or absent. `cache` enables a KV-backed boundary
+ * compile cache keyed by content address + tier.
+ */
+export interface EdgeHostAdapterConfig {
+  /** Static theme config, or a resolver invoked with each request's context. */
+  readonly theme?: ThemeCompileConfig | ((context: EdgeHostContext) => ThemeCompileConfig | null | undefined);
+  /** KV-backed boundary output cache; omit to disable caching. */
+  readonly cache?: EdgeHostCacheConfig;
+}
+
+/** Cache lookup outcome reported in {@link EdgeHostResolution}. */
+export type EdgeHostCacheStatus = 'disabled' | 'hit' | 'miss';
+
+/**
+ * Full per-request resolution output from {@link EdgeHostAdapter.resolve}.
+ *
+ * Carries the device context, optional theme and compiled outputs, the
+ * `data-czap-*` attribute string for the root HTML element, and the
+ * `Accept-CH`/`Critical-CH` headers the response should send back.
+ */
+export interface EdgeHostResolution extends EdgeHostContext {
+  /** Compiled theme result, if a theme config was resolved for this request. */
+  readonly theme?: ThemeCompileResult;
+  /** Compiled per-state outputs for the configured boundary, if caching is enabled. */
+  readonly compiledOutputs?: CompiledOutputs;
+  /** `data-czap-cap`/`data-czap-motion`/`data-czap-design` string for `<html>`. */
+  readonly htmlAttributes: string;
+  /** Response headers to send back so the browser will supply hints next time. */
+  readonly responseHeaders: {
+    /** `Accept-CH` header value. */
+    readonly acceptCH: string;
+    /** `Critical-CH` header value. */
+    readonly criticalCH: string;
+  };
+  /** Whether the boundary outputs came from cache, were computed and stored, or caching is off. */
+  readonly cacheStatus: EdgeHostCacheStatus;
+}
+
+/**
+ * Opaque host-facing adapter returned by {@link createEdgeHostAdapter}.
+ *
+ * Call `resolve(headers)` per request; the adapter drives tier detection,
+ * theme compilation, and boundary caching in a single pass.
+ */
+export interface EdgeHostAdapter {
+  /** Resolve a request's device context, theme, and compiled outputs. */
+  resolve(headers: Headers | ClientHintsHeaders): Promise<EdgeHostResolution>;
+}
+
+function resolveThemeConfig(
+  theme: EdgeHostAdapterConfig['theme'],
+  context: EdgeHostContext,
+): ThemeCompileConfig | null | undefined {
+  if (typeof theme === 'function') {
+    return theme(context);
+  }
+  return theme;
+}
+
+/**
+ * Create an {@link EdgeHostAdapter} with optional theme and boundary cache.
+ *
+ * The returned adapter is designed to be instantiated once per worker and
+ * reused across requests; it caches a compiled static theme eagerly and
+ * only invokes the compile callback on cache miss when caching is enabled.
+ */
+export function createEdgeHostAdapter(config: EdgeHostAdapterConfig = {}): EdgeHostAdapter {
+  let boundaryCache: ReturnType<typeof createBoundaryCache> | null = null;
+  if (config.cache) {
+    boundaryCache = createBoundaryCache(config.cache.kv, {
+      ttl: config.cache.ttl,
+      prefix: config.cache.prefix,
+    });
+  }
+  const staticThemeConfig = typeof config.theme === 'function' ? undefined : config.theme;
+  let compiledStaticTheme: ThemeCompileResult | undefined;
+  if (staticThemeConfig) {
+    compiledStaticTheme = compileTheme(staticThemeConfig);
+  }
+  const responseHeaders = {
+    acceptCH: ClientHints.acceptCHHeader(),
+    criticalCH: ClientHints.criticalCHHeader(),
+  } as const;
+
+  return {
+    async resolve(headers: Headers | ClientHintsHeaders): Promise<EdgeHostResolution> {
+      const capabilities = ClientHints.parseClientHints(headers);
+      const tier = EdgeTier.detectTier(headers);
+      const context: EdgeHostContext = { capabilities, tier };
+      const themeConfig = compiledStaticTheme ? undefined : resolveThemeConfig(config.theme, context);
+      let theme = compiledStaticTheme;
+      if (!theme && themeConfig) {
+        theme = compileTheme(themeConfig);
+      }
+
+      let compiledOutputs: CompiledOutputs | undefined;
+      let cacheStatus: EdgeHostCacheStatus = boundaryCache ? 'miss' : 'disabled';
+
+      if (boundaryCache && config.cache) {
+        const cached = await boundaryCache.getCompiledOutputs(config.cache.boundaryId, tier);
+        if (cached) {
+          compiledOutputs = cached;
+          cacheStatus = 'hit';
+        } else {
+          compiledOutputs = await config.cache.compile({ capabilities, tier, theme });
+          await boundaryCache.putCompiledOutputs(config.cache.boundaryId, tier, compiledOutputs);
+        }
+      }
+
+      return {
+        capabilities,
+        tier,
+        theme,
+        compiledOutputs,
+        htmlAttributes: EdgeTier.tierDataAttributes(tier),
+        responseHeaders,
+        cacheStatus,
+      };
+    },
+  };
+}
+
+/**
+ * Edge host adapter namespace.
+ *
+ * `EdgeHostAdapter.create(config)` builds a reusable adapter that resolves
+ * Client Hints, tiers, theme compilation, and KV-backed boundary caching
+ * in a single per-request pass.
+ */
+export const EdgeHostAdapter = {
+  /** Alias for {@link createEdgeHostAdapter}. */
+  create: createEdgeHostAdapter,
+} as const;
+
+export declare namespace EdgeHostAdapter {
+  /** Alias for {@link EdgeHostAdapterConfig}. */
+  export type Config = EdgeHostAdapterConfig;
+  /** Alias for {@link EdgeHostResolution}. */
+  export type Resolution = EdgeHostResolution;
+  /** Alias for {@link EdgeHostCacheStatus}. */
+  export type CacheStatus = EdgeHostCacheStatus;
+  /** Alias for {@link EdgeHostContext}. */
+  export type Context = EdgeHostContext;
+  /** Alias for {@link EdgeHostCompileContext}. */
+  export type CompileContext = EdgeHostCompileContext;
+}

package/src/index.ts

@@ -0,0 +1,33 @@
+/**
+ * `@czap/edge` — **LiteShip** edge-station: server-side tier detection,
+ * content-addressed boundary cache, and theme **casting** for first paint.
+ *
+ * Parses HTTP Client Hints headers into device capabilities, maps them
+ * to the same tier lattice used on the client, and provides helpers for
+ * HTML injection, KV-backed boundary caching, and per-tenant theme
+ * compilation.
+ *
+ * @module
+ */
+
+export { ClientHints } from './client-hints.js';
+export type { ClientHintsHeaders } from './client-hints.js';
+
+export { EdgeTier } from './edge-tier.js';
+export type { EdgeTierResult } from './edge-tier.js';
+
+export { createBoundaryCache, KVCache } from './kv-cache.js';
+export type { KVNamespace, BoundaryCache, CompiledOutputs } from './kv-cache.js';
+
+export { compileTheme } from './theme-compiler.js';
+export type { ThemeCompileConfig, ThemeCompileResult } from './theme-compiler.js';
+
+export { createEdgeHostAdapter, EdgeHostAdapter } from './host-adapter.js';
+export type {
+  EdgeHostAdapterConfig,
+  EdgeHostResolution,
+  EdgeHostCacheConfig,
+  EdgeHostCacheStatus,
+  EdgeHostContext,
+  EdgeHostCompileContext,
+} from './host-adapter.js';

package/src/kv-cache.ts

@@ -0,0 +1,189 @@
+/**
+ * Content-addressed boundary precomputation cache with a generic KV
+ * interface -- not coupled to any specific KV provider (Cloudflare,
+ * Deno KV, Vercel KV, etc.).
+ *
+ * Cache keys encode the boundary content address and the two-axis tier
+ * result so each tier combination gets its own cached compilation output.
+ *
+ * @module
+ */
+
+import { Diagnostics, type ContentAddress } from '@czap/core';
+import type { EdgeTierResult } from './edge-tier.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Minimal KV namespace interface -- compatible with Cloudflare Workers KV,
+ * Deno KV, or any adapter that implements get/put with string values.
+ */
+export interface KVNamespace {
+  get(key: string): Promise<string | null>;
+  put(key: string, value: string, options?: { expirationTtl?: number }): Promise<void>;
+}
+
+/**
+ * Precompiled CSS outputs for a single boundary at a given tier.
+ */
+export interface CompiledOutputs {
+  readonly css: string;
+  readonly propertyRegistrations: string;
+  readonly containerQueries: string;
+}
+
+/**
+ * Content-addressed cache for boundary compilation results keyed by
+ * tier combination.
+ */
+export interface BoundaryCache {
+  getCompiledOutputs(boundaryId: ContentAddress, tierResult: EdgeTierResult): Promise<CompiledOutputs | null>;
+
+  putCompiledOutputs(boundaryId: ContentAddress, tierResult: EdgeTierResult, outputs: CompiledOutputs): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+interface CacheOptions {
+  readonly ttl?: number;
+  readonly prefix?: string;
+}
+
+function buildCacheKey(prefix: string, boundaryId: ContentAddress, tierResult: EdgeTierResult): string {
+  return `${prefix}:boundary:${boundaryId}:${tierResult.motionTier}:${tierResult.designTier}`;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a {@link BoundaryCache} backed by the provided KV namespace.
+ *
+ * Cache keys encode the boundary content address and the two-axis tier
+ * result so each tier combination gets its own cached compilation output.
+ *
+ * @example
+ * ```ts
+ * import { KVCache } from '@czap/edge';
+ * import { ContentAddress } from '@czap/core';
+ *
+ * const kv = { get: async (k: string) => null, put: async (k: string, v: string) => {} };
+ * const cache = KVCache.createBoundaryCache(kv, { ttl: 3600, prefix: 'myapp' });
+ *
+ * const boundaryId = ContentAddress('fnv1a:abcd1234');
+ * const tierResult = {
+ *   capLevel: 'reactive',
+ *   motionTier: 'transitions',
+ *   designTier: 'standard',
+ * } as const;
+ *
+ * // Store compiled outputs
+ * await cache.putCompiledOutputs(boundaryId, tierResult, {
+ *   css: '...',
+ *   propertyRegistrations: '...',
+ *   containerQueries: '...',
+ * });
+ *
+ * // Retrieve cached outputs
+ * const cached = await cache.getCompiledOutputs(boundaryId, tierResult);
+ * ```
+ *
+ * @param kv      - A generic KV namespace implementing get/put
+ * @param options - Optional TTL (seconds) and key prefix configuration
+ * @returns A {@link BoundaryCache} instance
+ */
+export function createBoundaryCache(kv: KVNamespace, options?: CacheOptions): BoundaryCache {
+  const prefix = options?.prefix ?? 'czap';
+  const ttl = options?.ttl;
+
+  return {
+    async getCompiledOutputs(boundaryId: ContentAddress, tierResult: EdgeTierResult): Promise<CompiledOutputs | null> {
+      const key = buildCacheKey(prefix, boundaryId, tierResult);
+      const raw = await kv.get(key);
+      if (raw === null) return null;
+
+      let parsed: unknown;
+      let invalidJson = false;
+      try {
+        parsed = JSON.parse(raw);
+      } catch (error) {
+        if (error instanceof SyntaxError) {
+          invalidJson = true;
+          Diagnostics.warnOnce({
+            source: 'czap/edge.kv-cache',
+            code: 'invalid-cache-entry',
+            message: `Boundary cache entry "${key}" could not be parsed and will be treated as a cache miss.`,
+            cause: error,
+          });
+        } else {
+          throw error;
+        }
+      }
+
+      if (invalidJson) {
+        return null;
+      }
+
+      if (
+        typeof parsed === 'object' &&
+        parsed !== null &&
+        'css' in parsed &&
+        'propertyRegistrations' in parsed &&
+        'containerQueries' in parsed
+      ) {
+        return {
+          css: String(parsed.css),
+          propertyRegistrations: String(parsed.propertyRegistrations),
+          containerQueries: String(parsed.containerQueries),
+        };
+      }
+
+      return null;
+    },
+
+    async putCompiledOutputs(
+      boundaryId: ContentAddress,
+      tierResult: EdgeTierResult,
+      outputs: CompiledOutputs,
+    ): Promise<void> {
+      const key = buildCacheKey(prefix, boundaryId, tierResult);
+      const value = JSON.stringify({
+        css: outputs.css,
+        propertyRegistrations: outputs.propertyRegistrations,
+        containerQueries: outputs.containerQueries,
+      });
+
+      await kv.put(key, value, ttl !== undefined ? { expirationTtl: ttl } : undefined);
+    },
+  };
+}
+
+/**
+ * KV cache namespace.
+ *
+ * Provides a content-addressed boundary precomputation cache backed by a
+ * generic KV interface (compatible with Cloudflare Workers KV, Deno KV,
+ * Vercel KV, etc.). Cache keys encode the boundary content address and
+ * the two-axis tier result (motion + design) so each tier combination
+ * gets its own cached CSS compilation output.
+ *
+ * @example
+ * ```ts
+ * import { KVCache } from '@czap/edge';
+ *
+ * const kv = { get: async (k: string) => null, put: async (k: string, v: string) => {} };
+ * const cache = KVCache.createBoundaryCache(kv, { ttl: 3600 });
+ * const outputs = await cache.getCompiledOutputs(boundaryId, tierResult);
+ * if (!outputs) {
+ *   await cache.putCompiledOutputs(boundaryId, tierResult, compiled);
+ * }
+ * ```
+ */
+export const KVCache = {
+  createBoundaryCache,
+} as const;

package/src/theme-compiler.ts

@@ -0,0 +1,151 @@
+/**
+ * Per-tenant theme compilation at the edge.
+ *
+ * Takes a flat map of design token definitions and produces CSS custom
+ * property declarations suitable for injection into the `<html>` element
+ * or a `<style>` block.
+ *
+ * This is a pure function with no side effects -- safe for edge runtime use.
+ *
+ * @module
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Input to {@link compileTheme}.
+ *
+ * Tokens are flat key/value pairs — nested paths like `color.primary` are
+ * sanitized into CSS-safe custom property names. Numeric values are emitted
+ * bare so consumers can apply their own units downstream.
+ */
+export interface ThemeCompileConfig {
+  /** Flat map of token name to value (string or numeric). */
+  readonly tokens: Readonly<Record<string, string | number>>;
+  /** CSS custom property prefix. Defaults to `'czap'`. */
+  readonly prefix?: string;
+}
+
+/**
+ * Output of {@link compileTheme}.
+ *
+ * Provides three views of the same declarations: structured, a full CSS
+ * rule, and an inline-style string — so hosts can pick whichever
+ * serialization best fits their HTML injection strategy.
+ */
+export interface ThemeCompileResult {
+  /** Structured declarations suitable for serializer-specific output. */
+  readonly declarations: readonly ThemeDeclaration[];
+  /** Full CSS rule with custom property declarations inside `:root {}`. */
+  readonly css: string;
+  /** Inline style string for `<html style="...">` injection. */
+  readonly inlineStyle: string;
+}
+
+/** A single compiled CSS custom property declaration. */
+export interface ThemeDeclaration {
+  /** Full CSS custom property name including the `--prefix-` prefix. */
+  readonly property: string;
+  /** Formatted value (numbers stringified bare, strings validated). */
+  readonly value: string;
+}
+
+const SAFE_PREFIX_PATTERN = /^[a-z0-9-]+$/;
+const UNSAFE_CSS_VALUE_PATTERN = /[;{}<>]/;
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert a token name to a valid CSS custom property name.
+ * Replaces dots and spaces with hyphens, lowercases, strips invalid chars.
+ */
+function tokenToProperty(prefix: string, name: string): string {
+  const sanitised = name
+    .toLowerCase()
+    .replace(/[.\s]+/g, '-')
+    .replace(/[^a-z0-9-_]/g, '');
+  return `--${prefix}-${sanitised}`;
+}
+
+function normalizePrefix(prefix: string): string {
+  const normalized = prefix.toLowerCase();
+  if (!SAFE_PREFIX_PATTERN.test(normalized)) {
+    throw new Error(
+      `Invalid theme prefix "${prefix}". Prefixes must contain only lowercase letters, digits, and hyphens.`,
+    );
+  }
+
+  return normalized;
+}
+
+/**
+ * Format a token value for CSS output.
+ * Numbers are emitted bare (no unit) so consumers can apply their own units.
+ */
+function formatValue(value: string | number): string {
+  const formatted = typeof value === 'number' ? String(value) : value;
+  if (UNSAFE_CSS_VALUE_PATTERN.test(formatted)) {
+    throw new Error(`Unsafe theme token value "${formatted}" cannot be serialized into CSS safely.`);
+  }
+
+  return formatted;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Compile a set of design tokens into CSS custom property declarations.
+ *
+ * @param config - Token definitions and optional prefix.
+ * @returns CSS string and inline style string.
+ *
+ * @example
+ * ```ts
+ * const result = compileTheme({
+ *   tokens: { 'color.primary': '#3b82f6', 'spacing.base': 16 },
+ *   prefix: 'czap',
+ * });
+ * // result.css =>
+ * //   :root {
+ * //     --czap-color-primary: #3b82f6;
+ * //     --czap-spacing-base: 16;
+ * //   }
+ * // result.inlineStyle =>
+ * //   --czap-color-primary:#3b82f6;--czap-spacing-base:16
+ * ```
+ */
+export function compileTheme(config: ThemeCompileConfig): ThemeCompileResult {
+  const prefix = normalizePrefix(config.prefix ?? 'czap');
+  const entries = Object.entries(config.tokens);
+
+  if (entries.length === 0) {
+    return { declarations: [], css: ':root {}', inlineStyle: '' };
+  }
+
+  const declarations: ThemeDeclaration[] = [];
+  const cssDeclarations: string[] = [];
+  const inlineParts: string[] = [];
+
+  for (const [name, value] of entries) {
+    const prop = tokenToProperty(prefix, name);
+    const formatted = formatValue(value);
+    declarations.push({ property: prop, value: formatted });
+    cssDeclarations.push(`  ${prop}: ${formatted};`);
+    inlineParts.push(`${prop}:${formatted}`);
+  }
+
+  const css = `:root {\n${cssDeclarations.join('\n')}\n}`;
+  const inlineStyle = inlineParts.join(';');
+
+  return {
+    declarations: Object.freeze(declarations),
+    css,
+    inlineStyle,
+  };
+}