@multiplatform.one/node-graph 7.7.2

package/types/dom/wire.d.ts

@@ -0,0 +1,355 @@
+/**
+ * The bridge surface: ONE discriminated union, ONE channel.
+ *
+ * Design 9.1. Every function prop on an Expo DOM component is its own async
+ * proxy with its own round trip, so nine callbacks would be nine proxies and a
+ * tenth event later would be a change to the bridge rather than to a type. One
+ * `onEvent(eventJson)` makes adding an event a type change and nothing else.
+ *
+ * The strings, not the objects, are what cross. `documentJson`, `commandsJson`
+ * and `envelopeJson` are all deliberately pre-serialized on the side that owns
+ * them: one `JSON.parse` inside beats structured prop walking across the
+ * marshaller, and an identity check becomes a string compare.
+ *
+ * Design's emission table is the `graphEventEmission` const below, not a
+ * comment. `createGraphEventEmitter` reads it, so the throttle column is
+ * executable and `wire.spec.ts` asserts the numbers verbatim.
+ */
+import type { FrameStats, GestureWindow } from "../bench/frameSampler";
+import type { NodeId, Viewport } from "../model/index";
+import type { GraphFontRef } from "../knobs/envelope";
+import type { BootStage } from "./boot";
+/**
+ * Design 9.1 calls this `FontFaceWire`. It is `GraphFontRef` — the same shape
+ * the envelope already carries — aliased rather than duplicated, so a face
+ * cannot mean one thing on the envelope and another on the props.
+ */
+export type FontFaceWire = GraphFontRef;
+export type GraphErrorPhase = "boot" | "module" | "render" | "runtime";
+/** One family's outcome from the corrupted-first-family probe (design 6.3). */
+/**
+ * A face probe, whole, because half of one is not evidence.
+ *
+ * It used to be `{ family, matched }`, and that shape could not survive contact
+ * with the panel that renders it: `GraphDiagnostics` prints the STACK and BOTH
+ * widths, because design §6.3's control is "the same cascade with only the first
+ * family name corrupted, measured twice". A boolean called `matched` with no
+ * widths behind it is exactly the font-name assertion AC-3 exists to replace.
+ *
+ * `conclusive` rides along for the same reason it exists on `FaceProbe`: equal
+ * widths are not a MISS when nothing measured, or when the stack has no
+ * fallback behind its first name.
+ */
+export interface FaceProbeWire {
+    readonly stack: string;
+    readonly widthStack: number;
+    /** The same cascade, first family name broken. */
+    readonly widthFirstCorrupted: number;
+    readonly matched: boolean;
+    readonly conclusive: boolean;
+}
+/**
+ * The JSON-safe projection of design 9.5's `GraphDiagnostics`.
+ *
+ * `layoutRunner` is a plain string here rather than a union: the runner kinds
+ * land with milestone 4's layout engine, and a wire type that has to be
+ * revised every time an engine is added would make the bridge the bottleneck
+ * for a change that has nothing to do with it.
+ */
+export interface GraphFaceDeliveryWire {
+    readonly id: string;
+    readonly family: string;
+    readonly weight: number;
+    /** Design 6.3's two mechanisms, plus the two states that are neither. */
+    readonly source: "asset" | "inline" | "pending" | "failed";
+}
+export interface GraphDiagnosticsWire {
+    readonly stage: BootStage | null;
+    /** Milliseconds from the `script` stamp to `ready`. The watchdog's evidence. */
+    readonly bootMs: number | null;
+    readonly renderer: "react-flow-web" | "react-flow-dom";
+    readonly xyflowVersion: string;
+    readonly layoutRunner: string;
+    readonly faces: readonly FaceProbeWire[];
+    /** Which mechanism delivered each face INSIDE the WebView (design 6.3). */
+    readonly faceDelivery: readonly GraphFaceDeliveryWire[];
+    /** Node bodies React Flow mounted. Differs from the next field under culling. */
+    readonly nodesMounted: number;
+    readonly nodesInDocument: number;
+    readonly culling: boolean;
+    readonly renderMode: "detail" | "overview";
+    readonly scheme: "light" | "dark";
+    readonly lastError: {
+        readonly phase: GraphErrorPhase;
+        readonly message: string;
+    } | null;
+}
+/**
+ * A finished perf run, as it crosses the bridge (milestone 6, design §13).
+ *
+ * The sampler now runs INSIDE the WebView, because that is the realm whose
+ * `requestAnimationFrame` deltas are the frames a user sees — the host RN
+ * view's FPS keeps ticking while the WebView is stalled. Nothing on the Hermes
+ * side can read those deltas, so the run has to come back as an event.
+ *
+ * `stats` is `FrameStats` aliased rather than duplicated, exactly as
+ * `FontFaceWire` aliases `GraphFontRef`: a percentile cannot be allowed to mean
+ * one thing in the sampler and another on the wire.
+ *
+ * `reportJson` carries the WHOLE `FrameReport`, deltas included, so an artifact
+ * writer on the native side has the raw run and not only its summary. It is a
+ * string for the same reason `documentJson` is: one `JSON.parse` on the far
+ * side beats structured prop walking across the marshaller, and 3600 numbers is
+ * exactly the shape that walk is worst at.
+ *
+ * A REJECTED run crosses too. `reportRun` discards a run where nothing moved
+ * (design §13.2), and a device readout that simply showed nothing would be
+ * indistinguishable from a Stop that never reached the canvas.
+ */
+export interface PerfReportWire {
+    readonly ok: boolean;
+    /**
+     * `empty`, `didMove` or `notStarted`, from `FrameReportRejection`. Absent on a
+     * pass.
+     *
+     * `notStarted` is the WIRE instrument, and the only one of the three that is
+     * not about the run: it means the canvas heard the Stop and had no run in
+     * flight, so the Start is what went missing. A readout that stays on
+     * `sampling…` means the opposite — the Stop never crossed at all — and those
+     * two were indistinguishable on device until this reason existed.
+     */
+    readonly reason?: "empty" | "didMove" | "notStarted";
+    readonly message?: string;
+    readonly label: string;
+    readonly nodeCount: number;
+    readonly culling: boolean;
+    readonly layoutRunner: string;
+    readonly didMove: boolean;
+    readonly durationMs: number;
+    readonly stats: FrameStats | null;
+    /**
+     * The GESTURE-ONLY cell: frames between `perfMark("start")` and
+     * `perfMark("end")`, with the idle frames counted rather than mixed in.
+     *
+     * `stats` above is the whole window, Start to Stop. The m6 iOS number —
+     * `952 frames · p95 18.8 · mean 16.7` over six scripted pans — was taken that
+     * way and shipped with the caveat attached, because idle frames between one
+     * pan and the next are cheap and plentiful: they pull the mean down and leave
+     * the p95 roughly alone, so the cell was optimistic about the average and
+     * there was no way to say by how much. Design §13.2's cell is the gesture.
+     *
+     * `null` when the run bracketed nothing, which is a different finding from a
+     * bracketed gesture that produced no frames.
+     */
+    readonly gesture: GestureWindow | null;
+    /** `JSON.stringify(FrameReport)` on a pass, `""` on a rejection. */
+    readonly reportJson: string;
+}
+/**
+ * Design §7.3's three moments, now that the gesture lives in the DOM realm.
+ *
+ * `arm` is the hold firing, `select` is the finger lifting with a marquee, and
+ * `cancel` is every way out — past the slop, a second finger, an unmount. They
+ * are three because a native shell buzzes on one, updates a readout on another
+ * and clears it on the third.
+ */
+export type LassoPhaseWire = "arm" | "select" | "cancel";
+export type GraphEventWire = {
+    t: "ready";
+    diagnostics: GraphDiagnosticsWire;
+} | {
+    t: "commit";
+    rev: number;
+    commandsJson: string;
+} | {
+    t: "selection";
+    ids: readonly NodeId[];
+} | {
+    t: "viewport";
+    viewport: Viewport;
+} | {
+    t: "nodeActivate";
+    id: NodeId;
+} | {
+    t: "connectRefused";
+    code: string;
+    message: string;
+} | {
+    t: "haptic";
+    kind: "selection" | "impact" | "warning";
+} | {
+    t: "metrics";
+    frames: readonly number[];
+    label: string;
+    didMove: boolean;
+}
+/**
+ * The canvas PAINTED. Milestone 6, design §9.4.
+ *
+ * `ready` is deliberately late — it waits `graphReadySettleMs` so the
+ * diagnostics it carries are filled in rather than reporting `nodesMounted:
+ * 0` — and on emulator-5592 the 12 s watchdog fired on a canvas that was
+ * already on screen. Ready and paint had come apart, and the watchdog was
+ * timing the wrong one. This is the early half: the frame after React Flow's
+ * first render, carrying nothing but the fact that pixels exist.
+ */
+ | {
+    t: "paint";
+    bootMs: number | null;
+}
+/**
+ * A tidy finished. Milestone 6, design §8 and §13.2.
+ *
+ * `runner` is the string the engine stamped, so `hermes-inline` on a phone
+ * and `worker-blob` on web are readable from a native sibling — which is the
+ * only place a device can read them, since the AutoLayout readout used to be
+ * a child of the canvas and children are dropped on native.
+ */
+/**
+ * `error` is the m6 device-pass addition, and it exists because a relayout
+ * that REJECTS used to answer with nothing at all.
+ *
+ * `layout()` rejects when the blob Worker cannot be constructed or dies
+ * mid-flight — both of which are realm-local and therefore exactly what a
+ * freshly recreated WebView can hit — and the bridge only had a `.then`. So
+ * the toolbar sat on "laying out…" forever with no `layoutResult` ever
+ * crossing, which is indistinguishable from a Tidy that never reached the
+ * canvas. On a rejection the runner is `none` and `ms` is 0, because
+ * inventing either would read as a successful tidy.
+ */
+ | {
+    t: "layoutResult";
+    runner: string;
+    ms: number;
+    nodeCount: number;
+    error?: string;
+} | {
+    t: "perfReport";
+    report: PerfReportWire;
+}
+/**
+ * The long press, from inside the WebView. Milestone 6, design §7.3.
+ *
+ * `haptic` is a HINT and not a command: the canvas cannot buzz, and whether a
+ * buzz is appropriate is the shell's call. `null` on every phase but `arm`.
+ */
+ | {
+    t: "lasso";
+    phase: LassoPhaseWire;
+    ids: readonly NodeId[];
+    haptic: "selection" | "impact" | "warning" | null;
+} | {
+    t: "error";
+    phase: GraphErrorPhase;
+    message: string;
+    stack?: string;
+};
+export type GraphEventKind = GraphEventWire["t"];
+/**
+ * The runtime list, maintained BESIDE the union rather than derived from the
+ * table below — deriving it from the table would make the spec's coverage
+ * assertion circular and prove nothing.
+ *
+ * The two conditional types under it are the compile-time half: a variant added
+ * to `GraphEventWire` and not to this tuple, or a name here that is not a
+ * variant, is a type error at build time.
+ */
+export declare const graphEventKinds: readonly ["ready", "commit", "selection", "viewport", "nodeActivate", "connectRefused", "haptic", "metrics", "paint", "layoutResult", "perfReport", "lasso", "error"];
+/**
+ * `trailing` coalesces to the LAST value in the window — a pan reports where it
+ * ended, not where it was 125 ms ago. `floor` drops what arrives inside the
+ * window — a second haptic 30 ms after the first is not a second buzz, it is
+ * the same one felt twice. They are different mechanisms and naming them apart
+ * is what stops one being implemented as the other.
+ */
+export type GraphEventThrottle = {
+    readonly mode: "none";
+} | {
+    readonly mode: "trailing";
+    readonly ms: number;
+} | {
+    readonly mode: "floor";
+    readonly ms: number;
+} | {
+    readonly mode: "onDemand";
+};
+export interface GraphEventEmission {
+    readonly firesOn: string;
+    readonly throttle: GraphEventThrottle;
+}
+/**
+ * Design 9.1's emission table, as data.
+ *
+ * Mapped over the union, so a new variant with no row here does not compile.
+ * That is the point: an event without a throttle decision is how a per-frame
+ * emitter reaches a bridge, and no reviewer catches it by reading a diff.
+ *
+ * `ready` and `error` are not in the design's table. Both are discrete and both
+ * are what a stuck WebView has to be able to say, so both are unthrottled; the
+ * decision is recorded here and asserted in the spec rather than left implied.
+ *
+ * Never emitted at all, at any throttle: node positions, viewport DURING a
+ * gesture, hover.
+ */
+export declare const graphEventEmission: {
+    readonly [K in GraphEventKind]: GraphEventEmission;
+};
+export declare function isGraphEventKind(value: unknown): value is GraphEventKind;
+export declare function encodeGraphEvent(event: GraphEventWire): string;
+/**
+ * Throws on a tag it does not know, rather than returning it.
+ *
+ * Both ends ship in the same bundle, so an unknown tag is not user input — it
+ * is a DOM bundle and a native host out of step, and the same reasoning as
+ * `parseKnobEnvelope`'s version check applies: failing loudly beats handling
+ * something plausible and wrong.
+ */
+export declare function decodeGraphEvent(json: string): GraphEventWire;
+export declare function isBenignCanvasError(message: unknown): boolean;
+/**
+ * Echo suppression, design 9.1.
+ *
+ * A change that came out of the canvas comes back in through `documentJson` on
+ * the next render. The host stamps a monotonic `rev`; the canvas ignores an
+ * inbound document at or below the highest rev it has already emitted or
+ * applied, so a drag does not fight its own echo and a re-render does not
+ * re-apply what is already on screen.
+ *
+ * One high-water number rather than a set of seen revs: `rev` is monotonic by
+ * contract, so the set would only ever grow and never be consulted below its
+ * maximum.
+ */
+export interface RevEchoGate {
+    /** The canvas just emitted a `commit` stamped `rev`. */
+    readonly markEmitted: (rev: number) => void;
+    /** True when this inbound document is new work and should be applied. */
+    readonly acceptInbound: (rev: number) => boolean;
+    readonly highWater: () => number;
+}
+export declare function createRevEchoGate(): RevEchoGate;
+export interface GraphEventEmitterOptions {
+    /** The single bridge crossing. `onEvent` on the DOM side; a test collector in a spec. */
+    readonly send: (eventJson: string) => void;
+    /** Test seam. Defaults to `Date.now`. */
+    readonly now?: () => number;
+    /** Test seam. Defaults to `globalThis.setTimeout`. */
+    readonly schedule?: (fn: () => void, ms: number) => unknown;
+    /** Test seam. Defaults to `globalThis.clearTimeout`. */
+    readonly cancel?: (handle: unknown) => void;
+}
+export interface GraphEventEmitter {
+    readonly emit: (event: GraphEventWire) => void;
+    /** Send anything still pending now. Called before a commit, so ordering holds. */
+    readonly flush: () => void;
+    /** Drop anything pending. Called on unmount, so no timer fires into a dead tree. */
+    readonly dispose: () => void;
+}
+/**
+ * The table, executed.
+ *
+ * Design 9.1's spec is "a 30-change drag produces exactly one bridge crossing",
+ * and this is where that is true: 30 `viewport` events inside one 125 ms window
+ * schedule one timer and send the last value.
+ */
+export declare function createGraphEventEmitter(options: GraphEventEmitterOptions): GraphEventEmitter;
+//# sourceMappingURL=wire.d.ts.map

