@viewscript/renderer 0.1.0-202605140639

package/dist/rasterizer/error-distribution.js

@@ -0,0 +1,231 @@
+/**
+ * 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.
+ */
+// =============================================================================
+// Largest Remainder Method
+// =============================================================================
+/**
+ * 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 function distributeWithLargestRemainder(group) {
+    const { childIds, parentDimension, childDimensions } = group;
+    // Edge case: no children
+    if (childIds.length === 0) {
+        return {
+            dimensions: [],
+            totalPixels: 0,
+            isExact: parentDimension === 0,
+            method: 'largest-remainder',
+        };
+    }
+    const items = childIds.map((id, index) => {
+        const original = childDimensions.get(id) ?? 0;
+        const floor = Math.floor(original);
+        return {
+            entityId: id,
+            original,
+            floor,
+            remainder: original - floor,
+            index,
+        };
+    });
+    // Step 2: Compute shortfall
+    const sumOfFloors = items.reduce((sum, item) => sum + item.floor, 0);
+    const shortfall = parentDimension - sumOfFloors;
+    // Sanity check: shortfall should be non-negative and <= childCount
+    if (shortfall < 0 || shortfall > items.length) {
+        // This indicates a constraint violation (children sum > parent)
+        // Fall back to proportional scaling
+        return distributeProportionally(group);
+    }
+    // Step 3: Sort by remainder (descending), then by index (ascending) for tie-break
+    const sorted = [...items].sort((a, b) => {
+        const remainderDiff = b.remainder - a.remainder;
+        if (Math.abs(remainderDiff) > 1e-10) {
+            return remainderDiff;
+        }
+        // Tie-break: leftmost first
+        return a.index - b.index;
+    });
+    // Step 4: Distribute shortfall to top N elements
+    const extraPixels = new Set();
+    for (let i = 0; i < shortfall; i++) {
+        extraPixels.add(sorted[i].entityId);
+    }
+    // Step 5: Build result
+    const dimensions = items.map(item => {
+        const pixels = item.floor + (extraPixels.has(item.entityId) ? 1 : 0);
+        return {
+            entityId: item.entityId,
+            pixels,
+            original: item.original,
+            error: pixels - item.original,
+        };
+    });
+    const totalPixels = dimensions.reduce((sum, d) => sum + d.pixels, 0);
+    return {
+        dimensions,
+        totalPixels,
+        isExact: totalPixels === parentDimension,
+        method: 'largest-remainder',
+    };
+}
+/**
+ * Fallback: Proportional scaling when LRM fails.
+ *
+ * Used when child sum exceeds parent (constraint violation).
+ */
+function distributeProportionally(group) {
+    const { childIds, parentDimension, childDimensions } = group;
+    const totalOriginal = childIds.reduce((sum, id) => sum + (childDimensions.get(id) ?? 0), 0);
+    if (totalOriginal === 0) {
+        return {
+            dimensions: childIds.map(id => ({
+                entityId: id,
+                pixels: 0,
+                original: 0,
+                error: 0,
+            })),
+            totalPixels: 0,
+            isExact: parentDimension === 0,
+            method: 'first-fit',
+        };
+    }
+    const scale = parentDimension / totalOriginal;
+    const scaled = childIds.map(id => {
+        const original = childDimensions.get(id) ?? 0;
+        return {
+            entityId: id,
+            original,
+            scaled: original * scale,
+        };
+    });
+    // Apply LRM to scaled values
+    const scaledGroup = {
+        ...group,
+        childDimensions: new Map(scaled.map(s => [s.entityId, s.scaled])),
+    };
+    const result = distributeWithLargestRemainder(scaledGroup);
+    result.method = 'first-fit';
+    return result;
+}
+/**
+ * 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 function applyErrorDistribution(roundedBounds, containments) {
+    const result = new Map(roundedBounds);
+    for (const constraint of containments) {
+        const parentBounds = result.get(constraint.parentId);
+        if (!parentBounds)
+            continue;
+        const parentDimension = constraint.axis === 'horizontal'
+            ? parentBounds.width
+            : parentBounds.height;
+        // Build sibling group
+        const childDimensions = new Map();
+        for (const childId of constraint.childIds) {
+            const childBounds = result.get(childId);
+            if (childBounds) {
+                const dim = constraint.axis === 'horizontal'
+                    ? childBounds.width
+                    : childBounds.height;
+                childDimensions.set(childId, dim);
+            }
+        }
+        const group = {
+            parentId: constraint.parentId,
+            childIds: constraint.childIds,
+            axis: constraint.axis,
+            parentDimension,
+            childDimensions,
+        };
+        // Distribute
+        const distribution = distributeWithLargestRemainder(group);
+        // Apply distributed dimensions
+        let offset = constraint.axis === 'horizontal' ? parentBounds.x : parentBounds.y;
+        for (const dist of distribution.dimensions) {
+            const childBounds = result.get(dist.entityId);
+            if (childBounds) {
+                if (constraint.axis === 'horizontal') {
+                    childBounds.x = offset;
+                    childBounds.width = dist.pixels;
+                }
+                else {
+                    childBounds.y = offset;
+                    childBounds.height = dist.pixels;
+                }
+                offset += dist.pixels;
+            }
+        }
+    }
+    return result;
+}
+// =============================================================================
+// Exports for Testing
+// =============================================================================
+export const _internals = {
+    distributeProportionally,
+};

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

@@ -0,0 +1,223 @@
+/**
+ * Gradient Shader Mapper: P-Dimension to GPU Shaders
+ *
+ * This module maps P-dimension gradient entities to GPU shader objects.
+ * It handles the critical transition from exact rational arithmetic to GPU-compatible
+ * floating-point representation while preserving visual fidelity.
+ *
+ * ## Architecture
+ *
+ * ```
+ *   P-Dimension (Exact)                        GPU (Float)
+ *   ─────────────────────────────────────────────────────────────
+ *
+ *   LinearGradient {                           GpuShaderBackend.Shader
+ *     start: Rational(1, 3)    ────────────▶   MakeLinearGradient(
+ *     end: Rational(2, 3)                        [0.333..., 0.666...],
+ *     stops: [                                   colors: Float32Array,
+ *       ColorStop(r=255, ...)                    positions: Float32Array
+ *     ]                                        )
+ *   }
+ *
+ *   ┌─────────────────────────────────────────────────────────────┐
+ *   │  CRITICAL: Topology-preserving rounding at this boundary   │
+ *   │                                                             │
+ *   │  - Color channels [0, 255] → [0.0, 1.0] with clamping      │
+ *   │  - Position values [0, 1] stay exact, no interpolation     │
+ *   │  - Control points use same rounding as other coordinates   │
+ *   └─────────────────────────────────────────────────────────────┘
+ * ```
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * const shader = mapLinearGradientToShader(ck, gradient, bounds, dpr);
+ * paint.setShader(shader);
+ * canvas.drawRect(bounds, paint);
+ * ```
+ */
+import type { Rational, RasterBounds } from '../ast/types';
+/** GPU shader backend interface (minimal subset needed for gradients) */
+export interface GpuShaderBackend {
+    Shader: {
+        MakeLinearGradient(start: Float32Array, end: Float32Array, colors: Float32Array, positions: Float32Array | null, mode: number, localMatrix?: Float32Array): ShaderInstance;
+        MakeTwoPointConicalGradient(start: Float32Array, startRadius: number, end: Float32Array, endRadius: number, colors: Float32Array, positions: Float32Array | null, mode: number, localMatrix?: Float32Array): ShaderInstance;
+        MakeSweepGradient(cx: number, cy: number, colors: Float32Array, positions: Float32Array | null, mode: number, startAngle: number, endAngle: number, localMatrix?: Float32Array): ShaderInstance;
+    };
+    TileMode: {
+        Clamp: number;
+        Repeat: number;
+        Mirror: number;
+        Decal: number;
+    };
+}
+export interface ShaderInstance {
+    delete(): void;
+}
+/**
+ * P-dimension color stop with exact rational values.
+ */
+export interface PColorStop {
+    /** Entity ID */
+    id: number;
+    /** Red channel [0, 255] (rational) */
+    r: Rational;
+    /** Green channel [0, 255] (rational) */
+    g: Rational;
+    /** Blue channel [0, 255] (rational) */
+    b: Rational;
+    /** Alpha channel [0, 1] (rational) */
+    a: Rational;
+    /** Position along gradient [0, 1] (rational) */
+    position: Rational;
+}
+/**
+ * P-dimension control point with exact coordinates.
+ */
+export interface PControlPoint {
+    id: number;
+    x: Rational;
+    y: Rational;
+}
+/**
+ * P-dimension linear gradient definition.
+ */
+export interface PLinearGradient {
+    id: number;
+    start: PControlPoint;
+    end: PControlPoint;
+    stops: PColorStop[];
+    tileMode: 'clamp' | 'repeat' | 'mirror' | 'decal';
+}
+/**
+ * P-dimension radial gradient definition.
+ */
+export interface PRadialGradient {
+    id: number;
+    center: PControlPoint;
+    radiusX: Rational;
+    radiusY: Rational;
+    focalPoint?: PControlPoint;
+    focalRadius?: Rational;
+    stops: PColorStop[];
+    tileMode: 'clamp' | 'repeat' | 'mirror' | 'decal';
+}
+/**
+ * P-dimension conic (sweep) gradient definition.
+ */
+export interface PConicGradient {
+    id: number;
+    center: PControlPoint;
+    /** Rotation offset in degrees (rational) */
+    rotation: Rational;
+    /** Start angle in degrees (rational) */
+    startAngle: Rational;
+    /** End angle in degrees (rational) */
+    endAngle: Rational;
+    stops: PColorStop[];
+}
+/**
+ * Map a P-dimension linear gradient to a GPU shader.
+ *
+ * @param ck - GPU shader backend instance
+ * @param gradient - P-dimension linear gradient definition
+ * @param bounds - Rasterized bounds for coordinate transformation
+ * @param devicePixelRatio - Device pixel ratio for coordinate scaling
+ * @returns GPU shader instance (caller must call delete() when done)
+ */
+export declare function mapLinearGradientToShader(ck: GpuShaderBackend, gradient: PLinearGradient, bounds: RasterBounds, devicePixelRatio: number): ShaderInstance;
+/**
+ * Map a P-dimension radial gradient to a GPU shader.
+ *
+ * The GPU backend uses two-point conical gradients which can express:
+ * - Circle gradients (same center, different radii)
+ * - Focal gradients (different centers)
+ *
+ * @param ck - GPU shader backend instance
+ * @param gradient - P-dimension radial gradient definition
+ * @param bounds - Rasterized bounds for coordinate transformation
+ * @param devicePixelRatio - Device pixel ratio for coordinate scaling
+ * @returns GPU shader instance
+ */
+export declare function mapRadialGradientToShader(ck: GpuShaderBackend, gradient: PRadialGradient, bounds: RasterBounds, devicePixelRatio: number): ShaderInstance;
+/**
+ * Map a P-dimension conic (sweep) gradient to a GPU shader.
+ *
+ * @param ck - GPU shader backend instance
+ * @param gradient - P-dimension conic gradient definition
+ * @param bounds - Rasterized bounds for coordinate transformation
+ * @param devicePixelRatio - Device pixel ratio for coordinate scaling
+ * @returns GPU shader instance
+ */
+export declare function mapConicGradientToShader(ck: GpuShaderBackend, gradient: PConicGradient, bounds: RasterBounds, devicePixelRatio: number): ShaderInstance;
+/**
+ * Convert a rational number to a floating-point number.
+ *
+ * This is the critical boundary where exact arithmetic meets GPU floats.
+ * The conversion is straightforward division, but precision loss is
+ * unavoidable and acceptable at this layer.
+ */
+export declare function rationalToFloat(r: Rational): number;
+/**
+ * Convert P-dimension color stops to a Float32Array of RGBA values.
+ *
+ * GPU shader expects colors in RGBA order, with each channel in [0, 1].
+ * P-dimension stores RGB in [0, 255] and Alpha in [0, 1].
+ *
+ * ## Topology-Preserving Rounding (Clamping)
+ *
+ * Color values are clamped to [0, 1] to ensure GPU-valid input.
+ * This preserves the topological ordering of colors even if the
+ * original rational values were slightly out of range.
+ */
+export declare function colorStopsToFloat32Array(stops: PColorStop[]): Float32Array;
+/**
+ * Convert P-dimension color stop positions to a Float32Array.
+ *
+ * Positions are kept as-is (already in [0, 1] in P-dimension),
+ * with clamping for safety.
+ */
+export declare function positionsToFloat32Array(stops: PColorStop[]): Float32Array;
+/**
+ * Clamp a value to [0, 1] range.
+ *
+ * This is the "topology-preserving rounding" for color values:
+ * it ensures the value is valid for GPU while preserving ordering.
+ */
+declare function clamp01(value: number): number;
+/**
+ * Map P-dimension tile mode to GPU tile mode constant.
+ */
+declare function mapTileMode(ck: GpuShaderBackend, mode: 'clamp' | 'repeat' | 'mirror' | 'decal'): number;
+/**
+ * Create a GPU shader from a FillStyle gradient definition.
+ *
+ * This is a higher-level factory that integrates with the existing
+ * FillStyle type from the AST.
+ */
+export declare function createGradientShader(ck: GpuShaderBackend, fillType: 'linear-gradient' | 'radial-gradient', stops: Array<{
+    offset: Rational;
+    color: string;
+}>, bounds: RasterBounds, devicePixelRatio: number): ShaderInstance | null;
+/**
+ * Parse a CSS color string to RGBA values.
+ *
+ * Supports:
+ * - Hex: #RGB, #RGBA, #RRGGBB, #RRGGBBAA
+ * - Named colors (basic set)
+ */
+declare function parseColorString(color: string): {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+};
+export declare const _internals: {
+    rationalToFloat: typeof rationalToFloat;
+    clamp01: typeof clamp01;
+    colorStopsToFloat32Array: typeof colorStopsToFloat32Array;
+    positionsToFloat32Array: typeof positionsToFloat32Array;
+    mapTileMode: typeof mapTileMode;
+    parseColorString: typeof parseColorString;
+};
+export {};