@viewscript/renderer 0.1.0-202605140639

package/dist/rasterizer/gradient-mapper.js

@@ -0,0 +1,352 @@
+/**
+ * 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);
+ * ```
+ */
+// =============================================================================
+// Core Mapping Functions
+// =============================================================================
+/**
+ * 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 function mapLinearGradientToShader(ck, gradient, bounds, devicePixelRatio) {
+    // Convert control points to device coordinates
+    const startX = rationalToFloat(gradient.start.x) * devicePixelRatio;
+    const startY = rationalToFloat(gradient.start.y) * devicePixelRatio;
+    const endX = rationalToFloat(gradient.end.x) * devicePixelRatio;
+    const endY = rationalToFloat(gradient.end.y) * devicePixelRatio;
+    // Sort stops by position (required by GPU shader backend)
+    const sortedStops = [...gradient.stops].sort((a, b) => rationalToFloat(a.position) - rationalToFloat(b.position));
+    // Convert colors to Float32Array (RGBA format, each channel 0-1)
+    const colors = colorStopsToFloat32Array(sortedStops);
+    const positions = positionsToFloat32Array(sortedStops);
+    // Map tile mode
+    const tileMode = mapTileMode(ck, gradient.tileMode);
+    return ck.Shader.MakeLinearGradient(new Float32Array([startX, startY]), new Float32Array([endX, endY]), colors, positions, tileMode);
+}
+/**
+ * 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 function mapRadialGradientToShader(ck, gradient, bounds, devicePixelRatio) {
+    // Convert center to device coordinates
+    const centerX = rationalToFloat(gradient.center.x) * devicePixelRatio;
+    const centerY = rationalToFloat(gradient.center.y) * devicePixelRatio;
+    // For elliptical gradients, we use the larger radius and scale
+    // For now, use average of radiusX and radiusY as the radius
+    const radiusX = rationalToFloat(gradient.radiusX) * devicePixelRatio;
+    const radiusY = rationalToFloat(gradient.radiusY) * devicePixelRatio;
+    const radius = Math.max(radiusX, radiusY);
+    // Handle focal point (if specified)
+    let focalX = centerX;
+    let focalY = centerY;
+    let focalR = 0;
+    if (gradient.focalPoint) {
+        focalX = rationalToFloat(gradient.focalPoint.x) * devicePixelRatio;
+        focalY = rationalToFloat(gradient.focalPoint.y) * devicePixelRatio;
+    }
+    if (gradient.focalRadius) {
+        focalR = rationalToFloat(gradient.focalRadius) * devicePixelRatio;
+    }
+    // Sort and convert stops
+    const sortedStops = [...gradient.stops].sort((a, b) => rationalToFloat(a.position) - rationalToFloat(b.position));
+    const colors = colorStopsToFloat32Array(sortedStops);
+    const positions = positionsToFloat32Array(sortedStops);
+    const tileMode = mapTileMode(ck, gradient.tileMode);
+    // Two-point conical: inner circle to outer circle
+    return ck.Shader.MakeTwoPointConicalGradient(new Float32Array([focalX, focalY]), focalR, new Float32Array([centerX, centerY]), radius, colors, positions, tileMode);
+}
+/**
+ * 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 function mapConicGradientToShader(ck, gradient, bounds, devicePixelRatio) {
+    // Convert center to device coordinates
+    const centerX = rationalToFloat(gradient.center.x) * devicePixelRatio;
+    const centerY = rationalToFloat(gradient.center.y) * devicePixelRatio;
+    // Convert angles (GPU shader expects degrees)
+    const startAngle = rationalToFloat(gradient.startAngle) + rationalToFloat(gradient.rotation);
+    const endAngle = rationalToFloat(gradient.endAngle) + rationalToFloat(gradient.rotation);
+    // Sort and convert stops
+    const sortedStops = [...gradient.stops].sort((a, b) => rationalToFloat(a.position) - rationalToFloat(b.position));
+    const colors = colorStopsToFloat32Array(sortedStops);
+    const positions = positionsToFloat32Array(sortedStops);
+    // Sweep gradient always uses Clamp-like behavior
+    return ck.Shader.MakeSweepGradient(centerX, centerY, colors, positions, ck.TileMode.Clamp, startAngle, endAngle);
+}
+// =============================================================================
+// Conversion Utilities
+// =============================================================================
+/**
+ * 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 function rationalToFloat(r) {
+    // Handle bigint to number conversion
+    // For very large rationals, this may lose precision
+    return Number(r.numerator) / Number(r.denominator);
+}
+/**
+ * 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 function colorStopsToFloat32Array(stops) {
+    const array = new Float32Array(stops.length * 4);
+    for (let i = 0; i < stops.length; i++) {
+        const stop = stops[i];
+        const offset = i * 4;
+        // Convert [0, 255] rational to [0, 1] float with clamping
+        array[offset + 0] = clamp01(rationalToFloat(stop.r) / 255);
+        array[offset + 1] = clamp01(rationalToFloat(stop.g) / 255);
+        array[offset + 2] = clamp01(rationalToFloat(stop.b) / 255);
+        // Alpha is already in [0, 1] in P-dimension
+        array[offset + 3] = clamp01(rationalToFloat(stop.a));
+    }
+    return array;
+}
+/**
+ * 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 function positionsToFloat32Array(stops) {
+    const array = new Float32Array(stops.length);
+    for (let i = 0; i < stops.length; i++) {
+        array[i] = clamp01(rationalToFloat(stops[i].position));
+    }
+    return array;
+}
+/**
+ * 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.
+ */
+function clamp01(value) {
+    return Math.max(0, Math.min(1, value));
+}
+/**
+ * Map P-dimension tile mode to GPU tile mode constant.
+ */
+function mapTileMode(ck, mode) {
+    switch (mode) {
+        case 'clamp':
+            return ck.TileMode.Clamp;
+        case 'repeat':
+            return ck.TileMode.Repeat;
+        case 'mirror':
+            return ck.TileMode.Mirror;
+        case 'decal':
+            return ck.TileMode.Decal;
+        default:
+            return ck.TileMode.Clamp;
+    }
+}
+// =============================================================================
+// Factory Function for Gradient FillStyle
+// =============================================================================
+/**
+ * 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 function createGradientShader(ck, fillType, stops, bounds, devicePixelRatio) {
+    // Convert simplified FillStyle stops to PColorStop format
+    const pStops = stops.map((stop, index) => {
+        const rgba = parseColorString(stop.color);
+        return {
+            id: index,
+            r: { numerator: BigInt(rgba.r), denominator: 1n },
+            g: { numerator: BigInt(rgba.g), denominator: 1n },
+            b: { numerator: BigInt(rgba.b), denominator: 1n },
+            a: { numerator: BigInt(Math.round(rgba.a * 1000)), denominator: 1000n },
+            position: stop.offset,
+        };
+    });
+    if (fillType === 'linear-gradient') {
+        // Default linear gradient: top to bottom
+        const linearGradient = {
+            id: 0,
+            start: {
+                id: 0,
+                x: { numerator: BigInt(Math.round(bounds.x)), denominator: 1n },
+                y: { numerator: BigInt(Math.round(bounds.y)), denominator: 1n },
+            },
+            end: {
+                id: 0,
+                x: { numerator: BigInt(Math.round(bounds.x)), denominator: 1n },
+                y: { numerator: BigInt(Math.round(bounds.y + bounds.height)), denominator: 1n },
+            },
+            stops: pStops,
+            tileMode: 'clamp',
+        };
+        return mapLinearGradientToShader(ck, linearGradient, bounds, devicePixelRatio);
+    }
+    else if (fillType === 'radial-gradient') {
+        // Default radial gradient: center of bounds, radius to edge
+        const cx = bounds.x + bounds.width / 2;
+        const cy = bounds.y + bounds.height / 2;
+        const radius = Math.max(bounds.width, bounds.height) / 2;
+        const radialGradient = {
+            id: 0,
+            center: {
+                id: 0,
+                x: { numerator: BigInt(Math.round(cx * 1000)), denominator: 1000n },
+                y: { numerator: BigInt(Math.round(cy * 1000)), denominator: 1000n },
+            },
+            radiusX: { numerator: BigInt(Math.round(radius * 1000)), denominator: 1000n },
+            radiusY: { numerator: BigInt(Math.round(radius * 1000)), denominator: 1000n },
+            stops: pStops,
+            tileMode: 'clamp',
+        };
+        return mapRadialGradientToShader(ck, radialGradient, bounds, devicePixelRatio);
+    }
+    return null;
+}
+/**
+ * Parse a CSS color string to RGBA values.
+ *
+ * Supports:
+ * - Hex: #RGB, #RGBA, #RRGGBB, #RRGGBBAA
+ * - Named colors (basic set)
+ */
+function parseColorString(color) {
+    // Named colors (basic set)
+    const namedColors = {
+        black: { r: 0, g: 0, b: 0 },
+        white: { r: 255, g: 255, b: 255 },
+        red: { r: 255, g: 0, b: 0 },
+        green: { r: 0, g: 128, b: 0 },
+        blue: { r: 0, g: 0, b: 255 },
+        yellow: { r: 255, g: 255, b: 0 },
+        cyan: { r: 0, g: 255, b: 255 },
+        magenta: { r: 255, g: 0, b: 255 },
+        transparent: { r: 0, g: 0, b: 0 },
+    };
+    const lower = color.toLowerCase().trim();
+    if (lower === 'transparent') {
+        return { r: 0, g: 0, b: 0, a: 0 };
+    }
+    if (namedColors[lower]) {
+        return { ...namedColors[lower], a: 1 };
+    }
+    // Hex parsing
+    if (lower.startsWith('#')) {
+        const hex = lower.slice(1);
+        if (hex.length === 3) {
+            // #RGB
+            return {
+                r: parseInt(hex[0] + hex[0], 16),
+                g: parseInt(hex[1] + hex[1], 16),
+                b: parseInt(hex[2] + hex[2], 16),
+                a: 1,
+            };
+        }
+        else if (hex.length === 4) {
+            // #RGBA
+            return {
+                r: parseInt(hex[0] + hex[0], 16),
+                g: parseInt(hex[1] + hex[1], 16),
+                b: parseInt(hex[2] + hex[2], 16),
+                a: parseInt(hex[3] + hex[3], 16) / 255,
+            };
+        }
+        else if (hex.length === 6) {
+            // #RRGGBB
+            return {
+                r: parseInt(hex.slice(0, 2), 16),
+                g: parseInt(hex.slice(2, 4), 16),
+                b: parseInt(hex.slice(4, 6), 16),
+                a: 1,
+            };
+        }
+        else if (hex.length === 8) {
+            // #RRGGBBAA
+            return {
+                r: parseInt(hex.slice(0, 2), 16),
+                g: parseInt(hex.slice(2, 4), 16),
+                b: parseInt(hex.slice(4, 6), 16),
+                a: parseInt(hex.slice(6, 8), 16) / 255,
+            };
+        }
+    }
+    // Fallback: black
+    return { r: 0, g: 0, b: 0, a: 1 };
+}
+// =============================================================================
+// Exports for Testing
+// =============================================================================
+export const _internals = {
+    rationalToFloat,
+    clamp01,
+    colorStopsToFloat32Array,
+    positionsToFloat32Array,
+    mapTileMode,
+    parseColorString,
+};

