@tellegen/svelte 0.4.2 → 0.4.4

package/dist/diagram/snapshot.js

@@ -0,0 +1,242 @@
+import { neutralTerminal } from '../multiconductor.js';
+/** The second member of a phase–ground pair. */
+export const GROUND = 'ground';
+const magnitude = (z) => Math.hypot(z.re, z.im);
+const sub = (a, b) => ({ re: a.re - b.re, im: a.im - b.im });
+/** Voltage unbalance factor |V2| / |V1| in percent, from three phasors in phase order. The ratio
+ * is the same for phase–neutral and phase–phase voltages, so either reference works. */
+export function sequenceUnbalance(a, b, c) {
+    // α = e^{j2π/3}: V1 = (a + α b + α² c) / 3, V2 = (a + α² b + α c) / 3.
+    const h = Math.sqrt(3) / 2;
+    const rot = (z, s) => ({
+        re: -0.5 * z.re - s * h * z.im,
+        im: s * h * z.re - 0.5 * z.im
+    });
+    const v1 = { re: a.re + rot(b, 1).re + rot(c, -1).re, im: a.im + rot(b, 1).im + rot(c, -1).im };
+    const v2 = { re: a.re + rot(b, -1).re + rot(c, 1).re, im: a.im + rot(b, -1).im + rot(c, 1).im };
+    const positive = magnitude(v1);
+    return positive > 0 ? (100 * magnitude(v2)) / positive : null;
+}
+function busSnapshot(bus, voltage) {
+    // A declared neutral (or a declared absence of one) wins; aliases only when nothing is declared.
+    const neutral = neutralTerminal(bus.terminals, bus.neutral);
+    const phases = bus.terminals.filter((t) => t !== neutral);
+    const limits = bus.limits ?? {};
+    const pairs = [];
+    const phasors = [];
+    const zero = { re: 0, im: 0 };
+    // Each declared reference that applies here gets its pairs. Without one, phase–neutral where
+    // there is a neutral, else phase–phase on three phases.
+    const ground = limits.phaseGround ?? [];
+    // Phase–phase pairs in the order (1,2), (2,3), (3,1), each with its declared band.
+    const triple = phases.length === 3
+        ? [
+            [phases[0], phases[1]],
+            [phases[1], phases[2]],
+            [phases[2], phases[0]]
+        ]
+        : [];
+    const declaredBands = limits.phasePhase;
+    const bands = declaredBands
+        ? triple.map(([a, b]) => declaredBands.find(({ pair }) => !pair || (pair[0] === a && pair[1] === b) || (pair[0] === b && pair[1] === a)) ?? null)
+        : [];
+    const declared = (!!neutral && !!limits.phaseNeutral) || bands.some((band) => band) || ground.length > 0;
+    if (neutral && (limits.phaseNeutral || !declared)) {
+        const vn = voltage(neutral) ?? zero;
+        phases.forEach((t, i) => {
+            const v = voltage(t);
+            if (!v)
+                return;
+            pairs.push({
+                pair: [t, neutral],
+                zone: 'phase–neutral',
+                volts: magnitude(sub(v, vn)),
+                min: limits.phaseNeutral?.min[i] ?? null,
+                max: limits.phaseNeutral?.max[i] ?? null
+            });
+            phasors.push(sub(v, vn));
+        });
+    }
+    if (triple.length && (bands.some((band) => band) || (!declared && !neutral))) {
+        triple.forEach(([a, b], k) => {
+            const va = voltage(a);
+            const vb = voltage(b);
+            if (!va || !vb)
+                return;
+            pairs.push({
+                pair: [a, b],
+                zone: 'phase–phase',
+                volts: magnitude(sub(va, vb)),
+                min: bands[k]?.min ?? null,
+                max: bands[k]?.max ?? null
+            });
+        });
+    }
+    // Terminal voltages are to ground, so a phase–ground pair is the terminal's own magnitude.
+    for (const { terminal, min, max } of ground) {
+        const v = voltage(terminal);
+        if (v)
+            pairs.push({ pair: [terminal, GROUND], zone: 'phase–ground', volts: magnitude(v), min, max });
+    }
+    // VUF is the same from any reference: a shared neutral shift is zero sequence, and phase–phase
+    // differences scale both sequences alike. Without phase–neutral phasors, the phase terminals'.
+    if (!phasors.length && phases.length === 3)
+        for (const t of phases) {
+            const v = voltage(t);
+            if (v)
+                phasors.push(v);
+        }
+    const vuf = phasors.length === 3 ? sequenceUnbalance(phasors[0], phasors[1], phasors[2]) : null;
+    return { pairs, unbalance: vuf === null ? null : { percent: vuf, definition: 'VUF' } };
+}
+/** Project a full multiconductor power-flow result onto the drawing's bus and branch order.
+ * Missing ports leave an end `null`; nothing is interpolated. */
+export function snapshotFromMcPf(result, buses, branches, label = 'Tellegen multiconductor power flow') {
+    // Nested maps keyed by bus, then element: no composite string keys on a 100k-bus result.
+    const voltages = new Map();
+    for (const t of result.terminals) {
+        let bus = voltages.get(t.bus);
+        if (!bus)
+            voltages.set(t.bus, (bus = new Map()));
+        bus.set(t.terminal, t.voltage);
+    }
+    const ports = new Map();
+    for (const p of result.element_ports) {
+        let element = ports.get(p.element);
+        if (!element)
+            ports.set(p.element, (element = new Map()));
+        const rows = element.get(p.bus);
+        if (rows)
+            rows.push(p);
+        else
+            element.set(p.bus, [p]);
+    }
+    /** The element's port rows, of its own kind when a line and a switch share a name. A closed
+     * switch has no ports of its own (the solver merges its buses), so it must not borrow another
+     * element's rows. */
+    const elementPorts = (branch, bus) => {
+        const all = ports.get(branch.id)?.get(bus);
+        if (!all || branch.kind === undefined)
+            return all;
+        return all.filter((r) => r.kind === branch.kind);
+    };
+    const seen = new Set();
+    const branchSnapshots = branches.map((branch) => {
+        const key = `${branch.kind ?? ''}\u0000${branch.id}`;
+        const primary = !seen.has(key);
+        seen.add(key);
+        const ends = [branch.from, branch.to].map((bus, side) => {
+            const rows = elementPorts(branch, bus);
+            if (!branch.inService || !rows?.length)
+                return null;
+            let p = 0;
+            let q = 0;
+            const byTerminal = new Map();
+            for (const r of rows) {
+                p += r.power_into_element.re;
+                q += r.power_into_element.im;
+                byTerminal.set(r.terminal, r);
+            }
+            const currents = [];
+            for (const terminal of side ? branch.toTerminals : branch.fromTerminals) {
+                const row = byTerminal.get(terminal);
+                if (row)
+                    currents.push({ terminal, amps: magnitude(row.current_into_element) });
+            }
+            return { p: p / 1000, q: q / 1000, currents };
+        });
+        return {
+            ends,
+            ...loadingOf(branch, ends, elementPorts),
+            primary,
+            loss: primary ? equipmentLoss(branch, elementPorts) : null
+        };
+    });
+    return {
+        kind: 'solved',
+        label,
+        iterations: result.iterations,
+        buses: buses.map((bus) => {
+            const terminals = voltages.get(bus.id);
+            return busSnapshot(bus, (t) => terminals?.get(t));
+        }),
+        branches: branchSnapshots
+    };
+}
+/** Bus results from a live session's transferred terminal arrays (`[re, im]` interleaved), for when
+ * the full result with element ports has not been fetched. Branches are left without results. */
+export function snapshotBusesFromTerminals(ids, voltages, buses) {
+    const index = new Map();
+    for (let k = 0; k < ids.length; k++)
+        index.set(`${ids[k][0]}\u0000${ids[k][1]}`, k);
+    return buses.map((bus) => busSnapshot(bus, (t) => {
+        const k = index.get(`${bus.id}\u0000${t}`);
+        return k === undefined ? undefined : { re: voltages[2 * k], im: voltages[2 * k + 1] };
+    }));
+}
+/** Power summed over a set of port rows, in kW and kvar. */
+function portPower(rows) {
+    let p = 0;
+    let q = 0;
+    for (const r of rows) {
+        p += r.power_into_element.re;
+        q += r.power_into_element.im;
+    }
+    return { p: p / 1000, q: q / 1000 };
+}
+/** Both ends' ports are signed into the equipment, so their sum over every bus it connects is what
+ * it consumes. Each bus counts once, however many winding pairs join it. */
+function equipmentLoss(branch, rows) {
+    if (!branch.inService)
+        return null;
+    const buses = new Set([branch.from, branch.to]);
+    if (branch.rating?.kind === 'apparent')
+        for (const bus of Object.keys(branch.rating.byBus))
+            buses.add(bus);
+    let p = 0;
+    let q = 0;
+    for (const bus of buses) {
+        const at = rows(branch, bus);
+        if (!at?.length)
+            return null;
+        const power = portPower(at);
+        p += power.p;
+        q += power.q;
+    }
+    return { p, q };
+}
+function loadingOf(branch, ends, rows) {
+    const rating = branch.rating;
+    if (!rating || !ends[0] || !ends[1])
+        return { loading: null, basis: null };
+    if (rating.kind === 'current') {
+        const ratios = ends.flatMap((end, side) => (end?.currents ?? []).map((c) => {
+            const k = (side ? branch.toTerminals : branch.fromTerminals).indexOf(c.terminal);
+            return rating.amps[k] > 0 ? c.amps / rating.amps[k] : NaN;
+        }));
+        return ratios.length && ratios.every(Number.isFinite)
+            ? {
+                loading: 100 * Math.max(...ratios),
+                basis: 'Maximum conductor |I| / rating across both ends'
+            }
+            : { loading: null, basis: null };
+    }
+    // Judged per bus against the transformer's rating there, so a winding-pair edge whose two ends
+    // are the same bus (a centre tap's halves) is not counted twice.
+    let loading = null;
+    for (const [bus, va] of Object.entries(rating.byBus)) {
+        const at = rows(branch, bus);
+        if (!(va > 0) || !at?.length)
+            continue;
+        const { p, q } = portPower(at);
+        const percent = (100 * Math.hypot(p, q) * 1000) / va;
+        if (loading === null || percent > loading)
+            loading = percent;
+    }
+    return loading === null
+        ? { loading: null, basis: null }
+        : {
+            loading,
+            basis: 'Maximum |S| at a connected bus / rating there; aggregate, not per winding'
+        };
+}

