stroke-outline 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yuki Kishino
+
+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

@@ -1,3 +1,97 @@
-# Temporary Holding Version
+# stroke-outline
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Turn vector paths into the filled outline of their stroke — the geometry a
+canvas draws for `stroke()`, returned as a path you can fill, cache, hit-test
+or tessellate. A WebAssembly build of a C++ library; works in browsers, workers
+and Node.
+
+```js
+import { init } from 'stroke-outline';
+
+const so = await init();  // loads the WASM once; reuse the result
+
+// stroke SVG path data
+const outline = so.buildOutline('M 10 10 H 90 A 20 20 0 0 1 90 50', { lineWidth: 8, lineCap: 'round' });
+outline.toSVG();    // SVG path data — <path d>, new Path2D(...), a file
+outline.commands;   // [{ type: 'moveTo', x, y }, { type: 'cubicTo', c1x, ... }, ...]
+outline.error;      // null, or { message } if the SVG data was malformed
+
+// parse SVG once, then stroke it as often as you like
+const icon = so.pathFromSVG('M 0 0 H 100 V 100 H 0 Z M 30 30 V 70 H 70 V 30 Z');
+const thin = so.buildOutline(icon, { lineWidth: 2 });
+const thick = so.buildOutline(icon, { lineWidth: 12, align: 'inside' });
+thinEl.setAttribute('d', thin.toSVG());
+thickEl.setAttribute('d', thick.toSVG());
+
+// or build paths in code
+const path = new so.Path().moveTo(0, 0).lineTo(100, 0).arcTo(30, 30, 0, false, true, 100, 60);
+const dashed = so.buildOutline(path, { lineWidth: 6, align: 'inside', dash: [12, 6] });
+ctx.fill(new Path2D(dashed.toSVG())); // each dash is its own subpath
+```
+
+**Fill outlines with the nonzero rule** (the default for canvas `fill()` and
+SVG). Outlines may overlap themselves; nonzero renders that correctly. With
+`clipToShape: true`, closed paths come out as simple contours that also fill
+correctly with even-odd.
+
+## API
+
+- `init()` → `Promise<StrokeOutline>`. Loads the WASM module; call it once and
+  reuse the result.
+- `so.buildOutline(pathOrSvg, options?)` → the outline as a `Path`. Takes a `Path` or
+  SVG path data; malformed data is stroked up to the first error, and the
+  outline's `error` says why (as for `pathFromSVG`, below).
+- `new so.Path()` with `moveTo`, `lineTo`, `quadTo`, `cubicTo`,
+  `arcTo(rx, ry, xAxisRotationDeg, largeArc, sweep, x, y)` and `close`, all
+  chainable; `.commands` and `.toSVG(precision = 3)`.
+- `so.pathFromSVG(d)` → `Path`. Malformed path data keeps everything before
+  the first error (as SVG renders it), and `path.error` is
+  `{ message }`, saying what went wrong and where
+  (`'expected a number at position 11'`, an index into `d`). `error` is `null`
+  for valid data and for paths built in code. Use it to parse once and stroke
+  many times, or to read the input's commands.
+- `precision` is a minimum number of decimals; small paths get more, so
+  rounding stays within ~1e-4 of their size.
+- `so.module` is the raw Embind module, for anything not wrapped here.
+
+Nothing needs freeing: the wrapper releases every WASM-side object itself.
+
+### Options
+
+All optional; omitted ones take these defaults.
+
+| Option | Default | |
+| --- | --- | --- |
+| `lineWidth` | `1` | must be a positive finite number, else nothing is stroked |
+| `lineJoin` | `'miter'` | `'miter'`, `'bevel'`, `'round'` |
+| `lineCap` | `'butt'` | `'butt'`, `'square'`, `'round'` |
+| `miterLimit` | `4` | below 1 behaves as 1 (always bevel) |
+| `align` | `'center'` | `'center'`, `'inside'`, `'outside'` — closed subpaths, relative to the whole fill (holes included) |
+| `fillRule` | `'nonzero'` | `'nonzero'`, `'evenodd'` — how subpaths form the fill, for `align` and `clipToShape` |
+| `clipToShape` | `false` | resolve over-wide or overlapping strokes into simple contours |
+| `dash` | none | e.g. `[10, 5]`; `[0, gap]` with round caps draws dots |
+| `dashOffset` | `0` | |
+
+An unknown option value (e.g. `lineJoin: 'rounded'`) throws a `TypeError`.
+
+## Bundlers
+
+The WebAssembly binary is embedded in the package's JavaScript, so there is no
+`.wasm` file to serve or configure: it works as is in Vite (dev and build),
+webpack, Rollup, esbuild and Node.
+
+## Building from source
+
+```sh
+# from the repository root: build the WASM module (publishes it into js/src/wasm)
+cmake --preset wasm && cmake --build --preset wasm-release
+cd js
+npm install
+npm test        # builds dist/ and runs the tests in Node
+npm pack        # the tarball that would be published
+```
+
+## License
+
+MIT — see `LICENSE`. Includes code ported from svg-arc-to-cubic-bezier
+(Colin Meinke, ISC license); see `THIRD_PARTY_NOTICES`.

