@usefragments/core 1.10.2 → 2.0.0

package/src/compiled-types/parse.test.ts

@@ -1,9 +1,6 @@
 import { describe, expect, it } from "vitest";
 
-import {
-  CompiledFragmentsFileValidationError,
-  parseCompiledFragmentsFile,
-} from "./index.js";
+import { CompiledFragmentsFileValidationError, parseCompiledFragmentsFile } from "./index.js";
 
 const validCatalog = {
   version: "1.0.0",
@@ -24,6 +21,64 @@ describe("parseCompiledFragmentsFile", () => {
     expect(parseCompiledFragmentsFile(JSON.stringify(validCatalog))).toMatchObject(validCatalog);
   });
 
+  it("accepts legacy optional omissions and preserves additive future fields without cloning", () => {
+    const legacyWithFutureData = {
+      ...validCatalog,
+      futureRoot: { schemaVersion: 2 },
+      fragments: {
+        Button: {
+          ...validCatalog.fragments.Button,
+          futureFragment: { interactionModel: "press" },
+        },
+      },
+    };
+
+    const parsed = parseCompiledFragmentsFile(legacyWithFutureData);
+
+    expect(parsed).toBe(legacyWithFutureData);
+    expect(parsed).toHaveProperty("futureRoot.schemaVersion", 2);
+    expect(parsed).toHaveProperty("fragments.Button.futureFragment.interactionModel", "press");
+  });
+
+  it("round-trips a valid current artifact without reinterpretation", () => {
+    const current = {
+      ...validCatalog,
+      generatorVersion: "sha256:generator",
+      buildInputs: ["src/Button.fragment.ts"],
+      packageName: "@acme/ui",
+      fragments: {
+        Button: {
+          ...validCatalog.fragments.Button,
+          meta: {
+            ...validCatalog.fragments.Button.meta,
+            aliases: ["Action"],
+          },
+          guidance: validCatalog.fragments.Button.usage,
+          preview: { theme: "dark", dynamicRegions: ["[data-clock]"] },
+          matrix: { axes: { tone: ["neutral", "danger"], density: "auto" } },
+          design: { figmaNode: "node:1" },
+          tokens: ["--color-action"],
+        },
+      },
+      graph: {
+        nodes: [{ name: "Button", category: "Actions", status: "stable" }],
+        edges: [],
+        health: {
+          orphans: ["Button"],
+          hubs: [],
+          compositionCoverage: 0,
+          connectedComponents: [["Button"]],
+          averageDegree: 0,
+          nodeCount: 1,
+          edgeCount: 0,
+        },
+      },
+    };
+    const serialized = JSON.stringify(current);
+
+    expect(JSON.stringify(parseCompiledFragmentsFile(serialized))).toBe(serialized);
+  });
+
   it("reports invalid fragment paths instead of allowing command-specific crashes", () => {
     expect(() =>
       parseCompiledFragmentsFile(
@@ -44,4 +99,90 @@ describe("parseCompiledFragmentsFile", () => {
       )
     ).toThrow("fragments.Button.meta.name");
   });
+
+  it("rejects malformed nested and compact graph shapes with sorted deterministic issues", () => {
+    let thrown: unknown;
+    try {
+      parseCompiledFragmentsFile(
+        {
+          ...validCatalog,
+          fragments: {
+            Button: {
+              ...validCatalog.fragments.Button,
+              meta: { name: "Button", description: false, category: "Actions" },
+              props: {
+                tone: { type: 1, description: "Tone", values: ["neutral", 2] },
+              },
+              variants: [{ name: "Default", description: 2 }],
+            },
+          },
+          graph: {
+            nodes: [{ name: "Button", category: "Actions", status: "stable" }],
+            edges: [{ s: "Button", t: "Card", ty: "renders", w: "heavy", p: "usage" }],
+            health: {
+              orphans: [],
+              hubs: [],
+              compositionCoverage: 0,
+              connectedComponents: [["Button"]],
+              averageDegree: 0,
+              nodeCount: 1,
+              edgeCount: 1,
+            },
+          },
+        },
+        "/repo/fragments.json"
+      );
+    } catch (error) {
+      thrown = error;
+    }
+
+    expect(thrown).toBeInstanceOf(CompiledFragmentsFileValidationError);
+    expect((thrown as CompiledFragmentsFileValidationError).issues).toEqual([
+      "fragments.Button.meta.description must be a string",
+      "fragments.Button.props.tone.type must be a string",
+      "fragments.Button.props.tone.values must be an array of strings",
+      "fragments.Button.variants.0.description must be a string",
+      "graph.edges.0.w must be a finite number",
+    ]);
+  });
+
+  it("rejects duplicate semantic fragment, variant, and graph-node identities", () => {
+    expect(() =>
+      parseCompiledFragmentsFile({
+        ...validCatalog,
+        fragments: {
+          PrimaryButton: {
+            ...validCatalog.fragments.Button,
+            variants: [
+              { name: "Default", description: "First" },
+              { name: "Default", description: "Second" },
+            ],
+          },
+          SecondaryButton: validCatalog.fragments.Button,
+        },
+        graph: {
+          nodes: [
+            { name: "Button", category: "Actions", status: "stable" },
+            { name: "Button", category: "Actions", status: "stable" },
+          ],
+          edges: [],
+          health: {
+            orphans: [],
+            hubs: [],
+            compositionCoverage: 0,
+            connectedComponents: [],
+            averageDegree: 0,
+            nodeCount: 2,
+            edgeCount: 0,
+          },
+        },
+      })
+    ).toThrow(/duplicates/);
+  });
+
+  it("uses a runtime-independent invalid JSON diagnostic", () => {
+    expect(() => parseCompiledFragmentsFile('{"fragments":', "memory.json")).toThrow(
+      "Invalid compiled Fragments catalog at memory.json: invalid JSON"
+    );
+  });
 });

package/src/component-contract.ts

@@ -5,7 +5,7 @@
  * files instead of `.fragment.tsx`. Maps trivially to CompiledFragment.
  */
 
-import { z } from 'zod';
+import { z } from "zod";
 
 // ---------------------------------------------------------------------------
 // Component Contract interface
@@ -20,10 +20,10 @@ export interface ComponentContract {
   description: string;
   category: string;
   tags?: string[];
-  status?: 'stable' | 'beta' | 'deprecated' | 'experimental';
+  status?: "stable" | "beta" | "deprecated" | "experimental";
 
   /** Framework hint (for extraction and documentation) */
-  framework?: 'react' | 'vue' | 'svelte' | 'web-components' | 'angular';
+  framework?: "react" | "vue" | "svelte" | "web-components" | "angular";
 
   /** External npm packages required by this component (displayed in docs Setup section) */
   dependencies?: Array<{
@@ -42,14 +42,17 @@ export interface ComponentContract {
   propsSummary: string[];
 
   /** Component props schema */
-  props: Record<string, {
-    type: string;
-    values?: string[];
-    default?: unknown;
-    description: string;
-    required?: boolean;
-    constraints?: string[];
-  }>;
+  props: Record<
+    string,
+    {
+      type: string;
+      values?: string[];
+      default?: unknown;
+      description: string;
+      required?: boolean;
+      constraints?: string[];
+    }
+  >;
 
   /** Usage guidelines */
   usage: {
@@ -70,7 +73,14 @@ export interface ComponentContract {
   /** Relations to other components */
   relations?: Array<{
     component: string;
-    relationship: 'alternative' | 'parent' | 'child' | 'sibling' | 'composition' | 'complementary' | 'used-by';
+    relationship:
+      | "alternative"
+      | "parent"
+      | "child"
+      | "sibling"
+      | "composition"
+      | "complementary"
+      | "used-by";
     note: string;
   }>;
 
@@ -81,11 +91,14 @@ export interface ComponentContract {
     a11yRules?: string[];
     bans?: Array<{ pattern: string; message: string }>;
     /** Sub-component slot metadata for compound components */
-    compoundChildren?: Record<string, {
-      required?: boolean;
-      accepts?: string[];
-      description?: string;
-    }>;
+    compoundChildren?: Record<
+      string,
+      {
+        required?: boolean;
+        accepts?: string[];
+        description?: string;
+      }
+    >;
     /** Canonical JSX usage examples */
     canonicalUsage?: string[];
     /** Per-component performance budget override in bytes (gzipped) */
@@ -94,7 +107,7 @@ export interface ComponentContract {
 
   /** AI metadata for compound component generation */
   ai?: {
-    compositionPattern?: 'compound' | 'simple' | 'controlled' | 'wrapper';
+    compositionPattern?: "compound" | "simple" | "controlled" | "wrapper";
     subComponents?: string[];
     requiredChildren?: string[];
     commonPatterns?: string[];
@@ -106,14 +119,14 @@ export interface ComponentContract {
     wrapperModule?: string;
     wrapperExport?: string;
     css?: string[];
-    theme?: 'light' | 'dark';
+    theme?: "light" | "dark";
   };
 
   /** Provenance tracking — required for verification */
   provenance: {
-    source: 'manual' | 'extracted' | 'merged' | 'migrated';
+    source: "manual" | "extracted" | "merged" | "migrated";
     verified: boolean;
-    frameworkSupport?: 'native' | 'manual-only';
+    frameworkSupport?: "native" | "manual-only";
     sourceHash?: string;
     extractedAt?: string;
   };
@@ -124,11 +137,14 @@ export interface ComponentContract {
   /** Figma mappings (same DSL as .fragment.tsx but in JSON form) */
   figma?: {
     nodeUrl?: string;
-    propMappings?: Record<string, {
-      type: 'string' | 'boolean' | 'enum' | 'instance' | 'children' | 'textContent';
-      figmaProperty: string;
-      values?: Record<string, string>;
-    }>;
+    propMappings?: Record<
+      string,
+      {
+        type: "string" | "boolean" | "enum" | "instance" | "children" | "textContent";
+        figmaProperty: string;
+        values?: Record<string, string>;
+      }
+    >;
   };
 }
 
@@ -161,7 +177,15 @@ const contractExampleSchema = z.object({
 
 const contractRelationSchema = z.object({
   component: z.string(),
-  relationship: z.enum(['alternative', 'parent', 'child', 'sibling', 'composition', 'complementary', 'used-by']),
+  relationship: z.enum([
+    "alternative",
+    "parent",
+    "child",
+    "sibling",
+    "composition",
+    "complementary",
+    "used-by",
+  ]),
   note: z.string(),
 });
 
@@ -169,21 +193,30 @@ const contractContractSchema = z.object({
   propsSummary: z.array(z.string()).optional(),
   scenarioTags: z.array(z.string()).optional(),
   a11yRules: z.array(z.string()).optional(),
-  bans: z.array(z.object({
-    pattern: z.string(),
-    message: z.string(),
-  })).optional(),
-  compoundChildren: z.record(z.string(), z.object({
-    required: z.boolean().optional(),
-    accepts: z.array(z.string()).optional(),
-    description: z.string().optional(),
-  })).optional(),
+  bans: z
+    .array(
+      z.object({
+        pattern: z.string(),
+        message: z.string(),
+      })
+    )
+    .optional(),
+  compoundChildren: z
+    .record(
+      z.string(),
+      z.object({
+        required: z.boolean().optional(),
+        accepts: z.array(z.string()).optional(),
+        description: z.string().optional(),
+      })
+    )
+    .optional(),
   canonicalUsage: z.array(z.string()).optional(),
-  performanceBudget: z.number().optional(),
+  performanceBudget: z.number().positive().finite().optional(),
 });
 
 const contractAiSchema = z.object({
-  compositionPattern: z.enum(['compound', 'simple', 'controlled', 'wrapper']).optional(),
+  compositionPattern: z.enum(["compound", "simple", "controlled", "wrapper"]).optional(),
   subComponents: z.array(z.string()).optional(),
   requiredChildren: z.array(z.string()).optional(),
   commonPatterns: z.array(z.string()).optional(),
@@ -194,24 +227,29 @@ const contractPreviewSchema = z.object({
   wrapperModule: z.string().optional(),
   wrapperExport: z.string().optional(),
   css: z.array(z.string()).optional(),
-  theme: z.enum(['light', 'dark']).optional(),
+  theme: z.enum(["light", "dark"]).optional(),
 });
 
 const contractProvenanceSchema = z.object({
-  source: z.enum(['manual', 'extracted', 'merged', 'migrated']),
+  source: z.enum(["manual", "extracted", "merged", "migrated"]),
   verified: z.boolean(),
-  frameworkSupport: z.enum(['native', 'manual-only']).optional(),
+  frameworkSupport: z.enum(["native", "manual-only"]).optional(),
   sourceHash: z.string().optional(),
   extractedAt: z.string().optional(),
 });
 
 const contractFigmaSchema = z.object({
   nodeUrl: z.string().optional(),
-  propMappings: z.record(z.string(), z.object({
-    type: z.enum(['string', 'boolean', 'enum', 'instance', 'children', 'textContent']),
-    figmaProperty: z.string(),
-    values: z.record(z.string(), z.string()).optional(),
-  })).optional(),
+  propMappings: z
+    .record(
+      z.string(),
+      z.object({
+        type: z.enum(["string", "boolean", "enum", "instance", "children", "textContent"]),
+        figmaProperty: z.string(),
+        values: z.record(z.string(), z.string()).optional(),
+      })
+    )
+    .optional(),
 });
 
 export const componentContractSchema = z.object({
@@ -220,13 +258,17 @@ export const componentContractSchema = z.object({
   description: z.string(),
   category: z.string(),
   tags: z.array(z.string()).optional(),
-  status: z.enum(['stable', 'beta', 'deprecated', 'experimental']).optional(),
-  framework: z.enum(['react', 'vue', 'svelte', 'web-components', 'angular']).optional(),
-  dependencies: z.array(z.object({
-    name: z.string(),
-    version: z.string(),
-    reason: z.string().optional(),
-  })).optional(),
+  status: z.enum(["stable", "beta", "deprecated", "experimental"]).optional(),
+  framework: z.enum(["react", "vue", "svelte", "web-components", "angular"]).optional(),
+  dependencies: z
+    .array(
+      z.object({
+        name: z.string(),
+        version: z.string(),
+        reason: z.string().optional(),
+      })
+    )
+    .optional(),
   sourcePath: z.string(),
   exportName: z.string(),
   propsSummary: z.array(z.string()),

package/src/composition.ts

@@ -1,4 +1,5 @@
-import type { CompiledFragment, RelationshipType } from "./types.js";
+import type { CompiledFragment } from "./compiled-types/index.js";
+import type { RelationshipType } from "./types.js";
 import type { ComponentGraph } from "./graph/index.js";
 import { ComponentGraphEngine } from "./graph/index.js";
 
@@ -50,6 +51,7 @@ export interface CompositionAnalysis {
 
 const CATEGORY_AFFINITIES: Record<string, string[]> = {
   forms: ["feedback"],
+  inputs: ["feedback"],
   actions: ["feedback"],
 };
 
@@ -69,7 +71,7 @@ export function analyzeComposition(
   fragments: Record<string, CompiledFragment>,
   componentNames: string[],
   _context?: string,
-  options?: { graph?: ComponentGraph },
+  options?: { graph?: ComponentGraph }
 ): CompositionAnalysis {
   const allNames = new Set(Object.keys(fragments));
 
@@ -193,9 +195,7 @@ export function analyzeComposition(
   }
 
   // 5. Category gap analysis
-  const selectedCategories = new Set(
-    components.map((name) => fragments[name].meta.category)
-  );
+  const selectedCategories = new Set(components.map((name) => fragments[name].meta.category));
 
   for (const [category, affinities] of Object.entries(CATEGORY_AFFINITIES)) {
     if (!selectedCategories.has(category)) continue;
@@ -215,9 +215,7 @@ export function analyzeComposition(
           component: candidate,
           reason: `Compositions using "${category}" components often benefit from a "${neededCategory}" component`,
           relationship: "category_gap",
-          sourceComponent: components.find(
-            (n) => fragments[n].meta.category === category
-          )!,
+          sourceComponent: components.find((n) => fragments[n].meta.category === category)!,
         });
         suggestedSet.add(candidate);
       }
@@ -263,11 +261,7 @@ export function analyzeComposition(
           .map((e) => (e.source === name ? e.target : e.source));
 
         for (const comp of blockComps) {
-          if (
-            !selectedSet.has(comp) &&
-            !suggestedSet.has(comp) &&
-            allNames.has(comp)
-          ) {
+          if (!selectedSet.has(comp) && !suggestedSet.has(comp) && allNames.has(comp)) {
             suggestions.push({
               component: comp,
               reason: `"${name}" and "${comp}" are used together in the "${blockName}" block`,

package/src/constants.ts

@@ -15,9 +15,6 @@ export const BRAND = {
   /** 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",
 
@@ -72,13 +69,13 @@ export const BRAND = {
   /** 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;
 
+/** Public schema URL for `.fragment` v3 definition bodies. */
+export const FRAGMENT_V3_SCHEMA_URL = "https://usefragments.com/schemas/fragment.v3.json" as const;
+
 export type Brand = typeof BRAND;
 
 /**

package/src/contract/hash.test.ts

@@ -61,6 +61,26 @@ describe("canonicalPreimage", () => {
       '{"xs":[1,{"y":"q","z":true}]}'
     );
   });
+
+  it("rejects circular and runtime-only values with deterministic paths", () => {
+    const circular: Record<string, unknown> = {};
+    circular.self = circular;
+
+    expect(() => canonicalPreimage(circular)).toThrow("Circular contract value at (root).self");
+    expect(() => canonicalPreimage({ nested: () => null })).toThrow(
+      "Unsupported contract value at (root).nested: function"
+    );
+    expect(() => canonicalPreimage({ createdAt: new Date(0) })).toThrow(
+      "Unsupported contract object at (root).createdAt: Date"
+    );
+  });
+
+  it("permits a shared acyclic object without treating it as a cycle", () => {
+    const shared = { value: 1 };
+    expect(canonicalPreimage({ left: shared, right: shared })).toBe(
+      '{"left":{"value":1},"right":{"value":1}}'
+    );
+  });
 });
 
 describe("contractHash", () => {

package/src/contract/hash.ts

@@ -30,8 +30,8 @@
  * 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.
+ * preimage. Non-finite numbers get legacy v1 sentinels instead; `-0` collapses
+ * to `0`.
  */
 function normalizeNumber(value: number): string {
   if (Number.isNaN(value)) return '"@num:nan"';
@@ -48,29 +48,72 @@ function normalizeNumber(value: number): string {
  * - `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)
+ * - circular, executable, and non-plain runtime values rejected with a stable path
  *
  * 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 {
+  return canonicalPreimageValue(value, new Set<object>(), "(root)");
+}
+
+/**
+ * Locale-independent lexical order for authority-bearing canonical records.
+ *
+ * `String#localeCompare` follows the runtime's default locale, so it can order
+ * the same Unicode identifiers differently across a developer machine, CI,
+ * and a browser. Relational string comparison is defined by ECMAScript over
+ * UTF-16 code units and therefore gives every runtime the same ordering.
+ */
+export function compareCanonicalStrings(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function canonicalPreimageValue(value: unknown, ancestors: Set<object>, path: string): 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 (type === "function" || type === "symbol") {
+    throw new TypeError(`Unsupported contract value at ${path}: ${type}`);
+  }
   if (Array.isArray(value)) {
-    return `[${value.map(canonicalPreimage).join(",")}]`;
+    if (ancestors.has(value)) throw new TypeError(`Circular contract value at ${path}`);
+    ancestors.add(value);
+    try {
+      return `[${value
+        .map((entry, index) => canonicalPreimageValue(entry, ancestors, `${path}[${index}]`))
+        .join(",")}]`;
+    } finally {
+      ancestors.delete(value);
+    }
   }
   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";
+    throw new TypeError(`Unsupported contract value at ${path}: ${type}`);
   }
-  const entries = Object.entries(value as Record<string, unknown>)
+  const object = value as object;
+  const prototype = Object.getPrototypeOf(object);
+  if (prototype !== Object.prototype && prototype !== null) {
+    const objectType = prototype?.constructor?.name ?? "unknown";
+    throw new TypeError(`Unsupported contract object at ${path}: ${objectType}`);
+  }
+  if (ancestors.has(object)) throw new TypeError(`Circular contract value at ${path}`);
+  ancestors.add(object);
+  const entries = Object.entries(object 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(",")}}`;
+    .sort(([a], [b]) => compareCanonicalStrings(a, b));
+  try {
+    return `{${entries
+      .map(
+        ([key, entry]) =>
+          `${JSON.stringify(key)}:${canonicalPreimageValue(entry, ancestors, `${path}.${key}`)}`
+      )
+      .join(",")}}`;
+  } finally {
+    ancestors.delete(object);
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -189,7 +232,21 @@ export function sha256Hex(message: string): string {
  * 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.
+ *
+ * Never feed preview modules, story states, guidance, or runtime config into
+ * this function and call the result an FCID — those belong to
+ * {@link artifactContentHash}.
  */
 export function contractHash(body: unknown): string {
   return sha256Hex(canonicalPreimage(body));
 }
+
+/**
+ * Content-address for preview artifacts (`artifactId`): the same deterministic
+ * SHA-256 canonicalization as {@link contractHash}, but a separate named seam so
+ * callers never assign `artifactId` from an FCID (or vice versa). Hash preview
+ * modules, states, guidance/render content, and runtime config here.
+ */
+export function artifactContentHash(body: unknown): string {
+  return sha256Hex(canonicalPreimage(body));
+}