@weasel-js/svg 1.6.1 → 1.7.1

package/README.md

@@ -66,6 +66,14 @@ 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.
 
+`serializeSvg` is synchronous, so a kind loaded on demand (`mesh-gradient`, or
+one declared with `registerPaintKindLoader`) that has not landed yet has no
+`toSvg` to call, and its def is left out with a warning. `await warmSvg(nodes)`
+first loads the kinds those nodes paint with, and the faces a sub- or
+superscript run with its own `baselineShift` takes its size from — nothing
+else, so an unrelated kind that fails to load cannot fail the export.
+`svgNeeds(nodes)` lists the same things without loading them.
+
 ### A gradient's blend space
 
 A gradient's `interpolate` — `'oklab'` or `'oklch'` — has no SVG spelling
@@ -83,6 +91,69 @@ 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.
 
+## Scene nodes, both ways
+
+`svgNodesToKitDrafts(parseSvg(text), nextId)` lowers a document to scene-node
+drafts the kit's built-in path, text and image painters draw, and registers
+the document's markers. Containers carry no opacity, so an element or group
+`opacity` is multiplied into the paints of the leaves under it. `nextId` is
+handed the node each id is for, and `options.leaf` maps each leaf's kit data
+into data of your own shape, from the source node's metadata too.
+
+`svgNodesFromKit(scene)` goes the other way: containers become groups, and
+each leaf is written the way its painter draws it, with the pose baked into
+the geometry and box-relative paints resolved into that box. Hand
+`serializeSvg` the result. Options pick the roots, skip nodes (a hidden
+layer), replace a leaf's lowering or decorate a group. The per-leaf pieces are
+public too: `svgLeafFromKit`, `svgPaintFromKit`, `svgStrokeFromKit`,
+`svgImageFromKit`.
+
+## Stroke markers
+
+A marker reference goes out as `marker-start` / `-mid` / `-end="url(#id)"` with
+one `<marker>` def per distinct reference. The path keeps its full-length `d`:
+baking the kit's inset in would have a re-import trim the line a second time.
+The cost is that other renderers draw the line under a hollow head.
+
+| Reference | Def id | What the def carries |
+|---|---|---|
+| `'arrow'` | `arrow` | `markerUnits="strokeWidth"` |
+| `{ key: 'arrow', size: 3 }` | `arrow-s3` | `markerUnits="userSpaceOnUse"`, `wzl:key="arrow"`, `wzl:size="3"` |
+| `{ key: 'arrow', size: { px: 6 } }` | `arrow-s6px` | the same, drawn at 6 user units, `wzl:size="6px"` |
+
+Any entry with a nonzero inset adds `wzl:inset` in marker units, and the root
+declares the `wzl` namespace whenever one of these attributes appears. `orient`
+is `auto-start-reverse`, because the kit turns every start head around, or an
+entry's fixed angle in degrees. An entry with its own `toSvg` writes its own
+def and gets none of the `wzl` attributes (a sized reference to one warns). A
+reference to a key nothing registered writes no attribute.
+
+On import, `url(#id)` naming a registered key reads back as that key, so an
+unsized built-in needs no def. A def with `wzl:key` and `wzl:size` reads back
+as that sized reference, registering the def's geometry under the key if
+nothing else has. Any other `<marker>` becomes an entry in
+`ParseResult.markers`, keyed by its id plus a hash of what it draws, and
+`svgNodesToKitDrafts` registers it. It is minted per reference rather than per
+def, because a `userSpaceOnUse` size and an `orient="auto"` start both depend on
+the referencing stroke. `wzl:inset` restores the inset; without it the inset is
+0. A reference to a marker neither registered nor defined warns and is dropped.
+
+## Stylesheets
+
+`<style>` rules cascade with the presentation attributes and `style=""`. A parse
+is one static render, so `@media` and `<style media>` are answered once, against
+a fixed environment: a `screen` whose viewport is the root's `width`/`height`
+(else its `viewBox`, else 300 × 150), `prefers-color-scheme: light`, and no
+hover or pointer. Pass `parseSvg(svg, { media: { prefersColorScheme: 'dark',
+width: 1200 } })` to render for different media; `evaluateMediaQuery` answers a
+query against the same environment.
+
+`@supports` asks whether this parser honors a declaration, not whether a browser
+parses it: `(fill: red)` holds, `(display: grid)` and `(clip-path: url(#c))` do
+not, because nothing reads them from a stylesheet. `@import` is not fetched, and
+each one is reported in `warnings`. Rules inside `@layer`, `@container` and
+other at-rules are skipped.
+
 ## Raster images
 
 `<image>` parses to an `SvgImageNode` holding the `href` verbatim — an

