@penpair/core 0.3.7 → 0.4.0

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>;

package/dist/map-penpot/projection.js

@@ -0,0 +1,176 @@
+import { nativeMapIcons } from "./icons.js";
+import { validateMapDrawingContent } from "./content-validation.js";
+import { nativeMapRoles } from "./content.js";
+import { observationHash } from "../journal.js";
+import { selectPage, withPageSession } from "../page-session.js";
+import { runSnippet } from "../snippet.js";
+import { inspectMapSnippet } from "./snippets.js";
+export function drawingFromPlan(plan) {
+    if (!plan.complete) {
+        throw new Error(`Map requires smaller detail boards: ${plan.reasons.join("; ")}`);
+    }
+    return {
+        mapId: `${plan.mapKind}:${plan.mapId}`,
+        contractHash: plan.mapHash,
+        title: plan.title,
+        goal: plan.goal,
+        ...(plan.summary !== undefined
+            ? {
+                summary: plan.summary,
+            }
+            : {}),
+        ...(plan.description !== undefined
+            ? {
+                description: plan.description,
+            }
+            : {}),
+        ...(plan.headerSummary !== undefined
+            ? {
+                headerSummary: plan.headerSummary,
+            }
+            : {}),
+        header: plan.header,
+        annotations: plan.annotations,
+        fontFamily: plan.fontFamily,
+        nodes: plan.nodes,
+        edges: plan.edges,
+    };
+}
+export function validateDrawing(drawing) {
+    validateMapDrawingContent(drawing);
+    if (!drawing.mapId ||
+        !/^[a-f0-9]{64}$/.test(drawing.contractHash) ||
+        !drawing.title ||
+        drawing.title.length > 1000) {
+        throw new Error("Map identity, title and SHA-256 contract hash are required");
+    }
+    if (drawing.nodes.length > 1000 || drawing.edges.length > 2000) {
+        throw new Error("Map exceeds graph limits");
+    }
+    if (drawing.origin &&
+        ![
+            drawing.origin.x,
+            drawing.origin.y,
+        ].every(Number.isFinite)) {
+        throw new Error("Map origin must be finite");
+    }
+    const identifiers = new Set(drawing.nodes.map((node) => node.id));
+    if (identifiers.size !== drawing.nodes.length ||
+        drawing.nodes.some((node) => !node.id ||
+            (node.icon !== undefined && !Object.hasOwn(nativeMapIcons, node.icon)) ||
+            (node.summary !== undefined &&
+                (typeof node.summary !== "string" || node.summary.length > 240)) ||
+            (node.description !== undefined &&
+                (typeof node.description !== "string" || node.description.length > 4000)) ||
+            (node.detail !== undefined &&
+                (node.kind !== "detail-link" ||
+                    !node.detail.fileId ||
+                    !node.detail.pageId ||
+                    !node.detail.frameId ||
+                    !node.detail.path ||
+                    !/^[a-f0-9]{64}$/.test(node.detail.sha256))) ||
+            (node.origin !== undefined &&
+                ![
+                    "observed",
+                    "proposed",
+                    "owner-decision",
+                    "unknown",
+                ].includes(node.origin)) ||
+            !node.label ||
+            node.label.length > 4000 ||
+            ![
+                node.x,
+                node.y,
+                node.width,
+                node.height,
+            ].every(Number.isFinite) ||
+            node.width < 64 ||
+            node.height < 32)) {
+        throw new Error("Map nodes need unique IDs, bounded labels and finite positive geometry");
+    }
+    if (new Set(drawing.edges.map((edge) => edge.id)).size !== drawing.edges.length ||
+        drawing.edges.some((edge) => !edge.id ||
+            !identifiers.has(edge.from) ||
+            !identifiers.has(edge.to) ||
+            typeof edge.label !== "string" ||
+            edge.label.length > 4000 ||
+            (edge.labelBox !== undefined &&
+                (![
+                    edge.labelBox.x,
+                    edge.labelBox.y,
+                    edge.labelBox.width,
+                    edge.labelBox.height,
+                ].every(Number.isFinite) ||
+                    edge.labelBox.width <= 0 ||
+                    edge.labelBox.height <= 0)) ||
+            (edge.points !== undefined &&
+                (!Array.isArray(edge.points) ||
+                    edge.points.length < 2 ||
+                    edge.points.length > 32 ||
+                    edge.points.some((point) => ![
+                        point.x,
+                        point.y,
+                    ].every(Number.isFinite)))))) {
+        throw new Error("Map edges need unique IDs and existing endpoints");
+    }
+}
+export function projection(target, mapId, result) {
+    if (!Array.isArray(result.shapes) ||
+        !Array.isArray(result.conflicts) ||
+        !(result.boardId === null || typeof result.boardId === "string") ||
+        !(result.boardBounds === null ||
+            (typeof result.boardBounds === "object" &&
+                result.boardBounds &&
+                [
+                    "x",
+                    "y",
+                    "width",
+                    "height",
+                ].every((key) => Number.isFinite(result.boardBounds[key])))) ||
+        !(result.contractHash === null || typeof result.contractHash === "string")) {
+        throw new Error("Native map inspection returned incomplete evidence");
+    }
+    if (result.shapes.some((shape) => !shape ||
+        typeof shape !== "object" ||
+        typeof shape.shapeId !== "string" ||
+        typeof shape.logicalId !== "string" ||
+        !nativeMapRoles.includes(shape.role) ||
+        ![
+            shape.x,
+            shape.y,
+            shape.width,
+            shape.height,
+        ].every(Number.isFinite) ||
+        !(shape.label === null || typeof shape.label === "string") ||
+        !(shape.content === null || typeof shape.content === "string")) ||
+        result.conflicts.some((conflict) => typeof conflict !== "string")) {
+        throw new Error("Native map inspection returned malformed shape evidence");
+    }
+    const observed = {
+        boardId: result.boardId,
+        boardBounds: result.boardBounds,
+        contractHash: result.contractHash,
+        shapes: result.shapes,
+        conflicts: result.conflicts,
+    };
+    return {
+        schemaVersion: 1,
+        kind: "native-map-projection",
+        ...target,
+        boardId: result.boardId,
+        boardBounds: result.boardBounds,
+        mapId,
+        contractHash: result.contractHash,
+        fingerprint: observationHash(observed),
+        shapes: result.shapes,
+        conflicts: result.conflicts,
+    };
+}
+export async function readProjection(client, target, mapId, options = {}) {
+    return withPageSession(client, async () => {
+        await selectPage(client, {
+            id: target.pageId,
+        }, options);
+        return projection(target, mapId, await runSnippet(client, inspectMapSnippet(target, mapId), options));
+    });
+}

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

@@ -0,0 +1,4 @@
+import type { PenpotToolClient } from "../client.js";
+import type { MapDrawing, MapTarget, NativeMapProjection, PublishMapOptions, PublishMapResult } from "./types.js";
+export declare function verificationProblems(drawing: MapDrawing, observed: NativeMapProjection): string[];
+export declare function publishMap(client: PenpotToolClient, target: MapTarget, drawing: MapDrawing, options?: PublishMapOptions): Promise<PublishMapResult>;