@flighthq/path 0.3.0-next.906.07cea63 → 0.3.0

package/src/explainStrokePathTessellation.test.ts

@@ -0,0 +1,39 @@
+import { explainStrokePathTessellation } from './explainStrokePathTessellation';
+import { appendPathClose, appendPathLineTo, appendPathMoveTo, appendPathRectangle, createPath } from './path';
+
+describe('explainStrokePathTessellation', () => {
+  it('reports a supported simple closed ring', () => {
+    const path = createPath();
+    appendPathRectangle(path, 0, 0, 100, 50);
+    expect(explainStrokePathTessellation(path, { width: 10 })).toEqual({
+      reason: 'ok',
+      subpath: null,
+      supported: true,
+    });
+  });
+
+  it('identifies the self-intersecting subpath behind a null mesh', () => {
+    const path = createPath();
+    appendPathMoveTo(path, 0, 0);
+    appendPathLineTo(path, 40, 40);
+    appendPathLineTo(path, 0, 40);
+    appendPathLineTo(path, 40, 0);
+    appendPathClose(path);
+    expect(explainStrokePathTessellation(path, { width: 8 })).toEqual({
+      reason: 'self-intersecting-centerline',
+      subpath: 0,
+      supported: false,
+    });
+  });
+
+  it('reports invalid style input without throwing', () => {
+    const path = createPath();
+    appendPathMoveTo(path, 0, 0);
+    appendPathLineTo(path, 10, 0);
+    expect(explainStrokePathTessellation(path, { width: 0 })).toEqual({
+      reason: 'invalid-style',
+      subpath: null,
+      supported: false,
+    });
+  });
+});

package/src/pathMorph.test.ts

