@penpair/core 0.3.7 → 0.4.1

package/dist/map-penpot/import.js

@@ -0,0 +1,255 @@
+import { nativeMapShapeKeys, nativeMapTextEntries } from "./content.js";
+import { importNativeContent } from "./import-content.js";
+import { requireResolvedMapDetails } from "./details.js";
+import { mapOriginLabels, mapOriginLegend } from "./status-labels.js";
+import { hashMapContract } from "../maps/validation.js";
+import { createMapProposal } from "../maps/proposal.js";
+import { readMapPathPoints } from "./path-geometry.js";
+import { validateDrawing } from "./projection.js";
+export function importMapProposal(drawing, observed, baseline) {
+    validateDrawing(drawing);
+    requireResolvedMapDetails(drawing);
+    if (observed.mapId !== drawing.mapId || observed.contractHash !== drawing.contractHash) {
+        throw new Error("Projection does not match base contract");
+    }
+    const presentation = [];
+    const edgeChanges = [];
+    const findings = [
+        ...observed.conflicts,
+    ];
+    const expectedKeys = nativeMapShapeKeys(drawing);
+    for (const shape of observed.shapes) {
+        if (!expectedKeys.delete(`${shape.role}:${shape.logicalId}`) &&
+            !([
+                "summary",
+                "full-summary",
+                "description",
+            ].includes(shape.role) && drawing.nodes.some((node) => node.id === shape.logicalId)) &&
+            !([
+                "map-summary",
+                "map-goal",
+                "map-description",
+            ].includes(shape.role) && shape.logicalId === drawing.mapId)) {
+            findings.push(`Unmapped managed object requires reconciliation: ${shape.shapeId}`);
+        }
+    }
+    for (const missing of expectedKeys) {
+        if (![
+            "summary",
+            "full-summary",
+            "description",
+            "map-summary",
+            "map-description",
+        ].some((role) => missing.startsWith(role + ":"))) {
+            findings.push(`Missing managed object: ${missing}`);
+        }
+    }
+    if (drawing.nodes.some((node) => node.origin) &&
+        observed.shapes.find((shape) => shape.role === "legend")?.label !== mapOriginLegend) {
+        findings.push("Origin legend changed; reconcile against the canonical evidence contract");
+    }
+    for (const node of drawing.nodes) {
+        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)) ||
+                (!node.detail && clickable.interactions?.length)) {
+                findings.push(`Native interaction changed; reconcile the pinned detail contract: ${node.id}`);
+            }
+        }
+        if (node.origin) {
+            const status = mapOriginLabels[node.origin];
+            if (observed.shapes.find((shape) => shape.role === "badge" && shape.logicalId === node.id)
+                ?.label !== status) {
+                findings.push(`Origin badge changed; update evidence in canonical contract: ${node.id}`);
+            }
+        }
+        const labels = observed.shapes.filter((shape) => shape.role === "label" && shape.logicalId === node.id);
+        const card = observed.shapes.find((shape) => shape.role === "node" && shape.logicalId === node.id);
+        if (labels.length !== 1 || !card || !labels[0]?.label) {
+            findings.push(`Missing or ambiguous node: ${node.id}`);
+            continue;
+        }
+        presentation.push({
+            nodeId: node.id,
+            x: card.x,
+            y: card.y,
+            width: card.width,
+            height: card.height,
+        });
+    }
+    for (const edge of drawing.edges) {
+        const paths = observed.shapes.filter((shape) => shape.role === "edge" && shape.logicalId === edge.id);
+        const path = paths[0];
+        const previous = baseline?.shapes.find((shape) => shape.role === "edge" && shape.logicalId === edge.id);
+        const labels = observed.shapes.filter((shape) => shape.role === "edge-label" && shape.logicalId === edge.id);
+        if (paths.length !== 1 || labels.length > 1 || !path) {
+            findings.push(`Relationship needs explicit reconciliation: ${edge.id}`);
+            continue;
+        }
+        let from = path.from;
+        let to = path.to;
+        if (!previous || path.content !== previous.content) {
+            const vertices = readMapPathPoints(path.content);
+            const start = vertices?.[0];
+            const end = vertices?.at(-1);
+            const matchEndpoint = (coordinates, side) => observed.shapes.filter((shape) => shape.role === "node" &&
+                (((Math.abs(shape.x + (side === "from" ? shape.width : 0) - coordinates?.x) < 0.01 ||
+                    (side === "from" && Math.abs(shape.x - coordinates?.x) < 0.01)) &&
+                    Math.abs(shape.y + shape.height / 2 - coordinates?.y) < 0.01) ||
+                    (side === "to" &&
+                        Math.abs(shape.x + shape.width / 2 - coordinates?.x) < 0.01 &&
+                        Math.abs(shape.y - coordinates?.y) < 0.01)));
+            const validPath = vertices !== undefined;
+            const starts = validPath ? matchEndpoint(start, "from") : [];
+            const ends = validPath ? matchEndpoint(end, "to") : [];
+            if (starts.length !== 1 || ends.length !== 1) {
+                findings.push(`Relationship endpoints are ambiguous: ${edge.id}`);
+                continue;
+            }
+            from = starts[0]?.logicalId;
+            to = ends[0]?.logicalId;
+        }
+        if (!drawing.nodes.some((node) => node.id === from) ||
+            !drawing.nodes.some((node) => node.id === to)) {
+            findings.push(`Relationship references unknown nodes: ${edge.id}`);
+            continue;
+        }
+        const label = labels[0]?.label ?? "";
+        if (from !== edge.from || to !== edge.to || label !== edge.label) {
+            edgeChanges.push({
+                edgeId: edge.id,
+                from: from,
+                to: to,
+                label,
+            });
+        }
+    }
+    for (const entry of nativeMapTextEntries(drawing).filter((entry) => !entry.semantic &&
+        ![
+            "edge-label",
+            "badge",
+            "legend",
+        ].includes(entry.role))) {
+        if (observed.shapes.find((shape) => shape.role === entry.role && shape.logicalId === entry.logicalId)?.label !== entry.text) {
+            findings.push(`Derived annotation label changed: ${entry.role}:${entry.logicalId}`);
+        }
+    }
+    const content = importNativeContent(drawing, observed, findings);
+    return {
+        schemaVersion: 1,
+        kind: "native-map-proposal",
+        baseContractHash: drawing.contractHash,
+        observedProjectionHash: observed.fingerprint,
+        mapId: drawing.mapId,
+        ...(observed.shapes.find((shape) => shape.role === "title")?.label !== drawing.title
+            ? {
+                title: observed.shapes.find((shape) => shape.role === "title")?.label ?? drawing.title,
+            }
+            : {}),
+        ...content,
+        edgeChanges,
+        presentation,
+        findings,
+    };
+}
+/** Convert a native observation into the canonical reviewed proposal format. */
+export function nativeProposalToMapProposal(map, drawing, observed, baseline) {
+    if (hashMapContract(map) !== drawing.contractHash ||
+        (map.id !== drawing.mapId && `${map.kind}:${map.id}` !== drawing.mapId)) {
+        throw new Error("Native import requires the exact canonical base contract");
+    }
+    const imported = importMapProposal(drawing, observed, baseline);
+    const proposedMap = {
+        ...map,
+        title: imported.title ?? map.title,
+        ...(imported.metadataChanges?.goal !== undefined
+            ? {
+                goal: imported.metadataChanges.goal,
+            }
+            : {}),
+        nodes: map.nodes.map((node) => {
+            const change = imported.changes.find((change) => change.nodeId === node.id);
+            if (!change) {
+                return {
+                    ...node,
+                };
+            }
+            const next = {
+                ...node,
+                origin: "proposed",
+                ...(change.label !== undefined
+                    ? {
+                        label: change.label,
+                    }
+                    : {}),
+            };
+            for (const field of [
+                "summary",
+                "description",
+                "icon",
+            ]) {
+                if (change[field] === null) {
+                    delete next[field];
+                }
+                else if (change[field] !== undefined) {
+                    Object.assign(next, {
+                        [field]: change[field],
+                    });
+                }
+            }
+            return next;
+        }),
+        edges: map.edges.map((edge) => {
+            const change = imported.edgeChanges.find((change) => change.edgeId === edge.id);
+            return change
+                ? {
+                    ...edge,
+                    from: change.from,
+                    to: change.to,
+                    label: change.label,
+                    origin: "proposed",
+                }
+                : {
+                    ...edge,
+                };
+        }),
+        findings: [
+            ...map.findings,
+            ...imported.findings.map((message, index) => ({
+                id: `native-${observed.fingerprint.slice(0, 12)}-${index}`,
+                message,
+                severity: "blocking",
+                status: "open",
+            })),
+        ],
+    };
+    for (const field of [
+        "summary",
+        "description",
+    ]) {
+        const value = imported.metadataChanges?.[field];
+        if (value === null) {
+            delete proposedMap[field];
+        }
+        else if (value !== undefined) {
+            proposedMap[field] = value;
+        }
+    }
+    return createMapProposal(map, proposedMap, `Imported native map edits from projection ${observed.fingerprint}; presentation remains separate`);
+}

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

