@viewscript/renderer 0.1.0-202605140639

package/dist/rasterizer/__tests__/error-distribution.test.js

@@ -0,0 +1,322 @@
+/**
+ * Unit Tests for Subpixel Error Distribution
+ *
+ * These tests verify the Largest Remainder Method implementation
+ * guarantees spatial closure (no gaps, no overflow).
+ */
+import { describe, it, expect } from 'vitest';
+import { distributeWithLargestRemainder, applyErrorDistribution, } from '../error-distribution';
+describe('Largest Remainder Method', () => {
+    /**
+     * CRITICAL TEST: Architect's Decision #2
+     *
+     * "幅100pxのコンテナ内に、幅33.333...pxの要素が3つ、
+     *  隙間なく隣接して配置される"
+     *
+     * This is the canonical case that motivated error distribution.
+     */
+    it('distributes 100px among 3 equal children (33.333...px each) without gaps', () => {
+        // Arrange
+        const group = {
+            parentId: 1,
+            childIds: [10, 11, 12],
+            axis: 'horizontal',
+            parentDimension: 100,
+            childDimensions: new Map([
+                [10, 100 / 3], // 33.333...
+                [11, 100 / 3], // 33.333...
+                [12, 100 / 3], // 33.333...
+            ]),
+        };
+        // Act
+        const result = distributeWithLargestRemainder(group);
+        // Assert: Sum must equal parent exactly
+        expect(result.totalPixels).toBe(100);
+        expect(result.isExact).toBe(true);
+        // Assert: Each child gets 33 or 34 pixels
+        const pixels = result.dimensions.map(d => d.pixels);
+        expect(pixels.every(p => p === 33 || p === 34)).toBe(true);
+        // Assert: Exactly one child gets the extra pixel
+        const count34 = pixels.filter(p => p === 34).length;
+        const count33 = pixels.filter(p => p === 33).length;
+        expect(count34).toBe(1);
+        expect(count33).toBe(2);
+        // Assert: Sum is exactly 100 (33 + 33 + 34 = 100)
+        expect(pixels.reduce((a, b) => a + b, 0)).toBe(100);
+        // Assert: Distribution is [34, 33, 33] (leftmost gets extra due to tie-break)
+        expect(pixels).toEqual([34, 33, 33]);
+    });
+    it('handles exact division (no remainder)', () => {
+        // Arrange: 100px / 4 = 25px exactly
+        const group = {
+            parentId: 1,
+            childIds: [10, 11, 12, 13],
+            axis: 'horizontal',
+            parentDimension: 100,
+            childDimensions: new Map([
+                [10, 25],
+                [11, 25],
+                [12, 25],
+                [13, 25],
+            ]),
+        };
+        // Act
+        const result = distributeWithLargestRemainder(group);
+        // Assert
+        expect(result.totalPixels).toBe(100);
+        expect(result.isExact).toBe(true);
+        expect(result.dimensions.map(d => d.pixels)).toEqual([25, 25, 25, 25]);
+    });
+    it('distributes multiple extra pixels by remainder priority', () => {
+        // Arrange: 100px for [40.9, 30.8, 28.3]
+        // floors: [40, 30, 28] = 98
+        // remainders: [0.9, 0.8, 0.3]
+        // shortfall: 2px
+        // Extra pixels go to: 40.9 → 41, 30.8 → 31
+        const group = {
+            parentId: 1,
+            childIds: [10, 11, 12],
+            axis: 'horizontal',
+            parentDimension: 100,
+            childDimensions: new Map([
+                [10, 40.9],
+                [11, 30.8],
+                [12, 28.3],
+            ]),
+        };
+        // Act
+        const result = distributeWithLargestRemainder(group);
+        // Assert
+        expect(result.totalPixels).toBe(100);
+        expect(result.isExact).toBe(true);
+        expect(result.dimensions.map(d => d.pixels)).toEqual([41, 31, 28]);
+    });
+    it('handles single child (trivial case)', () => {
+        const group = {
+            parentId: 1,
+            childIds: [10],
+            axis: 'horizontal',
+            parentDimension: 100,
+            childDimensions: new Map([[10, 100]]),
+        };
+        const result = distributeWithLargestRemainder(group);
+        expect(result.totalPixels).toBe(100);
+        expect(result.dimensions[0].pixels).toBe(100);
+    });
+    it('handles empty children', () => {
+        const group = {
+            parentId: 1,
+            childIds: [],
+            axis: 'horizontal',
+            parentDimension: 100,
+            childDimensions: new Map(),
+        };
+        const result = distributeWithLargestRemainder(group);
+        expect(result.totalPixels).toBe(0);
+        expect(result.dimensions).toEqual([]);
+    });
+    it('ties are broken by layout order (leftmost first)', () => {
+        // Arrange: 10px for [3.5, 3.5] - equal remainders
+        // floors: [3, 3] = 6
+        // remainders: [0.5, 0.5] - TIE!
+        // shortfall: 4px (wait, that's wrong)
+        // Actually: 10 - 6 = 4... no, 3.5 + 3.5 = 7, not 10
+        // Let me fix: 7px for [3.5, 3.5]
+        const group = {
+            parentId: 1,
+            childIds: [10, 11],
+            axis: 'horizontal',
+            parentDimension: 7,
+            childDimensions: new Map([
+                [10, 3.5],
+                [11, 3.5],
+            ]),
+        };
+        // Act
+        const result = distributeWithLargestRemainder(group);
+        // Assert: shortfall is 1, so first element (leftmost) gets it
+        expect(result.totalPixels).toBe(7);
+        expect(result.dimensions.map(d => d.pixels)).toEqual([4, 3]);
+    });
+    it('handles vertical axis', () => {
+        const group = {
+            parentId: 1,
+            childIds: [10, 11, 12],
+            axis: 'vertical',
+            parentDimension: 100,
+            childDimensions: new Map([
+                [10, 100 / 3],
+                [11, 100 / 3],
+                [12, 100 / 3],
+            ]),
+        };
+        const result = distributeWithLargestRemainder(group);
+        expect(result.totalPixels).toBe(100);
+        expect(result.isExact).toBe(true);
+    });
+    it('records error for each element', () => {
+        const group = {
+            parentId: 1,
+            childIds: [10, 11, 12],
+            axis: 'horizontal',
+            parentDimension: 100,
+            childDimensions: new Map([
+                [10, 100 / 3], // ~33.333
+                [11, 100 / 3],
+                [12, 100 / 3],
+            ]),
+        };
+        const result = distributeWithLargestRemainder(group);
+        // First element: 34 - 33.333... = +0.666...
+        expect(result.dimensions[0].error).toBeCloseTo(0.6667, 3);
+        // Other elements: 33 - 33.333... = -0.333...
+        expect(result.dimensions[1].error).toBeCloseTo(-0.3333, 3);
+        expect(result.dimensions[2].error).toBeCloseTo(-0.3333, 3);
+    });
+});
+describe('applyErrorDistribution (Integration)', () => {
+    it('adjusts child bounds to fit parent exactly', () => {
+        // Arrange
+        const roundedBounds = new Map([
+            [1, { x: 0, y: 0, width: 100, height: 50 }], // Parent
+            [10, { x: 0, y: 0, width: 33, height: 50 }], // Child 1 (naive)
+            [11, { x: 33, y: 0, width: 33, height: 50 }], // Child 2
+            [12, { x: 66, y: 0, width: 33, height: 50 }], // Child 3
+            // Sum: 33 + 33 + 33 = 99 ← GAP!
+        ]);
+        const containments = [
+            {
+                parentId: 1,
+                childIds: [10, 11, 12],
+                axis: 'horizontal',
+            },
+        ];
+        // Act
+        const result = applyErrorDistribution(roundedBounds, containments);
+        // Assert: Children sum to parent width exactly
+        const child1 = result.get(10);
+        const child2 = result.get(11);
+        const child3 = result.get(12);
+        const totalWidth = child1.width + child2.width + child3.width;
+        expect(totalWidth).toBe(100);
+        // Assert: Children are contiguous (no gaps)
+        expect(child2.x).toBe(child1.x + child1.width);
+        expect(child3.x).toBe(child2.x + child2.width);
+    });
+    it('handles multiple containment constraints', () => {
+        const roundedBounds = new Map([
+            // Horizontal container
+            [1, { x: 0, y: 0, width: 100, height: 50 }],
+            [10, { x: 0, y: 0, width: 33, height: 50 }],
+            [11, { x: 33, y: 0, width: 33, height: 50 }],
+            [12, { x: 66, y: 0, width: 33, height: 50 }],
+            // Vertical container
+            [2, { x: 0, y: 50, width: 100, height: 100 }],
+            [20, { x: 0, y: 50, width: 100, height: 33 }],
+            [21, { x: 0, y: 83, width: 100, height: 33 }],
+            [22, { x: 0, y: 116, width: 100, height: 33 }],
+        ]);
+        const containments = [
+            { parentId: 1, childIds: [10, 11, 12], axis: 'horizontal' },
+            { parentId: 2, childIds: [20, 21, 22], axis: 'vertical' },
+        ];
+        const result = applyErrorDistribution(roundedBounds, containments);
+        // Horizontal container
+        const hTotal = result.get(10).width + result.get(11).width + result.get(12).width;
+        expect(hTotal).toBe(100);
+        // Vertical container
+        const vTotal = result.get(20).height + result.get(21).height + result.get(22).height;
+        expect(vTotal).toBe(100);
+    });
+});
+describe('Edge Cases', () => {
+    it('handles very small fractional differences', () => {
+        // 100px / 7 = 14.285714...
+        const group = {
+            parentId: 1,
+            childIds: [1, 2, 3, 4, 5, 6, 7],
+            axis: 'horizontal',
+            parentDimension: 100,
+            childDimensions: new Map([
+                [1, 100 / 7],
+                [2, 100 / 7],
+                [3, 100 / 7],
+                [4, 100 / 7],
+                [5, 100 / 7],
+                [6, 100 / 7],
+                [7, 100 / 7],
+            ]),
+        };
+        const result = distributeWithLargestRemainder(group);
+        expect(result.totalPixels).toBe(100);
+        expect(result.isExact).toBe(true);
+        // 7 * 14 = 98, shortfall = 2
+        // Two elements get 15px, five get 14px
+        const fifteens = result.dimensions.filter(d => d.pixels === 15).length;
+        const fourteens = result.dimensions.filter(d => d.pixels === 14).length;
+        expect(fifteens).toBe(2);
+        expect(fourteens).toBe(5);
+    });
+    it('handles zero-width children', () => {
+        const group = {
+            parentId: 1,
+            childIds: [10, 11],
+            axis: 'horizontal',
+            parentDimension: 100,
+            childDimensions: new Map([
+                [10, 100],
+                [11, 0],
+            ]),
+        };
+        const result = distributeWithLargestRemainder(group);
+        expect(result.totalPixels).toBe(100);
+        expect(result.dimensions[0].pixels).toBe(100);
+        expect(result.dimensions[1].pixels).toBe(0);
+    });
+    it('uses proportional scaling when children exceed parent', () => {
+        // Children sum to 150, but parent is only 100
+        const group = {
+            parentId: 1,
+            childIds: [10, 11, 12],
+            axis: 'horizontal',
+            parentDimension: 100,
+            childDimensions: new Map([
+                [10, 50],
+                [11, 50],
+                [12, 50],
+            ]),
+        };
+        const result = distributeWithLargestRemainder(group);
+        // Falls back to proportional: each gets ~33.33
+        expect(result.totalPixels).toBe(100);
+        expect(result.method).toBe('first-fit');
+    });
+});
+describe('Proof: No Gaps or Overflow', () => {
+    /**
+     * Property test: For ANY valid input, sum(children) === parent
+     */
+    it('maintains invariant for random inputs', () => {
+        const testCases = [
+            { parent: 100, children: [100 / 3, 100 / 3, 100 / 3] },
+            { parent: 1000, children: [1000 / 7, 1000 / 7, 1000 / 7, 1000 / 7, 1000 / 7, 1000 / 7, 1000 / 7] },
+            { parent: 50, children: [12.5, 12.5, 12.5, 12.5] },
+            { parent: 99, children: [33, 33, 33] },
+            { parent: 101, children: [50.5, 50.5] },
+            { parent: 1, children: [0.5, 0.5] },
+            { parent: 2, children: [0.6, 0.7, 0.7] },
+        ];
+        for (const tc of testCases) {
+            const group = {
+                parentId: 1,
+                childIds: tc.children.map((_, i) => i + 10),
+                axis: 'horizontal',
+                parentDimension: tc.parent,
+                childDimensions: new Map(tc.children.map((c, i) => [i + 10, c])),
+            };
+            const result = distributeWithLargestRemainder(group);
+            expect(result.totalPixels).toBe(tc.parent);
+            expect(result.isExact).toBe(true);
+        }
+    });
+});