@@ -0,0 +1,290 @@
+import { PathCommand } from '@flighthq/types/contract';
+
+import {
+  appendPathClose,
+  appendPathCircle,
+  appendPathCubicCurveTo,
+  appendPathCurveTo,
+  appendPathLineTo,
+  appendPathMoveTo,
+  appendPathRectangle,
+  createPath,
+} from './path';
+import { createPathMorph, samplePathMorph } from './pathMorph';
+
+describe('createPathMorph', () => {
+  it('normalizes different line and quadratic verbs to one cubic command stream', () => {
+    const start = createPath();
+    appendPathMoveTo(start, 0, 0);
+    appendPathLineTo(start, 6, 0);
+    const end = createPath();
+    appendPathMoveTo(end, 2, 2);
+    appendPathCurveTo(end, 5, 8, 8, 2);
+
+    const morph = createPathMorph(start, end)!;
+
+    expect(morph.commands).toStrictEqual([PathCommand.MOVE_TO, PathCommand.CUBIC_CURVE_TO]);
+    expect(morph.startData).toStrictEqual([0, 0, 2, 0, 4, 0, 6, 0]);
+    expect(morph.endData).toStrictEqual([2, 2, 4, 6, 6, 6, 8, 2]);
+  });
+
+  it('preserves authored cubic control points', () => {
+    const start = createPath();
+    appendPathMoveTo(start, 0, 0);
+    appendPathLineTo(start, 9, 0);
+    const end = createPath();
+    appendPathMoveTo(end, 1, 2);
+    appendPathCubicCurveTo(end, 3, 4, 6, 8, 10, 12);
+
+    const morph = createPathMorph(start, end)!;
+
+    expect(morph.endData).toStrictEqual([1, 2, 3, 4, 6, 8, 10, 12]);
+  });
+
+  it('subdivides the lower segment count without changing its endpoint geometry', () => {
+    const start = createPath();
+    appendPathMoveTo(start, 0, 0);
+    appendPathLineTo(start, 10, 0);
+    const end = createPath();
+    appendPathMoveTo(end, 0, 0);
+    appendPathLineTo(end, 5, 0);
+    appendPathLineTo(end, 10, 0);
+
+    const morph = createPathMorph(start, end)!;
+
+    expect(morph.commands).toStrictEqual([PathCommand.MOVE_TO, PathCommand.CUBIC_CURVE_TO, PathCommand.CUBIC_CURVE_TO]);
+    for (let i = 0; i < morph.startData.length; i++) {
+      expect(morph.startData[i]).toBeCloseTo(morph.endData[i]);
+    }
+    expect(morph.startData.slice(-2)).toStrictEqual([10, 0]);
+  });
+
+  it('aligns equivalent closed contours authored from different starting vertices', () => {
+    const start = createPath();
+    appendPathRectangle(start, 0, 0, 10, 10);
+    const end = createPath();
+    appendPathMoveTo(end, 10, 0);
+    appendPathLineTo(end, 10, 10);
+    appendPathLineTo(end, 0, 10);
+    appendPathLineTo(end, 0, 0);
+    appendPathClose(end);
+
+    const morph = createPathMorph(start, end)!;
+
+    expect(morph.startData).toEqual(morph.endData);
+    expect(morph.commands[morph.commands.length - 1]).toBe(PathCommand.CLOSE);
+  });
+
+  it('prepares a closed line rectangle against a closed cubic circle', () => {
+    const start = createPath();
+    appendPathRectangle(start, -10, -10, 20, 20);
+    const end = createPath();
+    appendPathCircle(end, 0, 0, 10);
+
+    const morph = createPathMorph(start, end)!;
+
+    expect(morph.commands).toStrictEqual([
+      PathCommand.MOVE_TO,
+      PathCommand.CUBIC_CURVE_TO,
+      PathCommand.CUBIC_CURVE_TO,
+      PathCommand.CUBIC_CURVE_TO,
+      PathCommand.CUBIC_CURVE_TO,
+      PathCommand.CLOSE,
+    ]);
+  });
+
+  it('normalizes wide move and line commands without retaining their dummy coordinates', () => {
+    const start = createPath();
+    start.commands.push(PathCommand.WIDE_MOVE_TO, PathCommand.WIDE_LINE_TO);
+    start.data.push(99, 98, 1, 2, 97, 96, 7, 8);
+    const end = createPath();
+    appendPathMoveTo(end, 1, 2);
+    appendPathLineTo(end, 7, 8);
+
+    const morph = createPathMorph(start, end)!;
+
+    expect(morph.startData).toEqual(morph.endData);
+    expect(morph.startData).toStrictEqual([1, 2, 3, 4, 5, 6, 7, 8]);
+  });
+
+  it('expands a point contour into degenerate cubics when the other endpoint has segments', () => {
+    const start = createPath();
+    appendPathMoveTo(start, 3, 4);
+    const end = createPath();
+    appendPathMoveTo(end, 0, 0);
+    appendPathLineTo(end, 10, 0);
+
+    const morph = createPathMorph(start, end)!;
+
+    expect(morph.startData).toStrictEqual([3, 4, 3, 4, 3, 4, 3, 4]);
+  });
+
+  it('expands a closed point contour without inventing an orientation', () => {
+    const start = createPath();
+    appendPathMoveTo(start, 3, 4);
+    appendPathClose(start);
+    const end = createPath();
+    appendPathRectangle(end, 0, 0, 10, 10);
+
+    const morph = createPathMorph(start, end)!;
+
+    expect(morph.commands).toStrictEqual([
+      PathCommand.MOVE_TO,
+      PathCommand.CUBIC_CURVE_TO,
+      PathCommand.CUBIC_CURVE_TO,
+      PathCommand.CUBIC_CURVE_TO,
+      PathCommand.CUBIC_CURVE_TO,
+      PathCommand.CLOSE,
+    ]);
+    expect(morph.startData.every((value, index) => value === (index % 2 === 0 ? 3 : 4))).toBe(true);
+  });
+
+  it('does not mutate either endpoint', () => {
+    const start = createPath();
+    appendPathMoveTo(start, 0, 0);
+    appendPathLineTo(start, 10, 0);
+    const end = createPath();
+    appendPathMoveTo(end, 0, 0);
+    appendPathLineTo(end, 5, 5);
+    appendPathLineTo(end, 10, 0);
+    const startCommands = start.commands.slice();
+    const startData = start.data.slice();
+    const endCommands = end.commands.slice();
+    const endData = end.data.slice();
+
+    createPathMorph(start, end);
+
+    expect(start.commands).toStrictEqual(startCommands);
+    expect(start.data).toStrictEqual(startData);
+    expect(end.commands).toStrictEqual(endCommands);
+    expect(end.data).toStrictEqual(endData);
+  });
+
+  it('returns null for paths with incompatible topology', () => {
+    const start = createPath('nonZero');
+    const end = createPath('evenOdd');
+    expect(createPathMorph(start, end)).toBeNull();
+  });
+
+  it('normalizes a consistently reversed closed endpoint', () => {
+    const start = createPath();
+    appendPathRectangle(start, 0, 0, 10, 10);
+    const end = createPath();
+    appendPathMoveTo(end, 0, 0);
+    appendPathLineTo(end, 0, 10);
+    appendPathLineTo(end, 10, 10);
+    appendPathLineTo(end, 10, 0);
+    appendPathClose(end);
+
+    const morph = createPathMorph(start, end)!;
+
+    for (let i = 0; i < morph.startData.length; i++) {
+      expect(morph.startData[i]).toBeCloseTo(morph.endData[i]);
+    }
+  });
+
+  it('normalizes opposing contours independently under even-odd winding', () => {
+    const start = createPath('evenOdd');
+    appendPathRectangle(start, 0, 0, 20, 20);
+    appendPathRectangle(start, 5, 5, 10, 10);
+    const end = createPath('evenOdd');
+    appendPathRectangle(end, 0, 0, 20, 20);
+    appendPathMoveTo(end, 5, 5);
+    appendPathLineTo(end, 5, 15);
+    appendPathLineTo(end, 15, 15);
+    appendPathLineTo(end, 15, 5);
+    appendPathClose(end);
+
+    const morph = createPathMorph(start, end)!;
+
+    for (let i = 0; i < morph.startData.length; i++) {
+      expect(morph.startData[i]).toBeCloseTo(morph.endData[i]);
+    }
+  });
+});
+
+describe('samplePathMorph', () => {
+  it('samples the prepared endpoints at zero and one', () => {
+    const start = createPath();
+    appendPathMoveTo(start, 0, 2);
+    appendPathLineTo(start, 6, 8);
+    const end = createPath();
+    appendPathMoveTo(end, 10, 12);
+    appendPathCurveTo(end, 14, 20, 18, 16);
+    const morph = createPathMorph(start, end)!;
+    const out = createPath();
+
+    samplePathMorph(out, morph, 0);
+    expect(out.data).toStrictEqual(morph.startData);
+    samplePathMorph(out, morph, 1);
+    expect(out.data).toStrictEqual(morph.endData);
+  });
+
+  it('copies endpoint coordinates exactly instead of reconstructing them arithmetically', () => {
+    const start = createPath();
+    appendPathMoveTo(start, -255_815_156_688.713_68, 12);
+    const end = createPath();
+    appendPathMoveTo(end, 0.000_030_389_885_488_608_44, -24);
+    const morph = createPathMorph(start, end)!;
+    const out = createPath();
+
+    samplePathMorph(out, morph, 0);
+    expect(out.data).toStrictEqual(morph.startData);
+    samplePathMorph(out, morph, 1);
+    expect(out.data).toStrictEqual(morph.endData);
+  });
+
+  it('writes the midpoint and winding into an existing path', () => {
+    const start = createPath('evenOdd');
+    appendPathMoveTo(start, 0, 0);
+    appendPathLineTo(start, 6, 0);
+    const end = createPath('evenOdd');
+    appendPathMoveTo(end, 2, 2);
+    appendPathCurveTo(end, 5, 8, 8, 2);
+    const out = createPath('nonZero');
+
+    samplePathMorph(out, createPathMorph(start, end)!, 0.5);
+
+    expect(out.commands).toStrictEqual([PathCommand.MOVE_TO, PathCommand.CUBIC_CURVE_TO]);
+    expect(out.data).toStrictEqual([1, 1, 3, 3, 5, 3, 7, 1]);
+    expect(out.winding).toBe('evenOdd');
+  });
+
+  it('reuses the output command and data arrays across samples', () => {
+    const start = createPath();
+    appendPathMoveTo(start, 0, 0);
+    appendPathLineTo(start, 10, 0);
+    const end = createPath();
+    appendPathMoveTo(end, 10, 10);
+    appendPathLineTo(end, 20, 10);
+    const morph = createPathMorph(start, end)!;
+    const out = createPath();
+    const commands = out.commands;
+    const data = out.data;
+
+    samplePathMorph(out, morph, 0.25);
+    samplePathMorph(out, morph, 0.75);
+
+    expect(out.commands).toBe(commands);
+    expect(out.data).toBe(data);
+  });
+
+  it('permits progress outside zero to one for easing overshoot', () => {
+    const start = createPath();
+    appendPathMoveTo(start, 0, 0);
+    const end = createPath();
+    appendPathMoveTo(end, 10, 20);
+    const out = createPath();
+
+    samplePathMorph(out, createPathMorph(start, end)!, 1.5);
+
+    expect(out.data).toStrictEqual([15, 30]);
+  });
+
+  it('samples an empty path pair', () => {
+    const out = createPath();
+    samplePathMorph(out, createPathMorph(createPath(), createPath())!, 0.5);
+    expect(out.commands).toStrictEqual([]);
+    expect(out.data).toStrictEqual([]);
+  });
+});