package/dist/diagram/summary.d.ts

@@ -0,0 +1,65 @@
+import type { BusSnapshot, PairVoltage, PairZone, ResultSnapshot, UnbalanceValue } from './snapshot.js';
+/** Loading thresholds in percent of rating: a warning from the shared attention line, a violation
+ * above the rating itself, since the multiconductor power flow does not enforce ratings. */
+export declare const LOADING_WARNING: number;
+export declare const LOADING_LIMIT = 100;
+export type VoltageState = 'normal' | 'violation' | 'unbounded' | 'missing';
+export type LoadingState = 'normal' | 'warning' | 'violation' | 'missing';
+export declare function pairState(p: PairVoltage): VoltageState;
+export declare function busState(bus: BusSnapshot): VoltageState;
+export declare function loadingState(loading: number | null): LoadingState;
+/** Distance outside [min, max] as a percentage of the violated limit; negative inside the band. */
+export declare function exceedance(p: PairVoltage): number;
+/** Magnitude-only fallback: max deviation from the mean / mean (IEEE PVUR or NEMA LVUR), over the
+ * three pairs of the bus's first reference. */
+export declare function magnitudeUnbalance(all: PairVoltage[]): UnbalanceValue | null;
+/** Phasor unbalance when the snapshot has it, otherwise the labelled magnitude fallback. */
+export declare const busUnbalance: (bus: BusSnapshot) => UnbalanceValue | null;
+export interface Issue {
+    kind: 'voltage' | 'loading';
+    severity: 'violation' | 'warning';
+    target: {
+        kind: 'bus' | 'branch';
+        index: number;
+    };
+    value: number;
+    limit: number;
+    score: number;
+    pair?: [string, string];
+    low?: boolean;
+}
+/** Violations first, then the largest relative exceedance; the index keeps ties deterministic. */
+export declare function rankIssues(result: ResultSnapshot): Issue[];
+export interface VoltageExtreme {
+    bus: number;
+    pair: [string, string];
+    volts: number;
+    state: VoltageState;
+}
+export interface ZoneSummary {
+    zone: PairZone;
+    min: VoltageExtreme;
+    max: VoltageExtreme;
+    buses: number;
+}
+export interface SnapshotSummary {
+    loss: {
+        p: number;
+        q: number;
+        branches: number;
+    };
+    loading: {
+        branch: number;
+        value: number;
+    } | null;
+    unbalance: (UnbalanceValue & {
+        bus: number;
+    }) | null;
+    zones: ZoneSummary[];
+    counts: {
+        voltage: number;
+        overload: number;
+        warning: number;
+    };
+}
+export declare function snapshotSummary(result: ResultSnapshot, issues?: Issue[]): SnapshotSummary;

