@flighthq/shape 0.3.0-next.906.07cea63 → 0.3.1-next.209.43ef1bc

package/dist/shapeStrokeOutline.js

@@ -0,0 +1,164 @@
+import { PathCommand } from '@flighthq/types/contract';
+import { compactStrokePath } from './compactStrokePath';
+import { appendShapeGeometryCommand, getPathCommandOperandCount } from './shapeFill';
+// Resolves a Shape's drawing-command stream into stroke OUTLINE regions for the GPU fill path: each
+// `lineStyle` span's centerline geometry is offset by the compact open-stroke kernel (real
+// miter/bevel/round joins, butt/round/square caps, and dashing), emitted as a
+// `ShapeFillRegion` so the renderer tessellates + fills it with the same flat-color mesh path solid
+// fills use. This replaces the offscreen Canvas-2D raster-to-texture stroke fallback with
+// GPU-tessellated, resolution-independent geometry (sharp when scaled, no per-shape offscreen cost,
+// and no bounds-clipped miter spikes) without retaining the larger closed-ring validation kernel.
+//
+// Returns `null` when the shape uses a stroke the direct-fill outline route cannot express, so the
+// caller falls back to the raster path: a gradient/bitmap stroke (non-solid color), or a CLOSED stroke.
+// A closed stroke offsets into a hollow RING, and the tessellator fills each contour solid with no hole
+// subtraction, so a ring can't be direct-filled — only an OPEN stroke's outline is a simple fillable
+// polygon. Closure is decided geometrically on the accumulated centerline (a CLOSE verb, or a subpath
+// whose end returns to its start — which covers self-closing rect/ellipse/circle/round-rect primitives,
+// `appendShapePolygon`, a manual return-to-start polyline, and a `drawPath` carrying either), so it is
+// stroke-span-aware: only geometry drawn under an active `lineStyle` reaches a centerline, so an
+// unstroked closed primitive never forces the fallback. Solid open strokes only; the backend's
+// explicit stroke-path-tessellation feature owns the closed-ring strip route.
+export function getShapeStrokeOutlineRegions(commands) {
+    if (hasNonSolidShapeStroke(commands))
+        return null;
+    const regions = [];
+    let centerline = null; // accumulated centerline for the active stroke span
+    let style = null;
+    let color = 0;
+    let alpha = 1;
+    let penX = 0;
+    let penY = 0;
+    let deferred = false; // a stroked span closed into a ring the direct-fill route can't express
+    const flush = () => {
+        if (style === null || centerline === null || centerline.commands.length === 0)
+            return;
+        if (isCenterlineClosed(centerline)) {
+            deferred = true;
+            return;
+        }
+        const outline = compactStrokePath(centerline, style);
+        if (outline.commands.length > 0)
+            regions.push({ path: outline, color, alpha });
+    };
+    let i = 0;
+    while (i < commands.length) {
+        const name = commands[i];
+        const argCount = commands[i + 1];
+        const a = i + 2;
+        i = a + argCount;
+        if (name === 'lineStyle') {
+            // A new stroke style ends the previous span's outline and opens a fresh centerline.
+            flush();
+            const thickness = commands[a];
+            if (thickness > 0) {
+                color = commands[a + 1];
+                alpha = commands[a + 2];
+                const caps = commands[a + 5];
+                const joints = commands[a + 6];
+                style = {
+                    width: thickness,
+                    // Shape's CapsStyle 'none' is Canvas/`strokeStyle`'s 'butt'; round/square pass through.
+                    cap: caps === 'none' ? 'butt' : caps,
+                    join: joints,
+                    miterLimit: commands[a + 7],
+                };
+                centerline = { commands: [], data: [], winding: 'nonZero' };
+            }
+            else {
+                style = null;
+                centerline = null;
+            }
+        }
+        else if (isShapeGeometryCommand(name)) {
+            if (centerline !== null) {
+                // A span whose first geometry is a lineTo/curve (no leading moveTo) begins from the current pen
+                // position, matching Canvas 2D stroking the running path.
+                if (centerline.commands.length === 0 && name !== 'moveTo') {
+                    centerline.commands.push(PathCommand.MOVE_TO);
+                    centerline.data.push(penX, penY);
+                }
+                appendShapeGeometryCommand(centerline, name, commands, a);
+            }
+            // Track the pen off the polyline verbs so the next span can seed from it (primitives self-start).
+            if (name === 'moveTo' || name === 'lineTo') {
+                penX = commands[a];
+                penY = commands[a + 1];
+            }
+            else if (name === 'curveTo') {
+                penX = commands[a + 2];
+                penY = commands[a + 3];
+            }
+            else if (name === 'cubicCurveTo') {
+                penX = commands[a + 4];
+                penY = commands[a + 5];
+            }
+        }
+        // Fill-style + other non-geometry commands do not affect the stroke centerline.
+    }
+    flush();
+    return deferred ? null : regions;
+}
+// True if the stream uses a stroke the GPU outline path cannot express (a gradient or bitmap stroke),
+// so the caller must fall back to the raster path. A solid `lineStyle` is expressible.
+function hasNonSolidShapeStroke(commands) {
+    let i = 0;
+    while (i < commands.length) {
+        const name = commands[i];
+        if (name === 'lineGradientStyle' || name === 'lineTextureStyle')
+            return true;
+        i += 2 + commands[i + 1];
+    }
+    return false;
+}
+// True if the centerline encloses a region — a CLOSE verb, or any subpath whose end returns to its
+// start (≥2 segments so it bounds area). Such a stroke offsets into a hollow ring the direct-fill
+// tessellator cannot express, so the caller defers the whole shape to raster. Walks the verb/data
+// stream with getPathCommandOperandCount so CLOSE/WIDE verbs keep the data cursor aligned.
+function isCenterlineClosed(path) {
+    const { commands, data } = path;
+    let d = 0;
+    let subStartX = 0;
+    let subStartY = 0;
+    let lastX = 0;
+    let lastY = 0;
+    let segments = 0;
+    const subpathReturnsToStart = () => segments >= 2 && Math.abs(lastX - subStartX) < CLOSE_EPSILON && Math.abs(lastY - subStartY) < CLOSE_EPSILON;
+    for (let c = 0; c < commands.length; c++) {
+        const verb = commands[c];
+        if (verb === PathCommand.CLOSE)
+            return true;
+        const n = getPathCommandOperandCount(verb);
+        if (verb === PathCommand.MOVE_TO || verb === PathCommand.WIDE_MOVE_TO) {
+            if (subpathReturnsToStart())
+                return true;
+            // A WIDE_MOVE_TO's real endpoint is its trailing (x,y) pair; MOVE_TO's is its only pair.
+            lastX = subStartX = data[d + n - 2];
+            lastY = subStartY = data[d + n - 1];
+            segments = 0;
+        }
+        else if (n >= 2) {
+            // The endpoint of LINE/CURVE/CUBIC/WIDE_LINE is its trailing (x,y) pair.
+            lastX = data[d + n - 2];
+            lastY = data[d + n - 1];
+            segments++;
+        }
+        d += n;
+    }
+    return subpathReturnsToStart();
+}
+function isShapeGeometryCommand(name) {
+    return (name === 'moveTo' ||
+        name === 'lineTo' ||
+        name === 'curveTo' ||
+        name === 'cubicCurveTo' ||
+        name === 'drawCircle' ||
+        name === 'drawEllipse' ||
+        name === 'drawRectangle' ||
+        name === 'drawRoundRectangle' ||
+        name === 'drawPath');
+}
+// Endpoint-coincidence tolerance for return-to-start closure. Authored primitives (rect/ellipse) and
+// polygons re-emit their start coordinate exactly, so this only absorbs trivial float noise.
+const CLOSE_EPSILON = 1e-6;
+//# sourceMappingURL=shapeStrokeOutline.js.map

