@weasel-js/svg 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 orochi235
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,23 @@
+# @weasel-js/svg
+
+SVG import/export for @weasel-js/core: parse SVG strings into weasel-native shapes and serialize them back.
+
+Part of [weasel](https://github.com/orochi235/weasel), a domain-agnostic 2D
+scene-graph canvas kit for React. See the
+[API reference](https://orochi235.github.io/weasel/api/).
+
+## Install
+
+```sh
+npm install @weasel-js/svg
+```
+
+## Usage
+
+```ts
+import { /* … */ } from '@weasel-js/svg';
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,307 @@
+import { Path, FillStyle, StyledRun, TextStyle, IngestCtx } from '@weasel-js/core';
+
+/**
+ * Public types for `@weasel-js/svg`. The package exposes a flat,
+ * discriminated-union node model (`SvgNode`) that mirrors the SVG element
+ * tree but uses weasel-native leaf data (`Path`, `FillStyle`) for geometry and
+ * paint.
+ *
+ * Parsing collapses every `transform="..."` onto its descendants' geometry,
+ * so the `SvgNode` tree returned from `parseSvg` never has a non-identity
+ * group transform. Consumers may still construct groups with explicit
+ * transforms before serializing, in which case the serializer emits a
+ * single `matrix(a b c d e f)` on the `<g>`.
+ */
+
+/**
+ * Opaque pass-through bag for namespaced XML content.
+ *
+ * weasel-svg does not interpret the contents — it only ensures that any
+ * attributes or child elements in a *declared* XML namespace round-trip
+ * losslessly through parse → serialize. Consumers (e.g. an app-specific
+ * bridge layer) hang their domain semantics off this structure.
+ *
+ * Keyed by namespace prefix (the prefix is a write-time choice; the URI
+ * is the canonical identifier and is supplied via `ParseOptions.namespaces`
+ * / `SerializeOptions.namespaces`).
+ */
+interface NamespaceMeta {
+    [prefix: string]: {
+        /** Local-name → string-value map for attributes in this namespace. */
+        attrs?: Record<string, string>;
+        /**
+         * Child elements in this namespace, keyed by local name. Each entry
+         * is an array because a namespace can host multiple sibling elements
+         * with the same tag (e.g. `<wd:layer/><wd:layer/>`).
+         */
+        elements?: Record<string, NamespacedElement[]>;
+    };
+}
+/** Opaque structured representation of a namespaced element. */
+interface NamespacedElement {
+    /** Attribute local-name → string-value. */
+    attrs: Record<string, string>;
+    /** Text content, when the element contains only text (no child elements). */
+    text?: string;
+    /** Nested namespaced children, keyed by local name (recursive). */
+    children?: Record<string, NamespacedElement[]>;
+}
+/**
+ * 2x3 affine matrix in column-major form (SVG's `matrix(a b c d e f)`
+ * order). Maps `[x', y'] = [a*x + c*y + e, b*x + d*y + f]`.
+ */
+type Matrix = readonly [number, number, number, number, number, number];
+/** Identity matrix — useful as a default in tests / constructors. */
+declare const IDENTITY_MATRIX: Matrix;
+/**
+ * FillStyle description in the SVG sense — either explicit `none`, a solid
+ * color, or a reference to a weasel-native gradient `FillStyle`. Solid colors
+ * are normalized to `#rrggbb` strings; opacity is carried separately so
+ * `fill-opacity` and `stroke-opacity` round-trip cleanly.
+ */
+type SvgPaint = {
+    kind: 'none';
+} | {
+    kind: 'solid';
+    color: string;
+    opacity?: number;
+} | {
+    kind: 'gradient';
+    paint: FillStyle;
+};
+/** Stroke description: a paint plus structural line parameters. */
+interface SvgStroke {
+    paint: SvgPaint;
+    width: number;
+    opacity?: number;
+    /** `stroke-linecap`. Default per SVG spec is `'butt'`. */
+    cap?: 'butt' | 'round' | 'square';
+    /** `stroke-linejoin`. Default per SVG spec is `'miter'`. SVG's `arcs` / `miter-clip` map to `'miter'` with a warning. */
+    join?: 'miter' | 'round' | 'bevel';
+    /** `stroke-dasharray` as a flat number array. Odd-length inputs are doubled per SVG spec. */
+    dash?: number[];
+    /**
+     * `stroke-miterlimit`. SVG's default is 4. Weasel's renderer defaults to
+     * 10 (Canvas2D) when unset, so parsed strokes without an explicit
+     * attribute may render with longer miters than the source SVG intended.
+     */
+    miterLimit?: number;
+}
+/**
+ * Leaf node: a path geometry plus fill/stroke. All other v1 shapes
+ * (`<rect>`, `<ellipse>`, etc.) are lowered to this representation on
+ * parse — `<rect>` uses weasel's `RectPath` fast-path subtype when
+ * possible, everything else becomes a `PolygonPath`.
+ */
+interface SvgPathNode {
+    kind: 'path';
+    path: Path;
+    fill: SvgPaint;
+    stroke?: SvgStroke;
+    /** Element-level opacity (`opacity="..."`), 0..1. */
+    opacity?: number;
+    /** Element-level rotation in **radians**, pivoting around the AABB
+     *  center of the underlying `path` geometry. Emitted as SVG
+     *  `transform="rotate(angleDegrees cx cy)"`. */
+    rotation?: number;
+    /** Opaque per-element bag for declared namespaces. See `NamespaceMeta`. */
+    meta?: NamespaceMeta;
+}
+/**
+ * Group node: an SVG `<g>`. On parse, `transform` is always omitted (any
+ * `transform` attribute is collapsed onto descendants' geometry). On
+ * serialize, a non-identity `transform` is emitted as
+ * `matrix(a b c d e f)`.
+ */
+interface SvgGroupNode {
+    kind: 'group';
+    children: SvgNode[];
+    transform?: Matrix;
+    opacity?: number;
+    /** Opaque per-element bag for declared namespaces. See `NamespaceMeta`. */
+    meta?: NamespaceMeta;
+}
+/**
+ * Text leaf node. Mirrors the kit's `TextPose` shape — a bounding box plus
+ * text content, optional rich-text `runs` (per-range styling), and an
+ * optional `TextStyle` for the node-wide defaults.
+ *
+ * Note on SVG text geometry: native `<text>` flows from a baseline; it
+ * doesn't have width/height attributes. The serializer emits
+ * `dominant-baseline="text-before-edge"` so `y` is the top of the text
+ * box, plus `data-weasel-width` / `data-weasel-height` so weasel's
+ * explicit box dimensions round-trip losslessly. External SVG text
+ * (lacking the data-* attrs) imports with estimated dimensions —
+ * `width = 99999` (effectively unbounded so wrap doesn't fire) and
+ * `height = fontSize * lineHeight * (lineCount || 1)`.
+ */
+interface SvgTextNode {
+    kind: 'text';
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Plain text. When `runs` is set, `runsToPlainText(runs)` must equal `text`. */
+    text: string;
+    /** Optional per-range styling — same shape as `TextPose.runs`. */
+    runs?: StyledRun[];
+    /** Node-wide style. Defaults applied at render time via `resolveTextStyle`. */
+    style?: TextStyle;
+    /** Element-level opacity (`opacity="..."`), 0..1. */
+    opacity?: number;
+    /** Element-level rotation in **radians**, pivoting around the unrotated
+     *  AABB center `(x + width/2, y + height/2)`. Emitted as SVG
+     *  `transform="rotate(angleDegrees cx cy)"`. */
+    rotation?: number;
+    /** Opaque per-element bag for declared namespaces. See `NamespaceMeta`. */
+    meta?: NamespaceMeta;
+}
+/** Discriminated-union node — the leaf of the public tree. */
+type SvgNode = SvgPathNode | SvgGroupNode | SvgTextNode;
+/** Options for {@link parseSvg}. */
+interface ParseOptions {
+    /**
+     * Map of prefix → URI for XML namespaces the caller wants surfaced.
+     * Attributes / child elements in any declared namespace are collected
+     * into `SvgNode.meta` (per element) or `ParseResult.documentMeta` (root).
+     * Undeclared namespaces are preserved in the DOM but not promoted into
+     * the structured `meta` bag; they are silently dropped at serialize time.
+     */
+    namespaces?: Record<string, string>;
+}
+/** Output of {@link parseSvg}. */
+interface ParseResult {
+    nodes: SvgNode[];
+    /** Non-fatal notices (unsupported elements, unrecognized attributes). */
+    warnings: string[];
+    /**
+     * Opaque per-document bag for declared namespaces. Holds root-level
+     * namespaced attributes (`documentMeta.<prefix>.attrs`) and namespaced
+     * root children (`documentMeta.<prefix>.elements`).
+     */
+    documentMeta?: NamespaceMeta;
+    /** Root `viewBox` attribute, parsed from `"x y width height"`. */
+    viewBox?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Root `width` attribute, parsed as a unitless number when present. */
+    width?: number;
+    /** Root `height` attribute, parsed as a unitless number when present. */
+    height?: number;
+    /** Text content of the first `<title>` child of `<svg>`, when present. */
+    title?: string;
+}
+/** Options for {@link serializeSvg}. */
+interface SerializeOptions {
+    /**
+     * Override the root `viewBox`. When omitted, the serializer computes
+     * a tight bounding box from the supplied nodes.
+     */
+    viewBox?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Emit `width="..."` on the root `<svg>`. */
+    width?: number;
+    /** Emit `height="..."` on the root `<svg>`. */
+    height?: number;
+    /**
+     * Emit `<title>...</title>` as the first child of the root `<svg>`. The
+     * value is XML-escaped on output. Empty strings are skipped.
+     */
+    title?: string;
+    /**
+     * Map of prefix → URI for XML namespaces to declare on the root
+     * `<svg>`. The serializer reads `documentMeta[prefix]` and
+     * `node.meta[prefix]` to write the actual attributes and elements.
+     */
+    namespaces?: Record<string, string>;
+    /**
+     * Opaque per-document namespaced extras. Each `<prefix>.attrs` becomes
+     * `<prefix>:<name>="..."` attributes on the root `<svg>`. Each
+     * `<prefix>.elements[localName]` becomes `<prefix>:<localName>...>`
+     * children placed immediately before any geometry.
+     */
+    documentMeta?: NamespaceMeta;
+    /** Pretty-print with newlines + indentation. Default `false`. */
+    pretty?: boolean;
+}
+
+/**
+ * Parse an SVG document string into a `SvgNode[]` tree. Walks the SVG
+ * DOM (via the platform's `DOMParser` — jsdom in tests, the browser at
+ * runtime) and lowers each supported element to weasel-native shapes.
+ *
+ * Transforms are pushed onto a matrix stack and collapsed into leaf
+ * geometry at the moment a leaf is created, so the output tree never
+ * carries `transform` data — even on `<g>` nodes.
+ */
+
+/**
+ * Public entry point: parse an SVG document string. Errors during DOM
+ * parsing produce a `ParseResult` with an empty `nodes` array and a
+ * warning describing the issue, rather than throwing.
+ */
+declare function parseSvg(svg: string, opts?: ParseOptions): ParseResult;
+
+/**
+ * Serialize a `SvgNode[]` tree to an SVG document string. Every leaf is
+ * emitted as a `<path>` (even shapes that started as `<rect>` etc.) —
+ * lossless geometry round-trip beats round-tripping the element-kind
+ * label. Gradient paints are gathered into a single `<defs>` block.
+ */
+
+/**
+ * Walk the tree and produce an SVG document string. The root `<svg>`'s
+ * `viewBox` is taken from `opts.viewBox` if supplied, otherwise computed
+ * as a tight bounding box around every leaf.
+ */
+declare function serializeSvg(nodes: SvgNode[], opts?: SerializeOptions): string;
+
+interface SvgDraftBounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+type DraftPose = SvgDraftBounds & {
+    rotation?: number;
+};
+/**
+ * One node the unpack wants the scene to materialize, in parent-before-child
+ * order (a draft's `parentId` always names an earlier draft, or `null` for
+ * roots). Leaf `data` is kit-painter-native (see module doc).
+ */
+type SvgSceneDraft = {
+    kind: 'container';
+    id: string;
+    parentId: string | null;
+    pose: DraftPose;
+} | {
+    kind: 'leaf';
+    id: string;
+    parentId: string | null;
+    pose: DraftPose;
+    data: Record<string, unknown>;
+};
+/**
+ * Walk an `SvgNode[]` tree and emit a flat, parent-before-child list of
+ * {@link SvgSceneDraft}s. Each `<g>` becomes a container whose pose is the
+ * union AABB of its descendants (the kit `group` action's convention);
+ * path/text leaves carry kit-painter-native data. Empty groups are dropped.
+ */
+declare function svgNodesToKitDrafts(nodes: readonly SvgNode[], nextId: () => string): SvgSceneDraft[];
+/**
+ * Parse each file and insert its node tree — one undoable `applyOps` batch
+ * per file. See the module doc for placement and wrapping policy. A file
+ * that fails to parse (or parses to nothing) is skipped with a
+ * `console.warn`; the rest proceed.
+ */
+declare function unpackSvgFiles(files: File[], ctx: IngestCtx): Promise<void>;
+
+export { IDENTITY_MATRIX, type Matrix, type NamespaceMeta, type NamespacedElement, type ParseOptions, type ParseResult, type SerializeOptions, type SvgDraftBounds, type SvgGroupNode, type SvgNode, type SvgPaint, type SvgPathNode, type SvgSceneDraft, type SvgStroke, type SvgTextNode, parseSvg, serializeSvg, svgNodesToKitDrafts, unpackSvgFiles };