package/types/dom/wire.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire.d.ts","sourceRoot":"","sources":["../../src/dom/wire.ts"],"names":[],"mappings":"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"}

package/types/edges/GraphEdge.d.ts

@@ -0,0 +1,59 @@
+/**
+ * ONE registered React Flow edge type, switching on `edge.kind` internally.
+ *
+ * Design §4.4: the package registers exactly one `edgeType`. That keeps the
+ * edge component count at one and the `d`-string building in one place, which
+ * is where the merged single-path overview layer plugs in later — 1,968 `<svg>`
+ * down to 1 in the engine-split spike. Registering four types would make that a
+ * four-site change.
+ *
+ * `edge.kind` is the MODEL's kind and rides in `edge.data.kind`; React Flow's
+ * own `edge.type` is always `graphEdgeType`.
+ */
+import type { Animation, BorderWidth } from "@multiplatform.one/theme";
+import type { EdgeProps } from "../react-flow/xy";
+import type { EdgePathKind } from "./edgeStyle";
+export declare const graphEdgeType = "mpGraphEdge";
+export interface GraphEdgeData {
+    /** The model's `edge.kind`. */
+    readonly kind?: string;
+    /** `EdgeKindSpec.appearance`, when the kind is not one of the four. */
+    readonly appearance?: string;
+    readonly label?: string;
+}
+interface PathGeometry {
+    readonly sourceX: number;
+    readonly sourceY: number;
+    readonly targetX: number;
+    readonly targetY: number;
+    readonly sourcePosition: EdgeProps["sourcePosition"];
+    readonly targetPosition: EdgeProps["targetPosition"];
+}
+/**
+ * `step` is `getSmoothStepPath` with a zero corner radius — React Flow has no
+ * separate step builder, and the design's table names four path SHAPES, not
+ * four functions.
+ */
+export declare function buildEdgePath(path: EdgePathKind, geometry: PathGeometry): [d: string, labelX: number, labelY: number];
+/**
+ * The raw knob values an edge paints from.
+ *
+ * `useResolvedKnobs` returns `knobProps`, not the knob NAMES, and the edge
+ * needs the names because §11 remaps `borderWidth` rather than honouring the
+ * resolved value. So this reads the same Preset context `useResolvedKnobs`
+ * reads at its own step 1 — which means task 1.6's `KnobEnvelopeProvider`,
+ * which rebuilds that context inside the WebView, feeds this hook with no
+ * change here.
+ */
+export declare function useEdgeKnobs(): {
+    borderWidth: BorderWidth;
+    animation: Animation;
+};
+export declare function GraphEdgeComponent(props: EdgeProps): import("react/jsx-runtime").JSX.Element;
+export declare const GraphEdge: import("react").MemoExoticComponent<typeof GraphEdgeComponent>;
+/** The whole registration. One entry, on purpose. */
+export declare const graphEdgeTypes: {
+    readonly mpGraphEdge: import("react").MemoExoticComponent<typeof GraphEdgeComponent>;
+};
+export {};
+//# sourceMappingURL=GraphEdge.d.ts.map

