@usefragments/core 1.10.2 → 1.11.0

package/src/preview/validation.ts

@@ -1,4 +1,17 @@
-import type { PreviewArtifactManifest } from "./types";
+import type { Previewability, PreviewArtifactManifest } from "./types";
+
+const PREVIEWABILITY_VALUES = new Set<Previewability>([
+  "ready",
+  "building",
+  "needs-preview-provider",
+  "missing-dependency",
+  "missing-asset",
+  "server-only",
+  "unsupported-framework",
+  "runtime-error",
+  "build-error",
+  "docs-only",
+]);
 
 export interface PreviewArtifactValidationResult {
   ok: boolean;
@@ -96,12 +109,25 @@ function validateComponents(value: unknown, issues: string[]) {
     issues.push("components must be an object");
     return;
   }
+  const normalizedComponentKeys = new Set<string>();
   for (const [key, component] of Object.entries(value)) {
     if (!isRecord(component)) {
       issues.push(`components.${key} must be an object`);
       continue;
     }
-    requireString(component, "componentKey", issues, `components.${key}`);
+    const componentKey = component.componentKey;
+    if (typeof componentKey !== "string" || !componentKey.trim()) {
+      issues.push(`components.${key}.componentKey must be a non-empty string`);
+    } else {
+      if (key !== componentKey) {
+        issues.push(`components.${key}.componentKey must match its components map key`);
+      }
+      const normalizedComponentKey = componentKey.trim();
+      if (normalizedComponentKeys.has(normalizedComponentKey)) {
+        issues.push(`components contains duplicate normalized componentKey ${componentKey}`);
+      }
+      normalizedComponentKeys.add(normalizedComponentKey);
+    }
     requireString(component, "publicRef", issues, `components.${key}`);
     requireString(component, "displayName", issues, `components.${key}`);
     requireString(component, "exportName", issues, `components.${key}`);
@@ -112,17 +138,33 @@ function validateComponents(value: unknown, issues: string[]) {
         `components.${key}.definitionSource must be one of typescript, fragment, manual, synthesized`
       );
     }
+    if (!isPreviewability(component.previewability)) {
+      issues.push(
+        `components.${key}.previewability must be one of ${[...PREVIEWABILITY_VALUES].join(", ")}`
+      );
+    }
     if (!isRecord(component.props)) {
       issues.push(`components.${key}.props must be an object`);
     }
     if (!Array.isArray(component.variants)) {
       issues.push(`components.${key}.variants must be an array`);
     } else {
+      const normalizedVariantIds = new Set<string>();
       component.variants.forEach((variant, index) => {
         if (!isRecord(variant)) {
           issues.push(`components.${key}.variants.${index} must be an object`);
           return;
         }
+        const variantPath = `components.${key}.variants.${index}`;
+        if (typeof variant.id !== "string" || !variant.id.trim()) {
+          issues.push(`${variantPath}.id must be a non-empty string`);
+        } else {
+          const normalizedVariantId = variant.id.trim();
+          if (normalizedVariantIds.has(normalizedVariantId)) {
+            issues.push(`${variantPath}.id must be unique within the component`);
+          }
+          normalizedVariantIds.add(normalizedVariantId);
+        }
         validateDesignReference(
           variant.design,
           issues,
@@ -297,6 +339,10 @@ function isPreviewDefinitionSource(value: unknown): boolean {
   );
 }
 
+function isPreviewability(value: unknown): value is Previewability {
+  return typeof value === "string" && PREVIEWABILITY_VALUES.has(value as Previewability);
+}
+
 function isFiniteNumber(value: unknown): value is number {
   return typeof value === "number" && Number.isFinite(value);
 }

package/src/preview-runtime.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useState, type ReactNode } from "react";
+import { useEffect, useRef, useState, type ReactNode } from "react";
 import type { VariantLoader, VariantRenderOptions } from "./types.js";
 
 /**
@@ -29,17 +29,208 @@ const EMPTY_STATE: PreviewRuntimeState = {
   loadedData: undefined,
 };
 
+const LOADING_STATE: PreviewRuntimeState = {
+  content: null,
+  isLoading: true,
+  error: null,
+  loadedData: undefined,
+};
+
+const LOADED_DATA_COMPARISON_MAX_DEPTH = 32;
+const LOADED_DATA_COMPARISON_MAX_OBJECTS = 1_000;
+const LOADED_DATA_COMPARISON_MAX_PROPERTIES = 4_000;
+
+const LOADED_DATA_COMPARISON_ERROR = new Error(
+  "Preview loadedData could not be compared safely. Pass a stable object reference, or use " +
+    `JSON-like data within ${LOADED_DATA_COMPARISON_MAX_DEPTH} levels, ` +
+    `${LOADED_DATA_COMPARISON_MAX_OBJECTS} objects, and ` +
+    `${LOADED_DATA_COMPARISON_MAX_PROPERTIES} property inspections.`
+);
+
+const LOADED_DATA_COMPARISON_ERROR_STATE: PreviewRuntimeState = {
+  content: null,
+  isLoading: false,
+  error: LOADED_DATA_COMPARISON_ERROR,
+  loadedData: undefined,
+};
+
+interface PreviewRuntimeResolution {
+  variant: PreviewVariantLike | null;
+  loadedData?: Record<string, unknown>;
+  state: PreviewRuntimeState;
+}
+
 function toError(error: unknown): Error {
   return error instanceof Error ? error : new Error(String(error));
 }
 
+type LoadedDataComparison = "equal" | "different" | "indeterminate";
+const NO_PENDING_LOADED_DATA = Symbol("no-pending-loaded-data");
+
+interface LoadedDataComparisonContext {
+  comparedObjects: number;
+  inspectedProperties: number;
+  leftToRight: WeakMap<object, object>;
+  rightToLeft: WeakMap<object, object>;
+}
+
+function isPlainRecord(value: object): value is Record<string, unknown> {
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function compareLoadedDataProperties(
+  left: object,
+  right: object,
+  depth: number,
+  context: LoadedDataComparisonContext
+): LoadedDataComparison {
+  let leftPropertyCount = 0;
+  for (const key in left) {
+    if (context.inspectedProperties >= LOADED_DATA_COMPARISON_MAX_PROPERTIES) {
+      return "indeterminate";
+    }
+    context.inspectedProperties += 1;
+
+    if (!Object.prototype.hasOwnProperty.call(left, key)) continue;
+    leftPropertyCount += 1;
+    if (!Object.prototype.hasOwnProperty.call(right, key)) return "different";
+
+    const leftDescriptor = Object.getOwnPropertyDescriptor(left, key);
+    const rightDescriptor = Object.getOwnPropertyDescriptor(right, key);
+    if (
+      !leftDescriptor ||
+      !rightDescriptor ||
+      !("value" in leftDescriptor) ||
+      !("value" in rightDescriptor)
+    ) {
+      return "indeterminate";
+    }
+
+    const comparison = compareLoadedDataValue(
+      leftDescriptor.value,
+      rightDescriptor.value,
+      depth + 1,
+      context
+    );
+    if (comparison !== "equal") return comparison;
+  }
+
+  let rightPropertyCount = 0;
+  for (const key in right) {
+    if (context.inspectedProperties >= LOADED_DATA_COMPARISON_MAX_PROPERTIES) {
+      return "indeterminate";
+    }
+    context.inspectedProperties += 1;
+    if (Object.prototype.hasOwnProperty.call(right, key)) rightPropertyCount += 1;
+  }
+
+  return leftPropertyCount === rightPropertyCount ? "equal" : "different";
+}
+
+function compareLoadedDataValue(
+  left: unknown,
+  right: unknown,
+  depth: number,
+  context: LoadedDataComparisonContext
+): LoadedDataComparison {
+  if (Object.is(left, right)) return "equal";
+
+  const leftType = typeof left;
+  const rightType = typeof right;
+  if (leftType !== rightType || left === null || right === null) return "different";
+  if (leftType === "function" || leftType === "symbol") return "indeterminate";
+  if (leftType !== "object") return "different";
+
+  const leftObject = left as object;
+  const rightObject = right as object;
+  const pairedRight = context.leftToRight.get(leftObject);
+  const pairedLeft = context.rightToLeft.get(rightObject);
+  if (pairedRight || pairedLeft) {
+    return pairedRight === rightObject && pairedLeft === leftObject ? "equal" : "different";
+  }
+
+  if (depth >= LOADED_DATA_COMPARISON_MAX_DEPTH) return "indeterminate";
+  if (context.comparedObjects >= LOADED_DATA_COMPARISON_MAX_OBJECTS) {
+    return "indeterminate";
+  }
+
+  const leftIsArray = Array.isArray(leftObject);
+  const rightIsArray = Array.isArray(rightObject);
+  if (leftIsArray !== rightIsArray) return "different";
+  if (leftIsArray && (leftObject as unknown[]).length !== (rightObject as unknown[]).length) {
+    return "different";
+  }
+  if (!leftIsArray) {
+    const leftIsPlainRecord = isPlainRecord(leftObject);
+    const rightIsPlainRecord = isPlainRecord(rightObject);
+    if (leftIsPlainRecord !== rightIsPlainRecord) return "different";
+    if (!leftIsPlainRecord) return "indeterminate";
+  }
+
+  context.comparedObjects += 1;
+  context.leftToRight.set(leftObject, rightObject);
+  context.rightToLeft.set(rightObject, leftObject);
+
+  return compareLoadedDataProperties(leftObject, rightObject, depth, context);
+}
+
+function compareLoadedData(
+  left: Record<string, unknown> | undefined,
+  right: Record<string, unknown> | undefined
+): LoadedDataComparison {
+  try {
+    return compareLoadedDataValue(left, right, 0, {
+      comparedObjects: 0,
+      inspectedProperties: 0,
+      leftToRight: new WeakMap(),
+      rightToLeft: new WeakMap(),
+    });
+  } catch {
+    // Host data must not make render fail when an accessor or proxy cannot be inspected safely.
+    return "indeterminate";
+  }
+}
+
+interface StableLoadedDataResult {
+  loadedData: Record<string, unknown> | undefined;
+  comparisonError: Error | null;
+}
+
+function useStableLoadedData(
+  loadedData: Record<string, unknown> | undefined
+): StableLoadedDataResult {
+  const stableLoadedData = useRef(loadedData);
+  const pendingLoadedData = useRef<
+    Record<string, unknown> | undefined | typeof NO_PENDING_LOADED_DATA
+  >(NO_PENDING_LOADED_DATA);
+  const comparison = compareLoadedData(stableLoadedData.current, loadedData);
+
+  if (comparison === "equal") {
+    pendingLoadedData.current = NO_PENDING_LOADED_DATA;
+    return { loadedData: stableLoadedData.current, comparisonError: null };
+  }
+
+  if (comparison === "different" || pendingLoadedData.current === loadedData) {
+    stableLoadedData.current = loadedData;
+    pendingLoadedData.current = NO_PENDING_LOADED_DATA;
+    return { loadedData, comparisonError: null };
+  }
+
+  pendingLoadedData.current = loadedData;
+  return {
+    loadedData: stableLoadedData.current,
+    comparisonError: LOADED_DATA_COMPARISON_ERROR,
+  };
+}
+
 /**
  * Execute all variant loaders and merge their payloads.
  * `loadedData` is applied last so host-level overrides win.
  */
 export async function executeVariantLoaders(
   loaders: VariantLoader[] | undefined,
-  loadedData?: Record<string, unknown>,
+  loadedData?: Record<string, unknown>
 ): Promise<Record<string, unknown> | undefined> {
   const hasLoaders = !!loaders && loaders.length > 0;
   if (!hasLoaders) {
@@ -49,7 +240,7 @@ export async function executeVariantLoaders(
   const results = await Promise.all(loaders.map((loader) => loader()));
   const mergedFromLoaders = results.reduce<Record<string, unknown>>(
     (acc, result) => ({ ...acc, ...result }),
-    {},
+    {}
   );
 
   return loadedData ? { ...mergedFromLoaders, ...loadedData } : mergedFromLoaders;
@@ -60,7 +251,7 @@ export async function executeVariantLoaders(
  * This is useful for testing and for hook/component orchestration.
  */
 export async function resolvePreviewRuntimeState(
-  options: PreviewRuntimeOptions,
+  options: PreviewRuntimeOptions
 ): Promise<PreviewRuntimeState> {
   const { variant, loadedData } = options;
   if (!variant) {
@@ -89,42 +280,58 @@ export async function resolvePreviewRuntimeState(
 /**
  * Hook for rendering a preview variant with loader support.
  */
-export function usePreviewVariantRuntime(
-  options: PreviewRuntimeOptions,
-): PreviewRuntimeState {
-  const { variant, loadedData } = options;
-  const [state, setState] = useState<PreviewRuntimeState>(EMPTY_STATE);
+export function usePreviewVariantRuntime(options: PreviewRuntimeOptions): PreviewRuntimeState {
+  const { variant } = options;
+  const { loadedData, comparisonError } = useStableLoadedData(options.loadedData);
+  const [resolution, setResolution] = useState<PreviewRuntimeResolution>({
+    variant: null,
+    loadedData: undefined,
+    state: EMPTY_STATE,
+  });
 
   useEffect(() => {
     let cancelled = false;
 
     if (!variant) {
-      setState(EMPTY_STATE);
+      setResolution({ variant: null, loadedData, state: EMPTY_STATE });
       return () => {
         cancelled = true;
       };
     }
 
-    const hasLoaders = !!variant.loaders && variant.loaders.length > 0;
-    setState({
-      content: null,
-      isLoading: hasLoaders,
-      error: null,
-      loadedData: undefined,
-    });
+    if (comparisonError) {
+      setResolution({ variant, loadedData, state: LOADED_DATA_COMPARISON_ERROR_STATE });
+      return () => {
+        cancelled = true;
+      };
+    }
+
+    setResolution({ variant, loadedData, state: LOADING_STATE });
 
     resolvePreviewRuntimeState({ variant, loadedData }).then((nextState) => {
       if (!cancelled) {
-        setState(nextState);
+        setResolution({ variant, loadedData, state: nextState });
       }
     });
 
     return () => {
       cancelled = true;
     };
-  }, [variant, loadedData]);
+  }, [variant, loadedData, comparisonError]);
+
+  if (!variant) {
+    return EMPTY_STATE;
+  }
+
+  if (comparisonError) {
+    return LOADED_DATA_COMPARISON_ERROR_STATE;
+  }
+
+  if (resolution.variant !== variant || resolution.loadedData !== loadedData) {
+    return LOADING_STATE;
+  }
 
-  return state;
+  return resolution.state;
 }
 
 interface PreviewVariantRuntimeProps extends PreviewRuntimeOptions {