npm - @czap/edge - Versions diffs - 0.1.0 - Mend

@czap/edge 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (33) hide show

package/LICENSE +21 -0
package/README.md +19 -0
package/dist/client-hints.d.ts +145 -0
package/dist/client-hints.d.ts.map +1 -0
package/dist/client-hints.js +268 -0
package/dist/client-hints.js.map +1 -0
package/dist/edge-tier.d.ts +67 -0
package/dist/edge-tier.d.ts.map +1 -0
package/dist/edge-tier.js +60 -0
package/dist/edge-tier.js.map +1 -0
package/dist/host-adapter.d.ts +139 -0
package/dist/host-adapter.d.ts.map +1 -0
package/dist/host-adapter.js +89 -0
package/dist/host-adapter.js.map +1 -0
package/dist/index.d.ts +22 -0
package/dist/index.d.ts.map +1 -0
package/dist/index.js +17 -0
package/dist/index.js.map +1 -0
package/dist/kv-cache.d.ts +105 -0
package/dist/kv-cache.d.ts.map +1 -0
package/dist/kv-cache.js +133 -0
package/dist/kv-cache.js.map +1 -0
package/dist/theme-compiler.d.ts +69 -0
package/dist/theme-compiler.d.ts.map +1 -0
package/dist/theme-compiler.js +94 -0
package/dist/theme-compiler.js.map +1 -0
package/package.json +55 -0
package/src/client-hints.ts +338 -0
package/src/edge-tier.ts +93 -0
package/src/host-adapter.ts +217 -0
package/src/index.ts +33 -0
package/src/kv-cache.ts +189 -0
package/src/theme-compiler.ts +151 -0

package/dist/host-adapter.d.ts ADDED Viewed

@@ -0,0 +1,139 @@
+/**
+ * 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 type { ClientHintsHeaders } from './client-hints.js';
+import type { EdgeTierResult } from './edge-tier.js';
+import type { CompiledOutputs, KVNamespace } from './kv-cache.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>;
+}
+/**
+ * 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 declare function createEdgeHostAdapter(config?: EdgeHostAdapterConfig): EdgeHostAdapter;
+/**
+ * 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 declare const EdgeHostAdapter: {
+    /** Alias for {@link createEdgeHostAdapter}. */
+    readonly create: typeof createEdgeHostAdapter;
+};
+export declare namespace EdgeHostAdapter {
+    /** Alias for {@link EdgeHostAdapterConfig}. */
+    type Config = EdgeHostAdapterConfig;
+    /** Alias for {@link EdgeHostResolution}. */
+    type Resolution = EdgeHostResolution;
+    /** Alias for {@link EdgeHostCacheStatus}. */
+    type CacheStatus = EdgeHostCacheStatus;
+    /** Alias for {@link EdgeHostContext}. */
+    type Context = EdgeHostContext;
+    /** Alias for {@link EdgeHostCompileContext}. */
+    type CompileContext = EdgeHostCompileContext;
+}
+//# sourceMappingURL=host-adapter.d.ts.map

package/dist/host-adapter.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"host-adapter.d.ts","sourceRoot":"","sources":["../src/host-adapter.ts"],"names":[],"mappings":"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"}

package/dist/host-adapter.js ADDED Viewed

