@usefragments/core 1.10.2 → 2.0.0

package/src/__tests__/preview-runtime-hook.test.tsx

@@ -0,0 +1,315 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { usePreviewVariantRuntime } from "../preview-runtime.js";
+
+const hookHarness = vi.hoisted(() => ({
+  cursor: 0,
+  renderRequested: false,
+  pendingEffects: [] as Array<() => void>,
+  slots: [] as Array<
+    | { kind: "state"; value: unknown }
+    | { kind: "ref"; value: { current: unknown } }
+    | {
+        kind: "effect";
+        cleanup?: () => void;
+        deps?: readonly unknown[];
+      }
+  >,
+  updates: [] as Array<{
+    state?: { content: unknown; isLoading: boolean; error: unknown };
+  }>,
+}));
+
+vi.mock("react", async () => {
+  const actual = await vi.importActual<typeof import("react")>("react");
+  return {
+    ...actual,
+    useEffect: (effect: () => void | (() => void), deps?: readonly unknown[]) => {
+      const slotIndex = hookHarness.cursor++;
+      const prior = hookHarness.slots[slotIndex];
+      const dependenciesChanged =
+        prior?.kind !== "effect" ||
+        deps === undefined ||
+        prior.deps === undefined ||
+        deps.length !== prior.deps.length ||
+        deps.some((dependency, index) => !Object.is(dependency, prior.deps?.[index]));
+
+      if (!dependenciesChanged) return;
+
+      hookHarness.pendingEffects.push(() => {
+        if (prior?.kind === "effect") prior.cleanup?.();
+        const cleanup = effect();
+        hookHarness.slots[slotIndex] = {
+          kind: "effect",
+          ...(typeof cleanup === "function" ? { cleanup } : {}),
+          deps,
+        };
+      });
+    },
+    useRef: <T,>(initial: T) => {
+      const slotIndex = hookHarness.cursor++;
+      const prior = hookHarness.slots[slotIndex];
+      if (prior?.kind === "ref") return prior.value;
+
+      const value = { current: initial };
+      hookHarness.slots[slotIndex] = { kind: "ref", value };
+      return value;
+    },
+    useState: <T,>(initial: T) => {
+      const slotIndex = hookHarness.cursor++;
+      const prior = hookHarness.slots[slotIndex];
+      if (prior?.kind !== "state") {
+        hookHarness.slots[slotIndex] = { kind: "state", value: initial };
+      }
+
+      return [
+        (hookHarness.slots[slotIndex] as { kind: "state"; value: T }).value,
+        (next: T | ((current: T) => T)) => {
+          const current = (hookHarness.slots[slotIndex] as { kind: "state"; value: T }).value;
+          const value = typeof next === "function" ? (next as (current: T) => T)(current) : next;
+          (hookHarness.slots[slotIndex] as { kind: "state"; value: T }).value = value;
+          hookHarness.renderRequested = true;
+          hookHarness.updates.push(
+            value as {
+              state?: { content: unknown; isLoading: boolean; error: unknown };
+            }
+          );
+        },
+      ];
+    },
+  };
+});
+
+function renderHook<T>(render: () => T): T {
+  hookHarness.cursor = 0;
+  hookHarness.renderRequested = false;
+  const result = render();
+  const effects = hookHarness.pendingEffects.splice(0);
+  for (const effect of effects) effect();
+  return result;
+}
+
+async function flushResolution(): Promise<void> {
+  await Promise.resolve();
+  await Promise.resolve();
+}
+
+async function settleHook<T>(render: () => T, maxRenders = 8): Promise<T> {
+  let result = renderHook(render);
+  for (
+    let renderCount = 0;
+    renderCount < maxRenders && hookHarness.renderRequested;
+    renderCount++
+  ) {
+    await flushResolution();
+    result = renderHook(render);
+  }
+  return result;
+}
+
+function makeWideLoadedData(version: string): Record<string, unknown> {
+  return {
+    version,
+    items: Array.from({ length: 1_005 }, (_, index) => ({ index })),
+  };
+}
+
+function makeDeepLoadedData(depth: number, label = "leaf"): Record<string, unknown> {
+  let node: Record<string, unknown> = { label };
+  for (let index = 0; index < depth; index++) {
+    node = { next: node };
+  }
+  return { node };
+}
+
+function readDeepLabel(loadedData: Record<string, unknown> | undefined): unknown {
+  let node = loadedData?.node as Record<string, unknown> | undefined;
+  while (node && "next" in node) {
+    node = node.next as Record<string, unknown> | undefined;
+  }
+  return node?.label;
+}
+
+function expectLoadedDataComparisonError(state: ReturnType<typeof usePreviewVariantRuntime>): void {
+  expect(state.content).toBeNull();
+  expect(state.isLoading).toBe(false);
+  expect(state.loadedData).toBeUndefined();
+  expect(state.error).toBeInstanceOf(Error);
+  expect(state.error?.message).toContain("stable object reference");
+}
+
+describe("usePreviewVariantRuntime", () => {
+  beforeEach(() => {
+    hookHarness.cursor = 0;
+    hookHarness.renderRequested = false;
+    hookHarness.pendingEffects.length = 0;
+    hookHarness.slots.length = 0;
+    hookHarness.updates.length = 0;
+  });
+
+  it("enters loading state while resolving a variant without loaders", async () => {
+    const variant = { render: () => null };
+    const initialState = renderHook(() => usePreviewVariantRuntime({ variant }));
+
+    expect(initialState).toMatchObject({
+      content: null,
+      isLoading: true,
+      error: null,
+    });
+
+    expect(hookHarness.updates[0]).toMatchObject({
+      state: {
+        content: null,
+        isLoading: true,
+        error: null,
+      },
+    });
+
+    await flushResolution();
+    const settledState = renderHook(() => usePreviewVariantRuntime({ variant }));
+
+    expect(settledState).toMatchObject({
+      content: null,
+      isLoading: false,
+      error: null,
+    });
+  });
+
+  it("settles when callers recreate equivalent inline loadedData", async () => {
+    const variant = {
+      render: (options?: { loadedData?: Record<string, unknown> }) =>
+        (options?.loadedData?.user as { profile?: { label?: string } } | undefined)?.profile?.label,
+    };
+
+    const state = await settleHook(() =>
+      usePreviewVariantRuntime({
+        variant,
+        loadedData: { user: { profile: { label: "from-host" } } },
+      })
+    );
+
+    expect(state).toEqual({
+      content: "from-host",
+      isLoading: false,
+      error: null,
+      loadedData: { user: { profile: { label: "from-host" } } },
+    });
+    expect(hookHarness.renderRequested).toBe(false);
+  });
+
+  it("re-resolves when a nested inline loadedData value changes", async () => {
+    const variant = {
+      render: (options?: { loadedData?: Record<string, unknown> }) =>
+        (options?.loadedData?.user as { label?: string } | undefined)?.label,
+    };
+    let label = "before";
+    const render = () => usePreviewVariantRuntime({ variant, loadedData: { user: { label } } });
+
+    expect(await settleHook(render)).toMatchObject({ content: "before", isLoading: false });
+
+    label = "after";
+    expect(renderHook(render)).toMatchObject({ content: null, isLoading: true });
+    await flushResolution();
+    expect(await settleHook(render)).toMatchObject({ content: "after", isLoading: false });
+  });
+
+  it("compares recreated cyclic loadedData without recursing forever", async () => {
+    const variant = { render: () => "settled" };
+    const render = () => {
+      const node: Record<string, unknown> = { label: "same" };
+      node.self = node;
+      return usePreviewVariantRuntime({ variant, loadedData: { node } });
+    };
+
+    expect(await settleHook(render)).toMatchObject({ content: "settled", isLoading: false });
+    expect(hookHarness.renderRequested).toBe(false);
+  });
+
+  it("fails closed for recreated loadedData above the comparison-count bound", async () => {
+    const stableLoadedData = makeWideLoadedData("same");
+    let recreateLoadedData = false;
+    const variant = {
+      render: (options?: { loadedData?: Record<string, unknown> }) => options?.loadedData?.version,
+    };
+    const render = () =>
+      usePreviewVariantRuntime({
+        variant,
+        loadedData: recreateLoadedData ? makeWideLoadedData("same") : stableLoadedData,
+      });
+
+    expect(await settleHook(render)).toMatchObject({ content: "same", isLoading: false });
+
+    recreateLoadedData = true;
+    expectLoadedDataComparisonError(await settleHook(render));
+    expect(hookHarness.renderRequested).toBe(false);
+  });
+
+  it("fails closed for recreated loadedData above the comparison-depth bound", async () => {
+    const stableLoadedData = makeDeepLoadedData(40);
+    let recreateLoadedData = false;
+    const variant = { render: () => "deep-settled" };
+    const render = () =>
+      usePreviewVariantRuntime({
+        variant,
+        loadedData: recreateLoadedData ? makeDeepLoadedData(40) : stableLoadedData,
+      });
+
+    expect(await settleHook(render)).toMatchObject({ content: "deep-settled", isLoading: false });
+
+    recreateLoadedData = true;
+    expectLoadedDataComparisonError(await settleHook(render));
+    expect(hookHarness.renderRequested).toBe(false);
+  });
+
+  it("fails closed before accepting a stable Date identity change", async () => {
+    const variant = {
+      render: (options?: { loadedData?: Record<string, unknown> }) =>
+        (options?.loadedData?.createdAt as Date | undefined)?.getTime(),
+    };
+    let loadedData = { createdAt: new Date(0) };
+    const render = () => usePreviewVariantRuntime({ variant, loadedData });
+
+    expect(await settleHook(render)).toMatchObject({ content: 0, isLoading: false, error: null });
+
+    loadedData = { createdAt: new Date(1) };
+    expectLoadedDataComparisonError(renderHook(render));
+    expect(await settleHook(render)).toMatchObject({ content: 1, isLoading: false, error: null });
+  });
+
+  it("fails closed before accepting a stable function identity change", async () => {
+    const variant = {
+      render: (options?: { loadedData?: Record<string, unknown> }) =>
+        (options?.loadedData?.getValue as (() => number) | undefined)?.(),
+    };
+    let loadedData = { getValue: () => 1 };
+    const render = () => usePreviewVariantRuntime({ variant, loadedData });
+
+    expect(await settleHook(render)).toMatchObject({ content: 1, isLoading: false, error: null });
+
+    loadedData = { getValue: () => 2 };
+    expectLoadedDataComparisonError(renderHook(render));
+    expect(await settleHook(render)).toMatchObject({ content: 2, isLoading: false, error: null });
+  });
+
+  it("fails closed before accepting a stable deep-leaf change beyond the depth bound", async () => {
+    const variant = {
+      render: (options?: { loadedData?: Record<string, unknown> }) =>
+        readDeepLabel(options?.loadedData),
+    };
+    let loadedData = makeDeepLoadedData(40, "before");
+    const render = () => usePreviewVariantRuntime({ variant, loadedData });
+
+    expect(await settleHook(render)).toMatchObject({
+      content: "before",
+      isLoading: false,
+      error: null,
+    });
+
+    loadedData = makeDeepLoadedData(40, "after");
+    expectLoadedDataComparisonError(renderHook(render));
+    expect(await settleHook(render)).toMatchObject({
+      content: "after",
+      isLoading: false,
+      error: null,
+    });
+  });
+});