package/types/edges/GraphEdge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GraphEdge.d.ts","sourceRoot":"","sources":["../../src/edges/GraphEdge.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAUvE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD,OAAO,KAAK,EAAE,YAAY,EAAa,MAAM,aAAa,CAAC;AAE3D,eAAO,MAAM,aAAa,gBAAgB,CAAC;AAE3C,MAAM,WAAW,aAAa;IAC5B,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,uEAAuE;IACvE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,UAAU,YAAY;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,cAAc,EAAE,SAAS,CAAC,gBAAgB,CAAC,CAAC;IACrD,QAAQ,CAAC,cAAc,EAAE,SAAS,CAAC,gBAAgB,CAAC,CAAC;CACtD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,YAAY,EAClB,QAAQ,EAAE,YAAY,GACrB,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAgC7C;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,IAAI;IAAE,WAAW,EAAE,WAAW,CAAC;IAAC,SAAS,EAAE,SAAS,CAAA;CAAE,CAIjF;AA0BD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,2CAiClD;AA+BD,eAAO,MAAM,SAAS,gEAA2B,CAAC;AAElD,qDAAqD;AACrD,eAAO,MAAM,cAAc;;CAA0C,CAAC"}

package/types/edges/edgeKinds.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The four built-in edge kinds, design §4.4.
+ *
+ * These are MODEL objects — `EdgeKindSpec`s a consumer drops into
+ * `createGraphSchema`. Their appearance lives in `edgeStyle.ts` and is reached
+ * by NAME, so the model half stays free of rendering and one registered React
+ * Flow edge type can switch on the kind internally.
+ */
+import type { EdgeKindSpec } from "../model/index";
+export type BuiltinEdgeKind = "flow" | "data" | "error" | "conditional";
+/**
+ * Declaration order is the order the table in design §4.4 reads, and the order
+ * the `Main` story lays them out.
+ */
+export declare const builtinEdgeKindNames: readonly BuiltinEdgeKind[];
+/**
+ * A type alias, not an interface. An interface has no implicit index signature,
+ * so `interface BuiltinEdgeData` does not satisfy `EdgeKindDefs` and
+ * `createGraphSchema` refuses it. That is a TypeScript rule about declaration
+ * merging rather than a modelling choice, and it bites every consumer the same
+ * way — so the kind maps in this package are written the shape a consumer must
+ * write too.
+ */
+export type BuiltinEdgeData = {
+    /** Control moving. */
+    readonly flow: Record<string, never>;
+    /** A value moving. */
+    readonly data: {
+        readonly dataType?: string;
+    };
+    /** The failure branch. */
+    readonly error: {
+        readonly reason?: string;
+    };
+    /** A branch not always taken. */
+    readonly conditional: {
+        readonly when?: string;
+    };
+};
+export declare const builtinEdgeKinds: {
+    readonly [K in BuiltinEdgeKind]: EdgeKindSpec<BuiltinEdgeData[K]>;
+};
+//# sourceMappingURL=edgeKinds.d.ts.map

