@penpair/core 0.4.1 → 0.5.0

package/dist/cli-main.js

@@ -61,6 +61,7 @@ Design agreements and release pages:
   penpair journey-map check|render|publish|import|accept|approve|context --from FILE
   penpair integration-map check|render|publish|import|accept|approve|context --from FILE
   penpair design-release plan|assemble|verify|finalize|check|context --from FILE
+  penpair design-release copy --source-page PAGE --frame ID --release VERSION [--debug-port PORT --apply]
   (publication previews by default; --apply writes Penpot, --write records local acceptance/review)
 Start here (guided, plain language; safe to run again):
   penpair setup                                        asks where your Penpot is (web is the default), sets everything up and checks it
@@ -2296,9 +2297,19 @@ async function runCliInternal(argv, options = {}) {
             argv[0] === "integration-map" ||
             argv[0] === "design-release") {
             const { runDesignCommand } = await import("./design-commands/index.js");
+            const copyConfig = argv[0] === "design-release" && argv[1] === "copy"
+                ? await loadCommandConfig(root)
+                : undefined;
             let designRedactor = (text) => redactEndpoint(text);
             return await runDesignCommand(argv[0], argv.slice(1), {
                 root,
+                copyTarget: copyConfig?.file?.id
+                    ? {
+                        fileId: copyConfig.file.id,
+                        origin: isExternal(copyConfig) ? copyConfig.profile.origin : frontendUrl(copyConfig),
+                        allowLoopbackAlias: !isExternal(copyConfig),
+                    }
+                    : undefined,
                 output,
                 redact: (text) => designRedactor(text),
                 async withPenpot(work) {

package/dist/clipboard-payload.d.ts

@@ -0,0 +1,2 @@
+/** A bounded identity check, evaluated inside the browser; clipboard text never leaves that page. */
+export declare function nativeClipboardPayloadMatches(text: string, fileId: string, frameIds: string[]): boolean;

package/dist/clipboard-payload.js

@@ -0,0 +1,89 @@
+/** A bounded identity check, evaluated inside the browser; clipboard text never leaves that page. */
+export function nativeClipboardPayloadMatches(text, fileId, frameIds) {
+    const uuid = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i;
+    const identity = (value) => {
+        if (typeof value !== "string") {
+            return undefined;
+        }
+        const plain = value.startsWith("~u") ? value.slice(2) : value;
+        return uuid.test(plain) ? plain.toLowerCase() : undefined;
+    };
+    const field = (record, name) => {
+        const ordinary = Object.hasOwn(record, name);
+        const encoded = Object.hasOwn(record, `~:${name}`);
+        return ordinary === encoded ? undefined : record[ordinary ? name : `~:${name}`];
+    };
+    const object = (value) => Boolean(value && typeof value === "object" && !Array.isArray(value));
+    if (typeof text !== "string" ||
+        text.length > 16 * 1024 * 1024 ||
+        !uuid.test(fileId) ||
+        !Array.isArray(frameIds) ||
+        !frameIds.length ||
+        frameIds.length > 100 ||
+        frameIds.some((id) => typeof id !== "string" || !uuid.test(id)) ||
+        new Set(frameIds.map((id) => id.toLowerCase())).size !== frameIds.length) {
+        return false;
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        return false;
+    }
+    if (!object(raw)) {
+        return false;
+    }
+    const type = field(raw, "type");
+    if ((type !== "copied-shapes" && type !== "~:copied-shapes") ||
+        identity(field(raw, "file-id")) !== fileId.toLowerCase()) {
+        return false;
+    }
+    let selected = field(raw, "selected");
+    if (object(selected)) {
+        const tags = Object.keys(selected);
+        if (tags.length !== 1 ||
+            ![
+                "~#set",
+                "~#ordered-set",
+            ].includes(tags[0])) {
+            return false;
+        }
+        selected = selected[tags[0]];
+    }
+    else if (Array.isArray(selected) &&
+        selected.length === 2 &&
+        typeof selected[0] === "string" &&
+        [
+            "~#set",
+            "~#ordered-set",
+        ].includes(selected[0])) {
+        selected = selected[1];
+    }
+    if (!Array.isArray(selected) || selected.length !== frameIds.length) {
+        return false;
+    }
+    const selectedIds = selected.map(identity);
+    if (selectedIds.some((id) => !id) ||
+        new Set(selectedIds).size !== frameIds.length ||
+        frameIds.some((id) => !selectedIds.includes(id.toLowerCase()))) {
+        return false;
+    }
+    const objects = field(raw, "objects");
+    if (!object(objects)) {
+        return false;
+    }
+    const entries = Object.entries(objects);
+    if (entries.length > 20000 || entries.length < frameIds.length) {
+        return false;
+    }
+    const objectIds = new Set();
+    for (const [key, value] of entries) {
+        const id = identity(key);
+        if (!id || objectIds.has(id) || !object(value) || identity(field(value, "id")) !== id) {
+            return false;
+        }
+        objectIds.add(id);
+    }
+    return frameIds.every((id) => objectIds.has(id.toLowerCase()));
+}

package/dist/design-commands/context.d.ts

@@ -5,5 +5,10 @@ export interface DesignCommandContext {
     root: string;
     output: CommandOutput;
     redact(value: string): string;
+    copyTarget?: {
+        fileId: string;
+        origin: string;
+        allowLoopbackAlias: boolean;
+    };
     withPenpot<T>(work: (client: PenpotToolClient) => Promise<T>): Promise<T>;
 }

package/dist/design-commands/copy-command.d.ts

@@ -0,0 +1,3 @@
+import type { DesignCommandContext } from "./context.js";
+/** Preview resolves native boards; only explicit apply obtains clipboard control. */
+export declare function runDesignReleaseCopyCommand(args: string[], context: DesignCommandContext): Promise<number>;

package/dist/design-commands/copy-command.js

@@ -0,0 +1,101 @@
+import { CommandArgumentError, parseCommandArgs } from "../cli-arguments.js";
+import { commandSignal } from "../command-result.js";
+import { copyReleaseBoards } from "../design-releases/copy.js";
+import { connectNativeClipboard } from "../native-editor-clipboard.js";
+const copyUsage = "design-release copy --source-page PAGE --frame ID [--frame ID ...] --release VERSION [--debug-port PORT --apply] [--resume RUN_ID]";
+function boundedText(value) {
+    return (typeof value === "string" &&
+        !!value.trim() &&
+        value.length <= 1000 &&
+        !/[\x00-\x1f]/.test(value));
+}
+/** Preview resolves native boards; only explicit apply obtains clipboard control. */
+export async function runDesignReleaseCopyCommand(args, context) {
+    const { values, positionals } = parseCommandArgs({
+        args,
+        allowPositionals: true,
+        options: {
+            "source-page": {
+                type: "string",
+            },
+            frame: {
+                type: "string",
+                multiple: true,
+            },
+            release: {
+                type: "string",
+            },
+            "debug-port": {
+                type: "string",
+            },
+            apply: {
+                type: "boolean",
+            },
+            resume: {
+                type: "string",
+            },
+            json: {
+                type: "boolean",
+            },
+            help: {
+                type: "boolean",
+            },
+        },
+    });
+    if (values.help) {
+        context.output.log(copyUsage);
+        return 0;
+    }
+    const frameIds = values.frame ?? [];
+    if (positionals.length ||
+        !boundedText(values["source-page"]) ||
+        !boundedText(values.release) ||
+        !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(values.release) ||
+        frameIds.length < 1 ||
+        frameIds.length > 100 ||
+        frameIds.some((frameId) => !boundedText(frameId)) ||
+        new Set(frameIds).size !== frameIds.length) {
+        throw new CommandArgumentError(copyUsage);
+    }
+    if (values.resume && (!values.apply || !/^[a-zA-Z0-9-]{1,100}$/.test(values.resume))) {
+        throw new CommandArgumentError("Copy recovery requires --apply and the original --resume RUN_ID");
+    }
+    if ((values.apply && !values["debug-port"]) ||
+        (values["debug-port"] !== undefined &&
+            (!/^\d+$/.test(values["debug-port"]) ||
+                Number(values["debug-port"]) < 1 ||
+                Number(values["debug-port"]) > 65535))) {
+        throw new CommandArgumentError("Copy --apply requires --debug-port with an integer from 1 to 65535");
+    }
+    const target = context.copyTarget;
+    if (!target?.fileId) {
+        throw new CommandArgumentError("Native copy requires the project's owner-confirmed file pin");
+    }
+    const result = await context.withPenpot((client) => copyReleaseBoards(client, context.root, {
+        fileId: target.fileId,
+        sourcePage: values["source-page"],
+        frameIds,
+        releaseVersion: values.release,
+    }, {
+        apply: values.apply === true,
+        resume: !!values.resume,
+        runId: values.resume,
+        redact: (text) => context.redact(text),
+        onStep: (message) => context.output.error(`… ${message}`),
+        ...(values.apply
+            ? {
+                clipboard: () => connectNativeClipboard({
+                    origin: target.origin,
+                    fileId: target.fileId,
+                    allowLoopbackAlias: target.allowLoopbackAlias,
+                    port: Number(values["debug-port"]),
+                    timeoutMs: 30000,
+                    signal: commandSignal(),
+                }),
+            }
+            : {}),
+    }));
+    context.output.result(result);
+    context.output.log(JSON.stringify(result, null, 2));
+    return result.status === "incomplete" ? 3 : 0;
+}

package/dist/design-commands/release-command.js

@@ -6,7 +6,9 @@ import { readProjectBytes } from "../bounded-file.js";
 import { resolveProjectOutput } from "../project-input.js";
 import { createArtifactReview } from "../maps/index.js";
 import { planRelease, assembleRelease, verifyRelease, finalizeRelease, checkRelease, releaseContext, releaseDesignHash, readDesignRelease, writeDesignRelease, } from "../design-releases/index.js";
-const releaseUsage = "design-release plan|assemble|verify|finalize|check|context --from FILE [--out FILE]";
+import { runDesignReleaseCopyCommand } from "./copy-command.js";
+const releaseUsage = "design-release plan|assemble|verify|finalize|check|context --from FILE [--out FILE]\n" +
+    "design-release copy --source-page PAGE --frame ID [--frame ID ...] --release VERSION [--debug-port PORT --apply] [--resume RUN_ID]";
 async function readReleaseJson(context, file) {
     return JSON.parse((await readProjectBytes(context.root, file, 16 * 1024 * 1024)).toString("utf8"));
 }
@@ -45,6 +47,9 @@ function validateReceiptInput(raw) {
 }
 /** CLI entrypoint: local planning stays offline and all live work uses a strictly pinned connection. */
 export async function runDesignReleaseCommand(args, context) {
+    if (args[0] === "copy") {
+        return runDesignReleaseCopyCommand(args.slice(1), context);
+    }
     const parsed = parseCommandArgs({
         args,
         allowPositionals: true,

package/dist/design-releases/copy-evidence.d.ts

@@ -0,0 +1,33 @@
+import type { PenpotToolClient } from "../client.js";
+import type { InspectionCapture } from "../inspection.js";
+import type { ReleaseArtifactRef } from "./types.js";
+export interface CopyFrameEvidence {
+    frameId: string;
+    name: string;
+    inspection: InspectionCapture;
+    inspectionRef: ReleaseArtifactRef;
+    render: ReleaseArtifactRef;
+    pixels: {
+        hash: string;
+        width: number;
+        height: number;
+    };
+}
+export interface CopiedFramePair {
+    sourceFrameId: string;
+    targetFrameId: string;
+}
+export interface CopyEvidenceComparison {
+    nativeVerified: boolean;
+    pixelsMatch: boolean;
+    nodeMap: Record<string, string>;
+    problems: string[];
+}
+/** Capture immutable native observations and a stable render; this does not approve a release. */
+export declare function captureCopyEvidence(client: PenpotToolClient, root: string, fileId: string, pageId: string, frameIds: string[], prefix: string, redact?: (text: string) => string): Promise<CopyFrameEvidence[]>;
+/** Matching identifies newly observed boards; names alone never establish a transfer identity. */
+export declare function matchCopiedFrames(sources: CopyFrameEvidence[], targets: CopyFrameEvidence[]): CopiedFramePair[];
+/** Validate observable structure and exact pixels separately; unknown native content never passes. */
+export declare function compareCopyEvidence(sources: CopyFrameEvidence[], targets: CopyFrameEvidence[], pairs: CopiedFramePair[]): CopyEvidenceComparison;
+/** A source preservation hash excludes capture revisions, timestamps and transport metrics. */
+export declare function sourceEvidenceHash(evidence: CopyFrameEvidence[]): string;

package/dist/design-releases/copy-evidence.js

@@ -0,0 +1,278 @@
+import { exportShapePng } from "../export.js";
+import { observationHash } from "../journal.js";
+import { saveArtifact } from "./artifact-paths.js";
+import { captureReleaseScreen } from "./live.js";
+import { compareNativeCopy, decodedPixels, deriveNodeMap } from "./fidelity.js";
+/** Capture immutable native observations and a stable render; this does not approve a release. */
+export async function captureCopyEvidence(client, root, fileId, pageId, frameIds, prefix, redact) {
+    if (!frameIds.length ||
+        frameIds.length > 100 ||
+        new Set(frameIds).size !== frameIds.length ||
+        frameIds.some((frameId) => typeof frameId !== "string" || !frameId || frameId.length > 256)) {
+        throw new Error("Copy evidence needs one to 100 distinct frame IDs");
+    }
+    const evidence = [];
+    for (const [index, frameId] of frameIds.entries()) {
+        const { inspection, image } = await captureFramePair(client, fileId, pageId, frameId);
+        const first = orderedNodes(inspection, frameId)[0].node;
+        if (typeof first.name !== "string") {
+            throw new Error("Copy frame name was not observed");
+        }
+        const pixels = await decodedPixels(image.png);
+        const stem = `${prefix}/frame-${index}`;
+        const inspectionRef = await saveArtifact(root, `${stem}.json`, JSON.stringify(inspection), redact);
+        const render = await saveArtifact(root, `${stem}.png`, image.png, redact);
+        evidence.push({
+            frameId,
+            name: first.name,
+            inspection,
+            inspectionRef,
+            render,
+            pixels,
+        });
+    }
+    return evidence;
+}
+/** Retry only an inconsistent read pair, never a mutation or an identity/stability failure. */
+async function captureFramePair(client, fileId, pageId, frameId) {
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const inspection = await captureReleaseScreen(client, fileId, pageId, frameId);
+        orderedNodes(inspection, frameId);
+        const image = await exportShapePng(client, frameId, {
+            stable: true,
+        });
+        if (!image.stable ||
+            image.capture.fileId !== fileId ||
+            image.capture.pageId !== pageId ||
+            image.capture.frameId !== frameId) {
+            throw new Error("Copy source changed or stable render identity was not established");
+        }
+        if (image.capture.revision === inspection.revision) {
+            return {
+                inspection,
+                image,
+            };
+        }
+    }
+    throw new Error("Copy source changed during both bounded inspection/render attempts");
+}
+/** Observe topology without claiming complete native fidelity for unsupported shape content. */
+function orderedNodes(inspection, frameId) {
+    if (inspection.kind !== "shape-inspection" ||
+        !inspection.complete ||
+        !Array.isArray(inspection.nodes) ||
+        !inspection.nodes.length ||
+        inspection.nodes.length > 20000) {
+        throw new Error("Copy matching 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)) {
+            throw new Error("Copy matching encountered duplicate or missing shape IDs");
+        }
+        nodes.set(node.id, node);
+    }
+    const root = nodes.get(frameId);
+    if (!root || root.parentId !== null || root.type !== "board") {
+        throw new Error("Copy matching requires the requested native board root");
+    }
+    const ordered = [];
+    const visited = new Set();
+    const pending = [
+        {
+            node: root,
+            path: "root",
+            parent: null,
+        },
+    ];
+    while (pending.length) {
+        const entry = pending.pop();
+        const id = String(entry.node.id);
+        const childIds = entry.node.childIds;
+        if (visited.has(id) ||
+            entry.node.parentId !== entry.parent ||
+            !Array.isArray(childIds) ||
+            entry.node.childrenTotal !== childIds.length) {
+            throw new Error("Copy matching encountered incomplete or inconsistent hierarchy");
+        }
+        visited.add(id);
+        ordered.push({
+            path: entry.path,
+            node: entry.node,
+        });
+        for (let index = childIds.length - 1; index >= 0; index--) {
+            const childId = childIds[index];
+            const child = typeof childId === "string" ? nodes.get(childId) : undefined;
+            if (!child || child.index !== index) {
+                throw new Error("Copy matching encountered an unknown or reordered child");
+            }
+            pending.push({
+                node: child,
+                path: `${entry.path}/${index}`,
+                parent: id,
+            });
+        }
+    }
+    if (visited.size !== nodes.size) {
+        throw new Error("Copy matching includes detached shape observations");
+    }
+    return ordered;
+}
+function matchingFingerprint(evidence) {
+    const ordered = orderedNodes(evidence.inspection, evidence.frameId);
+    const rootGeometry = ordered[0].node.geometry;
+    if (!rootGeometry) {
+        throw new Error("Copy root geometry is unavailable");
+    }
+    const fingerprint = ordered.map(({ path, node }) => {
+        const geometry = node.geometry;
+        if (!geometry || typeof node.name !== "string" || typeof node.type !== "string") {
+            throw new Error("Copy matching needs observed names, types and geometry");
+        }
+        const normalized = {};
+        for (const axis of [
+            "x",
+            "y",
+            "width",
+            "height",
+            "rotation",
+        ]) {
+            const value = geometry[axis];
+            if (typeof value !== "number" || !Number.isFinite(value)) {
+                throw new Error("Copy matching geometry must be finite and observable");
+            }
+            const origin = axis === "x" || axis === "y" ? rootGeometry[axis] : 0;
+            if (typeof origin !== "number" || !Number.isFinite(origin)) {
+                throw new Error("Copy matching root position must be observable");
+            }
+            normalized[axis] = Math.round((value - origin) * 1e6) / 1e6;
+        }
+        return {
+            path,
+            name: node.name,
+            type: node.type,
+            geometry: normalized,
+        };
+    });
+    return observationHash(fingerprint);
+}
+/** Matching identifies newly observed boards; names alone never establish a transfer identity. */
+export function matchCopiedFrames(sources, targets) {
+    if (!sources.length || sources.length > 100 || sources.length !== targets.length) {
+        throw new Error("Copied frame count does not match the requested sources");
+    }
+    if (new Set(sources.map((source) => source.frameId)).size !== sources.length ||
+        new Set(targets.map((target) => target.frameId)).size !== targets.length ||
+        targets.some((target) => sources.some((source) => source.frameId === target.frameId))) {
+        throw new Error("Source and copied frame identities must be distinct");
+    }
+    const sourceFingerprints = sources.map(matchingFingerprint);
+    const targetFingerprints = targets.map(matchingFingerprint);
+    if (new Set(sourceFingerprints).size !== sourceFingerprints.length) {
+        throw new Error("Source boards are ambiguous; copy matching cannot assign unique identities");
+    }
+    return sources.map((source, index) => {
+        const matches = targets.filter((_target, targetIndex) => targetFingerprints[targetIndex] === sourceFingerprints[index]);
+        if (matches.length !== 1) {
+            throw new Error("Copied board content is missing, changed or ambiguous");
+        }
+        return {
+            sourceFrameId: source.frameId,
+            targetFrameId: matches[0].frameId,
+        };
+    });
+}
+/** Validate observable structure and exact pixels separately; unknown native content never passes. */
+export function compareCopyEvidence(sources, targets, pairs) {
+    if (!sources.length ||
+        sources.length > 100 ||
+        pairs.length !== sources.length ||
+        targets.length !== sources.length ||
+        new Set(pairs.map((pair) => pair.sourceFrameId)).size !== pairs.length ||
+        new Set(pairs.map((pair) => pair.targetFrameId)).size !== pairs.length ||
+        new Set(sources.map((source) => source.frameId)).size !== sources.length ||
+        new Set(targets.map((target) => target.frameId)).size !== targets.length) {
+        throw new Error("Copy verification requires complete distinct source-to-target pairs");
+    }
+    const observations = pairs.map((pair) => {
+        const source = sources.find((item) => item.frameId === pair.sourceFrameId);
+        const target = targets.find((item) => item.frameId === pair.targetFrameId);
+        if (!source ||
+            !target ||
+            source.frameId === target.frameId ||
+            source.inspection.fileId !== target.inspection.fileId) {
+            throw new Error("Copy verification pair refers to an unknown or original frame");
+        }
+        return {
+            source,
+            target,
+        };
+    });
+    const nodeMap = {};
+    const mappedTargets = new Set();
+    for (const { source, target } of observations) {
+        const before = orderedNodes(source.inspection, source.frameId);
+        const after = orderedNodes(target.inspection, target.frameId);
+        if (before.length !== after.length) {
+            throw new Error("Copy hierarchy node counts differ");
+        }
+        for (const [index, entry] of before.entries()) {
+            const copied = after[index];
+            const from = String(entry.node.id);
+            const to = String(copied.node.id);
+            if (entry.path !== copied.path ||
+                entry.node.type !== copied.node.type ||
+                from === to ||
+                Object.hasOwn(nodeMap, from) ||
+                mappedTargets.has(to)) {
+                throw new Error("Copy topology or independent shape identity differs");
+            }
+            nodeMap[from] = to;
+            mappedTargets.add(to);
+        }
+    }
+    if (Object.keys(nodeMap).some((id) => mappedTargets.has(id))) {
+        throw new Error("Copied descendants overlap original source identities");
+    }
+    const problems = [];
+    let nativeVerified = true;
+    let pixelsMatch = true;
+    for (const { source, target } of observations) {
+        try {
+            deriveNodeMap(source.inspection, target.inspection);
+            compareNativeCopy(source.inspection, target.inspection, nodeMap);
+            const before = orderedNodes(source.inspection, source.frameId);
+            const after = orderedNodes(target.inspection, target.frameId);
+            if (before.some((entry, index) => entry.node.name !== after[index].node.name)) {
+                throw new Error("Native copy changed a board or descendant name");
+            }
+        }
+        catch (error) {
+            nativeVerified = false;
+            problems.push(`Native fidelity for ${source.frameId}: ${error instanceof Error ? error.message : "unavailable"}`);
+        }
+        if (source.pixels.hash !== target.pixels.hash ||
+            source.pixels.width !== target.pixels.width ||
+            source.pixels.height !== target.pixels.height) {
+            pixelsMatch = false;
+            problems.push(`Exported pixels differ for ${source.frameId}`);
+        }
+    }
+    return {
+        nativeVerified,
+        pixelsMatch,
+        nodeMap,
+        problems,
+    };
+}
+/** A source preservation hash excludes capture revisions, timestamps and transport metrics. */
+export function sourceEvidenceHash(evidence) {
+    return observationHash(evidence.map((frame) => ({
+        frameId: frame.frameId,
+        name: frame.name,
+        fileId: frame.inspection.fileId,
+        pageId: frame.inspection.pageId,
+        nodes: frame.inspection.nodes,
+        pixels: frame.pixels,
+    })));
+}

package/dist/design-releases/copy-plan.d.ts

@@ -0,0 +1,49 @@
+export interface CopyRequest {
+    fileId: string;
+    sourcePage: string;
+    frameIds: string[];
+    releaseVersion: string;
+}
+export interface CopyPreview {
+    arranged?: boolean;
+    destinationNamed?: boolean;
+    fileId: string;
+    revision: number;
+    sourcePageId: string;
+    sourcePageName: string;
+    destinationPageId: string | null;
+    destinationName: string;
+    destinationRootIds: string[];
+    destinationBounds: {
+        bottom: number;
+    };
+    sourceFrames: Array<{
+        id: string;
+        name: string;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        nodeCount: number;
+    }>;
+    createdPageOwner: string | null;
+}
+export interface CopyObservation {
+    pageId: string;
+    rootIds: string[];
+    selectionIds: string[];
+    rootFrames: Array<{
+        id: string;
+        name: string;
+        type: string;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        nodeCount: number;
+        copyRunId: string | null;
+    }>;
+}
+export declare function validateCopyRequest(request: CopyRequest): void;
+export declare function readCopyPreview(raw: Record<string, unknown>, request: CopyRequest): CopyPreview;
+export declare function copyRequestHash(request: CopyRequest): string;

package/dist/design-releases/copy-plan.js

@@ -0,0 +1,55 @@
+import { observationHash } from "../journal.js";
+export function validateCopyRequest(request) {
+    const text = (value) => typeof value === "string" &&
+        value.trim().length > 0 &&
+        value.length <= 256 &&
+        !/[\x00-\x1f\x7f]/.test(value);
+    if (!text(request.fileId) ||
+        !text(request.sourcePage) ||
+        !Array.isArray(request.frameIds) ||
+        !request.frameIds.length ||
+        request.frameIds.length > 100 ||
+        request.frameIds.some((id) => !text(id)) ||
+        new Set(request.frameIds).size !== request.frameIds.length) {
+        throw new Error("Copy requires a pinned file, source page and 1–100 distinct board IDs");
+    }
+    if (!text(request.releaseVersion) ||
+        !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(request.releaseVersion)) {
+        throw new Error("Copy release version must be a safe semantic version, for example 1.2.0");
+    }
+}
+export function readCopyPreview(raw, request) {
+    if (raw.ok !== true ||
+        raw.fileId !== request.fileId ||
+        !Number.isInteger(raw.revision) ||
+        typeof raw.sourcePageId !== "string" ||
+        typeof raw.sourcePageName !== "string" ||
+        !(raw.destinationPageId === null || typeof raw.destinationPageId === "string") ||
+        raw.destinationName !== `release/${request.releaseVersion}` ||
+        !Array.isArray(raw.destinationRootIds) ||
+        raw.destinationRootIds.some((id) => typeof id !== "string") ||
+        !Array.isArray(raw.sourceFrames) ||
+        raw.sourceFrames.length !== request.frameIds.length ||
+        !raw.destinationBounds ||
+        typeof raw.destinationBounds !== "object" ||
+        !Number.isFinite(raw.destinationBounds.bottom)) {
+        throw new Error("Copy inspection did not establish the complete source and destination identities");
+    }
+    const frames = raw.sourceFrames;
+    if (frames.some((frame, index) => !frame ||
+        frame.id !== request.frameIds[index] ||
+        typeof frame.name !== "string" ||
+        ![
+            frame.x,
+            frame.y,
+            frame.width,
+            frame.height,
+            frame.nodeCount,
+        ].every(Number.isFinite))) {
+        throw new Error("Copy inspection returned incomplete board evidence");
+    }
+    return raw;
+}
+export function copyRequestHash(request) {
+    return observationHash(request);
+}