@weasel-js/svg 1.5.0 → 1.5.2

package/README.md

@@ -40,6 +40,49 @@ answer, and the alternative is unrepresentable anyway (see above). It only
 shows up on foreign SVG that sets decoration on a group and cancels it on a
 child.
 
+## Paints SVG cannot express
+
+SVG has `<linearGradient>`, `<radialGradient>` and `<pattern>` and nothing
+else, so a conic gradient — or any paint kind a consumer registers — has no
+element to serialize into. Both go out as a def in weasel's own namespace,
+declared on the root as `xmlns:wzl="urn:weasel-js:svg"` only when a document
+holds such a paint:
+
+```xml
+<defs><wzl:conicGradient id="grad0" gradientUnits="objectBoundingBox"
+  cx="0.5" cy="0.5" angle="0.25"><stop offset="0" stop-color="#ff0000"/>
+  <stop offset="1" stop-color="#0000ff"/></wzl:conicGradient></defs>
+<path fill="url(#grad0) #ff0000" d="…"/>
+```
+
+The color after the reference is SVG's own paint fallback: this package reads
+the def back and reproduces the paint exactly, every other renderer skips the
+def it does not know and paints that flat color instead. A registered kind's
+`toSvg` gets the same treatment, with the fallback taken from its `colorOf` —
+or `none` when the kind has no single color, so an unresolvable reference
+paints nothing rather than something arbitrary.
+
+That cuts both ways on import: a `fill="url(#mesh1) #c04a3f"` from Inkscape,
+whose mesh gradients this package does not model, imports as flat `#c04a3f`
+rather than as a dropped fill.
+
+### A gradient's blend space
+
+A gradient's `interpolate` — `'oklab'` or `'oklch'` — has no SVG spelling
+either: `color-interpolation` carries `sRGB` and `linearRGB` only. It goes out
+as `wzl:interpolate` on the gradient's *own* element, which stays
+`<linearGradient>` or `<radialGradient>`:
+
+```xml
+<linearGradient id="grad0" gradientUnits="objectBoundingBox"
+  x1="0" y1="0" x2="1" y2="0" wzl:interpolate="oklch">…</linearGradient>
+```
+
+No fallback color rides along, because a foreign renderer still paints the
+gradient — it just blends the stops in sRGB, which moves the midpoint rather
+than losing the paint. A space this package does not know is dropped on import
+rather than carried through.
+
 ## Raster images
 
 `<image>` parses to an `SvgImageNode` holding the `href` verbatim — an

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import { Path, FillStyle, StyledRun, TextStyle, Stroke, TilePatternSpec, IngestCtx } from '@weasel-js/core';
+import { Mat3 } from '@weasel-js/geom';
+import { Path, FillStyle, ScreenLength, StrokeAlign, StyledRun, TextStyle, TextVerticalAlign, Stroke, MarkerEntry, TilePatternSpec, IngestCtx } from '@weasel-js/core';
 
 /**
  * Public types for `@weasel-js/svg`. The package exposes a flat,
@@ -47,10 +48,15 @@ interface NamespacedElement {
     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]`.
+ * 2x3 affine matrix in SVG's `matrix(a b c d e f)` order, mapping
+ * `[x', y'] = [a*x + c*y + e, b*x + d*y + f]`.
+ *
+ * The same order the kernel's affine tier uses, so this is that type under
+ * the name the SVG spec gives it — not a parallel one. An `SvgGroupNode`'s
+ * transform and a geom `Mat3` are interchangeable without a conversion.
  */
-type Matrix = readonly [number, number, number, number, number, number];
+type Matrix = Mat3;
+
 /** Identity matrix — useful as a default in tests / constructors. */
 declare const IDENTITY_MATRIX: Matrix;
 /**
@@ -73,11 +79,9 @@ type SvgPaint = {
 interface SvgStroke {
     paint: SvgPaint;
     /** World units, or `{ px }` for a width that holds its rendered thickness
-     *  however the document is scaled — SVG's `vector-effect="non-scaling-stroke"`,
-     *  and the same unit system as the kit's `Stroke.width`. */
-    width: number | {
-        px: number;
-    };
+     *  however the document is scaled — SVG's `vector-effect="non-scaling-stroke"`.
+     *  Literally the kit's own unit, not a second spelling of it. */
+    width: ScreenLength;
     opacity?: number;
     /** `stroke-linecap`. Default per SVG spec is `'butt'`. */
     cap?: 'butt' | 'round' | 'square';
