@czap/edge 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Eassa Ayoub <eassa@heyoub.dev>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,19 @@
+# @czap/edge
+
+CDN-edge: Client Hints, tier detection, KV boundary cache, theme compilation.
+
+## Docs
+
+- [Naming & vocabulary](../../docs/GLOSSARY.md) — LiteShip, CZAP, `@czap/*`
+
+- [API reference](https://github.com/heyoub/LiteShip/tree/main/docs/api/edge/) — generated from source TSDoc
+- [Architecture index](https://github.com/heyoub/LiteShip/blob/main/docs/ARCHITECTURE.md)
+- [ADRs](https://github.com/heyoub/LiteShip/tree/main/docs/adr/)
+
+## Install
+
+```bash
+pnpm add @czap/edge
+```
+
+## Part of [LiteShip](https://github.com/heyoub/LiteShip#readme)

package/dist/client-hints.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Client Hints header parsing for edge-side device capability detection.
+ *
+ * Converts HTTP Client Hints headers into the same `ExtendedDeviceCapabilities`
+ * structure that `@czap/detect` uses, enabling reuse of the pure tier mapping
+ * functions at the edge without browser APIs.
+ *
+ * @module
+ */
+import type { ExtendedDeviceCapabilities } from '@czap/detect';
+/**
+ * Plain-object header bag accepted by {@link ClientHints.parseClientHints}.
+ *
+ * All names are lowercased because Client Hints headers are always lowercase
+ * in spec. Values that are missing simply fall back to conservative
+ * defaults during parsing.
+ */
+export interface ClientHintsHeaders {
+    /** `Sec-CH-UA-Platform` (e.g. `"macOS"`, `"Windows"`). */
+    readonly 'sec-ch-ua-platform'?: string;
+    /** `Sec-CH-Device-Memory` in GiB (one of the standard buckets). */
+    readonly 'sec-ch-device-memory'?: string;
+    /** `Sec-CH-DPR` — devicePixelRatio as a decimal string. */
+    readonly 'sec-ch-dpr'?: string;
+    /** `Sec-CH-Viewport-Width` in CSS pixels. */
+    readonly 'sec-ch-viewport-width'?: string;
+    /** `Sec-CH-Viewport-Height` in CSS pixels. */
+    readonly 'sec-ch-viewport-height'?: string;
+    /** `Sec-CH-Prefers-Reduced-Motion` (`reduce` / `no-preference`). */
+    readonly 'sec-ch-prefers-reduced-motion'?: string;
+    /** `Sec-CH-Prefers-Color-Scheme` (`light` / `dark`). */
+    readonly 'sec-ch-prefers-color-scheme'?: string;
+    /** `Sec-CH-UA-Mobile` as a structured boolean (`?1` / `?0`). */
+    readonly 'sec-ch-ua-mobile'?: string;
+    /** `Sec-CH-UA` — full user-agent brand list. */
+    readonly 'sec-ch-ua'?: string;
+    /** `Save-Data` (`on`). */
+    readonly 'save-data'?: string;
+    /** `Downlink` estimate in Mb/s. */
+    readonly downlink?: string;
+    /** `ECT` effective connection type. */
+    readonly ect?: string;
+    /** `RTT` round-trip-time estimate in ms. */
+    readonly rtt?: string;
+    /** `User-Agent` fallback for GPU-tier heuristics. */
+    readonly 'user-agent'?: string;
+}
+/**
+ * Parse Client Hints headers into an {@link ExtendedDeviceCapabilities} structure.
+ *
+ * For properties that cannot be determined from headers (GPU tier, WebGPU
+ * support, CPU cores), conservative defaults are used.
+ *
+ * @example
+ * ```ts
+ * import { ClientHints } from '@czap/edge';
+ *
+ * const caps = ClientHints.parseClientHints({
+ *   'sec-ch-device-memory': '8',
+ *   'sec-ch-dpr': '2',
+ *   'sec-ch-viewport-width': '1440',
+ *   'sec-ch-prefers-color-scheme': 'dark',
+ *   'sec-ch-ua-mobile': '?0',
+ * });
+ * console.log(caps.memory);             // 8
+ * console.log(caps.devicePixelRatio);    // 2
+ * console.log(caps.prefersColorScheme);  // 'dark'
+ * ```
+ *
+ * @param headers - Client Hints headers (plain object or Web API Headers)
+ * @returns An {@link ExtendedDeviceCapabilities} structure
+ */
+declare function parseClientHints(headers: ClientHintsHeaders | Headers): ExtendedDeviceCapabilities;
+/**
+ * Generate the `Accept-CH` header value for requesting all useful Client Hints
+ * on subsequent requests.
+ *
+ * @example
+ * ```ts
+ * import { ClientHints } from '@czap/edge';
+ *
+ * const response = new Response('OK', {
+ *   headers: { 'Accept-CH': ClientHints.acceptCHHeader() },
+ * });
+ * ```
+ *
+ * @returns A comma-separated list of Client Hint header names
+ */
+declare function acceptCHHeader(): string;
+/**
+ * Generate the `Critical-CH` header value for hints needed on the very first
+ * request (triggers a browser retry if missing).
+ *
+ * @example
+ * ```ts
+ * import { ClientHints } from '@czap/edge';
+ *
+ * const response = new Response('OK', {
+ *   headers: {
+ *     'Accept-CH': ClientHints.acceptCHHeader(),
+ *     'Critical-CH': ClientHints.criticalCHHeader(),
+ *   },
+ * });
+ * ```
+ *
+ * @returns A comma-separated list of critical Client Hint header names
+ */
+declare function criticalCHHeader(): string;
+/**
+ * Client Hints namespace.
+ *
+ * Parses HTTP Client Hints headers into the same
+ * {@link ExtendedDeviceCapabilities} structure used by `@czap/detect`,
+ * enabling server-side / edge-side tier mapping without browser APIs.
+ * Also generates the `Accept-CH` and `Critical-CH` response headers needed
+ * to request hints from the browser.
+ *
+ * @example
+ * ```ts
+ * import { ClientHints } from '@czap/edge';
+ *
+ * // In an edge handler:
+ * const caps = ClientHints.parseClientHints(request.headers);
+ * const response = new Response(body, {
+ *   headers: {
+ *     'Accept-CH': ClientHints.acceptCHHeader(),
+ *     'Critical-CH': ClientHints.criticalCHHeader(),
+ *   },
+ * });
+ * ```
+ */
+export declare const ClientHints: {
+    /** Parse Client Hints headers into {@link ExtendedDeviceCapabilities}. */
+    readonly parseClientHints: typeof parseClientHints;
+    /** Produce the `Accept-CH` response header value listing all useful hints. */
+    readonly acceptCHHeader: typeof acceptCHHeader;
+    /** Produce the `Critical-CH` response header value listing boot-required hints. */
+    readonly criticalCHHeader: typeof criticalCHHeader;
+};
+export declare namespace ClientHints {
+    /** Alias for {@link ClientHintsHeaders} — plain-object header bag shape. */
+    type Headers = ClientHintsHeaders;
+}
+export {};
+//# sourceMappingURL=client-hints.d.ts.map

package/dist/client-hints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-hints.d.ts","sourceRoot":"","sources":["../src/client-hints.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,0BAA0B,EAAW,MAAM,cAAc,CAAC;AAMxE;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,0DAA0D;IAC1D,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IACvC,mEAAmE;IACnE,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IACzC,2DAA2D;IAC3D,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,6CAA6C;IAC7C,QAAQ,CAAC,uBAAuB,CAAC,EAAE,MAAM,CAAC;IAC1C,8CAA8C;IAC9C,QAAQ,CAAC,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAC3C,oEAAoE;IACpE,QAAQ,CAAC,+BAA+B,CAAC,EAAE,MAAM,CAAC;IAClD,wDAAwD;IACxD,QAAQ,CAAC,6BAA6B,CAAC,EAAE,MAAM,CAAC;IAChD,gEAAgE;IAChE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,gDAAgD;IAChD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,0BAA0B;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,mCAAmC;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,uCAAuC;IACvC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,4CAA4C;IAC5C,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAmHD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,iBAAS,gBAAgB,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,GAAG,0BAA0B,CA+D3F;AAED;;;;;;;;;;;;;;GAcG;AACH,iBAAS,cAAc,IAAI,MAAM,CAEhC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,iBAAS,gBAAgB,IAAI,MAAM,CAElC;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,WAAW;IACtB,0EAA0E;;IAE1E,8EAA8E;;IAE9E,mFAAmF;;CAE3E,CAAC;AAEX,MAAM,CAAC,OAAO,WAAW,WAAW,CAAC;IACnC,4EAA4E;IAC5E,KAAY,OAAO,GAAG,kBAAkB,CAAC;CAC1C"}

package/dist/client-hints.js

@@ -0,0 +1,268 @@
+/**
+ * Client Hints header parsing for edge-side device capability detection.
+ *
+ * Converts HTTP Client Hints headers into the same `ExtendedDeviceCapabilities`
+ * structure that `@czap/detect` uses, enabling reuse of the pure tier mapping
+ * functions at the edge without browser APIs.
+ *
+ * @module
+ */
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Type guard for Web API Headers objects (fetch Headers).
+ * Checks for the `get` method that distinguishes Headers from plain objects.
+ */
+function isWebHeaders(value) {
+    return typeof value.get === 'function';
+}
+/**
+ * Normalise a Headers-like input (Web API Headers or plain object) into
+ * a case-insensitive getter function.
+ */
+function headerGetter(headers) {
+    if (isWebHeaders(headers)) {
+        return (name) => headers.get(name) ?? undefined;
+    }
+    // Client Hints headers are always lowercase in spec, but normalise anyway
+    const lower = {};
+    for (const [k, v] of Object.entries(headers)) {
+        if (v !== undefined)
+            lower[k.toLowerCase()] = v;
+    }
+    return (name) => lower[name.toLowerCase()];
+}
+/**
+ * Parse a numeric header, returning undefined for missing / malformed values.
+ */
+function parseFloat_(get, name) {
+    const raw = get(name);
+    if (raw === undefined || raw === '')
+        return undefined;
+    const n = Number.parseFloat(raw);
+    return Number.isFinite(n) ? n : undefined;
+}
+/**
+ * Clamp device memory to the set of valid values browsers actually report.
+ */
+function clampMemory(raw) {
+    const buckets = [0.25, 0.5, 1, 2, 4, 8];
+    let closest = buckets[0];
+    for (const b of buckets) {
+        if (Math.abs(b - raw) < Math.abs(closest - raw))
+            closest = b;
+    }
+    return closest;
+}
+/**
+ * Crude GPU tier heuristic from User-Agent string.
+ * Without WebGL renderer info we can only make rough guesses.
+ */
+function gpuTierFromUA(ua) {
+    if (!ua)
+        return 1;
+    const lower = ua.toLowerCase();
+    // Very low-end indicators
+    if (/kaios|nokia|feature/i.test(lower))
+        return 0;
+    // High-end mobile
+    if (/iphone\s*1[4-9]|iphone\s*[2-9]\d/i.test(lower))
+        return 2;
+    if (/sm-s9|sm-s2[4-9]|pixel\s*[8-9]/i.test(lower))
+        return 2;
+    // Desktop with common high-end hints
+    if (/windows nt.*win64|macintosh.*mac os x 1[4-9]/i.test(lower))
+        return 2;
+    // Default to low-mid -- conservative
+    return 1;
+}
+/**
+ * Map the ECT (effective connection type) string to a normalised form.
+ */
+function normaliseECT(ect) {
+    if (!ect)
+        return '4g';
+    const lower = ect.toLowerCase().trim();
+    if (['slow-2g', '2g', '3g', '4g'].includes(lower))
+        return lower;
+    return '4g';
+}
+// ---------------------------------------------------------------------------
+// Accept-CH / Critical-CH header values
+// ---------------------------------------------------------------------------
+const ALL_HINTS = [
+    'Sec-CH-Device-Memory',
+    'Sec-CH-DPR',
+    'Sec-CH-Viewport-Width',
+    'Sec-CH-Viewport-Height',
+    'Sec-CH-Prefers-Reduced-Motion',
+    'Sec-CH-Prefers-Color-Scheme',
+    'Sec-CH-UA-Mobile',
+    'Sec-CH-UA',
+    'Sec-CH-UA-Platform',
+    'Save-Data',
+    'Downlink',
+    'ECT',
+    'RTT',
+];
+const CRITICAL_HINTS = [
+    'Sec-CH-Prefers-Reduced-Motion',
+    'Sec-CH-Prefers-Color-Scheme',
+    'Sec-CH-UA-Mobile',
+    'Sec-CH-Device-Memory',
+];
+// ---------------------------------------------------------------------------
+// Public API -- namespace object pattern
+// ---------------------------------------------------------------------------
+/**
+ * Parse Client Hints headers into an {@link ExtendedDeviceCapabilities} structure.
+ *
+ * For properties that cannot be determined from headers (GPU tier, WebGPU
+ * support, CPU cores), conservative defaults are used.
+ *
+ * @example
+ * ```ts
+ * import { ClientHints } from '@czap/edge';
+ *
+ * const caps = ClientHints.parseClientHints({
+ *   'sec-ch-device-memory': '8',
+ *   'sec-ch-dpr': '2',
+ *   'sec-ch-viewport-width': '1440',
+ *   'sec-ch-prefers-color-scheme': 'dark',
+ *   'sec-ch-ua-mobile': '?0',
+ * });
+ * console.log(caps.memory);             // 8
+ * console.log(caps.devicePixelRatio);    // 2
+ * console.log(caps.prefersColorScheme);  // 'dark'
+ * ```
+ *
+ * @param headers - Client Hints headers (plain object or Web API Headers)
+ * @returns An {@link ExtendedDeviceCapabilities} structure
+ */
+function parseClientHints(headers) {
+    const get = headerGetter(headers);
+    // Memory
+    const rawMemory = parseFloat_(get, 'sec-ch-device-memory');
+    const memory = rawMemory !== undefined ? clampMemory(rawMemory) : 4;
+    // DPR
+    const dpr = parseFloat_(get, 'sec-ch-dpr') ?? 1;
+    // Viewport
+    const viewportWidth = parseFloat_(get, 'sec-ch-viewport-width') ?? 1920;
+    const viewportHeight = parseFloat_(get, 'sec-ch-viewport-height') ?? 1080;
+    // Preferences
+    const reducedMotionRaw = get('sec-ch-prefers-reduced-motion');
+    const prefersReducedMotion = reducedMotionRaw === 'reduce' || reducedMotionRaw === '"reduce"';
+    const colorSchemeRaw = get('sec-ch-prefers-color-scheme');
+    const prefersColorScheme = colorSchemeRaw === 'dark' || colorSchemeRaw === '"dark"' ? 'dark' : 'light';
+    // Touch (mobile hint)
+    const mobileRaw = get('sec-ch-ua-mobile');
+    const touchPrimary = mobileRaw === '?1' || mobileRaw === 'true';
+    // Save-Data
+    const saveDataRaw = get('save-data');
+    const saveData = saveDataRaw === 'on' || saveDataRaw === '1' || saveDataRaw === 'true';
+    // Network
+    const downlink = parseFloat_(get, 'downlink') ?? 10;
+    const ect = normaliseECT(get('ect'));
+    // GPU tier heuristic from UA
+    const gpu = gpuTierFromUA(get('user-agent'));
+    return {
+        // Base DeviceCapabilities
+        gpu,
+        cores: 4, // Conservative default -- not available via Client Hints
+        memory,
+        webgpu: false, // Cannot determine from headers
+        touchPrimary,
+        prefersReducedMotion,
+        prefersColorScheme,
+        viewportWidth,
+        viewportHeight,
+        devicePixelRatio: dpr,
+        connection: {
+            effectiveType: ect,
+            downlink,
+            saveData,
+        },
+        // Extended properties -- conservative defaults for edge
+        prefersContrast: 'no-preference',
+        forcedColors: false,
+        prefersReducedTransparency: false,
+        dynamicRange: 'standard',
+        colorGamut: 'srgb',
+        updateRate: 'fast',
+    };
+}
+/**
+ * Generate the `Accept-CH` header value for requesting all useful Client Hints
+ * on subsequent requests.
+ *
+ * @example
+ * ```ts
+ * import { ClientHints } from '@czap/edge';
+ *
+ * const response = new Response('OK', {
+ *   headers: { 'Accept-CH': ClientHints.acceptCHHeader() },
+ * });
+ * ```
+ *
+ * @returns A comma-separated list of Client Hint header names
+ */
+function acceptCHHeader() {
+    return ALL_HINTS.join(', ');
+}
+/**
+ * Generate the `Critical-CH` header value for hints needed on the very first
+ * request (triggers a browser retry if missing).
+ *
+ * @example
+ * ```ts
+ * import { ClientHints } from '@czap/edge';
+ *
+ * const response = new Response('OK', {
+ *   headers: {
+ *     'Accept-CH': ClientHints.acceptCHHeader(),
+ *     'Critical-CH': ClientHints.criticalCHHeader(),
+ *   },
+ * });
+ * ```
+ *
+ * @returns A comma-separated list of critical Client Hint header names
+ */
+function criticalCHHeader() {
+    return CRITICAL_HINTS.join(', ');
+}
+// ---------------------------------------------------------------------------
+// Namespace export
+// ---------------------------------------------------------------------------
+/**
+ * Client Hints namespace.
+ *
+ * Parses HTTP Client Hints headers into the same
+ * {@link ExtendedDeviceCapabilities} structure used by `@czap/detect`,
+ * enabling server-side / edge-side tier mapping without browser APIs.
+ * Also generates the `Accept-CH` and `Critical-CH` response headers needed
+ * to request hints from the browser.
+ *
+ * @example
+ * ```ts
+ * import { ClientHints } from '@czap/edge';
+ *
+ * // In an edge handler:
+ * const caps = ClientHints.parseClientHints(request.headers);
+ * const response = new Response(body, {
+ *   headers: {
+ *     'Accept-CH': ClientHints.acceptCHHeader(),
+ *     'Critical-CH': ClientHints.criticalCHHeader(),
+ *   },
+ * });
+ * ```
+ */
+export const ClientHints = {
+    /** Parse Client Hints headers into {@link ExtendedDeviceCapabilities}. */
+    parseClientHints,
+    /** Produce the `Accept-CH` response header value listing all useful hints. */
+    acceptCHHeader,
+    /** Produce the `Critical-CH` response header value listing boot-required hints. */
+    criticalCHHeader,
+};
+//# sourceMappingURL=client-hints.js.map

package/dist/client-hints.js.map

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

package/dist/edge-tier.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Edge-side tier detection -- wraps the pure tier mapping functions from
+ * `@czap/detect` for use with HTTP Client Hints headers at the edge.
+ *
+ * @module
+ */
+import type { CapLevel } from '@czap/core';
+import type { DesignTier, MotionTier } from '@czap/detect';
+import type { ClientHintsHeaders } from './client-hints.js';
+/**
+ * Outcome of an edge-side tier detection sweep.
+ *
+ * All three fields use the same branded tier types as the client runtime,
+ * so downstream boundary evaluation and output gating reuse the exact
+ * code paths from `@czap/detect`.
+ */
+export interface EdgeTierResult {
+    /** Highest {@link CapLevel} the device qualifies for. */
+    readonly capLevel: CapLevel;
+    /** Motion complexity tier permitted for this device. */
+    readonly motionTier: MotionTier;
+    /** Visual fidelity tier permitted for this device. */
+    readonly designTier: DesignTier;
+}
+/**
+ * Detect capability tiers from HTTP headers using Client Hints parsing
+ * and the same pure tier mapping functions used on the client.
+ */
+declare function detectTier(headers: Headers | ClientHintsHeaders): EdgeTierResult;
+/**
+ * Generate HTML data attribute string for injection into the `<html>` element.
+ *
+ * @example
+ * ```
+ * tierDataAttributes(result)
+ * // => 'data-czap-cap="reactive" data-czap-motion="animations" data-czap-design="enhanced"'
+ * ```
+ */
+declare function tierDataAttributes(result: EdgeTierResult): string;
+/**
+ * Edge tier detection namespace.
+ *
+ * Pairs {@link ClientHints.parseClientHints} with the pure tier-mapping
+ * functions from `@czap/detect` so the edge and the browser produce the
+ * same `capLevel`/`motionTier`/`designTier` triple for a given device.
+ *
+ * @example
+ * ```ts
+ * import { EdgeTier } from '@czap/edge';
+ *
+ * const result = EdgeTier.detectTier(request.headers);
+ * const html = `<html ${EdgeTier.tierDataAttributes(result)}>`;
+ * // `<html data-czap-cap="reactive" data-czap-motion="animations" data-czap-design="enhanced">`
+ * ```
+ */
+export declare const EdgeTier: {
+    /** Detect {@link EdgeTierResult} from a `Headers`-like bag. */
+    readonly detectTier: typeof detectTier;
+    /** Render an `EdgeTierResult` into `data-czap-*` attributes for the root HTML element. */
+    readonly tierDataAttributes: typeof tierDataAttributes;
+};
+export declare namespace EdgeTier {
+    /** Alias for {@link EdgeTierResult}. */
+    type Result = EdgeTierResult;
+}
+export {};
+//# sourceMappingURL=edge-tier.d.ts.map

package/dist/edge-tier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge-tier.d.ts","sourceRoot":"","sources":["../src/edge-tier.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE3D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAM5D;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,wDAAwD;IACxD,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,sDAAsD;IACtD,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;CACjC;AAMD;;;GAGG;AACH,iBAAS,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,kBAAkB,GAAG,cAAc,CAMzE;AAED;;;;;;;;GAQG;AACH,iBAAS,kBAAkB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAE1D;AAMD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,QAAQ;IACnB,+DAA+D;;IAE/D,0FAA0F;;CAElF,CAAC;AAEX,MAAM,CAAC,OAAO,WAAW,QAAQ,CAAC;IAChC,wCAAwC;IACxC,KAAY,MAAM,GAAG,cAAc,CAAC;CACrC"}

package/dist/edge-tier.js

@@ -0,0 +1,60 @@
+/**
+ * Edge-side tier detection -- wraps the pure tier mapping functions from
+ * `@czap/detect` for use with HTTP Client Hints headers at the edge.
+ *
+ * @module
+ */
+import { tierFromCapabilities, motionTierFromCapabilities, designTierFromCapabilities } from '@czap/detect';
+import { ClientHints } from './client-hints.js';
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Detect capability tiers from HTTP headers using Client Hints parsing
+ * and the same pure tier mapping functions used on the client.
+ */
+function detectTier(headers) {
+    const caps = ClientHints.parseClientHints(headers);
+    const capLevel = tierFromCapabilities(caps);
+    const motionTier = motionTierFromCapabilities(caps);
+    const designTier = designTierFromCapabilities(caps);
+    return { capLevel, motionTier, designTier };
+}
+/**
+ * Generate HTML data attribute string for injection into the `<html>` element.
+ *
+ * @example
+ * ```
+ * tierDataAttributes(result)
+ * // => 'data-czap-cap="reactive" data-czap-motion="animations" data-czap-design="enhanced"'
+ * ```
+ */
+function tierDataAttributes(result) {
+    return `data-czap-cap="${result.capLevel}" data-czap-motion="${result.motionTier}" data-czap-design="${result.designTier}"`;
+}
+// ---------------------------------------------------------------------------
+// Namespace export
+// ---------------------------------------------------------------------------
+/**
+ * Edge tier detection namespace.
+ *
+ * Pairs {@link ClientHints.parseClientHints} with the pure tier-mapping
+ * functions from `@czap/detect` so the edge and the browser produce the
+ * same `capLevel`/`motionTier`/`designTier` triple for a given device.
+ *
+ * @example
+ * ```ts
+ * import { EdgeTier } from '@czap/edge';
+ *
+ * const result = EdgeTier.detectTier(request.headers);
+ * const html = `<html ${EdgeTier.tierDataAttributes(result)}>`;
+ * // `<html data-czap-cap="reactive" data-czap-motion="animations" data-czap-design="enhanced">`
+ * ```
+ */
+export const EdgeTier = {
+    /** Detect {@link EdgeTierResult} from a `Headers`-like bag. */
+    detectTier,
+    /** Render an `EdgeTierResult` into `data-czap-*` attributes for the root HTML element. */
+    tierDataAttributes,
+};
+//# sourceMappingURL=edge-tier.js.map

package/dist/edge-tier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge-tier.js","sourceRoot":"","sources":["../src/edge-tier.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,oBAAoB,EAAE,0BAA0B,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAE5G,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAuBhD,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;GAGG;AACH,SAAS,UAAU,CAAC,OAAqC;IACvD,MAAM,IAAI,GAAG,WAAW,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;IACnD,MAAM,QAAQ,GAAG,oBAAoB,CAAC,IAAI,CAAC,CAAC;IAC5C,MAAM,UAAU,GAAG,0BAA0B,CAAC,IAAI,CAAC,CAAC;IACpD,MAAM,UAAU,GAAG,0BAA0B,CAAC,IAAI,CAAC,CAAC;IACpD,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,UAAU,EAAE,CAAC;AAC9C,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,kBAAkB,CAAC,MAAsB;IAChD,OAAO,kBAAkB,MAAM,CAAC,QAAQ,uBAAuB,MAAM,CAAC,UAAU,uBAAuB,MAAM,CAAC,UAAU,GAAG,CAAC;AAC9H,CAAC;AAED,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,+DAA+D;IAC/D,UAAU;IACV,0FAA0F;IAC1F,kBAAkB;CACV,CAAC"}