@usefragments/core 1.0.0

package/src/conform.ts

@@ -0,0 +1,160 @@
+/**
+ * Shared contract for the design-system conform engine.
+ *
+ * These types are the single source of truth for the conform pipeline:
+ * - The private Engine implements `conformSnippet(input, context)`.
+ * - The private hosted MCP runtime re-exports the result types as its tool contract.
+ * - Cloud / CLI / standalone-MCP each build a `DesignSystemContext` from their
+ *   own data source (Convex catalog, local config, bundle) and call the engine.
+ *
+ * Keeping them here (a browser-safe, dependency-light package) lets every
+ * surface agree on one shape without duplication.
+ */
+
+export type ConformConfidence = "high" | "medium" | "low";
+
+export interface ConformInput {
+  /** UI code to conform: JSX/TSX, HTML, or a CSS/SCSS block. */
+  code: string;
+  /** Filename or extension hint used to pick the parser (defaults to TSX). */
+  filename?: string;
+  /** deterministic (default) applies safe edits; none returns findings only. */
+  apply?: "deterministic" | "none";
+}
+
+export interface ConformLocation {
+  line?: number;
+  column?: number;
+  endLine?: number;
+  endColumn?: number;
+}
+
+export interface ConformChange {
+  kind: "swap-component" | "rewrite-import" | "rename-prop" | "replace-token" | "add-fallback";
+  ruleId?: string;
+  /** Versioned diagnostic code, e.g. FUI0601. */
+  code?: string;
+  severity: "error" | "warning" | "info";
+  message: string;
+  before?: string;
+  after?: string;
+  /** Canonical primitive involved in the change, when applicable. */
+  canonical?: string;
+  confidence: ConformConfidence;
+  location?: ConformLocation;
+}
+
+export interface ConformSuggestion {
+  kind:
+    | "map-prop-value"
+    | "choose-among-alternates"
+    | "review-low-confidence"
+    | "flag-accessibility";
+  message: string;
+  canonical?: string;
+  hint?: string;
+  confidence: ConformConfidence;
+  location?: ConformLocation;
+}
+
+export interface ConformUnresolved {
+  element?: string;
+  canonical?: string;
+  reason: string;
+  location?: ConformLocation;
+}
+
+export interface ConformPropMapping {
+  rawProp: string;
+  canonicalProp: string;
+  /**
+   * Confirmed value translation table for cross-library prop values, e.g.
+   * `{ primary: "brand" }` to rewrite `color="primary"` into `variant="brand"`.
+   * A value is only rewritten when it exactly matches a key here; anything else
+   * is surfaced as a `map-prop-value` suggestion rather than guessed.
+   */
+  valueMap?: Record<string, string>;
+}
+
+export interface ConformComponentMapping {
+  /**
+   * Canonical primitive name, e.g. "Button". This is the JSX identifier the
+   * conform engine rewrites toward.
+   */
+  name: string;
+  /** Stable canonical vocabulary label when it differs from the component name. */
+  canonical?: string;
+  /** Native HTML element this component replaces, e.g. "button". */
+  htmlEquivalent?: string;
+  /** Import source to add or prefer for the canonical component. */
+  importPath?: string;
+  /** Confirmed prop renames from raw usage to the canonical component API. */
+  propMapping?: ConformPropMapping[];
+  /** Classifier confidence, when known. Only confirmed mappings should be passed. */
+  confidence?: number;
+}
+
+export interface ConformResult {
+  /** Code with deterministic edits applied, or the original if apply=none / parse failed. */
+  conformed: string;
+  changed: boolean;
+  summary: string;
+  designSystem?: {
+    name?: string;
+    importsAdded: string[];
+  };
+  /** Applied, deterministic edits. */
+  changes: ConformChange[];
+  /** Items needing agent judgment (e.g. cross-library prop-value translation). */
+  suggestions: ConformSuggestion[];
+  /** Elements/values with no design-system equivalent. */
+  unresolved: ConformUnresolved[];
+  /**
+   * How much of the tenant's design system this run could evaluate against.
+   * `evaluated` is false when the catalog supplied no tokens and no usable
+   * component mappings — in that case a "clean" result proves nothing, so
+   * callers (e.g. `prove_compliant`) must not certify compliance.
+   */
+  coverage?: ConformCoverage;
+}
+
+export interface ConformCoverage {
+  /** Count of relevant tokens (color/spacing/radius) the engine evaluated against. */
+  tokens: number;
+  /** Count of usable component mappings the engine evaluated against. */
+  components: number;
+  /** True when there was at least one token or component to evaluate against. */
+  evaluated: boolean;
+}
+
+/**
+ * A design-system token as the conform engine consumes it. Each surface maps
+ * its own token model into this shape.
+ */
+export interface ConformToken {
+  /** Raw value to match against code, e.g. "#2563eb". */
+  value: string;
+  /**
+   * The authored CSS custom property, e.g. "--brand-600", when known. A token
+   * is only eligible for an automatic rewrite when this is present — the engine
+   * never guesses a variable name.
+   */
+  cssVar?: string;
+  /** Token category, e.g. "color" | "spacing". */
+  category?: string;
+  /** Human-readable label for suggestions, e.g. "color.brand.600". */
+  label?: string;
+  /** Tie-break ordering when two tokens share a value: "canonical" wins. */
+  tier?: string;
+}
+
+/**
+ * Everything the conform engine needs about a tenant's design system. Built by
+ * each surface (cloud from Convex, CLI from local config, MCP from a bundle).
+ */
+export interface DesignSystemContext {
+  designSystemName?: string;
+  tokens: ConformToken[];
+  /** Confirmed canonical component replacements for this tenant. */
+  components?: ConformComponentMapping[];
+}

