@viewscript/renderer 0.1.0-202605140639

package/dist/rasterizer/canvas-mapper.js

@@ -0,0 +1,414 @@
+/**
+ * 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
+ */
+// =============================================================================
+// Core Mapping Logic
+// =============================================================================
+/**
+ * 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 function mapPathsToCanvas(paths, controlPoints, devicePixelRatio = 1) {
+    return paths.map(path => mapSinglePath(path, controlPoints, devicePixelRatio));
+}
+/**
+ * Map a single path definition to rasterized commands.
+ */
+function mapSinglePath(path, controlPoints, dpr) {
+    const commands = [];
+    let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+    const toFloat = (r) => {
+        // RASTERIZATION BOUNDARY: Convert Rational to f64
+        return (Number(r.numerator) / Number(r.denominator)) * dpr;
+    };
+    const getPoint = (id) => {
+        const cp = controlPoints.get(id);
+        if (!cp) {
+            throw new Error(`ControlPoint ${id} not found in resolved set`);
+        }
+        return {
+            x: toFloat(cp.x),
+            y: toFloat(cp.y),
+        };
+    };
+    const updateBounds = (x, y) => {
+        minX = Math.min(minX, x);
+        minY = Math.min(minY, y);
+        maxX = Math.max(maxX, x);
+        maxY = Math.max(maxY, y);
+    };
+    const toRational = (n) => ({
+        // Convert float back to rational for PathCommand type
+        // This is a simplification - in production, we'd keep exact rationals
+        numerator: BigInt(Math.round(n * 1000000)),
+        denominator: BigInt(1000000),
+    });
+    for (const segment of path.segments) {
+        switch (segment.type) {
+            case 'moveTo': {
+                const p = getPoint(segment.point);
+                commands.push({ type: 'M', x: toRational(p.x), y: toRational(p.y) });
+                updateBounds(p.x, p.y);
+                break;
+            }
+            case 'lineTo': {
+                const p = getPoint(segment.point);
+                commands.push({ type: 'L', x: toRational(p.x), y: toRational(p.y) });
+                updateBounds(p.x, p.y);
+                break;
+            }
+            case 'quadTo': {
+                const ctrl = getPoint(segment.control);
+                const end = getPoint(segment.point);
+                commands.push({
+                    type: 'Q',
+                    x1: toRational(ctrl.x),
+                    y1: toRational(ctrl.y),
+                    x: toRational(end.x),
+                    y: toRational(end.y),
+                });
+                updateBounds(ctrl.x, ctrl.y);
+                updateBounds(end.x, end.y);
+                break;
+            }
+            case 'cubicTo': {
+                const ctrl1 = getPoint(segment.control1);
+                const ctrl2 = getPoint(segment.control2);
+                const end = getPoint(segment.point);
+                commands.push({
+                    type: 'C',
+                    x1: toRational(ctrl1.x),
+                    y1: toRational(ctrl1.y),
+                    x2: toRational(ctrl2.x),
+                    y2: toRational(ctrl2.y),
+                    x: toRational(end.x),
+                    y: toRational(end.y),
+                });
+                updateBounds(ctrl1.x, ctrl1.y);
+                updateBounds(ctrl2.x, ctrl2.y);
+                updateBounds(end.x, end.y);
+                break;
+            }
+            case 'arcTo': {
+                const end = getPoint(segment.point);
+                commands.push({
+                    type: 'A',
+                    rx: segment.radiusX,
+                    ry: segment.radiusY,
+                    rotation: toFloat(segment.xRotation),
+                    largeArc: segment.largeArc,
+                    sweep: segment.sweep,
+                    x: toRational(end.x),
+                    y: toRational(end.y),
+                });
+                updateBounds(end.x, end.y);
+                // Note: Arc bounds are approximate without full geometric calculation
+                break;
+            }
+            case 'close': {
+                commands.push({ type: 'Z' });
+                break;
+            }
+        }
+    }
+    return {
+        id: path.id,
+        commands,
+        fillRule: path.fillRule,
+        closed: path.closed,
+        bounds: {
+            minX: minX === Infinity ? 0 : minX,
+            minY: minY === Infinity ? 0 : minY,
+            maxX: maxX === -Infinity ? 0 : maxX,
+            maxY: maxY === -Infinity ? 0 : maxY,
+        },
+    };
+}
+/**
+ * Fill type constants.
+ */
+export const FillType = {
+    Winding: 0, // nonzero
+    EvenOdd: 1, // evenodd
+};
+/**
+ * Build a PathEntity from rasterized path data.
+ *
+ * @param path - Rasterized path with float coordinates
+ * @param pathBuilder - Path builder object to populate
+ */
+export function buildPathEntity(path, pathBuilder) {
+    // Set fill rule
+    pathBuilder.setFillType(path.fillRule === 'evenodd' ? FillType.EvenOdd : FillType.Winding);
+    const toFloat = (r) => Number(r.numerator) / Number(r.denominator);
+    for (const cmd of path.commands) {
+        switch (cmd.type) {
+            case 'M':
+                pathBuilder.moveTo(toFloat(cmd.x), toFloat(cmd.y));
+                break;
+            case 'L':
+                pathBuilder.lineTo(toFloat(cmd.x), toFloat(cmd.y));
+                break;
+            case 'Q':
+                pathBuilder.quadTo(toFloat(cmd.x1), toFloat(cmd.y1), toFloat(cmd.x), toFloat(cmd.y));
+                break;
+            case 'C':
+                pathBuilder.cubicTo(toFloat(cmd.x1), toFloat(cmd.y1), toFloat(cmd.x2), toFloat(cmd.y2), toFloat(cmd.x), toFloat(cmd.y));
+                break;
+            case 'A':
+                // Uses arcToRotated for SVG-style arcs
+                pathBuilder.arcToRotated(toFloat(cmd.rx), toFloat(cmd.ry), cmd.rotation, // already a number
+                !cmd.largeArc, // useSmallArc is inverse of largeArc
+                !cmd.sweep, // isCCW may differ from sweep
+                toFloat(cmd.x), toFloat(cmd.y));
+                break;
+            case 'Z':
+                pathBuilder.close();
+                break;
+        }
+    }
+}
+// =============================================================================
+// Topology-Preserving Shared Control Points
+// =============================================================================
+/**
+ * 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 function normalizeSharedControlPoints(paths, controlPoints) {
+    // Collect all control point references
+    const refCounts = new Map();
+    for (const path of paths) {
+        for (const segment of path.segments) {
+            const ids = getSegmentPointIds(segment);
+            for (const id of ids) {
+                refCounts.set(id, (refCounts.get(id) ?? 0) + 1);
+            }
+        }
+    }
+    // Create normalized map (same as input, but this is the guarantee point)
+    // In a real implementation, we'd ensure caching of float conversions
+    const normalized = new Map();
+    for (const [id, cp] of controlPoints) {
+        // If this point is shared (referenced by multiple paths),
+        // it will produce the same float coordinates for all references
+        normalized.set(id, {
+            ...cp,
+            // The Rational values are preserved exactly; float conversion
+            // happens once at rasterization boundary
+        });
+    }
+    return normalized;
+}
+function getSegmentPointIds(segment) {
+    switch (segment.type) {
+        case 'moveTo':
+        case 'lineTo':
+        case 'arcTo':
+            return [segment.point];
+        case 'quadTo':
+            return [segment.control, segment.point];
+        case 'cubicTo':
+            return [segment.control1, segment.control2, segment.point];
+        case 'close':
+            return [];
+    }
+}
+// =============================================================================
+// Validation
+// =============================================================================
+/**
+ * Validate that all control point references in paths are resolvable.
+ */
+export function validatePathReferences(paths, controlPoints) {
+    const errors = [];
+    for (const path of paths) {
+        for (let i = 0; i < path.segments.length; i++) {
+            const segment = path.segments[i];
+            const ids = getSegmentPointIds(segment);
+            for (const id of ids) {
+                if (!controlPoints.has(id)) {
+                    errors.push(`Path ${path.id} segment ${i}: references undefined ControlPoint ${id}`);
+                }
+            }
+        }
+        // Validate path starts with moveTo
+        if (path.segments.length > 0 && path.segments[0].type !== 'moveTo') {
+            errors.push(`Path ${path.id}: first segment must be 'moveTo', got '${path.segments[0].type}'`);
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}
+/**
+ * Convert rational to float at RASTERIZATION BOUNDARY ONLY.
+ */
+function toFloat(r) {
+    return Number(r.numerator) / Number(r.denominator);
+}
+/**
+ * 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 function drawArc(canvas, arc, paint) {
+    // Convert rational values to float at rasterization boundary
+    const cx = toFloat(arc.center.x);
+    const cy = toFloat(arc.center.y);
+    const r = toFloat(arc.radius.value);
+    const startAngle = toFloat(arc.startAngle);
+    const endAngle = toFloat(arc.endAngle);
+    // Compute sweep angle
+    let sweepAngle = endAngle - startAngle;
+    if (arc.clockwise && sweepAngle > 0) {
+        sweepAngle -= 360;
+    }
+    else if (!arc.clockwise && sweepAngle < 0) {
+        sweepAngle += 360;
+    }
+    // drawArc uses an oval bounds
+    const oval = {
+        x: cx - r,
+        y: cy - r,
+        width: r * 2,
+        height: r * 2,
+    };
+    canvas.drawArc(oval, startAngle, sweepAngle, false, paint);
+}
+/**
+ * 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 function drawRoundedRect(canvas, rect, paint) {
+    // Convert rational values to float at rasterization boundary
+    const x = toFloat(rect.bounds.x);
+    const y = toFloat(rect.bounds.y);
+    const width = toFloat(rect.bounds.width);
+    const height = toFloat(rect.bounds.height);
+    const rTL = toFloat(rect.radii.topLeft.value);
+    const rTR = toFloat(rect.radii.topRight.value);
+    const rBR = toFloat(rect.radii.bottomRight.value);
+    const rBL = toFloat(rect.radii.bottomLeft.value);
+    // Check if all radii are equal (use simpler API)
+    if (rTL === rTR && rTR === rBR && rBR === rBL) {
+        canvas.drawRoundRect({ x, y, width, height }, rTL, rTL, paint);
+    }
+    else {
+        // Different radii per corner - would need GPU renderer's RRect support
+        // For now, use uniform radius (max of all)
+        const maxR = Math.max(rTL, rTR, rBR, rBL);
+        canvas.drawRoundRect({ x, y, width, height }, maxR, maxR, paint);
+    }
+}
+/**
+ * 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 function drawCircle(canvas, center, radius, paint) {
+    const cx = toFloat(center.x);
+    const cy = toFloat(center.y);
+    const r = toFloat(radius.value);
+    const oval = {
+        x: cx - r,
+        y: cy - r,
+        width: r * 2,
+        height: r * 2,
+    };
+    canvas.drawArc(oval, 0, 360, false, paint);
+}
+/**
+ * Validate arc/radius entity references.
+ */
+export function validateArcReferences(arcs, centers, radii) {
+    const errors = [];
+    for (const arc of arcs) {
+        // Center must exist
+        if (!centers.has(arc.center.id)) {
+            errors.push(`Arc ${arc.id}: center ControlPoint ${arc.center.id} not found`);
+        }
+        // Radius must exist
+        if (!radii.has(arc.radius.id)) {
+            errors.push(`Arc ${arc.id}: Radius entity ${arc.radius.id} not found`);
+        }
+        // Angles must be valid
+        const start = toFloat(arc.startAngle);
+        const end = toFloat(arc.endAngle);
+        if (isNaN(start) || isNaN(end)) {
+            errors.push(`Arc ${arc.id}: invalid angle values`);
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}
+// =============================================================================
+// Exports for Testing
+// =============================================================================
+export const _internals = {
+    mapSinglePath,
+    toFloat,
+    getSegmentPointIds,
+};

package/dist/rasterizer/error-distribution.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Subpixel Error Distribution Algorithm
+ *
+ * This module implements the Largest Remainder Method (LRM) for distributing
+ * subpixel rounding errors across child elements within a parent container.
+ *
+ * ## The Problem (Architect's Decision #2: Spatial Closure)
+ *
+ * Given a 100px container with 3 children of equal width (33.333...px each):
+ *
+ * ```
+ * Naive rounding:
+ *   floor(33.333) = 33
+ *   33 + 33 + 33 = 99px  ← 1px HOLE!
+ * ```
+ *
+ * This violates VS axiom: "Constraint holes cannot be hidden in theoretical blind spots"
+ *
+ * ## Solution: Largest Remainder Method
+ *
+ * 1. Compute integer quotients: floor(33.333) = 33 for each
+ * 2. Compute remainders: 0.333... for each
+ * 3. Total shortfall: 100 - 99 = 1px
+ * 4. Distribute 1px to elements with largest remainders
+ *
+ * Result: [34, 33, 33] or [33, 34, 33] or [33, 33, 34]
+ * Sum: 100px exactly ✓
+ *
+ * ## Mathematical Guarantee
+ *
+ * For any set of positive rationals r₁, r₂, ..., rₙ where Σrᵢ = T (integer):
+ *
+ *   Σ⌊rᵢ⌋ ≤ T ≤ Σ⌈rᵢ⌉
+ *
+ * LRM distributes exactly (T - Σ⌊rᵢ⌋) extra pixels to achieve Σ = T.
+ */
+import type { EntityId } from '../ast/types';
+/**
+ * A sibling group: children that must sum to parent's dimension.
+ */
+export interface SiblingGroup {
+    /** Parent container entity */
+    parentId: EntityId;
+    /** Child entities in layout order */
+    childIds: EntityId[];
+    /** Axis being distributed */
+    axis: 'horizontal' | 'vertical';
+    /** Parent's exact pixel dimension (must be integer) */
+    parentDimension: number;
+    /** Each child's rational dimension (pre-rounding) */
+    childDimensions: Map<EntityId, number>;
+}
+/**
+ * Distribution result for a single child.
+ */
+export interface DistributedDimension {
+    entityId: EntityId;
+    /** Integer pixel dimension after distribution */
+    pixels: number;
+    /** Original fractional value */
+    original: number;
+    /** Error introduced by rounding (-0.5 to +0.5) */
+    error: number;
+}
+/**
+ * Complete distribution result.
+ */
+export interface DistributionResult {
+    /** Distributed dimensions for each child */
+    dimensions: DistributedDimension[];
+    /** Verification: sum of all pixels */
+    totalPixels: number;
+    /** Should equal parentDimension exactly */
+    isExact: boolean;
+    /** Distribution method used */
+    method: 'largest-remainder' | 'first-fit';
+}
+/**
+ * Distribute subpixel errors using the Largest Remainder Method.
+ *
+ * ## Algorithm
+ *
+ * ```
+ * INPUT: childDimensions = [33.333, 33.333, 33.333], parentDimension = 100
+ *
+ * Step 1: Compute floors
+ *   floors = [33, 33, 33]
+ *   sum(floors) = 99
+ *
+ * Step 2: Compute remainders
+ *   remainders = [0.333, 0.333, 0.333]
+ *
+ * Step 3: Compute shortfall
+ *   shortfall = 100 - 99 = 1
+ *
+ * Step 4: Sort by remainder (descending), distribute shortfall
+ *   Give 1px to first element (arbitrary tie-break: leftmost)
+ *
+ * OUTPUT: [34, 33, 33]
+ * ```
+ *
+ * ## Tie-Breaking Strategy
+ *
+ * When remainders are equal (common for equal-width elements):
+ * - Distribute extra pixels left-to-right (reading order)
+ * - This is visually predictable and matches user expectation
+ */
+export declare function distributeWithLargestRemainder(group: SiblingGroup): DistributionResult;
+/**
+ * Fallback: Proportional scaling when LRM fails.
+ *
+ * Used when child sum exceeds parent (constraint violation).
+ */
+declare function distributeProportionally(group: SiblingGroup): DistributionResult;
+/**
+ * Parent-child containment constraint for error distribution.
+ */
+export interface ContainmentConstraint {
+    parentId: EntityId;
+    childIds: EntityId[];
+    axis: 'horizontal' | 'vertical';
+}
+/**
+ * Apply error distribution to a set of sibling groups.
+ *
+ * This is called AFTER basic topology-preserving rounding,
+ * to ensure parent boundaries are exactly satisfied.
+ */
+export declare function applyErrorDistribution(roundedBounds: Map<EntityId, {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}>, containments: ContainmentConstraint[]): Map<EntityId, {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}>;
+export declare const _internals: {
+    distributeProportionally: typeof distributeProportionally;
+};
+export {};