@usefragments/core 1.0.0

package/dist/package-identity.d.ts

@@ -0,0 +1,42 @@
+declare const OWNED_PACKAGE_IDENTITY_SOURCE_SHA256: "e1777bd86647150762a454d021343627fc8d4ef73067c9bf5e61095866635baf";
+
+type OwnedPackageStatus = "retained" | "moved" | "retired";
+interface OwnedPackageIdentityResolution {
+    readonly input: string;
+    readonly owned: boolean;
+    readonly identityId?: string;
+    readonly status?: OwnedPackageStatus;
+    /** Supported public read target. Absent for retired identities. */
+    readonly canonicalSpecifier?: string;
+    /** What first-party generators write in the active authoring epoch. */
+    readonly authoringSpecifier?: string;
+    /** Permanent legacy spelling used only inside the fcid-preimage:v1 domain. */
+    readonly v1Specifier: string;
+    /** Supported public spellings for this exact logical read identity. */
+    readonly readEquivalents?: readonly string[];
+}
+/**
+ * Resolve only exact Fragments-owned npm roots/subpaths. Unknown packages and
+ * arbitrary strings are intentionally opaque; this is not a substring rewrite.
+ */
+declare function resolveOwnedPackageImport(specifier: string): OwnedPackageIdentityResolution;
+/**
+ * Canonical current-read spelling. Retired/unknown identities are returned
+ * unchanged so a caller cannot accidentally expose a private @repo/* target.
+ */
+declare function canonicalizeOwnedImport(specifier: string): string;
+/** Active-epoch spelling for generators; retired/unknown inputs stay unchanged. */
+declare function authorOwnedImport(specifier: string): string;
+/**
+ * Permanent compatibility encoder for fcid-preimage:v1 only. Never use this
+ * result for source edits, suggestions, provenance, or generated guidance.
+ */
+declare function projectV1OwnedImportIdentity(specifier: string): string;
+declare function ownedImportEquivalents(specifier: string): readonly string[];
+declare function canonicalizeOwnedComponentId(value: string): string;
+/** fcid-preimage:v1 component-id compatibility; subject to the same restriction. */
+declare function projectV1OwnedComponentId(value: string): string;
+/** Exposed for diagnostics and generator tests, not as a second policy owner. */
+declare const OWNED_PACKAGE_IDENTITY_EPOCH: "current";
+
+export { OWNED_PACKAGE_IDENTITY_EPOCH, OWNED_PACKAGE_IDENTITY_SOURCE_SHA256, type OwnedPackageIdentityResolution, type OwnedPackageStatus, authorOwnedImport, canonicalizeOwnedComponentId, canonicalizeOwnedImport, ownedImportEquivalents, projectV1OwnedComponentId, projectV1OwnedImportIdentity, resolveOwnedPackageImport };

package/dist/package-identity.js

@@ -0,0 +1,23 @@
+import {
+  OWNED_PACKAGE_IDENTITY_EPOCH,
+  OWNED_PACKAGE_IDENTITY_SOURCE_SHA256,
+  authorOwnedImport,
+  canonicalizeOwnedComponentId,
+  canonicalizeOwnedImport,
+  ownedImportEquivalents,
+  projectV1OwnedComponentId,
+  projectV1OwnedImportIdentity,
+  resolveOwnedPackageImport
+} from "./chunk-JNBFJ34I.js";
+export {
+  OWNED_PACKAGE_IDENTITY_EPOCH,
+  OWNED_PACKAGE_IDENTITY_SOURCE_SHA256,
+  authorOwnedImport,
+  canonicalizeOwnedComponentId,
+  canonicalizeOwnedImport,
+  ownedImportEquivalents,
+  projectV1OwnedComponentId,
+  projectV1OwnedImportIdentity,
+  resolveOwnedPackageImport
+};
+//# sourceMappingURL=package-identity.js.map

package/dist/package-identity.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/preview/index.d.ts