package/types/edges/edgeKinds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edgeKinds.d.ts","sourceRoot":"","sources":["../../src/edges/edgeKinds.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,aAAa,CAAC;AAExE;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,SAAS,eAAe,EAK1D,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,sBAAsB;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACrC,sBAAsB;IACtB,QAAQ,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,0BAA0B;IAC1B,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7C,iCAAiC;IACjC,QAAQ,CAAC,WAAW,EAAE;QAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAClD,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE;IAC7B,QAAQ,EAAE,CAAC,IAAI,eAAe,GAAG,YAAY,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;CAMlE,CAAC"}

package/types/edges/edgeStyle.d.ts

@@ -0,0 +1,79 @@
+/**
+ * How an edge paints, design §4.4 and §11.
+ *
+ * Pure: knob names in, a style out. No React, no `@xyflow`, no DOM — so the
+ * table can be asserted without mounting anything, which is what makes
+ * `edgeStyle.spec.ts` a cheap test rather than a render.
+ *
+ * Stroke width is NOT per kind (design §4.4's last line): it comes from the
+ * `borderWidth` knob, so one flip moves every edge on the canvas. Task 1.7's
+ * `theme/graphVars.ts` reads `edgeStrokeWidth` from here rather than repeating
+ * the ladder — §11's borderWidth row cites that file, and one ladder in two
+ * places is one ladder that can drift.
+ */
+import type { Animation, BorderWidth } from "@multiplatform.one/theme";
+import type { BuiltinEdgeKind } from "./edgeKinds";
+export type EdgePathKind = "bezier" | "smoothstep" | "step" | "straight";
+export type EdgeMarker = "arrow" | "arrowclosed";
+export interface EdgeAppearance {
+    readonly path: EdgePathKind;
+    /** A token expression. A hex literal here fails `edgeStyle.spec.ts`. */
+    readonly stroke: string;
+    /** SVG `stroke-dasharray`. Absent means a solid line. */
+    readonly dash?: string;
+    readonly marker: EdgeMarker;
+}
+/** Design §4.4's table, verbatim. */
+export declare const edgeAppearances: Readonly<Record<BuiltinEdgeKind, EdgeAppearance>>;
+/**
+ * §11: an edge is a stroke, not a border, and a 0-width edge erases the graph's
+ * primary information. The theme's own `borderWidthMap` is 0 / 0.5 / 1 / 2
+ * (`public/theme/src/theme/resolveKnobs.ts:90`), so this is a remap, and
+ * deliberately not a floor to `hairlineWidth` — that token is dividers-only by
+ * its own header, and a stroke that stays legible while the canvas zooms out is
+ * not a divider.
+ */
+export declare const edgeStrokeWidths: Readonly<Record<BorderWidth, number>>;
+export declare function edgeStrokeWidth(borderWidth: BorderWidth): number;
+/** The keyframes live in `css/graph.css`, which lands with task 1.7. */
+export declare const dashAnimation = "mp-graph-dash 0.5s linear infinite";
+/**
+ * The marker goes on the EDGE OBJECT, not on the rendered path.
+ *
+ * React Flow builds its `<marker>` defs from the edges array and hands the
+ * component an already-resolved `url(#...)` string, so `BaseEdge`'s `markerEnd`
+ * is a string and cannot take a type. Measured against
+ * `@xyflow/react` 12.11.5's `BaseEdgeProps`. So whoever BUILDS the edges — the
+ * controller in task 1.11, or a story — reads the marker from here.
+ */
+export declare function edgeMarkerEnd(input: {
+    readonly kind: string;
+    readonly appearance?: string;
+}): {
+    readonly type: EdgeMarker;
+};
+export interface EdgeStyleInput {
+    /** `edge.kind` from the model, not React Flow's `edge.type`. */
+    readonly kind: string;
+    /** `EdgeKindSpec.appearance`, when the kind is not one of the four. */
+    readonly appearance?: string;
+    readonly borderWidth: BorderWidth;
+    readonly animation: Animation;
+}
+/**
+ * `"$color9"` -> `"color9"`. The theme key, so a renderer can look the token up
+ * without the appearance table ever holding a resolved colour — which is what
+ * keeps `edgeStyle.spec.ts`'s hex ban meaningful.
+ */
+export declare function themeTokenName(stroke: string): string;
+export interface EdgeStyle {
+    readonly path: EdgePathKind;
+    readonly stroke: string;
+    readonly strokeWidth: number;
+    readonly strokeDasharray?: string;
+    readonly marker: EdgeMarker;
+    /** A CSS `animation` shorthand. `"none"` when the knob says so. */
+    readonly animation: string;
+}
+export declare function resolveEdgeStyle(input: EdgeStyleInput): EdgeStyle;
+//# sourceMappingURL=edgeStyle.d.ts.map

package/types/edges/edgeStyle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edgeStyle.d.ts","sourceRoot":"","sources":["../../src/edges/edgeStyle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,YAAY,GAAG,MAAM,GAAG,UAAU,CAAC;AACzE,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,aAAa,CAAC;AAEjD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,wEAAwE;IACxE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yDAAyD;IACzD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;CAC7B;AAED,qCAAqC;AACrC,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,eAAe,EAAE,cAAc,CAAC,CAK7E,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,CAKlE,CAAC;AAEF,wBAAgB,eAAe,CAAC,WAAW,EAAE,WAAW,GAAG,MAAM,CAEhE;AAED,wEAAwE;AACxE,eAAO,MAAM,aAAa,uCAAuC,CAAC;AAMlE;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG;IAC7F,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;CAC3B,CAGA;AAED,MAAM,WAAW,cAAc;IAC7B,gEAAgE;IAChE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uEAAuE;IACvE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;CAC/B;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,mEAAmE;IACnE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,cAAc,GAAG,SAAS,CAgBjE"}