package/src/constants.ts

@@ -0,0 +1,114 @@
+/**
+ * Brand constants for easy rebranding if domain availability requires it.
+ * All naming throughout the codebase should reference these constants.
+ */
+export const BRAND = {
+  /** Display name (e.g., "Fragments") */
+  name: "Fragments",
+
+  /** Lowercase name for file paths and CLI (e.g., "fragments") */
+  nameLower: "fragments",
+
+  /** File extension for fragment definition files — V2 canonical format */
+  fileExtension: ".contract.json",
+
+  /** Legacy file extension for segments (still supported for migration) */
+  legacyFileExtension: ".segment.tsx",
+
+  /** JSON file extension for compiled output */
+  jsonExtension: ".fragment.json",
+
+  /** Default output file name (e.g., "fragments.json") */
+  outFile: "fragments.json",
+
+  /** Config file name (e.g., "fragments.config.ts") */
+  configFile: "fragments.config.ts",
+
+  /** Legacy config file name (still supported for migration) */
+  legacyConfigFile: "segments.config.ts",
+
+  /** CLI command name (e.g., "fragments") */
+  cliCommand: "fragments",
+
+  /** Directory for storing fragments, registry, and cache */
+  dataDir: ".fragments",
+
+  /** Components subdirectory within .fragments/ */
+  componentsDir: "components",
+
+  /** Registry file name */
+  registryFile: "registry.json",
+
+  /** Default compiler governance report path */
+  governanceFile: ".fragments/governance.json",
+
+  /** Context file name (AI-ready markdown) */
+  contextFile: "context.md",
+
+  /** Screenshots subdirectory */
+  screenshotsDir: "screenshots",
+
+  /** Cache subdirectory (gitignored) */
+  cacheDir: "cache",
+
+  /** Diff output subdirectory (gitignored) */
+  diffDir: "diff",
+
+  /** Manifest filename */
+  manifestFile: "manifest.json",
+
+  /** Prefix for localStorage keys (e.g., "fragments-") */
+  storagePrefix: "fragments-",
+
+  /** Static viewer HTML file name */
+  viewerHtmlFile: "fragments-viewer.html",
+
+  /** MCP tool name prefix (e.g., "fragments_") */
+  mcpToolPrefix: "fragments_",
+
+  /** File extension for block definition files */
+  blockFileExtension: ".block.ts",
+
+  /** @deprecated Use blockFileExtension instead */
+  recipeFileExtension: ".recipe.ts",
+
+  /** Vite plugin namespace */
+  vitePluginNamespace: "fragments-core-shim",
+} as const;
+
+export type Brand = typeof BRAND;
+
+/**
+ * Default configuration values for the service.
+ * These can be overridden in fragments.config.ts
+ */
+export const DEFAULTS = {
+  /** Default viewport dimensions */
+  viewport: {
+    width: 1280,
+    height: 800,
+  },
+
+  /** Default diff threshold (percentage) */
+  diffThreshold: 5,
+
+  /** Browser pool size */
+  poolSize: 3,
+
+  /** Idle timeout before browser shutdown (ms) - 5 minutes */
+  idleTimeoutMs: 5 * 60 * 1000,
+
+  /** Delay after render before capture (ms) */
+  captureDelayMs: 100,
+
+  /** Font loading timeout (ms) */
+  fontTimeoutMs: 3000,
+
+  /** Default theme */
+  theme: "light" as const,
+
+  /** Dev server port */
+  port: 6006,
+} as const;
+
+export type Defaults = typeof DEFAULTS;