@@ -0,0 +1,11 @@
+export type * from "./types.js";
+export { drawingFromPlan, readProjection } from "./projection.js";
+export { publishMap } from "./publish.js";
+export { importMapProposal, nativeProposalToMapProposal } from "./import.js";
+export { inspectMapSnippet, publishMapSnippet } from "./snippets.js";
+export { assembleReleaseMaps, type ReleaseMapPublication } from "./release-maps.js";
+export { createMapPresentationProposal, validateMapPresentationProposal, acceptMapPresentationProposal, preserveMapPresentation, validateNativeMapProjection, type MapPresentationProposal, } from "./presentation.js";
+export { resolveMapDetails } from "./details.js";
+export { MapExportEvidenceError } from "./evidence-error.js";
+export { nativeMapTextEntries, nativeMapShapeKeys, type NativeMapTextEntry } from "./content.js";
+export { nativeMapIcons, defaultMapIcon } from "./icons.js";

package/dist/map-penpot/index.js

@@ -0,0 +1,10 @@
+export { drawingFromPlan, readProjection } from "./projection.js";
+export { publishMap } from "./publish.js";
+export { importMapProposal, nativeProposalToMapProposal } from "./import.js";
+export { inspectMapSnippet, publishMapSnippet } from "./snippets.js";
+export { assembleReleaseMaps } from "./release-maps.js";
+export { createMapPresentationProposal, validateMapPresentationProposal, acceptMapPresentationProposal, preserveMapPresentation, validateNativeMapProjection, } from "./presentation.js";
+export { resolveMapDetails } from "./details.js";
+export { MapExportEvidenceError } from "./evidence-error.js";
+export { nativeMapTextEntries, nativeMapShapeKeys } from "./content.js";
+export { nativeMapIcons, defaultMapIcon } from "./icons.js";

