@penpair/core 0.3.6 → 0.4.0

package/dist/map-penpot/publish.js

@@ -0,0 +1,301 @@
+import { nativeMapShapeKeys, nativeMapTextEntries } from "./content.js";
+import { defaultMapIcon, identifyMapIcon } from "./icons.js";
+import { mapOriginLabels, mapOriginLegend } from "./status-labels.js";
+import { redactEndpoint } from "../endpoint.js";
+import { MapExportEvidenceError } from "./evidence-error.js";
+import { resolveMapDetails } from "./details.js";
+import { exportShapePng } from "../export.js";
+import { runOperation } from "../operation.js";
+import { routeMapEdges, mapDrawingGeometryProblems } from "../maps/layout.js";
+import { preserveMapPresentation } from "./presentation.js";
+import { withPageSession } from "../page-session.js";
+import { readMapPathPoints } from "./path-geometry.js";
+import { inspectMapSnippet, publishMapSnippet } from "./snippets.js";
+import { validateDrawing, projection, readProjection } from "./projection.js";
+export function verificationProblems(drawing, observed) {
+    const problems = [
+        ...observed.conflicts,
+    ];
+    if (!observed.boardId || observed.contractHash !== drawing.contractHash) {
+        problems.push("Map board or contract identity differs");
+    }
+    const expectedKeys = nativeMapShapeKeys(drawing);
+    for (const shape of observed.shapes) {
+        if (!expectedKeys.delete(`${shape.role}:${shape.logicalId}`)) {
+            problems.push(`Unexpected shape ${shape.shapeId}`);
+        }
+    }
+    if (expectedKeys.size) {
+        problems.push("Managed shapes are missing");
+    }
+    if (drawing.nodes.some((node) => node.origin) &&
+        observed.shapes.find((shape) => shape.role === "legend")?.label !== mapOriginLegend) {
+        problems.push("Origin legend differs");
+    }
+    for (const shape of observed.shapes) {
+        const style = shape.appearance;
+        const radius = shape.role === "node" || shape.role === "annotation-panel"
+            ? 12
+            : shape.role === "icon-well"
+                ? 8
+                : undefined;
+        if (radius !== undefined &&
+            [
+                "borderRadiusTopLeft",
+                "borderRadiusTopRight",
+                "borderRadiusBottomLeft",
+                "borderRadiusBottomRight",
+            ].some((corner) => typeof style?.[corner] === "number" && style[corner] !== radius)) {
+            problems.push(`Native rounded corners differ: ${shape.role}:${shape.logicalId}`);
+        }
+        if ((typeof style?.opacity === "number" && style.opacity !== 1) ||
+            (typeof style?.blendMode === "string" && style.blendMode !== "normal")) {
+            problems.push(`Native decorative opacity/blend differs: ${shape.role}:${shape.logicalId}`);
+        }
+    }
+    const bounds = observed.boardBounds;
+    if (bounds) {
+        for (const shape of observed.shapes.filter((shape) => shape.role !== "edge")) {
+            if (shape.x < bounds.x ||
+                shape.y < bounds.y ||
+                shape.x + shape.width > bounds.x + bounds.width + 0.01 ||
+                shape.y + shape.height > bounds.y + bounds.height + 0.01) {
+                problems.push(`Map content exceeds board bounds: ${shape.logicalId}`);
+            }
+        }
+    }
+    for (const node of drawing.nodes) {
+        const label = observed.shapes.find((shape) => shape.role === "label" && shape.logicalId === node.id);
+        for (const clickable of observed.shapes.filter((shape) => shape.logicalId === node.id &&
+            [
+                "node",
+                "label",
+                "badge",
+                "summary",
+                "icon-well",
+                "icon",
+                "port-in",
+                "port-out",
+            ].includes(shape.role))) {
+            if (node.detail &&
+                (clickable.interactions?.length !== 1 ||
+                    clickable.interactions[0]?.trigger !== "click" ||
+                    clickable.interactions[0]?.type !== "navigate-to" ||
+                    clickable.interactions[0]?.destinationId !== node.detail.frameId ||
+                    clickable.interactions[0]?.destinationPageId !== node.detail.pageId ||
+                    clickable.interactions[0]?.destinationMapHash !== node.detail.contractHash ||
+                    clickable.interactions[0]?.destinationMapId !== node.detail.mapId)) {
+                problems.push(`Detail link destination differs or is unobservable: ${node.id}`);
+            }
+            if (!node.detail && clickable.interactions?.length) {
+                problems.push(`Unexpected native interaction: ${node.id}`);
+            }
+        }
+        if (node.origin) {
+            const status = mapOriginLabels[node.origin];
+            if (observed.shapes.find((shape) => shape.role === "badge" && shape.logicalId === node.id)
+                ?.label !== status) {
+                problems.push(`Origin badge differs: ${node.id}`);
+            }
+        }
+        const icon = observed.shapes.find((shape) => shape.role === "icon" && shape.logicalId === node.id);
+        if (!icon || identifyMapIcon(icon) !== (node.icon ?? defaultMapIcon(node.kind))) {
+            problems.push(`Native icon differs: ${node.id}`);
+        }
+        const card = observed.shapes.find((shape) => shape.role === "node" && shape.logicalId === node.id);
+        if (card &&
+            label &&
+            (label.x < card.x ||
+                label.y < card.y ||
+                label.x + label.width > card.x + card.width + 0.01 ||
+                label.y + label.height > card.y + card.height + 0.01)) {
+            problems.push(`Node label exceeds card bounds: ${node.id}`);
+        }
+    }
+    if (observed.shapes.find((shape) => shape.role === "title")?.label !== drawing.title) {
+        problems.push("Map title differs");
+    }
+    for (const entry of nativeMapTextEntries(drawing)) {
+        const actual = observed.shapes.find((shape) => shape.role === entry.role && shape.logicalId === entry.logicalId);
+        if (actual?.label !== entry.text) {
+            problems.push(`Native text differs: ${entry.role}:${entry.logicalId}`);
+        }
+        if (actual && actual.height > entry.height + 0.01) {
+            problems.push(`Native text exceeds reserved space: ${entry.role}:${entry.logicalId}`);
+        }
+    }
+    const title = observed.shapes.find((shape) => shape.role === "title");
+    const legend = observed.shapes.find((shape) => shape.role === "legend");
+    if (title &&
+        (title.height > (drawing.header?.titleBox.height ?? 48) ||
+            (legend && title.y + title.height > legend.y))) {
+        problems.push("Map title exceeds the reserved header space");
+    }
+    for (const edge of drawing.edges) {
+        const path = observed.shapes.find((shape) => shape.role === "edge" && shape.logicalId === edge.id);
+        if (path?.from !== edge.from || path.to !== edge.to) {
+            problems.push(`Relationship differs: ${edge.id}`);
+        }
+        const edgeLabel = observed.shapes.find((shape) => shape.role === "edge-label" && shape.logicalId === edge.id);
+        if (edge.label && edgeLabel?.label !== edge.label) {
+            problems.push(`Relationship label differs: ${edge.id}`);
+        }
+        if (edge.labelBox && edgeLabel && edgeLabel.height > edge.labelBox.height + 0.01) {
+            problems.push(`Relationship label exceeds reserved space: ${edge.id}`);
+        }
+        const from = observed.shapes.find((shape) => shape.role === "node" && shape.logicalId === edge.from);
+        const to = observed.shapes.find((shape) => shape.role === "node" && shape.logicalId === edge.to);
+        const vertices = readMapPathPoints(path?.content);
+        const start = vertices?.[0];
+        const end = vertices?.at(-1);
+        const close = (left, right) => left !== undefined && Number.isFinite(left) && Math.abs(left - right) < 0.01;
+        if (!from ||
+            !to ||
+            !vertices ||
+            !(close(start?.x, from.x + from.width) || close(start?.x, from.x)) ||
+            !close(start?.y, from.y + from.height / 2) ||
+            !((close(end?.x, to.x) && close(end?.y, to.y + to.height / 2)) ||
+                (edge.from === edge.to && close(end?.x, to.x + to.width / 2) && close(end?.y, to.y)))) {
+            problems.push(`Relationship native geometry differs: ${edge.id}`);
+        }
+    }
+    if (bounds) {
+        const nodes = observed.shapes
+            .filter((shape) => shape.role === "node")
+            .map((shape) => ({
+            id: shape.logicalId,
+            x: shape.x - bounds.x,
+            y: shape.y - bounds.y,
+            width: shape.width,
+            height: shape.height,
+        }));
+        const edges = drawing.edges.flatMap((edge) => {
+            const path = observed.shapes.find((shape) => shape.role === "edge" && shape.logicalId === edge.id);
+            const points = readMapPathPoints(path?.content);
+            const label = observed.shapes.find((shape) => shape.role === "edge-label" && shape.logicalId === edge.id);
+            return points && label
+                ? [
+                    {
+                        id: edge.id,
+                        points: points.map((point) => ({
+                            x: point.x - bounds.x,
+                            y: point.y - bounds.y,
+                        })),
+                        labelBox: {
+                            x: label.x - bounds.x,
+                            y: label.y - bounds.y,
+                            width: label.width,
+                            height: label.height,
+                        },
+                    },
+                ]
+                : [];
+        });
+        problems.push(...mapDrawingGeometryProblems(nodes, edges));
+    }
+    return problems;
+}
+export async function publishMap(client, target, drawing, options = {}) {
+    const configuredRedact = options.redact ?? options.journal?.redact;
+    const redact = (text) => redactEndpoint(configuredRedact ? configuredRedact(text) : text);
+    const requireProtectedValuesAbsent = (value) => {
+        const encoded = JSON.stringify(value);
+        if (redact(encoded) !== encoded) {
+            throw new Error("Native map contains protected values; publication refused");
+        }
+    };
+    requireProtectedValuesAbsent(drawing);
+    validateDrawing(drawing);
+    if (drawing.nodes.some((node) => node.detail)) {
+        if (!options.journal?.root) {
+            throw new Error("Pinned detail publication needs its project root");
+        }
+        drawing = await resolveMapDetails(options.journal.root, drawing);
+    }
+    drawing = {
+        ...drawing,
+        edges: drawing.edges.every((edge) => edge.points && edge.labelBox)
+            ? drawing.edges
+            : routeMapEdges(drawing.nodes, drawing.edges),
+    };
+    requireProtectedValuesAbsent(drawing);
+    const geometryProblems = mapDrawingGeometryProblems(drawing.nodes, drawing.edges);
+    if (geometryProblems.length) {
+        throw new Error(`Map layout requires review: ${geometryProblems.join("; ")}`);
+    }
+    if (options.apply && !options.journal) {
+        throw new Error("Map publication requires a durable operation journal");
+    }
+    return withPageSession(client, async () => {
+        const before = await readProjection(client, target, drawing.mapId, options);
+        requireProtectedValuesAbsent(before);
+        if (before.conflicts.length) {
+            throw new Error(before.conflicts.join("; "));
+        }
+        if (options.apply &&
+            before.boardId &&
+            !options.journal?.resume &&
+            (!options.expected ||
+                options.expected.fingerprint !== before.fingerprint ||
+                options.expected.mapId !== drawing.mapId ||
+                options.expected.fileId !== target.fileId ||
+                options.expected.pageId !== target.pageId)) {
+            throw new Error("Existing map requires matching prior projection; import and reconcile edits first");
+        }
+        // Build the full write during preview too; size limits fail before a journal or remote mutation.
+        publishMapSnippet(target, before.boardId ? preserveMapPresentation(drawing, before) : drawing, before);
+        const operation = {
+            name: "publish-map",
+            page: () => undefined,
+            inspect: () => inspectMapSnippet(target, drawing.mapId),
+            apply: (_drawing, inspected) => {
+                const observed = inspected
+                    ? projection(target, drawing.mapId, inspected)
+                    : {
+                        ...before,
+                        boardId: null,
+                        boardBounds: null,
+                        contractHash: null,
+                        shapes: [],
+                        conflicts: [],
+                    };
+                const projectedDrawing = observed.boardId
+                    ? preserveMapPresentation(drawing, observed)
+                    : drawing;
+                requireProtectedValuesAbsent(projectedDrawing);
+                requireProtectedValuesAbsent(observed);
+                return publishMapSnippet(target, projectedDrawing, observed);
+            },
+            readback: () => inspectMapSnippet(target, drawing.mapId),
+            verify: ({ readback }) => verificationProblems(drawing, projection(target, drawing.mapId, readback)),
+        };
+        const report = await runOperation(client, operation, drawing, options);
+        const observed = report.readback ? projection(target, drawing.mapId, report.readback) : before;
+        let image;
+        if (options.apply && report.verified && options.export !== false && observed.boardId) {
+            try {
+                image = await exportShapePng(client, observed.boardId, {
+                    ...options,
+                    stable: true,
+                });
+            }
+            catch (error) {
+                const detail = redact(error instanceof Error ? error.message : String(error));
+                if (report.journal?.runId) {
+                    throw new MapExportEvidenceError(report.journal.runId, detail);
+                }
+                throw error;
+            }
+        }
+        return {
+            report,
+            projection: observed,
+            ...(image
+                ? {
+                    image,
+                }
+                : {}),
+            visualReviewRequired: Boolean(options.apply),
+        };
+    });
+}

