@penpair/core 0.3.7 → 0.4.0

package/dist/maps/layout.js

@@ -0,0 +1,364 @@
+function boxesOverlap(left, right) {
+    return (left.x < right.x + right.width &&
+        right.x < left.x + left.width &&
+        left.y < right.y + right.height &&
+        right.y < left.y + left.height);
+}
+function segmentCrossesBox(from, to, box) {
+    if (from.x === to.x) {
+        return (from.x > box.x &&
+            from.x < box.x + box.width &&
+            Math.max(from.y, to.y) > box.y &&
+            Math.min(from.y, to.y) < box.y + box.height);
+    }
+    if (from.y === to.y) {
+        return (from.y > box.y &&
+            from.y < box.y + box.height &&
+            Math.max(from.x, to.x) > box.x &&
+            Math.min(from.x, to.x) < box.x + box.width);
+    }
+    return true;
+}
+export function mapDrawingGeometryProblems(nodes, edges) {
+    const problems = [];
+    const verticalTracks = new Map();
+    for (const node of nodes) {
+        if (node.x < 0 || node.y < 160) {
+            problems.push(`Card ${node.id} intrudes into the title/legend or outside the board`);
+        }
+        if (nodes.some((other) => other.id !== node.id && boxesOverlap(node, other))) {
+            problems.push(`Card ${node.id} overlaps another card`);
+        }
+    }
+    for (const edge of edges) {
+        if (edge.labelBox.x < 0 ||
+            edge.labelBox.y < 160 ||
+            nodes.some((node) => boxesOverlap(edge.labelBox, node))) {
+            problems.push(`Edge label ${edge.id} overlaps a card/header or leaves the board`);
+        }
+        if (edges.some((other) => other.id !== edge.id && boxesOverlap(edge.labelBox, other.labelBox))) {
+            problems.push(`Edge label ${edge.id} overlaps another edge label`);
+        }
+        for (let index = 1; index < edge.points.length; index++) {
+            const from = edge.points[index - 1];
+            const to = edge.points[index];
+            if (from.x === to.x && from.y !== to.y) {
+                const low = Math.min(from.y, to.y);
+                const high = Math.max(from.y, to.y);
+                const track = verticalTracks.get(from.x) ?? [];
+                if (track.some((other) => other.id !== edge.id && other.low < high && low < other.high)) {
+                    problems.push(`Connectors share an ambiguous vertical track: ${edge.id}`);
+                }
+                track.push({
+                    id: edge.id,
+                    low,
+                    high,
+                });
+                verticalTracks.set(from.x, track);
+            }
+            if (nodes.some((node) => segmentCrossesBox(from, to, node)) ||
+                edges.some((other) => segmentCrossesBox(from, to, other.labelBox))) {
+                problems.push(`Connector ${edge.id} crosses a card or label`);
+                break;
+            }
+        }
+        if (problems.length >= 20) {
+            break;
+        }
+    }
+    return [
+        ...new Set(problems),
+    ].slice(0, 20);
+}
+export function mapLabelHeight(text, width) {
+    const charactersPerLine = Math.max(1, Math.floor(width / 16));
+    const lines = text
+        .split(/\r?\n/)
+        .reduce((total, line) => total + Math.max(1, Math.ceil(line.length / charactersPerLine)), 0);
+    return lines * 24 + 16;
+}
+export function mapEdgeLabelWidth(label) {
+    return Math.max(80, Math.min(240, Math.max(...label.split(/\r?\n/).map((line) => line.length)) * 7 + 16));
+}
+/** Labels occupy dedicated gaps; routes stay outside those boxes and all card interiors. */
+export function routeMapEdges(nodes, edges) {
+    const byId = new Map(nodes.map((node) => [
+        node.id,
+        node,
+    ]));
+    const columns = [
+        ...new Set(nodes.map((node) => node.x)),
+    ].sort((left, right) => left - right);
+    const corridorEnds = new Map();
+    const portTracks = new Map();
+    const takeTrack = (key) => {
+        const track = portTracks.get(key) ?? 0;
+        portTracks.set(key, track + 1);
+        return track;
+    };
+    const pending = [];
+    const routed = [];
+    for (const edge of [
+        ...edges,
+    ].sort((left, right) => {
+        const aligned = (entry) => {
+            const from = byId.get(entry.from);
+            const to = byId.get(entry.to);
+            return (to.x > from.x &&
+                columns.indexOf(to.x) === columns.indexOf(from.x) + 1 &&
+                from.y + from.height / 2 === to.y + to.height / 2);
+        };
+        return (Number(!aligned(left)) - Number(!aligned(right)) ||
+            (left.id < right.id ? -1 : left.id > right.id ? 1 : 0));
+    })) {
+        const from = byId.get(edge.from);
+        const to = byId.get(edge.to);
+        if (!from || !to) {
+            throw new Error("Cannot route an edge with a missing node");
+        }
+        const sourceColumn = columns.indexOf(from.x);
+        const targetColumn = columns.indexOf(to.x);
+        if (targetColumn > sourceColumn + 1 || targetColumn < sourceColumn) {
+            pending.push({
+                edge,
+                from,
+                to,
+            });
+            continue;
+        }
+        const cyclic = targetColumn === sourceColumn;
+        const labelWidth = mapEdgeLabelWidth(edge.label);
+        const labelX = cyclic
+            ? from.x - labelWidth - 96
+            : (from.x + from.width + to.x - labelWidth) / 2;
+        const corridorKey = cyclic ? -from.x : from.x;
+        const sourceTrack = takeTrack(`${cyclic ? "left" : "right"}:${cyclic ? from.x : from.x + from.width}`);
+        const targetTrack = takeTrack(`left:${to.x}`);
+        const labelHeight = mapLabelHeight(edge.label, labelWidth);
+        const naturalY = to.y + to.height / 2 - labelHeight - 12;
+        const direct = !cyclic &&
+            from.y + from.height / 2 === to.y + to.height / 2 &&
+            naturalY >= 160 &&
+            !routed.some((entry) => boxesOverlap(entry.labelBox, {
+                x: labelX,
+                y: naturalY,
+                width: labelWidth,
+                height: labelHeight,
+            }));
+        const labelBox = {
+            x: labelX,
+            y: direct
+                ? naturalY
+                : Math.max(naturalY, corridorEnds.get(corridorKey) ??
+                    Math.max(180, Math.min(...nodes.map((node) => node.y)))),
+            width: labelWidth,
+            height: labelHeight,
+        };
+        corridorEnds.set(corridorKey, labelBox.y + labelBox.height + 80);
+        const routeY = labelBox.y + labelBox.height + 16;
+        const start = {
+            x: cyclic ? from.x : from.x + from.width,
+            y: from.y + from.height / 2,
+        };
+        const finish = {
+            x: to.x,
+            y: to.y + to.height / 2,
+        };
+        const points = direct
+            ? [
+                start,
+                finish,
+            ]
+            : cyclic
+                ? [
+                    start,
+                    {
+                        x: from.x - 24 - sourceTrack * 8,
+                        y: start.y,
+                    },
+                    {
+                        x: from.x - 24 - sourceTrack * 8,
+                        y: routeY,
+                    },
+                    {
+                        x: labelBox.x - 16,
+                        y: routeY,
+                    },
+                    {
+                        x: labelBox.x - 16,
+                        y: routeY + 20,
+                    },
+                    {
+                        x: to.x - 24 - targetTrack * 8,
+                        y: routeY + 20,
+                    },
+                    {
+                        x: to.x - 24 - targetTrack * 8,
+                        y: finish.y,
+                    },
+                    finish,
+                ]
+                : [
+                    start,
+                    {
+                        x: start.x + 24 + sourceTrack * 8,
+                        y: start.y,
+                    },
+                    {
+                        x: start.x + 24 + sourceTrack * 8,
+                        y: routeY,
+                    },
+                    {
+                        x: finish.x - 24 - targetTrack * 8,
+                        y: routeY,
+                    },
+                    {
+                        x: finish.x - 24 - targetTrack * 8,
+                        y: finish.y,
+                    },
+                    finish,
+                ];
+        routed.push({
+            ...edge,
+            points,
+            labelBox,
+        });
+    }
+    let bottom = Math.max(180, ...nodes.map((node) => node.y + node.height), ...corridorEnds.values()) + 100;
+    for (const { edge, from, to } of pending) {
+        const sourceTrack = takeTrack(`right:${from.x + from.width}`);
+        const targetTrack = takeTrack(`left:${to.x}`);
+        const labelWidth = mapEdgeLabelWidth(edge.label);
+        const labelBox = {
+            x: Math.min(from.x, to.x) + Math.max(from.width, to.width) + 32,
+            y: bottom,
+            width: labelWidth,
+            height: mapLabelHeight(edge.label, labelWidth),
+        };
+        const routeY = labelBox.y + labelBox.height + 16;
+        const start = {
+            x: from.x + from.width,
+            y: from.y + from.height / 2,
+        };
+        const finish = {
+            x: to.x,
+            y: to.y + to.height / 2,
+        };
+        routed.push({
+            ...edge,
+            labelBox,
+            points: [
+                start,
+                {
+                    x: start.x + 24 + sourceTrack * 8,
+                    y: start.y,
+                },
+                {
+                    x: start.x + 24 + sourceTrack * 8,
+                    y: routeY,
+                },
+                {
+                    x: finish.x - 24 - targetTrack * 8,
+                    y: routeY,
+                },
+                {
+                    x: finish.x - 24 - targetTrack * 8,
+                    y: finish.y,
+                },
+                finish,
+            ],
+        });
+        bottom = routeY + 80;
+    }
+    return routed.sort((left, right) => (left.id < right.id ? -1 : left.id > right.id ? 1 : 0));
+}
+/** Ignore DFS return edges for placement only; every connector remains in the drawing. */
+export function mapNodeLayers(contract) {
+    const outgoing = new Map(contract.nodes.map((node) => [
+        node.id,
+        [],
+    ]));
+    const incomingCount = new Map(contract.nodes.map((node) => [
+        node.id,
+        0,
+    ]));
+    for (const edge of contract.edges) {
+        outgoing.get(edge.from).push(edge.to);
+        incomingCount.set(edge.to, incomingCount.get(edge.to) + 1);
+    }
+    const byId = new Map(contract.nodes.map((node) => [
+        node.id,
+        node,
+    ]));
+    for (const neighbors of outgoing.values()) {
+        neighbors.sort((left, right) => Number(byId.get(left).kind !== "screen") - Number(byId.get(right).kind !== "screen") ||
+            (left < right ? -1 : left > right ? 1 : 0));
+    }
+    const state = new Map();
+    const successors = new Map(contract.nodes.map((node) => [
+        node.id,
+        new Set(),
+    ]));
+    const roots = [
+        ...contract.nodes,
+    ].sort((left, right) => Number(incomingCount.get(left.id) > 0) - Number(incomingCount.get(right.id) > 0) ||
+        (left.id < right.id ? -1 : left.id > right.id ? 1 : 0));
+    for (const root of roots) {
+        if (state.has(root.id)) {
+            continue;
+        }
+        state.set(root.id, "visiting");
+        const stack = [
+            {
+                id: root.id,
+                index: 0,
+            },
+        ];
+        while (stack.length) {
+            const current = stack[stack.length - 1];
+            const next = outgoing.get(current.id)[current.index++];
+            if (next === undefined) {
+                state.set(current.id, "done");
+                stack.pop();
+            }
+            else if (state.get(next) !== "visiting") {
+                successors.get(current.id).add(next);
+                if (!state.has(next)) {
+                    state.set(next, "visiting");
+                    stack.push({
+                        id: next,
+                        index: 0,
+                    });
+                }
+            }
+        }
+    }
+    const indegrees = new Map(contract.nodes.map((node) => [
+        node.id,
+        0,
+    ]));
+    const depths = new Map(contract.nodes.map((node) => [
+        node.id,
+        0,
+    ]));
+    for (const targets of successors.values()) {
+        for (const target of targets) {
+            indegrees.set(target, indegrees.get(target) + 1);
+        }
+    }
+    const queue = contract.nodes
+        .filter((node) => indegrees.get(node.id) === 0)
+        .map((node) => node.id);
+    while (queue.length) {
+        queue.sort();
+        const current = queue.shift();
+        for (const next of successors.get(current)) {
+            depths.set(next, Math.max(depths.get(next), depths.get(current) + 1));
+            indegrees.set(next, indegrees.get(next) - 1);
+            if (indegrees.get(next) === 0) {
+                queue.push(next);
+            }
+        }
+    }
+    return depths;
+}