package/dist/map-penpot/path-geometry.d.ts

@@ -0,0 +1,5 @@
+/** Parse the absolute M/L subset emitted by Penpot, including compact/comma SVG normalization. */
+export declare function readMapPathPoints(content: string | null | undefined): Array<{
+    x: number;
+    y: number;
+}> | undefined;

package/dist/map-penpot/path-geometry.js

@@ -0,0 +1,51 @@
+/** Parse the absolute M/L subset emitted by Penpot, including compact/comma SVG normalization. */
+export function readMapPathPoints(content) {
+    if (typeof content !== "string" || content.length > 65536) {
+        return undefined;
+    }
+    let offset = 0;
+    const number = /[-+]?(?:\d+\.?\d*|\.\d+)(?:[eE][-+]?\d+)?/y;
+    const skipSeparators = () => {
+        while (offset < content.length && /[\s,]/.test(content[offset])) {
+            offset++;
+        }
+    };
+    const readCoordinate = () => {
+        skipSeparators();
+        number.lastIndex = offset;
+        const match = number.exec(content);
+        if (!match) {
+            return undefined;
+        }
+        offset = number.lastIndex;
+        const value = Number(match[0]);
+        return Number.isFinite(value) ? value : undefined;
+    };
+    const points = [];
+    while (offset < content.length) {
+        skipSeparators();
+        if (offset === content.length) {
+            break;
+        }
+        const command = content[offset];
+        if (command === "M" || command === "L") {
+            if (points.length === 0 ? command !== "M" : command !== "L") {
+                return undefined;
+            }
+            offset++;
+        }
+        else if (points.length === 0) {
+            return undefined;
+        }
+        const x = readCoordinate();
+        const y = readCoordinate();
+        if (x === undefined || y === undefined || points.length >= 32) {
+            return undefined;
+        }
+        points.push({
+            x,
+            y,
+        });
+    }
+    return points.length >= 2 ? points : undefined;
+}

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

