@penpair/core 0.3.6 → 0.4.0

package/dist/design-releases/fidelity.js

@@ -0,0 +1,328 @@
+import { observationHash } from "../journal.js";
+import { inspectImageEvidence } from "../image-evidence.js";
+import { hashBytes } from "./artifact-paths.js";
+const requiredFields = [
+    "geometry",
+    "text",
+    "layout",
+    "component",
+    "tokens",
+    "style",
+    "metadata",
+];
+function object(value, message) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(message);
+    }
+    return value;
+}
+export function nativeTree(inspection) {
+    if (inspection.kind !== "shape-inspection" ||
+        !inspection.complete ||
+        inspection.reasons.length ||
+        !Array.isArray(inspection.nodes) ||
+        !inspection.nodes.length ||
+        inspection.nodes.length > 20000) {
+        throw new Error("Native fidelity requires a complete bounded shape inspection");
+    }
+    const nodes = new Map();
+    for (const node of inspection.nodes) {
+        if (typeof node.id !== "string" ||
+            !node.id ||
+            nodes.has(node.id) ||
+            !Array.isArray(node.childIds) ||
+            !Array.isArray(node.unknowns) ||
+            node.unknowns.length) {
+            throw new Error("Unknown fields or duplicate identities block native fidelity");
+        }
+        for (const key of requiredFields) {
+            if (!Object.hasOwn(node, key)) {
+                throw new Error(`Native inspection is missing required field ${key}`);
+            }
+        }
+        const geometry = object(node.geometry, "Native geometry is unavailable");
+        for (const axis of [
+            "x",
+            "y",
+            "width",
+            "height",
+            "rotation",
+        ]) {
+            if (typeof geometry[axis] !== "number" || !Number.isFinite(geometry[axis])) {
+                throw new Error("Native geometry contains an unobservable or nonfinite field");
+            }
+        }
+        if (Number(geometry.width) < 0 ||
+            Number(geometry.height) < 0 ||
+            typeof geometry.hidden !== "boolean" ||
+            typeof geometry.blocked !== "boolean" ||
+            [
+                "flipX",
+                "flipY",
+                "proportionLock",
+            ].some((key) => typeof geometry[key] !== "boolean")) {
+            throw new Error("Native geometry flags/dimensions are unobservable");
+        }
+        if (![
+            "board",
+            "rect",
+            "rectangle",
+            "ellipse",
+            "text",
+            "path",
+            "group",
+        ].includes(String(node.type))) {
+            throw new Error("Native shape content is unsupported or unobservable");
+        }
+        if (node.type === "path" && (typeof node.content !== "string" || !node.content)) {
+            throw new Error("Native path content fidelity is unobservable in this inspection");
+        }
+        const layout = object(node.layout, "Native layout is unavailable");
+        if (!Object.hasOwn(layout, "showInViewMode") || !Object.hasOwn(layout, "boardSizing")) {
+            throw new Error("Native board behavior observations are missing");
+        }
+        if (node.type === "board") {
+            if (typeof layout.showInViewMode !== "boolean") {
+                throw new Error("Native board viewer visibility is unobservable");
+            }
+            const sizing = object(layout.boardSizing, "Native board sizing is unobservable");
+            for (const key of [
+                "horizontalSizing",
+                "verticalSizing",
+            ]) {
+                if (!Object.hasOwn(sizing, key) ||
+                    ![
+                        null,
+                        "auto",
+                        "fix",
+                    ].includes(sizing[key])) {
+                    throw new Error("Native board sizing is unsupported or unobservable");
+                }
+            }
+        }
+        const constraints = object(layout.constraints, "Native constraints observations are missing");
+        const horizontal = [
+            "center",
+            "left",
+            "right",
+            "leftright",
+            "scale",
+            ...(node.type === "board"
+                ? [
+                    null,
+                ]
+                : []),
+        ];
+        const vertical = [
+            "center",
+            "top",
+            "bottom",
+            "scale",
+            "topbottom",
+            ...(node.type === "board"
+                ? [
+                    null,
+                ]
+                : []),
+        ];
+        if (!Object.hasOwn(constraints, "constraintsHorizontal") ||
+            !Object.hasOwn(constraints, "constraintsVertical") ||
+            !horizontal.includes(constraints.constraintsHorizontal) ||
+            !vertical.includes(constraints.constraintsVertical) ||
+            typeof constraints.fixedWhenScrolling !== "boolean") {
+            throw new Error("Native constraints are unobservable or unsupported");
+        }
+        const style = object(node.style, "Native style is unavailable");
+        if (!Object.hasOwn(style, "blur") || !Object.hasOwn(style, "backgroundBlur")) {
+            throw new Error("Native blur observations are missing");
+        }
+        if (node.type === "text") {
+            const text = object(node.text, "Native text is unavailable");
+            const typography = object(text.typography, "Native typography is unavailable");
+            if (!Object.hasOwn(typography, "textTransform") ||
+                !Object.hasOwn(typography, "textDecoration")) {
+                throw new Error("Native text transform/decoration observations are missing");
+            }
+        }
+        const component = object(node.component, "Component observations are unavailable");
+        if (component.isComponentInstance === true ||
+            component.isComponentCopyInstance === true ||
+            component.isComponentMainInstance === true ||
+            component.isComponentRoot === true) {
+            throw new Error("Component override fidelity is unobservable in this inspection; native release verification is blocked");
+        }
+        if (node.type === "group" && !Object.hasOwn(node, "maskedGroup")) {
+            throw new Error("Mask fidelity is unobservable for this group");
+        }
+        nodes.set(node.id, node);
+    }
+    const roots = inspection.nodes.filter((node) => node.parentId === null);
+    if (roots.length !== 1 || roots[0]?.type !== "board") {
+        throw new Error("A release screen must be one native board root");
+    }
+    const root = roots[0];
+    const ordered = [];
+    const paths = new Map();
+    const visit = (node, currentPath, parentId) => {
+        const id = String(node.id);
+        if (paths.has(id) || node.parentId !== parentId || paths.size >= 20000) {
+            throw new Error("Native hierarchy is cyclic, ambiguous or inconsistent");
+        }
+        paths.set(id, currentPath);
+        ordered.push({
+            path: currentPath,
+            node,
+        });
+        const children = node.childIds;
+        if (node.childrenTotal !== children.length) {
+            throw new Error("Native hierarchy children are incomplete");
+        }
+        children.forEach((childId, index) => {
+            if (typeof childId !== "string" || !nodes.has(childId)) {
+                throw new Error("Native hierarchy has an unknown child");
+            }
+            const child = nodes.get(childId);
+            if (child.index !== index) {
+                throw new Error("Native child order is inconsistent");
+            }
+            visit(child, `${currentPath}/${index}`, id);
+        });
+    };
+    visit(root, "root", null);
+    if (paths.size !== nodes.size) {
+        throw new Error("Native inspection includes detached shapes");
+    }
+    return {
+        root,
+        ordered,
+        paths,
+    };
+}
+function referenceValue(value, paths, remap) {
+    if (typeof value === "string") {
+        const original = remap[value] ?? value;
+        return paths.get(original) ?? original;
+    }
+    if (Array.isArray(value)) {
+        return value.map((entry) => referenceValue(entry, paths, remap));
+    }
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([key, entry]) => [
+            key,
+            referenceValue(entry, paths, remap),
+        ]));
+    }
+    return value;
+}
+export function semanticInspection(inspection, remap = {}) {
+    const tree = nativeTree(inspection);
+    const rootGeometry = object(tree.root.geometry, "Root geometry is unavailable");
+    const paths = new Map([
+        ...tree.paths.entries(),
+    ].map(([id, value]) => [
+        remap[id] ?? id,
+        value,
+    ]));
+    return tree.ordered.map(({ path, node }) => {
+        const geometry = object(node.geometry, "Geometry is unavailable");
+        const relativeGeometry = {
+            ...geometry,
+        };
+        for (const axis of [
+            "x",
+            "y",
+        ]) {
+            if (typeof geometry[axis] !== "number" || typeof rootGeometry[axis] !== "number") {
+                throw new Error("Native geometry must be finite and observable");
+            }
+            relativeGeometry[axis] =
+                Math.round((geometry[axis] - rootGeometry[axis]) * 1e6) / 1e6;
+        }
+        const metadata = object(node.metadata, "Interaction observations unavailable");
+        if (!Object.hasOwn(metadata, "interactions")) {
+            throw new Error("Native interactions are unobservable");
+        }
+        return {
+            path,
+            type: node.type,
+            children: node.childIds.length,
+            geometry: relativeGeometry,
+            text: node.text,
+            layout: node.layout,
+            tokens: node.tokens,
+            style: node.style,
+            maskedGroup: node.maskedGroup ?? null,
+            pathContent: node.type === "path" ? node.content : null,
+            component: referenceValue(node.component, paths, remap),
+            interactions: referenceValue(metadata.interactions, paths, remap),
+        };
+    });
+}
+export function inspectionContentHash(inspection) {
+    return observationHash(semanticInspection(inspection));
+}
+export function deriveNodeMap(source, target) {
+    const before = nativeTree(source);
+    const after = nativeTree(target);
+    if (before.ordered.length !== after.ordered.length) {
+        throw new Error("Native copy changed hierarchy node count");
+    }
+    const entries = before.ordered.map((entry, index) => {
+        const copied = after.ordered[index];
+        if (entry.path !== copied.path ||
+            entry.node.type !== copied.node.type ||
+            entry.node.id === copied.node.id) {
+            throw new Error("Native copy topology/type or independent shape identity differs");
+        }
+        return [
+            String(entry.node.id),
+            String(copied.node.id),
+        ];
+    });
+    return Object.fromEntries(entries);
+}
+export function compareNativeCopy(source, target, fullNodeMap) {
+    deriveNodeMap(source, target);
+    const inverse = Object.fromEntries(Object.entries(fullNodeMap).map(([from, to]) => [
+        to,
+        from,
+    ]));
+    const sourceHash = inspectionContentHash(source);
+    const targetHash = observationHash(semanticInspection(target, inverse));
+    if (sourceHash !== targetHash) {
+        throw new Error("Native copy changed text, hierarchy, layout, geometry, tokens, images, components or interaction references");
+    }
+    return {
+        sourceHash,
+        targetHash,
+    };
+}
+export async function decodedPixels(png) {
+    if (png.length > 64 * 1024 * 1024) {
+        throw new Error("Release render exceeds 64-MiB input budget");
+    }
+    const header = inspectImageEvidence(png);
+    if (header.format !== "png" || header.width * header.height > 64_000_000) {
+        throw new Error("Release fidelity requires bounded PNG evidence");
+    }
+    const { default: sharp } = await import("sharp");
+    const image = sharp(png, {
+        failOn: "error",
+        limitInputPixels: 64_000_000,
+    });
+    const metadata = await image.metadata();
+    if (metadata.depth !== "uchar" || metadata.bitsPerSample === 16 || (metadata.pages ?? 1) !== 1) {
+        throw new Error("Release fidelity requires a static 8-bit render");
+    }
+    const { data, info } = await image.ensureAlpha().raw().toBuffer({
+        resolveWithObject: true,
+    });
+    if (info.width !== header.width || info.height !== header.height || info.channels !== 4) {
+        throw new Error("Decoded render dimensions changed");
+    }
+    return {
+        hash: hashBytes(data),
+        width: info.width,
+        height: info.height,
+    };
+}