package/dist/shapeStrokeOutline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shapeStrokeOutline.js","sourceRoot":"","sources":["../src/shapeStrokeOutline.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,8 @@
 {
   "name": "@flighthq/shape",
-  "version": "0.3.0-next.906.07cea63",
+  "version": "0.3.1-next.209.43ef1bc",
+  "author": "Joshua Granick and other contributors",
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/flighthq/flight.git",
@@ -36,15 +38,16 @@
     "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
   },
   "dependencies": {
-    "@flighthq/scene2d": "0.3.0-next.906.07cea63",
-    "@flighthq/geometry": "0.3.0-next.906.07cea63",
-    "@flighthq/node": "0.3.0-next.906.07cea63",
-    "@flighthq/path": "0.3.0-next.906.07cea63",
-    "@flighthq/types": "0.3.0-next.906.07cea63"
+    "@flighthq/animation": "0.3.1-next.209.43ef1bc",
+    "@flighthq/scene2d": "0.3.1-next.209.43ef1bc",
+    "@flighthq/geometry": "0.3.1-next.209.43ef1bc",
+    "@flighthq/node": "0.3.1-next.209.43ef1bc",
+    "@flighthq/path": "0.3.1-next.209.43ef1bc",
+    "@flighthq/types": "0.3.1-next.209.43ef1bc"
   },
   "devDependencies": {
     "typescript": "^5.3.0"
   },