@@ -0,0 +1,20 @@
+import type { MapContract } from "../maps/types.js";
+import type { MapDrawing, NativeMapProjection } from "./types.js";
+export interface MapPresentationProposal {
+    schemaVersion: 1;
+    kind: "map-presentation-proposal";
+    mapKind: MapContract["kind"];
+    mapId: string;
+    baseContractHash: string;
+    baselineFingerprint: string;
+    observedProjectionHash: string;
+    projection: NativeMapProjection;
+    hash: string;
+}
+export declare function validateNativeMapProjection(raw: unknown): NativeMapProjection;
+export declare function validateMapPresentationProposal(raw: unknown): MapPresentationProposal;
+export declare function createMapPresentationProposal(map: MapContract, drawing: MapDrawing, observed: NativeMapProjection, baseline: NativeMapProjection): MapPresentationProposal;
+/** The caller must independently observe the live projection before adopting this saved evidence. */
+export declare function acceptMapPresentationProposal(current: MapContract, baseline: NativeMapProjection, raw: unknown, resolvedDrawing?: MapDrawing): NativeMapProjection;
+/** Reuse accepted node geometry while preserving the new contract's semantic graph. */
+export declare function preserveMapPresentation(drawing: MapDrawing, savedProjection: NativeMapProjection): MapDrawing;

package/dist/map-penpot/presentation.js