package/dist/design-releases/finalize.d.ts

@@ -0,0 +1,4 @@
+import type { PenpotToolClient } from "../client.js";
+import type { ArtifactReview } from "../maps/types.js";
+import type { DesignRelease, ReleaseOptions } from "./types.js";
+export declare function finalizeRelease(client: PenpotToolClient, root: string, raw: DesignRelease, suppliedReview: ArtifactReview | undefined, options?: ReleaseOptions): Promise<DesignRelease>;

package/dist/design-releases/finalize.js

@@ -0,0 +1,201 @@
+import { lstat } from "node:fs/promises";
+import { observationHash, readJournalTarget, runJournaledSteps } from "../journal.js";
+import { validateArtifactReview, findArtifactReview } from "../maps/review.js";
+import { guardRevision } from "../coordination.js";
+import { withPageSession } from "../page-session.js";
+import { runSnippet } from "../snippet.js";
+import { artifactPath, readArtifact, saveArtifact } from "./artifact-paths.js";
+import { checkRelease, releaseReferences } from "./check.js";
+import { observeRelease, releaseClient } from "./live.js";
+import { readReleaseContract, writeDesignRelease, readDesignRelease } from "./store.js";
+import { finalizeReleaseSnippet } from "./snippets.js";
+import { validateDesignRelease, hashDesignRelease } from "./validation.js";
+export async function finalizeRelease(client, root, raw, suppliedReview, options = {}) {
+    const release = validateDesignRelease(raw);
+    if (release.status !== "verified" && release.status !== "final") {
+        throw new Error("Only fully verified design evidence can be finalized");
+    }
+    client = releaseClient(client, release);
+    const checkStart = await readJournalTarget(client);
+    const checked = await checkRelease(client, root, release, options);
+    const checkedTarget = await readJournalTarget(client);
+    if (checkStart.fileId !== checkedTarget.fileId ||
+        checkStart.revision !== checkedTarget.revision) {
+        throw new Error("Release changed during the independent final check");
+    }
+    if (!checked.valid) {
+        throw new Error(`Release finalization is blocked: ${checked.reasons.join("; ")}`);
+    }
+    if (!options.apply || release.status === "final") {
+        return release;
+    }
+    let review = validateArtifactReview(suppliedReview);
+    const designHash = hashDesignRelease(release);
+    if (!findArtifactReview([
+        review,
+    ], "design-release", release.id, designHash)) {
+        throw new Error("Owner review must bind the exact verified release design hash");
+    }
+    client = releaseClient(client, release);
+    return withPageSession(client, async () => {
+        const pointer = options.pointerPath ?? `design/releases/${release.productVersion}/release.json`;
+        const pointerFile = await artifactPath(root, pointer, true);
+        try {
+            await lstat(pointerFile);
+            const existing = await readDesignRelease(root, pointer);
+            if (existing.status === "final") {
+                throw new Error("This product version is already finalized; ordinary writes cannot replace it");
+            }
+            if (existing.id !== release.id || existing.productVersion !== release.productVersion) {
+                throw new Error("Final pointer belongs to another release identity");
+            }
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                throw error;
+            }
+        }
+        const bundlePath = `design/releases/${release.productVersion}/approved/bundle.json`;
+        const bundleFile = await artifactPath(root, bundlePath, true);
+        let storedBundle;
+        try {
+            await lstat(bundleFile);
+            const { readProjectBytes } = await import("../bounded-file.js");
+            storedBundle = JSON.parse((await readProjectBytes(root, bundlePath, 16 * 1024 * 1024)).toString("utf8"));
+            const originalReview = validateArtifactReview(storedBundle.review);
+            if (storedBundle.schemaVersion !== 1 ||
+                storedBundle.kind !== "approved-design-release" ||
+                storedBundle.designHash !== designHash ||
+                hashDesignRelease(storedBundle.release) !== designHash ||
+                originalReview.by !== review.by ||
+                originalReview.note !== review.note ||
+                originalReview.artifactHash !== review.artifactHash ||
+                observationHash(originalReview.artifacts ?? []) !== observationHash(review.artifacts ?? [])) {
+                throw new Error("Product version already has a different immutable design/review bundle");
+            }
+            review = originalReview;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                throw error;
+            }
+        }
+        const references = releaseReferences(release);
+        for (const contract of release.contracts) {
+            const map = await readReleaseContract(root, contract);
+            for (const source of map.sources) {
+                if (source.path) {
+                    references.push({
+                        path: source.path,
+                        sha256: source.sha256,
+                    });
+                }
+            }
+        }
+        for (const artifact of review.artifacts ?? []) {
+            references.push(artifact);
+        }
+        const snapshots = [];
+        for (const original of new Map(references.map((reference) => [
+            `${reference.path}:${reference.sha256}`,
+            reference,
+        ])).values()) {
+            const bytes = await readArtifact(root, original, 64 * 1024 * 1024);
+            const snapshot = await saveArtifact(root, `design/releases/${release.productVersion}/approved/artifacts/${original.sha256}.bin`, bytes, options.redact);
+            snapshots.push({
+                original,
+                snapshot,
+            });
+        }
+        const bundle = storedBundle ?? {
+            schemaVersion: 1,
+            kind: "approved-design-release",
+            designHash,
+            release,
+            review,
+            artifacts: snapshots,
+        };
+        const serialized = `${JSON.stringify(bundle, null, 2)}\n`;
+        if (Buffer.byteLength(serialized) > 16 * 1024 * 1024) {
+            throw new Error("Immutable release bundle exceeds the 16-MiB budget");
+        }
+        const bundleReference = await saveArtifact(root, bundlePath, serialized, options.redact);
+        for (const item of bundle.artifacts) {
+            await readArtifact(root, item.snapshot, 64 * 1024 * 1024);
+        }
+        const final = validateDesignRelease({
+            ...release,
+            status: "final",
+            reviews: [
+                ...release.reviews,
+                review,
+            ],
+            finalized: {
+                bundle: bundleReference,
+                markerHash: bundleReference.sha256,
+                reviewHash: review.hash,
+            },
+        });
+        const offline = await checkRelease(undefined, root, final, options);
+        if (!offline.valid) {
+            throw new Error(`Immutable bundle is invalid; remote marker not written: ${offline.reasons.join("; ")}`);
+        }
+        const before = await observeRelease(client, release);
+        const beforeMarker = await readJournalTarget(client);
+        if (beforeMarker.fileId !== checkedTarget.fileId ||
+            beforeMarker.revision !== checkedTarget.revision) {
+            throw new Error("Release changed while preparing its immutable bundle; marker not written");
+        }
+        const complete = (observation) => Boolean(observation.marker?.status === "released" &&
+            observation.marker.bundleHash === bundleReference.sha256 &&
+            observation.marker.reviewHash === review.hash);
+        if (before.marker?.status === "released" && !complete(before)) {
+            throw new Error("Remote release marker belongs to different immutable evidence");
+        }
+        if (!complete(before)) {
+            await runJournaledSteps([
+                {
+                    key: "released-marker",
+                    label: "Mark independently verified design release",
+                    signature: finalizeReleaseSnippet(release, bundleReference.sha256, review.hash).code,
+                    initial: before,
+                    inspect: () => observeRelease(client, release),
+                    apply: () => runSnippet(guardRevision(client, checkedTarget), finalizeReleaseSnippet(release, bundleReference.sha256, review.hash), {
+                        retries: 0,
+                        effect: "write",
+                    }),
+                    verify: complete,
+                    reconcile: (_before, current) => complete(current)
+                        ? "complete"
+                        : current.marker?.status === "draft"
+                            ? "pending"
+                            : "conflict",
+                },
+            ], {
+                root,
+                operation: "design-release-finalize",
+                input: {
+                    designHash,
+                    bundleHash: bundleReference.sha256,
+                    reviewHash: review.hash,
+                },
+                runId: options.runId ?? `finalize-${release.target.ownerKey.slice(0, 32)}`,
+                resume: options.resume,
+                target: () => readJournalTarget(client),
+                redact: options.redact,
+                onStep: options.onStep,
+            });
+        }
+        const observed = await observeRelease(client, release);
+        if (!complete(observed)) {
+            throw new Error("Independent finalized marker readback failed; local final pointer not written");
+        }
+        const rechecked = await checkRelease(client, root, final, options);
+        if (!rechecked.valid) {
+            throw new Error(`Release changed after its remote marker; local final pointer not written: ${rechecked.reasons.join("; ")}`);
+        }
+        // The immutable bundle and remote readback exist before the authoritative local pointer changes.
+        await writeDesignRelease(root, pointer, final, options);
+        return final;
+    });
+}

