@weasel-js/svg 1.7.0 → 1.7.2

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
@@ -130,6 +138,22 @@ 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, MarkerRef, 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,
@@ -255,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 {
@@ -352,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
@@ -365,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.
@@ -393,23 +469,20 @@ declare function tilePreviewSvg(spec: TilePatternSpec, background?: string): str
 declare function tilePreviewCssUrl(spec: TilePatternSpec, background?: string): string;
 
 /**
- * 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.
+ * `@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.
  */
-
-/** `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;
+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
@@ -472,6 +545,7 @@ interface SvgKitTree<TId extends string = string> {
     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[];
@@ -520,6 +594,7 @@ type SvgSceneDraft<TData = Record<string, unknown>> = {
 };
 /** 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
@@ -570,4 +645,4 @@ declare function svgNodesToKitDrafts<TData = Record<string, unknown>>(input: Par
  */
 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 SvgKitLeafData, type SvgKitPose, type SvgKitTree, type SvgKitTreeNode, type SvgLeafNode, type SvgNode, type SvgNodesFromKitOptions, type SvgNodesToKitDraftsOptions, type SvgPaint, type SvgPathNode, type SvgSceneDraft, type SvgStroke, type SvgTextNode, fillDataFromSvg, nativeSvgKind, nativeSvgSpace, parseSvg, serializeSvg, strokeDataFromSvg, svgImageFromKit, svgLeafFromKit, svgNodesFromKit, svgNodesToKitDrafts, svgPaintFromKit, svgStrokeFromKit, 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 };