@@ -0,0 +1,205 @@
+import { observationHash } from "../journal.js";
+import { routeMapEdges, mapDrawingGeometryProblems } from "../maps/layout.js";
+import { buildMapDrawingPlan } from "../maps/render.js";
+import { hashMapContract } from "../maps/validation.js";
+import { importMapProposal } from "./import.js";
+import { drawingFromPlan, projection, validateDrawing } from "./projection.js";
+export function validateNativeMapProjection(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new Error("Saved map projection must be an object");
+    }
+    const record = raw;
+    if (record.schemaVersion !== 1 ||
+        record.kind !== "native-map-projection" ||
+        typeof record.fileId !== "string" ||
+        !record.fileId ||
+        typeof record.pageId !== "string" ||
+        !record.pageId ||
+        typeof record.mapId !== "string" ||
+        !record.mapId ||
+        typeof record.fingerprint !== "string") {
+        throw new Error("Saved map projection is missing identity or fingerprint");
+    }
+    const checked = projection({
+        fileId: record.fileId,
+        pageId: record.pageId,
+    }, record.mapId, record);
+    if (checked.fingerprint !== record.fingerprint) {
+        throw new Error("Saved map projection fingerprint differs from its observations");
+    }
+    return structuredClone(checked);
+}
+function sameMap(left, right) {
+    return (left.fileId === right.fileId &&
+        left.pageId === right.pageId &&
+        left.boardId === right.boardId &&
+        left.mapId === right.mapId);
+}
+export function validateMapPresentationProposal(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new Error("Map presentation proposal must be an object");
+    }
+    const record = raw;
+    if (record.schemaVersion !== 1 ||
+        record.kind !== "map-presentation-proposal" ||
+        ![
+            "journey-map",
+            "integration-map",
+        ].includes(String(record.mapKind)) ||
+        typeof record.mapId !== "string" ||
+        !record.mapId ||
+        [
+            record.baseContractHash,
+            record.baselineFingerprint,
+            record.observedProjectionHash,
+            record.hash,
+        ].some((hash) => typeof hash !== "string" || !/^[a-f0-9]{64}$/.test(hash))) {
+        throw new Error("Unsupported map presentation proposal or missing hashes");
+    }
+    const observed = validateNativeMapProjection(record.projection);
+    if (observed.fingerprint !== record.observedProjectionHash ||
+        observed.contractHash !== record.baseContractHash ||
+        !observed.boardId ||
+        observed.conflicts.length) {
+        throw new Error("Presentation proposal observations conflict with their base contract");
+    }
+    const { hash, ...body } = record;
+    if (hash !== observationHash(body)) {
+        throw new Error("Map presentation proposal record hash differs");
+    }
+    return structuredClone(record);
+}
+export function createMapPresentationProposal(map, drawing, observed, baseline) {
+    const baseHash = hashMapContract(map);
+    const before = validateNativeMapProjection(baseline);
+    const after = validateNativeMapProjection(observed);
+    if (drawing.contractHash !== baseHash ||
+        before.contractHash !== baseHash ||
+        after.contractHash !== baseHash ||
+        !sameMap(before, after) ||
+        before.fingerprint === after.fingerprint) {
+        throw new Error("Presentation proposal requires a changed projection of the same exact contract and board");
+    }
+    const semantic = importMapProposal(drawing, after, before);
+    if (semantic.metadataChanges ||
+        semantic.changes.length ||
+        semantic.edgeChanges.length ||
+        semantic.title !== undefined ||
+        semantic.findings.length ||
+        before.conflicts.length) {
+        throw new Error("Semantic edits or unresolved findings require a canonical map proposal");
+    }
+    const priorShapes = new Map(before.shapes.map((shape) => [
+        shape.shapeId,
+        shape,
+    ]));
+    if (priorShapes.size !== after.shapes.length ||
+        after.shapes.some((shape) => {
+            const prior = priorShapes.get(shape.shapeId);
+            return (!prior ||
+                prior.role !== shape.role ||
+                prior.logicalId !== shape.logicalId ||
+                observationHash(prior.appearance) !== observationHash(shape.appearance));
+        })) {
+        throw new Error("Presentation adoption supports geometry edits of existing managed objects; style or ownership changes need reconciliation");
+    }
+    const body = {
+        schemaVersion: 1,
+        kind: "map-presentation-proposal",
+        mapKind: map.kind,
+        mapId: map.id,
+        baseContractHash: baseHash,
+        baselineFingerprint: before.fingerprint,
+        observedProjectionHash: after.fingerprint,
+        projection: after,
+    };
+    return validateMapPresentationProposal({
+        ...body,
+        hash: observationHash(body),
+    });
+}
+/** The caller must independently observe the live projection before adopting this saved evidence. */
+export function acceptMapPresentationProposal(current, baseline, raw, resolvedDrawing) {
+    const proposal = validateMapPresentationProposal(raw);
+    const before = validateNativeMapProjection(baseline);
+    if (proposal.mapId !== current.id ||
+        proposal.mapKind !== current.kind ||
+        hashMapContract(current) !== proposal.baseContractHash ||
+        before.contractHash !== proposal.baseContractHash ||
+        before.fingerprint !== proposal.baselineFingerprint ||
+        !sameMap(before, proposal.projection)) {
+        throw new Error("Presentation proposal is stale or belongs to another map");
+    }
+    const revalidated = createMapPresentationProposal(current, resolvedDrawing ?? drawingFromPlan(buildMapDrawingPlan(current)), proposal.projection, before);
+    if (revalidated.hash !== proposal.hash) {
+        throw new Error("Presentation proposal contains unsupported changes or metadata");
+    }
+    return structuredClone(proposal.projection);
+}
+/** Reuse accepted node geometry while preserving the new contract's semantic graph. */
+export function preserveMapPresentation(drawing, savedProjection) {
+    validateDrawing(drawing);
+    const saved = validateNativeMapProjection(savedProjection);
+    if (saved.mapId !== drawing.mapId || !saved.boardBounds || saved.conflicts.length) {
+        throw new Error("Cannot preserve presentation from a different or conflicted map");
+    }
+    const bounds = saved.boardBounds;
+    const nodes = drawing.nodes.map((node) => {
+        const cards = saved.shapes.filter((shape) => shape.role === "node" && shape.logicalId === node.id);
+        const card = cards[0];
+        if (!card) {
+            return {
+                ...node,
+            };
+        }
+        const appearance = card.appearance;
+        if (cards.length !== 1 ||
+            typeof appearance?.name !== "string" ||
+            !appearance.name.startsWith(`${node.kind}: `)) {
+            throw new Error(`Node kind changed or presentation is ambiguous: ${node.id}`);
+        }
+        return {
+            ...node,
+            x: card.x - bounds.x,
+            y: card.y - bounds.y,
+            width: card.width,
+            height: card.height,
+        };
+    });
+    const edges = routeMapEdges(nodes, drawing.edges);
+    const problems = mapDrawingGeometryProblems(nodes, edges);
+    if (problems.length) {
+        throw new Error(`Preserved map layout needs reconciliation: ${problems.join("; ")}`);
+    }
+    const flowBottom = (flow) => Math.max(0, ...flow.nodes.map((node) => node.y + node.height), ...flow.edges.flatMap((edge) => [
+        ...(edge.points ?? []).map((point) => point.y),
+        ...(edge.labelBox
+            ? [
+                edge.labelBox.y + edge.labelBox.height,
+            ]
+            : []),
+    ]));
+    const noteOffset = Math.max(0, flowBottom({
+        nodes,
+        edges,
+    }) - flowBottom(drawing));
+    const preserved = {
+        ...drawing,
+        ...(drawing.annotations
+            ? {
+                annotations: drawing.annotations.map((annotation) => ({
+                    ...annotation,
+                    y: annotation.y + noteOffset,
+                })),
+            }
+            : {}),
+        origin: {
+            x: bounds.x,
+            y: bounds.y,
+        },
+        nodes,
+        edges,
+    };
+    validateDrawing(preserved);
+    return preserved;
+}

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

@@ -0,0 +1,8 @@
+import type { PenpotToolClient } from "../client.js";
+import { type SnippetResult } from "../snippet.js";
+import type { MapDrawingPlan } from "../maps/types.js";
+import type { MapDrawing, MapTarget, NativeMapProjection, ProjectionReadOptions } from "./types.js";
+export declare function drawingFromPlan(plan: MapDrawingPlan): MapDrawing;
+export declare function validateDrawing(drawing: MapDrawing): void;
+export declare function projection(target: MapTarget, mapId: string, result: SnippetResult): NativeMapProjection;
+export declare function readProjection(client: PenpotToolClient, target: MapTarget, mapId: string, options?: ProjectionReadOptions): Promise<NativeMapProjection>;