@formicoidea/labre-framework-wardley 0.42.0 → 0.45.0

package/dist/svg-recognise-labre.js

@@ -0,0 +1,240 @@
+import { BOARD_SVG_MARKER_VERSION } from '@formicoidea/labre-core/blocks/surface';
+import { matchLabels, owmPlotOf } from './export.js';
+import { WARDLEY_ROLE, WARDLEY_ROLES } from './roles.js';
+import { startDrawnMap } from './svg-read.js';
+import { WARDLEY_SVG_IMPORT_REMARKS } from './svg-remarks.js';
+/**
+ * Labre's own board SVG, recognised (ADR 0032 §4.1, §6) — first in detection
+ * order, because it is the one producer whose file states roles exactly.
+ *
+ * The export wraps every element it replays in a `<g>` carrying
+ * `data-labre-id`, `-type`, `-role`, `-xywh` (the stored bound, in the file's
+ * coordinates), `-source` / `-target` on a connector and `-group` on a grouped
+ * element, and stamps the root with `data-labre-svg`. Certain on that root
+ * stamp, at a version this reader knows.
+ *
+ * So nothing is guessed but names: the plot is the map's own (`owmPlotOf` on
+ * the board's bound), a node's place is its stored bound, a dependency names
+ * its two ends, a change arrow names the twin it points at. A NAME is read off
+ * the `<text>` the renderer drew, never off a marker — the markers carry no
+ * prose — and matched to its node with the very function the OWM export uses
+ * (`matchLabels`), so the export and this import agree on whose name is
+ * whose. What the statements have no word for — an area, a Porter's force, a
+ * method, another framework's artefact, a role no Wardley table declares —
+ * is left to the sketch.
+ */
+/** Roles that are a node of the value chain, and the keyword each lays out as. */
+const NODE_KEYWORD = Object.assign(Object.create(null), {
+    [WARDLEY_ROLE.component]: 'component',
+    [WARDLEY_ROLE.anchor]: 'anchor',
+    [WARDLEY_ROLE.market]: 'market',
+    [WARDLEY_ROLE.ecosystem]: 'ecosystem',
+    [WARDLEY_ROLE.accelerator]: 'accelerator',
+    [WARDLEY_ROLE.decelerator]: 'deaccelerator',
+});
+/** A bound a marker states, as four finite numbers, or `undefined`. */
+function boxOf(raw) {
+    if (raw === null)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (!Array.isArray(parsed) || parsed.length !== 4)
+        return undefined;
+    if (!parsed.every(value => typeof value === 'number' && Number.isFinite(value)))
+        return undefined;
+    const [x, y, w, h] = parsed;
+    return { x, y, w, h };
+}
+const centreOf = (box) => ({
+    x: box.x + box.w / 2,
+    y: box.y + box.h / 2,
+});
+/** The words a group's own `<text>`s draw, line after line. */
+function drawnText(element) {
+    return Array.from(element.querySelectorAll('text'))
+        .map(text => text.textContent ?? '')
+        .join(' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+export function recogniseLabreExport(root) {
+    if (root.getAttribute('data-labre-svg') !== BOARD_SVG_MARKER_VERSION) {
+        return undefined;
+    }
+    const { drawn, consume: consumeElement } = startDrawnMap({
+        producer: `Labre SVG ${BOARD_SVG_MARKER_VERSION}`,
+    });
+    const consume = (marked) => consumeElement(marked?.element);
+    /* Every marked group whose numbers are numbers and whose role is Wardley's. */
+    const marked = [];
+    for (const element of Array.from(root.querySelectorAll('g[data-labre-id]'))) {
+        const id = element.getAttribute('data-labre-id') ?? '';
+        const box = boxOf(element.getAttribute('data-labre-xywh'));
+        if (id.length === 0)
+            continue;
+        if (!box) {
+            drawn.remarks.push({
+                kind: 'warning',
+                sourceId: id,
+                message: WARDLEY_SVG_IMPORT_REMARKS.unreadableCoordinates[1],
+                messageKey: WARDLEY_SVG_IMPORT_REMARKS.unreadableCoordinates[0],
+            });
+            continue;
+        }
+        const role = element.getAttribute('data-labre-role') ?? undefined;
+        // A role no Wardley table declares — another framework's, or a forged
+        // one — is not this reader's to read: that element stays a sketch, and is
+        // never a new role (ADR 0032 §7).
+        if (role !== undefined && !WARDLEY_ROLES[role])
+            continue;
+        marked.push({
+            element,
+            id,
+            type: element.getAttribute('data-labre-type') ?? '',
+            role,
+            box,
+            source: element.getAttribute('data-labre-source') ?? undefined,
+            target: element.getAttribute('data-labre-target') ?? undefined,
+        });
+    }
+    const byId = new Map(marked.map(entry => [entry.id, entry]));
+    const withRole = (role) => marked.filter(entry => entry.role === role);
+    /* The map, and its plot. */
+    const map = withRole(WARDLEY_ROLE.map)[0];
+    if (map) {
+        const plot = owmPlotOf(map.box);
+        drawn.plot = plot;
+        consume(map);
+    }
+    /* Names, matched the way the OWM export matches them. */
+    const named = marked.filter(entry => entry.type === 'wardleyNode');
+    const labels = withRole(WARDLEY_ROLE.label);
+    const names = matchLabels(named.map(entry => ({
+        id: entry.id,
+        kind: entry.role?.slice('wardley:'.length) ?? '',
+        role: entry.role,
+        elementBound: entry.box,
+    })), labels.map(entry => ({
+        text: drawnText(entry.element),
+        elementBound: entry.box,
+    })));
+    /* Change arrows first: their targets are twins, not nodes. */
+    const twins = new Set();
+    for (const arrow of withRole(WARDLEY_ROLE.changeArrow)) {
+        const from = arrow.source ? byId.get(arrow.source) : undefined;
+        const twin = arrow.target ? byId.get(arrow.target) : undefined;
+        if (!from || !twin || !NODE_KEYWORD[from.role ?? ''])
+            continue;
+        twins.add(twin.id);
+        drawn.evolutions.push({
+            of: from.id,
+            name: names.get(twin.id) ?? names.get(from.id) ?? '',
+            x: centreOf(twin.box).x,
+        });
+        consume(arrow);
+        consume(twin);
+    }
+    /* Nodes. */
+    for (const entry of named) {
+        const keyword = NODE_KEYWORD[entry.role ?? ''];
+        if (!keyword || twins.has(entry.id))
+            continue;
+        drawn.nodes.push({
+            id: entry.id,
+            kind: keyword,
+            name: names.get(entry.id) ?? '',
+            ...centreOf(entry.box),
+        });
+        consume(entry);
+    }
+    /* Pipelines stand alone; a handle is redrawn with its body. */
+    const handleOf = new Map();
+    const bodies = withRole(WARDLEY_ROLE.pipeline);
+    for (const body of bodies) {
+        drawn.pipelines.push({
+            id: body.id,
+            name: names.get(body.id) ?? '',
+            top: body.box.y,
+            x1: body.box.x,
+            x2: body.box.x + body.box.w,
+        });
+        consume(body);
+    }
+    for (const handle of withRole(WARDLEY_ROLE.handle)) {
+        const { x, y } = centreOf(handle.box);
+        const body = bodies.find(candidate => x >= candidate.box.x &&
+            x <= candidate.box.x + candidate.box.w &&
+            Math.abs(y - candidate.box.y) <= handle.box.h);
+        if (!body)
+            continue;
+        // The layout names the handle it mints after its pipeline.
+        handleOf.set(handle.id, `${body.id} handle`);
+        consume(handle);
+    }
+    /* Dependencies, by the two ids they name. */
+    const nodeIds = new Set(drawn.nodes.map(node => node.id));
+    const end = (id) => id === undefined ? undefined : nodeIds.has(id) ? id : handleOf.get(id);
+    for (const link of withRole(WARDLEY_ROLE.dependency)) {
+        const from = end(link.source);
+        const to = end(link.target);
+        if (from === undefined || to === undefined) {
+            drawn.remarks.push({
+                kind: 'warning',
+                sourceId: link.id,
+                element: 'link',
+                message: WARDLEY_SVG_IMPORT_REMARKS.danglingLink[1],
+                messageKey: WARDLEY_SVG_IMPORT_REMARKS.danglingLink[0],
+            });
+            continue;
+        }
+        drawn.links.push({ from, to });
+        consume(link);
+    }
+    /* Inertia bars, and free texts — an OWM note is a free text on the map. */
+    for (const bar of withRole(WARDLEY_ROLE.inertia)) {
+        drawn.inertias.push(centreOf(bar.box));
+        consume(bar);
+    }
+    for (const text of marked.filter(entry => entry.type === 'text' && entry.role === undefined)) {
+        const words = drawnText(text.element);
+        if (words.length === 0)
+            continue;
+        drawn.notes.push({ text: words, ...centreOf(text.box) });
+        consume(text);
+    }
+    /* A glyph's own wiring (a market's dots and triangle), and the groups. */
+    const wiring = new Set(marked
+        .filter(entry => entry.type === 'wardleyNode' && entry.role === undefined)
+        .map(entry => entry.id));
+    for (const entry of marked) {
+        const glyph = wiring.has(entry.id) ||
+            (entry.type === 'connector' &&
+                entry.role === undefined &&
+                wiring.has(entry.source ?? '') &&
+                wiring.has(entry.target ?? ''));
+        if (glyph || entry.type === 'group')
+            consume(entry);
+    }
+    // The clip paths svgcanvas hoists to the root draw nothing by themselves.
+    for (const defs of Array.from(root.children).filter(child => child.localName === 'defs')) {
+        drawn.consumed.add(defs);
+    }
+    // A label goes when it named something now drawn natively — the layout
+    // writes that name again. One that named nothing, or named an artefact left
+    // to the sketch (a method, a force), stays visible beside it.
+    const redrawn = new Set([
+        ...drawn.nodes.map(node => node.id),
+        ...twins,
+        ...bodies.map(body => body.id),
+    ].flatMap(id => (names.has(id) ? [names.get(id)] : [])));
+    for (const label of labels) {
+        if (redrawn.has(drawnText(label.element)))
+            consume(label);
+    }
+    return drawn;
+}

package/dist/svg-recognise-owm.d.ts

@@ -0,0 +1,2 @@
+import { type DrawnWardleyMap } from './svg-read.js';
+export declare function recogniseOnlineWardleyMaps(root: Element): DrawnWardleyMap | undefined;

package/dist/svg-recognise-owm.js

@@ -0,0 +1,303 @@
+import { svgFrameOf } from '@formicoidea/labre-core/blocks/surface';
+import { finiteAttr, idIndex, originOf, startDrawnMap, textOf, } from './svg-read.js';
+import { WARDLEY_SVG_IMPORT_REMARKS } from './svg-remarks.js';
+/**
+ * An OnlineWardleyMaps "Export SVG", recognised (ADR 0032 §4.3).
+ *
+ * Read against the export the tool actually writes (`MapEnvironment.tsx`
+ * `downloadMapAsSVG`, and the corpus files rendered from its own components),
+ * which is NOT quite what its source suggests at a glance:
+ *
+ * - every artefact is a `modern_movable_element_<id>` group translated to its
+ *   centre, holding an `element_circle_<id>` (a component), an
+ *   `element_square_<id>` (a component inside a pipeline), and for a market
+ *   or an ecosystem a `market_circle_<id>` / `ecosystem_circle_<id>` on top;
+ *   its name is the `<id>-text` text, drawn in a sibling group;
+ * - `<id>` is the component's line in the DSL, so it is a number — but it is
+ *   read as an opaque string, whatever a hostile file puts there;
+ * - an anchor is a `modern_movable_anchor__<id>_` group with its name inside;
+ * - a link is `modern_link_<from>_<to>`, drawn TWICE when one end is an anchor
+ *   (once among the links, once among the anchor links);
+ * - an evolved twin is the `<id>_evolved` artefact, its arrow
+ *   `modern_evolving_link_<id>_<id>_evolved`;
+ * - inertia is a `line.inertia-symbol`; a pipeline is `pipeline_box_<line>`
+ *   with its two ends `modern_movable_pipeline_x1_<line>` / `x2_`, under the
+ *   component whose square sits on its top edge;
+ * - a note is `modern_movable_modern_note_<line>` around
+ *   `modern_note_text_<line>`; a climate arrow is
+ *   `modern_movable_accelerator_element_<line>`, turned by `rotate(180…)` when
+ *   it is a decelerator, and drawn with NO name;
+ * - the plot is `rect#fillArea`, the title `text#mapTitle`.
+ *
+ * Methods (`method_<id>`), annotations and the PST boxes have no native
+ * artefact here and are left to the sketch, as is anything a person added.
+ *
+ * ## Certain, with or without the plot
+ *
+ * ADR 0032 §4 names `fillArea` plus one element marker as certain, and §5 then
+ * reads an OWM file "whose `fillArea` was stripped" as certain too. Both hold
+ * here: certainty comes from an element marker INSIDE OWM's own movable
+ * wrapper — two structures only this tool writes together — and `fillArea`
+ * decides whether the plot is read or estimated.
+ */
+const MOVABLE_ELEMENT = 'modern_movable_element_';
+const MOVABLE_ANCHOR = /^modern_movable_anchor__(.*)_$/;
+const MOVABLE_ACCELERATOR = 'modern_movable_accelerator_element_';
+const MOVABLE_NOTE = 'modern_movable_modern_note_';
+const PIPELINE_BOX = 'pipeline_box_';
+const LINK = 'modern_link_';
+const EVOLVING_LINK = 'modern_evolving_link_';
+const EVOLVED = '_evolved';
+/** The chrome every export carries, drawn by the native board instead. */
+const CHROME_IDS = ['grid', 'fillArea', 'valueChain', 'Evolution', 'mapTitle'];
+/** How far a pipeline's owner may sit from the box's top edge, in file units. */
+const PIPELINE_OWNER_REACH = 15;
+const after = (id, prefix) => id.startsWith(prefix) ? id.slice(prefix.length) : undefined;
+export function recogniseOnlineWardleyMaps(root) {
+    const ids = idIndex(root);
+    /* Certain: an OWM element marker inside OWM's own movable wrapper. */
+    const certain = [...ids.keys()].some(id => {
+        const own = after(id, MOVABLE_ELEMENT);
+        return (own !== undefined &&
+            [
+                'element_circle_',
+                'element_square_',
+                'market_circle_',
+                'ecosystem_circle_',
+            ]
+                .map(prefix => ids.get(`${prefix}${own}`))
+                .some(marker => marker !== undefined && ids.get(id).contains(marker)));
+    });
+    if (!certain)
+        return undefined;
+    const { drawn, consume } = startDrawnMap({
+        producer: 'OnlineWardleyMaps SVG',
+    });
+    const unreadable = (sourceId) => {
+        drawn.remarks.push({
+            kind: 'warning',
+            sourceId,
+            message: WARDLEY_SVG_IMPORT_REMARKS.unreadableCoordinates[1],
+            messageKey: WARDLEY_SVG_IMPORT_REMARKS.unreadableCoordinates[0],
+        });
+    };
+    /* The plot, in the coordinates of its parent group. */
+    const fillArea = ids.get('fillArea');
+    if (fillArea) {
+        const frame = svgFrameOf(fillArea);
+        const [x, y, w, h] = ['x', 'y', 'width', 'height'].map(name => finiteAttr(fillArea, name));
+        if (w !== undefined && h !== undefined && w > 0 && h > 0) {
+            const plot = {
+                x0: frame.ox + (x ?? 0) * frame.s,
+                y0: frame.oy + (y ?? 0) * frame.s,
+                width: w * frame.s,
+                height: h * frame.s,
+            };
+            drawn.plot = plot;
+        }
+    }
+    const title = textOf(ids.get('mapTitle'));
+    if (title.length > 0)
+        drawn.title = title;
+    /* The chrome: drawn again by the native board, so never sketched. */
+    for (const id of CHROME_IDS)
+        consume(ids.get(id));
+    // The pan-and-zoom canvas's own backdrops: the plain rects beside the
+    // plot's ancestors, between it and the root (never the root's own children,
+    // which is where anything somebody added to the file lands).
+    for (let at = fillArea?.parentElement; at && at !== root && at.parentElement !== root; at = at.parentElement) {
+        for (const sibling of Array.from(at.parentElement?.children ?? [])) {
+            if (sibling.localName === 'rect' && !sibling.hasAttribute('id')) {
+                consume(sibling);
+            }
+        }
+    }
+    // Hover animations and gradient definitions draw nothing by themselves.
+    for (const element of Array.from(root.querySelectorAll('defs, style'))) {
+        consume(element);
+    }
+    /* The artefacts. */
+    const byId = new Map();
+    const twins = [];
+    for (const [id, group] of ids) {
+        const own = after(id, MOVABLE_ELEMENT);
+        if (own === undefined)
+            continue;
+        if (own.endsWith(EVOLVED)) {
+            twins.push({ of: own.slice(0, -EVOLVED.length), group });
+            continue;
+        }
+        const kind = ids.has(`market_circle_${own}`)
+            ? 'market'
+            : ids.has(`ecosystem_circle_${own}`)
+                ? 'ecosystem'
+                : ids.has(`element_circle_${own}`) || ids.has(`element_square_${own}`)
+                    ? 'component'
+                    : undefined;
+        if (kind === undefined)
+            continue;
+        const at = originOf(group);
+        if (!at) {
+            unreadable(own);
+            continue;
+        }
+        const label = ids.get(`${own}-text`);
+        const node = { id: own, kind, name: textOf(label), x: at[0], y: at[1] };
+        byId.set(own, node);
+        drawn.nodes.push(node);
+        consume(group);
+        consume(ids.get(`modern_movable_${own}-text-movable`));
+    }
+    for (const [id, group] of ids) {
+        const own = MOVABLE_ANCHOR.exec(id)?.[1];
+        if (own === undefined)
+            continue;
+        const at = originOf(group);
+        if (!at) {
+            unreadable(own);
+            continue;
+        }
+        const node = {
+            id: own,
+            kind: 'anchor',
+            name: textOf(ids.get(`${own}-text`)),
+            x: at[0],
+            y: at[1],
+        };
+        byId.set(own, node);
+        drawn.nodes.push(node);
+        consume(group);
+    }
+    for (const [id, group] of ids) {
+        const own = after(id, MOVABLE_ACCELERATOR);
+        if (own === undefined)
+            continue;
+        const at = originOf(group);
+        if (!at) {
+            unreadable(own);
+            continue;
+        }
+        const arrow = ids.get(`accelerator_circle_${own}`);
+        const turned = /rotate\(\s*180/.test(arrow?.getAttribute('transform') ?? '');
+        drawn.nodes.push({
+            id: `accelerator ${own}`,
+            kind: turned ? 'deaccelerator' : 'accelerator',
+            name: '',
+            x: at[0],
+            y: at[1],
+        });
+        consume(group);
+    }
+    for (const { of, group } of twins) {
+        const base = byId.get(of);
+        const at = originOf(group);
+        if (!base || !at) {
+            if (!at)
+                unreadable(`${of}${EVOLVED}`);
+            continue;
+        }
+        drawn.evolutions.push({
+            of,
+            name: textOf(ids.get(`${of}${EVOLVED}-text`)) || base.name,
+            x: at[0],
+        });
+        consume(group);
+        consume(ids.get(`modern_movable_${of}${EVOLVED}-text-movable`));
+        consume(ids.get(`${EVOLVING_LINK}${of}_${of}${EVOLVED}`));
+    }
+    /* Links, bound by the two ids in their own id. */
+    const known = (end) => byId.has(end)
+        ? end
+        : end.endsWith(EVOLVED) && byId.has(end.slice(0, -EVOLVED.length))
+            ? end.slice(0, -EVOLVED.length)
+            : undefined;
+    const linked = new Set();
+    for (const element of Array.from(root.querySelectorAll('[id]'))) {
+        const rest = after(element.getAttribute('id') ?? '', LINK);
+        if (rest === undefined)
+            continue;
+        let ends;
+        for (let at = rest.indexOf('_'); at >= 0; at = rest.indexOf('_', at + 1)) {
+            const from = known(rest.slice(0, at));
+            const to = known(rest.slice(at + 1));
+            if (from !== undefined && to !== undefined) {
+                ends = [from, to];
+                break;
+            }
+        }
+        if (!ends) {
+            drawn.remarks.push({
+                kind: 'warning',
+                sourceId: rest,
+                element: 'link',
+                message: WARDLEY_SVG_IMPORT_REMARKS.danglingLink[1],
+                messageKey: WARDLEY_SVG_IMPORT_REMARKS.danglingLink[0],
+            });
+            continue;
+        }
+        consume(element);
+        // Drawn twice when an end is an anchor; one dependency all the same.
+        const key = JSON.stringify(ends);
+        if (linked.has(key))
+            continue;
+        linked.add(key);
+        drawn.links.push({ from: ends[0], to: ends[1] });
+    }
+    /* Inertia. */
+    for (const line of Array.from(root.querySelectorAll('line.inertia-symbol'))) {
+        const [x1, y1, x2, y2] = ['x1', 'y1', 'x2', 'y2'].map(name => finiteAttr(line, name));
+        if ([x1, y1, x2, y2].some(value => value === undefined)) {
+            unreadable('inertia');
+            continue;
+        }
+        const frame = svgFrameOf(line);
+        drawn.inertias.push({
+            x: frame.ox + ((x1 + x2) / 2) * frame.s,
+            y: frame.oy + ((y1 + y2) / 2) * frame.s,
+        });
+        consume(line);
+    }
+    /* Pipelines, hung under the component sitting on their top edge. */
+    for (const [id, box] of ids) {
+        const own = after(id, PIPELINE_BOX);
+        if (own === undefined)
+            continue;
+        const top = originOf(box);
+        const left = originOf(ids.get(`modern_movable_pipeline_x1_${own}`) ?? box);
+        const right = ids.get(`modern_movable_pipeline_x2_${own}`);
+        const end = right ? originOf(right) : undefined;
+        if (!top || !left || !end) {
+            unreadable(id);
+            continue;
+        }
+        const owner = drawn.nodes
+            .filter(node => node.kind === 'component' &&
+            Math.abs(node.y - top[1]) <= PIPELINE_OWNER_REACH &&
+            node.x >= Math.min(left[0], end[0]) - PIPELINE_OWNER_REACH &&
+            node.x <= Math.max(left[0], end[0]) + PIPELINE_OWNER_REACH)
+            .sort((a, b) => Math.abs(a.y - top[1]) - Math.abs(b.y - top[1]))[0];
+        if (!owner)
+            continue;
+        drawn.pipelines.push({ of: owner.id, x1: left[0], x2: end[0] });
+        consume(box);
+        consume(ids.get(`modern_movable_pipeline_x1_${own}`));
+        consume(right);
+    }
+    /* Notes. */
+    for (const [id, group] of ids) {
+        const own = after(id, MOVABLE_NOTE);
+        if (own === undefined)
+            continue;
+        const at = originOf(group);
+        if (!at) {
+            unreadable(id);
+            continue;
+        }
+        const text = textOf(ids.get(`modern_note_text_${own}`) ?? group);
+        if (text.length === 0)
+            continue;
+        drawn.notes.push({ text, x: at[0], y: at[1] });
+        consume(group);
+    }
+    return drawn;
+}

package/dist/svg-recognise-renderer.d.ts

@@ -0,0 +1,2 @@
+import { type DrawnWardleyMap } from './svg-read.js';
+export declare function recogniseWardleyMapRenderer(root: Element): DrawnWardleyMap | undefined;