package/dist/design-releases/index.d.ts

@@ -0,0 +1,8 @@
+export type * from "./types.js";
+export { planRelease, readDesignRelease, writeDesignRelease } from "./store.js";
+export { assembleRelease } from "./assemble.js";
+export { verifyRelease } from "./verify.js";
+export { finalizeRelease } from "./finalize.js";
+export { checkRelease } from "./check.js";
+export { releaseContext } from "./context.js";
+export { validateDesignRelease, validateReleasePlan, hashDesignRelease, hashDesignRelease as releaseDesignHash, } from "./validation.js";

package/dist/design-releases/index.js

@@ -0,0 +1,7 @@
+export { planRelease, readDesignRelease, writeDesignRelease } from "./store.js";
+export { assembleRelease } from "./assemble.js";
+export { verifyRelease } from "./verify.js";
+export { finalizeRelease } from "./finalize.js";
+export { checkRelease } from "./check.js";
+export { releaseContext } from "./context.js";
+export { validateDesignRelease, validateReleasePlan, hashDesignRelease, hashDesignRelease as releaseDesignHash, } from "./validation.js";

package/dist/design-releases/live.d.ts

@@ -0,0 +1,22 @@
+import type { PenpotToolClient } from "../client.js";
+import { type InspectionCapture } from "../inspection.js";
+import type { DesignRelease, ReleaseSource } from "./types.js";
+export interface ReleaseObservation {
+    pageId: string | null;
+    overviewFrameId: string | null;
+    marker: null | {
+        schemaVersion: 1;
+        owner: string;
+        releaseId: string;
+        productVersion: string;
+        ownerKey: string;
+        status: string;
+        bundleHash?: string;
+        reviewHash?: string;
+    };
+}
+export declare function releaseClient(client: PenpotToolClient, release: DesignRelease): PenpotToolClient;
+export declare function observeRelease(client: PenpotToolClient, release: DesignRelease): Promise<ReleaseObservation>;
+export declare function captureReleaseScreen(client: PenpotToolClient, fileId: string, pageId: string, frameId: string): Promise<InspectionCapture>;
+export declare function dependencyFingerprint(raw: unknown): string;
+export declare function assertSourceUnchanged(client: PenpotToolClient, root: string, release: DesignRelease, source: ReleaseSource): Promise<InspectionCapture>;

