@mosaicoo/svg-engine 0.1.0

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

@@ -0,0 +1,476 @@
+import { SvgDocument, Disposable, SvgNode } from '@mosaicoo/svg-engine/core';
+import * as i0 from '@angular/core';
+
+/**
+ * Outcome of an import operation. Either a parsed document with
+ * (optional) non-fatal warnings, OR a hard failure with reason.
+ *
+ * Soft failures (e.g., "skipped a `<script>` for safety") go in
+ * `warnings`; they don't abort the import. Hard failures (malformed
+ * XML, unsupported root element) produce `{ ok: false, error }`.
+ */
+type ImportResult = {
+    readonly ok: true;
+    readonly document: SvgDocument;
+    readonly warnings: readonly string[];
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/**
+ * Plugin contribution to the import pipeline (categoria 4 do D-023).
+ *
+ * **Fields**:
+ * - `id`: unique within {@link ImporterRegistry}. Reverse-DNS suggested.
+ * - `name`: human-readable label for UIs that surface importer choice.
+ * - `mediaTypes`: list of MIME types the importer accepts (used by UI
+ *   to filter `<input type="file" accept="...">` and auto-pick).
+ * - `extensions`: file extensions WITHOUT the dot (`'svg'`, not `'.svg'`).
+ *   Same usage as `mediaTypes` for file-based UIs.
+ * - `import(text)`: parse `text` and return either a document or an
+ *   error. MUST be pure (no DOM/state mutation) for testability.
+ */
+interface Importer {
+    readonly id: string;
+    readonly name: string;
+    readonly mediaTypes: readonly string[];
+    readonly extensions: readonly string[];
+    import(text: string): ImportResult;
+}
+/**
+ * Plugin contribution to the export pipeline (categoria 5 do D-023).
+ *
+ * Mirrors {@link Importer} on the way out.
+ *
+ * **Fields**:
+ * - `id`/`name`: identifier + label
+ * - `mediaType`: emitted MIME type (e.g., `'image/svg+xml'`)
+ * - `extension`: suggested file extension WITHOUT the dot
+ * - `export(doc)`: serialize the document. Returns `string` for text
+ *   formats (SVG), or `Promise<string | Blob>` for binary / async
+ *   formats (PNG via canvas, PDF, etc. — anything that needs Image
+ *   loading or worker offload).
+ *
+ * **Why the union return type**: text-format exporters (SVG) are
+ * cheap + synchronous; forcing them to wrap in `Promise` would add
+ * noise + slow down the common case. Binary exporters are inherently
+ * async due to `Image.onload`. The union lets each format express
+ * its natural shape.
+ *
+ * Consumers check `typeof result === 'string'` for the sync branch
+ * and `await result` for the async branch (or use `await Promise.resolve(result)`
+ * to handle both uniformly).
+ */
+interface Exporter {
+    readonly id: string;
+    readonly name: string;
+    readonly mediaType: string;
+    readonly extension: string;
+    export(document: SvgDocument): string | Promise<string | Blob>;
+}
+
+/**
+ * Registry of {@link Importer}s (categoria 4 do D-023). Signal-backed,
+ * `register()` returns `Disposable`. Plugins contribute formats via
+ * `ctx.track(reg.register(importer))`.
+ *
+ * **Lookup helpers** for file-based UIs:
+ * - `byExtension(ext)`: case-insensitive extension match (without dot)
+ * - `byMediaType(type)`: exact MIME match
+ * - Both return the FIRST matching importer (insertion order tiebreak)
+ *
+ * **Why insertion-order tiebreak**: when multiple plugins claim the
+ * same extension (e.g., two SVG variants), the first-registered wins.
+ * Apps decide priority via the order in their `provideSvgEnginePlugin`
+ * array. To override a builtin, plug-in your importer BEFORE the
+ * builtin plugin.
+ */
+declare class ImporterRegistry {
+    private readonly _importers;
+    /** Reactive snapshot of all registered importers (insertion order). */
+    readonly importers: i0.Signal<readonly Importer[]>;
+    register(importer: Importer): Disposable;
+    get(id: string): Importer | null;
+    byExtension(ext: string): Importer | null;
+    byMediaType(mediaType: string): Importer | null;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ImporterRegistry, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ImporterRegistry>;
+}
+/**
+ * Registry of {@link Exporter}s (categoria 5 do D-023). Same shape as
+ * {@link ImporterRegistry}.
+ */
+declare class ExporterRegistry {
+    private readonly _exporters;
+    readonly exporters: i0.Signal<readonly Exporter[]>;
+    register(exporter: Exporter): Disposable;
+    get(id: string): Exporter | null;
+    byExtension(ext: string): Exporter | null;
+    byMediaType(mediaType: string): Exporter | null;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ExporterRegistry, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ExporterRegistry>;
+}
+
+/**
+ * Built-in SVG importer (Fase 5-IO). Parses SVG XML text into a
+ * {@link SvgDocument} that the editor's model understands.
+ *
+ * **Sanitization**: the importer never executes any payload from the
+ * input. Specifically:
+ *
+ * - `<script>` elements (anywhere in the tree) are dropped + warned
+ * - `on*` event-handler attributes (`onclick`, `onload`, ...) are
+ *   dropped + warned
+ * - `xlink:href` / `href` values starting with `javascript:` are
+ *   dropped + warned. `data:` URIs are allowed (caller can validate
+ *   externally if they want stricter policy)
+ * - External entity references (`<!ENTITY>` / `&xxe;`) are not
+ *   processed by the browser's DOMParser when called via `parseFromString`
+ *   with `'image/svg+xml'`, so XXE is structurally precluded
+ *
+ * **Unsupported elements** (gradients, filters, masks, clipPaths,
+ * markers, defs, use, switch, foreignObject, ...) are skipped with
+ * a single per-tag warning so the result is always a "best-effort"
+ * approximation — never a hard fail on a partially-supported file.
+ *
+ * **viewBox**: extracted from the root `<svg>`. If absent, falls back
+ * to `width`/`height` attributes; if those are missing too, defaults
+ * to `0 0 800 600`.
+ *
+ * **Pure**: no DOM mutation outside the throwaway parser document, no
+ * service injection. Safe to call from a Web Worker (if/when we add
+ * that path).
+ */
+declare const svgImporter: Importer;
+
+/**
+ * **D-097 — merge two `<defs>` fragments by top-level id.**
+ *
+ * A `<defs>` fragment is the literal inner XML of a `<defs>` block: zero
+ * or more top-level reusable elements (`<linearGradient>`, `<radialGradient>`,
+ * `<filter>`, `<pattern>`, `<clipPath>`, …), each typically carrying an `id`
+ * that shapes reference via `fill="url(#id)"`.
+ *
+ * Merging is needed whenever imported content (e.g. replacing/editing a Smart
+ * Object's contents, D-097) brings its own defs that must join the document's
+ * shared defs so the references keep resolving. Naive string concatenation
+ * would duplicate definitions every time the same SVG is re-imported/edited;
+ * this dedups by id:
+ *
+ * - **Existing** fragment is kept verbatim (it owns its ids).
+ * - From **incoming**, each top-level element is appended ONLY when its `id`
+ *   is not already present in existing. Id-less elements are always appended.
+ *
+ * Returns the original `existing` string (reference-preserving) when there is
+ * nothing new to add, so callers can cheaply skip a state write. Best-effort:
+ * if parsing is unavailable/fails (non-DOM env, malformed fragment) it falls
+ * back to plain concatenation rather than throwing.
+ *
+ * **Known limitation** (engine-wide): ids are document-global and NOT
+ * namespaced. Two unrelated SVGs that both use `id="grad"` collide — the first
+ * definition wins. Faithful multi-asset isolation would require id-rewriting,
+ * out of scope here (matches the additive-import behavior).
+ */
+declare function mergeDefsFragments(existing: string | undefined, incoming: string | undefined): string;
+
+/**
+ * Collect every element `id` defined inside a `<defs>` fragment string.
+ * Returns an empty set when the fragment is empty or `DOMParser` is
+ * unavailable (non-browser). Best-effort regex fallback if parsing fails.
+ */
+declare function collectDefsIds(defs: string | undefined | null): ReadonlySet<string>;
+/** Result of {@link namespaceCollidingDefs}. */
+interface NamespacedDefs {
+    /** The node tree with references to renamed ids rewritten (same ref when none). */
+    readonly root: SvgNode;
+    /** The defs fragment with colliding ids + their internal refs rewritten. */
+    readonly defs: string;
+    /** `oldId → newId` for every renamed id (empty when there was no collision). */
+    readonly renamed: ReadonlyMap<string, string>;
+}
+/**
+ * **D-101** — namespace the incoming `(root, defs)` so it can be merged into a
+ * document that already owns the ids in `taken`, without collision. Only ids in
+ * `defs` that are ALSO in `taken` are renamed (to `prefix + id`); every
+ * reference to them is rewritten in both the defs fragment and the node tree.
+ *
+ * Pure: never mutates its inputs. When nothing collides, returns the inputs
+ * unchanged (same references) with an empty `renamed` map — so the common
+ * single-import path is a no-op.
+ *
+ * @param root   the imported content (typically a group) whose nodes may
+ *               reference defs ids via style `url(#…)` or `symbol-use`.
+ * @param defs   the incoming `<defs>` inner fragment (as produced by the importer).
+ * @param taken  ids already present in the destination document's defs
+ *               (see {@link collectDefsIds}).
+ * @param prefix unique-per-merge prefix applied to colliding ids (caller-supplied
+ *               so the function stays deterministic / testable).
+ */
+declare function namespaceCollidingDefs(root: SvgNode, defs: string, taken: ReadonlySet<string>, prefix: string): NamespacedDefs;
+
+/**
+ * Built-in SVG exporter (Fase 5-IO). Serializes a {@link SvgDocument}
+ * back to SVG XML text with **deterministic** output: byte-for-byte
+ * stable for the same input, friendly for diffs / golden-file tests /
+ * VCS commits.
+ *
+ * **Determinism guarantees**:
+ *
+ * - Element attribute order: fixed per element type (canonical order
+ *   below) instead of object-iteration order
+ * - Numeric formatting: 6 decimal places max, trailing zeros stripped
+ *   (`Math.round(n * 1e6) / 1e6` → trim trailing zeros). Eliminates
+ *   floating-point noise like `0.30000000000000004`
+ * - Transform: only emitted when not identity (`[1,0,0,1,0,0]`).
+ *   Default matrix is implicit in the spec — no point bloating output
+ * - Style: only emitted when non-empty. Style attributes are emitted
+ *   as individual presentation attributes (`fill="..."`), not inline
+ *   CSS (`style="fill:..."`) — easier to query in raw SVG, and
+ *   identical visual rendering
+ *
+ * **Indentation**: 2-space, recursive. Tags on their own line for
+ * leaf elements; opening + content + closing tags collapsed for
+ * single-line text content. Matches Inkscape's default save style.
+ *
+ * **Pure**: no DOM mutation, no service injection. Worker-safe.
+ */
+declare const svgExporter: Exporter;
+/**
+ * **D-086** — Serialize a SINGLE node to its SVG element markup, in
+ * isolation (no document wrapper, no `<defs>`). Reuses the exporter's
+ * `renderNode` so a node's geometry/attributes/transform serialize
+ * exactly as they would inside a full export.
+ *
+ * **Primary use**: building `<clipPath>` / `<mask>` definitions from a
+ * "clipper" shape for the Object ▸ Mask commands (D-086) — the returned
+ * markup is the inner geometry placed inside a `<clipPath>` / `<mask>`
+ * element. Titles and SMIL are intentionally OFF (a clip/mask def needs
+ * pure geometry, not authored names or animation).
+ *
+ * **Coordinate space**: the node's own `transform` IS emitted, so the
+ * markup paints in the same place the node was on the canvas — exactly
+ * what `clipPathUnits="userSpaceOnUse"` / `maskUnits="userSpaceOnUse"`
+ * expect. Ancestor-group transforms are NOT baked in (caller's
+ * responsibility when the node is nested).
+ *
+ * @returns the element markup (possibly multi-line/indented), or `''`
+ *   when the node is doc-hidden (`metadata.visible === false`).
+ */
+declare function nodeToSvgMarkup(node: SvgNode): string;
+
+/**
+ * Reference plugin: PNG export via `<canvas>` (Item 6 — débito 5-IO).
+ *
+ * Serves two purposes:
+ * 1. **Real feature**: lets users export their drawing as a raster
+ *    PNG (handy for slack/discord/preview thumbnails)
+ * 2. **Demonstration of the async exporter contract** — shows how a
+ *    third-party plugin (or built-in) implements `Exporter` returning
+ *    `Promise<Blob>` instead of synchronous text
+ *
+ * **Pipeline**:
+ * - Serialize the document to SVG text via {@link svgExporter}
+ * - Wrap as a `data:image/svg+xml;base64,...` URI
+ * - Load it into an `Image` element (the only way browsers convert
+ *   SVG → raster on the main thread)
+ * - Draw to an offscreen `<canvas>` sized to the viewBox
+ * - `toBlob('image/png')` extracts the binary PNG
+ *
+ * **Quality**: the canvas runs at 2× the viewBox resolution to keep
+ * the export crisp on retina displays. Configurable in a future
+ * polish via constructor arg (kept hard-coded here for simplicity).
+ *
+ * **Failure modes**: when `Image.onerror` fires (malformed SVG, cross-
+ * origin issues) OR `canvas.toBlob` returns `null` (canvas tainted /
+ * unsupported), the returned Promise rejects with a descriptive error.
+ *
+ * **NOT a plugin yet**: this is just the `Exporter` object. The
+ * `builtinIoPlugin` could register it, but to demonstrate plugin
+ * separation we ship it as a SEPARATE plugin ({@link pngExporterPlugin})
+ * so consumers can opt in/out independently of the SVG IO plugin.
+ */
+/**
+ * Render a `SvgDocument` to a PNG Blob at the requested `scale`
+ * multiplier (1, 2, 3 — or any positive number). Reused by both the
+ * `Exporter` interface implementation and the playground's
+ * "Export PNG with presets" dialog.
+ *
+ * Pipeline matches the original `pngExporter`: serialize → base64 →
+ * `<img>` load → `<canvas>` paint → `toBlob('image/png')`.
+ */
+declare function renderPng(document: SvgDocument, scale?: number): Promise<Blob>;
+declare const pngExporter: Exporter;
+
+/** gzip a UTF-8 string to bytes. Throws if `CompressionStream` is absent. */
+declare function gzipText(text: string): Promise<Uint8Array>;
+/**
+ * gunzip bytes back to a UTF-8 string. Accepts an `ArrayBuffer` (e.g.
+ * `await file.arrayBuffer()`) or a `Uint8Array`. Throws if
+ * `DecompressionStream` is absent, and rejects if `input` is not valid
+ * gzip data.
+ */
+declare function gunzipText(input: ArrayBuffer | Uint8Array): Promise<string>;
+/**
+ * `Exporter` that serializes a document to SVG (via {@link svgExporter})
+ * then gzips it into an `.svgz` Blob. Async (gzip is stream-based), so it
+ * follows the same `Promise<Blob>` shape as `pngExporter`.
+ *
+ * The Blob's MIME stays `image/svg+xml` — that's what SVGZ *is* (a
+ * gzip-encoded SVG); the `.svgz` extension is what tags it as compressed
+ * to the OS and other tools.
+ */
+declare const svgzExporter: Exporter;
+
+/**
+ * **D-110 — Code Generators (Group A).** Contract for a "code output"
+ * format that transforms an {@link SvgDocument} into a **string of source
+ * code** — React JSX, a React component file, a Data URI, etc. — for
+ * pasting into an app or component library.
+ *
+ * **Why a registry distinct from {@link Exporter}**: an `Exporter`
+ * (io-types.ts) is download-oriented (`mediaType`/`extension`/`Blob`) and
+ * has no notion of per-format options. A code generator is preview-and-copy
+ * oriented and almost always carries a few knobs (component name, TS vs JS,
+ * encoding…). Modelling it as its own contract keeps the asset-export panel
+ * (binary/visual outputs) and the code-generation dialog (textual outputs)
+ * cleanly separated — exactly the split the user asked for: code is reviewed
+ * and copied, not configured-and-batched like a PNG slot.
+ *
+ * **Pure** (like `svgExporter`): `generate()` MUST be a pure
+ * `SvgDocument → string` transform — no DOM, no service access, no side
+ * effects. The "optimize first" step (running the {@link OptimizerRegistry}
+ * pipeline) happens BEFORE `generate()` is called, in the UI layer, so the
+ * generator always starts from a plain document. Worker-safe.
+ *
+ * **Plugin contribution**: generators register via
+ * `ctx.track(registry.register(gen))` exactly like importers/exporters —
+ * see {@link CodeGeneratorRegistry}.
+ */
+interface CodeGenerator {
+    /** Unique id within the {@link CodeGeneratorRegistry}. */
+    readonly id: string;
+    /** Human-readable label for the format dropdown (e.g. "React JSX"). */
+    readonly name: string;
+    /** Optional one-line description shown under the format picker. */
+    readonly description?: string;
+    /**
+     * Language hint for the output — drives the dialog subtitle and the
+     * Download filename extension fallback. e.g. `'tsx' | 'jsx' | 'text'`.
+     */
+    readonly language: string;
+    /** File extension (no leading dot) for the Download action. */
+    readonly extension: string;
+    /**
+     * Declarative option specs the UI renders **generically** (no per-format
+     * hardcode). Omit for a zero-option generator.
+     */
+    readonly options?: readonly CodeGeneratorOptionSpec[];
+    /**
+     * Transform the document into source code. `options` carries the resolved
+     * values for {@link options} (use {@link resolveCodeGeneratorOptionDefaults}
+     * to seed them); a generator MUST tolerate a missing/partial `options` by
+     * falling back to its declared defaults.
+     */
+    generate(document: SvgDocument, options?: CodeGeneratorOptions): string;
+}
+/** Allowed value types for a generator option. */
+type CodeGeneratorOptionValue = string | number | boolean;
+/** A free-text option (e.g. the component name). */
+interface CodeGeneratorTextOption {
+    readonly kind: 'text';
+    readonly key: string;
+    readonly label: string;
+    readonly default: string;
+    readonly placeholder?: string;
+    readonly hint?: string;
+}
+/** An on/off option (e.g. TypeScript, currentColor). */
+interface CodeGeneratorBooleanOption {
+    readonly kind: 'boolean';
+    readonly key: string;
+    readonly label: string;
+    readonly default: boolean;
+    readonly hint?: string;
+}
+/** A pick-one option (e.g. Data URI encoding url/base64). */
+interface CodeGeneratorSelectOption {
+    readonly kind: 'select';
+    readonly key: string;
+    readonly label: string;
+    readonly default: string;
+    readonly choices: readonly {
+        readonly value: string;
+        readonly label: string;
+    }[];
+    readonly hint?: string;
+}
+/** Discriminated union of every option control the dialog can render. */
+type CodeGeneratorOptionSpec = CodeGeneratorTextOption | CodeGeneratorBooleanOption | CodeGeneratorSelectOption;
+/** Resolved option values keyed by {@link CodeGeneratorOptionSpec.key}. */
+type CodeGeneratorOptions = Record<string, CodeGeneratorOptionValue>;
+/**
+ * Build the default option map for a generator (`{ key: default }` for every
+ * declared option). The UI seeds its editable option state from this; a
+ * generator called with no `options` behaves as if seeded from it too.
+ */
+declare function resolveCodeGeneratorOptionDefaults(gen: CodeGenerator): CodeGeneratorOptions;
+
+/**
+ * **D-110 — Registry of {@link CodeGenerator}s.** Signal-backed, same shape
+ * as {@link ExporterRegistry} / {@link ImporterRegistry}: `register()`
+ * returns a `Disposable`, lookups are insertion-ordered.
+ *
+ * Plugins contribute formats via `ctx.track(reg.register(generator))`; the
+ * built-in Group-A generators (React JSX / React Component / Data URI) are
+ * registered by `codeGeneratorsPlugin` (svg-engine/ui). Headless consumers
+ * can register the bare generators from `svg-engine/io` directly.
+ *
+ * `providedIn: 'root'` so the registry is a single shared instance — the
+ * code-generation dialog and any plugin see the same set.
+ */
+declare class CodeGeneratorRegistry {
+    private readonly _generators;
+    /** Reactive snapshot of all registered generators (insertion order). */
+    readonly generators: i0.Signal<readonly CodeGenerator[]>;
+    register(generator: CodeGenerator): Disposable;
+    get(id: string): CodeGenerator | null;
+    static ɵfac: i0.ɵɵFactoryDeclaration<CodeGeneratorRegistry, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<CodeGeneratorRegistry>;
+}
+
+/** Drop the leading `<?xml …?>` declaration — unwanted in JSX / data URIs. */
+declare function stripXmlProlog(svg: string): string;
+/**
+ * Replace concrete `fill`/`stroke` colors with `currentColor` so the output
+ * inherits the surrounding text color (the standard themeable-icon pattern).
+ * Leaves `none`, `transparent`, `url(#…)` paint-server refs, and values
+ * already set to `currentColor` untouched.
+ */
+declare function applyCurrentColor(svg: string): string;
+/**
+ * Rewrite a serialized SVG string into JSX: strips the `<?xml?>` prolog and
+ * rewrites every opening/self-closing tag's attributes (names → JSX, `style`
+ * string → object). Text nodes and entities are left as-is — JSX decodes the
+ * exporter's `&amp;`/`&lt;`/`&gt;` in element children correctly.
+ */
+declare function svgStringToJsx(svg: string): string;
+/**
+ * Serialize an SVG string to a `data:` URI. `url` encoding (default) uses
+ * `encodeURIComponent` — valid in `<img src>` and (quoted) CSS `url()`, and
+ * typically smaller than base64 for attribute-light icons. `base64` is the
+ * classic, universally-accepted form.
+ */
+declare function svgToDataUri(svg: string, encoding: 'url' | 'base64'): string;
+/** Coerce an arbitrary label into a PascalCase identifier (≥1 leading letter). */
+declare function toPascalCaseComponentName(name: string): string;
+/** Inline SVG-as-JSX (camelCased attributes) for pasting into a component. */
+declare const reactJsxGenerator: CodeGenerator;
+/** A standalone React component (.tsx/.jsx) that spreads props onto `<svg>`. */
+declare const reactComponentGenerator: CodeGenerator;
+/** A `data:image/svg+xml,…` URI for CSS `background-image` or an `<img>` src. */
+declare const dataUriGenerator: CodeGenerator;
+/** The Group-A built-in set, in display order. */
+declare const BUILTIN_CODE_GENERATORS: readonly CodeGenerator[];
+
+export { BUILTIN_CODE_GENERATORS, CodeGeneratorRegistry, ExporterRegistry, ImporterRegistry, applyCurrentColor, collectDefsIds, dataUriGenerator, gunzipText, gzipText, mergeDefsFragments, namespaceCollidingDefs, nodeToSvgMarkup, pngExporter, reactComponentGenerator, reactJsxGenerator, renderPng, resolveCodeGeneratorOptionDefaults, stripXmlProlog, svgExporter, svgImporter, svgStringToJsx, svgToDataUri, svgzExporter, toPascalCaseComponentName };
+export type { CodeGenerator, CodeGeneratorBooleanOption, CodeGeneratorOptionSpec, CodeGeneratorOptionValue, CodeGeneratorOptions, CodeGeneratorSelectOption, CodeGeneratorTextOption, Exporter, ImportResult, Importer, NamespacedDefs };

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

@@ -0,0 +1,183 @@
+import { SvgDocument, Disposable, Command, CommandContext, CommandResult } from '@mosaicoo/svg-engine/core';
+import * as i0 from '@angular/core';
+
+/**
+ * Plugin contribution to the SVG optimization pipeline (categoria 3
+ * do D-023). Pure transformation `SvgDocument → SvgDocument`.
+ *
+ * **Contract**:
+ * - `optimize(doc)` MUST be pure (no DOM, no service access, no
+ *   side effects). Worker-safe.
+ * - MUST return a structurally-equivalent document on no-op input
+ *   (lets the pipeline detect "nothing changed" via reference
+ *   equality and short-circuit).
+ * - SHOULD NOT mutate the input — return a new document via
+ *   `{ ...doc, root: ... }` when changes are needed.
+ *
+ * **Fields**:
+ * - `id`: unique within {@link OptimizerRegistry}
+ * - `name`: human-readable label for UIs
+ * - `description`: optional one-liner explaining what the pass does
+ * - `order`: sort key in the pipeline (lower runs first). Default
+ *   100. Use lower for "structural" passes that other passes can
+ *   then optimize on top of (e.g., precision-round before dedupe).
+ * - `defaultEnabled`: whether the pipeline includes this pass when
+ *   no explicit selection is provided. Default `true`.
+ */
+interface Optimizer {
+    readonly id: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly order?: number;
+    readonly defaultEnabled?: boolean;
+    optimize(document: SvgDocument): SvgDocument;
+}
+
+/**
+ * Registry of {@link Optimizer}s (categoria 3 do D-023). Signal-backed,
+ * `register()` returns `Disposable`. Plugins contribute passes via
+ * `ctx.track(reg.register(opt))`.
+ *
+ * The registry also offers a {@link runPipeline} convenience that
+ * sorts active optimizers by `order` (default 100, stable sort on
+ * ties) and chains them — most consumers want this, not raw enumeration.
+ */
+declare class OptimizerRegistry {
+    private readonly _optimizers;
+    /** Reactive snapshot (insertion order; pipeline reorders by `order`). */
+    readonly optimizers: i0.Signal<readonly Optimizer[]>;
+    register(optimizer: Optimizer): Disposable;
+    get(id: string): Optimizer | null;
+    /**
+     * Run all enabled optimizers in `order` ascending. When
+     * `enabledIds` is provided, only those (intersected with available)
+     * run — useful for "advanced settings" UIs where users toggle
+     * individual passes. When omitted, all optimizers with
+     * `defaultEnabled !== false` run.
+     *
+     * Returns a new document with all passes applied in order. If no
+     * pass changes the document (reference equality), the original
+     * document is returned unchanged.
+     */
+    runPipeline(document: SvgDocument, enabledIds?: ReadonlySet<string> | null): SvgDocument;
+    static ɵfac: i0.ɵɵFactoryDeclaration<OptimizerRegistry, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<OptimizerRegistry>;
+}
+
+/**
+ * Round all geometric numeric values to a fixed precision (default 3
+ * decimal places). Eliminates `0.30000000000000004` and friends that
+ * accumulate from floating-point drag / scale gestures, without losing
+ * meaningful coordinate precision.
+ *
+ * **Touches**: rect/ellipse/line/polygon/polyline/text/image positions
+ * + sizes + radii; path `d` numeric tokens (via regex); transform
+ * matrix components; style strokeWidth/opacity/fillOpacity/strokeOpacity.
+ *
+ * **Doesn't touch**: ids, hrefs, colors, transform STRUCTURE (only the
+ * numbers inside it).
+ *
+ * **Order 10** — runs FIRST in the default pipeline so later passes
+ * see clean rounded values.
+ */
+declare const precisionOptimizer: Optimizer;
+/**
+ * Strip presentation-attribute values that match the SVG default
+ * (e.g., `fill-opacity="1"`, `stroke-width="1"`). These attributes
+ * are redundant in the output — removing them shrinks the file and
+ * makes diffs less noisy.
+ *
+ * **Defaults handled**:
+ * - `fillOpacity === 1`
+ * - `strokeOpacity === 1`
+ * - `opacity === 1`
+ * - `visibility === 'visible'`
+ *
+ * **Order 50** — runs in the middle of the pipeline so precision
+ * rounding (10) already cleaned the values + later passes (e.g.,
+ * group pruning) see the minimized style.
+ *
+ * **NOT handled**: `fill === 'black'` / `stroke === 'none'` etc. Those
+ * are arguably "defaults" but stripping them changes rendered output
+ * if the parent specifies a different value (CSS inheritance). Safer
+ * to leave color defaults explicit.
+ */
+declare const dropDefaultsOptimizer: Optimizer;
+/**
+ * **D-072 follow-up — Strip authored-title emission preference.**
+ *
+ * Sets `document.exportPreferences.emitAuthoredTitles = false` so the
+ * SVG exporter omits the `<title>...</title>` child element it would
+ * otherwise emit for every node with `metadata.name`.
+ *
+ * **What it does NOT do**: remove `metadata.name` itself. The name
+ * stays on the model — the layer panel still shows "Bercos", a future
+ * export with the preference un-stripped (or the in-editor session)
+ * still has the name available. Stripping is purely an export-side
+ * decision, reversible by toggling the preference back to `true`.
+ *
+ * **Order 80** — runs after value-rounding (10) and default-dropping
+ * (50), before group-pruning (90). Position doesn't really matter for
+ * this pass (it doesn't touch the tree), but keeping it in the middle
+ * makes the pipeline read top-to-bottom by "what touches what".
+ *
+ * **Opt-in** (`defaultEnabled: false`): the default pipeline preserves
+ * authored names — stripping is for minified/production-ready output
+ * where editor metadata is unwanted.
+ */
+declare const stripAuthoredTitlesOptimizer: Optimizer;
+/**
+ * Remove empty groups (`<g>` with no children) recursively. Common
+ * after a delete-then-undo cycle or after the user ungroups+regroups.
+ *
+ * Preserves the document root (which is always a group) even if it
+ * becomes empty — the root is a structural anchor, not a layer.
+ *
+ * **Order 90** — runs after value-rounding (10) and default-stripping
+ * (50) so groups that became "empty" via earlier passes are picked up
+ * in the same pipeline run.
+ */
+declare const pruneEmptyGroupsOptimizer: Optimizer;
+
+/**
+ * Run the optimization pipeline as ONE undoable command (Item 3 —
+ * débito 5-Optimize).
+ *
+ * Pre-Item-3, the playground called `OptimizerRegistry.runPipeline()`
+ * directly and bypassed the undo stack — Optimize was destructive
+ * to history because the user couldn't `Ctrl+Z` back to the pre-
+ * optimize state. Now wrapping the pipeline in a Command produces
+ * exactly one undo entry covering the whole pass set.
+ *
+ * **Construction-time dependency injection of the registry**: the
+ * command needs access to the live `OptimizerRegistry`. Since
+ * `Command` doesn't have an injector (its `CommandContext` only
+ * exposes `state`), we pass the registry to the constructor. The
+ * playground / consumer injects `OptimizerRegistry` and passes it
+ * in.
+ *
+ * **No-op when pipeline doesn't change the document**: the registry's
+ * `runPipeline` returns the same reference when no pass mutated;
+ * we detect that and return `ok()` without pushing onto history.
+ *
+ * **Undo**: restores the pre-optimize document via the captured
+ * snapshot (one reference; structural sharing means it's cheap).
+ *
+ * **`enabledIds`**: forwarded to `runPipeline` so the caller can
+ * pick a subset of passes (e.g., from an "advanced settings" UI).
+ * When omitted, all `defaultEnabled` passes run.
+ */
+declare class OptimizeCommand implements Command {
+    private readonly registry;
+    private readonly enabledIds?;
+    readonly id: string;
+    readonly label = "Optimize";
+    readonly isDestructive = true;
+    private previousDocument;
+    constructor(registry: OptimizerRegistry, enabledIds?: (ReadonlySet<string> | null) | undefined);
+    execute(ctx: CommandContext): CommandResult;
+    undo(ctx: CommandContext): CommandResult;
+}
+
+export { OptimizeCommand, OptimizerRegistry, dropDefaultsOptimizer, precisionOptimizer, pruneEmptyGroupsOptimizer, stripAuthoredTitlesOptimizer };
+export type { Optimizer };