@@ -0,0 +1,484 @@
+type JsonPrimitive = string | number | boolean | null;
+type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+type Previewability = "ready" | "building" | "needs-preview-provider" | "missing-dependency" | "missing-asset" | "server-only" | "unsupported-framework" | "runtime-error" | "build-error" | "docs-only";
+type PreviewDefinitionSource = "typescript" | "fragment" | "manual" | "synthesized";
+/**
+ * Seed provenance of a Specimen state (Slice 4). Distinct from
+ * `PreviewDefinitionSource` (how the variant def was authored): this records
+ * which evidence stream the state came from, in confidence order — a real
+ * Storybook story (`csf`), an observed call-site (`usage`), a fragment variant
+ * (`fragment`), or a synthesized enum-gap filler (`synthesized`).
+ */
+type SpecimenStateSource = "csf" | "usage" | "fragment" | "synthesized";
+type PreviewComponentTier = "primitive" | "provider-backed" | "app-context" | "server-bound";
+interface PreviewArtifactIdentity {
+    artifactId: string;
+    artifactVersion: "preview-artifact/v1";
+    orgId: string;
+    projectId: string;
+    bindingId: string;
+    repoFullName: string;
+    commitSha: string;
+    sourceRef: string;
+    packageName?: string;
+    packagePath?: string;
+    lockfileHash?: string;
+    configHash?: string;
+    createdAt: string;
+}
+interface PreviewArtifactBuilder {
+    name: string;
+    version: string;
+    configFile?: string;
+    typecheck: "typescript" | "none";
+    sources: PreviewDefinitionSource[];
+    adapters: string[];
+}
+interface PreviewArtifactManifest {
+    artifactVersion: "preview-artifact/v1";
+    identity: PreviewArtifactIdentity;
+    builder: PreviewArtifactBuilder;
+    runtime: {
+        framework: "react";
+        reactVersion?: string;
+        moduleFormat: "esm";
+        entry: string;
+        css: string[];
+        assetsBaseUrl: string;
+    };
+    capabilities: PreviewArtifactCapabilities;
+    components: Record<string, PreviewComponentDefinition>;
+    diagnostics: PreviewDiagnostic[];
+    /**
+     * The component-contract FCID (`contractHash`) this specimen was derived
+     * against (Slice 4). Lets ingest pin each state row to its `contractVersions`
+     * row so a served state names the same contract identity CI enforces.
+     */
+    derivedFromContractHash?: string;
+}
+interface PreviewArtifactCapabilities {
+    supportsThemes: boolean;
+    supportsViewports: boolean;
+    supportsActions: boolean;
+    supportsSlots: boolean;
+    supportsA11yScan: boolean;
+    supportsPlayFunctions: boolean;
+    supportsSceneNodes: boolean;
+}
+interface PreviewDesignReference {
+    provider: "figma";
+    label?: string;
+    nodeUrl?: string;
+    fileKey?: string;
+    nodeId?: string;
+    imageUrl?: string;
+    size?: {
+        width: number;
+        height: number;
+    };
+    /**
+     * Optional comparison evidence produced by a preview capture pipeline.
+     *
+     * The preview package stores and scores this evidence, but does not own
+     * browser rendering, Figma API calls, or pixel-diff execution. Node
+     * consumers such as the CLI can populate these fields from Playwright,
+     * Figma, and pixelmatch; UI consumers can render the same report shape.
+     */
+    comparison?: PreviewDesignComparisonReference;
+}
+interface PreviewDesignComparisonReference {
+    /**
+     * Preview state that produced this stored evidence. Consumers can still show
+     * the linked design for other states, but should only score stored image and
+     * style evidence when the active preview state matches this context.
+     */
+    state?: PreviewDesignComparisonState;
+    previewImageUrl?: string;
+    previewSize?: {
+        width: number;
+        height: number;
+    };
+    designStyles?: Record<string, string>;
+    previewStyles?: Record<string, string>;
+    diffImageUrl?: string;
+    diffPercentage?: number;
+    diffPixelCount?: number;
+    totalPixels?: number;
+    changedRegions?: Array<{
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }>;
+    capturedAt?: string;
+}
+interface PreviewDesignComparisonState {
+    variantId?: string;
+    theme?: string;
+    viewport?: PreviewViewport;
+}
+interface PreviewComponentDefinition {
+    componentKey: string;
+    publicRef: string;
+    displayName: string;
+    sourcePath?: string;
+    exportName: string;
+    importPath: string;
+    tier: PreviewComponentTier;
+    previewability: Previewability;
+    definitionSource: PreviewDefinitionSource;
+    diagnostics: PreviewDiagnostic[];
+    props: Record<string, PreviewPropDefinition>;
+    variants: PreviewVariantDefinition[];
+    defaultVariantId?: string;
+    requiredProviders?: PreviewProviderRequirement[];
+    canvas?: PreviewCanvasMetadata;
+    design?: PreviewDesignReference;
+}
+interface PreviewProviderRequirement {
+    id: string;
+    label: string;
+    optional?: boolean;
+}
+interface PreviewCanvasMetadata {
+    defaultWidth?: number;
+    defaultHeight?: number;
+    supportsChildren?: boolean;
+}
+interface PreviewPropDefinition {
+    name: string;
+    type: string;
+    required: boolean;
+    defaultValue?: JsonValue;
+    source: PreviewDefinitionSource;
+    control: {
+        type: "text";
+    } | {
+        type: "number";
+        min?: number;
+        max?: number;
+        step?: number;
+    } | {
+        type: "boolean";
+    } | {
+        type: "select";
+        options: Array<string | number | boolean>;
+    } | {
+        type: "color";
+    } | {
+        type: "slot";
+        presets: PreviewSlotPreset[];
+    } | {
+        type: "action";
+    } | {
+        type: "unsupported";
+        reason: string;
+    };
+    description?: string;
+}
+interface PreviewVariantDefinition {
+    id: string;
+    name: string;
+    description?: string;
+    source: PreviewDefinitionSource;
+    props: Record<string, JsonValue>;
+    slots?: Record<string, PreviewSlotValue>;
+    tags?: string[];
+    /** Seed provenance of this state (Slice 4); pinned alongside the FCID. */
+    stateSource?: SpecimenStateSource;
+    /** Confidence of the seed, 0..1 (csf high → synthesized low). */
+    confidence?: number;
+    design?: PreviewDesignReference;
+}
+type PreviewSlotValue = {
+    kind: "text";
+    value: string;
+} | {
+    kind: "html";
+    value: string;
+} | {
+    kind: "component";
+    node: ComponentInstanceNode;
+};
+interface PreviewSlotPreset {
+    id: string;
+    label: string;
+    value: PreviewSlotValue;
+}
+type ComponentCanvasNode = ComponentInstanceNode | FrameNode | TextNode;
+interface ComponentInstanceNode {
+    kind: "component-instance";
+    nodeId: string;
+    componentKey: string;
+    variantId?: string;
+    props: Record<string, JsonValue>;
+    slots: Record<string, ComponentCanvasNode[]>;
+    layout: LayoutConstraints;
+    styleOverrides?: ComponentStyleOverrides;
+}
+interface FrameNode {
+    kind: "frame";
+    nodeId: string;
+    children: string[];
+    layout: LayoutConstraints;
+    style?: {
+        background?: string;
+        padding?: number | string;
+        gap?: number | string;
+    };
+}
+interface TextNode {
+    kind: "text";
+    nodeId: string;
+    text: string;
+    layout: LayoutConstraints;
+}
+interface LayoutConstraints {
+    position?: "auto" | "absolute";
+    width?: "hug" | "fill" | number;
+    height?: "hug" | "fill" | number;
+    minWidth?: number;
+    minHeight?: number;
+    x?: number;
+    y?: number;
+}
+interface ComponentStyleOverrides {
+    className?: string;
+    style?: Record<string, JsonValue>;
+}
+interface PreviewViewport {
+    width: number;
+    height: number;
+    background?: string;
+}
+interface RenderPreviewArgs {
+    action: (name: string, payload?: JsonValue[]) => void;
+    component: PreviewComponentDefinition;
+    componentKey: string;
+    manifest: PreviewArtifactManifest;
+    props: Record<string, JsonValue>;
+    root: HTMLElement;
+    slots: Record<string, PreviewSlotValue>;
+    theme?: string;
+    variantId?: string;
+    viewport?: PreviewViewport;
+}
+type PreviewCleanup = void | (() => void) | {
+    cleanup: () => void;
+};
+type RenderPreview = (args: RenderPreviewArgs) => PreviewCleanup | Promise<PreviewCleanup>;
+interface PreviewDiagnostic {
+    code: "missing-dependency" | "missing-peer-dependency" | "unresolved-import" | "unsupported-server-component" | "node-only-import" | "missing-env" | "missing-provider" | "missing-asset" | "css-build-failed" | "runtime-error" | "render-timeout" | "unsupported-prop-control";
+    severity: "info" | "warning" | "error";
+    message: string;
+    componentKey?: string;
+    sourcePath?: string;
+    importPath?: string;
+    suggestedFix?: string;
+    docsHref?: string;
+}
+
+type PreviewComparisonSourceKind = "figma" | "preview";
+type PreviewComparisonStatus = "pass" | "review" | "fail" | "incomplete";
+type PreviewComparisonSeverity = "info" | "warning" | "error";
+interface PreviewComparisonSize {
+    width: number;
+    height: number;
+}
+interface PreviewComparisonBounds extends PreviewComparisonSize {
+    x: number;
+    y: number;
+}
+type PreviewComparisonStyleMap = Record<string, string | undefined>;
+interface PreviewComparisonSource {
+    kind: PreviewComparisonSourceKind;
+    label: string;
+    imageDataUrl?: string;
+    imageUrl?: string;
+    size?: PreviewComparisonSize;
+    styles?: PreviewComparisonStyleMap;
+    capturedAt?: string;
+}
+interface FigmaDesignComparisonSource extends PreviewComparisonSource {
+    kind: "figma";
+    fileKey?: string;
+    nodeId?: string;
+    nodeUrl?: string;
+}
+interface RenderedPreviewComparisonSource extends PreviewComparisonSource {
+    kind: "preview";
+    componentKey: string;
+    variantId?: string;
+    theme?: string;
+    viewport?: PreviewViewport;
+}
+interface PreviewComparisonThresholds {
+    imageDiffPercentage: number;
+    dimensionPx: number;
+    numericPx: number;
+    colorChannel: number;
+    alpha: number;
+}
+interface PreviewImageDiffInput {
+    diffPercentage: number;
+    changedRegions?: PreviewComparisonBounds[];
+    diffImageDataUrl?: string;
+    diffImageUrl?: string;
+    diffPixelCount?: number;
+    totalPixels?: number;
+}
+interface PreviewComparisonInput {
+    design: FigmaDesignComparisonSource;
+    preview: RenderedPreviewComparisonSource;
+    imageDiff?: PreviewImageDiffInput;
+    thresholds?: Partial<PreviewComparisonThresholds>;
+    findings?: PreviewComparisonFinding[];
+    context?: PreviewComparisonContext;
+}
+interface BuildPreviewComparisonReportInput {
+    component: PreviewComponentDefinition;
+    variantId?: string;
+    designReference?: PreviewDesignReference;
+    designReferenceScope?: "component" | "variant";
+    preview?: Partial<Omit<RenderedPreviewComparisonSource, "kind" | "componentKey">> & {
+        componentKey?: string;
+    };
+    imageDiff?: PreviewImageDiffInput;
+    thresholds?: Partial<PreviewComparisonThresholds>;
+}
+interface PreviewStyleComparisonItem {
+    property: string;
+    design: string;
+    preview: string;
+    match: boolean;
+}
+interface PreviewComparisonFinding {
+    code: "image-diff-threshold-exceeded" | "dimension-mismatch" | "style-mismatch" | "missing-comparison-signal" | "invalid-comparison-signal" | "stale-comparison-signal";
+    severity: PreviewComparisonSeverity;
+    message: string;
+    bounds?: PreviewComparisonBounds;
+    property?: string;
+    designValue?: string;
+    previewValue?: string;
+}
+type PreviewComparisonReferenceScope = "component" | "variant";
+type PreviewComparisonContextMismatch = "variant" | "theme" | "viewport";
+interface PreviewComparisonContext {
+    scope: PreviewComparisonReferenceScope;
+    captured?: PreviewDesignComparisonState;
+    active: PreviewDesignComparisonState;
+    stale: boolean;
+    staleReasons: PreviewComparisonContextMismatch[];
+}
+interface PreviewComparisonReport {
+    status: PreviewComparisonStatus;
+    score: number | null;
+    summary: string;
+    design: FigmaDesignComparisonSource;
+    preview: RenderedPreviewComparisonSource;
+    thresholds: PreviewComparisonThresholds;
+    image?: {
+        match: boolean;
+        diffPercentage: number;
+        diffImageDataUrl?: string;
+        diffImageUrl?: string;
+        changedRegions: PreviewComparisonBounds[];
+        diffPixelCount?: number;
+        totalPixels?: number;
+    };
+    dimensions?: {
+        match: boolean;
+        design: PreviewComparisonSize;
+        preview: PreviewComparisonSize;
+        delta: PreviewComparisonSize;
+    };
+    styles?: {
+        match: boolean;
+        properties: PreviewStyleComparisonItem[];
+    };
+    findings: PreviewComparisonFinding[];
+    context?: PreviewComparisonContext;
+}
+type PreviewComparisonSignalId = "image" | "dimensions" | "styles";
+type PreviewComparisonSignalStatus = "pass" | "review" | "fail" | "missing";
+interface PreviewComparisonSignal {
+    id: PreviewComparisonSignalId;
+    label: string;
+    status: PreviewComparisonSignalStatus;
+    value: string;
+    detail: string;
+}
+interface PreviewComparisonContextSummary {
+    status: "current" | "stale";
+    label: string;
+    value: string;
+    detail: string;
+}
+interface PreviewComparisonRegionOverlay extends PreviewComparisonBounds {
+    label: string;
+    leftPercent: number;
+    topPercent: number;
+    widthPercent: number;
+    heightPercent: number;
+}
+declare function comparePreviewToDesign(input: PreviewComparisonInput): PreviewComparisonReport;
+declare function resolvePreviewComparisonThresholds(thresholds?: Partial<PreviewComparisonThresholds> | null): PreviewComparisonThresholds;
+declare function buildPreviewComparisonReport(input: BuildPreviewComparisonReportInput): PreviewComparisonReport | null;
+declare function buildPreviewDesignComparisonEvidence(report: PreviewComparisonReport): PreviewDesignComparisonReference | null;
+declare function buildPreviewDesignReferenceFromReport(report: PreviewComparisonReport): PreviewDesignReference;
+
+interface PreviewComparisonArtifactAssetPaths {
+    rendered?: string;
+    figma?: string;
+    diff?: string;
+}
+interface PreviewComparisonArtifactTarget {
+    componentKey: string;
+    variantId?: string;
+    designReferenceScope: PreviewComparisonReferenceScope;
+}
+interface BuildPreviewComparisonArtifactPayloadInput {
+    report?: PreviewComparisonReport;
+    designReference?: PreviewDesignReference;
+    comparisonEvidence?: PreviewDesignComparisonReference;
+    assets?: PreviewComparisonArtifactAssetPaths;
+}
+interface PreviewComparisonArtifactPayload {
+    target: PreviewComparisonArtifactTarget;
+    report: PreviewComparisonReport;
+    designReference: PreviewDesignReference;
+    comparisonEvidence?: PreviewDesignComparisonReference;
+}
+type ApplyPreviewComparisonArtifactStatus = "applied" | "component-not-found" | "variant-not-found" | "missing-comparison-evidence";
+interface ApplyPreviewComparisonArtifactPayloadResult {
+    status: ApplyPreviewComparisonArtifactStatus;
+    applied: boolean;
+    manifest: PreviewArtifactManifest;
+    message: string;
+}
+declare function buildPreviewComparisonArtifactPayload(input: BuildPreviewComparisonArtifactPayloadInput): PreviewComparisonArtifactPayload | null;
+declare function applyPreviewComparisonArtifactPayload(manifest: PreviewArtifactManifest, payload: PreviewComparisonArtifactPayload): ApplyPreviewComparisonArtifactPayloadResult;
+
+declare function getPreviewComparisonSignals(report: PreviewComparisonReport): PreviewComparisonSignal[];
+declare function getPreviewComparisonRegionOverlays(report: PreviewComparisonReport): PreviewComparisonRegionOverlay[];
+declare function getPreviewComparisonContextSummary(report: PreviewComparisonReport): PreviewComparisonContextSummary | null;
+declare function formatPreviewComparisonFinding(finding: PreviewComparisonFinding): string;
+
+declare function parseFigmaNodeUrl(url: string): {
+    fileKey: string;
+    nodeId: string;
+} | null;
+declare function getPreviewDesignReference(component: PreviewComponentDefinition, variantId?: string): PreviewDesignReference | undefined;
+declare function buildFigmaDesignSource(reference: PreviewDesignReference, fallbackLabel: string): FigmaDesignComparisonSource;
+
+interface PreviewArtifactValidationResult {
+    ok: boolean;
+    issues: string[];
+}
+declare function definePreviewArtifactManifest(manifest: PreviewArtifactManifest): PreviewArtifactManifest;
+declare function validatePreviewArtifactManifest(value: unknown): PreviewArtifactValidationResult;
+declare function isPreviewArtifactManifest(value: unknown): value is PreviewArtifactManifest;
+
+export { type ApplyPreviewComparisonArtifactPayloadResult, type ApplyPreviewComparisonArtifactStatus, type BuildPreviewComparisonArtifactPayloadInput, type BuildPreviewComparisonReportInput, type ComponentCanvasNode, type ComponentInstanceNode, type ComponentStyleOverrides, type FigmaDesignComparisonSource, type FrameNode, type JsonPrimitive, type JsonValue, type LayoutConstraints, type PreviewArtifactBuilder, type PreviewArtifactCapabilities, type PreviewArtifactIdentity, type PreviewArtifactManifest, type PreviewArtifactValidationResult, type PreviewCanvasMetadata, type PreviewCleanup, type PreviewComparisonArtifactAssetPaths, type PreviewComparisonArtifactPayload, type PreviewComparisonArtifactTarget, type PreviewComparisonBounds, type PreviewComparisonContext, type PreviewComparisonContextMismatch, type PreviewComparisonContextSummary, type PreviewComparisonFinding, type PreviewComparisonInput, type PreviewComparisonReferenceScope, type PreviewComparisonRegionOverlay, type PreviewComparisonReport, type PreviewComparisonSeverity, type PreviewComparisonSignal, type PreviewComparisonSignalId, type PreviewComparisonSignalStatus, type PreviewComparisonSize, type PreviewComparisonSource, type PreviewComparisonSourceKind, type PreviewComparisonStatus, type PreviewComparisonStyleMap, type PreviewComparisonThresholds, type PreviewComponentDefinition, type PreviewComponentTier, type PreviewDefinitionSource, type PreviewDesignComparisonReference, type PreviewDesignComparisonState, type PreviewDesignReference, type PreviewDiagnostic, type PreviewImageDiffInput, type PreviewPropDefinition, type PreviewProviderRequirement, type PreviewSlotPreset, type PreviewSlotValue, type PreviewStyleComparisonItem, type PreviewVariantDefinition, type PreviewViewport, type Previewability, type RenderPreview, type RenderPreviewArgs, type RenderedPreviewComparisonSource, type SpecimenStateSource, type TextNode, applyPreviewComparisonArtifactPayload, buildFigmaDesignSource, buildPreviewComparisonArtifactPayload, buildPreviewComparisonReport, buildPreviewDesignComparisonEvidence, buildPreviewDesignReferenceFromReport, comparePreviewToDesign, definePreviewArtifactManifest, formatPreviewComparisonFinding, getPreviewComparisonContextSummary, getPreviewComparisonRegionOverlays, getPreviewComparisonSignals, getPreviewDesignReference, isPreviewArtifactManifest, parseFigmaNodeUrl, resolvePreviewComparisonThresholds, validatePreviewArtifactManifest };