-  "description": "Vector Shape display node: drawing commands, scale-9 shapes, and shape hit testing",
+  "description": "Vector Shape and MorphShape display nodes: retained commands, compound geometry and paint morphing, scale-9, and hit testing",
   "sideEffects": false
 }

package/src/compactStrokePath.test.ts

@@ -0,0 +1,31 @@
+import type { Path } from '@flighthq/types/contract';
+import { PathCommand } from '@flighthq/types/contract';
+
+import { compactStrokePath } from './compactStrokePath';
+
+describe('compactStrokePath', () => {
+  it('converts an open centerline into a closed fill outline', () => {
+    const centerline: Path = {
+      commands: [PathCommand.MOVE_TO, PathCommand.LINE_TO],
+      data: [0, 0, 20, 0],
+      winding: 'nonZero',
+    };
+
+    const outline = compactStrokePath(centerline, { cap: 'square', width: 4 });
+
+    expect(outline.commands[0]).toBe(PathCommand.MOVE_TO);
+    expect(outline.commands.at(-1)).toBe(PathCommand.CLOSE);
+    expect(outline.data).toContain(-2);
+    expect(outline.data).toContain(22);
+  });
+
+  it('returns an empty path for a centerline without a segment', () => {
+    const centerline: Path = {
+      commands: [PathCommand.MOVE_TO],
+      data: [0, 0],
+      winding: 'nonZero',
+    };
+
+    expect(compactStrokePath(centerline, { width: 4 }).commands).toEqual([]);
+  });
+});

package/src/explainMorphShapeGradientEndpoints.test.ts

@@ -0,0 +1,47 @@
+import {
+  explainMorphShapeGradientEndpoints,
+  getMorphShapeGradientEndpointIssue,
+} from './explainMorphShapeGradientEndpoints';
+
+describe('explainMorphShapeGradientEndpoints', () => {
+  it('reports compatible equal-length gradient stops', () => {
+    expect(
+      explainMorphShapeGradientEndpoints(
+        { alphas: [1], colors: [0], ratios: [0] },
+        { alphas: [1], colors: [0xffffff], ratios: [255] },
+      ),
+    ).toStrictEqual({ endStopCount: 1, reason: 'ok', startStopCount: 1, supported: true });
+  });
+
+  it.each([
+    [{ alphas: [], colors: [], ratios: [] }, { alphas: [], colors: [], ratios: [] }, 'empty-gradient'],
+    [
+      { alphas: [], colors: [0], ratios: [0] },
+      { alphas: [1], colors: [0], ratios: [0] },
+      'start-stop-component-count-mismatch',
+    ],
+    [
+      { alphas: [1], colors: [0], ratios: [0] },
+      { alphas: [], colors: [0], ratios: [0] },
+      'end-stop-component-count-mismatch',
+    ],
+    [
+      { alphas: [1], colors: [0], ratios: [0] },
+      { alphas: [1, 1], colors: [0, 1], ratios: [0, 255] },
+      'stop-count-mismatch',
+    ],
+  ])('reports incompatible topology as %s', (start, end, reason) => {
+    expect(explainMorphShapeGradientEndpoints(start, end)).toMatchObject({ reason, supported: false });
+  });
+});
+
+describe('getMorphShapeGradientEndpointIssue', () => {
+  it('provides a string-free compatibility seam for paint construction', () => {
+    expect(
+      getMorphShapeGradientEndpointIssue(
+        { alphas: [1], colors: [0], ratios: [0] },
+        { alphas: [1], colors: [0xffffff], ratios: [255] },
+      ),
+    ).toBe(0);
+  });
+});