package/src/context.ts

@@ -0,0 +1,2 @@
+export { generateContext, filterPlaceholders, PLACEHOLDER_PATTERNS } from './generate/index.js';
+export type { ContextOptions, ContextResult } from './generate/index.js';

package/src/contract/fixture.ts

@@ -0,0 +1,110 @@
+/**
+ * `catalog-fixture-a` — the committed reference catalog shared by the contract
+ * acceptance cases (contract-identity ACCEPTANCE §1–§4) and the Cloud-side
+ * parity test. Small but full-surface: components with props, tokens, one
+ * confirmed + one proposed canonical mapping, a policy with rules, a
+ * composition pattern, and one authored waiver.
+ *
+ * `CATALOG_FIXTURE_A_FCID` is the golden value for
+ * `contractHash(projectContractPreimage(catalogFixtureA))`. Cloud's Convex
+ * parity test imports BOTH from here, so an intentional projection change is
+ * updated in exactly one place and every runtime follows (ACCEPTANCE §1).
+ */
+import type { ContractCatalogInput } from "./preimage.js";
+
+export const catalogFixtureA: ContractCatalogInput = {
+  components: [
+    {
+      name: "Button",
+      props: ["variant", "size", "disabled"],
+      contract: { bans: [{ prop: "style", reason: "token-governed surface" }] },
+    },
+    {
+      name: "Card",
+      props: ["padding"],
+      compoundChildren: ["Card.Header", "Card.Body"],
+    },
+    {
+      name: "Card.Header",
+      parentName: "Card",
+      props: ["title"],
+    },
+  ],
+  tokens: [
+    { name: "--fui-color-accent", value: "#3366ff", type: "color" },
+    { name: "--fui-space-2", value: "8px", type: "dimension" },
+    { name: "--fui-radius-md", value: "6px", type: "dimension" },
+  ],
+  canonicalMappings: [
+    {
+      component: "LegacyButton",
+      canonical: "Button",
+      status: "confirmed",
+      propMapping: [{ rawProp: "kind", canonicalProp: "variant" }],
+    },
+    {
+      component: "AppCard",
+      canonical: "Card",
+      status: "proposed",
+    },
+  ],
+  policy: {
+    rules: {
+      tokens_hardcoded_values: { enabled: true, severity: "error" },
+      components_prefer_library: { enabled: true, severity: "warning" },
+    },
+    compositionPatterns: [
+      { id: "card-structure", region: "Card", require: ["Card.Header"], severity: "warning" },
+    ],
+    waivers: [
+      {
+        id: "waiver-001",
+        target: "FUI4001",
+        reason: "legacy promo banner, replacement tracked in #482",
+        expiresOn: "2026-09-30",
+      },
+    ],
+  },
+};
+
+/**
+ * Golden fcid for {@link catalogFixtureA}. Regenerate only on an intentional
+ * projection change: `contractHash(projectContractPreimage(catalogFixtureA))`.
+ */
+export const CATALOG_FIXTURE_A_FCID =
+  "41ae847b36618f25a9aa73bda47851f6467e30ce4bcfb5a5aa25d27fee3fee54";
+
+/**
+ * The same fixture expressed as Cloud-shaped mint materials: the
+ * `code-contracts` payload body and the DTCG token document that assemble to
+ * exactly {@link catalogFixtureA} through the adapters. Kept here so a fixture
+ * edit happens in one file — the core §1 test guards the payload↔components
+ * equivalence, and Cloud's parity test asserts the golden fcid end to end.
+ */
+export const catalogFixtureAContractPayload = {
+  fragments: [
+    {
+      meta: { name: "Button" },
+      props: { variant: {}, size: {}, disabled: {} },
+      contract: { bans: [{ prop: "style", reason: "token-governed surface" }] },
+    },
+    {
+      meta: { name: "Card" },
+      props: { padding: {} },
+      structure: {
+        compoundChildren: [{ name: "Card.Header" }, { name: "Card.Body" }],
+      },
+    },
+    {
+      meta: { name: "Card.Header", parentComponentName: "Card" },
+      props: { title: {} },
+    },
+  ],
+};
+
+/** DTCG form of {@link catalogFixtureA}'s tokens (flattened Cloud-side). */
+export const catalogFixtureATokensDtcg = {
+  "--fui-color-accent": { $value: "#3366ff", $type: "color" },
+  "--fui-space-2": { $value: "8px", $type: "dimension" },
+  "--fui-radius-md": { $value: "6px", $type: "dimension" },
+};