package/src/pathMorphGeometry.test.ts

@@ -0,0 +1,18 @@
+import { appendPathLineTo, appendPathMoveTo, createPath } from './path';
+import { buildPathMorph, PathMorphIssueNone } from './pathMorphGeometry';
+
+describe('buildPathMorph', () => {
+  it('returns the prepared buffers with the internal success issue', () => {
+    const start = createPath();
+    appendPathMoveTo(start, 0, 0);
+    appendPathLineTo(start, 1, 0);
+    const end = createPath();
+    appendPathMoveTo(end, 0, 0);
+    appendPathLineTo(end, 2, 0);
+
+    const result = buildPathMorph(start, end);
+
+    expect(result.issue).toBe(PathMorphIssueNone);
+    expect(result.morph).not.toBeNull();
+  });
+});

package/src/strokePathGeometry.test.ts

@@ -0,0 +1,27 @@
+import { appendPathLineTo, appendPathMoveTo, appendPathRectangle, createPath } from './path';
+import {
+  buildStrokePathGeometry,
+  StrokePathTessellationIssueNone,
+  StrokePathTessellationIssueSelfIntersectingCenterline,
+} from './strokePathGeometry';
+
+describe('buildStrokePathGeometry', () => {
+  it('builds paired closed-ring sections and reports pathological centerlines', () => {
+    const rectangle = createPath();
+    appendPathRectangle(rectangle, 0, 0, 100, 50);
+    const valid = buildStrokePathGeometry(rectangle, { width: 10 }, 0.25);
+    expect(valid.issue).toBe(StrokePathTessellationIssueNone);
+    expect(valid.pieces).toHaveLength(1);
+    expect(valid.pieces[0].closed).toBe(true);
+    expect(valid.pieces[0].left.length).toBe(valid.pieces[0].right.length);
+
+    const crossing = createPath();
+    appendPathMoveTo(crossing, 0, 0);
+    appendPathLineTo(crossing, 40, 40);
+    appendPathLineTo(crossing, 0, 40);
+    appendPathLineTo(crossing, 40, 0);
+    const invalid = buildStrokePathGeometry(crossing, { width: 10 }, 0.25);
+    expect(invalid.issue).toBe(StrokePathTessellationIssueSelfIntersectingCenterline);
+    expect(invalid.issueSubpath).toBe(0);
+  });
+});