package/THIRD_PARTY_NOTICES

@@ -0,0 +1,29 @@
+Third-party notices
+===================
+
+This project includes code derived from the following third-party software.
+
+-------------------------------------------------------------------------------
+svg-arc-to-cubic-bezier
+https://github.com/colinmeinke/svg-arc-to-cubic-bezier
+
+Used in: src/io/svg_arc.cpp (SVG elliptical arc to cubic bézier conversion),
+ported to C++. Also compiled into the WebAssembly module.
+
+Internet Systems Consortium license
+===================================
+
+Copyright (c) `2017`, `Colin Meinke`
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted, provided that the above copyright notice
+and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.
+-------------------------------------------------------------------------------

package/dist/index.d.ts

@@ -0,0 +1,102 @@
+import type { MainModule } from './wasm/stroke_outline.js';
+export type LineJoin = 'miter' | 'bevel' | 'round';
+export type LineCap = 'butt' | 'square' | 'round';
+export type StrokeAlign = 'center' | 'inside' | 'outside';
+export type FillRule = 'nonzero' | 'evenodd';
+export interface StrokeOptions {
+    /** Stroke width; must be a positive finite number. Default 1. */
+    lineWidth?: number;
+    /** Default 'miter'. */
+    lineJoin?: LineJoin;
+    /** Default 'butt'. */
+    lineCap?: LineCap;
+    /** Miter length / line width beyond which a miter is beveled. Default 4. */
+    miterLimit?: number;
+    /** Inside/outside apply to closed subpaths, relative to the whole fill. Default 'center'. */
+    align?: StrokeAlign;
+    /** How subpaths combine into a fill (for align and clipToShape). Default 'nonzero'. */
+    fillRule?: FillRule;
+    /** Resolve over-wide/overlapping strokes into simple contours. Default false. */
+    clipToShape?: boolean;
+    /** Dash pattern, e.g. [10, 5]. Empty or omitted: solid. [0, gap] with round caps: dots. */
+    dash?: number[];
+    /** Where the dash pattern starts. Default 0. */
+    dashOffset?: number;
+}
+/** One path command; coordinates are absolute. */
+export type PathCommand = {
+    type: 'moveTo';
+    x: number;
+    y: number;
+} | {
+    type: 'lineTo';
+    x: number;
+    y: number;
+} | {
+    type: 'quadTo';
+    cx: number;
+    cy: number;
+    x: number;
+    y: number;
+} | {
+    type: 'cubicTo';
+    c1x: number;
+    c1y: number;
+    c2x: number;
+    c2y: number;
+    x: number;
+    y: number;
+} | {
+    type: 'close';
+};
+/** Why SVG path data stopped parsing. */
+export interface SvgError {
+    /**
+     * What went wrong, and where (an index into the string):
+     * `'expected a number at position 11'`, or, when the data ends too early,
+     * `'expected a number at position 10 (end of data)'`.
+     */
+    message: string;
+}
+export interface Path {
+    moveTo(x: number, y: number): Path;
+    lineTo(x: number, y: number): Path;
+    quadTo(cx: number, cy: number, x: number, y: number): Path;
+    cubicTo(c1x: number, c1y: number, c2x: number, c2y: number, x: number, y: number): Path;
+    /** SVG elliptical arc to (x, y), expanded to cubics. */
+    arcTo(rx: number, ry: number, xAxisRotationDeg: number, largeArc: boolean, sweep: boolean, x: number, y: number): Path;
+    close(): Path;
+    /** The commands so far (absolute coordinates). */
+    readonly commands: readonly PathCommand[];
+    /**
+     * For a path parsed from malformed SVG data, or the outline of one: why and
+     * where parsing stopped (the path holds everything before it, as SVG
+     * renders it). Otherwise null.
+     */
+    readonly error: SvgError | null;
+    /** SVG path data; `precision` is the minimum number of decimals (default 3). */
+    toSVG(precision?: number): string;
+}
+export interface StrokeOutline {
+    /** A new, empty path. */
+    Path: new () => Path;
+    /**
+     * Parse SVG path data. Malformed data keeps everything before the first
+     * error, as SVG renders it; `path.error` says whether, why and where.
+     */
+    pathFromSVG(d: string): Path;
+    /**
+     * Stroke a path, or SVG path data; returns the outline as a new path (fill
+     * it with nonzero). Malformed SVG data is stroked up to the first error, as
+     * SVG renders it, and the outline's `error` says why and where.
+     */
+    buildOutline(path: Path | string, options?: StrokeOptions): Path;
+    /** The underlying Embind module, for anything not wrapped here. */
+    readonly module: MainModule;
+}
+/**
+ * Load the WASM module and return the API. Call once and reuse the result.
+ * The WebAssembly binary is embedded in the package, so there is no file to
+ * serve or locate.
+ */
+export declare function init(): Promise<StrokeOutline>;

