@czap/astro 0.1.0

package/src/headers.ts

@@ -0,0 +1,84 @@
+/**
+ * HTTP header helpers shipped by `@czap/astro`.
+ *
+ * Encodes the two concerns the integration cares about: asking browsers
+ * for the Client Hints czap uses (tier detection), and shipping the
+ * COOP/COEP pair required by `SharedArrayBuffer`-backed workers.
+ *
+ * @module
+ */
+
+/**
+ * Default `Accept-CH` / `Critical-CH` response headers czap requests
+ * so the browser sends viewport width, device memory, motion
+ * preference, and DPR on the next navigation.
+ */
+export const CLIENT_HINTS_HEADERS: Record<string, string> = {
+  'Accept-CH': 'Sec-CH-Viewport-Width, Sec-CH-Device-Memory, Sec-CH-Prefers-Reduced-Motion, Sec-CH-DPR',
+  'Critical-CH': 'Sec-CH-Viewport-Width',
+};
+
+/**
+ * COOP/COEP header pair required for `SharedArrayBuffer` (used by
+ * `@czap/worker`'s SPSC ring). Applied only when the integration is
+ * configured with `workers: { enabled: true }`.
+ */
+export const CROSS_ORIGIN_HEADERS: Record<string, string> = {
+  'Cross-Origin-Opener-Policy': 'same-origin',
+  'Cross-Origin-Embedder-Policy': 'require-corp',
+};
+
+/**
+ * Build the `[header, value]` entries czap wants to emit for a given
+ * feature toggle set. Used by dev-server middleware and edge adapters
+ * that prefer tuple iteration over the `Headers` API.
+ */
+export function getCzapHeaderEntries(options: {
+  readonly detectEnabled: boolean;
+  readonly workersEnabled: boolean;
+  readonly acceptCH?: string;
+  readonly criticalCH?: string;
+}): Array<readonly [string, string]> {
+  const entries: Array<readonly [string, string]> = [];
+
+  if (options.detectEnabled) {
+    const acceptCH = options.acceptCH ?? CLIENT_HINTS_HEADERS['Accept-CH'];
+    const criticalCH = options.criticalCH ?? CLIENT_HINTS_HEADERS['Critical-CH'];
+    if (acceptCH) {
+      entries.push(['Accept-CH', acceptCH]);
+    }
+    if (criticalCH) {
+      entries.push(['Critical-CH', criticalCH]);
+    }
+  }
+
+  if (options.workersEnabled) {
+    for (const [header, value] of Object.entries(CROSS_ORIGIN_HEADERS)) {
+      entries.push([header, value]);
+    }
+  }
+
+  return entries;
+}
+
+/**
+ * Apply the czap header set to an existing {@link Headers} bag and
+ * return it (for chaining). Convenience wrapper over
+ * {@link getCzapHeaderEntries} for middleware that already has a
+ * `Headers` object in hand.
+ */
+export function applyCzapHeaders(
+  headers: Headers,
+  options: {
+    readonly detectEnabled: boolean;
+    readonly workersEnabled: boolean;
+    readonly acceptCH?: string;
+    readonly criticalCH?: string;
+  },
+): Headers {
+  for (const [header, value] of getCzapHeaderEntries(options)) {
+    headers.set(header, value);
+  }
+
+  return headers;
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+/**
+ * `@czap/astro` — **LiteShip** on Astro 6: constraint-shaped adaptive
+ * projection hosted as islands and directives.
+ *
+ * Provides the Astro `Integration` that registers `@czap/vite`,
+ * injects client tier detection, **rigs** the `client:satellite` directive,
+ * and exposes `Satellite` for shells with server-resolved bearings.
+ *
+ * @example
+ * ```ts
+ * // astro.config.mjs
+ * import { defineConfig } from 'astro/config';
+ * import { integration as czap } from '@czap/astro';
+ *
+ * const config = defineConfig({
+ *   integrations: [czap({ themes: ['./themes/default.ts'] })],
+ * });
+ * ```
+ *
+ * @module
+ */
+
+export type { IntegrationConfig } from './integration.js';
+export { integration } from './integration.js';
+export type { ServerIslandContext, QuantizeProps } from './quantize.js';
+export { resolveInitialState } from './quantize.js';
+export { satelliteAttrs, resolveInitialStateFallback } from './Satellite.js';
+export type { SatelliteProps } from './Satellite.js';
+export { czapMiddleware } from './middleware.js';
+export type { CzapLocals, CzapMiddlewareConfig } from './middleware.js';

package/src/integration.ts

@@ -0,0 +1,309 @@
+/**
+ * Astro 6 `AstroIntegration` for czap.
+ *
+ * Registers the `@czap/vite` plugin, injects the detect/boot scripts,
+ * registers every client directive (`client:satellite`,
+ * `client:stream`, `client:llm`, `client:worker`, `client:gpu`,
+ * `client:wasm`) that the host opts into, and turns on Astro's
+ * `serverIslands` experimental flag when requested.
+ *
+ * @module
+ */
+
+import type { AstroIntegration } from 'astro';
+import { plugin } from '@czap/vite';
+import type { PluginConfig } from '@czap/vite';
+import { DETECT_UPGRADE_SCRIPT } from './detect-upgrade.js';
+import { getCzapHeaderEntries } from './headers.js';
+import type { RuntimeEndpointPolicy } from '@czap/web';
+import {
+  normalizeRuntimeSecurityPolicy,
+  type RuntimeHtmlPolicy,
+  type RuntimeSecurityPolicy,
+} from './runtime/policy.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Options passed to {@link integration} from `astro.config.mjs`. Every
+ * field is optional; omitted features fall back to conservative
+ * defaults (detect enabled, stream/llm/gpu enabled, workers/wasm/server
+ * islands opt-in).
+ */
+export interface IntegrationConfig {
+  /** Overrides passed through to `@czap/vite`'s plugin. */
+  readonly vite?: PluginConfig;
+  /** Enable the inline detect script (default `true`). */
+  readonly detect?: boolean;
+  /** Turn on Astro's experimental server-islands flag (default `false`). */
+  readonly serverIslands?: boolean;
+  /** WASM runtime configuration. */
+  readonly wasm?: { readonly enabled?: boolean; readonly path?: string };
+  /** GPU runtime configuration. */
+  readonly gpu?: { readonly enabled?: boolean; readonly preferWebGPU?: boolean };
+  /** Off-thread worker runtime configuration. */
+  readonly workers?: { readonly enabled?: boolean };
+  /** SSE streaming runtime configuration. */
+  readonly stream?: { readonly enabled?: boolean };
+  /** LLM streaming runtime configuration. */
+  readonly llm?: { readonly enabled?: boolean };
+  /** Security policies applied to runtime fetch/HTML boundaries. */
+  readonly security?: {
+    readonly endpointPolicy?: RuntimeEndpointPolicy;
+    readonly htmlPolicy?: RuntimeHtmlPolicy;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Detect Script
+// ---------------------------------------------------------------------------
+
+/**
+ * Inline script that runs device detection on page load and stores
+ * the result as CSS custom properties on the <html> element and
+ * as a global for runtime access.
+ */
+const DETECT_INLINE_SCRIPT = `
+(function(){
+  function writeDetectState(next) {
+    var safe = Object.freeze(Object.assign({}, next));
+    try {
+      Object.defineProperty(window, '__CZAP_DETECT__', {
+        value: safe,
+        configurable: true,
+        enumerable: false,
+        writable: false
+      });
+    } catch (_) {
+      try {
+        window.__CZAP_DETECT__ = safe;
+      } catch (_) {}
+    }
+  }
+
+  try {
+    var h = document.documentElement;
+    var w = window.innerWidth || 0;
+    var cores = navigator.hardwareConcurrency || 2;
+    var mem = navigator.deviceMemory || 4;
+    var touch = ('ontouchstart' in window) || (navigator.maxTouchPoints > 0);
+    var motion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+    var dark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+    var dpr = window.devicePixelRatio || 1;
+
+    h.style.setProperty('--czap-vw', w + 'px');
+    h.style.setProperty('--czap-cores', String(cores));
+    h.style.setProperty('--czap-dpr', String(dpr));
+    h.setAttribute('data-czap-touch', String(touch));
+    h.setAttribute('data-czap-motion', motion ? 'reduce' : 'no-preference');
+    h.setAttribute('data-czap-scheme', dark ? 'dark' : 'light');
+
+    // Provisional tier -- conservative, no GPU probe available inline.
+    // Full detect package overrides on hydration via data-czap-tier attribute.
+    var tier = 'reactive';
+    if (motion) tier = 'static';
+    else if (cores <= 2 || mem <= 2) tier = 'styled';
+    h.setAttribute('data-czap-tier', tier);
+    h.setAttribute('data-czap-tier-provisional', 'true');
+
+    writeDetectState({
+      tier: tier,
+      provisional: true
+    });
+  } catch(e) {}
+})();
+`.trim();
+
+function serializeInlineRuntimePolicy(policy: RuntimeSecurityPolicy): string {
+  return JSON.stringify(policy).replace(/</g, '\\u003c').replace(/>/g, '\\u003e').replace(/&/g, '\\u0026');
+}
+
+function runtimeBootstrapScript(policy: RuntimeSecurityPolicy): string {
+  return `
+import { bootstrapSlots, configureRuntimePolicy, installSwapReinit } from '@czap/astro/runtime';
+
+configureRuntimePolicy(${serializeInlineRuntimePolicy(policy)});
+bootstrapSlots();
+installSwapReinit();
+`.trim();
+}
+
+const WASM_RUNTIME_SCRIPT = `
+import { wasmUrl } from 'virtual:czap/wasm-url';
+import { configureWasmRuntime } from '@czap/astro/runtime';
+
+configureWasmRuntime(wasmUrl);
+`.trim();
+
+/**
+ * Build an `updateConfig` payload that toggles a single experimental flag
+ * not yet present in Astro's declared `experimental` shape.
+ *
+ * The `experimental` field on `AstroConfig` is strictly keyed, so adding
+ * an unknown flag requires a widening bridge. Containing that bridge
+ * here keeps the cast off individual call sites.
+ */
+function withExperimentalFlag(flag: string, value: boolean): { experimental: Record<string, unknown> } {
+  return { experimental: { [flag]: value } };
+}
+
+// ---------------------------------------------------------------------------
+// Integration
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the czap `AstroIntegration`.
+ *
+ * Plug the returned object into `astro.config.mjs`'s `integrations`
+ * array. The integration wires Astro's `astro:config:setup`,
+ * `astro:config:done`, `astro:server:setup`, and `astro:build:done`
+ * hooks.
+ *
+ * @example
+ * ```ts
+ * // astro.config.mjs
+ * import { integration as czap } from '@czap/astro';
+ *
+ * const config = defineConfig({
+ *   integrations: [czap({ detect: true, workers: { enabled: true } })],
+ * });
+ * ```
+ */
+export function integration(config?: IntegrationConfig): AstroIntegration {
+  const detectEnabled = config?.detect !== false;
+  const serverIslandsEnabled = config?.serverIslands === true;
+  const workersEnabled = config?.workers?.enabled === true;
+  const gpuEnabled = config?.gpu?.enabled !== false;
+  const streamEnabled = config?.stream?.enabled !== false;
+  const llmEnabled = config?.llm?.enabled !== false;
+  const wasmEnabled = config?.wasm?.enabled === true;
+  const runtimePolicy = normalizeRuntimeSecurityPolicy({
+    endpointPolicy: config?.security?.endpointPolicy,
+    htmlPolicy: config?.security?.htmlPolicy,
+  });
+
+  return {
+    name: '@czap/astro',
+
+    hooks: {
+      'astro:config:setup': ({ updateConfig, addClientDirective, injectScript, logger }) => {
+        type AstroViteConfig = Parameters<typeof updateConfig>[0]['vite'];
+        logger.info('Setting up @czap integration');
+
+        // Astro may carry a different Vite type graph than @czap/vite. The plugin
+        // runtime contract is still compatible, so the host integration owns the
+        // version bridge here instead of leaking duplicate plugin shapes downstream.
+        const astroViteConfig = {
+          plugins: [
+            plugin({
+              ...(config?.vite ?? {}),
+              ...(wasmEnabled ? { wasm: { enabled: true, path: config?.wasm?.path } } : {}),
+            }),
+          ],
+        } as AstroViteConfig;
+
+        updateConfig({
+          vite: astroViteConfig,
+        });
+
+        // Register client directives
+        addClientDirective({
+          name: 'satellite',
+          entrypoint: '@czap/astro/client-directives/satellite',
+        });
+        logger.info('Registered satellite client directive');
+
+        if (streamEnabled) {
+          addClientDirective({
+            name: 'stream',
+            entrypoint: '@czap/astro/client-directives/stream',
+          });
+          logger.info('Registered stream client directive');
+        }
+
+        if (llmEnabled) {
+          addClientDirective({
+            name: 'llm',
+            entrypoint: '@czap/astro/client-directives/llm',
+          });
+          logger.info('Registered llm client directive');
+        }
+
+        if (workersEnabled) {
+          addClientDirective({
+            name: 'worker',
+            entrypoint: '@czap/astro/client-directives/worker',
+          });
+          logger.info('Registered worker client directive');
+        }
+
+        if (gpuEnabled) {
+          addClientDirective({
+            name: 'gpu',
+            entrypoint: '@czap/astro/client-directives/gpu',
+          });
+          logger.info('Registered gpu client directive');
+        }
+
+        if (wasmEnabled) {
+          addClientDirective({
+            name: 'wasm',
+            entrypoint: '@czap/astro/client-directives/wasm',
+          });
+          logger.info('Registered wasm client directive');
+        }
+
+        // Inject detect script for client-side capability detection
+        if (detectEnabled) {
+          injectScript('head-inline', DETECT_INLINE_SCRIPT);
+          logger.info('Injected detect script');
+
+          // Inject GPU probe upgrade (deferred, non-blocking)
+          if (gpuEnabled) {
+            injectScript('page', DETECT_UPGRADE_SCRIPT);
+            logger.info('Injected GPU probe upgrade');
+          }
+        }
+
+        injectScript('page', runtimeBootstrapScript(runtimePolicy));
+
+        if (wasmEnabled) {
+          injectScript('page', WASM_RUNTIME_SCRIPT);
+          logger.info('Injected wasm runtime bootstrap');
+        }
+
+        // Configure server islands if enabled.
+        // `serverIslands` is not in Astro 6's declared experimental keys yet;
+        // enablement is delegated via a named bridge so only the one call site
+        // opts out of the declared-config shape.
+        if (serverIslandsEnabled) {
+          updateConfig(withExperimentalFlag('serverIslands', true));
+          logger.info('Enabled server islands');
+        }
+      },
+
+      'astro:config:done': ({ config: astroConfig, logger }) => {
+        logger.info(`@czap configured for ${astroConfig.output} output`);
+      },
+
+      'astro:server:setup': ({ server, logger }) => {
+        logger.info('@czap dev server middleware active');
+
+        if (detectEnabled || workersEnabled) {
+          server.middlewares.use((_req: unknown, res: { setHeader(k: string, v: string): void }, next: () => void) => {
+            for (const [header, value] of getCzapHeaderEntries({ detectEnabled, workersEnabled })) {
+              res.setHeader(header, value);
+            }
+            next();
+          });
+        }
+      },
+
+      'astro:build:done': ({ logger }) => {
+        logger.info('@czap build integration complete');
+      },
+    },
+  };
+}

package/src/middleware.ts

@@ -0,0 +1,133 @@
+/**
+ * Edge middleware -- Client Hints parsing, tier detection, response headers.
+ *
+ * Framework-agnostic handler compatible with Astro middleware,
+ * Cloudflare Workers, and Express/Vite dev server.
+ *
+ * @module
+ */
+
+import { ClientHints, createEdgeHostAdapter, EdgeTier } from '@czap/edge';
+import type { CompiledOutputs, EdgeHostAdapterConfig, ThemeCompileResult } from '@czap/edge';
+import type { ExtendedDeviceCapabilities } from '@czap/detect';
+import { applyCzapHeaders } from './headers.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Shape of `context.locals.czap` injected by {@link czapMiddleware}.
+ * Astro components (and downstream middleware) read this to drive
+ * adaptive rendering decisions.
+ */
+export interface CzapLocals {
+  /** Resolved tiers (capability, motion, design). */
+  readonly tier: {
+    readonly cap: string;
+    readonly motion: string;
+    readonly design: string;
+  };
+  /** Parsed device capabilities. */
+  readonly capabilities: ExtendedDeviceCapabilities;
+  /** Edge-host resolution result, present when an edge adapter is configured. */
+  readonly edge?: {
+    readonly theme?: ThemeCompileResult;
+    readonly compiledOutputs?: CompiledOutputs;
+    readonly htmlAttributes: string;
+    readonly cacheStatus: 'disabled' | 'hit' | 'miss';
+  };
+}
+
+/**
+ * Options accepted by {@link czapMiddleware}.
+ *
+ * Omit `edge` to run in pure Client-Hints mode. Pass `edge` when you
+ * have an `@czap/edge` host adapter (KV cache, theme compilation).
+ */
+export interface CzapMiddlewareConfig {
+  /** Edge host adapter configuration (KV cache, theme compilation). */
+  readonly edge?: EdgeHostAdapterConfig;
+  /** Whether to include the Client Hints request headers (default `true`). */
+  readonly detect?: boolean;
+  /** Whether to emit COOP/COEP headers for worker features. */
+  readonly workers?: { readonly enabled?: boolean };
+}
+
+interface MiddlewareContext {
+  readonly request: Request;
+  locals: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// Middleware
+// ---------------------------------------------------------------------------
+
+/**
+ * Create the czap edge middleware.
+ *
+ * Parses Client Hints from request headers, computes tier detection,
+ * injects results into `context.locals.czap`, and sets Client Hints
+ * response headers (`Accept-CH`, `Critical-CH`).
+ *
+ * @example
+ * ```ts
+ * // Astro middleware (src/middleware.ts)
+ * import { czapMiddleware } from '@czap/astro';
+ * export const onRequest = czapMiddleware();
+ * ```
+ */
+export function czapMiddleware(
+  config?: CzapMiddlewareConfig,
+): (context: MiddlewareContext, next: () => Promise<Response>) => Promise<Response> {
+  const edgeConfig = config?.edge;
+  let edgeAdapter: ReturnType<typeof createEdgeHostAdapter> | null = null;
+  if (edgeConfig) {
+    edgeAdapter = createEdgeHostAdapter(edgeConfig);
+  }
+  const detectEnabled = config?.detect !== false;
+  const workersEnabled = config?.workers?.enabled === true;
+
+  return async (context: MiddlewareContext, next: () => Promise<Response>): Promise<Response> => {
+    const edgeResolution = edgeAdapter ? await edgeAdapter.resolve(context.request.headers) : null;
+    const capabilities = edgeResolution?.capabilities ?? ClientHints.parseClientHints(context.request.headers);
+    const tier = edgeResolution?.tier ?? EdgeTier.detectTier(context.request.headers);
+
+    // Inject into locals for component access
+    context.locals.czap = {
+      tier: {
+        cap: tier.capLevel,
+        motion: tier.motionTier,
+        design: tier.designTier,
+      },
+      capabilities,
+      ...(edgeResolution
+        ? {
+            edge: {
+              theme: edgeResolution.theme,
+              compiledOutputs: edgeResolution.compiledOutputs,
+              htmlAttributes: edgeResolution.htmlAttributes,
+              cacheStatus: edgeResolution.cacheStatus,
+            },
+          }
+        : {}),
+    } satisfies CzapLocals;
+
+    // Continue to the route handler
+    const response = await next();
+
+    // Add Client Hints request headers to the response
+    const headers = applyCzapHeaders(new Headers(response.headers), {
+      detectEnabled,
+      workersEnabled,
+      acceptCH: edgeResolution?.responseHeaders.acceptCH ?? ClientHints.acceptCHHeader(),
+      criticalCH: edgeResolution?.responseHeaders.criticalCH ?? ClientHints.criticalCHHeader(),
+    });
+
+    return new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers,
+    });
+  };
+}