package/dist/diagram/summary.js

@@ -0,0 +1,144 @@
+import { LOADING_ATTENTION } from '../colors.js';
+/** Loading thresholds in percent of rating: a warning from the shared attention line, a violation
+ * above the rating itself, since the multiconductor power flow does not enforce ratings. */
+export const LOADING_WARNING = 100 * LOADING_ATTENTION;
+export const LOADING_LIMIT = 100;
+export function pairState(p) {
+    if (!Number.isFinite(p.volts))
+        return 'missing';
+    if (p.min === null || p.max === null)
+        return 'unbounded';
+    return p.volts < p.min || p.volts > p.max ? 'violation' : 'normal';
+}
+export function busState(bus) {
+    if (!bus.pairs.length)
+        return 'missing';
+    const states = bus.pairs.map(pairState);
+    return states.includes('violation')
+        ? 'violation'
+        : states.includes('normal')
+            ? 'normal'
+            : states[0];
+}
+export function loadingState(loading) {
+    if (loading === null || !Number.isFinite(loading))
+        return 'missing';
+    return loading > LOADING_LIMIT ? 'violation' : loading >= LOADING_WARNING ? 'warning' : 'normal';
+}
+/** Distance outside [min, max] as a percentage of the violated limit; negative inside the band. */
+export function exceedance(p) {
+    if (p.min === null || p.max === null)
+        return Number.NEGATIVE_INFINITY;
+    if (p.volts < p.min)
+        return (100 * (p.min - p.volts)) / p.min;
+    if (p.volts > p.max)
+        return (100 * (p.volts - p.max)) / p.max;
+    return (-100 * Math.min(p.volts - p.min, p.max - p.volts)) / (p.max - p.min);
+}
+/** Magnitude-only fallback: max deviation from the mean / mean (IEEE PVUR or NEMA LVUR), over the
+ * three pairs of the bus's first reference. */
+export function magnitudeUnbalance(all) {
+    const zone = all[0]?.zone;
+    const pairs = all.filter((p) => p.zone === zone);
+    if (pairs.length !== 3)
+        return null;
+    const mean = (pairs[0].volts + pairs[1].volts + pairs[2].volts) / 3;
+    if (!(mean > 0))
+        return null;
+    const percent = (100 * Math.max(...pairs.map((p) => Math.abs(p.volts - mean)))) / mean;
+    return { percent, definition: zone === 'phase–phase' ? 'NEMA LVUR' : 'IEEE PVUR' };
+}
+/** Phasor unbalance when the snapshot has it, otherwise the labelled magnitude fallback. */
+export const busUnbalance = (bus) => bus.unbalance ?? magnitudeUnbalance(bus.pairs);
+/** Violations first, then the largest relative exceedance; the index keeps ties deterministic. */
+export function rankIssues(result) {
+    const issues = [];
+    result.buses.forEach((bus, index) => {
+        let worst = null;
+        for (const p of bus.pairs) {
+            if (pairState(p) === 'violation' && (!worst || exceedance(p) > exceedance(worst)))
+                worst = p;
+        }
+        if (!worst || worst.min === null || worst.max === null)
+            return;
+        const low = worst.volts < worst.min;
+        issues.push({
+            kind: 'voltage',
+            severity: 'violation',
+            target: { kind: 'bus', index },
+            pair: worst.pair,
+            value: worst.volts,
+            limit: low ? worst.min : worst.max,
+            low,
+            score: exceedance(worst)
+        });
+    });
+    result.branches.forEach((branch, index) => {
+        if (!branch.primary)
+            return;
+        const state = loadingState(branch.loading);
+        if (state !== 'warning' && state !== 'violation')
+            return;
+        const value = branch.loading;
+        issues.push({
+            kind: 'loading',
+            severity: state,
+            target: { kind: 'branch', index },
+            value,
+            limit: LOADING_LIMIT,
+            score: value - LOADING_LIMIT
+        });
+    });
+    const rank = (i) => (i.severity === 'violation' ? 0 : 1);
+    return issues.sort((a, b) => rank(a) - rank(b) || b.score - a.score || a.target.index - b.target.index);
+}
+export function snapshotSummary(result, issues = rankIssues(result)) {
+    const zones = new Map();
+    let unbalance = null;
+    result.buses.forEach((bus, index) => {
+        for (const p of bus.pairs) {
+            const extreme = { bus: index, pair: p.pair, volts: p.volts, state: pairState(p) };
+            const zone = zones.get(p.zone);
+            if (!zone)
+                zones.set(p.zone, { min: extreme, max: extreme, buses: new Set([index]) });
+            else {
+                zone.buses.add(index);
+                if (p.volts < zone.min.volts)
+                    zone.min = extreme;
+                if (p.volts > zone.max.volts)
+                    zone.max = extreme;
+            }
+        }
+        const u = busUnbalance(bus);
+        if (u && (!unbalance || u.percent > unbalance.percent))
+            unbalance = { ...u, bus: index };
+    });
+    const loss = { p: 0, q: 0, branches: 0 };
+    let loading = null;
+    result.branches.forEach((branch, index) => {
+        // Once per piece of equipment: a multi-winding transformer has several edges.
+        if (branch.loss) {
+            loss.p += branch.loss.p;
+            loss.q += branch.loss.q;
+            loss.branches++;
+        }
+        if (branch.loading !== null &&
+            Number.isFinite(branch.loading) &&
+            (!loading || branch.loading > loading.value))
+            loading = { branch: index, value: branch.loading };
+    });
+    const count = (kind, severity) => issues.filter((i) => i.kind === kind && i.severity === severity).length;
+    return {
+        loss,
+        loading,
+        unbalance,
+        zones: [...zones]
+            .map(([zone, z]) => ({ zone, min: z.min, max: z.max, buses: z.buses.size }))
+            .sort((a, b) => b.max.volts - a.max.volts),
+        counts: {
+            voltage: count('voltage', 'violation'),
+            overload: count('loading', 'violation'),
+            warning: count('loading', 'warning')
+        }
+    };
+}