package/dist/rasterizer/canvas-mapper.d.ts

@@ -0,0 +1,280 @@
+/**
+ * Path Projection (Phase 6)
+ *
+ * This module transforms P-dimension ControlPoint entities (with exact rational
+ * coordinates) into rasterized PathEntity objects for rendering.
+ *
+ * ## Architecture
+ *
+ * ```
+ *   P-Dimension                    Rasterization Boundary                 Canvas
+ *   ───────────────────────────────────────────────────────────────────────────
+ *
+ *   ControlPoint                   ┌──────────────────┐
+ *   entities with   ─────────────▶ │  canvas-mapper   │ ─────────────▶  PathEntity
+ *   Rational coords                │  (this module)   │               objects
+ *                                  └──────────────────┘
+ *                                          │
+ *                                          ▼
+ *                                  topology-rounding.ts
+ *                                  (pixel-perfect adjacency)
+ * ```
+ *
+ * ## Critical Invariants
+ *
+ * 1. **Float Decontamination**: All f64 values are produced ONLY by
+ *    `Rational.to_f64_for_rasterization()` at this boundary
+ * 2. **Topology Preservation**: Shared ControlPoints produce bit-identical
+ *    coordinates, ensuring seamless curve connections
+ * 3. **Fill Rule Semantics**: SVG fill-rule (nonzero/evenodd) is preserved
+ */
+import type { EntityId, Rational, PathCommand } from '../ast/types';
+/**
+ * Control point with resolved rational coordinates.
+ */
+export interface ResolvedControlPoint {
+    id: EntityId;
+    x: Rational;
+    y: Rational;
+    role: 'anchor' | 'handle';
+}
+/**
+ * Path segment referencing control points by EntityId.
+ */
+export type PathSegmentRef = {
+    type: 'moveTo';
+    point: EntityId;
+} | {
+    type: 'lineTo';
+    point: EntityId;
+} | {
+    type: 'quadTo';
+    control: EntityId;
+    point: EntityId;
+} | {
+    type: 'cubicTo';
+    control1: EntityId;
+    control2: EntityId;
+    point: EntityId;
+} | {
+    type: 'arcTo';
+    point: EntityId;
+    radiusX: Rational;
+    radiusY: Rational;
+    xRotation: Rational;
+    largeArc: boolean;
+    sweep: boolean;
+} | {
+    type: 'close';
+};
+/**
+ * Path definition with EntityId references.
+ */
+export interface PathDefinition {
+    id: EntityId;
+    segments: PathSegmentRef[];
+    fillRule: 'nonzero' | 'evenodd';
+    closed: boolean;
+}
+/**
+ * Rasterized path ready for GPU renderer consumption.
+ */
+export interface RasterizedPath {
+    /** Unique path ID */
+    id: EntityId;
+    /** SVG-style path commands with float coordinates */
+    commands: PathCommand[];
+    /** Fill rule for winding calculation */
+    fillRule: 'nonzero' | 'evenodd';
+    /** Whether path is closed */
+    closed: boolean;
+    /** Computed bounding box (for culling) */
+    bounds: {
+        minX: number;
+        minY: number;
+        maxX: number;
+        maxY: number;
+    };
+}
+/**
+ * Maps P-dimension path definitions to rasterized PathEntity objects.
+ *
+ * @param paths - Path definitions with EntityId references
+ * @param controlPoints - Map of resolved control point positions
+ * @param devicePixelRatio - DPR for coordinate scaling
+ * @returns Rasterized paths ready for GPU renderer
+ */
+export declare function mapPathsToCanvas(paths: PathDefinition[], controlPoints: Map<EntityId, ResolvedControlPoint>, devicePixelRatio?: number): RasterizedPath[];
+/**
+ * Map a single path definition to rasterized commands.
+ */
+declare function mapSinglePath(path: PathDefinition, controlPoints: Map<EntityId, ResolvedControlPoint>, dpr: number): RasterizedPath;
+/**
+ * Interface matching the GPU path builder type (subset).
+ */
+export interface PathBuilderLike {
+    moveTo(x: number, y: number): void;
+    lineTo(x: number, y: number): void;
+    quadTo(cpx: number, cpy: number, x: number, y: number): void;
+    cubicTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, y: number): void;
+    arcToOval(oval: Float32Array, startAngle: number, sweepAngle: number, forceMoveTo: boolean): void;
+    arcToRotated(rx: number, ry: number, xAxisRotate: number, useSmallArc: boolean, isCCW: boolean, x: number, y: number): void;
+    close(): void;
+    setFillType(fillType: number): void;
+}
+/**
+ * Fill type constants.
+ */
+export declare const FillType: {
+    Winding: number;
+    EvenOdd: number;
+};
+/**
+ * Build a PathEntity from rasterized path data.
+ *
+ * @param path - Rasterized path with float coordinates
+ * @param pathBuilder - Path builder object to populate
+ */
+export declare function buildPathEntity(path: RasterizedPath, pathBuilder: PathBuilderLike): void;
+/**
+ * Ensures that paths sharing control points produce bit-identical coordinates.
+ *
+ * This is critical for seamless curve connections: if two Bezier curves share
+ * an endpoint, the rasterized coordinates must be exactly the same to prevent
+ * visual gaps or overlaps.
+ *
+ * ## Algorithm
+ *
+ * 1. Identify all paths that share control points
+ * 2. For shared points, use a single coordinate resolution
+ * 3. Both paths reference the same float value
+ *
+ * @param paths - Paths that may share control points
+ * @param controlPoints - Control point definitions
+ * @returns Normalized control point map with consistent coordinates
+ */
+export declare function normalizeSharedControlPoints(paths: PathDefinition[], controlPoints: Map<EntityId, ResolvedControlPoint>): Map<EntityId, ResolvedControlPoint>;
+declare function getSegmentPointIds(segment: PathSegmentRef): EntityId[];
+/**
+ * Validate that all control point references in paths are resolvable.
+ */
+export declare function validatePathReferences(paths: PathDefinition[], controlPoints: Map<EntityId, ResolvedControlPoint>): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * A resolved Radius entity (scalar value).
+ */
+export interface ResolvedRadius {
+    id: EntityId;
+    value: Rational;
+}
+/**
+ * A resolved Arc entity with center, radius, and angles.
+ */
+export interface ResolvedArc {
+    id: EntityId;
+    /** Center control point (already resolved). */
+    center: ResolvedControlPoint;
+    /** Radius value (already resolved). */
+    radius: ResolvedRadius;
+    /** Start angle in degrees. */
+    startAngle: Rational;
+    /** End angle in degrees. */
+    endAngle: Rational;
+    /** Direction: true = clockwise. */
+    clockwise: boolean;
+}
+/**
+ * A resolved RoundedRect with corner radii.
+ */
+export interface ResolvedRoundedRect {
+    id: EntityId;
+    /** Bounds (x, y, width, height). */
+    bounds: {
+        x: Rational;
+        y: Rational;
+        width: Rational;
+        height: Rational;
+    };
+    /** Corner radii (all resolved). */
+    radii: {
+        topLeft: ResolvedRadius;
+        topRight: ResolvedRadius;
+        bottomRight: ResolvedRadius;
+        bottomLeft: ResolvedRadius;
+    };
+}
+/**
+ * Interface matching the GPU canvas drawing surface methods.
+ */
+export interface DrawSurfaceLike {
+    drawArc(oval: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }, startAngle: number, sweepAngle: number, useCenter: boolean, paint: unknown): void;
+    drawRoundRect(rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }, rx: number, ry: number, paint: unknown): void;
+    drawRRect(rrect: unknown, paint: unknown): void;
+}
+/**
+ * Convert rational to float at RASTERIZATION BOUNDARY ONLY.
+ */
+declare function toFloat(r: Rational): number;
+/**
+ * Draw an arc to a GPU draw surface.
+ *
+ * ## Deferred Evaluation (Phase 7)
+ *
+ * The arc's circumference points are NOT computed in P-dimension.
+ * Only the center, radius, and angles are constrained linearly.
+ * The actual arc rendering is delegated to the GPU renderer which evaluates
+ * the parametric curve (cos/sin) in its native floating-point space.
+ *
+ * @param canvas - GPU draw surface
+ * @param arc - Resolved arc with rational center/radius/angles
+ * @param paint - Paint style for the arc
+ */
+export declare function drawArc(canvas: DrawSurfaceLike, arc: ResolvedArc, paint: unknown): void;
+/**
+ * Draw a rounded rectangle to a GPU draw surface.
+ *
+ * ## Deferred Evaluation (Phase 7)
+ *
+ * Corner curves are NOT evaluated in P-dimension. Only the bounds and
+ * radius scalars are constrained. The GPU renderer evaluates the corner arcs
+ * internally using native floating-point math.
+ *
+ * @param canvas - GPU draw surface
+ * @param rect - Resolved rounded rect with rational bounds/radii
+ * @param paint - Paint style
+ */
+export declare function drawRoundedRect(canvas: DrawSurfaceLike, rect: ResolvedRoundedRect, paint: unknown): void;
+/**
+ * Draw a full circle (special case of arc: 0° to 360°).
+ *
+ * @param canvas - GPU draw surface
+ * @param center - Resolved center control point
+ * @param radius - Resolved radius entity
+ * @param paint - Paint style
+ */
+export declare function drawCircle(canvas: DrawSurfaceLike, center: ResolvedControlPoint, radius: ResolvedRadius, paint: unknown): void;
+/**
+ * Validate arc/radius entity references.
+ */
+export declare function validateArcReferences(arcs: ResolvedArc[], centers: Map<EntityId, ResolvedControlPoint>, radii: Map<EntityId, ResolvedRadius>): {
+    valid: boolean;
+    errors: string[];
+};
+export declare const _internals: {
+    mapSinglePath: typeof mapSinglePath;
+    toFloat: typeof toFloat;
+    getSegmentPointIds: typeof getSegmentPointIds;
+};
+export {};