@formicoidea/labre-framework-wardley 0.32.0 → 0.33.0

package/dist/actions.d.ts

@@ -1,5 +1,7 @@
-import { type WardleyBgVariant } from '@formicoidea/labre-core/model';
-import type { GfxController } from '@formicoidea/labre-core/std/gfx';
+import { WardleyBackgroundElementModel, type WardleyBgVariant } from '@formicoidea/labre-core/model';
+import type { BlockStdScope } from '@formicoidea/labre-core/std';
+import { type GfxController } from '@formicoidea/labre-core/std/gfx';
+import { type WardleyExportBoard } from './export.js';
 /**
  * The single-circle node flavours: one connectable ellipse + a label to its
  * right, grouped. The glyph itself (anchor silhouette, ecosystem hatching,
@@ -61,10 +63,55 @@ export declare function createWardleyPipeline(gfx: GfxController): void;
  * everything is grouped into one object.
  */
 export declare function createWardleyMarket(gfx: GfxController): void;
+/**
+ * Read an SVG the user picks as a SKETCH, and say what it cost.
+ *
+ * Wardley's first interchange command, and its whole implementation: the four
+ * steps live in {@link runInterchangeImportFile} and the reading lives in the
+ * declared capability, so this framework contributes a declaration and a
+ * label rather than a pipeline (`docs/adr/0012`, P1 and P3).
+ *
+ * It takes a `BlockStdScope` and not the `GfxController` the rest of this file
+ * runs on, because an import is not a drawing gesture: it opens a picker,
+ * writes a whole board in one undo step, moves the viewport and notifies —
+ * none of which a `GfxController` alone can do.
+ */
+export declare function importWardleySvgFile(std: BlockStdScope): Promise<void>;
 /**
  * Activate the native connector tool, pre-styled for a Wardley link (grey,
  * solid, no arrow) or evolution arrow (red, dashed, FILLED triangle). The
  * user then draws from one node to another (endpoints attach to centers).
  */
 export declare function activateWardleyConnector(gfx: GfxController, kind: 'link' | 'arrow'): void;
+/** The maps on the surface — what the export command is offered against. */
+export declare function wardleyMapsOnBoard(std: BlockStdScope): WardleyBackgroundElementModel[];
+/**
+ * Everything on the surface the exporter speaks about, in document order.
+ *
+ * The half that needs an editor, and only that half: reading the surface. The
+ * picking is {@link wardleyBoardFrom}, which the interchange capability calls
+ * with the same elements and no `std` at all (`docs/adr/0012`, P3).
+ */
+export declare function wardleyBoardOf(std: BlockStdScope): WardleyExportBoard;
+/**
+ * Serialize the board as an OWM document and hand it to the browser.
+ *
+ * Three steps, and only the first and the last know what an editor is: read the
+ * surface, run the DECLARED capability, download what it produced. The middle
+ * step is not re-implemented here — the document, the filename and the content
+ * type all come out of `WARDLEY_OWM_EXPORT.run`, so the command and the
+ * registry cannot describe the same map differently. There is one door, and the
+ * registry is the label on it.
+ */
+export declare function exportOwmFile(std: BlockStdScope): void;
+/**
+ * Read an `.owm` the user picks, draw it, and say what it cost.
+ *
+ * The whole of the import glue, and it is one line: the generic pipeline picks
+ * the file from the format's own declaration, runs the capability, mints the
+ * surface ids and repairs the link endpoints that named the file's names,
+ * brings the map into view and reports. Nothing in it is about Wardley except
+ * the capability handed to it.
+ */
+export declare function importOwmFile(std: BlockStdScope): Promise<void>;
 export {};

package/dist/actions.js

@@ -1,10 +1,15 @@
-import { backgroundSize, DefaultTool } from '@formicoidea/labre-core/blocks/surface';
+import { backgroundSize, DefaultTool, runInterchangeImportFile, } from '@formicoidea/labre-core/blocks/surface';
 import { ConnectorTool } from '@formicoidea/labre-core/gfx/connector';
 import { createGroupCommand } from '@formicoidea/labre-core/gfx/group';