package/dist/index.js

@@ -0,0 +1,212 @@
+// The stroke-outline JavaScript API: a thin, typed wrapper over the WASM module.
+//
+//   import { init } from 'stroke-outline';
+//   const so = await init();
+//   const outline = so.buildOutline('M 0 0 L 100 0', { lineWidth: 8, lineCap: 'round' });
+//   ctx.fill(new Path2D(outline.toSVG()));
+//
+// Options are partial: anything omitted takes the C++ default. Nothing here
+// needs freeing; the wrapper releases every WASM-side object itself.
+import createModule from './wasm/stroke_outline.js';
+/**
+ * Load the WASM module and return the API. Call once and reuse the result.
+ * The WebAssembly binary is embedded in the package, so there is no file to
+ * serve or locate.
+ */
+export async function init() {
+    return createApi(await createModule());
+}
+function createApi(module) {
+    const ZERO = { x: 0, y: 0 };
+    const joins = { miter: module.LineJoin.Miter, bevel: module.LineJoin.Bevel, round: module.LineJoin.Round };
+    const caps = { butt: module.LineCap.Butt, square: module.LineCap.Square, round: module.LineCap.Round };
+    const aligns = {
+        center: module.StrokeAlign.Center,
+        inside: module.StrokeAlign.Inside,
+        outside: module.StrokeAlign.Outside,
+    };
+    const fillRules = { nonzero: module.FillRule.NonZero, evenodd: module.FillRule.EvenOdd };
+    function pick(table, value, name, fallback) {
+        if (value === undefined)
+            return fallback;
+        if (!(value in table))
+            throw new TypeError(`stroke-outline: unknown ${name} '${value}'`);
+        return table[value];
+    }
+    function settings(options = {}) {
+        const d = module.defaultStrokeSettings();
+        return {
+            lineWidth: options.lineWidth ?? d.lineWidth,
+            lineJoin: pick(joins, options.lineJoin, 'lineJoin', d.lineJoin),
+            lineCap: pick(caps, options.lineCap, 'lineCap', d.lineCap),
+            miterLimit: options.miterLimit ?? d.miterLimit,
+            align: pick(aligns, options.align, 'align', d.align),
+            fillRule: pick(fillRules, options.fillRule, 'fillRule', d.fillRule),
+            clipToShape: options.clipToShape ?? d.clipToShape,
+            dashPattern: options.dash ?? d.dashPattern,
+            dashOffset: options.dashOffset ?? d.dashOffset,
+        };
+    }
+    function toWasm(commands) {
+        const vec = new module.PathCommandVector();
+        for (const c of commands) {
+            let command;
+            switch (c.type) {
+                case 'moveTo':
+                    command = { verb: module.Verb.MoveTo, ctrl1: ZERO, ctrl2: ZERO, to: { x: c.x, y: c.y } };
+                    break;
+                case 'lineTo':
+                    command = { verb: module.Verb.LineTo, ctrl1: ZERO, ctrl2: ZERO, to: { x: c.x, y: c.y } };
+                    break;
+                case 'quadTo':
+                    command = {
+                        verb: module.Verb.QuadraticTo,
+                        ctrl1: { x: c.cx, y: c.cy },
+                        ctrl2: ZERO,
+                        to: { x: c.x, y: c.y },
+                    };
+                    break;
+                case 'cubicTo':
+                    command = {
+                        verb: module.Verb.CubicTo,
+                        ctrl1: { x: c.c1x, y: c.c1y },
+                        ctrl2: { x: c.c2x, y: c.c2y },
+                        to: { x: c.x, y: c.y },
+                    };
+                    break;
+                case 'close':
+                    command = { verb: module.Verb.Close, ctrl1: ZERO, ctrl2: ZERO, to: ZERO };
+                    break;
+            }
+            vec.push_back(command);
+        }
+        return vec;
+    }
+    // Read a vector into plain commands and free it.
+    function fromWasm(vec) {
+        try {
+            const out = [];
+            for (let i = 0; i < vec.size(); i++) {
+                const c = vec.get(i);
+                switch (c.verb.value) {
+                    case module.Verb.MoveTo.value:
+                        out.push({ type: 'moveTo', x: c.to.x, y: c.to.y });
+                        break;
+                    case module.Verb.LineTo.value:
+                        out.push({ type: 'lineTo', x: c.to.x, y: c.to.y });
+                        break;
+                    case module.Verb.QuadraticTo.value:
+                        out.push({ type: 'quadTo', cx: c.ctrl1.x, cy: c.ctrl1.y, x: c.to.x, y: c.to.y });
+                        break;
+                    case module.Verb.CubicTo.value:
+                        out.push({
+                            type: 'cubicTo',
+                            c1x: c.ctrl1.x,
+                            c1y: c.ctrl1.y,
+                            c2x: c.ctrl2.x,
+                            c2y: c.ctrl2.y,
+                            x: c.to.x,
+                            y: c.to.y,
+                        });
+                        break;
+                    case module.Verb.Close.value:
+                        out.push({ type: 'close' });
+                        break;
+                }
+            }
+            return out;
+        }
+        finally {
+            vec.delete();
+        }
+    }
+    function withWasm(commands, use) {
+        const vec = toWasm(commands);
+        try {
+            return use(vec);
+        }
+        finally {
+            vec.delete();
+        }
+    }
+    class PathImpl {
+        list = [];
+        // Current point and subpath start, for arcs and close.
+        x = 0;
+        y = 0;
+        startX = 0;
+        startY = 0;
+        error;
+        constructor(commands = [], error = null) {
+            for (const c of commands)
+                this.push(c);
+            this.error = error;
+        }
+        push(c) {
+            this.list.push(c);
+            if (c.type === 'close') {
+                this.x = this.startX;
+                this.y = this.startY;
+            }
+            else {
+                this.x = c.x;
+                this.y = c.y;
+                if (c.type === 'moveTo') {
+                    this.startX = c.x;
+                    this.startY = c.y;
+                }
+            }
+            return this;
+        }
+        get commands() {
+            return this.list;
+        }
+        moveTo(x, y) {
+            return this.push({ type: 'moveTo', x, y });
+        }
+        lineTo(x, y) {
+            return this.push({ type: 'lineTo', x, y });
+        }
+        quadTo(cx, cy, x, y) {
+            return this.push({ type: 'quadTo', cx, cy, x, y });
+        }
+        cubicTo(c1x, c1y, c2x, c2y, x, y) {
+            return this.push({ type: 'cubicTo', c1x, c1y, c2x, c2y, x, y });
+        }
+        arcTo(rx, ry, rotation, largeArc, sweep, x, y) {
+            // From the current point. A degenerate arc comes back as a straight line.
+            for (const c of fromWasm(module.arcToCommands(this.x, this.y, rx, ry, rotation, largeArc, sweep, x, y)))
+                this.push(c);
+            return this;
+        }
+        close() {
+            return this.push({ type: 'close' });
+        }
+        toSVG(precision = 3) {
+            return withWasm(this.list, vec => module.pathToSvg(vec, precision));
+        }
+    }
+    return {
+        Path: PathImpl,
+        pathFromSVG: d => {
+            const parsed = module.parseSvgPathChecked(d);
+            const error = parsed.ok ? null : { message: String(parsed.message) };
+            return new PathImpl(fromWasm(parsed.commands), error);
+        },
+        buildOutline: (path, options) => {
+            const s = settings(options);
+            if (typeof path !== 'string')
+                return new PathImpl(withWasm(path.commands, vec => fromWasm(module.buildStrokeOutline(vec, s))));
+            // SVG data: stroke the parsed commands where they are, in WASM memory.
+            const parsed = module.parseSvgPathChecked(path);
+            try {
+                const error = parsed.ok ? null : { message: String(parsed.message) };
+                return new PathImpl(fromWasm(module.buildStrokeOutline(parsed.commands, s)), error);
+            }
+            finally {
+                parsed.commands.delete();
+            }
+        },
+        module,
+    };
+}