package/src/explainShapeTessellation.test.ts

@@ -0,0 +1,65 @@
+import { explainShapeTessellation } from './explainShapeTessellation';
+import { createShape } from './shape';
+import {
+  appendShapeBeginFill,
+  appendShapeBeginGradientFill,
+  appendShapeEndFill,
+  appendShapeLineStyle,
+  appendShapeLineTo,
+  appendShapeMoveTo,
+  appendShapeRectangle,
+} from './shapeCommands';
+
+describe('explainShapeTessellation', () => {
+  it('reports a solid fill as tessellating at any alpha, opaque or not', () => {
+    // Alpha is carried on the region, so it never moves a shape off the mesh lane — worth pinning,
+    // because a translucent shape that fails to draw invites blaming the alpha.
+    for (const alpha of [1, 0.25, 0]) {
+      const shape = createShape();
+      appendShapeBeginFill(shape, 0xff0000, alpha);
+      appendShapeRectangle(shape, 0, 0, 50, 50);
+      appendShapeEndFill(shape);
+
+      expect(explainShapeTessellation(shape.data.commands)).toEqual({ blockedBy: 'none', status: 'tessellates' });
+    }
+  });
+
+  it('reports an open stroke as tessellating', () => {
+    const shape = createShape();
+    appendShapeLineStyle(shape, 2, 0x000000);
+    appendShapeMoveTo(shape, 0, 0);
+    appendShapeLineTo(shape, 50, 0);
+
+    expect(explainShapeTessellation(shape.data.commands)).toEqual({ blockedBy: 'none', status: 'tessellates' });
+  });
+
+  it('names the closed stroke that the default lane declines, and clears it for the opt-in lane', () => {
+    const shape = createShape();
+    appendShapeBeginFill(shape, 0xff0000, 1);
+    appendShapeLineStyle(shape, 2, 0x000000);
+    appendShapeRectangle(shape, 0, 0, 50, 50);
+    appendShapeEndFill(shape);
+
+    expect(explainShapeTessellation(shape.data.commands)).toEqual({
+      blockedBy: 'stroke-outline',
+      status: 'needs-rasterizer',
+    });
+    expect(explainShapeTessellation(shape.data.commands, true)).toEqual({
+      blockedBy: 'none',
+      status: 'tessellates',
+    });
+  });
+
+  it('names a non-solid fill, which no stroke lane setting can rescue', () => {
+    const shape = createShape();
+    appendShapeBeginGradientFill(shape, 'linear', [0xff0000, 0x0000ff], [1, 1], [0, 255]);
+    appendShapeRectangle(shape, 0, 0, 50, 50);
+    appendShapeEndFill(shape);
+
+    expect(explainShapeTessellation(shape.data.commands)).toEqual({
+      blockedBy: 'non-solid-fill',
+      status: 'needs-rasterizer',
+    });
+    expect(explainShapeTessellation(shape.data.commands, true).status).toBe('needs-rasterizer');
+  });
+});

package/src/morphShape.test.ts