package/src/contract/hash.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from "vitest";
+
+import { canonicalPreimage, contractHash, sha256Hex } from "./hash.js";
+
+describe("sha256Hex", () => {
+  // FIPS 180-4 / NIST known-answer vectors.
+  it("matches the empty-string vector", () => {
+    expect(sha256Hex("")).toBe("e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855");
+  });
+
+  it("matches the 'abc' vector", () => {
+    expect(sha256Hex("abc")).toBe(
+      "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
+    );
+  });
+
+  it("matches the 56-byte multi-block vector", () => {
+    expect(sha256Hex("abcdbcdecdefdefgefghfghighijhijkijkljklmklmnlmnomnopnopq")).toBe(
+      "248d6a61d20638b8e5c026930c3e6039a33ce45964ff2167f6ecedd419db06c1"
+    );
+  });
+
+  it("hashes UTF-8 multibyte input deterministically", () => {
+    // "héllo→" exercises 2- and 3-byte UTF-8 sequences through TextEncoder.
+    expect(sha256Hex("héllo→")).toBe(sha256Hex("héllo→"));
+    expect(sha256Hex("héllo→")).toHaveLength(64);
+  });
+
+  it("crosses the padding boundary correctly (block-length inputs)", () => {
+    for (const n of [55, 56, 57, 63, 64, 65, 119, 120]) {
+      expect(sha256Hex("a".repeat(n))).toMatch(/^[0-9a-f]{64}$/);
+    }
+  });
+});
+
+describe("canonicalPreimage", () => {
+  it("is order-independent for object keys", () => {
+    expect(canonicalPreimage({ b: 1, a: 2 })).toBe(canonicalPreimage({ a: 2, b: 1 }));
+  });
+
+  it("drops undefined properties but preserves null", () => {
+    expect(canonicalPreimage({ a: 1, b: undefined })).toBe('{"a":1}');
+    expect(canonicalPreimage({ a: null })).toBe('{"a":null}');
+  });
+
+  it("normalizes negative zero to zero", () => {
+    expect(canonicalPreimage(-0)).toBe("0");
+    expect(canonicalPreimage(0)).toBe("0");
+  });
+
+  it("gives non-finite numbers unambiguous, distinct sentinels", () => {
+    expect(canonicalPreimage(NaN)).toBe('"@num:nan"');
+    expect(canonicalPreimage(Infinity)).toBe('"@num:+inf"');
+    expect(canonicalPreimage(-Infinity)).toBe('"@num:-inf"');
+    // and they do not collapse to null the way JSON.stringify would
+    expect(canonicalPreimage(NaN)).not.toBe(canonicalPreimage(null));
+  });
+
+  it("encodes nested arrays and objects canonically", () => {
+    expect(canonicalPreimage({ xs: [1, { z: true, y: "q" }] })).toBe(
+      '{"xs":[1,{"y":"q","z":true}]}'
+    );
+  });
+});
+
+describe("contractHash", () => {
+  it("is stable across attribute order", () => {
+    const a = { primitives: [{ id: "button", html: "button" }], v: 2 };
+    const b = { v: 2, primitives: [{ html: "button", id: "button" }] };
+    expect(contractHash(a)).toBe(contractHash(b));
+  });
+
+  it("changes when contract content changes", () => {
+    const base = { primitives: [{ id: "button" }] };
+    const changed = { primitives: [{ id: "button" }, { id: "input" }] };
+    expect(contractHash(base)).not.toBe(contractHash(changed));
+  });
+
+  it("ignores undefined optional fields", () => {
+    expect(contractHash({ id: "x", note: undefined })).toBe(contractHash({ id: "x" }));
+  });
+
+  it("returns a 64-char lowercase hex FCID", () => {
+    expect(contractHash({ any: "body" })).toMatch(/^[0-9a-f]{64}$/);
+  });
+});

