@mosaicoo/svg-engine 0.1.0

package/types/mosaicoo-svg-engine-render.d.ts

@@ -0,0 +1,628 @@
+import * as _angular_core from '@angular/core';
+import { Type } from '@angular/core';
+import { SvgNode, BoundingBox, SvgDocument, EllipseNode, ImageNode, LineNode, SvgStyle, TextRun, PathNode, PolygonNode, PolylineNode, RectNode, SymbolUseNode, TextNode, Transform, Point } from '@mosaicoo/svg-engine/core';
+import * as _mosaicoo_svg_engine_render from '@mosaicoo/svg-engine/render';
+
+/**
+ * Top-level SVG renderer. Read-only — does **not** handle selection,
+ * editing or interaction (those live in `svg-engine/edit`). Suitable as
+ * an embedded viewer in third-party applications (D-017 headless boundary:
+ * zero deps on `@angular/material`).
+ *
+ * **Inputs**:
+ * - `tree` (required): the {@link SvgNode} to render. Typically a
+ *   {@link SvgDocument} `root`, but any node is valid (single-node
+ *   preview, etc.).
+ * - `viewBox` (optional): **seed** for {@link ViewportService.contentBox}.
+ *   The value is mirrored into the viewport on every change. The actual
+ *   viewBox attribute on the `<svg>` element is **always** derived from
+ *   `viewport.viewBox()`, so pan/zoom calls on `ViewportService` always
+ *   take effect regardless of whether this input is provided.
+ * - `width` / `height` (optional): CSS pixel dimensions of the rendered
+ *   `<svg>` element. When both are omitted the SVG is sized by its CSS
+ *   container (the component sets `:host` and `svg` to `100%/100%` by
+ *   default).
+ * - `ariaLabel` (optional): accessibility label for the `<svg role="img">`.
+ *
+ * **Pan/zoom semantics**: at the default viewport state (`zoom=1`,
+ * `pan=0`), `viewport.viewBox()` equals `viewport.contentBox()`, so the
+ * rendered SVG matches the seed exactly. After a `viewport.zoomIn()`
+ * (etc.) call, the rendered viewBox reflects the new state — the
+ * displayed content scales/pans accordingly.
+ */
+declare class SvgeRenderer {
+    private readonly viewport;
+    private readonly svgRoot;
+    /**
+     * **AUDIT-FIX P9** — typed accessor for the rendered `<svg>` element
+     * scoped to **this** renderer instance.
+     *
+     * Returns `null` when the view hasn't been attached yet (early calls
+     * during ngOnInit, SSR, jsdom without layout). Consumers should
+     * defensively check for null.
+     *
+     * **Why expose it**: consumers that need to perform DOM measurements
+     * on the rendered shapes (bbox, hit-testing, pointer→doc conversion)
+     * previously had to call `document.querySelector('svge-renderer svg')`.
+     * That global selector breaks the moment a host mounts more than one
+     * `<svge-renderer>` on the same page — the first match wins, leaking
+     * measurements between editor instances. Using
+     * `@ViewChild(SvgeRenderer)` + `svgElement()` keeps the lookup scoped
+     * to the component's own tree.
+     *
+     * @example
+     * ```ts
+     * @Component({ ... })
+     * export class MyHost {
+     *   private readonly renderer = viewChild(SvgeRenderer);
+     *
+     *   measureNode(id: NodeId): BoundingBox | null {
+     *     const svg = this.renderer()?.svgElement();
+     *     return svg === null ? null : getRenderedNodeBBox(svg, id);
+     *   }
+     * }
+     * ```
+     */
+    svgElement(): SVGSVGElement | null;
+    readonly tree: _angular_core.InputSignal<SvgNode>;
+    readonly viewBox: _angular_core.InputSignal<BoundingBox | null>;
+    readonly width: _angular_core.InputSignal<number | null>;
+    readonly height: _angular_core.InputSignal<number | null>;
+    readonly ariaLabel: _angular_core.InputSignal<string | null>;
+    /**
+     * Optional reusable-definitions fragment ({@link SvgDocument.defs}).
+     * When non-empty, the renderer injects the fragment as the first
+     * child of `<svg>` via `insertAdjacentHTML('afterbegin', ...)` so
+     * `url(#id)` references inside the tree resolve at paint time.
+     *
+     * **Why insertAdjacentHTML and not the Angular template**: the
+     * fragment can include arbitrary SVG markup (`<linearGradient>`,
+     * `<clipPath>`, …) with namespaces and id attributes. Embedding via
+     * `[innerHTML]` would run through Angular's sanitizer which can
+     * mangle SVG-specific constructs. The fragment was already sanitized
+     * at import time (script, event handlers, javascript: hrefs all
+     * removed); we trust it as opaque markup here.
+     */
+    readonly defs: _angular_core.InputSignal<string | null>;
+    /**
+     * Rendered viewBox attribute. **Always** derived from
+     * `viewport.viewBox()` — which itself is `contentBox` transformed by
+     * current zoom and pan. The optional `viewBox` input feeds the
+     * viewport's `contentBox` (via the constructor effect), making it the
+     * starting point that pan/zoom act upon.
+     *
+     * This single-source-of-truth approach guarantees that any caller of
+     * `ViewportService.zoomIn()`/`pan()`/etc. produces a visible change
+     * regardless of whether `viewBox` was supplied as an input.
+     */
+    protected readonly viewBoxAttr: _angular_core.Signal<string>;
+    /**
+     * Sentinel data attribute applied to the injected `<defs>` block so
+     * re-runs can find and replace it idempotently instead of stacking
+     * duplicates.
+     */
+    private static readonly DEFS_MARKER_ATTR;
+    constructor();
+    /**
+     * Idempotently materialize the current `defs()` value as the first
+     * child of `<svg>`. Sequence of operations:
+     *
+     * 1. Locate (and remove) any previous `<defs data-svge-injected-defs="1">`
+     *    we wrote on an earlier effect tick.
+     * 2. If the new fragment is non-empty, build a fresh `<defs>` element
+     *    and set its inner XML via `insertAdjacentHTML`. The marker attr
+     *    distinguishes our injection from consumer-provided defs.
+     *
+     * Safe in jsdom (no-ops when the viewChild ref hasn't resolved yet),
+     * SSR (typeof document gate via insertAdjacentHTML availability),
+     * and worker contexts (effect simply never runs DOM ops without the
+     * viewChild element).
+     */
+    private syncDefs;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SvgeRenderer, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SvgeRenderer, "svge-renderer", never, { "tree": { "alias": "tree"; "required": true; "isSignal": true; }; "viewBox": { "alias": "viewBox"; "required": false; "isSignal": true; }; "width": { "alias": "width"; "required": false; "isSignal": true; }; "height": { "alias": "height"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "defs": { "alias": "defs"; "required": false; "isSignal": true; }; }, {}, never, ["[svgeBehind]", "*"], true, never>;
+}
+/**
+ * Convenience helper for consumers that hold a {@link SvgDocument}: returns
+ * its `root` and `viewBox` ready to bind to {@link SvgeRenderer}.
+ *
+ * ```html
+ * <svge-renderer [tree]="doc().root" [viewBox]="doc().viewBox" />
+ * ```
+ */
+declare function projectDocumentToRenderer(doc: SvgDocument): {
+    readonly tree: SvgNode;
+    readonly viewBox: BoundingBox;
+};
+
+/** Apply to `<svg:ellipse>` to bind attributes from an {@link EllipseNode}. */
+declare class SvgeEllipseDirective {
+    readonly node: _angular_core.InputSignal<EllipseNode>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SvgeEllipseDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<SvgeEllipseDirective, "[svgeEllipse]", never, { "node": { "alias": "svgeEllipse"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/** Apply to `<svg:image>` to bind attributes from an {@link ImageNode}. */
+declare class SvgeImageDirective {
+    readonly node: _angular_core.InputSignal<ImageNode>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SvgeImageDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<SvgeImageDirective, "[svgeImage]", never, { "node": { "alias": "svgeImage"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/** Apply to `<svg:line>` to bind attributes from a {@link LineNode}. */
+declare class SvgeLineDirective {
+    readonly node: _angular_core.InputSignal<LineNode>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SvgeLineDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<SvgeLineDirective, "[svgeLine]", never, { "node": { "alias": "svgeLine"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Dispatch a single {@link SvgNode} to the correct attribute-binding
+ * directive on the appropriate SVG element.
+ *
+ * **Why an attribute selector** (`g[svgeNode]`):
+ *
+ * The dispatcher's host is itself a `<svg:g>` (the wrapper that carries
+ * `data-node-id` and the node's `transform`). Using a custom-element
+ * selector like `<svge-node>` would inject a non-SVG element into the
+ * SVG render tree, and SVG painters do not paint through unknown
+ * non-SVG elements — geometry inside would silently fail to render.
+ * Attribute selector + `<svg:g>` host keeps the entire DOM in the SVG
+ * namespace.
+ *
+ * Built-in dispatch:
+ * - 8 leaf types are bound by per-type directives (`[svgeRect]`,
+ *   `[svgeEllipse]`, …) on their native SVG element.
+ * - `group` is handled inline (recursive case) — each child becomes a
+ *   nested `<svg:g svgeNode>`.
+ * - Unknown types fall through to {@link NodeRendererRegistry} (D-020
+ *   plugin extensibility).
+ *
+ * Usage (top-level):
+ * ```html
+ * <svg:g svgeNode [node]="root" />
+ * ```
+ */
+declare class SvgeNodeRenderer {
+    private readonly registry;
+    readonly node: _angular_core.InputSignal<SvgNode>;
+    /** Host-bound transform attr; runs once per input change (OnPush). */
+    protected readonly transformAttr: _angular_core.Signal<string | null>;
+    /**
+     * Custom-component lookup stays computed because the
+     * {@link NodeRendererRegistry} signal can change at runtime (plugin
+     * install/uninstall) and we want the @switch default branch to react.
+     */
+    protected readonly customComponent: _angular_core.Signal<_mosaicoo_svg_engine_render.SvgNodeRendererComponent | null>;
+    /**
+     * **GROUP-STYLE-FIX (A)** — the node's style ONLY when it's a group,
+     * else `null`. Drives the group-wrapper paint/filter/opacity host
+     * bindings (see the `host` block). Leaf nodes return `null` here so
+     * those bindings emit no attribute on the leaf wrapper (the per-type
+     * directive paints the leaf's style on its inner element instead).
+     */
+    protected readonly groupStyle: _angular_core.Signal<SvgStyle | null>;
+    /**
+     * `stroke-dasharray` for the group wrapper, formatted as the SVG
+     * space-separated string. `null` (no attribute) when this isn't a
+     * group or the group has no dash pattern. Mirrors the exporter's
+     * `strokeDasharray.map(fmt).join(' ')`.
+     */
+    protected groupDashArray(): string | null;
+    /**
+     * Text content access for the `@case ('text')` branch. Returns `''`
+     * for non-text nodes (never reached at runtime; appeases the template
+     * type checker without scattering `$any` for the string interpolation).
+     */
+    protected textContent(): string;
+    /**
+     * **D-100** — `true` when the text node has a non-empty `runs` array.
+     * Gates the rich-text (inline styled tspans) render branch. Sits below
+     * the `textPathRef` branch in precedence (text on a path with per-run
+     * styling is out of scope) and above the multi-line `\n` path.
+     */
+    protected textHasRuns(): boolean;
+    /** Runs for the rich-text branch; `[]` when the node has none. */
+    protected textRuns(): readonly TextRun[];
+    /**
+     * `true` when the text node's content contains newline characters —
+     * the renderer switches to the multi-line tspan path. Single-line
+     * text keeps the simpler plain interpolation.
+     */
+    protected textIsMultiLine(): boolean;
+    /**
+     * Split text content into lines for the multi-line tspan path.
+     * Returns `[]` for non-text nodes (defensive — branch is gated by
+     * `textIsMultiLine`).
+     */
+    protected textLines(): readonly string[];
+    /**
+     * X position of the text node — every tspan inherits this value
+     * via its own `x` attribute (the default behaviour of tspan without
+     * explicit `x` is to continue from the previous tspan's end, which
+     * is NOT what we want for multi-line — we want each line to start
+     * at the same horizontal anchor).
+     */
+    protected textX(): number;
+    /**
+     * **D-069** — `dy` value (in `em`s) for non-first tspans in the
+     * multi-line text path. Reads `node().lineHeight` and falls back to
+     * `1.2` (the pre-D-069 hardcoded default) when undefined — preserves
+     * backward compatibility for existing docs/specs.
+     *
+     * Returned as a CSS-style string with `em` unit so it composes with
+     * the `font-size` already on the parent `<text>` (the tspan inherits).
+     * Choosing `em` over `px` keeps line spacing proportional when the
+     * user later changes the font size — same behavior as CSS
+     * `line-height: <number>` (unitless multiplier).
+     */
+    protected textLineDy(): string;
+    protected textPathHref(): string | null;
+    protected textPathStartOffset(): string | null;
+    /**
+     * `<textPath>` does NOT honor `\n` — embedded newlines render as
+     * a single literal space (per SVG spec: whitespace collapse). We
+     * pre-collapse so the user sees what they get instead of a stretched
+     * "  word " gap from the raw newline character.
+     */
+    protected textPathFlattened(): string;
+    /**
+     * Children iteration for the `@case ('group')` branch. Same template-
+     * type-checker rationale as {@link textContent}. Empty array for
+     * non-group nodes (never reached).
+     */
+    protected groupChildren(): readonly SvgNode[];
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SvgeNodeRenderer, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SvgeNodeRenderer, "g[svgeNode]", never, { "node": { "alias": "node"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Apply to `<svg:path>` to bind attributes from a {@link PathNode}.
+ *
+ * **D-055 (Live Corners)**: when `node.cornerRadius > 0`, the
+ * rendered `d` is the result of {@link roundPathCorners}(authored d,
+ * radius) — sharp interior vertices get smoothly rounded with that
+ * radius. Authored `d` is left untouched (preserved on the model
+ * for later edits / radius slider changes). When `cornerRadius` is
+ * `0` or `undefined`, the authored `d` is emitted verbatim — same
+ * behavior as before D-055.
+ *
+ * **D-068 follow-up — `id` host binding**: paths are the only shape
+ * type a `<textPath href="#…">` (D-053) can reference, so the path
+ * needs a DOM `id` matching `node.id`. Without this, `textPathRef` set
+ * by the Inspector resolves to no element and the text silently
+ * disappears (bbox in place, zero characters painted). The wrapper
+ * `<g>` already carries `data-node-id` for selection lookup, but
+ * `data-*` doesn't satisfy `#id` href lookups — only the standard
+ * `id` attribute does. Cost is one attribute per path, negligible.
+ * No collision risk because `NodeId`s are UUIDs (globally unique
+ * across documents and editors). If a future use-case wants to opt
+ * out of paint-target ids, gate this behind a flag — keeping it
+ * unconditional makes textPath, future `<use href>` fallbacks, and
+ * DOM inspector debugging all easier.
+ */
+declare class SvgePathDirective {
+    readonly node: _angular_core.InputSignal<PathNode>;
+    protected readonly effectiveD: _angular_core.Signal<string>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SvgePathDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<SvgePathDirective, "[svgePath]", never, { "node": { "alias": "svgePath"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/** Apply to `<svg:polygon>` to bind attributes from a {@link PolygonNode}. */
+declare class SvgePolygonDirective {
+    readonly node: _angular_core.InputSignal<PolygonNode>;
+    protected readonly pointsAttr: _angular_core.Signal<string>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SvgePolygonDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<SvgePolygonDirective, "[svgePolygon]", never, { "node": { "alias": "svgePolygon"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/** Apply to `<svg:polyline>` to bind attributes from a {@link PolylineNode}. */
+declare class SvgePolylineDirective {
+    readonly node: _angular_core.InputSignal<PolylineNode>;
+    protected readonly pointsAttr: _angular_core.Signal<string>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SvgePolylineDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<SvgePolylineDirective, "[svgePolyline]", never, { "node": { "alias": "svgePolyline"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Apply to a `<svg:rect>` element to bind its attributes from a
+ * {@link RectNode}. Use the directive as both selector and value binding:
+ *
+ * ```html
+ * <svg:rect [svgeRect]="rectNode" />
+ * ```
+ *
+ * Why a directive (not a component): components inject a host element
+ * created by `document.createElement(selector)` which lives in the HTML
+ * namespace. Inside an `<svg>`, an HTML wrapper element breaks the SVG
+ * render tree — the SVG painter does not traverse non-SVG elements. A
+ * directive applied to an actual `<svg:rect>` element keeps the host in
+ * the SVG namespace so geometry attributes paint correctly.
+ */
+declare class SvgeRectDirective {
+    readonly node: _angular_core.InputSignal<RectNode>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SvgeRectDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<SvgeRectDirective, "[svgeRect]", never, { "node": { "alias": "svgeRect"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Apply to `<svg:use>` to bind attributes from a {@link SymbolUseNode}
+ * (D-059). The `<symbol id="{symbolId}">` definition that this `<use>`
+ * references is contributed to `<defs>` by `ActiveSymbolsService`
+ * (in `svg-engine/edit`).
+ *
+ * **Style inheritance**: `fill`/`stroke`/`opacity` set on the `<use>`
+ * cascade into the shadow tree (the master's contents) for any inner
+ * element that didn't specify those values explicitly. Editing the
+ * master overrides everywhere; editing the instance customizes a
+ * single occurrence.
+ *
+ * **Filter on `<use>`** applies to the rendered output, AFTER the
+ * symbol expansion — useful for "glow that one instance" without
+ * touching the master.
+ *
+ * **width/height optional**: when omitted, the symbol renders at its
+ * master's natural size (from the `<symbol>`'s `viewBox`).
+ */
+declare class SvgeSymbolUseDirective {
+    readonly node: _angular_core.InputSignal<SymbolUseNode>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SvgeSymbolUseDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<SvgeSymbolUseDirective, "[svgeSymbolUse]", never, { "node": { "alias": "svgeSymbolUse"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Apply to `<svg:text>` to bind attributes from a {@link TextNode}.
+ *
+ * The `<svg:text>` element's text **content** is set in the dispatcher's
+ * template, because directives cannot inject child nodes. The dispatcher
+ * splits `node.content` on `\n` and emits one `<tspan dy>` per line, so
+ * multi-line text is rendered by simply embedding line breaks in the
+ * `content` field. Explicit `<tspan>` runs with per-run styling are
+ * still not modelled at the data layer — that would require an extra
+ * `runs` field on `TextNode`.
+ */
+declare class SvgeTextDirective {
+    readonly node: _angular_core.InputSignal<TextNode>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SvgeTextDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<SvgeTextDirective, "[svgeText]", never, { "node": { "alias": "svgeText"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Viewport state for the SVG renderer: zoom level and pan offset over a
+ * base "content" {@link BoundingBox}. Exposed as Angular signals so the
+ * renderer can recompute the displayed `viewBox` reactively.
+ *
+ * Coordinate model:
+ * - `contentBox` is the original document space ("what to show at zoom 1").
+ * - `zoom` scales the visible window: `>1` zooms in (smaller window),
+ *   `<1` zooms out (larger window).
+ * - `panX`/`panY` translate the visible window in **content units**.
+ *
+ * The resulting visible {@link BoundingBox} is exposed via {@link viewBox},
+ * suitable for binding to `<svg [attr.viewBox]>`.
+ */
+declare class ViewportService {
+    private readonly _contentBox;
+    private readonly _zoom;
+    private readonly _panX;
+    private readonly _panY;
+    private readonly _minZoom;
+    private readonly _maxZoom;
+    /**
+     * **D-106** — CSS-pixel size of the rendered canvas viewport (the `<svg>`
+     * element's client box). `{0,0}` until a consumer reports it (the
+     * `[svgeCanvasGestures]` directive does, via a ResizeObserver). Needed to
+     * relate the internal `zoom` (which is relative to `contentBox`) to a
+     * **physical** on-screen scale — see {@link displayScale}.
+     */
+    private readonly _viewportSize;
+    readonly contentBox: _angular_core.Signal<BoundingBox>;
+    readonly zoom: _angular_core.Signal<number>;
+    readonly panX: _angular_core.Signal<number>;
+    readonly panY: _angular_core.Signal<number>;
+    readonly minZoom: _angular_core.Signal<number>;
+    readonly maxZoom: _angular_core.Signal<number>;
+    readonly viewportSize: _angular_core.Signal<{
+        readonly width: number;
+        readonly height: number;
+    }>;
+    /**
+     * Visible window in content coordinates, derived from `contentBox`,
+     * `zoom`, `panX`, `panY`. Bind directly to `<svg [attr.viewBox]>`.
+     */
+    readonly viewBox: _angular_core.Signal<BoundingBox>;
+    /**
+     * **D-106** — physical scale (CSS px per document unit) that the WHOLE
+     * `contentBox` occupies at `zoom === 1` — i.e. the "fit to window" factor.
+     * `preserveAspectRatio="xMidYMid meet"` applies a uniform scale, so it's the
+     * limiting (min) of the two axis ratios. `null` when the viewport size or
+     * content box is unknown/degenerate (e.g. headless tests with no layout).
+     */
+    readonly fitScale: _angular_core.Signal<number | null>;
+    /**
+     * **D-106** — true on-screen scale: how many CSS pixels one document unit
+     * occupies right now. `displayScale === 1` means real 1:1 ("100% / Actual
+     * Size", the market convention). Because the SVG renders the visible
+     * `viewBox` (`contentBox.size / zoom`) stretched to fill the viewport, the
+     * physical scale is `zoom × fitScale`.
+     *
+     * **Fallback**: when {@link fitScale} is unknown (no measured viewport, e.g.
+     * headless rendering) this returns the raw `zoom` — preserving the old
+     * "zoom = percent" meaning so non-DOM consumers/tests keep working.
+     */
+    readonly displayScale: _angular_core.Signal<number>;
+    /** Replace the base content box (e.g., when loading a new document). */
+    setContentBox(box: BoundingBox): void;
+    /**
+     * **D-106** — report the rendered canvas size (CSS px). Drives
+     * {@link fitScale}/{@link displayScale}. Ignores non-finite/negative input.
+     */
+    setViewportSize(width: number, height: number): void;
+    /**
+     * **D-106** — set the internal `zoom` so the on-screen {@link displayScale}
+     * equals `scale` (e.g. `1` for true 1:1). When the viewport hasn't been
+     * measured ({@link fitScale} null), falls back to setting `zoom` directly so
+     * the call still does something sensible.
+     */
+    setDisplayScale(scale: number): void;
+    /** **D-106** — "Actual Size" (100%): pin the on-screen scale to true 1:1. */
+    actualSize(): void;
+    /**
+     * **D-107** — initial framing for a FRESH document: show it at true 100%
+     * (1:1) when the whole content box fits the viewport, otherwise fit it to the
+     * window. Pan resets to origin (centered). This is the "Fit on Screen"
+     * convention (Photoshop): documents that fit open at 100%; larger ones fit so
+     * the user isn't dropped into a corner. Falls back to fit (zoom 1) when the
+     * viewport hasn't been measured ({@link fitScale} null).
+     *
+     * (Opening a saved `.svge`/`.svgez` does NOT use this — it restores the
+     * viewport persisted in the file.)
+     */
+    frameNewDocument(): void;
+    /** Replace zoom directly (clamped to `[minZoom, maxZoom]`). */
+    setZoom(zoom: number): void;
+    /** Multiply current zoom by `factor` (clamped). */
+    multiplyZoom(factor: number): void;
+    /** Zoom in by the configured step factor. */
+    zoomIn(step?: number): void;
+    /** Zoom out by the configured step factor. */
+    zoomOut(step?: number): void;
+    /** Replace pan offset directly (in content units). */
+    setPan(x: number, y: number): void;
+    /** Translate the current pan by `(dx, dy)` in content units. */
+    pan(dx: number, dy: number): void;
+    /**
+     * Zoom by `factor` while keeping `anchor` (in document coordinates)
+     * stationary on screen. Used by wheel-zoom (anchor = cursor) and
+     * "zoom to selection" (anchor = selection centre).
+     *
+     * **Math**: pre-zoom relative position of the anchor inside the
+     * visible viewBox must equal post-zoom relative position. Solving
+     * for the new pan and applying both `zoom` and `pan` atomically
+     * makes the visible viewBox preserve the anchor.
+     *
+     * **No-op-safe**: if `factor` would push zoom past min/max limits,
+     * the clamped zoom may equal the current zoom — pan adjusts to a
+     * zero delta, anchor stays put (no observable change).
+     */
+    zoomAt(factor: number, anchor: {
+        readonly x: number;
+        readonly y: number;
+    }): void;
+    /** Reset zoom to 1 and pan to origin (centered on content). */
+    reset(): void;
+    /**
+     * Reset to fit the content box exactly. Identical to {@link reset}
+     * today; reserved for future "fit to selection" / "fit to bounds"
+     * variants.
+     */
+    fit(): void;
+    /**
+     * **D-118** — frame `target` (in document/content coordinates) in the visible
+     * viewBox: zoom so the box fits with `paddingFraction` margin on each side,
+     * and pan so it's centered. Powers `View ▸ Zoom ▸ Fit Selection`.
+     *
+     * The visible viewBox always keeps the content aspect ratio, so the box is
+     * fit "meet"-style — the limiting dimension touches the padded edge, the other
+     * has extra room. Zoom is clamped to `[minZoom, maxZoom]`. A degenerate
+     * (zero-area) target only re-centers, preserving the current zoom.
+     */
+    fitBox(target: BoundingBox, paddingFraction?: number): void;
+    /** Configure clamping bounds for zoom. Throws on invalid input. */
+    setZoomLimits(min: number, max: number): void;
+    private clampZoom;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ViewportService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<ViewportService>;
+}
+
+/**
+ * Renderer component class. The dispatcher (`<svge-node>`) mounts these
+ * via `*ngComponentOutlet` and binds `inputs: { node: <SvgNode> }`. The
+ * concrete shape of the component is not enforced statically (Angular's
+ * `input.required<T>()` returns an `InputSignal<T>`, which does not match
+ * a plain `T` field) — the runtime contract is:
+ *
+ *  - The component declares `node` as an Angular `input()` (preferred)
+ *    or a plain settable property accepting an `SvgNode`.
+ *  - The component is `standalone: true`.
+ */
+type SvgNodeRendererComponent = Type<unknown>;
+/**
+ * Registry of **custom** renderer components, keyed by `SvgNode['type']`.
+ *
+ * Built-in node types (`rect`, `ellipse`, `line`, `polygon`, `polyline`,
+ * `path`, `text`, `image`, `group`) are dispatched by the dispatcher's own
+ * `@switch` and do **not** go through this registry. The registry is the
+ * extension point for plugins (D-020) that introduce new `type`
+ * discriminators (e.g., `'star'`, `'chart-bar'`).
+ *
+ * Plugin install code:
+ * ```ts
+ * inject(NodeRendererRegistry).register('star', SvgeStarRenderer);
+ * ```
+ *
+ * The dispatcher resolves the registry's component for unknown types,
+ * mounts it via `*ngComponentOutlet` and binds `[node]` automatically.
+ */
+declare class NodeRendererRegistry {
+    private readonly entries;
+    /**
+     * Register a renderer component for a custom node type. Throws when the
+     * `type` is already registered (use {@link unregister} first to override).
+     */
+    register(type: string, component: SvgNodeRendererComponent): void;
+    /** Remove a previously registered renderer. No-op when absent. */
+    unregister(type: string): void;
+    /** Resolve the renderer for the given type, or `null` if unregistered. */
+    resolve(type: string): SvgNodeRendererComponent | null;
+    /** All currently registered type discriminators (for inspection/tooling). */
+    registeredTypes(): readonly string[];
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NodeRendererRegistry, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<NodeRendererRegistry>;
+}
+
+/**
+ * Serialize a {@link Transform} for the SVG `transform` attribute, e.g.
+ * `matrix(1 0 0 1 10 20)`. Returns `null` for the identity transform so
+ * callers can bind directly with `[attr.transform]` and omit the attribute
+ * when it would be a no-op.
+ */
+declare function renderTransformAttr(transform: Transform): string | null;
+
+/**
+ * Project a client (screen) pixel coordinate into the document's
+ * user-space coordinate system by inverting the SVG element's live
+ * `getScreenCTM()`.
+ *
+ * **Why a shared util**: this is the single most duplicated helper
+ * across the codebase. Until this util, the same 10-line block lived
+ * in 5 different files (`custom-editor` (ex-`playground-home`), `selection-overlay`,
+ * `canvas-gestures.directive`, `guides-overlay`, `rulers`) — every new
+ * pointer-driven component had to re-implement the CTM dance with the
+ * same defensive guards (jsdom missing `getScreenCTM`/`createSVGPoint`,
+ * SSR-detached SVG returning a `null` CTM, etc.). Centralizing prevents
+ * subtle drift (e.g., one site forgetting the `createSVGPoint` guard
+ * and crashing under jsdom).
+ *
+ * **What it handles**:
+ * - `svg === null` → returns `null` (caller didn't have an SVG ref yet)
+ * - `getScreenCTM` not implemented → returns `null` (jsdom / SSR)
+ * - `getScreenCTM` returns `null` → returns `null` (detached SVG)
+ * - `createSVGPoint` not available → returns `null` (older SVG impls)
+ *
+ * **What it does NOT do**:
+ * - Locate the `<svg>` element for you. Callers supply it via
+ *   `ElementRef.ownerSVGElement`, `document.querySelector`, or a saved
+ *   `viewChild` ref. Each caller knows the right way to reach its own
+ *   SVG; baking a strategy here would couple this util to component DI.
+ *
+ * @param svg The `<svg>` element whose CTM defines the projection.
+ *   Pass `null` to short-circuit (returns `null`).
+ * @param clientX `clientX` from a `MouseEvent` / `PointerEvent`.
+ * @param clientY `clientY` from a `MouseEvent` / `PointerEvent`.
+ * @returns Doc-space `{ x, y }` or `null` when projection is impossible.
+ */
+declare function screenToDoc(svg: SVGSVGElement | null, clientX: number, clientY: number): Point | null;
+
+export { NodeRendererRegistry, SvgeEllipseDirective, SvgeImageDirective, SvgeLineDirective, SvgeNodeRenderer, SvgePathDirective, SvgePolygonDirective, SvgePolylineDirective, SvgeRectDirective, SvgeRenderer, SvgeSymbolUseDirective, SvgeTextDirective, ViewportService, projectDocumentToRenderer, renderTransformAttr, screenToDoc };
+export type { SvgNodeRendererComponent };