@viewscript/renderer 0.1.0-202605140639

package/dist/ast/types.d.ts

@@ -0,0 +1,403 @@
+/**
+ * ViewScript Renderer AST: Bilayer Orthogonal Architecture
+ *
+ * This module defines the type system for the dual-layer rendering model:
+ * - Canvas Layer: Visual representation (wgpu draw commands)
+ * - DOM Layer: Interaction regions (accessibility, events, focus)
+ *
+ * ## Architectural Invariants
+ *
+ * 1. Every logical entity has exactly one EntityId
+ * 2. An entity MAY have a CanvasNode (visual), a DOMNode (interactive), or both
+ * 3. Canvas and DOM nodes are synchronized via shared EntityId
+ * 4. DOM nodes have NO visual properties; Canvas nodes have NO interaction logic
+ *
+ * ## Data Flow
+ *
+ * ```
+ *   IR (.vs)                    Renderer AST
+ *   ────────────────────────────────────────────────────────
+ *
+ *   ┌─────────────┐         ┌─────────────────────────────┐
+ *   │  Constraint │         │       RenderableEntity      │
+ *   │    Graph    │   ──▶   │  ┌─────────┐ ┌───────────┐  │
+ *   │  (P-dim)    │         │  │ Canvas  │ │   DOM     │  │
+ *   └─────────────┘         │  │  Node   │ │   Node    │  │
+ *                           │  └─────────┘ └───────────┘  │
+ *                           │       ▲           ▲         │
+ *                           │       └─────┬─────┘         │
+ *                           │         EntityId            │
+ *                           └─────────────────────────────┘
+ * ```
+ */
+/** Unique identifier for all P-dimension entities. */
+export type EntityId = number;
+/** Unique identifier for constraints. */
+export type ConstraintId = number;
+/** Unique identifier for render chunks (for progressive loading). */
+export type ChunkId = string;
+/**
+ * Rational number representation for exact arithmetic.
+ * Used before rasterization to pixel coordinates.
+ */
+export interface Rational {
+    numerator: bigint;
+    denominator: bigint;
+}
+/**
+ * P-dimension vector with exact rational coordinates.
+ * T is included for animation/state-dependent positioning.
+ */
+export interface PVector {
+    x: Rational;
+    y: Rational;
+    z: Rational;
+    t: Rational;
+}
+/**
+ * Rasterized coordinates for actual rendering.
+ * Produced by the topology-preserving rounding algorithm.
+ */
+export interface RasterCoord {
+    /** X in device pixels */
+    x: number;
+    /** Y in device pixels */
+    y: number;
+    /** Z-index for layering */
+    zIndex: number;
+}
+/**
+ * Base interface for all Canvas layer nodes.
+ * These produce wgpu draw commands.
+ */
+export interface CanvasNodeBase {
+    /** Discriminant for node type */
+    readonly kind: string;
+    /** Back-reference to logical entity */
+    entityId: EntityId;
+    /** Pre-rasterization coordinates */
+    bounds: PVectorBounds;
+    /** Rasterized coordinates (computed by rounding algorithm) */
+    rasterBounds: RasterBounds;
+    /** Z-order for painter's algorithm */
+    zOrder: number;
+    /** Chunk this node belongs to (for progressive loading) */
+    chunkId: ChunkId;
+}
+export interface PVectorBounds {
+    topLeft: PVector;
+    bottomRight: PVector;
+}
+export interface RasterBounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Path-based canvas node (curves, shapes).
+ */
+export interface CanvasPathNode extends CanvasNodeBase {
+    kind: 'path';
+    /** SVG-like path commands, pre-compiled */
+    pathData: PathCommand[];
+    /** Fill style (solid, gradient, pattern) */
+    fill: FillStyle | null;
+    /** Stroke style */
+    stroke: StrokeStyle | null;
+}
+export type PathCommand = {
+    type: 'M';
+    x: Rational;
+    y: Rational;
+} | {
+    type: 'L';
+    x: Rational;
+    y: Rational;
+} | {
+    type: 'C';
+    x1: Rational;
+    y1: Rational;
+    x2: Rational;
+    y2: Rational;
+    x: Rational;
+    y: Rational;
+} | {
+    type: 'Q';
+    x1: Rational;
+    y1: Rational;
+    x: Rational;
+    y: Rational;
+} | {
+    type: 'A';
+    rx: Rational;
+    ry: Rational;
+    rotation: number;
+    largeArc: boolean;
+    sweep: boolean;
+    x: Rational;
+    y: Rational;
+} | {
+    type: 'Z';
+};
+export interface FillStyle {
+    type: 'solid' | 'linear-gradient' | 'radial-gradient' | 'pattern';
+    color?: string;
+    stops?: GradientStop[];
+    patternRef?: EntityId;
+}
+export interface GradientStop {
+    offset: Rational;
+    color: string;
+}
+export interface StrokeStyle {
+    color: string;
+    width: Rational;
+    lineCap: 'butt' | 'round' | 'square';
+    lineJoin: 'miter' | 'round' | 'bevel';
+    dashArray?: Rational[];
+}
+/**
+ * Text canvas node.
+ */
+export interface CanvasTextNode extends CanvasNodeBase {
+    kind: 'text';
+    /** Text content (may be Q-dimension bound) */
+    content: string | QDimensionRef;
+    /** Font specification */
+    font: FontSpec;
+    /** Text layout results (computed) */
+    glyphs: GlyphRun[];
+}
+export interface FontSpec {
+    family: string;
+    size: Rational;
+    weight: number;
+    style: 'normal' | 'italic' | 'oblique';
+}
+export interface GlyphRun {
+    glyphIds: number[];
+    positions: RasterCoord[];
+}
+/**
+ * Image canvas node (Q-dimension source).
+ */
+export interface CanvasImageNode extends CanvasNodeBase {
+    kind: 'image';
+    /** Reference to Q-dimension image source */
+    source: QDimensionRef;
+    /** How to fit the image in bounds */
+    fit: 'fill' | 'contain' | 'cover' | 'none';
+}
+/**
+ * Group node for hierarchical transforms.
+ */
+export interface CanvasGroupNode extends CanvasNodeBase {
+    kind: 'group';
+    /** Child nodes */
+    children: CanvasNode[];
+    /** Transform matrix (2D affine) */
+    transform: AffineTransform;
+    /** Clip path (optional) */
+    clipPath?: PathCommand[];
+    /** Opacity (0-1) */
+    opacity: number;
+}
+export interface AffineTransform {
+    a: number;
+    b: number;
+    c: number;
+    d: number;
+    tx: number;
+    ty: number;
+}
+export type CanvasNode = CanvasPathNode | CanvasTextNode | CanvasImageNode | CanvasGroupNode;
+/**
+ * Base interface for all DOM layer nodes.
+ * These produce invisible DOM elements for interaction.
+ */
+export interface DOMNodeBase {
+    /** Discriminant for node type */
+    readonly kind: string;
+    /** Back-reference to logical entity (MUST match CanvasNode if paired) */
+    entityId: EntityId;
+    /** Position synchronized with Canvas layer */
+    rasterBounds: RasterBounds;
+    /** ARIA attributes for accessibility */
+    aria: ARIAAttributes;
+    /** Tab index for keyboard navigation (-1 = not focusable) */
+    tabIndex: number;
+}
+export interface ARIAAttributes {
+    role?: string;
+    label?: string;
+    describedBy?: EntityId;
+    labelledBy?: EntityId;
+    hidden?: boolean;
+    expanded?: boolean;
+    selected?: boolean;
+    checked?: boolean | 'mixed';
+    disabled?: boolean;
+    live?: 'off' | 'polite' | 'assertive';
+}
+/**
+ * Interactive region (clickable, focusable).
+ */
+export interface DOMInteractiveNode extends DOMNodeBase {
+    kind: 'interactive';
+    /** Event bindings (Q-dimension triggers) */
+    events: EventBinding[];
+    /** Cursor style when hovering */
+    cursor: string;
+}
+export interface EventBinding {
+    /** DOM event type */
+    type: 'click' | 'pointerdown' | 'pointerup' | 'pointermove' | 'focus' | 'blur' | 'keydown' | 'keyup';
+    /** Constraint to update on event (T-vector mutation) */
+    targetConstraint: ConstraintId;
+    /** How to compute the new value */
+    valueMapping: EventValueMapping;
+}
+export type EventValueMapping = {
+    type: 'constant';
+    value: Rational;
+} | {
+    type: 'toggle';
+    values: [Rational, Rational];
+} | {
+    type: 'increment';
+    delta: Rational;
+} | {
+    type: 'pointer-x';
+} | {
+    type: 'pointer-y';
+} | {
+    type: 'pointer-delta-x';
+} | {
+    type: 'pointer-delta-y';
+};
+/**
+ * Text input region.
+ */
+export interface DOMInputNode extends DOMNodeBase {
+    kind: 'input';
+    /** Input type */
+    inputType: 'text' | 'number' | 'password' | 'email' | 'search';
+    /** Constraint bound to input value */
+    valueConstraint: ConstraintId;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Max length */
+    maxLength?: number;
+}
+/**
+ * Scroll container region.
+ */
+export interface DOMScrollNode extends DOMNodeBase {
+    kind: 'scroll';
+    /** Scroll direction */
+    direction: 'horizontal' | 'vertical' | 'both';
+    /** Constraints bound to scroll position */
+    scrollXConstraint?: ConstraintId;
+    scrollYConstraint?: ConstraintId;
+    /** Content size (for scrollbar calculation) */
+    contentSize: {
+        width: Rational;
+        height: Rational;
+    };
+}
+/**
+ * Focus trap region (for modals, dialogs).
+ */
+export interface DOMFocusTrapNode extends DOMNodeBase {
+    kind: 'focus-trap';
+    /** First and last focusable children */
+    focusableChildren: EntityId[];
+}
+export type DOMNode = DOMInteractiveNode | DOMInputNode | DOMScrollNode | DOMFocusTrapNode;
+/**
+ * Reference to Q-dimension (unpredictable) data.
+ */
+export interface QDimensionRef {
+    /** Type of Q-dimension source */
+    type: 'user-input' | 'fetch' | 'image' | 'video' | 'audio' | 'shader' | 'time';
+    /** Source identifier */
+    sourceId: string;
+    /** Current value (runtime state, not in IR) */
+    currentValue?: unknown;
+}
+/**
+ * A complete renderable entity combining Canvas and DOM representations.
+ *
+ * ## Pairing Rules
+ *
+ * | Entity Type     | Canvas Node | DOM Node    |
+ * |-----------------|-------------|-------------|
+ * | Static shape    | Required    | None        |
+ * | Button          | Required    | Required    |
+ * | Text input      | Required    | Required    |
+ * | Decorative img  | Required    | None        |
+ * | Interactive img | Required    | Required    |
+ * | Scroll area     | Optional    | Required    |
+ * | Focus trap      | None        | Required    |
+ */
+export interface RenderableEntity {
+    /** Unique identifier */
+    id: EntityId;
+    /** Human-readable name (for debugging) */
+    name?: string;
+    /** Canvas layer representation (visual) */
+    canvas: CanvasNode | null;
+    /** DOM layer representation (interactive) */
+    dom: DOMNode | null;
+    /** Constraints that affect this entity */
+    dependentConstraints: ConstraintId[];
+    /** Entities that this entity references */
+    referencedEntities: EntityId[];
+    /** Chunk membership */
+    chunkId: ChunkId;
+}
+/**
+ * The complete render tree produced by the compiler.
+ */
+export interface RenderTree {
+    /** All renderable entities, indexed by EntityId */
+    entities: Map<EntityId, RenderableEntity>;
+    /** Root entity IDs (top-level elements) */
+    roots: EntityId[];
+    /** Chunk definitions for progressive loading */
+    chunks: Map<ChunkId, Chunk>;
+    /** Viewport configuration */
+    viewport: ViewportConfig;
+    /** Device pixel ratio for rasterization */
+    devicePixelRatio: number;
+}
+export interface Chunk {
+    id: ChunkId;
+    /** Entities in this chunk */
+    entityIds: EntityId[];
+    /** Dependencies on other chunks */
+    dependsOn: ChunkId[];
+    /** Is this the initial chunk? */
+    isInitial: boolean;
+    /** Trigger conditions for lazy loading */
+    loadTriggers: LoadTrigger[];
+}
+export type LoadTrigger = {
+    type: 'immediate';
+} | {
+    type: 'viewport-intersect';
+    entityId: EntityId;
+} | {
+    type: 'event';
+    eventType: string;
+    targetEntity: EntityId;
+} | {
+    type: 'constraint-change';
+    constraintId: ConstraintId;
+};
+export interface ViewportConfig {
+    width: Rational;
+    height: Rational;
+    unitsPerPixel: Rational;
+}