@@ -91,6 +95,10 @@ interface SvgStroke {
      * attribute may render with longer miters than the source SVG intended.
      */
     miterLimit?: number;
+    /** The kit stroke's `align`. SVG has no stroke alignment, so the serializer
+     *  writes the stroke centered and says so through `onWarn`; the parser
+     *  never sets it. */
+    align?: StrokeAlign;
     /** `marker-start` / `marker-mid` / `marker-end`, as the bare `url(#id)` key. */
     markerStart?: string;
     markerMid?: string;
@@ -126,6 +134,12 @@ interface SvgGroupNode {
     kind: 'group';
     children: SvgNode[];
     transform?: Matrix;
+    /** Clips the group's contents. Serializes to a `<clipPath>` def plus
+     *  `clip-path="url(#id)"`, and lives in the same space as `children` —
+     *  SVG applies the group's own `transform` to the clip as well.
+     *  A `<clipPath>` of more than one shape parses back as no clip: SVG
+     *  unions them and a `Path` holds one outline. */
+    clip?: Path;
     opacity?: number;
     /** Opaque per-element bag for declared namespaces. See `NamespaceMeta`. */
     meta?: NamespaceMeta;
@@ -159,6 +173,10 @@ interface SvgTextNode {
     runs?: StyledRun[];
     /** Node-wide typography. Defaults applied at render time via `resolveTextStyle`. */
     style?: TextStyle;
+    /** Where the laid-out text sits inside the box — `kit:text`'s
+     *  `data.verticalAlign`. SVG text has no box to align in, so this rides in
+     *  `data-weasel-vertical-align` and other readers draw the text top-aligned. */
+    verticalAlign?: TextVerticalAlign;
     /**
      * Node-wide glyph paint, the `FillStyle` / `Stroke` a kit text node holds
      * in `data.fill` / `data.stroke`. Not `SvgPaint`, which is the path
@@ -186,6 +204,12 @@ interface SvgTextNode {
  * a reference and only resolves when something downstream loads it.
  *
  * SVG's `preserveAspectRatio` is not modeled; the box is taken literally.
+ *
+ * With a `source` rect or a flip, the element is written as a `<g
+ * data-weasel-image>` holding a nested `<svg>` viewport at the box, whose
+ * `viewBox` is the source window over a unit-square `<image>` — plain SVG 1.1,
+ * which any reader crops and mirrors the same way, and which `parseSvg` reads
+ * back as one image node.
  */
 interface SvgImageNode {
     kind: 'image';
@@ -194,6 +218,20 @@ interface SvgImageNode {
     y: number;
     width: number;
     height: number;
+    /** The part of the bitmap drawn into the box, as fractions of the bitmap's
+     *  width and height from its top-left. Omitted draws the whole bitmap.
+     *  Fractions rather than bitmap pixels because this package never decodes
+     *  the image, so it cannot know its size. */
+    source?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Mirror the drawn region within the box, as `ImageDrawCommand` does. The
+     *  box does not move. */
+    flipX?: boolean;
+    flipY?: boolean;
     /** Element-level opacity (`opacity="..."`), 0..1. */
     opacity?: number;
     /** Element-level rotation in **radians**, pivoting around the unrotated
@@ -240,6 +278,13 @@ interface ParseResult {
     height?: number;
     /** Text content of the first `<title>` child of `<svg>`, when present. */
     title?: string;
+    /**
+     * An entry for each document `<marker>` a stroke references under a key the
+     * marker registry does not know, keyed as the strokes in `nodes` now name
+     * them. Nothing draws them until they are registered (`registerMarker`),
+     * which `unpackSvgFiles` does.
+     */
+    markers?: MarkerEntry[];
 }
 /** Options for {@link serializeSvg}. */
 interface SerializeOptions {
@@ -254,9 +299,11 @@ interface SerializeOptions {
         height: number;
     };
     /**
-     * Called for paint that can't be expressed in SVG and is dropped — a
-     * conic gradient, or a pattern carrying a `TextureHandle` instead of a
-     * `TilePatternSpec`. Without this the loss is silent.
+     * Called for what the document cannot carry the way weasel draws it: a
+     * paint SVG cannot express (a pattern carrying a `TextureHandle` instead of
+     * a `TilePatternSpec`), a stroke aligned off its edge, text that wraps or
+     * sits lower than the top of its box. Each message is said once per call.
+     * Without this the loss is silent.
      */
     onWarn?: (message: string) => void;
     /** Emit `width="..."` on the root `<svg>`. */