@czap/vite 0.1.0

package/src/css-quantize.ts

@@ -0,0 +1,294 @@
+/**
+ * `@quantize` CSS block parser and compiler.
+ *
+ * Parses custom `@quantize boundaryName { state { prop: value } }` blocks
+ * from CSS source and compiles them into native `@container` queries using
+ * resolved `BoundaryDef` thresholds.
+ *
+ * @module
+ */
+
+import type { Boundary } from '@czap/core';
+import { CSSCompiler } from '@czap/compiler';
+import { normalizeCssLineEndings } from './normalize-css-eol.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * A single parsed `@quantize` block: the boundary being quantised, the
+ * per-state property bag, and provenance info so HMR can emit
+ * source-mapped warnings.
+ */
+export interface QuantizeBlock {
+  /** Boundary name referenced in the at-rule preamble. */
+  readonly boundaryName: string;
+  /** `{ stateName: { cssProp: value } }` mapping. */
+  readonly states: Record<string, Record<string, string>>;
+  /** Absolute path of the CSS source file. */
+  readonly sourceFile: string;
+  /** 1-based source line where the block begins. */
+  readonly line: number;
+}
+
+// ---------------------------------------------------------------------------
+// Parser helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse all property declarations inside a state block starting at `pos`
+ * (the character immediately after the opening `{` of the state block).
+ *
+ * Uses character-level scanning so multi-line values -- e.g.
+ *   background: linear-gradient(
+ *     to bottom,
+ *     red,
+ *     blue
+ *   );
+ * -- are collected as a single declaration before matching.
+ *
+ * Tracks paren depth so commas/semicolons inside functional notation
+ * (var(), calc(), linear-gradient(), etc.) are not treated as delimiters.
+ * Tracks brace depth so values containing braces (e.g. `var(--x, empty)`)
+ * do not prematurely close the state block.
+ *
+ * Returns the parsed properties and the position immediately after the
+ * closing `}` of the state block.
+ */
+function parseStateDeclarations(css: string, pos: number): { props: Record<string, string>; end: number } {
+  const props: Record<string, string> = {};
+  let braceDepth = 0;
+
+  while (pos < css.length) {
+    // Skip whitespace between declarations
+    while (pos < css.length && /\s/.test(css[pos]!)) pos++;
+    if (pos >= css.length) break;
+
+    const ch = css[pos]!;
+
+    // Skip block comments
+    if (ch === '/' && css[pos + 1] === '*') {
+      pos += 2;
+      while (pos < css.length - 1 && !(css[pos] === '*' && css[pos + 1] === '/')) pos++;
+      pos += 2;
+      continue;
+    }
+
+    // Closing brace of the state block
+    if (ch === '}' && braceDepth === 0) {
+      pos++;
+      return { props, end: pos };
+    }
+
+    // Opening brace nested inside a value (e.g. var(--x, {}))
+    if (ch === '{') {
+      braceDepth++;
+      pos++;
+      continue;
+    }
+
+    if (ch === '}') {
+      braceDepth--;
+      pos++;
+      continue;
+    }
+
+    // Accumulate a full declaration: collect until `;` at paren-depth 0,
+    // or until `}` that closes this state block, whichever comes first.
+    let declBuf = '';
+    let parenDepth = 0;
+
+    while (pos < css.length) {
+      const dc = css[pos]!;
+
+      // Skip block comments inside declaration
+      if (dc === '/' && css[pos + 1] === '*') {
+        pos += 2;
+        while (pos < css.length - 1 && !(css[pos] === '*' && css[pos + 1] === '/')) pos++;
+        pos += 2;
+        continue;
+      }
+
+      // Skip quoted strings
+      if (dc === '"' || dc === "'") {
+        const quote = dc;
+        declBuf += dc;
+        pos++;
+        while (pos < css.length && css[pos] !== quote) {
+          if (css[pos] === '\\') {
+            declBuf += css[pos]!;
+            pos++;
+          }
+          declBuf += css[pos]!;
+          pos++;
+        }
+        if (pos < css.length) {
+          declBuf += css[pos]!;
+          pos++;
+        }
+        continue;
+      }
+
+      if (dc === '(') {
+        parenDepth++;
+        declBuf += dc;
+        pos++;
+        continue;
+      }
+      if (dc === ')') {
+        parenDepth--;
+        declBuf += dc;
+        pos++;
+        continue;
+      }
+
+      // Semicolon at paren-depth 0 ends the declaration
+      if (dc === ';' && parenDepth === 0) {
+        pos++;
+        break;
+      }
+
+      // Unmatched `}` at paren-depth 0 closes the state block --
+      // do NOT consume it here; the outer loop will handle it.
+      if (dc === '}' && parenDepth === 0) {
+        break;
+      }
+
+      declBuf += dc;
+      pos++;
+    }
+
+    const decl = declBuf.trim();
+    if (decl.length === 0) continue;
+
+    // Match `property-name: value` (property names are [a-zA-Z-][a-zA-Z0-9-]*)
+    const colonIdx = decl.indexOf(':');
+    if (colonIdx > 0) {
+      const propName = decl.slice(0, colonIdx).trim();
+      const propValue = decl.slice(colonIdx + 1).trim();
+      if (/^[a-zA-Z-][a-zA-Z0-9-]*$/.test(propName) && propValue.length > 0) {
+        props[propName] = propValue;
+      }
+    }
+  }
+
+  return { props, end: pos };
+}
+
+// ---------------------------------------------------------------------------
+// Parser
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse every `@quantize` block from CSS source text.
+ *
+ * Grammar:
+ *
+ * ```css
+ * @quantize boundaryName {
+ *   stateName {
+ *     property: value;
+ *   }
+ * }
+ * ```
+ *
+ * The outer `@quantize` and state-name matching is line-based for
+ * simplicity; property declarations inside state blocks use a
+ * character-level parser so that multi-line values (e.g.
+ * `linear-gradient` spread across lines) are collected correctly
+ * before being matched.
+ */
+export function parseQuantizeBlocks(css: string, sourceFile: string): readonly QuantizeBlock[] {
+  const normalized = normalizeCssLineEndings(css);
+  const blocks: QuantizeBlock[] = [];
+  const lines = normalized.split('\n');
+  let i = 0;
+
+  while (i < lines.length) {
+    const line = lines[i]!;
+    const atMatch = line.match(/^\s*@quantize\s+([a-zA-Z_][a-zA-Z0-9_-]*)\s*\{/);
+
+    if (atMatch) {
+      const boundaryName = atMatch[1]!;
+      const blockStartLine = i + 1; // 1-indexed
+      const states: Record<string, Record<string, string>> = {};
+
+      i++; // advance past @quantize line
+      let braceDepth = 1;
+
+      while (i < lines.length && braceDepth > 0) {
+        const currentLine = lines[i]!;
+        const trimmed = currentLine.trim();
+
+        if (braceDepth === 1) {
+          // Look for a state block opening: `stateName {`
+          const stateMatch = trimmed.match(/^([a-zA-Z_][a-zA-Z0-9_-]*)\s*\{/);
+          if (stateMatch) {
+            const stateName = stateMatch[1]!;
+
+            // Compute the character offset of the `{` that opens this state
+            // block inside the full CSS string so we can hand off to the
+            // character-level parser.
+            const lineOffset = normalized.split('\n').slice(0, i).join('\n').length + 1;
+            const openBrace = lineOffset + currentLine.indexOf('{') + 1;
+
+            const { props, end } = parseStateDeclarations(normalized, openBrace);
+            states[stateName] = props;
+
+            // Advance the line cursor to the line that contains `end`
+            let charCount = 0;
+            let lineIdx = 0;
+            for (const l of normalized.split('\n')) {
+              charCount += l.length + 1; // +1 for the '\n'
+              lineIdx++;
+              if (charCount >= end) break;
+            }
+            i = lineIdx;
+            continue;
+          }
+
+          // Closing brace for the @quantize block
+          if (trimmed === '}') {
+            braceDepth--;
+            i++;
+            continue;
+          }
+        }
+
+        // Track nested braces outside of state blocks for robustness
+        for (const ch of trimmed) {
+          if (ch === '{') braceDepth++;
+          if (ch === '}') braceDepth--;
+        }
+        i++;
+      }
+
+      blocks.push({
+        boundaryName,
+        states,
+        sourceFile,
+        line: blockStartLine,
+      });
+    } else {
+      i++;
+    }
+  }
+
+  return blocks;
+}
+
+// ---------------------------------------------------------------------------
+// Compiler (delegates to @czap/compiler CSSCompiler)
+// ---------------------------------------------------------------------------
+
+/**
+ * Compile a parsed {@link QuantizeBlock} plus its resolved
+ * {@link Boundary.Shape} into CSS `@container` query rules. Delegates
+ * to the canonical `CSSCompiler` to avoid duplicating threshold-to-query
+ * logic.
+ */
+export function compileQuantizeBlock(block: QuantizeBlock, boundary: Boundary.Shape): string {
+  const result = CSSCompiler.compile(boundary, block.states);
+  return CSSCompiler.serialize(result);
+}

package/src/environments.ts

@@ -0,0 +1,98 @@
+/**
+ * Vite 8 Environment API configuration.
+ *
+ * Provides environment-specific resolve conditions and optimisation
+ * settings for browser, server, and shader build targets.
+ *
+ * @module
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Named czap build environment. */
+export type CzapEnvironmentName = 'browser' | 'server' | 'shader';
+
+/**
+ * Subset of a Vite `Environment` config that czap touches: resolve
+ * conditions plus `optimizeDeps` include/exclude lists. Returned by
+ * {@link getEnvironmentConfig} and merged into the host Vite config
+ * via {@link buildEnvironments}.
+ */
+export interface CzapEnvironmentConfig {
+  readonly resolve: {
+    readonly conditions: string[];
+    readonly extensions: string[];
+  };
+  readonly optimizeDeps: {
+    readonly include: string[];
+    readonly exclude: string[];
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Environment Definitions
+// ---------------------------------------------------------------------------
+
+const BROWSER_ENV: CzapEnvironmentConfig = {
+  resolve: {
+    conditions: ['browser', 'import', 'module', 'default'],
+    extensions: ['.ts', '.tsx', '.js', '.jsx', '.css'],
+  },
+  optimizeDeps: {
+    include: ['@czap/core', '@czap/detect'],
+    exclude: [],
+  },
+} as const;
+
+const SERVER_ENV: CzapEnvironmentConfig = {
+  resolve: {
+    conditions: ['node', 'import', 'module', 'default'],
+    extensions: ['.ts', '.tsx', '.js', '.jsx'],
+  },
+  optimizeDeps: {
+    include: [],
+    exclude: ['@czap/core', '@czap/detect'],
+  },
+} as const;
+
+const SHADER_ENV: CzapEnvironmentConfig = {
+  resolve: {
+    conditions: ['browser', 'import', 'module', 'default'],
+    extensions: ['.ts', '.js', '.glsl', '.wgsl', '.vert', '.frag'],
+  },
+  optimizeDeps: {
+    include: ['@czap/core'],
+    exclude: ['@czap/detect'],
+  },
+} as const;
+
+const ENVIRONMENT_MAP: Record<CzapEnvironmentName, CzapEnvironmentConfig> = {
+  browser: BROWSER_ENV,
+  server: SERVER_ENV,
+  shader: SHADER_ENV,
+} as const;
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Get the Vite environment configuration for a specific czap target.
+ */
+export function getEnvironmentConfig(name: CzapEnvironmentName): CzapEnvironmentConfig {
+  return ENVIRONMENT_MAP[name];
+}
+
+/**
+ * Build the Vite environments configuration object from a list of
+ * requested environment names.
+ */
+export function buildEnvironments(names: readonly CzapEnvironmentName[]): Record<string, CzapEnvironmentConfig> {
+  const result: Record<string, CzapEnvironmentConfig> = {};
+  for (const name of names) {
+    result[name] = getEnvironmentConfig(name);
+  }
+  return result;
+}

package/src/hmr.ts

@@ -0,0 +1,121 @@
+/**
+ * HMR handler for `czap:update` messages.
+ *
+ * Performs surgical DOM updates when `@quantize` CSS or shader
+ * uniforms change during development, avoiding full page reloads.
+ *
+ * @module
+ */
+
+declare global {
+  interface HTMLCanvasElement {
+    /**
+     * czap runtime-attached WebGL program for HMR uniform updates.
+     * Set by the shader directive when a program is linked.
+     */
+    __czapProgram?: WebGLProgram;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Shape of the HMR payload the czap Vite plugin ships over the Vite
+ * dev-server WebSocket. Handled by {@link handleHMR} on the client.
+ */
+export interface HMRPayload {
+  /** Message discriminator. Always `'czap:update'`. */
+  readonly type: 'czap:update';
+  /** Boundary id whose compiled output changed. */
+  readonly boundary: string;
+  /** New compiled CSS (omitted when only uniforms changed). */
+  readonly css?: string;
+  /** New shader-uniform values (omitted when only CSS changed). */
+  readonly uniforms?: Record<string, number>;
+}
+
+// ---------------------------------------------------------------------------
+// CSS Hot Update
+// ---------------------------------------------------------------------------
+
+/**
+ * Find or create a <style> element for a specific boundary's compiled CSS.
+ * Uses a data attribute for identification across HMR cycles.
+ */
+function getOrCreateStyleElement(boundaryId: string): HTMLStyleElement {
+  const selector = `style[data-czap-boundary="${boundaryId}"]`;
+  const existing = document.querySelector(selector);
+  if (existing instanceof HTMLStyleElement) return existing;
+
+  const el = document.createElement('style');
+  el.setAttribute('data-czap-boundary', boundaryId);
+  document.head.appendChild(el);
+  return el;
+}
+
+/**
+ * Apply CSS updates by replacing the boundary's style element content.
+ */
+function applyCSSUpdate(boundary: string, css: string): void {
+  const el = getOrCreateStyleElement(boundary);
+  el.textContent = css;
+}
+
+// ---------------------------------------------------------------------------
+// Shader Uniform Hot Update
+// ---------------------------------------------------------------------------
+
+/**
+ * Update shader uniform values on all canvases that have a czap-boundary
+ * attribute matching the boundary name.
+ *
+ * This works by dispatching a custom event that the czap runtime shader
+ * system listens for, passing the uniform map for in-place updates.
+ */
+function applyUniformUpdate(boundary: string, uniforms: Record<string, number>): void {
+  const event = new CustomEvent('czap:uniform-update', {
+    detail: { boundary, uniforms },
+    bubbles: true,
+  });
+  document.dispatchEvent(event);
+
+  // Direct update: find canvas elements with matching boundary data attribute
+  const canvases = Array.from(document.querySelectorAll<HTMLCanvasElement>(`canvas[data-czap-boundary="${boundary}"]`));
+  for (const canvas of canvases) {
+    const gl = canvas.getContext('webgl2') ?? canvas.getContext('webgl');
+    if (!gl) continue;
+
+    // Look up the program stored on the canvas element via a custom property
+    const program = canvas.__czapProgram;
+    if (!program) continue;
+
+    for (const [name, value] of Object.entries(uniforms)) {
+      const location = gl.getUniformLocation(program, name);
+      if (location !== null) {
+        gl.uniform1f(location, value);
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Handle a czap:update HMR payload.
+ * Dispatches to CSS replacement or shader uniform updates based on payload content.
+ */
+export function handleHMR(payload: HMRPayload): void {
+  if (typeof document === 'undefined') return;
+
+  if (payload.css !== undefined) {
+    applyCSSUpdate(payload.boundary, payload.css);
+  }
+
+  if (payload.uniforms !== undefined) {
+    applyUniformUpdate(payload.boundary, payload.uniforms);
+  }
+}

package/src/html-transform.ts

@@ -0,0 +1,61 @@
+/**
+ * HTML transform -- resolves `data-czap="name"` to boundary JSON.
+ *
+ * Scans HTML/Astro source for `data-czap="..."` attributes, resolves
+ * the named boundary via the existing boundary resolution infrastructure,
+ * and replaces with `data-czap-boundary='...'` containing serialized JSON.
+ *
+ * @module
+ */
+
+import { Diagnostics } from '@czap/core';
+import { resolvePrimitive } from './primitive-resolve.js';
+
+// Match data-czap="boundaryName" (not data-czap-* which are other attrs)
+const DATA_CZAP_PATTERN = /data-czap="([^"]+)"/g;
+
+/**
+ * Transform HTML source, replacing `data-czap="name"` with resolved boundary JSON.
+ *
+ * @param source - The HTML/Astro source string
+ * @param fromFile - The file path of the source (for resolution context)
+ * @param projectRoot - The project root directory
+ * @returns The transformed source, or the original if no transforms needed
+ */
+export async function transformHTML(source: string, fromFile: string, projectRoot: string): Promise<string> {
+  const matches = [...source.matchAll(DATA_CZAP_PATTERN)];
+  if (matches.length === 0) return source;
+
+  let result = source;
+
+  for (const match of matches) {
+    const fullMatch = match[0]!;
+    const boundaryName = match[1]!;
+
+    const resolution = await resolvePrimitive('boundary', boundaryName, fromFile, projectRoot);
+    if (!resolution) {
+      Diagnostics.warn({
+        source: 'czap/vite.html-transform',
+        code: 'boundary-not-found',
+        message: `Boundary "${boundaryName}" could not be resolved for HTML transform.`,
+        detail: { fromFile },
+      });
+      continue;
+    }
+
+    const boundary = resolution.primitive;
+    const serialized = JSON.stringify({
+      id: boundary.id,
+      input: boundary.input,
+      thresholds: boundary.thresholds,
+      states: boundary.states,
+      hysteresis: boundary.hysteresis,
+    });
+
+    // Replace data-czap="name" with data-czap-boundary='...'
+    const replacement = `data-czap-boundary='${serialized.replace(/'/g, '&#39;')}'`;
+    result = result.replace(fullMatch, replacement);
+  }
+
+  return result;
+}

package/src/index.ts

@@ -0,0 +1,71 @@
+/**
+ * `@czap/vite` — **LiteShip** Vite 8 plugin: turns `@token` / `@theme` /
+ * `@style` / `@quantize` at-rule blocks into native CSS and **rigs** HMR for
+ * `@czap/*` definitions.
+ *
+ * The plugin hooks into Vite's `resolveId`, `load`, `transform`, and
+ * `handleHotUpdate` phases:
+ *
+ * - `resolveId` + `load`: map `virtual:czap/*` specifiers to generated
+ *   modules (device capabilities, WASM URL, ...).
+ * - `transform`: rewrite `@token`, `@theme`, `@style`, and `@quantize`
+ *   at-rule blocks into native CSS (custom properties,
+ *   `html[data-theme]` selectors, scoped `@layer` / `@scope` rules,
+ *   and `@container` queries).
+ * - `handleHotUpdate`: emit surgical HMR payloads so CSS variables,
+ *   shader uniforms, and boundary definitions update without a full
+ *   page reload.
+ *
+ * @example
+ * ```ts
+ * // vite.config.ts
+ * import { defineConfig } from 'vite';
+ * import { plugin as czap } from '@czap/vite';
+ *
+ * const config = defineConfig({
+ *   plugins: [czap({ themes: ['./themes/default.ts'] })],
+ * });
+ * ```
+ *
+ * @module
+ */
+
+// Plugin
+export type { PluginConfig } from './plugin.js';
+export { plugin } from './plugin.js';
+export { resolveWASM } from './wasm-resolve.js';
+export type { WASMResolution } from './wasm-resolve.js';
+
+// @quantize
+export type { QuantizeBlock } from './css-quantize.js';
+export { parseQuantizeBlocks, compileQuantizeBlock } from './css-quantize.js';
+
+// @token
+export type { TokenBlock } from './token-transform.js';
+export { parseTokenBlocks, compileTokenBlock } from './token-transform.js';
+
+// @theme
+export type { ThemeBlock } from './theme-transform.js';
+export { parseThemeBlocks, compileThemeBlock } from './theme-transform.js';
+
+// @style
+export type { StyleBlock } from './style-transform.js';
+export { parseStyleBlocks, compileStyleBlock } from './style-transform.js';
+
+// HTML transform
+export { transformHTML } from './html-transform.js';
+
+// Virtual modules
+export type { VirtualModuleId } from './virtual-modules.js';
+export { resolveVirtualId, isVirtualId, loadVirtualModule } from './virtual-modules.js';
+
+// HMR
+export type { HMRPayload } from './hmr.js';
+export { handleHMR } from './hmr.js';
+
+// Generic primitive resolution. `KIND_META` is intentionally not exported —
+// it's the internal static lookup table that powers `resolvePrimitive`.
+// Consumers building custom Vite plugin layers use `resolvePrimitive`;
+// they don't need the internal config map.
+export type { PrimitiveKind, PrimitiveResolution, PrimitiveShape } from './primitive-resolve.js';
+export { resolvePrimitive } from './primitive-resolve.js';

package/src/normalize-css-eol.ts

@@ -0,0 +1,8 @@
+/**
+ * Normalize CSS newlines to LF for line-based parsing of CSS at-rules.
+ *
+ * @module
+ */
+export function normalizeCssLineEndings(css: string): string {
+  return css.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+}