package/dist/ast/types.js

@@ -0,0 +1,33 @@
+/**
+ * ViewScript Renderer AST: Bilayer Orthogonal Architecture
+ *
+ * This module defines the type system for the dual-layer rendering model:
+ * - Canvas Layer: Visual representation (wgpu draw commands)
+ * - DOM Layer: Interaction regions (accessibility, events, focus)
+ *
+ * ## Architectural Invariants
+ *
+ * 1. Every logical entity has exactly one EntityId
+ * 2. An entity MAY have a CanvasNode (visual), a DOMNode (interactive), or both
+ * 3. Canvas and DOM nodes are synchronized via shared EntityId
+ * 4. DOM nodes have NO visual properties; Canvas nodes have NO interaction logic
+ *
+ * ## Data Flow
+ *
+ * ```
+ *   IR (.vs)                    Renderer AST
+ *   ────────────────────────────────────────────────────────
+ *
+ *   ┌─────────────┐         ┌─────────────────────────────┐
+ *   │  Constraint │         │       RenderableEntity      │
+ *   │    Graph    │   ──▶   │  ┌─────────┐ ┌───────────┐  │
+ *   │  (P-dim)    │         │  │ Canvas  │ │   DOM     │  │
+ *   └─────────────┘         │  │  Node   │ │   Node    │  │
+ *                           │  └─────────┘ └───────────┘  │
+ *                           │       ▲           ▲         │
+ *                           │       └─────┬─────┘         │
+ *                           │         EntityId            │
+ *                           └─────────────────────────────┘
+ * ```
+ */
+export {};

