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/theme-compiler.js ADDED Viewed

@@ -0,0 +1,94 @@
+/**
+ * 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
+ */
+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, name) {
+    const sanitised = name
+        .toLowerCase()
+        .replace(/[.\s]+/g, '-')
+        .replace(/[^a-z0-9-_]/g, '');
+    return `--${prefix}-${sanitised}`;
+}
+function normalizePrefix(prefix) {
+    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) {
+    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) {
+    const prefix = normalizePrefix(config.prefix ?? 'czap');
+    const entries = Object.entries(config.tokens);
+    if (entries.length === 0) {
+        return { declarations: [], css: ':root {}', inlineStyle: '' };
+    }
+    const declarations = [];
+    const cssDeclarations = [];
+    const inlineParts = [];
+    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,
+    };
+}
+//# sourceMappingURL=theme-compiler.js.map

package/dist/theme-compiler.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"theme-compiler.js","sourceRoot":"","sources":["../src/theme-compiler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AA4CH,MAAM,mBAAmB,GAAG,cAAc,CAAC;AAC3C,MAAM,wBAAwB,GAAG,SAAS,CAAC;AAE3C,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E;;;GAGG;AACH,SAAS,eAAe,CAAC,MAAc,EAAE,IAAY;IACnD,MAAM,SAAS,GAAG,IAAI;SACnB,WAAW,EAAE;SACb,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC;SACvB,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC;IAC/B,OAAO,KAAK,MAAM,IAAI,SAAS,EAAE,CAAC;AACpC,CAAC;AAED,SAAS,eAAe,CAAC,MAAc;IACrC,MAAM,UAAU,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC;IACxC,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CACb,yBAAyB,MAAM,uEAAuE,CACvG,CAAC;IACJ,CAAC;IAED,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;GAGG;AACH,SAAS,WAAW,CAAC,KAAsB;IACzC,MAAM,SAAS,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IACpE,IAAI,wBAAwB,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;QAC7C,MAAM,IAAI,KAAK,CAAC,6BAA6B,SAAS,yCAAyC,CAAC,CAAC;IACnG,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,YAAY,CAAC,MAA0B;IACrD,MAAM,MAAM,GAAG,eAAe,CAAC,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,CAAC;IACxD,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAE9C,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,EAAE,YAAY,EAAE,EAAE,EAAE,GAAG,EAAE,UAAU,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC;IAChE,CAAC;IAED,MAAM,YAAY,GAAuB,EAAE,CAAC;IAC5C,MAAM,eAAe,GAAa,EAAE,CAAC;IACrC,MAAM,WAAW,GAAa,EAAE,CAAC;IAEjC,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,OAAO,EAAE,CAAC;QACpC,MAAM,IAAI,GAAG,eAAe,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAC3C,MAAM,SAAS,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;QACrC,YAAY,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;QACxD,eAAe,CAAC,IAAI,CAAC,KAAK,IAAI,KAAK,SAAS,GAAG,CAAC,CAAC;QACjD,WAAW,CAAC,IAAI,CAAC,GAAG,IAAI,IAAI,SAAS,EAAE,CAAC,CAAC;IAC3C,CAAC;IAED,MAAM,GAAG,GAAG,YAAY,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC;IACxD,MAAM,WAAW,GAAG,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAE1C,OAAO;QACL,YAAY,EAAE,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC;QACzC,GAAG;QACH,WAAW;KACZ,CAAC;AACJ,CAAC"}

package/package.json ADDED Viewed

@@ -0,0 +1,55 @@
+{
+  "name": "@czap/edge",
+  "version": "0.1.0",
+  "description": "CDN-edge client hints, tier detection, and KV cache",
+  "license": "MIT",
+  "author": "Eassa Ayoub <eassa@heyoub.dev>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/heyoub/LiteShip",
+    "directory": "packages/edge"
+  },
+  "bugs": "https://github.com/heyoub/LiteShip/issues",
+  "homepage": "https://github.com/heyoub/LiteShip#readme",
+  "keywords": [
+    "czap",
+    "edge",
+    "cdn",
+    "client-hints",
+    "kv-cache",
+    "tier-detection",
+    "typescript"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "development": "./src/index.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@czap/core": "0.1.0",
+    "@czap/detect": "0.1.0"
+  },
+  "peerDependencies": {
+    "effect": ">=4.0.0-beta.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc"
+  }
+}

package/src/client-hints.ts ADDED Viewed

@@ -0,0 +1,338 @@
+/**
+ * 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, GPUTier } from '@czap/detect';
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+/**
+ * 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;
+}
+// ---------------------------------------------------------------------------
+// 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: ClientHintsHeaders | Headers): value is Headers {
+  return typeof (value as Record<string, unknown>).get === 'function';
+}
+/**
+ * Normalise a Headers-like input (Web API Headers or plain object) into
+ * a case-insensitive getter function.
+ */
+function headerGetter(headers: ClientHintsHeaders | Headers): (name: string) => string | undefined {
+  if (isWebHeaders(headers)) {
+    return (name: string) => headers.get(name) ?? undefined;
+  }
+  // Client Hints headers are always lowercase in spec, but normalise anyway
+  const lower: Record<string, string> = {};
+  for (const [k, v] of Object.entries(headers)) {
+    if (v !== undefined) lower[k.toLowerCase()] = v;
+  }
+  return (name: string) => lower[name.toLowerCase()];
+}
+/**
+ * Parse a numeric header, returning undefined for missing / malformed values.
+ */
+function parseFloat_(get: (name: string) => string | undefined, name: string): number | undefined {
+  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: number): number {
+  const buckets = [0.25, 0.5, 1, 2, 4, 8] as const;
+  let closest: number = 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: string | undefined): GPUTier {
+  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: string | undefined): string {
+  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',
+] as const;
+const CRITICAL_HINTS = [
+  'Sec-CH-Prefers-Reduced-Motion',
+  'Sec-CH-Prefers-Color-Scheme',
+  'Sec-CH-UA-Mobile',
+  'Sec-CH-Device-Memory',
+] as const;
+// ---------------------------------------------------------------------------
+// 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: ClientHintsHeaders | Headers): ExtendedDeviceCapabilities {
+  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: 'light' | 'dark' =
+    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(): string {
+  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(): string {
+  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,
+} as const;
+export declare namespace ClientHints {
+  /** Alias for {@link ClientHintsHeaders} — plain-object header bag shape. */
+  export type Headers = ClientHintsHeaders;
+}

package/src/edge-tier.ts ADDED Viewed

@@ -0,0 +1,93 @@
+/**
+ * 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 { tierFromCapabilities, motionTierFromCapabilities, designTierFromCapabilities } from '@czap/detect';
+import type { DesignTier, MotionTier } from '@czap/detect';
+import { ClientHints } from './client-hints.js';
+import type { ClientHintsHeaders } from './client-hints.js';
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+/**
+ * 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;
+}
+// ---------------------------------------------------------------------------
+// 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: Headers | ClientHintsHeaders): EdgeTierResult {
+  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: EdgeTierResult): string {
+  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,
+} as const;
+export declare namespace EdgeTier {
+  /** Alias for {@link EdgeTierResult}. */
+  export type Result = EdgeTierResult;
+}