@formicoidea/labre-core 0.42.0 → 0.45.0

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

@@ -0,0 +1,137 @@
+import { type BlockStdScope, LifeCycleWatcher } from '../../../std/index.js';
+import { GfxGroupLikeElementModel, type GfxModel, DEFAULT_LAYER_ID, type SurfaceBlockModel } from '../../../std/gfx/index.js';
+import { type ReadonlySignal } from '@preact/signals-core';
+/** The default layer's reserved id (ADR 0031 §2), re-exported from std. */
+export { DEFAULT_LAYER_ID };
+/**
+ * One row of the selection pane, as the HEADLESS API hands it out (ADR 0031
+ * §12): ids and states only, never a wording. Whoever draws the row reads the
+ * label off the element at render time — its own text, its label sibling, its
+ * role's wording — so a rename on the canvas never has to invalidate this
+ * tree, and no element text ever crosses the seam in a payload a host might
+ * log.
+ */
+export interface SelectionPaneNode {
+    id: string;
+    /**
+     * `'layer'` is a user layer's row (ADR 0031 §2). The top-level rows are
+     * always the layers, top first, and every element row sits under its
+     * effective layer. A surface with no `layers` has one, the default layer
+     * ({@link DEFAULT_LAYER_ID}), shown although it has no record yet (ADR 0031
+     * amendments); its name is `userLayerName`'s, the first-layer seed.
+     */
+    kind: 'element' | 'block' | 'layer';
+    /** The element `type` (`shape`, `group`…) or the block flavour. */
+    type: string;
+    /** The element's role, when it carries one. Blocks carry none. */
+    role?: string;
+    /** The group-like ELEMENT (group, mindmap) this row is listed under. */
+    groupId?: string;
+    /**
+     * The effective layer (ADR 0031 §4): the outermost group's, a dangling id
+     * read as {@link DEFAULT_LAYER_ID}. A layer row carries its own id.
+     */
+    layerId: string;
+    /** Locked by itself — what the row's lock toggle shows and flips. */
+    locked: boolean;
+    /**
+     * Hidden for this viewer only (`CanvasLocalVisibility`): still listed, still
+     * selectable from the pane, just not painted or picked on the canvas.
+     */
+    hiddenLocal: boolean;
+    /**
+     * Hidden for everyone (the stored `hiddenForEveryone`, ADR 0031 §7): listed
+     * and selectable like a local hide, but no viewer paints or picks it.
+     */
+    hiddenForEveryone: boolean;
+    /** Present on a group, a mindmap or a layer: its members, top first. */
+    children?: SelectionPaneNode[];
+}
+/** The user layers a tree is built against (ADR 0031 §4). */
+export interface SelectionPaneLayers {
+    /** Every layer id, TOP first. */
+    readonly order: readonly string[];
+    /** Each id's rank key, as `compare` reads it. */
+    readonly ranks: ReadonlyMap<string, string>;
+    effectiveLayerOf(model: GfxModel): string;
+    /** The layers this viewer hid (stage 7). */
+    readonly hiddenLocally?: ReadonlySet<string>;
+    /** The layers whose record says `hidden: true` (stage 7). */
+    readonly hiddenForEveryone?: ReadonlySet<string>;
+}
+/**
+ * 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 declare function paneContainerOf(model: GfxModel): GfxGroupLikeElementModel | 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 declare function buildSelectionPaneTree(models: readonly GfxModel[], hiddenLocally?: ReadonlySet<string>, layers?: SelectionPaneLayers): SelectionPaneNode[];
+/**
+ * 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 declare function paneLayersOf(surface: SurfaceBlockModel, hiddenLocally?: ReadonlySet<string>): SelectionPaneLayers;
+/**
+ * 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 declare class SelectionPaneModel extends LifeCycleWatcher {
+    static key: string;
+    private readonly _revision$;
+    private _disposeSurfaceEffect;
+    private _subscriptions;
+    /** Whether the library's own panel is on screen. Written by that panel. */
+    readonly open$: import("@preact/signals-core").Signal<boolean>;
+    readonly tree$: ReadonlySignal<SelectionPaneNode[]>;
+    /** Force a rebuild; for a change no subscribed event reports. */
+    invalidate(): void;
+    mounted(): void;
+    private _surfaceSubscriptions;
+    private _watchSurface;
+    unmounted(): void;
+}
+/**
+ * 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 declare function selectionPaneTree(std: BlockStdScope): ReadonlySignal<SelectionPaneNode[]>;

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-translations.d.ts

@@ -39,6 +39,9 @@ export declare const SVG_SKETCH_SKIPPED: ChromeWording;
 export declare const SVG_SKETCH_REMOVED: ChromeWording;
 export declare const SVG_SKETCH_REMOVED_ATTRIBUTE: ChromeWording;
 export declare const SVG_SKETCH_EMPTY: ChromeWording;
+export declare const SVG_SKETCH_ERROR_MALFORMED_XML: ChromeWording;
+export declare const SVG_SKETCH_ERROR_NOT_SVG: ChromeWording;
+export declare const SVG_SKETCH_ERROR_SANITIZED_AWAY: ChromeWording;
 /**
  * Every wording declared above, in declaration order — joined into
  * `PACKAGE_WORDINGS` (`packages/affine/all/src/translations.ts`) alongside

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

@@ -92,6 +92,26 @@ export const SVG_SKETCH_EMPTY = [
     'com.labre.interchange.svg.empty',
     'No shape or text was recognised in this SVG, so nothing was drawn.',
 ];
+/* ── The reader's own refusals (#390) ─────────────────────────────────────
+ *
+ * Thrown via `InterchangeImportError` and rendered by `runInterchangeImport`
+ * in the failure notification — the same shape as `BPMN_IMPORT_ERRORS`
+ * (`gfx/bpmn/src/import.ts`), and keyed for the same reason: these three
+ * sentences were written for a user, not for a console, and were reaching a
+ * French host in English because a bare `new Error(…)` carries no key.
+ */
+export const SVG_SKETCH_ERROR_MALFORMED_XML = [
+    'com.labre.interchange.svg.error.malformed-xml',
+    'This file is not well-formed XML, so no drawing can be read out of it: {{detail}}',
+];
+export const SVG_SKETCH_ERROR_NOT_SVG = [
+    'com.labre.interchange.svg.error.not-svg',
+    'An SVG opens on <svg>; this one opens on <{{tag}}>.',
+];
+export const SVG_SKETCH_ERROR_SANITIZED_AWAY = [
+    'com.labre.interchange.svg.error.sanitized-away',
+    'Nothing survived sanitizing this SVG, so there is no drawing to read.',
+];
 /**
  * Every wording declared above, in declaration order — joined into
  * `PACKAGE_WORDINGS` (`packages/affine/all/src/translations.ts`) alongside
@@ -117,4 +137,7 @@ export const SVG_SKETCH_WORDINGS = [
     SVG_SKETCH_REMOVED,
     SVG_SKETCH_REMOVED_ATTRIBUTE,
     SVG_SKETCH_EMPTY,
+    SVG_SKETCH_ERROR_MALFORMED_XML,
+    SVG_SKETCH_ERROR_NOT_SVG,
+    SVG_SKETCH_ERROR_SANITIZED_AWAY,
 ];

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

@@ -1,4 +1,5 @@
-import type { InterchangeImportContext, 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, InterchangeImportResult } from './interc
  * 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, InterchangeImportResult } from './interc
 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 {};