package/dist/wasm/stroke_outline.d.ts

@@ -0,0 +1,96 @@
+// TypeScript bindings for emscripten-generated code.  Automatically generated at compile time.
+interface WasmModule {
+}
+
+type EmbindString = ArrayBuffer|Uint8Array|Uint8ClampedArray|Int8Array|string;
+export interface ClassHandle {
+  isAliasOf(other: ClassHandle): boolean;
+  delete(): void;
+  deleteLater(): this;
+  isDeleted(): boolean;
+  // @ts-ignore - If targeting lower than ESNext, this symbol might not exist.
+  [Symbol.dispose](): void;
+  clone(): this;
+}
+export type Vec2 = {
+  x: number,
+  y: number
+};
+
+export interface VerbValue<T extends number> {
+  value: T;
+}
+export type Verb = VerbValue<0>|VerbValue<1>|VerbValue<2>|VerbValue<3>|VerbValue<4>;
+
+export interface LineJoinValue<T extends number> {
+  value: T;
+}
+export type LineJoin = LineJoinValue<0>|LineJoinValue<1>|LineJoinValue<2>;
+
+export interface LineCapValue<T extends number> {
+  value: T;
+}
+export type LineCap = LineCapValue<0>|LineCapValue<1>|LineCapValue<2>;
+
+export interface StrokeAlignValue<T extends number> {
+  value: T;
+}
+export type StrokeAlign = StrokeAlignValue<0>|StrokeAlignValue<1>|StrokeAlignValue<2>;
+
+export interface FillRuleValue<T extends number> {
+  value: T;
+}
+export type FillRule = FillRuleValue<0>|FillRuleValue<1>;
+
+export type PathCommand = {
+  verb: Verb,
+  ctrl1: Vec2,
+  ctrl2: Vec2,
+  to: Vec2
+};
+
+export type StrokeSettings = {
+  lineWidth: number,
+  lineJoin: LineJoin,
+  lineCap: LineCap,
+  miterLimit: number,
+  align: StrokeAlign,
+  fillRule: FillRule,
+  clipToShape: boolean,
+  dashPattern: any,
+  dashOffset: number
+};
+
+export interface PathCommandVector extends ClassHandle, Iterable<PathCommand> {
+  push_back(_0: PathCommand): void;
+  resize(_0: number, _1: PathCommand): void;
+  size(): number;
+  get(_0: number): PathCommand | undefined;
+  set(_0: number, _1: PathCommand): boolean;
+}
+
+export type SvgParse = {
+  commands: PathCommandVector,
+  ok: boolean,
+  message: EmbindString
+};
+
+interface EmbindModule {
+  Verb: {MoveTo: VerbValue<0>, LineTo: VerbValue<1>, QuadraticTo: VerbValue<2>, CubicTo: VerbValue<3>, Close: VerbValue<4>};
+  LineJoin: {Miter: LineJoinValue<0>, Bevel: LineJoinValue<1>, Round: LineJoinValue<2>};
+  LineCap: {Butt: LineCapValue<0>, Square: LineCapValue<1>, Round: LineCapValue<2>};
+  StrokeAlign: {Center: StrokeAlignValue<0>, Inside: StrokeAlignValue<1>, Outside: StrokeAlignValue<2>};
+  FillRule: {NonZero: FillRuleValue<0>, EvenOdd: FillRuleValue<1>};
+  PathCommandVector: {
+    new(): PathCommandVector;
+  };
+  buildStrokeOutline(_0: PathCommandVector, _1: StrokeSettings): PathCommandVector;
+  defaultStrokeSettings(): StrokeSettings;
+  parseSvgPath(_0: EmbindString): PathCommandVector;
+  parseSvgPathChecked(_0: EmbindString): SvgParse;
+  pathToSvg(_0: PathCommandVector, _1: number): string;
+  arcToCommands(_0: number, _1: number, _2: number, _3: number, _4: number, _5: boolean, _6: boolean, _7: number, _8: number): PathCommandVector;
+}
+
+export type MainModule = WasmModule & EmbindModule;
+export default function MainModuleFactory (options?: unknown): Promise<MainModule>;