package/dist/maps/proposal.d.ts

@@ -0,0 +1,5 @@
+import type { MapContract, MapProposal } from "./types.js";
+export declare function validateMapProposal(raw: unknown): MapProposal;
+export declare function createMapProposal(current: MapContract, proposed: MapContract, reason: string): MapProposal;
+/** Accepting changes the canonical revision; it neither creates nor carries forward owner approval. */
+export declare function acceptMapProposal(current: MapContract, raw: MapProposal): MapContract;

package/dist/maps/proposal.js

@@ -0,0 +1,67 @@
+import { observationHash } from "../journal.js";
+import { hashMapContract, mapHash, mapObject, mapText, validateMapContract } from "./validation.js";
+export function validateMapProposal(raw) {
+    const proposal = mapObject(raw, "Map proposal", [
+        "schemaVersion",
+        "kind",
+        "baseHash",
+        "proposedHash",
+        "proposedMap",
+        "reason",
+        "hash",
+    ]);
+    if (proposal.schemaVersion !== 1 || proposal.kind !== "map-proposal") {
+        throw new Error("Unsupported map proposal schema");
+    }
+    const result = {
+        schemaVersion: 1,
+        kind: "map-proposal",
+        baseHash: mapHash(proposal.baseHash, "Proposal base hash"),
+        proposedHash: mapHash(proposal.proposedHash, "Proposed map hash"),
+        proposedMap: validateMapContract(proposal.proposedMap),
+        reason: mapText(proposal.reason, "Proposal reason", 8000),
+        hash: mapHash(proposal.hash, "Proposal record hash"),
+    };
+    const { hash, ...body } = result;
+    if (hash !== observationHash(body) ||
+        result.proposedHash !== hashMapContract(result.proposedMap)) {
+        throw new Error("Map proposal evidence hash mismatch");
+    }
+    return result;
+}
+export function createMapProposal(current, proposed, reason) {
+    const base = validateMapContract(current);
+    const proposedMap = validateMapContract(proposed);
+    if (base.kind !== proposedMap.kind || base.id !== proposedMap.id) {
+        throw new Error("A proposal must preserve map identity and kind");
+    }
+    if (hashMapContract(base) === hashMapContract(proposedMap)) {
+        throw new Error("A proposal requires a semantic contract change");
+    }
+    const body = {
+        schemaVersion: 1,
+        kind: "map-proposal",
+        baseHash: hashMapContract(base),
+        proposedHash: hashMapContract(proposedMap),
+        proposedMap,
+        reason,
+    };
+    return validateMapProposal({
+        ...body,
+        hash: observationHash(body),
+    });
+}
+/** Accepting changes the canonical revision; it neither creates nor carries forward owner approval. */
+export function acceptMapProposal(current, raw) {
+    const base = validateMapContract(current);
+    const proposal = validateMapProposal(raw);
+    if (hashMapContract(base) !== proposal.baseHash ||
+        base.id !== proposal.proposedMap.id ||
+        base.kind !== proposal.proposedMap.kind) {
+        throw new Error("Map proposal is stale or belongs to another map; review against the current contract");
+    }
+    if (proposal.proposedHash === proposal.baseHash) {
+        throw new Error("A proposal must change the canonical revision before it can be accepted");
+    }
+    return structuredClone(proposal.proposedMap);
+}

package/dist/maps/render.d.ts

@@ -0,0 +1,4 @@
+import type { MapContract, MapDrawingPlan } from "./types.js";
+export declare function renderMapMermaid(raw: MapContract): string;
+export declare function renderMapMarkdown(raw: MapContract): string;
+export declare function buildMapDrawingPlan(raw: MapContract, detailMaps?: Record<string, MapContract>): MapDrawingPlan;