-import { ConnectorMode, FontFamily, PointStyle, ShapeStyle, StrokeStyle, TextFitMode, } from '@formicoidea/labre-core/model';
-import { EditPropsStore } from '@formicoidea/labre-core/shared/services';
+import { ConnectorMode, FontFamily, PointStyle, ShapeStyle, StrokeStyle, TextFitMode, WardleyBackgroundElementModel, } from '@formicoidea/labre-core/model';
+import { NotificationProvider, translateKey, } from '@formicoidea/labre-core/shared/services';
+import { downloadBlob } from '@formicoidea/labre-core/shared/utils';
 import { Bound } from '@formicoidea/labre-core/global/gfx';
+import { GfxControllerIdentifier } from '@formicoidea/labre-core/std/gfx';
 import { WARDLEY_BACKGROUND } from './background.js';
+import { WARDLEY_SVG_IMPORT } from './interchange.js';
+import { wardleyBoardFrom, wardleySafeFilename, } from './export.js';
+import { WARDLEY_OWM_EXPORT, WARDLEY_OWM_IMPORT } from './interchange.js';
 import { ECOSYSTEM_LABEL, ECOSYSTEM_SIZE, HANDLE_SIZE, INERTIA_COLOR, INERTIA_SIZE, LABEL_DEFAULT, LABEL_FONT_SIZE, LABEL_GAP, LINK_GREY, LINK_STROKE_WIDTH, MARKET_DOT_RING, MARKET_DOT_SIZE, MARKET_DOT_STROKE_WIDTH, MARKET_LABEL, MARKET_LINK_COLOR, MARKET_LINK_WIDTH, MARKET_SIZE, METHOD_FILL, METHOD_LABEL, METHOD_SIZE, NODE_FILL, NODE_SIZE, NODE_STROKE, NODE_STROKE_WIDTH, PIPELINE_FILL, PIPELINE_HEIGHT, PIPELINE_LABEL, PIPELINE_WIDTH, WARDLEY_RED, } from './node/consts.js';
 import { WARDLEY_ROLE } from './roles.js';
 /**
@@ -292,30 +297,28 @@ export function createWardleyMarket(gfx) {
     const labelId = addLabel(surface, MARKET_LABEL, cx + R + LABEL_GAP, cy - LABEL_H / 2);
     finish(gfx, group(gfx, [circleId, ...dotIds, ...connIds, labelId]));
 }
+/**
+ * Read an SVG the user picks as a SKETCH, and say what it cost.
+ *
+ * Wardley's first interchange command, and its whole implementation: the four
+ * steps live in {@link runInterchangeImportFile} and the reading lives in the
+ * declared capability, so this framework contributes a declaration and a
+ * label rather than a pipeline (`docs/adr/0012`, P1 and P3).
+ *
+ * It takes a `BlockStdScope` and not the `GfxController` the rest of this file
+ * runs on, because an import is not a drawing gesture: it opens a picker,
+ * writes a whole board in one undo step, moves the viewport and notifies —
+ * none of which a `GfxController` alone can do.
+ */
+export async function importWardleySvgFile(std) {
+    await runInterchangeImportFile(std, WARDLEY_SVG_IMPORT);
+}
 /**
  * Activate the native connector tool, pre-styled for a Wardley link (grey,
  * solid, no arrow) or evolution arrow (red, dashed, FILLED triangle). The
  * user then draws from one node to another (endpoints attach to centers).
  */
 export function activateWardleyConnector(gfx, kind) {
-    const props = kind === 'arrow'
-        ? {
-            mode: ConnectorMode.Straight,
-            stroke: WARDLEY_RED,
-            strokeStyle: StrokeStyle.Dash,
-            strokeWidth: LINK_STROKE_WIDTH,
-            frontEndpointStyle: PointStyle.None,
-            rearEndpointStyle: PointStyle.Triangle,
-        }
-        : {
-            mode: ConnectorMode.Straight,
-            stroke: LINK_GREY,
-            strokeStyle: StrokeStyle.Solid,
-            strokeWidth: LINK_STROKE_WIDTH,
-            frontEndpointStyle: PointStyle.None,
-            rearEndpointStyle: PointStyle.None,
-        };
-    gfx.std.get(EditPropsStore).recordLastProps('connector', props);
     gfx.tool.setTool(ConnectorTool, {
         mode: ConnectorMode.Straight,
         // The value-chain link IS the "depends on" edge of a Wardley map; the
@@ -324,7 +327,96 @@ export function activateWardleyConnector(gfx, kind) {
         // specialising the other: W1 is about where an arrow points and must never
         // fall on a dependency.
         role: kind === 'link' ? WARDLEY_ROLE.dependency : WARDLEY_ROLE.changeArrow,
+        // The look rides on the activation, never through the last-props store:
+        // the plain connector tool must keep the user's own style (#144 M1).
+        style: kind === 'arrow'
+            ? {
+                stroke: WARDLEY_RED,
+                strokeStyle: StrokeStyle.Dash,
+                strokeWidth: LINK_STROKE_WIDTH,
+                frontEndpointStyle: PointStyle.None,
+                rearEndpointStyle: PointStyle.Triangle,
+            }
+            : {
+                stroke: LINK_GREY,
+                strokeStyle: StrokeStyle.Solid,
+                strokeWidth: LINK_STROKE_WIDTH,
+                frontEndpointStyle: PointStyle.None,
+                rearEndpointStyle: PointStyle.None,
+            },
     });
     // The wardley palette stays open (native sub-menu behaviour): it only
     // closes on re-click of the senior button, another senior tool, or Escape.
 }
+/* ── Interchange: the OWM DSL, out and in (`docs/adr/0012`) ───────────── */
+/**
+ * The one wording this file owns: what a WRITER could not say.
+ *
+ * The import's wordings live in the pipeline that writes them
+ * (`affine-block-surface`, `extensions/interchange-import.ts`) — one set of
+ * keys for every format, with the format's own name composed into them, so
+ * "OWM file imported" needs no key of its own. An export's losses are the
+ * capability's own sentences and have nowhere else to go.
+ */
+const EXPORT_WARNINGS_KEY = 'com.labre.commands.wardley.exportOwm.warnings';
+const EXPORT_WARNINGS_FALLBACK = 'What this export could not write down';
+/** The maps on the surface — what the export command is offered against. */
+export function wardleyMapsOnBoard(std) {
+    const surface = std.get(GfxControllerIdentifier).surface;
+    return (surface?.elementModels ?? []).filter((model) => model instanceof WardleyBackgroundElementModel);
+}
+/**
+ * Everything on the surface the exporter speaks about, in document order.
+ *
+ * The half that needs an editor, and only that half: reading the surface. The
+ * picking is {@link wardleyBoardFrom}, which the interchange capability calls
+ * with the same elements and no `std` at all (`docs/adr/0012`, P3).
+ */
+export function wardleyBoardOf(std) {
+    return wardleyBoardFrom(std.get(GfxControllerIdentifier).surface?.elementModels ?? []);
+}
+/**
+ * Serialize the board as an OWM document and hand it to the browser.
+ *
+ * Three steps, and only the first and the last know what an editor is: read the
+ * surface, run the DECLARED capability, download what it produced. The middle
+ * step is not re-implemented here — the document, the filename and the content
+ * type all come out of `WARDLEY_OWM_EXPORT.run`, so the command and the
+ * registry cannot describe the same map differently. There is one door, and the
+ * registry is the label on it.
+ */
+export function exportOwmFile(std) {
+    const elements = std.get(GfxControllerIdentifier).surface?.elementModels ?? [];
+    const title = std.store.workspace.meta.getDocMeta(std.store.id)?.title;
+    const { text, filename, mime, warnings } = WARDLEY_OWM_EXPORT.run(elements, {
+        name: wardleySafeFilename(title),
+    });
+    // The charset is the browser's business, not the format's: `mime` is what an
+    // `.owm` IS, and this is how a blob is told to carry it.
+    downloadBlob(new Blob([text], { type: `${mime};charset=utf-8` }), filename);
+    // A warning is never an error: the file downloaded, and it is valid; what it
+    // could not say is what this names. A board with two maps on it, a component
+    // with no name, an evolution arrow that also climbs the value chain — each is
+    // a sentence the format has no way to write down, and the person who clicked
+    // Export is the one entitled to hear about it.
+    if (!warnings || warnings.length === 0)
+        return;
+    std.getOptional(NotificationProvider)?.notify({
+        title: translateKey(std, EXPORT_WARNINGS_KEY, EXPORT_WARNINGS_FALLBACK),
+        message: warnings.join('\n'),
+        accent: 'warning',
+        duration: 8000,
+    });
+}
+/**
+ * Read an `.owm` the user picks, draw it, and say what it cost.
+ *
+ * The whole of the import glue, and it is one line: the generic pipeline picks
+ * the file from the format's own declaration, runs the capability, mints the
+ * surface ids and repairs the link endpoints that named the file's names,
+ * brings the map into view and reports. Nothing in it is about Wardley except
+ * the capability handed to it.
+ */
+export async function importOwmFile(std) {
+    await runInterchangeImportFile(std, WARDLEY_OWM_IMPORT);
+}

package/dist/commands.d.ts

@@ -1,5 +1,9 @@
 import type { CommandDescriptor } from '@formicoidea/labre-core/std';
 import type { TemplateResult } from 'lit';
+/**
+ * The Wardley registry: the thirteen toolbox entries, then the two directions
+ * of the OWM DSL and the SVG fallback (`docs/adr/0012`).
+ */
 export declare const wardleyCommands: CommandDescriptor[];
 /** `iconKey` → template. Never travels through either manifest (ADR 0008). */
 export declare const wardleyCommandIcons: Record<string, TemplateResult>;

package/dist/commands.js

@@ -1,7 +1,7 @@
 import { GfxControllerIdentifier } from '@formicoidea/labre-core/std/gfx';
-import { activateWardleyConnector, createWardleyBackground, createWardleyInertia, createWardleyMarket, createWardleyNode, createWardleyPipeline, } from './actions.js';
-import { WARDLEY_ROLE, WARDLEY_ROLES, } from './roles.js';
-import { wardleyAnchorIcon, wardleyArrowIcon, wardleyBackgroundIcon, wardleyBenefitIcon, wardleyComponentIcon, wardleyEcosystemIcon, wardleyEvolutionGradientIcon, wardleyInertiaIcon, wardleyLinkIcon, wardleyMarketIcon, wardleyMethodIcon, wardleyOpportunityIcon, wardleyPipelineIcon, } from './toolbar/icons.js';
+import { activateWardleyConnector, createWardleyBackground, createWardleyInertia, createWardleyMarket, createWardleyNode, createWardleyPipeline, exportOwmFile, importOwmFile, importWardleySvgFile, wardleyMapsOnBoard, } from './actions.js';
+import { WARDLEY_ROLE, WARDLEY_ROLES } from './roles.js';
+import { wardleyAnchorIcon, wardleyArrowIcon, wardleyBackgroundIcon, wardleyBenefitIcon, wardleyComponentIcon, wardleyEcosystemIcon, wardleyEvolutionGradientIcon, wardleyExportOwmIcon, wardleyImportOwmIcon, wardleyImportSvgIcon, wardleyInertiaIcon, wardleyLinkIcon, wardleyMarketIcon, wardleyMethodIcon, wardleyOpportunityIcon, wardleyPipelineIcon, } from './toolbar/icons.js';
 const SPECS = [
     {
         id: 'addBackground',
@@ -153,7 +153,7 @@ function gestureOf(spec) {
         descriptionFallback: direction.gestureHintFallback,
     };
 }
-export const wardleyCommands = SPECS.map((spec, order) => ({
+const toolboxCommands = SPECS.map((spec, order) => ({
     id: `wardley.${spec.id}`,
     owner: 'wardley',
     kind: spec.kind,
@@ -172,6 +172,165 @@ export const wardleyCommands = SPECS.map((spec, order) => ({
     run: std => spec.run(std.get(GfxControllerIdentifier)),
     telemetry: { framework: 'wardley', element: spec.element },
 }));
+/**
+ * The IMPORT — the first Wardley command whose subject is a whole map rather
+ * than something you draw, and the first that needs nothing on the board.
+ *
+ * ## `'senior-menu'`, per the PO decision of 2026-08-28
+ *
+ * An interpreted import lives in its framework's sub-menu. On an empty canvas
+ * the sub-menu is the first thing a user opens, and "start from the map
+ * somebody sent me" belongs in that row beside "start from a component" —
+ * asking them to find the catalogue sidepanel first is the friction the
+ * decision names. It is Wardley's fourteenth nomination, which is exactly the
+ * cap, so nothing about the sub-menu's arbitration changes and no button is
+ * pushed out of the row.
+ *
+ * No `'contextual-toolbar'`: a contextual toolbar is a statement about a
+ * SELECTION, and the moment this command is most wanted is on a board with
+ * nothing on it at all.
+ *
+ * ## `'editable'`
+ *
+ * An import needs no selection, but it WRITES, so a read-only document is one
+ * it cannot run on — and that is a precondition a catalogue has to be able to
+ * show. `'always'` would light the entry on a read-only board, do nothing when
+ * clicked, and put the same untruth into the manifest a host reads.
+ */
+const importCommand = {
+    id: 'wardley.importOwm',
+    owner: 'wardley',
+    kind: 'action',
+    labelKey: 'com.labre.commands.wardley.importOwm',
+    labelFallback: 'Import Wardley map (OWM)',
+    descriptionKey: 'com.labre.commands.wardley.importOwm.description',
+    descriptionFallback: 'Open an OnlineWardleyMaps .owm file as a map. What Labre cannot draw is kept in the document, and the import says what it was.',
+    category: 'interchange',
+    iconKey: 'wardley.import-owm',
+    surfaces: ['senior-menu', 'catalogue', 'palette', 'agent'],
+    order: SPECS.length,
+    scope: 'edgeless',
+    // Keyless by intent. The `w` chord already seats seven artefacts, and a
+    // framework binds past that by host override rather than by shipping a
+    // default — still bindable from Settings › Shortcuts.
+    defaultKeys: { mac: [], other: [] },
+    availability: 'editable',
+    run: std => void importOwmFile(std),
+    // `board:` and not `node:` — this one is launched with no map anywhere.
+    telemetry: { framework: 'wardley', element: 'board:import-owm' },
+};
+/**
+ * The EXPORT — the other direction of the same format.
+ *
+ * It declines `'senior-menu'`, and the asymmetry with the import above is the
+ * ruling BPMN already carries: the sub-menu is where a board COMES FROM, and an
+ * export is what you do to a board you already have. It keeps `'catalogue'`,
+ * which is the registry's own invariant rather than a category claim — a
+ * command missing from the catalogue is unreachable the moment its framework
+ * overflows the fourteen slots — plus the palette and the agent. No
+ * `'contextual-toolbar'` either, and that is a declaration rather than an
+ * oversight: a contextual-toolbar surface is rendered by an element's own
+ * `ToolbarModuleConfig`, and declaring one nothing invokes would put an entry
+ * in the manifest that no toolbar draws.
+ *
+ * `'always'` with a `when` on the BOARD, and the pair is deliberate. An export
+ * READS: it needs no selection, and it is offered on a locked map and on a
+ * read-only document — which is precisely the board somebody wants to take
+ * away. What it DOES need is a plot to measure coordinates against, and that is
+ * a fact about the surface rather than about the selection: a Wardley node has
+ * no `visibility` prop, so its position on the plot IS its coordinate, and with
+ * no map there is nothing to invert. `'selection'` would be BPMN's shape copied
+ * for the look of it — that command's precondition genuinely is a selected
+ * pool, and this one's is not.
+ *
+ * **v1 writes one map.** An OWM document is one map; a board holding several is
+ * written against the first in document order and the export says so out loud
+ * in its warnings.
+ */
+const exportCommand = {
+    id: 'wardley.exportOwm',
+    owner: 'wardley',
+    kind: 'action',
+    labelKey: 'com.labre.commands.wardley.exportOwm',
+    labelFallback: 'Export Wardley map (OWM)',
+    descriptionKey: 'com.labre.commands.wardley.exportOwm.description',
+    descriptionFallback: 'Download the map as an OnlineWardleyMaps .owm file, ready to open in any Wardley mapping tool.',
+    category: 'interchange',
+    iconKey: 'wardley.export-owm',
+    surfaces: ['catalogue', 'palette', 'agent'],
+    order: SPECS.length + 1,
+    scope: 'edgeless',
+    defaultKeys: { mac: [], other: [] },
+    availability: 'always',
+    run: exportOwmFile,
+    telemetry: { framework: 'wardley', element: 'board:export-owm' },
+    when: std => wardleyMapsOnBoard(std).length > 0,
+};
+/**
+ * The SVG FALLBACK import — the visual tier, named as such before the picker
+ * opens (`docs/adr/0012`, P2).
+ *
+ * ## Why the catalogue and not the senior row
+ *
+ * Because {@link importCommand} is already there. The sub-menu carries the
+ * framework's NATIVE format — the OWM DSL, which the ADR's roadmap calls the
+ * reference Wardley import — and that is the route a user should be pointed at:
+ * an `.owm` file carries `[visibility, evolution]` pairs, which ARE the map's
+ * meaning, so it round-trips. This one reads a picture. A fallback that
+ * outranked the real thing would be the platform offering the lossy door first,
+ * and Wardley's fourteen nominations are already exactly the cap — a fifteenth
+ * would push a button out of the row for the rarest thing anybody does to a map.
+ *
+ * So it lands one click away, in the artefact catalogue behind "More
+ * artefacts…", and keeps `'palette'` and `'agent'` so it stays findable by name
+ * and invocable by an agent.
+ *
+ * **Flagged for the PO** as a curation call rather than a technical one: it is
+ * a one-line change either way.
+ *
+ * ## The label names the tier before the file is read
+ *
+ * A map is coordinates, and this reader recovers none: it recognises circles
+ * and words. Saying so in the description is not modesty, it is the contract —
+ * "the import surface must name the tier before the file is read".
+ */
+const importSvgCommand = {
+    id: 'wardley.importSvg',
+    owner: 'wardley',
+    kind: 'action',
+    labelKey: 'com.labre.commands.wardley.importSvg',
+    labelFallback: 'Import SVG sketch',
+    descriptionKey: 'com.labre.commands.wardley.importSvg.description',
+    descriptionFallback: 'Best effort: recognises shapes and text, no round-trip. The axes and the evolution are not read — what arrives is a sketch you then promote.',
+    // The same section the two OWM directions are filed under, and the same one
+    // BPMN files its `.bpmn` pair under: a host that translated the header once
+    // has translated it for every framework.
+    category: 'interchange',
+    iconKey: 'wardley.import-svg',
+    surfaces: ['catalogue', 'palette', 'agent'],
+    // Last of the three interchange entries, which is also how the section reads
+    // for somebody scanning "what can I do with a file": the native format both
+    // ways, then the best-effort reader.
+    order: SPECS.length + 2,
+    scope: 'edgeless',
+    defaultKeys: { mac: [], other: [] },
+    // It WRITES, so a read-only document is one it cannot run on.
+    availability: 'editable',
+    run: importWardleySvgFile,
+    // `board:` and not `node:`: it is launched with nothing selected, and often
+    // with nothing on the canvas at all.
+    telemetry: { framework: 'wardley', element: 'board:import-svg' },
+};
+/**
+ * The Wardley registry: the thirteen toolbox entries, then the two directions
+ * of the OWM DSL and the SVG fallback (`docs/adr/0012`).
+ */
+export const wardleyCommands = [
+    ...toolboxCommands,
+    importCommand,
+    exportCommand,
+    importSvgCommand,
+];
 /** `iconKey` → template. Never travels through either manifest (ADR 0008). */
 export const wardleyCommandIcons = {
     'wardley.background': wardleyBackgroundIcon,
@@ -187,4 +346,7 @@ export const wardleyCommandIcons = {
     'wardley.link': wardleyLinkIcon,
     'wardley.arrow': wardleyArrowIcon,
     'wardley.inertia': wardleyInertiaIcon,
+    'wardley.import-owm': wardleyImportOwmIcon,
+    'wardley.export-owm': wardleyExportOwmIcon,
+    'wardley.import-svg': wardleyImportSvgIcon,
 };

package/dist/export.d.ts

@@ -0,0 +1,211 @@
+import { ConnectorElementModel, TextElementModel, WardleyBackgroundElementModel, WardleyNodeElementModel } from '@formicoidea/labre-core/model';
+import type { GfxPrimitiveElementModel } from '@formicoidea/labre-core/std/gfx';
+/**
+ * A Wardley map as an OnlineWardleyMaps (OWM) DSL document — models in, text
+ * out (`docs/adr/0012`, P3).
+ *
+ * This is the function ADR 0012 records as owed: the Wardley serializer that
+ * exists today in **labre-mcp**, outside this repo, and is the ADR's one named
+ * violation of P3. It lands here so that both consumers — the editor command
+ * and the MCP tool — call one implementation, tested once, and so that the
+ * reader next door (`import.ts`) has a writer it agrees with about every
+ * coordinate, name and carried line.
+ *
+ * ## Pure, like its BPMN sibling
+ *
+ * Element models in, a string out. No `BlockStdScope`, no surface, no DOM, no
+ * clock, no randomness. `interchange.ts` is the thin adapter that names the
+ * file; `actions.ts` is the thinner one that downloads it.
+ *
+ * ## The plot IS the coordinate
+ *
+ * A Wardley node carries **no** `visibility` and **no** `evolution` prop — its
+ * position on the map's plot is the whole of what the map says about it. So the
+ * writer inverts the projection the reader applied: a node's centre, measured
+ * against the plot of the background it sits on, is the `[visibility,
+ * evolution]` pair OWM spells. Both numbers are written to exactly **two
+ * decimals**, and that stability is load-bearing rather than cosmetic: the
+ * fixed point `export(import(export(board)))` is byte-identical only because a
+ * value that survives one rounding survives every one after it. The reader
+ * tolerates any precision a foreign file happens to use.
+ *
+ * ## A name is a separate element, so it has to be found
+ *
+ * On this canvas the name of an artefact is a free text element beside it, not
+ * a prop on it (`roles.ts`, `WARDLEY_ROLE.label`). The writer therefore matches
+ * each label to the node it names by comparing where the label IS with where a
+ * label for that node WOULD be — see {@link matchLabels}, which is the one
+ * heuristic in this module and is documented as one.
+ *
+ * ## v1 reads one map
+ *
+ * An OWM document is one map. A surface holding several Wardley backgrounds is
+ * serialized against the FIRST in document order, and the export warns; the
+ * other maps' artefacts are written against that first plot, which is the
+ * honest behaviour (nothing is dropped) and is named in the warning so nobody
+ * discovers it from a file.
+ */
+/**
+ * The format id, and therefore THE KEY foreign matter rides under on an element
+ * (ADR 0012, D2) — `interchange.owm`. Declared here and re-exported by
+ * `import.ts`, so a reader filing a fragment and a writer looking one up cannot
+ * disagree about where it went.
+ */
+export declare const WARDLEY_OWM_FORMAT_ID = "owm";
+/**
+ * OWM's scope vocabulary — where a carried line came off (D2).
+ *
+ * The DSL is a flat list of statements with no nesting and no ids, so it needs
+ * exactly two `@`-prefixed role keys and never an element id:
+ *
+ * - `@document` — the whole file: the lines this reader has no artefact for,
+ *   and the `title` it consumed. They ride on the map's background element,
+ *   which is D6's stated asymmetry (delete the map and the residue goes with
+ *   it) and is where `profileId` already lives for the same reason.
+ * - `@self` — the line an element WAS. Used for the verbatim tail of a mapped
+ *   line, i.e. everything the writer would otherwise drop: `label [x, y]`,
+ *   `(build)`, `inertia`, a trailing comment.
+ */
+export declare const OWM_SCOPE: {
+    readonly document: "@document";
+    readonly self: "@self";
+};
+/** Where a mapped line's un-modelled tail is filed, under `attrs['@self']`. */
+export declare const OWM_TAIL_ATTR = "tail";
+/** Where the file's own `title` is filed, under `attrs['@document']`. */
+export declare const OWM_TITLE_ATTR = "title";
+/**
+ * Keywords a line may open on, none of which can be a bare component name.
+ *
+ * Two different parsers care. `BaseStrategyRunner` claims a line for a keyword
+ * when the TRIMMED line opens on `"<keyword> "`, and `LinksExtractionStrategy`
+ * refuses to read a line as a link when it opens on any of these — so a
+ * component genuinely called `style` would silently stop being linkable. The
+ * writer quotes such a name rather than betting nobody ever picks one.
+ */
+export declare const OWM_KEYWORDS: Set<string>;
+/**
+ * A name as the DSL spells it — bare when it can be, quoted and escaped
+ * otherwise.
+ *
+ * The escaping mirrors OWM's own `escapeComponentNameForMapText` /
+ * `unescapeComponentNameFromMapText` pair character for character, which is
+ * what makes `"Vente retail thés, accessoires, coffrets"` come back with its
+ * commas and its accents intact.
+ */
+export declare function owmName(raw: string): string;
+/** A name in quotes, escaped as OWM's `escapeComponentNameForMapText` does. */
+export declare function owmQuote(raw: string): string;
+/**
+ * A coordinate, to exactly two decimals — the whole of the fixed point's
+ * arithmetic.
+ *
+ * `-0` is written as `0.00`, because `(-0).toFixed(2)` is `"-0.00"` and a
+ * node dropped one pixel above the plot's top edge would otherwise produce a
+ * file whose bytes depend on which side of zero a float landed on. A
+ * non-finite value (an element with no geometry) is written as `0.00` rather
+ * than as `NaN`, which no parser reads.
+ */
+export declare function owmNumber(value: number): string;
+/** The plot of a map, in ABSOLUTE surface units. */
+export interface OwmPlot {
+    /** Surface x of evolution `0`, and y of visibility `1`. */
+    x0: number;
+    y0: number;
+    width: number;
+    height: number;
+}
+/** The reference map an import lays out on, and an export falls back to. */
+export declare const OWM_DEFAULT_MAP_WIDTH: number;
+export declare const OWM_DEFAULT_MAP_HEIGHT: number;
+/**
+ * The plot of a background element, in absolute units — the declaration's
+ * margins, never a hand-written inset.
+ *
+ * `templates/maps.ts` learned this the hard way: a plot copied as four numbers
+ * drifted from the drawn one, and a rule measuring against the declaration then
+ * judged nodes laid out against the copy. Both directions of this format read
+ * the same function for the same reason.
+ */
+export declare function owmPlotOf(bound: {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}): OwmPlot;
+/** The default plot: a reference map at the origin. */
+export declare function owmDefaultPlot(): OwmPlot;
+/**
+ * `[visibility, evolution]` → a surface point.
+ *
+ * Mind the inversion, which is the one thing about these axes that is easy to
+ * get backwards and impossible to see in a test that only round-trips: OWM's
+ * visibility `1.0` is the TOP of the value chain, and a canvas' y grows
+ * downwards.
+ */
+export declare function owmPointOf(plot: OwmPlot, visibility: number, evolution: number): [number, number];
+/** A surface point → `[visibility, evolution]`. The exact inverse. */
+export declare function owmCoordsOf(plot: OwmPlot, x: number, y: number): {
+    visibility: number;
+    evolution: number;
+};
+/**
+ * The artefacts the writer speaks about, picked out of a surface's elements and
+ * kept in the order they were given.
+ *
+ * Document order matters for the same reason it does in BPMN: it decides which
+ * map is THE map when a board holds several, and it is the order every section
+ * of the produced file is written in — so a file exported twice from an
+ * untouched board is the same file, byte for byte.
+ *
+ * `notes` is every text element with NO role. That is a deliberate reading and
+ * not a leak: an OWM `note` IS a free text at a position, so a text somebody
+ * dropped on the map is written as one. Only a text carrying the `label` role
+ * is a name, and only a name is resolved onto a node.
+ */
+export interface WardleyExportBoard {
+    maps: WardleyBackgroundElementModel[];
+    nodes: WardleyNodeElementModel[];
+    labels: TextElementModel[];
+    notes: TextElementModel[];
+    connectors: ConnectorElementModel[];
+}
+export declare function wardleyBoardFrom(elements: readonly GfxPrimitiveElementModel[]): WardleyExportBoard;
+/**
+ * A name a file system will accept, minus the extension. BPMN's sanitizer,
+ * verbatim in behaviour and different only in its fallback — `map`, because
+ * that is what an OWM document is.
+ */
+export declare function wardleySafeFilename(raw: string | undefined): string;
+/** The label box an import writes, and the width a prediction assumes. */
+export declare const OWM_LABEL_WIDTH = 200;
+export declare const OWM_LABEL_HEIGHT: number;
+/** A text element's string, whether it is a `Y.Text` or a test's plain one. */
+export declare function textOf(element: {
+    text?: unknown;
+}): string;
+export interface WardleyOwmExportOptions {
+    /** The board's own title, already sanitized by the caller. */
+    name?: string;
+}
+/**
+ * The board as an OWM document, plus what the format could not say.
+ *
+ * Sections in a fixed order — title, nodes, pipelines, notes, evolutions,
+ * links, carried lines — and DOCUMENT order inside each. That pairing is what
+ * makes the fixed point hold: the reader creates elements in the order it meets
+ * them, so a file's sections come back as a document whose order re-sections
+ * identically.
+ */
+export declare function exportWardleyOwmWithWarnings(board: WardleyExportBoard, options?: WardleyOwmExportOptions): {
+    text: string;
+    warnings: string[];
+};
+/**
+ * The board as an OWM document — models in, text out, and nothing else.
+ *
+ * The signature P3 names: exported from this package's index so that labre-mcp
+ * calls THIS function rather than keeping the copy ADR 0012 records as the one
+ * violation of it.
+ */
+export declare function exportWardleyOwm(board: WardleyExportBoard, options?: WardleyOwmExportOptions): string;