package/dist/index.d.ts

@@ -1,5 +1,44 @@
 import { Mat3 } from '@weasel-js/geom';
-import { Path, FillStyle, ScreenLength, StrokeAlign, StyledRun, TextStyle, TextVerticalAlign, Stroke, MarkerEntry, TilePatternSpec, ImageNodeData, IngestCtx } from '@weasel-js/core';
+import { Path, FillStyle, ScreenLength, StrokeAlign, MarkerRef, StyledRun, TextStyle, TextVerticalAlign, Stroke, MarkerEntry, RenderNeeds, TilePatternSpec, ImageNodeData, IngestCtx } from '@weasel-js/core';
+
+/**
+ * Media Queries 4 evaluation against a fixed environment.
+ *
+ * A parse represents one static render, so `@media` and `<style media>` are
+ * answered once, against an {@link SvgMediaEnvironment}, rather than tracked
+ * as live conditions.
+ */
+/** The media a parse is taken to be rendered on. */
+interface SvgMediaEnvironment {
+    /** Media type; `all` always matches as well. */
+    readonly type: string;
+    /** Viewport width in CSS px. */
+    readonly width: number;
+    /** Viewport height in CSS px. */
+    readonly height: number;
+    /** Device pixels per CSS px. */
+    readonly resolution: number;
+    readonly prefersColorScheme: 'light' | 'dark';
+    readonly prefersReducedMotion: 'no-preference' | 'reduce';
+    /** Answers both `hover` and `any-hover`. */
+    readonly hover: 'none' | 'hover';
+    /** Answers both `pointer` and `any-pointer`. */
+    readonly pointer: 'none' | 'coarse' | 'fine';
+    /** How often the output can change once rendered. */
+    readonly update: 'none' | 'slow' | 'fast';
+    /** Bits per color component; 0 on a monochrome device. */
+    readonly color: number;
+    /** Bits per pixel of a monochrome device; 0 otherwise. */
+    readonly monochrome: number;
+}
+/** A static, light-scheme screen render with no pointer. Width and height are the replaced-element default. */
+declare const DEFAULT_MEDIA_ENVIRONMENT: SvgMediaEnvironment;
+/**
+ * Whether a media query list matches `env`. An empty list matches; a
+ * malformed query in the list is `not all`, leaving its neighbors intact; an
+ * unknown feature or value is unknown, which never matches, even under `not`.
+ */
+declare function evaluateMediaQuery(list: string, env: SvgMediaEnvironment): boolean;
 
 /**
  * Public types for `@weasel-js/svg`. The package exposes a flat,
@@ -99,10 +138,12 @@ interface SvgStroke {
      *  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;
-    markerEnd?: string;
+    /** `marker-start` / `marker-mid` / `marker-end` as the kit's `MarkerRef`: the
+     *  bare `url(#id)` key, or a key with the `size` the serializer writes into a
+     *  def of its own. */
+    markerStart?: MarkerRef;
+    markerMid?: MarkerRef;
+    markerEnd?: MarkerRef;
 }
 /**
  * Leaf node: a path geometry plus fill/stroke. All other v1 shapes
@@ -253,6 +294,14 @@ interface ParseOptions {
      * the structured `meta` bag; they are silently dropped at serialize time.
      */
     namespaces?: Record<string, string>;