package/src/__tests__/preview-runtime.test.tsx

@@ -14,11 +14,8 @@ describe("executeVariantLoaders", () => {
 
   it("merges loader results and applies host loadedData last", async () => {
     const result = await executeVariantLoaders(
-      [
-        async () => ({ count: 1, fromFirst: true }),
-        async () => ({ count: 2, fromSecond: true }),
-      ],
-      { count: 3, fromHost: true },
+      [async () => ({ count: 1, fromFirst: true }), async () => ({ count: 2, fromSecond: true })],
+      { count: 3, fromHost: true }
     );
 
     expect(result).toEqual({
@@ -43,6 +40,21 @@ describe("resolvePreviewRuntimeState", () => {
     expect(state.content).toBe("Preview content");
   });
 
+  it("settles a null render without remaining in a loading state", async () => {
+    const variant: PreviewVariantLike = {
+      render: () => null,
+    };
+
+    const state = await resolvePreviewRuntimeState({ variant });
+
+    expect(state).toEqual({
+      content: null,
+      isLoading: false,
+      error: null,
+      loadedData: undefined,
+    });
+  });
+
   it("renders with successful loaders", async () => {
     const variant: PreviewVariantLike = {
       loaders: [async () => ({ label: "from-loader" })],
@@ -58,7 +70,11 @@ describe("resolvePreviewRuntimeState", () => {
 
   it("returns an error when a loader rejects", async () => {
     const variant: PreviewVariantLike = {
-      loaders: [async () => { throw new Error("loader failed"); }],
+      loaders: [
+        async () => {
+          throw new Error("loader failed");
+        },
+      ],
       render: () => "should not render",
     };
 
@@ -83,7 +99,11 @@ describe("resolvePreviewRuntimeState", () => {
 
   it("normalizes non-Error throwables", async () => {
     const variant: PreviewVariantLike = {
-      loaders: [async () => { throw "string-failure"; }],
+      loaders: [
+        async () => {
+          throw "string-failure";
+        },
+      ],
       render: () => "never",
     };
 
@@ -93,7 +113,9 @@ describe("resolvePreviewRuntimeState", () => {
   });
 
   it("uses host data as override input in render options", async () => {
-    const renderSpy = vi.fn((options?: { loadedData?: Record<string, unknown> }) => options?.loadedData);
+    const renderSpy = vi.fn(
+      (options?: { loadedData?: Record<string, unknown> }) => options?.loadedData
+    );
     const variant: PreviewVariantLike = {
       loaders: [async () => ({ count: 1 })],
       render: renderSpy,

package/src/__tests__/schema.test.ts

@@ -1,31 +1,208 @@
-import { describe, expect, it } from 'vitest';
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import Ajv2020 from "ajv/dist/2020.js";
+import addFormats from "ajv-formats";
+import { describe, expect, it } from "vitest";
 
-import { observedUsagePropSchema } from '../schema.js';
+import {
+  fragmentDefinitionV2Schema,
+  fragmentDefinitionV3BodySchema,
+  fragmentDefinitionV3Schema,
+  fragmentGeneratedSchema,
+  fragmentProvenanceSchema,
+  fragmentsConfigSchema,
+  observedUsagePropSchema,
+  propAnnotationSchema,
+} from "../schema.js";
+import type { FragmentGenerated, FragmentProvenance } from "../types.js";
+import type { FragmentGenerated as CompiledFragmentGenerated } from "../compiled-types/index.js";
 
-describe('observedUsagePropSchema', () => {
-  it('accepts structural JSX children observations', () => {
+const testsDir = dirname(fileURLToPath(import.meta.url));
+const repoRoot = join(testsDir, "../../../..");
+
+const publicV3Schema = JSON.parse(
+  readFileSync(join(repoRoot, "apps/docs/public/schemas/fragment.v3.json"), "utf8")
+) as Record<string, unknown>;
+
+/**
+ * The v3 parity corpus. Owned by Core (A06-04 is the parity owner) and read
+ * verbatim by the compiler's loader test, so "the loader accepts what the
+ * published schema accepts" is one fixture set, not two that can drift. It
+ * lives under `test-fixtures/` because `src/` ships inside the package.
+ */
+const parityFixtures = JSON.parse(
+  readFileSync(join(testsDir, "../../test-fixtures/fragment-v3-parity.json"), "utf8")
+) as {
+  validBody: Record<string, unknown>;
+  validTimestamps: string[];
+  invalidTimestamps: string[];
+  invalidBodies: Array<{ name: string; body: Record<string, unknown> }>;
+};
+
+const publicSchemaValidator = new Ajv2020({ allErrors: true, strict: false });
+addFormats(publicSchemaValidator);
+const validatePublicV3 = publicSchemaValidator.compile(publicV3Schema);
+
+function publicV3Accepts(value: unknown): boolean {
+  return validatePublicV3(value) as boolean;
+}
+
+const scannedAuthoringFragment = { source: "scan" } satisfies FragmentGenerated;
+const scannedCompiledFragment = { source: "scan" } satisfies CompiledFragmentGenerated;
+const verifiedScannedFragment = {
+  source: "scan",
+  verified: true,
+} satisfies FragmentGenerated & CompiledFragmentGenerated;
+const provenanceWithoutVerification = { source: "scan" } satisfies FragmentProvenance;
+
+describe("fragmentGeneratedSchema", () => {
+  it("keeps scan provenance aligned across runtime and public types", () => {
+    expect(fragmentGeneratedSchema.parse(scannedAuthoringFragment).source).toBe("scan");
+    expect(fragmentGeneratedSchema.parse(scannedCompiledFragment).source).toBe("scan");
+  });
+
+  it("preserves verification accepted by both public generated-fragment types", () => {
+    expect(fragmentGeneratedSchema.parse(verifiedScannedFragment)).toEqual({
+      source: "scan",
+      verified: true,
+    });
+  });
+});
+
+describe("fragmentProvenanceSchema", () => {
+  it("keeps verification optional across runtime and public types", () => {
+    expect(fragmentProvenanceSchema.parse(provenanceWithoutVerification)).toEqual({
+      source: "scan",
+    });
+  });
+});
+
+describe("fragmentsConfigSchema", () => {
+  it("does not expose the retired storybook filter option", () => {
+    expect(Object.hasOwn(fragmentsConfigSchema.shape, "storybook")).toBe(false);
+  });
+});
+
+describe("observedUsagePropSchema", () => {
+  it("accepts structural JSX children observations", () => {
     expect(
       observedUsagePropSchema.safeParse({
-        name: 'children',
-        kind: 'jsx',
-      }).success,
+        name: "children",
+        kind: "jsx",
+      }).success
     ).toBe(true);
   });
 
-  it('accepts boolean and null prop observations', () => {
+  it("accepts boolean and null prop observations", () => {
     expect(
       observedUsagePropSchema.safeParse({
-        name: 'disabled',
-        kind: 'boolean',
+        name: "disabled",
+        kind: "boolean",
         value: true,
-      }).success,
+      }).success
     ).toBe(true);
     expect(
       observedUsagePropSchema.safeParse({
-        name: 'tone',
-        kind: 'null',
+        name: "tone",
+        kind: "null",
         value: null,
-      }).success,
+      }).success
     ).toBe(true);
   });
 });
+
+describe("fragmentDefinitionV2Schema", () => {
+  it("accepts migrated provenance with verification fields", () => {
+    const result = fragmentDefinitionV2Schema.safeParse({
+      component: () => null,
+      meta: { name: "Button", description: "A button", category: "actions" },
+      guidance: { when: [], whenNot: [] },
+      props: {},
+      examples: [],
+      _provenance: {
+        source: "migrated",
+        verified: true,
+        frameworkSupport: "native",
+        sourceHash: "abc123",
+      },
+    });
+
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data._provenance).toEqual({
+        source: "migrated",
+        verified: true,
+        frameworkSupport: "native",
+        sourceHash: "abc123",
+      });
+    }
+  });
+});
+
+describe("fragmentDefinitionV3Schema parity with public schema (A06-04)", () => {
+  const { validBody, validTimestamps, invalidTimestamps, invalidBodies } = parityFixtures;
+
+  it("accepts the same valid fixture in Zod and the published schema", () => {
+    expect(fragmentDefinitionV3BodySchema.safeParse(validBody).success).toBe(true);
+    expect(
+      fragmentDefinitionV3Schema.safeParse({
+        ...validBody,
+        component: () => null,
+        governance: [],
+      }).success
+    ).toBe(true);
+    expect(publicV3Accepts(validBody)).toBe(true);
+  });
+
+  it.each(validTimestamps)(
+    "accepts RFC 3339 provenance timestamp %s in Zod and the published schema",
+    (timestamp) => {
+      const withTimestamp = {
+        ...validBody,
+        _provenance: { ...(validBody._provenance as object), timestamp },
+      };
+      expect(fragmentDefinitionV3BodySchema.safeParse(withTimestamp).success).toBe(true);
+      expect(publicV3Accepts(withTimestamp)).toBe(true);
+    }
+  );
+
+  it.each(invalidTimestamps)(
+    "rejects invalid provenance timestamp %s in Zod and the published schema",
+    (timestamp) => {
+      const withTimestamp = {
+        ...validBody,
+        _provenance: { ...(validBody._provenance as object), timestamp },
+      };
+      expect(fragmentDefinitionV3BodySchema.safeParse(withTimestamp).success).toBe(false);
+      expect(publicV3Accepts(withTimestamp)).toBe(false);
+    }
+  );
+
+  it.each(invalidBodies.map(({ name, body }) => [name, body] as const))(
+    "rejects %s in both Zod and the published schema",
+    (_name, invalidBody) => {
+      expect(fragmentDefinitionV3BodySchema.safeParse(invalidBody).success).toBe(false);
+      expect(publicV3Accepts(invalidBody)).toBe(false);
+    }
+  );
+
+  it("rejects prop annotations that redefine type/default at the leaf schema", () => {
+    expect(
+      propAnnotationSchema.safeParse({ description: "x", type: "enum", default: "primary" }).success
+    ).toBe(false);
+  });
+
+  it("keeps callable govern authoring out of the JSON interchange projection", () => {
+    const withGovern = { ...validBody, govern: () => [] };
+    expect(fragmentDefinitionV3BodySchema.safeParse(withGovern).success).toBe(true);
+    expect(publicV3Accepts(withGovern)).toBe(false);
+  });
+
+  it("publishes the versioned schema document with the usefragments $id", () => {
+    expect(publicV3Schema).toMatchObject({
+      $id: "https://usefragments.com/schemas/fragment.v3.json",
+    });
+    expect(publicV3Schema).toHaveProperty("$defs.state.not.required", ["code"]);
+  });
+});