@@ -0,0 +1,207 @@
+import { createRectangle } from '@flighthq/geometry/contract';
+import { getNodeLocalContentRevision } from '@flighthq/node/contract';
+import { appendPathLineTo, appendPathMoveTo, createPath, createPathMorph } from '@flighthq/path/contract';
+import type {
+  MorphShapePaintBinding,
+  MorphShapePathBinding,
+  PathMorph,
+  ShapeCommandToken,
+} from '@flighthq/types/contract';
+import { MorphShapeKind } from '@flighthq/types/contract';
+
+import {
+  appendMorphShapePath,
+  createMorphShape,
+  createMorphShapeData,
+  createMorphShapeRuntime,
+  getMorphShapeRuntime,
+  setMorphShapeProgress,
+} from './morphShape';
+import { getShapeBounds } from './shape';
+import { appendShapeBeginFill, appendShapeEndFill } from './shapeCommands';
+
+describe('appendMorphShapePath', () => {
+  it('inserts the live path between ordinary Shape styling commands', () => {
+    const shape = createMorphShape(createTestMorph());
+    appendShapeBeginFill(shape, 0x336699, 0.75);
+
+    appendMorphShapePath(shape);
+    appendShapeEndFill(shape);
+
+    expect(shape.data.commands).toStrictEqual([
+      'beginFill',
+      2,
+      0x336699,
+      0.75,
+      'drawPath',
+      3,
+      shape.data.path.commands,
+      shape.data.path.data,
+      'nonZero',
+      'endFill',
+      0,
+    ]);
+    expect(shape.data.commands[6]).toBe(shape.data.path.commands);
+    expect(shape.data.commands[7]).toBe(shape.data.path.data);
+  });
+
+  it('retains and reuses independent path morphs in one command stream', () => {
+    const shape = createMorphShape(createTestMorph());
+    const secondMorph = createTestMorph(100);
+    const primaryPath = appendMorphShapePath(shape);
+    const secondPath = appendMorphShapePath(shape, secondMorph);
+    const repeatedSecondPath = appendMorphShapePath(shape, secondMorph);
+    const primaryCommands = primaryPath.commands;
+    const primaryData = primaryPath.data;
+    const secondCommands = secondPath.commands;
+    const secondData = secondPath.data;
+    const revision = getNodeLocalContentRevision(shape);
+
+    setMorphShapeProgress(shape, 0.5);
+
+    expect(shape.data.pathBindings).toHaveLength(2);
+    expect(repeatedSecondPath).toBe(secondPath);
+    expect(primaryPath.commands).toBe(primaryCommands);
+    expect(primaryPath.data).toBe(primaryData);
+    expect(secondPath.commands).toBe(secondCommands);
+    expect(secondPath.data).toBe(secondData);
+    expect(primaryPath.data.slice(0, 2)).toStrictEqual([5, 10]);
+    expect(secondPath.data.slice(0, 2)).toStrictEqual([105, 110]);
+    expect(getNodeLocalContentRevision(shape)).toBe(revision + 1);
+  });
+});
+
+describe('createMorphShape', () => {
+  it('creates a distinct MorphShape over the prepared start sample', () => {
+    const morph = createTestMorph();
+
+    const shape = createMorphShape(morph);
+
+    expect(shape.kind).toBe(MorphShapeKind);
+    expect(shape.data.commands).toStrictEqual([]);
+    expect(shape.data.morph).toBe(morph);
+    expect(shape.data.pathBindings).toStrictEqual([{ morph, path: shape.data.path }]);
+    expect(shape.data.paintBindings).toStrictEqual([]);
+    expect(shape.data.path.commands).toStrictEqual(morph.commands);
+    expect(shape.data.path.data).toStrictEqual(morph.startData);
+    expect(shape.data.progress).toBe(0);
+  });
+
+  it('uses initial progress and a provided command buffer', () => {
+    const commands: ShapeCommandToken[] = ['beginFill', 2, 0xff0000, 1];
+
+    const shape = createMorphShape(createTestMorph(), { data: { commands, progress: 0.5 } });
+
+    expect(shape.data.commands).toBe(commands);
+    expect(shape.data.path.data).toStrictEqual([5, 10, 10, 10, 15, 10, 20, 10]);
+    expect(shape.data.progress).toBe(0.5);
+  });
+
+  it('owns a distinct sampled path for each retained shape', () => {
+    const morph = createTestMorph();
+
+    const a = createMorphShape(morph);
+    const b = createMorphShape(morph);
+
+    expect(a).not.toBe(b);
+    expect(a.data.path).not.toBe(b.data.path);
+    expect(a.data.path.commands).not.toBe(b.data.path.commands);
+    expect(a.data.path.data).not.toBe(b.data.path.data);
+  });
+});
+
+describe('createMorphShapeData', () => {
+  it('owns its mutable binding registries without replacing retained values', () => {
+    const morph = createTestMorph();
+    const paintBindings: MorphShapePaintBinding[] = [];
+    const pathBindings: MorphShapePathBinding[] = [];
+
+    const data = createMorphShapeData(morph, { paintBindings, pathBindings });
+
+    expect(data.paintBindings).not.toBe(paintBindings);
+    expect(data.pathBindings).not.toBe(pathBindings);
+    expect(paintBindings).toStrictEqual([]);
+    expect(pathBindings).toStrictEqual([]);
+    expect(data.pathBindings).toStrictEqual([{ morph, path: data.path }]);
+  });
+
+  it('samples the requested initial endpoint exactly', () => {
+    const morph = createTestMorph();
+
+    const data = createMorphShapeData(morph, { progress: 1 });
+
+    expect(data.path.data).toStrictEqual(morph.endData);
+  });
+});
+
+describe('createMorphShapeRuntime', () => {
+  it('creates the standard Shape bounds runtime', () => {
+    expect(createMorphShapeRuntime().computeLocalBoundsRectangle).toBeTypeOf('function');
+  });
+});
+
+describe('getMorphShapeRuntime', () => {
+  it('returns the runtime attached to the retained shape', () => {
+    expect(getMorphShapeRuntime(createMorphShape(createTestMorph()))).not.toBeNull();
+  });
+});
+
+describe('setMorphShapeProgress', () => {
+  it('does not invalidate or resample unchanged progress', () => {
+    const shape = createMorphShape(createTestMorph());
+    const revision = getNodeLocalContentRevision(shape);
+    const data = shape.data.path.data.slice();
+
+    setMorphShapeProgress(shape, 0);
+
+    expect(shape.data.path.data).toStrictEqual(data);
+    expect(getNodeLocalContentRevision(shape)).toBe(revision);
+  });
+
+  it('resamples stable buffers, stores progress, and invalidates content', () => {
+    const shape = createMorphShape(createTestMorph());
+    appendMorphShapePath(shape);
+    const commands = shape.data.path.commands;
+    const data = shape.data.path.data;
+    const revision = getNodeLocalContentRevision(shape);
+
+    setMorphShapeProgress(shape, 0.5);
+
+    expect(shape.data.progress).toBe(0.5);
+    expect(shape.data.path.commands).toBe(commands);
+    expect(shape.data.path.data).toBe(data);
+    expect(shape.data.path.data).toStrictEqual([5, 10, 10, 10, 15, 10, 20, 10]);
+    expect(getNodeLocalContentRevision(shape)).toBe(revision + 1);
+  });
+
+  it('updates the bounds observed through the ordinary Shape runtime', () => {
+    const shape = createMorphShape(createTestMorph());
+    appendMorphShapePath(shape);
+    const bounds = createRectangle();
+    getShapeBounds(bounds, shape);
+    expect(bounds).toMatchObject({ x: 0, y: 0, width: 10, height: 0 });
+
+    setMorphShapeProgress(shape, 1);
+    getShapeBounds(bounds, shape);
+
+    expect(bounds).toMatchObject({ x: 10, y: 20, width: 20, height: 0 });
+  });
+
+  it('preserves unclamped easing overshoot', () => {
+    const shape = createMorphShape(createTestMorph());
+
+    setMorphShapeProgress(shape, 1.5);
+
+    expect(shape.data.path.data.slice(0, 2)).toStrictEqual([15, 30]);
+  });
+});
+
+function createTestMorph(offset = 0): PathMorph {
+  const start = createPath();
+  appendPathMoveTo(start, offset, offset);
+  appendPathLineTo(start, offset + 10, offset);
+  const end = createPath();
+  appendPathMoveTo(end, offset + 10, offset + 20);
+  appendPathLineTo(end, offset + 30, offset + 20);
+  return createPathMorph(start, end)!;
+}