@usefragments/core 1.10.2 → 2.0.0

package/src/defineFragment.test.ts

@@ -1,10 +1,6 @@
-import { describe, it, expect } from 'vitest';
-import { defineFragment, compileFragment, normalizeToV1 } from './defineFragment.js';
-import type {
-  FragmentDefinition,
-  FragmentDefinitionV2,
-  FragmentVariant,
-} from './types.js';
+import { afterEach, describe, it, expect, vi } from "vitest";
+import { defineBlock, defineFragment, compileFragment, normalizeToV1 } from "./defineFragment.js";
+import type { FragmentDefinition, FragmentDefinitionV2 } from "./types.js";
 
 // ---------------------------------------------------------------------------
 // Helpers — minimal component stubs
@@ -16,28 +12,30 @@ function StubComponent(_props: { children?: string }) {
 
 const renderStub = () => null;
 
+afterEach(() => {
+  vi.unstubAllEnvs();
+});
+
 function makeV1(): FragmentDefinition<{ children?: string }> {
   return {
     component: StubComponent,
-    meta: { name: 'Stub', description: 'A stub', category: 'test', status: 'stable' },
+    meta: { name: "Stub", description: "A stub", category: "test", status: "stable" },
     usage: {
-      when: ['Testing v1'],
-      whenNot: ['Production'],
+      when: ["Testing v1"],
+      whenNot: ["Production"],
     },
     props: {
-      children: { type: 'node', description: 'Content', required: false },
+      children: { type: "node", description: "Content", required: false },
     },
-    variants: [
-      { name: 'Default', description: 'Default variant', render: renderStub },
-    ],
+    variants: [{ name: "Default", description: "Default variant", render: renderStub }],
     ai: {
-      compositionPattern: 'simple',
+      compositionPattern: "simple",
     },
     contract: {
-      propsSummary: ['children: node'],
+      propsSummary: ["children: node"],
     },
     _generated: {
-      source: 'manual',
+      source: "manual",
       confidence: 1,
     },
   };
@@ -46,31 +44,29 @@ function makeV1(): FragmentDefinition<{ children?: string }> {
 function makeV2(): FragmentDefinitionV2<{ children?: string }> {
   return {
     component: StubComponent,
-    meta: { name: 'Stub', description: 'A stub', category: 'test', status: 'stable' },
+    meta: { name: "Stub", description: "A stub", category: "test", status: "stable" },
     guidance: {
-      when: ['Testing v2'],
-      whenNot: ['Production'],
+      when: ["Testing v2"],
+      whenNot: ["Production"],
     },
     props: {
-      children: { type: 'node', description: 'Content', required: false },
+      children: { type: "node", description: "Content", required: false },
     },
-    examples: [
-      { name: 'Default', description: 'Default example', render: renderStub },
-    ],
+    examples: [{ name: "Default", description: "Default example", render: renderStub }],
     composition: {
-      pattern: 'compound',
-      subComponents: ['Header', 'Body'],
-      requiredChildren: ['Body'],
-      commonPatterns: ['<Stub><Stub.Header /><Stub.Body /></Stub>'],
+      pattern: "compound",
+      subComponents: ["Header", "Body"],
+      requiredChildren: ["Body"],
+      commonPatterns: ["<Stub><Stub.Header /><Stub.Body /></Stub>"],
     },
     contract: {
-      propsSummary: ['children: node'],
+      propsSummary: ["children: node"],
     },
     _provenance: {
-      source: 'scan',
+      source: "scan",
       confidence: 0.85,
-      autoFields: ['props', 'composition'],
-      humanFields: ['guidance', 'examples'],
+      autoFields: ["props", "composition"],
+      humanFields: ["guidance", "examples"],
     },
   };
 }
@@ -79,26 +75,26 @@ function makeV2(): FragmentDefinitionV2<{ children?: string }> {
 // defineFragment — v1 shape
 // ---------------------------------------------------------------------------
 
-describe('defineFragment — v1 shape', () => {
-  it('accepts and returns v1 definition unchanged', () => {
+describe("defineFragment — v1 shape", () => {
+  it("accepts and returns v1 definition unchanged", () => {
     const v1 = makeV1();
     const result = defineFragment(v1);
     expect(result).toBe(v1);
-    expect(result.usage.when).toEqual(['Testing v1']);
-    expect(result.variants[0].name).toBe('Default');
-    expect(result.ai?.compositionPattern).toBe('simple');
+    expect(result.usage.when).toEqual(["Testing v1"]);
+    expect(result.variants[0].name).toBe("Default");
+    expect(result.ai?.compositionPattern).toBe("simple");
   });
 
-  it('throws on invalid v1 definition', () => {
+  it("throws on invalid v1 definition", () => {
     const invalid = {
       component: StubComponent,
-      meta: { name: '', description: 'bad', category: 'test' }, // empty name
+      meta: { name: "", description: "bad", category: "test" }, // empty name
       usage: { when: [], whenNot: [] },
       props: {},
       variants: [],
     } as unknown as FragmentDefinition;
 
-    expect(() => defineFragment(invalid)).toThrow('Invalid fragment definition');
+    expect(() => defineFragment(invalid)).toThrow("Invalid fragment definition");
   });
 });
 
@@ -106,43 +102,43 @@ describe('defineFragment — v1 shape', () => {
 // defineFragment — v2 shape
 // ---------------------------------------------------------------------------
 
-describe('defineFragment — v2 shape', () => {
-  it('accepts and returns v2 definition unchanged', () => {
+describe("defineFragment — v2 shape", () => {
+  it("accepts and returns v2 definition unchanged", () => {
     const v2 = makeV2();
     const result = defineFragment(v2);
     expect(result).toBe(v2);
-    expect((result as FragmentDefinitionV2).guidance.when).toEqual(['Testing v2']);
-    expect((result as FragmentDefinitionV2).examples[0].name).toBe('Default');
-    expect((result as FragmentDefinitionV2).composition?.pattern).toBe('compound');
+    expect((result as FragmentDefinitionV2).guidance.when).toEqual(["Testing v2"]);
+    expect((result as FragmentDefinitionV2).examples[0].name).toBe("Default");
+    expect((result as FragmentDefinitionV2).composition?.pattern).toBe("compound");
   });
 
-  it('validates v2 field names correctly', () => {
+  it("validates v2 field names correctly", () => {
     const v2 = makeV2();
     // Should not throw
     expect(() => defineFragment(v2)).not.toThrow();
   });
 
-  it('throws on invalid v2 definition', () => {
+  it("throws on invalid v2 definition", () => {
     const invalid = {
       component: StubComponent,
-      meta: { name: 'Test', description: 'test', category: 'test' },
-      guidance: { when: 'not-an-array', whenNot: [] }, // wrong type
+      meta: { name: "Test", description: "test", category: "test" },
+      guidance: { when: "not-an-array", whenNot: [] }, // wrong type
       props: {},
       examples: [],
     } as unknown as FragmentDefinitionV2;
 
-    expect(() => defineFragment(invalid)).toThrow('Invalid fragment definition');
+    expect(() => defineFragment(invalid)).toThrow("Invalid fragment definition");
   });
 
-  it('accepts wrapper composition pattern', () => {
+  it("accepts wrapper composition pattern", () => {
     const v2 = makeV2();
-    v2.composition = { pattern: 'wrapper' };
+    v2.composition = { pattern: "wrapper" };
     expect(() => defineFragment(v2)).not.toThrow();
   });
 
-  it('accepts scan provenance source', () => {
+  it("accepts scan provenance source", () => {
     const v2 = makeV2();
-    v2._provenance = { source: 'scan', confidence: 0.9 };
+    v2._provenance = { source: "scan", confidence: 0.9 };
     expect(() => defineFragment(v2)).not.toThrow();
   });
 });
@@ -151,68 +147,73 @@ describe('defineFragment — v2 shape', () => {
 // normalizeToV1
 // ---------------------------------------------------------------------------
 
-describe('normalizeToV1', () => {
-  it('maps guidance → usage', () => {
+describe("normalizeToV1", () => {
+  it("maps guidance → usage", () => {
     const v2 = makeV2();
     const v1 = normalizeToV1(v2);
     expect(v1.usage).toBe(v2.guidance);
-    expect(v1.usage.when).toEqual(['Testing v2']);
+    expect(v1.usage.when).toEqual(["Testing v2"]);
   });
 
-  it('maps examples → variants', () => {
+  it("maps examples → variants", () => {
     const v2 = makeV2();
     const v1 = normalizeToV1(v2);
     expect(v1.variants).toBe(v2.examples);
-    expect(v1.variants[0].name).toBe('Default');
+    expect(v1.variants[0].name).toBe("Default");
   });
 
-  it('maps composition → ai', () => {
+  it("maps composition → ai", () => {
     const v2 = makeV2();
     const v1 = normalizeToV1(v2);
     expect(v1.ai).toEqual({
-      compositionPattern: 'compound',
-      subComponents: ['Header', 'Body'],
-      requiredChildren: ['Body'],
-      commonPatterns: ['<Stub><Stub.Header /><Stub.Body /></Stub>'],
+      compositionPattern: "compound",
+      subComponents: ["Header", "Body"],
+      requiredChildren: ["Body"],
+      commonPatterns: ["<Stub><Stub.Header /><Stub.Body /></Stub>"],
     });
   });
 
-  it('maps _provenance → _generated (narrows scan → ai)', () => {
+  it("maps _provenance → _generated without rewriting scan provenance", () => {
     const v2 = makeV2();
     const v1 = normalizeToV1(v2);
     expect(v1._generated).toEqual({
-      source: 'ai', // scan → ai (v1 doesn't have scan)
+      source: "scan",
       sourceFile: undefined,
       confidence: 0.85,
       timestamp: undefined,
     });
   });
 
-  it('preserves storybook source as-is', () => {
+  it("preserves storybook source as-is", () => {
     const v2 = makeV2();
-    v2._provenance = { source: 'storybook', sourceFile: 'Button.stories.tsx' };
+    v2._provenance = {
+      source: "storybook",
+      sourceFile: "Button.stories.tsx",
+      verified: true,
+    };
     const v1 = normalizeToV1(v2);
-    expect(v1._generated!.source).toBe('storybook');
-    expect(v1._generated!.sourceFile).toBe('Button.stories.tsx');
+    expect(v1._generated!.source).toBe("storybook");
+    expect(v1._generated!.sourceFile).toBe("Button.stories.tsx");
+    expect(v1._generated!.verified).toBe(true);
   });
 
-  it('handles undefined composition gracefully', () => {
+  it("handles undefined composition gracefully", () => {
     const v2 = makeV2();
     v2.composition = undefined;
     const v1 = normalizeToV1(v2);
     expect(v1.ai).toBeUndefined();
   });
 
-  it('handles undefined _provenance gracefully', () => {
+  it("handles undefined _provenance gracefully", () => {
     const v2 = makeV2();
     v2._provenance = undefined;
     const v1 = normalizeToV1(v2);
     expect(v1._generated).toBeUndefined();
   });
 
-  it('preserves contract and relations', () => {
+  it("preserves contract and relations", () => {
     const v2 = makeV2();
-    v2.relations = [{ component: 'Other', relationship: 'sibling', note: 'test' }];
+    v2.relations = [{ component: "Other", relationship: "sibling", note: "test" }];
     const v1 = normalizeToV1(v2);
     expect(v1.contract).toBe(v2.contract);
     expect(v1.relations).toBe(v2.relations);
@@ -223,35 +224,419 @@ describe('normalizeToV1', () => {
 // compileFragment — v2 support
 // ---------------------------------------------------------------------------
 
-describe('compileFragment — v2 support', () => {
-  it('compiles v1 definition', () => {
+describe("compileFragment — v2 support", () => {
+  it("compiles v1 definition", () => {
     const v1 = makeV1();
-    const compiled = compileFragment(v1, 'test/Stub.fragment.tsx');
-    expect(compiled.meta.name).toBe('Stub');
-    expect(compiled.usage.when).toEqual(['Testing v1']);
-    expect(compiled.variants[0].name).toBe('Default');
-    expect(compiled.ai?.compositionPattern).toBe('simple');
+    const compiled = compileFragment(v1, "test/Stub.fragment.tsx");
+    expect(compiled.meta.name).toBe("Stub");
+    expect(compiled.usage.when).toEqual(["Testing v1"]);
+    expect(compiled.variants[0].name).toBe("Default");
+    expect(compiled.ai?.compositionPattern).toBe("simple");
   });
 
-  it('compiles v2 definition (normalizes to v1 output)', () => {
+  it("compiles v2 definition (normalizes to v1 output)", () => {
     const v2 = makeV2();
-    const compiled = compileFragment(v2, 'test/Stub.fragment.tsx');
-    expect(compiled.meta.name).toBe('Stub');
-    expect(compiled.usage.when).toEqual(['Testing v2']);
-    expect(compiled.variants[0].name).toBe('Default');
-    expect(compiled.ai?.compositionPattern).toBe('compound');
-    expect(compiled.ai?.subComponents).toEqual(['Header', 'Body']);
-    expect(compiled._generated?.source).toBe('ai'); // scan normalized to ai
+    const compiled = compileFragment(v2, "test/Stub.fragment.tsx");
+    expect(compiled.meta.name).toBe("Stub");
+    expect(compiled.usage.when).toEqual(["Testing v2"]);
+    expect(compiled.variants[0].name).toBe("Default");
+    expect(compiled.ai?.compositionPattern).toBe("compound");
+    expect(compiled.ai?.subComponents).toEqual(["Header", "Body"]);
+    expect(compiled._generated?.source).toBe("scan");
   });
 
-  it('compiles v2 without optional fields', () => {
+  it("compiles v2 without optional fields", () => {
     const v2 = makeV2();
     v2.composition = undefined;
     v2._provenance = undefined;
     v2.contract = undefined;
-    const compiled = compileFragment(v2, 'test/Stub.fragment.tsx');
+    const compiled = compileFragment(v2, "test/Stub.fragment.tsx");
     expect(compiled.ai).toBeUndefined();
     expect(compiled._generated).toBeUndefined();
     expect(compiled.contract).toBeUndefined();
   });
+
+  it("maps governed composition metadata to compiled ai metadata", () => {
+    const compiled = compileFragment(
+      {
+        component: StubComponent,
+        meta: { name: "Stub", description: "A stub", category: "test" },
+        guidance: { when: ["Testing"], whenNot: [] },
+        composition: {
+          pattern: "compound",
+          subComponents: ["Header", "Body"],
+          requiredChildren: ["Body"],
+          commonPatterns: ["<Stub><Stub.Body /></Stub>"],
+        },
+        _provenance: { source: "scan" },
+        governance: [],
+      },
+      "test/Stub.fragment.ts"
+    );
+
+    expect(compiled.ai).toEqual({
+      compositionPattern: "compound",
+      subComponents: ["Header", "Body"],
+      requiredChildren: ["Body"],
+      commonPatterns: ["<Stub><Stub.Body /></Stub>"],
+    });
+    expect(compiled._generated?.source).toBe("scan");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// defineFragment — v3 arity discrimination (A06-01..A06-03)
+// ---------------------------------------------------------------------------
+
+describe("defineFragment — v3 two-argument arity", () => {
+  type ButtonProps = {
+    variant?: "primary" | "secondary";
+    children?: string;
+  };
+
+  function Button(_props: ButtonProps) {
+    return null;
+  }
+
+  it("returns a bound fragment definition from two arguments (A06-01)", () => {
+    const result = defineFragment(Button, {
+      meta: {
+        name: "Button",
+        purpose: "Primary page action",
+        category: "forms",
+        aliases: ["cta"],
+      },
+      states: {
+        primary: {
+          render: null,
+          canonical: true,
+        },
+      },
+      guidance: {
+        when: ["Confirming a form"],
+        whenNot: ["Navigation"],
+        dont: [
+          {
+            reason: "Raw styling bypasses the contract",
+            bad: '<button style={{ background: "#3b82f6" }}>Save</button>',
+            good: null,
+          },
+        ],
+      },
+      matrix: {
+        axes: { variant: "auto", theme: ["light", "dark"] },
+        forced: ["hover", "disabled"],
+      },
+      preview: { providers: [], dynamicRegions: [] },
+      design: { figmaNode: "https://figma.com/file/x" },
+      annotations: { notes: ["pilot"] },
+      props: {
+        variant: { description: "Visual style", visibility: "public" },
+      },
+    });
+
+    expect(result.component).toBe(Button);
+    expect(result.meta.purpose).toBe("Primary page action");
+    expect(result.states.primary.canonical).toBe(true);
+    expect(result.guidance.dont?.[0]?.reason).toContain("Raw styling");
+  });
+
+  it("type-checks real component props on annotations (A06-01)", () => {
+    const result = defineFragment(Button, {
+      meta: { name: "Button", purpose: "Action", category: "forms" },
+      states: { primary: { render: () => null } },
+      guidance: { when: [], whenNot: [] },
+      props: {
+        variant: { description: "Visual style" },
+        // @ts-expect-error unknown prop is not on ButtonProps
+        madeUp: { description: "nope" },
+      },
+    });
+    expect(result.props?.variant?.description).toBe("Visual style");
+  });
+
+  it("preserves one-argument v2 behavior (A06-01)", () => {
+    const v2 = makeV2();
+    const result = defineFragment(v2);
+    expect(result).toBe(v2);
+  });
+
+  it("does not misclassify plain v2 as governed (A06-02)", () => {
+    const v2 = makeV2();
+    const result = defineFragment(v2);
+    expect("governance" in result).toBe(false);
+    expect((result as FragmentDefinitionV2).guidance.when).toEqual(["Testing v2"]);
+  });
+
+  it("keeps governed-without-govern (governance array only) as governed (A06-02)", () => {
+    const result = defineFragment({
+      component: StubComponent,
+      meta: { name: "Stub", description: "A stub", category: "test" },
+      guidance: { when: ["Testing"], whenNot: [] },
+      governance: [],
+    });
+    expect(result.governance).toEqual([]);
+  });
+
+  it("rejects an optional-key impostor with neither govern nor governance (A06-02)", () => {
+    const compileOnlyInvalidDefinition = () => {
+      // @ts-expect-error governed definitions require govern or governance
+      defineFragment({
+        component: StubComponent,
+        meta: { name: "Stub", description: "A stub", category: "test" },
+        guidance: { when: ["Testing"], whenNot: [] },
+      });
+    };
+    expect(compileOnlyInvalidDefinition).toBeTypeOf("function");
+
+    expect(() =>
+      defineFragment({
+        component: StubComponent,
+        meta: { name: "Stub", description: "A stub", category: "test" },
+        guidance: { when: ["Testing"], whenNot: [] },
+        govern: undefined,
+      } as never)
+    ).toThrow(/props|examples|govern/);
+  });
+
+  it.each([
+    ["v1 govern", makeV1(), "govern", "not-a-function"],
+    ["v1 governance", makeV1(), "governance", { kind: "capability" }],
+    ["v2 govern", makeV2(), "govern", "not-a-function"],
+    ["v2 governance", makeV2(), "governance", { kind: "capability" }],
+  ])(
+    "rejects malformed reserved governance values on an otherwise-valid %s",
+    (_name, body, key, value) => {
+      expect(() => defineFragment({ ...body, [key]: value } as never)).toThrow(
+        /Invalid fragment definition.*govern/s
+      );
+    }
+  );
+
+  it("rejects authored code: strings on states (A06-03)", () => {
+    expect(() =>
+      defineFragment(Button, {
+        meta: { name: "Button", purpose: "Action", category: "forms" },
+        states: {
+          primary: {
+            render: null,
+            // @ts-expect-error code is forbidden on v3 states
+            code: "<Button>Save</Button>",
+          },
+        },
+        guidance: { when: [], whenNot: [] },
+      } as never)
+    ).toThrow(/code/);
+  });
+
+  it("rejects prop annotations that redefine extracted type/default (A06-03)", () => {
+    expect(() =>
+      defineFragment(Button, {
+        meta: { name: "Button", purpose: "Action", category: "forms" },
+        states: { primary: { render: null } },
+        guidance: { when: [], whenNot: [] },
+        props: {
+          variant: {
+            description: "Visual style",
+            type: "enum",
+            default: "primary",
+          } as never,
+        },
+      })
+    ).toThrow(/Unrecognized key|redefine|type|default/);
+  });
+
+  it("resolves govern on the two-argument path", () => {
+    const result = defineFragment(Button, {
+      meta: { name: "Button", purpose: "Action", category: "forms" },
+      states: { primary: { render: null } },
+      guidance: { when: [], whenNot: [] },
+      govern: (g) => [g.capability("submit-action")],
+    });
+    expect(result.governance).toEqual([{ kind: "capability", capability: "submit-action" }]);
+  });
+});
+
+describe("defineFragment — production v3 runtime boundary", () => {
+  type RescueButtonProps = {
+    variant?: "primary" | "secondary";
+  };
+
+  function RescueButton(_props: RescueButtonProps) {
+    return null;
+  }
+
+  const validBody = () => ({
+    meta: { name: "RescueButton", purpose: "Action", category: "forms" },
+    states: { primary: { render: null } },
+    guidance: { when: ["Submitting"], whenNot: [] },
+  });
+
+  it("rejects authored state code in production (A06A-01)", () => {
+    vi.stubEnv("NODE_ENV", "production");
+
+    expect(() =>
+      defineFragment(RescueButton, {
+        ...validBody(),
+        states: {
+          primary: {
+            render: null,
+            code: "<RescueButton />",
+          },
+        },
+      } as never)
+    ).toThrow(/states\.primary.*code/s);
+  });
+
+  it.each([
+    ["undefined", undefined],
+    ["null", null],
+  ])("rejects a malformed v3 body (%s) with the coded validation error", (_label, body) => {
+    vi.stubEnv("NODE_ENV", "production");
+
+    expect(() => defineFragment(RescueButton, body as never)).toThrow(
+      /Invalid fragment definition/
+    );
+  });
+
+  it.each([
+    ["undefined", undefined],
+    ["null", null],
+    ["number", 1],
+    ["string", "invalid"],
+    ["boolean", true],
+  ])(
+    "rejects a non-object one-argument definition (%s) with the coded validation error",
+    (_label, value) => {
+      vi.stubEnv("NODE_ENV", "production");
+
+      expect(() => defineFragment(value as never)).toThrow(/Invalid fragment definition/);
+    }
+  );
+
+  it.each([
+    ["type", { type: "enum" }],
+    ["default", { default: "primary" }],
+  ])("rejects authored prop %s truth in production (A06A-02)", (_field, truth) => {
+    vi.stubEnv("NODE_ENV", "production");
+
+    expect(() =>
+      defineFragment(RescueButton, {
+        ...validBody(),
+        props: {
+          variant: { description: "Visual style", ...truth },
+        },
+      } as never)
+    ).toThrow(/props\.variant|Unrecognized key|type|default/);
+  });
+
+  it.each([
+    ["non-function govern", { govern: "not-a-function" }],
+    ["non-array governance", { governance: { kind: "capability" } }],
+    ["malformed governance record", { governance: [{ kind: "capability", capability: "" }] }],
+  ])("rejects %s in production (A06A-03)", (_case, invalidGovernance) => {
+    vi.stubEnv("NODE_ENV", "production");
+
+    expect(() =>
+      defineFragment(RescueButton, {
+        ...validBody(),
+        ...invalidGovernance,
+      } as never)
+    ).toThrow(/govern|capability/);
+  });
+
+  it("returns a valid governed definition and preserves v1/v2 in production (A06A-04)", () => {
+    vi.stubEnv("NODE_ENV", "production");
+
+    const result = defineFragment(RescueButton, {
+      ...validBody(),
+      govern: (g) => [g.capability("submit-action")],
+    });
+
+    expect(result).not.toBe(RescueButton);
+    expect(result.component).toBe(RescueButton);
+    expect(result.governance).toEqual([{ kind: "capability", capability: "submit-action" }]);
+    expect(defineFragment(makeV1())).toEqual(makeV1());
+    expect(defineFragment(makeV2())).toEqual(makeV2());
+  });
+
+  it.each([
+    [
+      "v1",
+      {
+        ...makeV1(),
+        meta: { ...makeV1().meta, name: "" },
+      },
+    ],
+    [
+      "v2",
+      {
+        ...makeV2(),
+        guidance: { when: "not-an-array", whenNot: [] },
+      },
+    ],
+  ])("rejects an invalid %s definition in production", (_api, definition) => {
+    vi.stubEnv("NODE_ENV", "production");
+
+    expect(() => defineFragment(definition as never)).toThrow(/Invalid fragment definition/);
+  });
+
+  it("rejects invalid blocks in production", () => {
+    vi.stubEnv("NODE_ENV", "production");
+
+    expect(() =>
+      defineBlock({
+        name: "",
+        description: "",
+        category: "",
+        components: [],
+        code: "",
+      })
+    ).toThrow(/Invalid block definition/);
+  });
+
+  it("orders validation issues deterministically", () => {
+    vi.stubEnv("NODE_ENV", "production");
+
+    let thrown: unknown;
+    try {
+      defineFragment({
+        ...makeV1(),
+        meta: { name: "", description: "", category: "" },
+      });
+    } catch (error) {
+      thrown = error;
+    }
+
+    expect((thrown as { issues: string[] }).issues).toEqual([
+      "meta.category: String must contain at least 1 character(s)",
+      "meta.description: String must contain at least 1 character(s)",
+      "meta.name: String must contain at least 1 character(s)",
+    ]);
+  });
+});
+
+describe("defineFragment — compiler validation hand-off", () => {
+  it("marks authoring validation errors without conflating arbitrary runtime failures", () => {
+    let thrown: unknown;
+    try {
+      defineFragment(StubComponent, {
+        meta: { name: "Stub", purpose: "Test", category: "test" },
+        states: { primary: { render: null, code: "<Stub />" } },
+        guidance: { when: [], whenNot: [] },
+      } as never);
+    } catch (error) {
+      thrown = error;
+    }
+
+    expect(thrown).toMatchObject({
+      name: "InvalidFragmentDefinitionError",
+      code: "FUI9010",
+      source: "@usefragments/core/defineFragment",
+      api: "v3",
+    });
+    expect((thrown as { issues: string[] }).issues).toEqual(
+      expect.arrayContaining([expect.stringMatching(/states\.primary.*code/s)])
+    );
+  });
 });