package/src/tessellateStrokePath.test.ts

@@ -0,0 +1,91 @@
+import { appendPathClose, appendPathLineTo, appendPathMoveTo, appendPathRectangle, createPath } from './path';
+import { tessellateStrokePath } from './tessellateStrokePath';
+
+describe('tessellateStrokePath', () => {
+  it('tessellates an open butt-capped line without overlapping triangles', () => {
+    const path = createPath();
+    appendPathMoveTo(path, 0, 0);
+    appendPathLineTo(path, 100, 0);
+    const mesh = tessellateStrokePath(path, { cap: 'butt', width: 10 });
+    expect(mesh).not.toBeNull();
+    expect(mesh!.indices.length).toBe(6);
+    expect(getMeshArea(mesh!)).toBeCloseTo(1000, 6);
+  });
+
+  it('tessellates a closed rectangle as a hollow ring', () => {
+    const path = createPath();
+    appendPathRectangle(path, 0, 0, 100, 50);
+    const mesh = tessellateStrokePath(path, { join: 'miter', width: 10 });
+    expect(mesh).not.toBeNull();
+    // Outer 110×60 minus inner 90×40 = 3000. Filling both contours would be 10200 instead.
+    expect(getMeshArea(mesh!)).toBeCloseTo(3000, 6);
+  });
+
+  it('normalizes an explicit CLOSE and a return-to-start centerline to the same ring', () => {
+    const closed = createPath();
+    appendPathRectangle(closed, 0, 0, 100, 50);
+    const returned = createPath();
+    appendPathMoveTo(returned, 0, 0);
+    appendPathLineTo(returned, 100, 0);
+    appendPathLineTo(returned, 100, 50);
+    appendPathLineTo(returned, 0, 50);
+    appendPathLineTo(returned, 0, 0);
+    expect(tessellateStrokePath(closed, { width: 10 })).toEqual(tessellateStrokePath(returned, { width: 10 }));
+  });
+
+  it('uses the same round-join sampling tolerance as stroke outlines', () => {
+    const path = createPath();
+    appendPathRectangle(path, 0, 0, 100, 50);
+    const fine = tessellateStrokePath(path, { join: 'round', width: 10 }, 0.1);
+    const coarse = tessellateStrokePath(path, { join: 'round', width: 10 }, 5);
+    expect(fine).not.toBeNull();
+    expect(coarse).not.toBeNull();
+    expect(fine!.vertices.length).toBeGreaterThan(coarse!.vertices.length);
+  });
+
+  it('turns a dashed closed path into independently capped open stroke pieces', () => {
+    const path = createPath();
+    appendPathRectangle(path, 0, 0, 100, 50);
+    const mesh = tessellateStrokePath(path, { cap: 'round', dash: [20, 10], width: 6 });
+    expect(mesh).not.toBeNull();
+    expect(mesh!.indices.length).toBeGreaterThan(6);
+  });
+
+  it('returns null for a self-intersecting centerline', () => {
+    const path = bowTie();
+    expect(tessellateStrokePath(path, { width: 8 })).toBeNull();
+  });
+
+  it('returns null for invalid stroke dimensions instead of emitting non-finite geometry', () => {
+    const path = createPath();
+    appendPathMoveTo(path, 0, 0);
+    appendPathLineTo(path, 10, 0);
+    expect(tessellateStrokePath(path, { width: 0 })).toBeNull();
+    expect(tessellateStrokePath(path, { width: Number.NaN })).toBeNull();
+  });
+});
+
+function bowTie() {
+  const path = createPath();
+  appendPathMoveTo(path, 0, 0);
+  appendPathLineTo(path, 40, 40);
+  appendPathLineTo(path, 0, 40);
+  appendPathLineTo(path, 40, 0);
+  appendPathClose(path);
+  return path;
+}
+
+function getMeshArea(mesh: { indices: readonly number[]; vertices: readonly number[] }): number {
+  let area = 0;
+  for (let i = 0; i < mesh.indices.length; i += 3) {
+    const a = mesh.indices[i] * 2;
+    const b = mesh.indices[i + 1] * 2;
+    const c = mesh.indices[i + 2] * 2;
+    area +=
+      Math.abs(
+        (mesh.vertices[b] - mesh.vertices[a]) * (mesh.vertices[c + 1] - mesh.vertices[a + 1]) -
+          (mesh.vertices[b + 1] - mesh.vertices[a + 1]) * (mesh.vertices[c] - mesh.vertices[a]),
+      ) / 2;
+  }
+  return area;
+}