@penpair/core 0.3.7 → 0.4.0

package/dist/map-penpot/import-content.d.ts

@@ -0,0 +1,2 @@
+import type { MapDrawing, NativeMapProjection, NativeMapProposal } from "./types.js";
+export declare function importNativeContent(drawing: MapDrawing, observed: NativeMapProjection, findings: string[]): Pick<NativeMapProposal, "changes" | "metadataChanges">;

package/dist/map-penpot/import-content.js

@@ -0,0 +1,150 @@
+import { nativeMapTextEntries } from "./content.js";
+import { defaultMapIcon, identifyMapIcon } from "./icons.js";
+export function importNativeContent(drawing, observed, findings) {
+    const entries = nativeMapTextEntries(drawing);
+    const changes = [];
+    const metadataChanges = {};
+    const read = (scope, field, nodeId) => {
+        const relevant = entries.filter((entry) => entry.semantic?.scope === scope &&
+            entry.semantic.field === field &&
+            entry.semantic.nodeId === nodeId);
+        const changed = relevant.flatMap((entry) => {
+            const actual = observed.shapes.find((shape) => shape.role === entry.role && shape.logicalId === entry.logicalId);
+            const text = actual?.label?.trim() ?? "";
+            return text !== entry.text
+                ? [
+                    {
+                        text,
+                        compact: entry.semantic?.compact === true,
+                    },
+                ]
+                : [];
+        });
+        if (!relevant.length) {
+            const roles = scope === "map"
+                ? field === "goal"
+                    ? [
+                        "map-goal",
+                    ]
+                    : field === "summary"
+                        ? [
+                            "map-summary",
+                        ]
+                        : [
+                            "map-description",
+                        ]
+                : field === "label"
+                    ? [
+                        "label",
+                        "full-label",
+                    ]
+                    : field === "summary"
+                        ? [
+                            "summary",
+                            "full-summary",
+                        ]
+                        : [
+                            "description",
+                        ];
+            const actual = observed.shapes.find((shape) => roles.includes(shape.role) &&
+                shape.logicalId === (nodeId ?? drawing.mapId) &&
+                !entries.some((entry) => entry.role === shape.role &&
+                    entry.logicalId === shape.logicalId &&
+                    entry.semantic &&
+                    entry.semantic.field !== field));
+            return actual?.label?.trim() || undefined;
+        }
+        if (!changed.length) {
+            return undefined;
+        }
+        const full = changed.find((change) => !change.compact);
+        const selected = full ?? changed[0];
+        if (selected.compact && selected.text.endsWith("…")) {
+            findings.push(`Edit the full ${field} annotation for ${nodeId ?? drawing.mapId}; compact text is incomplete`);
+            return undefined;
+        }
+        if (changed.some((change) => change.text !== selected.text && !selected.text.startsWith(change.text.replace(/…$/, "")))) {
+            findings.push(`Conflicting compact/full ${field} edits: ${nodeId ?? drawing.mapId}`);
+        }
+        return selected.text || null;
+    };
+    for (const field of [
+        "title",
+        "goal",
+        "summary",
+        "description",
+    ]) {
+        const value = read("map", field);
+        if (value === undefined) {
+            continue;
+        }
+        if (field === "goal" || field === "title") {
+            if (!value) {
+                findings.push("Map goal cannot be empty");
+            }
+            else {
+                metadataChanges[field] = value;
+            }
+        }
+        else {
+            metadataChanges[field] = value;
+        }
+    }
+    for (const node of drawing.nodes) {
+        const change = {
+            nodeId: node.id,
+        };
+        for (const field of [
+            "label",
+            "summary",
+            "description",
+        ]) {
+            let value = read("node", field, node.id);
+            if (value === undefined) {
+                continue;
+            }
+            if (field === "label") {
+                if (!value) {
+                    findings.push(`Node title cannot be empty: ${node.id}`);
+                    continue;
+                }
+                if (node.cardTitle === undefined) {
+                    value =
+                        node.kind === "decision"
+                            ? value.replace(/^Decision: /, "")
+                            : node.kind === "detail-link"
+                                ? value.replace(/^Details: /, "")
+                                : value;
+                }
+                change.label = value;
+            }
+            else {
+                change[field] = value;
+            }
+        }
+        const icon = observed.shapes.find((shape) => shape.role === "icon" && shape.logicalId === node.id);
+        const key = icon ? identifyMapIcon(icon) : undefined;
+        if (!key) {
+            findings.push(`Unrecognized or missing native icon: ${node.id}`);
+        }
+        else if (icon?.iconKey &&
+            icon.iconKey !== key &&
+            icon.iconKey !== (node.icon ?? defaultMapIcon(node.kind))) {
+            findings.push(`Icon metadata and glyph disagree: ${node.id}`);
+        }
+        else if (key !== (node.icon ?? defaultMapIcon(node.kind))) {
+            change.icon = key;
+        }
+        if (Object.keys(change).length > 1) {
+            changes.push(change);
+        }
+    }
+    return {
+        changes,
+        ...(Object.keys(metadataChanges).length
+            ? {
+                metadataChanges,
+            }
+            : {}),
+    };
+}

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

@@ -0,0 +1,5 @@
+import type { MapContract, MapProposal } from "../maps/types.js";
+import type { MapDrawing, NativeMapProjection, NativeMapProposal } from "./types.js";
+export declare function importMapProposal(drawing: MapDrawing, observed: NativeMapProjection, baseline?: NativeMapProjection): NativeMapProposal;
+/** Convert a native observation into the canonical reviewed proposal format. */
+export declare function nativeProposalToMapProposal(map: MapContract, drawing: MapDrawing, observed: NativeMapProjection, baseline?: NativeMapProjection): MapProposal;

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;