+    /**
+     * The media `@media` rules and `<style media>` are evaluated against. A
+     * parse is one static render: by default a `screen` whose viewport is the
+     * root's `width` / `height` (else its `viewBox`, else 300 × 150), with a
+     * light color scheme and no hover or pointer. Fields given here replace
+     * those defaults.
+     */
+    media?: Partial<SvgMediaEnvironment>;
 }
 /** Output of {@link parseSvg}. */
 interface ParseResult {
@@ -350,12 +399,24 @@ interface SerializeOptions {
 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.
+ * Map between SVG `<linearGradient>` / `<radialGradient>` elements and
+ * weasel's `FillStyle` gradient variants. Definitions are indexed by id
+ * wherever in the document they appear, and looked up when a `fill` /
+ * `stroke` attribute references one as `url(#id)`. On serialize, we
+ * emit a fresh `<defs>` block with stable generated ids.
  */
 
+/** `true` when SVG has a paint server for this kind, so the reference needs no
+ *  fallback color and the root needs no foreign namespace. */
+/** Whether SVG has its own paint server for paint kind `kind`: solids, the
+ *  linear and radial gradients, and patterns. Any other kind is written in
+ *  weasel's namespace with a fallback color, which other renderers paint flat. */
+declare function nativeSvgKind(kind: string): boolean;
+/** Whether a gradient interpolating through `space` blends the same in every
+ *  SVG renderer — only sRGB, the default. A perceptual space still exports,
+ *  but renderers other than weasel blend it in sRGB. */
+declare function nativeSvgSpace(space: string | null | undefined): boolean;
+
 /**
  * Walk the tree and produce an SVG document string. The root `<svg>`'s
  * `viewBox` is taken from `opts.viewBox` if supplied, otherwise computed
@@ -363,6 +424,23 @@ declare function parseSvg(svg: string, opts?: ParseOptions): ParseResult;
  */
 declare function serializeSvg(nodes: SvgNode[], opts?: SerializeOptions): string;
 
+/**
+ * What `serializeSvg(nodes)` reads that loads on demand: the paint kind of
+ * every fill and stroke it writes as a paint server, and the face of every
+ * run whose script size it takes from font metrics. The kinds come from the
+ * serializer's own paint pre-pass, so the two cannot disagree. Registered
+ * kinds are included.
+ */
+declare function svgNeeds(nodes: readonly SvgNode[]): RenderNeeds;
+/**
+ * Load what {@link svgNeeds} lists, so a `serializeSvg(nodes)` issued after it
+ * resolves writes every paint server's def and every script size from the
+ * face it renders in. Only those load: a lazily registered kind or font the
+ * nodes do not use is never fetched, and cannot fail the export. A kind
+ * nothing registered is passed over; the export warns about it instead.
+ */
+declare function warmSvg(nodes: readonly SvgNode[]): Promise<void>;
+
 /**
  * Map between SVG `<pattern>` elements and weasel's `pattern` `FillStyle`.
  * The counterpart to `gradients.ts` for the other paint-server kind.
@@ -390,6 +468,102 @@ declare function tilePreviewSvg(spec: TilePatternSpec, background?: string): str
 /** `tilePreviewSvg` packed as a `url(...)` value for CSS `background-image`. */
 declare function tilePreviewCssUrl(spec: TilePatternSpec, background?: string): string;
 
+/**
+ * `@supports` evaluation. A declaration test asks whether this parser would
+ * honor the declaration ({@link isDeclarationHonored}), not whether a browser
+ * could parse it — the answer decides whether the guarded rules apply here.
+ */
+interface SupportsOptions {
+    /** Answers `selector(…)`; without it every selector test is false. */
+    readonly selector?: (selector: string) => boolean;
+}
+/**
+ * Whether a `@supports` condition holds. `selector()` defers to
+ * `opts.selector`; any other function and any unrecognized parenthesized
+ * content is false, so `not` of one is true. A malformed condition is false.
+ */
+declare function evaluateSupports(condition: string, opts?: SupportsOptions): boolean;
+
+/**
+ * The kit-to-SVG direction: scene leaves back to `SvgNode`s, the inverse of
+ * `svgNodesToKitDrafts`. Each leaf is written as the built-in painter that
+ * draws it would draw it — the pose baked into the geometry, box-relative
+ * paints resolved into that box — so `serializeSvg` over the result shows what
+ * the canvas shows.
+ */
+
+/** A leaf's box: where it is drawn, and the frame its box-relative paints
+ *  resolve against. */
+interface SvgKitPose {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    rotation?: number;
+}
+/** The leaf data the kit's path, text and image painters read — what
+ *  `svgNodesToKitDrafts` writes. */
+interface SvgKitLeafData {
+    path?: Path;
+    fill?: FillStyle | null;
+    stroke?: Stroke | null;
+    text?: string;
+    style?: TextStyle;
+    runs?: readonly StyledRun[];
+    verticalAlign?: TextVerticalAlign;
+    image?: ImageNodeData['image'];
+}
+/** A kit paint as an `SvgPaint`. `null` is `fill="none"`; a box-relative
+ *  gradient or pattern is resolved into `box`, since the geometry it paints
+ *  is written already placed there. */
+declare function svgPaintFromKit(fill: FillStyle | null, box: SvgKitPose): SvgPaint;
+/** A kit `Stroke` as an `SvgStroke` — the inverse of `strokeDataFromSvg`.
+ *  One with no paint or no width draws nothing and is written as no stroke. */
+declare function svgStrokeFromKit(stroke: Stroke | null | undefined, box: SvgKitPose): SvgStroke | undefined;
+/** Write a `kit:image` leaf as an `SvgImageNode` — the inverse of the image
+ *  arm of `svgNodesToKitDrafts`. The pose is the image's box. */
+declare function svgImageFromKit(image: ImageNodeData['image'], pose: SvgKitPose): SvgImageNode;
+/**
+ * Write one leaf as the `SvgNode` its built-in painter draws — image, text or
+ * path, in the order the painters claim a node. `null` for data none of them
+ * draws.
+ *
+ * A path with no `fill` takes `kit:path`'s fallback: the default shape fill
+ * when it has no stroke, and no fill when it has one.
+ */
+declare function svgLeafFromKit(data: SvgKitLeafData, pose: SvgKitPose): SvgPathNode | SvgTextNode | SvgImageNode | null;
+/** One node as {@link svgNodesFromKit} reads it. */
+interface SvgKitTreeNode {
+    kind: string;
+    data: unknown;
+    pose: SvgKitPose;
+}
+/** The read side of a scene that {@link svgNodesFromKit} walks. A kit
+ *  `Scene` is one as it stands. */
+interface SvgKitTree<TId extends string = string> {
+    readonly roots: readonly TId[];
+    childrenOf(id: TId): readonly TId[];
+    get(id: TId): SvgKitTreeNode | undefined;
+}
+/** Options for {@link svgNodesFromKit}. */
+interface SvgNodesFromKitOptions<TId extends string = string> {
+    /** Walk these ids, in this order, instead of the tree's roots. */
+    roots?: readonly TId[];
+    /** `false` leaves a node out, with everything under it — a hidden layer. */
+    include?(id: TId): boolean;
+    /** Lower a leaf yourself; `null` leaves it out. Defaults to {@link svgLeafFromKit}. */
+    leaf?(id: TId, node: SvgKitTreeNode): SvgNode | null;
+    /** Decorate the group written for a container, e.g. with `meta`. */
+    group?(id: TId, group: SvgGroupNode): SvgGroupNode;
+}
+/**
+ * Walk a scene's container tree into `SvgNode`s ready for `serializeSvg`:
+ * every `container` becomes a group of its children, in z-order, and every
+ * leaf goes through {@link svgLeafFromKit} unless `options.leaf` says
+ * otherwise.
+ */
+declare function svgNodesFromKit<TId extends string>(tree: SvgKitTree<TId>, options?: SvgNodesFromKitOptions<TId>): SvgNode[];
+
 /** Axis-aligned box, in the coordinate space of the SVG being unpacked. Used
  *  for the bounds a draft occupies before it becomes a scene node. */
 interface SvgDraftBounds {
@@ -406,7 +580,7 @@ type DraftPose = SvgDraftBounds & {
  * 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 = {
+type SvgSceneDraft<TData = Record<string, unknown>> = {
     kind: 'container';
     id: string;
     parentId: string | null;
@@ -416,8 +590,30 @@ type SvgSceneDraft = {
     id: string;
     parentId: string | null;
     pose: DraftPose;
-    data: Record<string, unknown>;
+    data: TData;
 };
+/** A leaf `SvgNode`: everything but a group. */
+type SvgLeafNode = Exclude<SvgNode, SvgGroupNode>;
+/** Options for {@link svgNodesToKitDrafts}. */
+interface SvgNodesToKitDraftsOptions<TData> {
+    /** Lower a leaf yourself, from the kit data the default writes for it and
+     *  the node it came from — for data shaped other than the kit painters', or
+     *  metadata the document carries. `null` leaves it out. */
+    leaf?(id: string, draft: {
+        pose: DraftPose;
+        data: SvgKitLeafData;
+    }, source: SvgLeafNode): TData | null;
+}
+/** Lower an `SvgPaint` onto the `kit:path` painter's `data.fill` — a
+ *  `FillStyle`, or `null` for SVG's `fill="none"` (the painter skips the
+ *  fill rather than falling back to its default). A solid paint keeps its
+ *  `fill-opacity`.
+ *
+ *  A gradient rides through as the `FillStyle` it already is, normalized to
+ *  the leaf's own box: `objectBoundingBox` gradients already are, and a
+ *  `userSpaceOnUse` one is rebased so it survives the fit-clamp and the
+ *  drop-point placement that move the geometry out from under it. */
+declare function fillDataFromSvg(paint: SvgPaint | undefined, box: SvgDraftBounds): FillStyle | null | undefined;
 /** Lower an `SvgStroke` onto the leaf's `data.stroke`.
  *
  *  Everything the SVG carried — paint, width, cap, join, dash, miter limit,
@@ -426,16 +622,21 @@ type SvgSceneDraft = {
  *  `userSpaceOnUse` gradient survives the fit-clamp and the drop-point
  *  placement. */
 declare function strokeDataFromSvg(stroke: SvgStroke | undefined, box: SvgDraftBounds): Stroke | undefined;
-/** Write a `kit:image` leaf as an `SvgImageNode` — the inverse of the image
- *  arm of {@link svgNodesToKitDrafts}. The pose is the image's box. */
-declare function svgImageFromKit(image: ImageNodeData['image'], pose: DraftPose): SvgImageNode;
 /**
  * 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.
+ *
+ * Handed a whole `ParseResult`, it also registers the document's markers
+ * (`parsed.markers`), without which the strokes naming them draw bare.
+ * Containers carry no opacity, so an element or group `opacity` is multiplied
+ * into the paints of every leaf under it.
+ *
+ * `nextId` is handed the node each id is for. `options.leaf` replaces a leaf's
+ * data; a group whose leaves it all leaves out is dropped like an empty one.
  */
-declare function svgNodesToKitDrafts(nodes: readonly SvgNode[], nextId: () => string): SvgSceneDraft[];
+declare function svgNodesToKitDrafts<TData = Record<string, unknown>>(input: ParseResult | readonly SvgNode[], nextId: (source: SvgNode) => string, options?: SvgNodesToKitDraftsOptions<TData>): SvgSceneDraft<TData>[];
 /**
  * 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
@@ -444,4 +645,4 @@ declare function svgNodesToKitDrafts(nodes: readonly SvgNode[], nextId: () => st
  */
 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 SvgImageNode, type SvgNode, type SvgPaint, type SvgPathNode, type SvgSceneDraft, type SvgStroke, type SvgTextNode, parseSvg, serializeSvg, strokeDataFromSvg, svgImageFromKit, svgNodesToKitDrafts, tilePreviewCssUrl, tilePreviewSvg, unpackSvgFiles };
+export { DEFAULT_MEDIA_ENVIRONMENT, IDENTITY_MATRIX, type Matrix, type NamespaceMeta, type NamespacedElement, type ParseOptions, type ParseResult, type SerializeOptions, type SupportsOptions, type SvgDraftBounds, type SvgGroupNode, type SvgImageNode, type SvgKitLeafData, type SvgKitPose, type SvgKitTree, type SvgKitTreeNode, type SvgLeafNode, type SvgMediaEnvironment, type SvgNode, type SvgNodesFromKitOptions, type SvgNodesToKitDraftsOptions, type SvgPaint, type SvgPathNode, type SvgSceneDraft, type SvgStroke, type SvgTextNode, evaluateMediaQuery, evaluateSupports, fillDataFromSvg, nativeSvgKind, nativeSvgSpace, parseSvg, serializeSvg, strokeDataFromSvg, svgImageFromKit, svgLeafFromKit, svgNeeds, svgNodesFromKit, svgNodesToKitDrafts, svgPaintFromKit, svgStrokeFromKit, tilePreviewCssUrl, tilePreviewSvg, unpackSvgFiles, warmSvg };