@@ -0,0 +1,89 @@
+/**
+ * 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 { ClientHints } from './client-hints.js';
+import { EdgeTier } from './edge-tier.js';
+import { createBoundaryCache } from './kv-cache.js';
+import { compileTheme } from './theme-compiler.js';
+function resolveThemeConfig(theme, context) {
+    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 = {}) {
+    let boundaryCache = 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;
+    if (staticThemeConfig) {
+        compiledStaticTheme = compileTheme(staticThemeConfig);
+    }
+    const responseHeaders = {
+        acceptCH: ClientHints.acceptCHHeader(),
+        criticalCH: ClientHints.criticalCHHeader(),
+    };
+    return {
+        async resolve(headers) {
+            const capabilities = ClientHints.parseClientHints(headers);
+            const tier = EdgeTier.detectTier(headers);
+            const context = { capabilities, tier };
+            const themeConfig = compiledStaticTheme ? undefined : resolveThemeConfig(config.theme, context);
+            let theme = compiledStaticTheme;
+            if (!theme && themeConfig) {
+                theme = compileTheme(themeConfig);
+            }
+            let compiledOutputs;
+            let cacheStatus = 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,
+};
+//# sourceMappingURL=host-adapter.js.map

package/dist/host-adapter.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"host-adapter.js","sourceRoot":"","sources":["../src/host-adapter.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts ADDED Viewed

@@ -0,0 +1,22 @@
+/**
+ * `@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';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAE5D,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,YAAY,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD,OAAO,EAAE,mBAAmB,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7D,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEjF,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,YAAY,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAElF,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAC3E,YAAY,EACV,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACnB,mBAAmB,EACnB,eAAe,EACf,sBAAsB,GACvB,MAAM,mBAAmB,CAAC"}

package/dist/index.js ADDED Viewed

@@ -0,0 +1,17 @@
+/**
+ * `@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 { EdgeTier } from './edge-tier.js';
+export { createBoundaryCache, KVCache } from './kv-cache.js';
+export { compileTheme } from './theme-compiler.js';
+export { createEdgeHostAdapter, EdgeHostAdapter } from './host-adapter.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map ADDED Viewed

	@@ -0,0 +1 @@
1	+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAG1C,OAAO,EAAE,mBAAmB,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAG7D,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGnD,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/kv-cache.d.ts ADDED Viewed

@@ -0,0 +1,105 @@
+/**
+ * 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 { type ContentAddress } from '@czap/core';
+import type { EdgeTierResult } from './edge-tier.js';
+/**
+ * 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>;
+}
+interface CacheOptions {
+    readonly ttl?: number;
+    readonly prefix?: string;
+}
+/**
+ * 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 declare function createBoundaryCache(kv: KVNamespace, options?: CacheOptions): BoundaryCache;
+/**
+ * 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 declare const KVCache: {
+    readonly createBoundaryCache: typeof createBoundaryCache;
+};
+export {};
+//# sourceMappingURL=kv-cache.d.ts.map

package/dist/kv-cache.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"kv-cache.d.ts","sourceRoot":"","sources":["../src/kv-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAe,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAMrD;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACzC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtF;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,kBAAkB,CAAC,UAAU,EAAE,cAAc,EAAE,UAAU,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAC;IAE5G,kBAAkB,CAAC,UAAU,EAAE,cAAc,EAAE,UAAU,EAAE,cAAc,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrH;AAMD,UAAU,YAAY;IACpB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAUD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,aAAa,CAgE1F;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,OAAO;;CAEV,CAAC"}

package/dist/kv-cache.js ADDED Viewed

@@ -0,0 +1,133 @@
+/**
+ * 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 } from '@czap/core';
+function buildCacheKey(prefix, boundaryId, tierResult) {
+    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, options) {
+    const prefix = options?.prefix ?? 'czap';
+    const ttl = options?.ttl;
+    return {
+        async getCompiledOutputs(boundaryId, tierResult) {
+            const key = buildCacheKey(prefix, boundaryId, tierResult);
+            const raw = await kv.get(key);
+            if (raw === null)
+                return null;
+            let parsed;
+            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, tierResult, outputs) {
+            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,
+};
+//# sourceMappingURL=kv-cache.js.map

package/dist/kv-cache.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"kv-cache.js","sourceRoot":"","sources":["../src/kv-cache.ts"],"names":[],"mappings":"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"}

package/dist/theme-compiler.d.ts ADDED Viewed

@@ -0,0 +1,69 @@
+/**
+ * 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
+ */
+/**
+ * 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;
+}
+/**
+ * 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 declare function compileTheme(config: ThemeCompileConfig): ThemeCompileResult;
+//# sourceMappingURL=theme-compiler.d.ts.map

package/dist/theme-compiler.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"theme-compiler.d.ts","sourceRoot":"","sources":["../src/theme-compiler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,2DAA2D;IAC3D,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC;IAC3D,wDAAwD;IACxD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,uEAAuE;IACvE,QAAQ,CAAC,YAAY,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACnD,yEAAyE;IACzE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,8DAA8D;IAC9D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,yDAAyD;AACzD,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,qEAAqE;IACrE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAiDD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,kBAAkB,GAAG,kBAAkB,CA4B3E"}