package/dist/compiler/chunk-splitter.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Chunk Splitting Strategy for Progressive Loading
+ *
+ * This module implements static analysis to partition the constraint graph
+ * into Initial and Lazy chunks, enabling Qwik/Wiz-style progressive hydration.
+ *
+ * ## Core Principle: T-Vector Reachability Analysis
+ *
+ * An entity belongs to the Initial Chunk if and only if:
+ * 1. It is visible at T=0 (initial render time), AND
+ * 2. It is reachable from the viewport bounds at T=0
+ *
+ * An entity belongs to a Lazy Chunk if:
+ * 1. It becomes visible only after T changes (user interaction), OR
+ * 2. It is outside the initial viewport (below the fold), OR
+ * 3. It depends on Q-dimension data that hasn't loaded yet
+ *
+ * ## Algorithm Overview
+ *
+ * ```
+ * INPUT: Constraint Graph G = (Entities, Constraints)
+ *        Viewport V = (width, height)
+ *        Initial Time T₀ = 0
+ *
+ * OUTPUT: Partition P = { Chunk₀ (initial), Chunk₁, Chunk₂, ... }
+ *
+ * ALGORITHM:
+ * 1. Evaluate all constraints at T=T₀ to get initial positions
+ * 2. Mark entities intersecting V as "initially visible"
+ * 3. For each Q-dimension binding (event handler):
+ *    a. Trace which constraints are affected when event fires
+ *    b. Group affected entities into event-specific lazy chunks
+ * 4. For entities below the fold:
+ *    a. Create viewport-intersection lazy chunks
+ * 5. Compute chunk dependency DAG
+ * ```
+ */
+import type { EntityId, ConstraintId, ChunkId, Chunk, Rational } from '../ast/types';
+interface IRConstraint {
+    id: ConstraintId;
+    target: EntityId;
+    component: 'x' | 'y' | 'z' | 't';
+    relation: 'eq' | 'lt' | 'le' | 'gt' | 'ge';
+    term: IRConstraintTerm;
+}
+type IRConstraintTerm = {
+    type: 'const';
+    value: Rational;
+} | {
+    type: 'ref';
+    entityId: EntityId;
+    component: 'x' | 'y' | 'z' | 't';
+} | {
+    type: 'linear';
+    coefficient: Rational;
+    entityId: EntityId;
+    component: 'x' | 'y' | 'z' | 't';
+    offset: Rational;
+};
+interface IRModule {
+    entities: EntityId[];
+    constraints: IRConstraint[];
+    eventBindings: EventBinding[];
+    imports: IRImport[];
+}
+interface EventBinding {
+    sourceEntity: EntityId;
+    eventType: string;
+    targetConstraint: ConstraintId;
+}
+interface IRImport {
+    path: string;
+    exportedEntities: EntityId[];
+}
+interface ViewportBounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Static analysis result for chunk splitting.
+ */
+export interface ChunkSplitResult {
+    /** The initial chunk (loaded immediately) */
+    initialChunk: Chunk;
+    /** Lazy chunks (loaded on demand) */
+    lazyChunks: Chunk[];
+    /** Mapping from entity to chunk */
+    entityToChunk: Map<EntityId, ChunkId>;
+    /** Chunk dependency DAG */
+    chunkDependencies: Map<ChunkId, Set<ChunkId>>;
+}
+/**
+ * Main chunk splitting function.
+ */
+export declare function splitIntoChunks(ir: IRModule, viewport: ViewportBounds): ChunkSplitResult;
+export {};