package/dist/rasterizer/topology-rounding.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Topology-Preserving Rounding Algorithm
+ *
+ * This module implements the rasterization layer that projects P-dimension
+ * rational coordinates to discrete pixel coordinates while preserving
+ * topological relationships (adjacency, containment, ordering).
+ *
+ * ## The Problem
+ *
+ * Given two adjacent surfaces A and B where:
+ *   A.right = 100.333... (rational)
+ *   B.left = 100.333... (same rational)
+ *
+ * Naive rounding may produce:
+ *   A.right = 100px (floor)
+ *   B.left = 101px (ceil)
+ *
+ * This creates a 1px gap that violates the topological constraint
+ * that A and B are adjacent (no gap, no overlap).
+ *
+ * ## Solution: Constraint-Aware Rounding
+ *
+ * Instead of rounding each coordinate independently, we:
+ * 1. Build a graph of topological relationships (adjacency, containment)
+ * 2. Partition coordinates into equivalence classes (same rational = same pixel)
+ * 3. Round equivalence classes together
+ * 4. Propagate rounding decisions through the constraint graph
+ *
+ * ## Algorithm
+ *
+ * ```
+ * INPUT:
+ *   - Set of surfaces S with rational bounds
+ *   - Topological constraints T (adjacency, containment)
+ *   - Device pixel ratio DPR
+ *
+ * OUTPUT:
+ *   - Integer pixel coordinates for all surfaces
+ *   - Guarantee: topology is preserved
+ *
+ * ALGORITHM:
+ *
+ * Phase 1: Build Coordinate Equivalence Classes
+ *   For each unique rational value r:
+ *     equiv[r] = { all coordinates that equal r }
+ *
+ * Phase 2: Compute Rounding Constraints
+ *   For each adjacency constraint (A.right = B.left):
+ *     round(A.right) MUST equal round(B.left)
+ *   For each ordering constraint (A.right < B.left):
+ *     round(A.right) MUST be < round(B.left)
+ *
+ * Phase 3: Propagate Rounding Decisions
+ *   Using constraint propagation:
+ *   - Start with coordinates that have no constraints (free variables)
+ *   - Round them to nearest integer
+ *   - Propagate to constrained coordinates
+ *   - Resolve conflicts by adjusting adjacent surfaces symmetrically
+ *
+ * Phase 4: Verify Topology Preservation
+ *   Assert all topological constraints are satisfied
+ * ```
+ */
+import type { EntityId, Rational, RasterBounds, PVectorBounds } from '../ast/types';
+/**
+ * A coordinate in the pre-rasterization space.
+ */
+interface RationalCoord {
+    entityId: EntityId;
+    edge: 'left' | 'right' | 'top' | 'bottom';
+    value: Rational;
+}
+/**
+ * Topological constraint between coordinates.
+ */
+type TopoConstraint = {
+    type: 'equal';
+    a: CoordRef;
+    b: CoordRef;
+} | {
+    type: 'less-than';
+    a: CoordRef;
+    b: CoordRef;
+} | {
+    type: 'adjacent';
+    a: CoordRef;
+    b: CoordRef;
+};
+interface CoordRef {
+    entityId: EntityId;
+    edge: 'left' | 'right' | 'top' | 'bottom';
+}
+/**
+ * Result of the rounding algorithm.
+ */
+export interface RoundingResult {
+    /** Rasterized bounds for each entity */
+    bounds: Map<EntityId, RasterBounds>;
+    /** Any topology violations detected (should be empty if algorithm is correct) */
+    violations: TopologyViolation[];
+    /** Statistics about the rounding process */
+    stats: RoundingStats;
+}
+interface TopologyViolation {
+    constraint: TopoConstraint;
+    message: string;
+}
+interface RoundingStats {
+    totalCoordinates: number;
+    equivalenceClasses: number;
+    constraintsPropagated: number;
+    conflictsResolved: number;
+}
+/**
+ * Topology-preserving rounding entry point.
+ */
+export declare function roundWithTopologyPreservation(entities: Map<EntityId, PVectorBounds>, constraints: TopoConstraint[], devicePixelRatio: number): RoundingResult;
+declare function extractCoordinates(entities: Map<EntityId, PVectorBounds>): RationalCoord[];
+/**
+ * Build equivalence classes from coordinates and equality constraints.
+ *
+ * Two coordinates are in the same class if:
+ * 1. They have the same rational value, OR
+ * 2. They are connected by an 'equal' or 'adjacent' constraint
+ */
+declare function buildEquivalenceClasses(coords: RationalCoord[], constraints: TopoConstraint[]): Map<string, RationalCoord[]>;
+declare function rationalToFloat(r: Rational): number;
+interface PropagationResult {
+    adjusted: Map<string, number>;
+    conflictsResolved: number;
+}
+/**
+ * Propagate rounding decisions through less-than constraints.
+ *
+ * If A < B in rational space, we must ensure round(A) < round(B) in pixel space.
+ * If rounding would violate this, we adjust by:
+ * 1. Decreasing A by 1, OR
+ * 2. Increasing B by 1
+ *
+ * We choose the option that minimizes total visual shift.
+ */
+declare function propagateConstraints(initial: Map<string, number>, equivClasses: Map<string, RationalCoord[]>, constraints: TopoConstraint[]): PropagationResult;
+declare function verifyTopology(bounds: Map<EntityId, RasterBounds>, constraints: TopoConstraint[]): TopologyViolation[];
+export declare const _internals: {
+    extractCoordinates: typeof extractCoordinates;
+    buildEquivalenceClasses: typeof buildEquivalenceClasses;
+    propagateConstraints: typeof propagateConstraints;
+    verifyTopology: typeof verifyTopology;
+    rationalToFloat: typeof rationalToFloat;
+};
+export {};