package/dist/diagram/svg-export.d.ts

@@ -0,0 +1,80 @@
+/** Report-ready vector export of the visible view with a title block. Pure: no DOM. */
+export declare const TITLE_BLOCK_HEIGHT = 76;
+export declare const MAX_SVG_SEGMENTS = 200000;
+export interface LineSet {
+    sources: ArrayLike<number>;
+    targets: ArrayLike<number>;
+    /** RGBA bytes per segment. */
+    colors: ArrayLike<number>;
+    count: number;
+    /** Per-segment pixel widths; `width` applies when absent. */
+    widths?: ArrayLike<number> | null;
+    width?: number;
+}
+export interface SvgText {
+    position: ArrayLike<number>;
+    text: string;
+    color?: string;
+    dx?: number;
+    dy?: number;
+}
+export interface SvgGlyph {
+    position: ArrayLike<number>;
+    text: string;
+    /** Counter-clockwise degrees, as text layers use. */
+    angle: number;
+    color: string;
+    size?: number;
+}
+export interface TitleBlock {
+    left: string[];
+    right: string[];
+}
+export interface SvgView {
+    /** World bounds `[x0, y0, x1, y1]`, y down. */
+    bounds: [number, number, number, number];
+    scale: number;
+    width: number;
+    height: number;
+    background: string;
+    ink: string;
+    muted: string;
+    lineSets?: LineSet[];
+    points?: {
+        positions: ArrayLike<number>;
+        colors: ArrayLike<number>;
+        count: number;
+        radius: number;
+    } | null;
+    markers?: {
+        position: ArrayLike<number>;
+        radius: number;
+        fill?: string;
+        stroke?: string;
+    }[];
+    glyphs?: SvgGlyph[];
+    texts?: SvgText[];
+    title: TitleBlock;
+}
+/** Fit a title-block line into its column; monospace makes character count a safe width proxy. */
+export declare function fitText(text: string, px: number): string;
+/** Visible segments only, one path per colour and width. Throws rather than writing a partial
+ * drawing when the view holds more than {@link MAX_SVG_SEGMENTS}. */
+export declare function viewportSvg(view: SvgView): string;
+/** What was drawn, which view, and the provenance needed to reproduce it. */
+export declare function titleBlock(t: {
+    dataset: string;
+    layout: string;
+    view: string;
+    camera: {
+        target: ArrayLike<number>;
+        zoom: number;
+    };
+    result: {
+        kind: 'solved' | 'stress';
+        label: string;
+        iterations: number | null;
+        revision: string;
+    } | null;
+    exported: string;
+}): TitleBlock;