package/src/contract/hash.ts

@@ -0,0 +1,195 @@
+/**
+ * Frontend Contract hashing — the cross-runtime content-address (FCID).
+ *
+ * The keystone trust property of the Frontend Contract is that "what the agent
+ * was served" and "what CI enforced" are provably the same bytes. That only
+ * holds if the contract hash is computed by an *identical* function in every
+ * runtime that touches it: the CLI (Node), the Convex isolate, and the browser.
+ *
+ * The fact-IR `hash64Hex` (FNV-1a, in `../facts/ids.ts`) is deliberately NOT
+ * used here: it is a 64-bit non-cryptographic integrity reference for in-process
+ * fact dedup, and Convex independently reaches for `crypto.subtle` (async, and a
+ * *different* algorithm). Two different hashes over the same preimage cannot back
+ * a "same 64 hex chars or the build is rejected" guarantee.
+ *
+ * So this module ships ONE function: a synchronous, dependency-free SHA-256 over
+ * a number-normalizing canonical preimage. Synchronous so it composes with the
+ * sync fact-compilation path; dependency-free so it is byte-identical across
+ * Node, the Convex isolate, and the browser without a native/optional dep
+ * (`crypto.subtle` is async; `@noble/hashes` is not a dependency of this MIT,
+ * browser-safe package). `TextEncoder` is the only ambient global used, and it is
+ * present in all three runtimes.
+ */
+
+// ---------------------------------------------------------------------------
+// Canonical preimage
+// ---------------------------------------------------------------------------
+
+/**
+ * Normalize a number to a stable string. `JSON.stringify` is stable for finite
+ * numbers, but renders `NaN`/`Infinity` as `null` (ambiguous) and does not
+ * collapse `-0`. Token values flow into the contract body, so a serializer that
+ * silently maps `NaN` to `null` would hash two different inputs to the same
+ * preimage. Non-finite numbers get unambiguous sentinels instead; `-0` collapses
+ * to `0`. This is total (never throws) because it runs on the ingest hot path.
+ */
+function normalizeNumber(value: number): string {
+  if (Number.isNaN(value)) return '"@num:nan"';
+  if (value === Infinity) return '"@num:+inf"';
+  if (value === -Infinity) return '"@num:-inf"';
+  if (Object.is(value, -0)) return "0";
+  return JSON.stringify(value);
+}
+
+/**
+ * Deterministic, canonical serialization of a contract body for hashing.
+ *
+ * - object keys sorted lexicographically; attribute order is irrelevant
+ * - `undefined` properties dropped (so optional fields don't perturb the hash)
+ * - numbers normalized via {@link normalizeNumber}
+ * - `bigint` encoded as its decimal string (JSON cannot represent it natively)
+ *
+ * This is intentionally a separate serializer from `facts/ids.ts#canonicalJson`:
+ * that one targets in-process fact IDs and does not normalize numbers, and we
+ * must not change its output (it would silently re-key existing fact IDs).
+ */
+export function canonicalPreimage(value: unknown): string {
+  if (value === undefined || value === null) return "null";
+  const type = typeof value;
+  if (type === "number") return normalizeNumber(value as number);
+  if (type === "string" || type === "boolean") return JSON.stringify(value);
+  if (type === "bigint") return JSON.stringify((value as bigint).toString());
+  if (Array.isArray(value)) {
+    return `[${value.map(canonicalPreimage).join(",")}]`;
+  }
+  if (type !== "object") {
+    // functions, symbols — not valid contract content; encode as null so the
+    // serializer stays total rather than throwing on the ingest path.
+    return "null";
+  }
+  const entries = Object.entries(value as Record<string, unknown>)
+    .filter(([, v]) => v !== undefined)
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalPreimage(v)}`).join(",")}}`;
+}
+
+// ---------------------------------------------------------------------------
+// SHA-256 (FIPS 180-4), synchronous, pure JS
+// ---------------------------------------------------------------------------
+
+// First 32 bits of the fractional parts of the cube roots of the first 64 primes.
+const K = new Uint32Array([
+  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+  0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+  0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+  0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+  0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+  0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+  0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+  0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+
+function rotr(value: number, bits: number): number {
+  return ((value >>> bits) | (value << (32 - bits))) >>> 0;
+}
+
+/**
+ * SHA-256 of a UTF-8 string, returned as 64 lowercase hex chars.
+ *
+ * Deterministic and synchronous in every runtime. Verified against the FIPS
+ * 180-4 vectors in `hash.test.ts`.
+ */
+export function sha256Hex(message: string): string {
+  const bytes = new TextEncoder().encode(message);
+  const length = bytes.length;
+  const bitLength = length * 8;
+
+  // Padding: append 0x80, then zeros, then the 64-bit big-endian bit length,
+  // so the total is a multiple of 64 bytes.
+  const withMarker = length + 1;
+  const zeroPad = (56 - (withMarker % 64) + 64) % 64;
+  const total = withMarker + zeroPad + 8;
+  const buffer = new Uint8Array(total);
+  buffer.set(bytes, 0);
+  buffer[length] = 0x80;
+
+  const view = new DataView(buffer.buffer);
+  // 64-bit length: high word then low word, big-endian. bitLength can exceed
+  // 2^32 for very large inputs, so split rather than truncate.
+  view.setUint32(total - 8, Math.floor(bitLength / 0x100000000));
+  view.setUint32(total - 4, bitLength >>> 0);
+
+  let h0 = 0x6a09e667;
+  let h1 = 0xbb67ae85;
+  let h2 = 0x3c6ef372;
+  let h3 = 0xa54ff53a;
+  let h4 = 0x510e527f;
+  let h5 = 0x9b05688c;
+  let h6 = 0x1f83d9ab;
+  let h7 = 0x5be0cd19;
+
+  const w = new Uint32Array(64);
+  for (let chunk = 0; chunk < total; chunk += 64) {
+    for (let t = 0; t < 16; t++) w[t] = view.getUint32(chunk + t * 4);
+    for (let t = 16; t < 64; t++) {
+      const w15 = w[t - 15];
+      const w2 = w[t - 2];
+      const s0 = rotr(w15, 7) ^ rotr(w15, 18) ^ (w15 >>> 3);
+      const s1 = rotr(w2, 17) ^ rotr(w2, 19) ^ (w2 >>> 10);
+      w[t] = (w[t - 16] + s0 + w[t - 7] + s1) >>> 0;
+    }
+
+    let a = h0;
+    let b = h1;
+    let c = h2;
+    let d = h3;
+    let e = h4;
+    let f = h5;
+    let g = h6;
+    let h = h7;
+
+    for (let t = 0; t < 64; t++) {
+      const s1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+      const ch = (e & f) ^ (~e & g);
+      const temp1 = (h + s1 + ch + K[t] + w[t]) >>> 0;
+      const s0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+      const maj = (a & b) ^ (a & c) ^ (b & c);
+      const temp2 = (s0 + maj) >>> 0;
+      h = g;
+      g = f;
+      f = e;
+      e = (d + temp1) >>> 0;
+      d = c;
+      c = b;
+      b = a;
+      a = (temp1 + temp2) >>> 0;
+    }
+
+    h0 = (h0 + a) >>> 0;
+    h1 = (h1 + b) >>> 0;
+    h2 = (h2 + c) >>> 0;
+    h3 = (h3 + d) >>> 0;
+    h4 = (h4 + e) >>> 0;
+    h5 = (h5 + f) >>> 0;
+    h6 = (h6 + g) >>> 0;
+    h7 = (h7 + h) >>> 0;
+  }
+
+  return [h0, h1, h2, h3, h4, h5, h6, h7]
+    .map((value) => value.toString(16).padStart(8, "0"))
+    .join("");
+}
+
+// ---------------------------------------------------------------------------
+// Contract hash (FCID)
+// ---------------------------------------------------------------------------
+
+/**
+ * The Frontend Contract ID: `sha256(canonicalPreimage(body))`, 64 lowercase hex
+ * chars. Identical inputs produce an identical FCID in the CLI, the Convex
+ * isolate, and the browser — which is what lets the gen-time agent view and the
+ * CI enforcement reference the same contract by hash.
+ */
+export function contractHash(body: unknown): string {
+  return sha256Hex(canonicalPreimage(body));
+}