package/dist/map-penpot/release-maps.d.ts

@@ -0,0 +1,21 @@
+import type { PenpotToolClient } from "../client.js";
+import type { MapContract } from "../maps/types.js";
+import type { MapTarget, PublishMapOptions, PublishMapResult } from "./types.js";
+export interface ReleaseMapPublication {
+    mapKind: MapContract["kind"];
+    mapId: string;
+    contractHash: string;
+    publication: PublishMapResult;
+}
+/** Each contract has its own recoverable journal; an interrupted batch is never replayed blindly. */
+export declare function assembleReleaseMaps(client: PenpotToolClient, root: string, target: MapTarget, contracts: MapContract[], options?: Omit<PublishMapOptions, "journal" | "expected"> & {
+    origin?: {
+        x: number;
+        y: number;
+    };
+    journals?: Record<string, {
+        runId: string;
+        resume?: boolean;
+    }>;
+    projections?: Record<string, NonNullable<PublishMapOptions["expected"]>>;
+}): Promise<ReleaseMapPublication[]>;

package/dist/map-penpot/release-maps.js

@@ -0,0 +1,104 @@
+import { observeMapSources } from "../maps/store.js";
+import { buildMapDrawingPlan } from "../maps/render.js";
+import { resolveMapDetails } from "./details.js";
+import { drawingFromPlan } from "./projection.js";
+import { publishMap } from "./publish.js";
+/** Each contract has its own recoverable journal; an interrupted batch is never replayed blindly. */
+export async function assembleReleaseMaps(client, root, target, contracts, options = {}) {
+    if (contracts.length > 100 ||
+        new Set(contracts.map((contract) => `${contract.kind}:${contract.id}`)).size !==
+            contracts.length) {
+        throw new Error("Release maps require at most 100 unique contract identities");
+    }
+    const prepared = new Map();
+    for (const contract of contracts) {
+        const observation = await observeMapSources(root, contract);
+        const plan = buildMapDrawingPlan(contract, observation.detailMaps);
+        const drawing = await resolveMapDetails(root, drawingFromPlan(plan));
+        prepared.set(drawing.mapId, {
+            contract,
+            drawing,
+            width: plan.width,
+        });
+    }
+    const ordered = [];
+    const visiting = new Set();
+    const completed = new Set();
+    const visit = (id) => {
+        if (visiting.has(id)) {
+            throw new Error("Release detail-map dependencies contain a cycle");
+        }
+        if (completed.has(id)) {
+            return;
+        }
+        const current = prepared.get(id);
+        visiting.add(id);
+        for (const node of current.drawing.nodes.filter((node) => node.detail)) {
+            const detail = node.detail;
+            const child = prepared.get(detail.mapId);
+            if (!child || child.drawing.contractHash !== detail.contractHash) {
+                throw new Error("Every detail contract must be explicitly included at its pinned revision in the release");
+            }
+            visit(child.drawing.mapId);
+        }
+        visiting.delete(id);
+        completed.add(id);
+        ordered.push(id);
+    };
+    for (const id of prepared.keys()) {
+        visit(id);
+    }
+    const results = [];
+    const published = new Map();
+    let nextX = options.origin?.x ?? 0;
+    for (const id of ordered) {
+        const entry = prepared.get(id);
+        const contract = entry.contract;
+        const drawing = {
+            ...entry.drawing,
+            origin: {
+                x: nextX,
+                y: options.origin?.y ?? 0,
+            },
+            nodes: entry.drawing.nodes.map((node) => {
+                if (!node.detail) {
+                    return node;
+                }
+                const child = published.get(node.detail.mapId);
+                if (options.apply && !child?.projection.boardId) {
+                    throw new Error("Release child map has no verified native target");
+                }
+                return child?.projection.boardId
+                    ? {
+                        ...node,
+                        detail: {
+                            ...node.detail,
+                            fileId: target.fileId,
+                            pageId: target.pageId,
+                            frameId: child.projection.boardId,
+                        },
+                    }
+                    : node;
+            }),
+        };
+        const recovery = options.journals?.[drawing.mapId];
+        const publication = await publishMap(client, target, drawing, {
+            ...options,
+            expected: options.projections?.[drawing.mapId],
+            journal: {
+                root,
+                redact: options.redact,
+                ...recovery,
+            },
+        });
+        nextX += Math.max(entry.width, publication.projection.boardBounds?.width ?? 964) + 160;
+        published.set(drawing.mapId, publication);
+        results.push({
+            mapKind: contract.kind,
+            mapId: contract.id,
+            contractHash: drawing.contractHash,
+            publication,
+        });
+    }
+    return results;
+}

