@formicoidea/labre-core 0.43.1 → 0.45.0

package/dist/_pkgs/affine-block-surface/extensions/selection-pane/tree.js

@@ -0,0 +1,323 @@
+import { CanvasLocalVisibility } from '../../../affine-shared/services/index.js';
+import { LifeCycleWatcher } from '../../../std/index.js';
+import { GfxBlockElementModel, GfxControllerIdentifier, GfxGroupLikeElementModel, GfxPrimitiveElementModel, DEFAULT_LAYER_ID, isStoredHiddenForEveryone, } from '../../../std/gfx/index.js';
+import { computed, effect, signal, } from '@preact/signals-core';
+import { userLayersBottomUp } from '../user-layers/actions.js';
+/** The default layer's reserved id (ADR 0031 §2), re-exported from std. */
+export { DEFAULT_LAYER_ID };
+const NOTHING_HIDDEN = new Set();
+/**
+ * The layers of a surface with no `layers` record: the default layer alone,
+ * shown but not written (ADR 0031 §2 and amendments). Every model is in it,
+ * whatever its own key says — with no record, every id is dangling.
+ */
+function unrecordedDefaultLayer(hiddenLocally) {
+    return {
+        order: [DEFAULT_LAYER_ID],
+        ranks: new Map(),
+        effectiveLayerOf: () => DEFAULT_LAYER_ID,
+        hiddenLocally,
+    };
+}
+/**
+ * The group-like ELEMENT a model is listed under, or `null` for a top-level
+ * row.
+ *
+ * Frames are deliberately not containers here, although they are
+ * group-compatible for z-order: a frame is a slide, and the pane filters BY
+ * frame rather than nesting under one — exactly the line ADR 0031 §4 draws for
+ * layers. `group` walks the model's surface, which throws on a model that is
+ * not attached to one; such a model is simply a top-level row.
+ */
+export function paneContainerOf(model) {
+    return containerOf(rawGroupOf(model));
+}
+/** The rule {@link paneContainerOf} applies, to a `group` already read. */
+function containerOf(group) {
+    return group instanceof GfxGroupLikeElementModel ? group : null;
+}
+/** `model.groups`, nearest first, or none where the getter throws. */
+function ancestorsOf(model) {
+    try {
+        return model.groups;
+    }
+    catch {
+        return [];
+    }
+}
+/** `model.group`, or `null` on a model no surface holds (the getter throws). */
+function rawGroupOf(model) {
+    try {
+        return model.group;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The pane's rows, built from the canvas' models: one pass to bucket every
+ * model under its container, one sort per sibling list, top first.
+ *
+ * Pure, so the budget test can time exactly what a live pane pays. The order
+ * is the canvas' own comparator (`compareLayer`) reversed — the paint order,
+ * never a second opinion of it — with one shortcut that is exact: two models
+ * under the same group-like ancestor are ordered by `compareLayer` on their
+ * `index` alone (its ancestor walk finds no difference and falls through to
+ * `compareIndex`). So that case reads two cached strings instead of walking
+ * two ancestor chains per comparison, and only models stacked under different
+ * ancestors (a frame's members beside loose elements) walk their chains, read
+ * once per model rather than once per comparison.
+ *
+ * The top-level rows are the layers; with no `layers` given, the default
+ * layer alone, unrecorded — what a canvas without layers shows.
+ */
+export function buildSelectionPaneTree(models, hiddenLocally = NOTHING_HIDDEN, layers = unrecordedDefaultLayer()) {
+    // A frame is an ordinary row (ADR 0031, amendments), listed where it
+    // paints: a block with no container, so its members — which paint right
+    // above it — are its siblings right above it, never its children.
+    const present = new Set();
+    const groupOf = new Map();
+    const indexOf = new Map();
+    for (const model of models) {
+        present.add(model.id);
+        groupOf.set(model, rawGroupOf(model));
+        indexOf.set(model, model.index);
+    }
+    const layerOf = (model) => layers.effectiveLayerOf(model);
+    // `compareLayer`'s ancestor rule, on ancestor chains read ONCE per model:
+    // `groups` walks the surface on every read, and a frame's members — rows
+    // beside loose elements since frames are rows — compared through
+    // `compareLayer` read it on every comparison, which blew the frame budget.
+    // A chain is the model's ancestors, outermost first, then the model; the
+    // first link two chains do not share decides by `index`, and a chain that
+    // is a prefix of the other is its ancestor, stacked below it. Held to
+    // `compareLayer` by the parity case in `selection-pane.unit.spec.ts`.
+    const chainOf = new Map();
+    const chain = (model) => {
+        let found = chainOf.get(model);
+        if (!found) {
+            found = [...ancestorsOf(model)].reverse().concat(model);
+            chainOf.set(model, found);
+        }
+        return found;
+    };
+    const byAncestors = (a, b) => {
+        const ac = chain(a);
+        const bc = chain(b);
+        let i = 0;
+        while (i < ac.length && i < bc.length && ac[i] === bc[i])
+            i++;
+        if (i === ac.length && i === bc.length)
+            return 0;
+        if (i === ac.length)
+            return -1;
+        if (i === bc.length)
+            return 1;
+        const ai = ac[i].index;
+        const bi = bc[i].index;
+        return ai === bi ? 0 : ai < bi ? -1 : 1;
+    };
+    const paintOrder = (a, b) => {
+        // Rank first, as `compare` does, so the index shortcut below only ever
+        // orders two models of the same layer.
+        const al = layerOf(a);
+        const bl = layerOf(b);
+        if (al !== bl) {
+            const ar = layers.ranks.get(al) ?? '';
+            const br = layers.ranks.get(bl) ?? '';
+            if (ar !== br)
+                return ar < br ? -1 : 1;
+        }
+        if (groupOf.get(a) !== groupOf.get(b))
+            return byAncestors(a, b);
+        const ai = indexOf.get(a);
+        const bi = indexOf.get(b);
+        return ai === bi ? 0 : ai < bi ? -1 : 1;
+    };
+    const buckets = new Map();
+    for (const model of models) {
+        // The `group` read once above: `paneContainerOf` would read it again.
+        const container = containerOf(groupOf.get(model));
+        // A container that is not listed (a stale group id) cannot hold a row:
+        // the member is listed at the top level rather than vanishing.
+        const key = container && present.has(container.id) ? container.id : null;
+        let bucket = buckets.get(key);
+        if (!bucket) {
+            bucket = [];
+            buckets.set(key, bucket);
+        }
+        bucket.push(model);
+    }
+    const build = (key) => {
+        const bucket = buckets.get(key);
+        if (!bucket)
+            return [];
+        bucket.sort((a, b) => paintOrder(b, a));
+        return bucket.map(model => {
+            const block = model instanceof GfxBlockElementModel;
+            const role = model instanceof GfxPrimitiveElementModel ? model.role : undefined;
+            const node = {
+                id: model.id,
+                kind: block ? 'block' : 'element',
+                type: block ? model.flavour : model.type,
+                layerId: layerOf(model),
+                locked: model.lockedBySelf === true,
+                hiddenLocal: hiddenLocally.has(model.id),
+                hiddenForEveryone: isStoredHiddenForEveryone(model),
+            };
+            if (role !== undefined)
+                node.role = role;
+            if (key !== null)
+                node.groupId = key;
+            if (model instanceof GfxGroupLikeElementModel) {
+                node.children = build(model.id);
+            }
+            return node;
+        });
+    };
+    const top = build(null);
+    // The top-level rows are the layers, top first, each holding its members
+    // in paint order. An empty layer is still a row — it is where a drop lands.
+    return layers.order.map(id => ({
+        id,
+        kind: 'layer',
+        type: 'layer',
+        layerId: id,
+        locked: false,
+        hiddenLocal: layers.hiddenLocally?.has(id) ?? false,
+        hiddenForEveryone: layers.hiddenForEveryone?.has(id) ?? false,
+        children: top.filter(node => node.layerId === id),
+    }));
+}
+/**
+ * The element props whose change can move, nest, lock or re-role a row. A
+ * drag writes `xywh` every frame and must not rebuild the tree every frame.
+ */
+const TREE_KEYS = new Set([
+    'index',
+    'layer',
+    'lockedBySelf',
+    'children',
+    'childIds',
+    'role',
+]);
+/**
+ * The surface's user layers as the tree builder takes them; while there is no
+ * record, the default layer alone, unrecorded (nothing is written to show it).
+ * Reads `layers$`, so a `computed` calling it re-derives on a create, a
+ * rename, a reorder — local or a peer's.
+ */
+export function paneLayersOf(surface, hiddenLocally) {
+    surface.props.layers$?.value;
+    const ranks = surface.userLayers?.ranks;
+    if (!ranks)
+        return unrecordedDefaultLayer(hiddenLocally);
+    const bottomUp = userLayersBottomUp(surface);
+    return {
+        order: bottomUp.map(layer => layer.id).reverse(),
+        ranks,
+        effectiveLayerOf: model => surface.userLayers.effectiveLayerOf(model),
+        hiddenLocally,
+        hiddenForEveryone: new Set(bottomUp
+            .filter(layer => layer.record.hidden === true)
+            .map(layer => layer.id)),
+    };
+}
+/**
+ * The live tree behind {@link selectionPaneTree}, one per editor.
+ *
+ * The tree is a `computed` over a revision counter, bumped by the few events
+ * that can change a row (an element or block added or removed, a reorder, a
+ * regroup, a lock) — never by geometry. A `computed` is lazy, so an editor
+ * whose pane is closed and whose host never reads the tree pays the counter
+ * bump and nothing else; an open pane pays one rebuild per relevant change,
+ * not one per frame.
+ *
+ * It also holds whether the LIBRARY's own panel is open (`open$`), which is
+ * what the toggle command reads. A host that replaced the panel through
+ * `SelectionPaneExtension` owns its own open state; `open$` then stays false
+ * and the toggle always opens.
+ */
+export class SelectionPaneModel extends LifeCycleWatcher {
+    constructor() {
+        super(...arguments);
+        this._revision$ = signal(0);
+        this._disposeSurfaceEffect = null;
+        this._subscriptions = [];
+        /** Whether the library's own panel is on screen. Written by that panel. */
+        this.open$ = signal(false);
+        this.tree$ = computed(() => {
+            this._revision$.value;
+            const gfx = this.std.get(GfxControllerIdentifier);
+            const surface = gfx.surface$.value;
+            if (!surface)
+                return [];
+            // Read here, so a local hide or show re-derives the rows' marks.
+            const local = this.std.getOptional(CanvasLocalVisibility);
+            const hidden = local?.hiddenIds$.value;
+            const hiddenLayers = local?.hiddenLayerIds$.value;
+            // And here, so a hide for everyone (local or a peer's) re-derives them too.
+            gfx.hiddenForEveryone?.ids$.value;
+            return buildSelectionPaneTree(gfx.gfxElements, hidden, paneLayersOf(surface, hiddenLayers));
+        });
+        this._surfaceSubscriptions = [];
+    }
+    static { this.key = 'selection-pane-model'; }
+    /** Force a rebuild; for a change no subscribed event reports. */
+    invalidate() {
+        // `peek`, not `value`: called from inside an effect, a READ would
+        // subscribe that effect to the counter it is about to bump.
+        this._revision$.value = this._revision$.peek() + 1;
+    }
+    mounted() {
+        super.mounted();
+        const gfx = this.std.get(GfxControllerIdentifier);
+        const store = this.std.store;
+        this._subscriptions.push(gfx.layer.slots.layerUpdated.subscribe(() => this.invalidate()), store.slots.blockUpdated.subscribe(payload => {
+            if (payload.type !== 'update' || TREE_KEYS.has(payload.props.key)) {
+                this.invalidate();
+            }
+        }));
+        // The surface is a signal: it may arrive after mount, or be replaced.
+        this._disposeSurfaceEffect = effect(() => {
+            const surface = gfx.surface$.value;
+            this._watchSurface(surface);
+        });
+    }
+    _watchSurface(surface) {
+        this._surfaceSubscriptions.forEach(sub => sub.unsubscribe());
+        this._surfaceSubscriptions = [];
+        if (!surface)
+            return;
+        this._surfaceSubscriptions.push(surface.elementAdded.subscribe(() => this.invalidate()), surface.elementRemoved.subscribe(() => this.invalidate()), surface.elementUpdated.subscribe(({ props }) => {
+            for (const key of Object.keys(props)) {
+                if (TREE_KEYS.has(key)) {
+                    this.invalidate();
+                    return;
+                }
+            }
+        }));
+        this.invalidate();
+    }
+    unmounted() {
+        this._disposeSurfaceEffect?.();
+        this._disposeSurfaceEffect = null;
+        this._watchSurface(null);
+        this._subscriptions.forEach(sub => sub.unsubscribe());
+        this._subscriptions = [];
+        this.open$.value = false;
+        super.unmounted();
+    }
+}
+/**
+ * The headless data API of the selection pane (ADR 0031 §12): a signal of
+ * rows, z-order, top first, ids only.
+ *
+ * What a host's own pane renders from, and what the library's panel renders
+ * from — one tree, so the two cannot disagree about the order of a canvas.
+ * Edgeless editors only: the model is registered by the surface's edgeless
+ * view extension.
+ */
+export function selectionPaneTree(std) {
+    return std.get(SelectionPaneModel).tree$;
+}

package/dist/_pkgs/affine-block-surface/extensions/svg-sketch.d.ts

@@ -1,4 +1,5 @@
-import { type InterchangeImportContext, type InterchangeImportResult } from './interchange.js';
+import type { TranslationParams } from '../../affine-shared/services/index.js';
+import { type InterchangeImportContext, type InterchangeImportResult, type InterchangeNote, type SerializedElementProps } from './interchange.js';
 /**
  * **SVG → a canvas sketch.** The platform's VISUAL-tier importer, shared by
  * every framework that declares it (`docs/adr/0012`, P2).
@@ -9,9 +10,11 @@ import { type InterchangeImportContext, type InterchangeImportResult } from './i
  * a one-paragraph statement of its heuristics and its known failure modes" —
  * answered ONCE, here, because every framework that declares `…:svg:import`
  * wraps this one function and therefore owes the same statement. It is
- * referenced by `bpmn:svg:import` and by `wardley:svg:import`; a framework that
- * ever wants a narrower or wider guess writes its own parser and its own
- * paragraph beside it._
+ * referenced by `bpmn:svg:import`; a framework that ever wants a narrower or
+ * wider guess writes its own parser and its own paragraph beside it. Wardley
+ * did (ADR 0032): a framework may CLAIM nodes before the walk below
+ * ({@link sanitizeSvg}, {@link sketchSvgTree}), and then owes its own statement
+ * for what it claims — this one still covers everything it leaves here._
  *
  * **What it guesses.** An SVG carries a rendering, not a model, so this reader
  * recognises GEOMETRY and nothing else: `<rect>` becomes a rectangle,
@@ -91,6 +94,110 @@ import { type InterchangeImportContext, type InterchangeImportResult } from './i
 export declare const SVG_SKETCH_FORMAT_ID = "svg";
 export declare const SVG_SKETCH_EXTENSION = ".svg";
 export declare const SVG_SKETCH_MIME = "image/svg+xml";
+/**
+ * The note channel, deduplicated on a key.
+ *
+ * D1's discipline, carried across to a tier that has no D1: nothing is dropped
+ * silently. What changes is the GRANULARITY — a file with four hundred
+ * `<use>` instances is one fact about the file, not four hundred, and a report
+ * nobody reads to the end is a report that was not written.
+ *
+ * Every note is a `warning`. The other four kinds would be lies here:
+ * `carried` and `quarantined` describe a payload this tier does not write, and
+ * `substituted-id` and `invented-layout` describe promises it does not make.
+ *
+ * Exported so a framework that claims part of a picture first (ADR 0032 §2)
+ * hands the SAME notebook to {@link sanitizeSvg} and {@link sketchSvgTree}: one
+ * file, one de-duplication, one list of remarks.
+ */
+export declare class SvgSketchNotebook {
+    private readonly seen;
+    readonly notes: InterchangeNote[];
+    /**
+     * @param dedupKey De-duplication identity — a note fires once per distinct
+     *   value (`font-unit:px`, `font-unit:pt`…), independent of the i18n key
+     *   below, which stays the same across all of them.
+     * @param message The English sentence, already filled in with the file's
+     *   own words — shown as is with no host catalogue registered.
+     * @param wording The key/fallback pair for this sentence's SHAPE
+     *   (`svg-sketch-translations.ts`), and the params that fill its
+     *   `{{name}}` holes when it has any.
+     */
+    once(dedupKey: string, message: string, wording: readonly [key: string, fallback: string], params?: TranslationParams, element?: string): void;
+}
+/**
+ * How a user-space coordinate at this depth becomes a canvas coordinate:
+ * `canvas = user * s + o`.
+ *
+ * Carrying the SCALE rather than only the offset is what makes a `viewBox`
+ * honest. `width="200" viewBox="0 0 1000 1000"` is a drawing authored at 1000
+ * units and displayed at 200; reading its coordinates 1:1 imports it five times
+ * too big, and every stroke width and font size with it. The factor is uniform
+ * — `min(width / viewBox width, height / viewBox height)` — because that is
+ * what the default `preserveAspectRatio` (`xMidYMid meet`) means, and a
+ * non-uniform read would need a shape model with independent axes.
+ *
+ * Exported as {@link SvgSketchFrame}: a recogniser reads a node's coordinates
+ * through {@link svgFrameOf} so it lands them exactly where this walk would
+ * have, and places what it leaves to the walk with the `place` option of
+ * {@link sketchSvgTree}.
+ */
+interface Frame {
+    ox: number;
+    oy: number;
+    s: number;
+}
+export type SvgSketchFrame = Frame;
+/**
+ * The second pass: a sanitised tree as sketch props, minus what a caller
+ * claimed.
+ *
+ * `skip` is the set of nodes a framework's recogniser already turned into its
+ * own artefacts; each one is left alone WITH its subtree, and everything else
+ * is read exactly as {@link parseSvgSketch} reads it. `place` composes a frame
+ * OUTSIDE the file's own viewport — `canvas = place.s · file + place.o` — so
+ * the remainder can land beside a board the recogniser laid out at another
+ * scale. Both default to nothing, which is {@link parseSvgSketch} itself.
+ *
+ * A framework that claims nodes owes its own heuristics statement for what it
+ * claims; this module's statement covers only what reaches this walk.
+ */
+export declare function sketchSvgTree(root: Element, notes: SvgSketchNotebook, options?: {
+    skip?: ReadonlySet<Element>;
+    place?: SvgSketchFrame;
+}): SerializedElementProps[];
+/**
+ * The frame a node's OWN attributes are read in — its `cx`, its `x1`, its
+ * `points` — composed exactly the way the walk composes it: the root's
+ * viewport, then every ancestor's translate and nested viewport, then the
+ * node's own `transform`. So a recogniser that reads a circle's centre through
+ * this lands it on the very point the sketch would have drawn it.
+ *
+ * The transforms the walk ignores are ignored here too, silently: the walk
+ * already says so once per kind when it meets them.
+ */
+export declare function svgFrameOf(element: Element): SvgSketchFrame;
+/**
+ * The document, sanitized, or an exception naming what is wrong with it.
+ *
+ * Well-formedness FIRST, because `DOMParser` reports a malformed document as a
+ * `parsererror` element rather than by throwing — a verdict in the shape of a
+ * document — and because DOMPurify's parser is the forgiving HTML one, which
+ * would quietly repair the very thing the caller needs to be told about. So:
+ * parse for the verdict, reading nothing out of the result but that; sanitize
+ * the SOURCE; and walk only what came back from the sanitizer.
+ *
+ * The sanitizer is not optional and it is not defensive programming. An `.svg`
+ * is an executable document — `<script>`, `<foreignObject>` with markup, event
+ * handler attributes — handed over by whoever sent the file. The same
+ * `USE_PROFILES: { svg: true }` guard is what the edgeless clipboard already
+ * puts in front of a pasted SVG.
+ *
+ * The first of the two passes {@link parseSvgSketch} is made of, exported so a
+ * framework that recognises part of a picture reads the SAME sanitised tree
+ * the sketch walks (ADR 0032 §2, §7) — never the source.
+ */
+export declare function sanitizeSvg(source: string, notes: SvgSketchNotebook): Element;
 /**
  * An SVG file as a canvas sketch — the shared VISUAL-tier importer.
  *
@@ -105,3 +212,4 @@ export declare const SVG_SKETCH_MIME = "image/svg+xml";
  * Malformed XML is the exception, because then the file was not read at all.
  */
 export declare function parseSvgSketch(source: string, context?: InterchangeImportContext): InterchangeImportResult;
+export {};

package/dist/_pkgs/affine-block-surface/extensions/svg-sketch.js

@@ -12,9 +12,11 @@ import { SVG_SKETCH_CURRENT_COLOR, SVG_SKETCH_CURVE, SVG_SKETCH_EMPTY, SVG_SKETC
  * a one-paragraph statement of its heuristics and its known failure modes" —
  * answered ONCE, here, because every framework that declares `…:svg:import`
  * wraps this one function and therefore owes the same statement. It is
- * referenced by `bpmn:svg:import` and by `wardley:svg:import`; a framework that
- * ever wants a narrower or wider guess writes its own parser and its own
- * paragraph beside it._
+ * referenced by `bpmn:svg:import`; a framework that ever wants a narrower or
+ * wider guess writes its own parser and its own paragraph beside it. Wardley
+ * did (ADR 0032): a framework may CLAIM nodes before the walk below
+ * ({@link sanitizeSvg}, {@link sketchSvgTree}), and then owes its own statement
+ * for what it claims — this one still covers everything it leaves here._
  *
  * **What it guesses.** An SVG carries a rendering, not a model, so this reader
  * recognises GEOMETRY and nothing else: `<rect>` becomes a rectangle,
@@ -165,8 +167,12 @@ function numbers(raw) {
  * Every note is a `warning`. The other four kinds would be lies here:
  * `carried` and `quarantined` describe a payload this tier does not write, and
  * `substituted-id` and `invented-layout` describe promises it does not make.
+ *
+ * Exported so a framework that claims part of a picture first (ADR 0032 §2)
+ * hands the SAME notebook to {@link sanitizeSvg} and {@link sketchSvgTree}: one
+ * file, one de-duplication, one list of remarks.
  */
-class Notebook {
+export class SvgSketchNotebook {
     constructor() {
         this.seen = new Set();
         this.notes = [];
@@ -774,6 +780,8 @@ function walk(parent, frame, inherited, sketch) {
 }
 /** One element and whatever it contains, placed in its parent's frame. */
 function visit(element, frame, inherited, sketch) {
+    if (sketch.skip.has(element))
+        return;
     const name = nameOf(element);
     if (NON_RENDERING.has(name))
         return;
@@ -851,6 +859,68 @@ function emit(element, name, frame, paint, sketch) {
             sketch.notes.once(`skipped:${name}`, `\`<${name}>\` is not recognised and was skipped.`, SVG_SKETCH_SKIPPED, { name }, name);
     }
 }
+/* ── The two passes, opened to a recogniser (ADR 0032 §2) ────────────── */
+/**
+ * The second pass: a sanitised tree as sketch props, minus what a caller
+ * claimed.
+ *
+ * `skip` is the set of nodes a framework's recogniser already turned into its
+ * own artefacts; each one is left alone WITH its subtree, and everything else
+ * is read exactly as {@link parseSvgSketch} reads it. `place` composes a frame
+ * OUTSIDE the file's own viewport — `canvas = place.s · file + place.o` — so
+ * the remainder can land beside a board the recogniser laid out at another
+ * scale. Both default to nothing, which is {@link parseSvgSketch} itself.
+ *
+ * A framework that claims nodes owes its own heuristics statement for what it
+ * claims; this module's statement covers only what reaches this walk.
+ */
+export function sketchSvgTree(root, notes, options = {}) {
+    const sketch = {
+        elements: [],
+        notes,
+        skip: options.skip ?? new Set(),
+    };
+    const place = options.place ?? IDENTITY;
+    const own = viewportFrame(root, IDENTITY);
+    // The root `<svg>` paints like any other element — a `fill` on it is what
+    // every shape under it inherits — and it establishes the outermost viewport.
+    walk(root, {
+        ox: own.ox * place.s + place.ox,
+        oy: own.oy * place.s + place.oy,
+        s: own.s * place.s,
+    }, paintOf(root, INITIAL_PAINT, notes), sketch);
+    return sketch.elements;
+}
+/**
+ * The frame a node's OWN attributes are read in — its `cx`, its `x1`, its
+ * `points` — composed exactly the way the walk composes it: the root's
+ * viewport, then every ancestor's translate and nested viewport, then the
+ * node's own `transform`. So a recogniser that reads a circle's centre through
+ * this lands it on the very point the sketch would have drawn it.
+ *
+ * The transforms the walk ignores are ignored here too, silently: the walk
+ * already says so once per kind when it meets them.
+ */
+export function svgFrameOf(element) {
+    const path = [];
+    for (let at = element; at; at = at.parentElement) {
+        path.unshift(at);
+    }
+    // The outermost `<svg>` on the path is the root the walk starts from: its
+    // viewport is the identity's, and its own `transform` is never read.
+    const rootIndex = path.findIndex(node => nameOf(node) === 'svg');
+    if (rootIndex < 0)
+        return IDENTITY;
+    const quiet = new SvgSketchNotebook();
+    let frame = viewportFrame(path[rootIndex], IDENTITY);
+    for (const node of path.slice(rootIndex + 1)) {
+        frame = translated(node, frame, quiet);
+        if (node !== element && nameOf(node) === 'svg') {
+            frame = viewportFrame(node, frame);
+        }
+    }
+    return frame;
+}
 /* ── The capability's function ────────────────────────────────────────── */
 /**
  * The document, sanitized, or an exception naming what is wrong with it.
@@ -867,8 +937,12 @@ function emit(element, name, frame, paint, sketch) {
  * handler attributes — handed over by whoever sent the file. The same
  * `USE_PROFILES: { svg: true }` guard is what the edgeless clipboard already
  * puts in front of a pasted SVG.
+ *
+ * The first of the two passes {@link parseSvgSketch} is made of, exported so a
+ * framework that recognises part of a picture reads the SAME sanitised tree
+ * the sketch walks (ADR 0032 §2, §7) — never the source.
  */
-function parseSvgRoot(source, notes) {
+export function sanitizeSvg(source, notes) {
     const doc = new DOMParser().parseFromString(source, 'image/svg+xml');
     const error = doc.querySelector('parsererror');
     if (error) {
@@ -952,25 +1026,22 @@ export function parseSvgSketch(source, context = {}) {
     // A sketch has no document-level name to take: what a board is CALLED is the
     // document's business, not any element's. Same answer the BPMN reader gives.
     void context;
-    const sketch = { elements: [], notes: new Notebook() };
-    const root = parseSvgRoot(source, sketch.notes);
-    // The root `<svg>` paints like any other element — a `fill` on it is what
-    // every shape under it inherits — and it establishes the outermost viewport.
-    walk(root, viewportFrame(root, IDENTITY), paintOf(root, INITIAL_PAINT, sketch.notes), sketch);
-    if (sketch.elements.length === 0) {
-        sketch.notes.once('empty', 'No shape or text was recognised in this SVG, so nothing was drawn.', SVG_SKETCH_EMPTY);
+    const notes = new SvgSketchNotebook();
+    const elements = sketchSvgTree(sanitizeSvg(source, notes), notes);
+    if (elements.length === 0) {
+        notes.once('empty', 'No shape or text was recognised in this SVG, so nothing was drawn.', SVG_SKETCH_EMPTY);
     }
     return {
-        elements: sketch.elements,
+        elements,
         report: {
-            mapped: sketch.elements.length,
+            mapped: elements.length,
             // Always zero, and it is the tier's whole contract rather than an
             // accident of this file: a visual import carries nothing and quarantines
             // nothing, because it writes no `interchange` payload to carry anything
             // IN (ADR 0012, P2). Pinned by an anti-decay test.
             carried: 0,
             quarantined: 0,
-            notes: sketch.notes.notes,
+            notes: notes.notes,
             // …and no `sourceVersion`. An SVG declares a version of the SVG spec, not
             // a version of a vocabulary this reader translates, so claiming one would
             // be a fact about the file dressed up as a fact about the import.