package/dist/diagram/svg-export.js

@@ -0,0 +1,108 @@
+/** Report-ready vector export of the visible view with a title block. Pure: no DOM. */
+export const TITLE_BLOCK_HEIGHT = 76;
+export const MAX_SVG_SEGMENTS = 200_000;
+const CHAR_PX = 6.7;
+const escapeXml = (v) => v.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
+const rgb = (c, i = 0) => `rgb(${c[i]} ${c[i + 1]} ${c[i + 2]})`;
+const r1 = (v) => Math.round(v * 10) / 10;
+/** Fit a title-block line into its column; monospace makes character count a safe width proxy. */
+export function fitText(text, px) {
+    const n = Math.max(4, Math.floor((px - 24) / CHAR_PX));
+    return text.length > n ? `${text.slice(0, n - 1)}…` : text;
+}
+/** Visible segments only, one path per colour and width. Throws rather than writing a partial
+ * drawing when the view holds more than {@link MAX_SVG_SEGMENTS}. */
+export function viewportSvg(view) {
+    const [x0, y0, x1, y1] = view.bounds;
+    const X = (x) => r1((x - x0) * view.scale);
+    const Y = (y) => r1((y - y0) * view.scale);
+    const inside = (p) => p[0] >= x0 && p[0] <= x1 && p[1] >= y0 && p[1] <= y1;
+    const groups = new Map();
+    let segments = 0;
+    for (const set of view.lineSets ?? []) {
+        const { sources: s, targets: t, colors } = set;
+        for (let i = 0; i < set.count; i++) {
+            const [ax, ay, bx, by] = [s[i * 3], s[i * 3 + 1], t[i * 3], t[i * 3 + 1]];
+            if (Math.max(ax, bx) < x0 ||
+                Math.min(ax, bx) > x1 ||
+                Math.max(ay, by) < y0 ||
+                Math.min(ay, by) > y1)
+                continue;
+            if (++segments > MAX_SVG_SEGMENTS)
+                throw new Error(`More than ${MAX_SVG_SEGMENTS.toLocaleString()} segments in view; zoom in to export a vector drawing`);
+            if (colors[i * 4 + 3] === 0)
+                continue;
+            const key = `${rgb(colors, i * 4)}|${set.widths ? r1(set.widths[i]) : (set.width ?? 1)}|${r1(colors[i * 4 + 3] / 255)}`;
+            const d = `M${X(ax)} ${Y(ay)}L${X(bx)} ${Y(by)}`;
+            const group = groups.get(key);
+            if (group)
+                group.push(d);
+            else
+                groups.set(key, [d]);
+        }
+    }
+    const paths = [...groups].map(([key, d]) => {
+        const [stroke, width, alpha] = key.split('|');
+        const opacity = Number(alpha) < 1 ? ` stroke-opacity="${alpha}"` : '';
+        return `<path d="${d.join('')}" stroke="${stroke}" stroke-width="${width}"${opacity}/>`;
+    });
+    const dots = [];
+    const points = view.points;
+    if (points)
+        for (let i = 0; i < points.count; i++) {
+            const p = [points.positions[i * 3], points.positions[i * 3 + 1]];
+            if (inside(p))
+                dots.push(`<circle cx="${X(p[0])}" cy="${Y(p[1])}" r="${points.radius}" fill="${rgb(points.colors, i * 4)}"/>`);
+        }
+    for (const m of view.markers ?? [])
+        if (inside(m.position)) {
+            const stroke = m.stroke ? ` stroke="${m.stroke}" stroke-width="1.5"` : '';
+            dots.push(`<circle cx="${X(m.position[0])}" cy="${Y(m.position[1])}" r="${m.radius}" fill="${m.fill ?? 'none'}"${stroke}/>`);
+        }
+    // Text-layer angles are counter-clockwise; SVG rotation is clockwise.
+    const arrows = (view.glyphs ?? [])
+        .filter((g) => inside(g.position))
+        .map((g) => {
+        const [x, y] = [X(g.position[0]), Y(g.position[1])];
+        return `<text x="${x}" y="${y}" fill="${g.color}" font-size="${g.size ?? 22}" text-anchor="middle" dominant-baseline="central" transform="rotate(${r1(-g.angle)} ${x} ${y})">${escapeXml(g.text)}</text>`;
+    });
+    const labels = (view.texts ?? [])
+        .filter((t) => inside(t.position))
+        .map((t) => `<text x="${X(t.position[0]) + (t.dx ?? 0)}" y="${Y(t.position[1]) + (t.dy ?? 0)}" fill="${t.color ?? view.ink}">${escapeXml(t.text)}</text>`);
+    const { width, height } = view;
+    const column = width / 2;
+    const line = (x, y, text, cls) => `<text x="${x}" y="${y}" class="${cls}">${escapeXml(fitText(text, column))}</text>`;
+    const block = [
+        `<rect x="0" y="${height}" width="${width}" height="${TITLE_BLOCK_HEIGHT}" fill="${view.background}"/>`,
+        `<line x1="0" x2="${width}" y1="${height + 0.5}" y2="${height + 0.5}" stroke="${view.muted}"/>`,
+        ...view.title.left.map((t, i) => line(12, height + 18 + i * 15, t, i ? 'muted' : 'strong')),
+        ...view.title.right.map((t, i) => line(column + 12, height + 18 + i * 15, t, 'muted'))
+    ];
+    const total = height + TITLE_BLOCK_HEIGHT;
+    return (`<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${total}" viewBox="0 0 ${width} ${total}" font-family="IBM Plex Mono, ui-monospace, monospace" font-size="11">` +
+        `<style>path{fill:none;stroke-linecap:round}.muted{fill:${view.muted}}.strong{fill:${view.ink};font-size:12px;font-weight:600}</style>` +
+        `<rect width="${width}" height="${height}" fill="${view.background}"/>` +
+        `<g>${paths.join('')}</g><g>${dots.join('')}</g><g>${arrows.join('')}</g><g>${labels.join('')}</g>${block.join('')}</svg>`);
+}
+/** What was drawn, which view, and the provenance needed to reproduce it. */
+export function titleBlock(t) {
+    const r = t.result;
+    return {
+        left: [
+            t.dataset,
+            t.layout,
+            t.view,
+            `Centre ${t.camera.target[0].toFixed(1)}, ${t.camera.target[1].toFixed(1)} · ${(2 ** t.camera.zoom).toPrecision(3)}×`
+        ],
+        right: [
+            r?.kind === 'stress'
+                ? 'ARTIFICIAL STRESS: NOT A SOLUTION'
+                : r
+                    ? `${r.label}${r.iterations === null ? '' : ` · ${r.iterations} iterations`}`
+                    : 'No result snapshot',
+            r ? `Result revision ${r.revision.slice(0, 16)}${r.revision.length > 16 ? '…' : ''}` : '',
+            'P/Q positive into equipment at each end',
+            `Exported ${t.exported}`
+        ].filter(Boolean)
+    };
+}

package/dist/diagram/tree-walk.d.ts

@@ -0,0 +1,13 @@
+import type { DistGraph } from '@tellegen/engine';
+import type { DisplayTree } from './display-tree.js';
+export type WalkKey = 'parent' | 'child' | 'previous' | 'next' | 'root';
+/** Keyboard navigation over the display tree, ordered as drawn: siblings and roots by their
+ * position (top to bottom, then left to right), so Up and Down move as the eye does. */
+export interface TreeWalk {
+    step(from: number, key: WalkKey): number;
+    children: number[][];
+}
+export declare function treeWalk(tree: DisplayTree, positions: ArrayLike<number>, stride?: number): TreeWalk;
+/** A spoken description of bus `i` for the keyboard cursor: where it sits in the tree, what hangs
+ * off it, and an optional result note (for example the worst voltage against its band). */
+export declare function describeBus(graph: DistGraph, tree: DisplayTree, walk: TreeWalk, i: number, note?: string | null): string;