package/dist/map-penpot/snippets.d.ts

@@ -0,0 +1,4 @@
+import { type Snippet } from "../snippet.js";
+import type { MapDrawing, MapTarget, NativeMapProjection } from "./types.js";
+export declare function inspectMapSnippet(target: MapTarget, mapId: string): Snippet;
+export declare function publishMapSnippet(target: MapTarget, drawing: MapDrawing, expected: NativeMapProjection): Snippet;

package/dist/map-penpot/snippets.js

@@ -0,0 +1,164 @@
+import { nativeMapRoles, nativeMapTextEntries } from "./content.js";
+import { nativeMapIcons, defaultMapIcon } from "./icons.js";
+import { mapOriginLabels, mapOriginLegend } from "./status-labels.js";
+import { snippet } from "../snippet.js";
+const inspectSource = `
+if (penpot.currentFile.id !== CFG.target.fileId || penpot.currentPage.id !== CFG.target.pageId) throw new Error("Map file/page identity changed");
+const readMeta = shape => {
+  if (typeof shape.getSharedPluginData !== "function") throw new Error("Map metadata API unavailable");
+  const raw = shape.getSharedPluginData("penpair", "map");
+  if (!raw) return null;
+  try { return JSON.parse(raw); } catch { throw new Error("Malformed managed map metadata"); }
+};
+const readInteractions = shape => {
+  if (!Array.isArray(shape.interactions)) return null;
+  return shape.interactions.map(interaction => {
+    const destination = interaction.action?.destination;
+    const destinationId = destination?.id || null;
+    const destinationPageId = destinationId ? penpot.currentFile.pages.find(page => page.getShapeById(destinationId)?.id === destinationId)?.id || null : null;
+    const destinationMeta = destination ? readMeta(destination) : null;
+    return {trigger:interaction.trigger,type:interaction.action?.type || "unknown",destinationId,destinationPageId,destinationMapHash:destinationMeta?.contractHash || null,destinationMapId:destinationMeta?.mapId || null};
+  });
+};
+const all = [], queue = [...penpot.currentPage.root.children], visited = new Set();
+while (queue.length) {
+  const shape = queue.shift();
+  if (visited.has(shape.id)) throw new Error("Cyclic native hierarchy");
+  visited.add(shape.id); all.push(shape);
+  if (all.length > 20000) throw new Error("Page traversal exceeds map inspection limit");
+  if (shape.children) queue.push(...shape.children);
+}
+const boards = all.filter(shape => { const meta = readMeta(shape); return meta && meta.mapId === CFG.mapId && meta.role === "board"; });
+if (boards.length > 1) throw new Error("Duplicate managed map boards");
+const board = boards[0] || null;
+if (CFG.target.boardId && (!board || board.id !== CFG.target.boardId)) throw new Error("Managed map board identity changed");
+const conflicts = [], shapes = [], keys = new Set();
+if (board) {
+  const meta = readMeta(board);
+  if (meta.schemaVersion !== 1 || meta.owner !== "penpair") conflicts.push("Edited board ownership");
+  for (const shape of board.children) {
+    const child = readMeta(shape);
+    if (!child || child.owner !== "penpair" || child.schemaVersion !== 1 || child.mapId !== CFG.mapId) { conflicts.push("Unknown or edited ownership: " + shape.id); continue; }
+    if (!${JSON.stringify(nativeMapRoles)}.includes(child.role) || typeof child.logicalId !== "string" || !child.logicalId) { conflicts.push("Unknown managed role or identity: " + shape.id); continue; }
+    const key = child.role + ":" + child.logicalId;
+    if (keys.has(key)) conflicts.push("Duplicate logical ID: " + key);
+    keys.add(key);
+    if (shape.children && shape.children.length) conflicts.push("Unexpected nested content: " + shape.id);
+    shapes.push({shapeId:shape.id,logicalId:child.logicalId,role:child.role,iconKey:child.iconKey || null,interactions:readInteractions(shape),label:shape.type === "text" ? shape.characters : null,x:shape.x,y:shape.y,width:shape.width,height:shape.height,content:shape.type === "path" ? shape.content : null,appearance:{type:shape.type,name:shape.name,fills:shape.fills || [],strokes:shape.strokes || [],fontId:shape.fontId || null,fontFamily:shape.fontFamily || null,fontVariantId:shape.fontVariantId || null,fontSize:shape.fontSize || null,growType:shape.growType || null,borderRadiusTopLeft:shape.borderRadiusTopLeft ?? shape.borderRadius ?? null,borderRadiusTopRight:shape.borderRadiusTopRight ?? shape.borderRadius ?? null,borderRadiusBottomLeft:shape.borderRadiusBottomLeft ?? shape.borderRadius ?? null,borderRadiusBottomRight:shape.borderRadiusBottomRight ?? shape.borderRadius ?? null,opacity:shape.opacity ?? null,blendMode:shape.blendMode ?? null,blur:shape.blur || null},...(child.from ? {from:child.from,to:child.to} : {})});
+  }
+  const childIds = new Set(board.children.map(shape => shape.id));
+  for (const shape of all) { const child = readMeta(shape); if (shape.id !== board.id && child && child.mapId === CFG.mapId && !childIds.has(shape.id)) conflicts.push("Reparented managed shape: " + shape.id); }
+}
+const observation = {boardId:board ? board.id : null,boardBounds:board ? {x:board.x,y:board.y,width:board.width,height:board.height} : null,contractHash:board ? readMeta(board).contractHash : null,shapes,conflicts};
+`;
+export function inspectMapSnippet(target, mapId) {
+    return snippet("map-projection-inspect", `${inspectSource}\nreturn {ok:true,...observation};`, {
+        target,
+        mapId,
+    }, "read");
+}
+export function publishMapSnippet(target, drawing, expected) {
+    return snippet("map-projection-publish", `${inspectSource}
+if (conflicts.length || JSON.stringify(observation) !== JSON.stringify(CFG.expected)) throw new Error("Map changed after inspection; reconcile before publishing");
+const fontName = CFG.drawing.fontFamily || "Inter";
+const exactFonts = Array.isArray(penpot.fonts.all) ? penpot.fonts.all.filter(font => font.name === fontName) : [];
+if (exactFonts.length !== 1) throw new Error("Map font unavailable or ambiguous: " + fontName);
+const font = exactFonts[0];
+if (typeof font.applyToText !== "function" || !Array.isArray(font.variants)) throw new Error("Map font unavailable");
+const variants = font.variants.filter(variant => String(variant.fontWeight) === "400" && (variant.fontStyle || "normal") === "normal");
+if (variants.length !== 1) throw new Error("Map regular font variant unavailable or ambiguous");
+if (typeof penpot.currentPage.root.setSharedPluginData !== "function" || ["createBoard","createRectangle","createEllipse","createPath","createText"].some(method => typeof penpot[method] !== "function")) throw new Error("Required native map creation/metadata APIs unavailable");
+const detailBoards = new Map();
+for (const node of CFG.drawing.nodes.filter(node => node.detail)) {
+  const detail = node.detail;
+  if (detail.fileId !== CFG.target.fileId) throw new Error("Detail map target must be in the same pinned file");
+  const pages = penpot.currentFile.pages.filter(page => page.id === detail.pageId);
+  if (pages.length !== 1 || typeof pages[0].getShapeById !== "function") throw new Error("Detail map target page is missing or cannot be inspected");
+  const target = pages[0].getShapeById(detail.frameId);
+  const targetMeta = target ? readMeta(target) : null;
+  if (!target || target.type !== "board" || !targetMeta || targetMeta.owner !== "penpair" || targetMeta.role !== "board" || !detail.mapId || targetMeta.mapId !== detail.mapId || !detail.contractHash || targetMeta.contractHash !== detail.contractHash) throw new Error("Detail map target is not the existing pinned owned contract board");
+  if (typeof target.addInteraction !== "function" || typeof target.removeInteraction !== "function") throw new Error("Native detail interaction API is unavailable");
+  detailBoards.set(node.id,target);
+}
+let root = board;
+if (!root) { root = penpot.createBoard(); root.name = CFG.drawing.title; root.fills = [{fillColor:"#F8FAFC",fillOpacity:1}]; root.clipContent = false; root.x = CFG.drawing.origin?.x || 0; root.y = CFG.drawing.origin?.y || 0; root.resize(1600,1200); }
+const metadata = (shape, role, logicalId, extra = {}) => {
+  if (typeof shape.setSharedPluginData !== "function") throw new Error("Map metadata write API unavailable");
+  shape.setSharedPluginData("penpair", "map", JSON.stringify({schemaVersion:1,owner:"penpair",mapId:CFG.mapId,role,logicalId,...extra}));
+};
+metadata(root,"board",CFG.mapId,{contractHash:CFG.drawing.contractHash});
+const previous = new Map(shapes.map(shape => [shape.role + ":" + shape.logicalId,shape]));
+const retained = new Set();
+const get = (role,id,create) => { const prior = previous.get(role + ":" + id); const shape = prior ? penpot.currentPage.getShapeById(prior.shapeId) : create(); root.appendChild(shape); retained.add(shape.id);shape.opacity=1;shape.blendMode="normal"; metadata(shape,role,id); return shape; };
+const strongVariants = font.variants.filter(variant => ["600","700"].includes(String(variant.fontWeight)) && (variant.fontStyle || "normal") === "normal").sort((left,right)=>Number(left.fontWeight)-Number(right.fontWeight));
+const textShape = entry => {
+  const shape = get(entry.role,entry.logicalId,() => penpot.createText(entry.text || " "));
+  shape.characters = entry.text || " ";
+  font.applyToText(shape,entry.strong && strongVariants.length ? strongVariants[0] : variants[0]);
+  shape.fontSize = entry.fontSize; shape.resize(entry.width,entry.height); shape.growType = "auto-height";
+  shape.x=root.x+entry.x; shape.y=root.y+entry.y; shape.fills=[{fillColor:entry.color,fillOpacity:1}];
+  return shape;
+};
+const plannedNodes = CFG.drawing.nodes;
+const nodes = new Map(plannedNodes.map(node => [node.id,node]));
+for (const edge of CFG.drawing.edges) {
+  const from = nodes.get(edge.from), to = nodes.get(edge.to);
+  const shape = get("edge",edge.id,() => penpot.createPath());
+  const points = edge.points.map(point => ({x:root.x+point.x,y:root.y+point.y}));
+  shape.content = points.map((point,index) => (index ? "L" : "M")+point.x+" "+point.y).join(" ");
+  shape.fills=[]; shape.strokes=[{strokeColor:"#98A2B3",strokeWidth:1.25,strokeCapEnd:"line-arrow"}];
+  metadata(shape,"edge",edge.id,{from:edge.from,to:edge.to});
+}
+for (const node of plannedNodes) {
+  const shape = get("node",node.id,() => penpot.createRectangle());
+  shape.name=node.kind+": "+node.label;shape.resize(node.width,node.height);shape.x=root.x+node.x;shape.y=root.y+node.y;
+  shape.fills=[{fillColor:"#FFFFFF",fillOpacity:1}];shape.strokes=[{strokeColor:"#D0D5DD",strokeWidth:1}];shape.borderRadius=12;
+  const well = get("icon-well",node.id,() => penpot.createRectangle());well.resize(32,32);well.x=shape.x+16;well.y=shape.y+16;well.borderRadius=8;well.fills=[{fillColor:"#EEF2FF",fillOpacity:1}];well.strokes=[];
+  const iconKey=node.icon || CFG.iconDefaults[node.id];
+  const glyph=get("icon",node.id,()=>penpot.createPath());
+  glyph.content=CFG.iconPaths[iconKey].replace(/([ML])(-?[0-9.]+) (-?[0-9.]+)/g,(_all,command,x,y)=>command+(shape.x+24+Number(x)*16/24)+" "+(shape.y+24+Number(y)*16/24));
+  glyph.resize(16,16);glyph.x=shape.x+24;glyph.y=shape.y+24;
+  glyph.fills=[];glyph.strokes=[{strokeColor:"#5B5BD6",strokeWidth:1.6,strokeCapStart:"round",strokeCapEnd:"round",strokeJoinStyle:"round"}];metadata(glyph,"icon",node.id,{iconKey});
+  for(const [role,x] of [["port-in",shape.x],["port-out",shape.x+shape.width]]){
+    const port=get(role,node.id,()=>penpot.createEllipse());port.resize(8,8);port.x=x-4;port.y=shape.y+shape.height/2-4;port.fills=[{fillColor:"#FFFFFF",fillOpacity:1}];port.strokes=[{strokeColor:"#98A2B3",strokeWidth:1.25}];
+  }
+}
+for(const annotation of CFG.drawing.annotations || []){
+  const panel=get("annotation-panel",annotation.id,()=>penpot.createRectangle());panel.resize(annotation.width,annotation.height);panel.x=root.x+annotation.x;panel.y=root.y+annotation.y;panel.borderRadius=12;panel.fills=[{fillColor:"#FFFFFF",fillOpacity:1}];panel.strokes=[{strokeColor:"#E4E7EC",strokeWidth:1}];
+}
+for(const entry of CFG.textEntries) textShape(entry);
+for(const node of plannedNodes){
+  const clickableRoles=new Set(["node","label","summary","badge","icon-well","icon","port-in","port-out"]);
+  for(const id of retained){
+    const shape=penpot.currentPage.getShapeById(id);const info=readMeta(shape);
+    if(info.logicalId!==node.id || !clickableRoles.has(info.role))continue;
+    if(Array.isArray(shape.interactions))for(const interaction of [...shape.interactions])shape.removeInteraction(interaction);
+    if(node.detail)shape.addInteraction("click",{type:"navigate-to",destination:detailBoards.get(node.id)});
+  }
+}
+if (typeof penpot.waitForLayoutUpdate === "function") await penpot.waitForLayoutUpdate();
+const right = Math.max(900,...root.children.map(shape => shape.x-root.x+shape.width)) + 64;
+const bottom = Math.max(160,...root.children.map(shape => shape.y-root.y+shape.height)) + 64;
+root.resize(right,bottom);
+for (const prior of shapes) if (!retained.has(prior.shapeId)) penpot.currentPage.getShapeById(prior.shapeId).remove();
+return {ok:true,boardId:root.id};`, {
+        target,
+        mapId: drawing.mapId,
+        drawing,
+        textEntries: nativeMapTextEntries(drawing),
+        iconPaths: nativeMapIcons,
+        iconDefaults: Object.fromEntries(drawing.nodes.map((node) => [
+            node.id,
+            defaultMapIcon(node.kind),
+        ])),
+        originLabels: mapOriginLabels,
+        originLegend: mapOriginLegend,
+        expected: {
+            boardId: expected.boardId,
+            boardBounds: expected.boardBounds,
+            contractHash: expected.contractHash,
+            shapes: expected.shapes,
+            conflicts: expected.conflicts,
+        },
+    }, "write");
+}

package/dist/map-penpot/status-labels.d.ts

@@ -0,0 +1,7 @@
+export declare const mapOriginLabels: {
+    observed: string;
+    proposed: string;
+    "owner-decision": string;
+    unknown: string;
+};
+export declare const mapOriginLegend = "Origin: Observed \u00B7 Proposed \u00B7 Owner decision \u00B7 Unknown. Status labels describe evidence, not implementation acceptance.";

package/dist/map-penpot/status-labels.js

@@ -0,0 +1,7 @@
+export const mapOriginLabels = {
+    observed: "Observed",
+    proposed: "Proposed",
+    "owner-decision": "Owner decision",
+    unknown: "Unknown",
+};
+export const mapOriginLegend = "Origin: Observed · Proposed · Owner decision · Unknown. Status labels describe evidence, not implementation acceptance.";