package/dist/design-releases/live.js

@@ -0,0 +1,97 @@
+import { captureInspection, inspectionFields } from "../inspection.js";
+import { selectPage } from "../page-session.js";
+import { observationHash } from "../journal.js";
+import { runSnippet, snippet } from "../snippet.js";
+import { guardFile } from "../file-guard.js";
+import { readArtifact } from "./artifact-paths.js";
+import { inspectionContentHash } from "./fidelity.js";
+import { inspectReleaseSnippet } from "./snippets.js";
+export function releaseClient(client, release) {
+    return guardFile(client, {
+        id: release.fileId,
+    }, {
+        mode: "strict",
+    });
+}
+export async function observeRelease(client, release) {
+    const result = await runSnippet(client, inspectReleaseSnippet(release));
+    if (!(result.pageId === null || typeof result.pageId === "string") ||
+        !(result.overviewFrameId === null || typeof result.overviewFrameId === "string") ||
+        !(result.marker === null || typeof result.marker === "object")) {
+        throw new Error("Release ownership observation is incomplete");
+    }
+    return {
+        pageId: result.pageId,
+        overviewFrameId: result.overviewFrameId,
+        marker: result.marker,
+    };
+}
+export async function captureReleaseScreen(client, fileId, pageId, frameId) {
+    await selectPage(client, {
+        id: pageId,
+    });
+    const page = await runSnippet(client, snippet("release-page-name", "return {ok:true,pageName:penpot.currentPage.name};", {}, "read"));
+    if (typeof page.pageName !== "string" || !page.pageName) {
+        throw new Error("Release page name unavailable");
+    }
+    const capture = await captureInspection(client, {
+        page: page.pageName,
+        shapeId: frameId,
+        fields: [
+            ...inspectionFields,
+        ],
+        depth: 256,
+        maxNodes: 20000,
+        documentBytes: 16 * 1024 * 1024,
+    });
+    if (!capture.complete ||
+        capture.kind !== "shape-inspection" ||
+        capture.fileId !== fileId ||
+        capture.pageId !== pageId ||
+        capture.nodes?.[0]?.id !== frameId) {
+        throw new Error("Incomplete or mismatched release screen inspection");
+    }
+    return capture;
+}
+export function dependencyFingerprint(raw) {
+    const value = raw;
+    if (value.schemaVersion !== 1 ||
+        value.kind !== "token-inspection" ||
+        value.complete !== true ||
+        !Array.isArray(value.reasons) ||
+        value.reasons.length ||
+        !Array.isArray(value.sets) ||
+        !Array.isArray(value.themes) ||
+        (value.counts?.unknownFields ?? 0) !== 0) {
+        throw new Error("Token dependency evidence is incomplete or unknown");
+    }
+    return observationHash({
+        sets: value.sets,
+        themes: value.themes,
+    });
+}
+export async function assertSourceUnchanged(client, root, release, source) {
+    const capture = await captureReleaseScreen(client, release.fileId, source.pageId, source.frameId);
+    if (inspectionContentHash(capture) !== source.contentHash) {
+        throw new Error(`Pinned release source changed: ${source.id}`);
+    }
+    const usesTokens = capture.nodes?.some((node) => node.tokens && typeof node.tokens === "object" && Object.keys(node.tokens).length > 0);
+    if (usesTokens && !source.dependencies) {
+        throw new Error("Token-bound source requires a pinned dependency inspection");
+    }
+    if (source.dependencies) {
+        const before = JSON.parse((await readArtifact(root, source.dependencies)).toString("utf8"));
+        if (before.fileId !== release.fileId) {
+            throw new Error("Dependency snapshot belongs to another file");
+        }
+        const current = await captureInspection(client, {
+            kind: "tokens",
+            maxNodes: 20000,
+            documentBytes: 16 * 1024 * 1024,
+        });
+        if (dependencyFingerprint(current) !== dependencyFingerprint(before)) {
+            throw new Error("Source token dependencies changed since the pinned snapshot");
+        }
+    }
+    return capture;
+}

package/dist/design-releases/snippets.d.ts

@@ -0,0 +1,5 @@
+import { type Snippet } from "../snippet.js";
+import type { DesignRelease } from "./types.js";
+export declare function inspectReleaseSnippet(release: DesignRelease): Snippet;
+export declare function assembleReleaseSnippet(release: DesignRelease): Snippet;
+export declare function finalizeReleaseSnippet(release: DesignRelease, bundleHash: string, reviewHash: string): Snippet;