@vectojs/core 0.1.0 → 0.2.0

package/dist/layout/LayoutWorkerSource.d.ts

@@ -0,0 +1 @@
+export declare const WORKER_SOURCE_STRING = "\"use strict\";(()=>{var b=new Map;self.onmessage=x=>{let{id:S,seqId:k,text:A,fontId:i,fontData:c,maxWidth:d,maxHeight:H,fontSize:o,lineHeight:F,letterSpacing:C}=x.data;c&&b.set(i,c);let n=b.get(i);if(!n)return;let f=[],u=[],y=[],l=[],e=0,r=0,h=n.metrics?.ascender??.8,D=n.metrics?.descender??-.2,m=F??o*(h-D),p=Array.from(A);for(let s=0;s<p.length;s++){let a=p[s].codePointAt(0),g=(n.glyphs?.find(w=>w.unicode===a)?.advance??1)*o;e+g>d&&a===32&&(e=0,r++),f.push(a),u.push(e);let M=r*m+h*o;y.push(M),l.push(-256),e+=g+(C??0)}let t={id:S,seqId:k,width:Math.min(e,d),height:(r+1)*m,codePoints:new Uint32Array(f),xCoords:new Float32Array(u),yCoords:new Float32Array(y),packedStyles:new Uint32Array(l)};self.postMessage(t,[t.codePoints.buffer,t.xCoords.buffer,t.yCoords.buffer,t.packedStyles.buffer])};})();\n";

package/dist/layout/index.d.ts

@@ -0,0 +1,3 @@
+export * from './LayoutEngine';
+export * from './LayoutWorkerManager';
+export * from './measure';

package/dist/layout/measure.d.ts

@@ -0,0 +1,20 @@
+import type { GlyphMeasurer } from './LayoutEngine';
+/**
+ * Create a {@link GlyphMeasurer} backed by a single lazily-created offscreen
+ * Canvas 2D context.
+ *
+ * Each grapheme is measured once at `baseSize` and cached; because canvas
+ * `measureText` advance width is linear in font size, later queries at any
+ * `fontSize` are derived by pure arithmetic (no re-measure). This gives the
+ * {@link LayoutEngine} real per-glyph metrics for text that has no pre-baked
+ * vector atlas, fixing the coarse `0.5em` line-breaking fallback.
+ *
+ * Returns `null` in DOM-free environments (SSR, workers without a canvas) so
+ * callers stay portable and the engine keeps its `0.5em` fallback.
+ *
+ * @param fontFamily - CSS font family used for measurement; should match what
+ *   the renderer actually draws (e.g. `TextEntity` falls back to `sans-serif`).
+ * @param baseSize - Pixel size at which each glyph is measured and cached.
+ * @returns A measurer, or `null` when no Canvas 2D context is available.
+ */
+export declare function createCanvasMeasurer(fontFamily?: string, baseSize?: number): GlyphMeasurer | null;

package/dist/math/SpatialHashGrid.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Fixed-cell Spatial Hash Grid for O(1) average-case AABB neighbor queries.
+ * Insert entities each frame, then query by AABB to find nearby entity IDs.
+ */
+export declare class SpatialHashGrid {
+    private cellSize;
+    private grid;
+    private entityCells;
+    constructor(cellSize?: number);
+    private hash;
+    private cellsForAABB;
+    /**
+     * Insert or update an entity's axis-aligned bounding box in the grid.
+     *
+     * If the entity is already registered its old cell memberships are removed
+     * before the new ones are computed, so this method is safe to call every
+     * frame.
+     *
+     * @param id - Unique string identifier for the entity.
+     * @param x - Left edge of the AABB in world space.
+     * @param y - Top edge of the AABB in world space.
+     * @param w - Width of the AABB.
+     * @param h - Height of the AABB.
+     */
+    insert(id: string, x: number, y: number, w: number, h: number): void;
+    /**
+     * Remove an entity from all grid cells it currently occupies.
+     *
+     * Silently does nothing if the entity is not registered.
+     *
+     * @param id - Unique string identifier of the entity to remove.
+     */
+    remove(id: string): void;
+    /**
+     * Return all entity IDs whose grid cells overlap the given AABB.
+     *
+     * Time complexity: O(k) where k is the number of cells the query AABB spans
+     * plus the number of results — O(1) average for small, similarly-sized entities.
+     *
+     * @param x - Left edge of the query AABB.
+     * @param y - Top edge of the query AABB.
+     * @param w - Width of the query AABB.
+     * @param h - Height of the query AABB.
+     * @returns A `Set` of entity ID strings whose cells intersect the query region.
+     */
+    query(x: number, y: number, w: number, h: number): Set<string>;
+    /**
+     * Clear all cells and entity registrations, resetting the grid to an empty state.
+     *
+     * Call once per frame before re-inserting all dynamic entities.
+     */
+    clear(): void;
+}

package/dist/math/SpringPhysics.d.ts

@@ -0,0 +1,13 @@
+export declare class SpringPhysics {
+    value: number;
+    target: number;
+    velocity: number;
+    stiffness: number;
+    damping: number;
+    mass: number;
+    private readonly valEpsilon;
+    private readonly velEpsilon;
+    constructor(initial: number);
+    update(dt: number): void;
+    isAtRest(): boolean;
+}

package/dist/renderer/CanvasRenderer.d.ts

@@ -0,0 +1,81 @@
+import { IRenderer } from './IRenderer';
+export declare class CanvasRenderer implements IRenderer {
+    private ctx;
+    private width;
+    private height;
+    /**
+     * Max circles per batched `fill()`. A single Canvas 2D `fill()` over a path is
+     * superlinear in sub-path count, so an unbounded batch is *slower* than many
+     * small fills at high entity counts. Capping bounds each fill's path
+     * complexity while still amortizing per-draw overhead. Tuned via the benchmark.
+     */
+    static readonly MAX_BATCH = 64;
+    private batchActive;
+    private batchColor;
+    private batchAlpha;
+    private batchCount;
+    constructor(canvas: HTMLCanvasElement);
+    /**
+     * Expose the underlying `CanvasRenderingContext2D` for operations not
+     * covered by the {@link IRenderer} interface.
+     *
+     * @returns The raw 2D rendering context.
+     */
+    getContext(): CanvasRenderingContext2D;
+    /**
+     * Resize the backing canvas buffer and re-apply DPR scaling.
+     *
+     * Called automatically by {@link Scene} on `window.resize` events.
+     *
+     * @param width - New logical width in CSS pixels.
+     * @param height - New logical height in CSS pixels.
+     */
+    resize(width: number, height: number): void;
+    /** @inheritdoc */
+    clear(): void;
+    /** @inheritdoc */
+    save(): void;
+    /** @inheritdoc */
+    restore(): void;
+    /** @inheritdoc */
+    translate(x: number, y: number): void;
+    /** @inheritdoc */
+    scale(x: number, y: number): void;
+    /** @inheritdoc */
+    rotate(angle: number): void;
+    /** @inheritdoc */
+    setGlobalAlpha(alpha: number): void;
+    /** @inheritdoc */
+    clip(x: number, y: number, width: number, height: number): void;
+    /** @inheritdoc */
+    beginPath(): void;
+    /** @inheritdoc */
+    moveTo(x: number, y: number): void;
+    /** @inheritdoc */
+    lineTo(x: number, y: number): void;
+    /** @inheritdoc */
+    bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, y: number): void;
+    /** @inheritdoc */
+    closePath(): void;
+    /** @inheritdoc */
+    arc(x: number, y: number, radius: number, startAngle: number, endAngle: number, counterclockwise?: boolean): void;
+    /** @inheritdoc */
+    roundRect(x: number, y: number, width: number, height: number, radii: number | number[]): void;
+    /** @inheritdoc */
+    drawImage(source: CanvasImageSource, dx: number, dy: number, dw: number, dh: number): void;
+    /** @inheritdoc */
+    fillCircle(cx: number, cy: number, radius: number, color: string, alpha?: number): void;
+    /** @inheritdoc */
+    flush(): void;
+    /** @inheritdoc */
+    fill(color: string | any): void;
+    /** @inheritdoc */
+    stroke(color: string | any, lineWidth?: number): void;
+    /** @inheritdoc */
+    fillText(text: string, x: number, y: number, font: string, color: string | any): void;
+    /** @inheritdoc */
+    createLinearGradient(x0: number, y0: number, x1: number, y1: number, colorStops: {
+        stop: number;
+        color: string;
+    }[]): any;
+}

package/dist/renderer/IRenderer.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Renderer abstraction consumed by every {@link Entity}.
+ *
+ * Implementations wrap a concrete drawing backend (Canvas 2D, WebGL, …) and
+ * expose a path-based drawing API.  Entities must only depend on `IRenderer`
+ * so they remain backend-agnostic.
+ *
+ * @example
+ * // Inside an Entity.render() implementation:
+ * render(r: IRenderer) {
+ *   r.beginPath();
+ *   r.fill('#38bdf8');
+ * }
+ */
+export interface IRenderer {
+    /** Clear the entire drawing surface to transparent / background color. */
+    clear(): void;
+    /** Push the current transform + state onto the renderer's stack. */
+    save(): void;
+    /** Pop the last saved transform + state from the renderer's stack. */
+    restore(): void;
+    /**
+     * Apply a translation to the current transform matrix.
+     *
+     * @param x - Horizontal offset in pixels.
+     * @param y - Vertical offset in pixels.
+     */
+    translate(x: number, y: number): void;
+    /**
+     * Apply a scale to the current transform matrix.
+     *
+     * @param x - Horizontal scale factor.
+     * @param y - Vertical scale factor.
+     */
+    scale(x: number, y: number): void;
+    /**
+     * Apply a clockwise rotation to the current transform matrix.
+     *
+     * @param angle - Rotation angle in radians.
+     */
+    rotate(angle: number): void;
+    /**
+     * Set the global opacity applied to all subsequent draw calls.
+     *
+     * @param alpha - Opacity in the range `[0, 1]`.
+     */
+    setGlobalAlpha(alpha: number): void;
+    /**
+     * Intersect the current clip region with a rectangle. Affects all subsequent
+     * draws until the next {@link restore}; wrap in {@link save}/{@link restore}.
+     *
+     * @param x - Left edge.
+     * @param y - Top edge.
+     * @param width - Rectangle width.
+     * @param height - Rectangle height.
+     */
+    clip(x: number, y: number, width: number, height: number): void;
+    /** Begin a new sub-path, discarding the current path. */
+    beginPath(): void;
+    /**
+     * Move the pen to the given point without drawing a line.
+     *
+     * @param x - Target X coordinate.
+     * @param y - Target Y coordinate.
+     */
+    moveTo(x: number, y: number): void;
+    /**
+     * Add a straight line segment from the current pen position to the given point.
+     *
+     * @param x - Target X coordinate.
+     * @param y - Target Y coordinate.
+     */
+    lineTo(x: number, y: number): void;
+    /**
+     * Add a cubic Bézier curve to the current path.
+     *
+     * @param cp1x - X of the first control point.
+     * @param cp1y - Y of the first control point.
+     * @param cp2x - X of the second control point.
+     * @param cp2y - Y of the second control point.
+     * @param x - X of the end point.
+     * @param y - Y of the end point.
+     */
+    bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, y: number): void;
+    /** Close the current sub-path by drawing a line back to its starting point. */
+    closePath(): void;
+    /**
+     * Add a circular arc to the current path.
+     *
+     * @param x - X of the arc center.
+     * @param y - Y of the arc center.
+     * @param radius - Arc radius in pixels.
+     * @param startAngle - Start angle in radians (0 = 3 o'clock).
+     * @param endAngle - End angle in radians.
+     * @param counterclockwise - If `true`, draws the arc counter-clockwise.
+     */
+    arc(x: number, y: number, radius: number, startAngle: number, endAngle: number, counterclockwise?: boolean): void;
+    /**
+     * Add a rounded rectangle to the current path.
+     *
+     * @param x - Left edge.
+     * @param y - Top edge.
+     * @param width - Rectangle width.
+     * @param height - Rectangle height.
+     * @param radii - Corner radius (uniform) or per-corner array as accepted by `CanvasRenderingContext2D.roundRect()`.
+     */
+    roundRect(x: number, y: number, width: number, height: number, radii: number | number[]): void;
+    /**
+     * Draw an image or video frame into the canvas.
+     *
+     * @param source - The image source (HTMLImageElement, HTMLVideoElement, HTMLCanvasElement, etc.).
+     * @param dx - Destination X.
+     * @param dy - Destination Y.
+     * @param dw - Destination width.
+     * @param dh - Destination height.
+     */
+    drawImage(source: CanvasImageSource, dx: number, dy: number, dw: number, dh: number): void;
+    /**
+     * Fill the current path with the given color or gradient.
+     *
+     * @param colorOrGradient - CSS color string or a gradient object.
+     */
+    fill(colorOrGradient: string | any): void;
+    /**
+     * Stroke the current path with the given color or gradient.
+     *
+     * @param colorOrGradient - CSS color string or a gradient object.
+     * @param lineWidth - Stroke width in pixels (default: `1`).
+     */
+    stroke(colorOrGradient: string | any, lineWidth?: number): void;
+    /**
+     * Render a text string at the given position.
+     *
+     * @param text - The string to draw.
+     * @param x - Left edge of the text baseline.
+     * @param y - Baseline Y coordinate.
+     * @param font - CSS font shorthand, e.g. `'16px monospace'`.
+     * @param color - CSS color string or gradient.
+     */
+    fillText(text: string, x: number, y: number, font: string, color: string | any): void;
+    /**
+     * Draw a filled circle through the order-preserving batch.
+     *
+     * Consecutive calls sharing the same `color` and `alpha` are coalesced into a
+     * single path and committed with one `fill()` on {@link flush} (or when the
+     * style changes / another draw call intervenes). Coordinates are in the
+     * current transform space. This collapses the per-entity
+     * `beginPath`/`arc`/`fill` of large point clouds into a handful of draw calls
+     * while preserving painter's-order semantics.
+     *
+     * @param cx - Center X in the current transform space.
+     * @param cy - Center Y in the current transform space.
+     * @param radius - Circle radius.
+     * @param color - CSS color string.
+     * @param alpha - Opacity in `[0, 1]` (default `1`).
+     */
+    fillCircle(cx: number, cy: number, radius: number, color: string, alpha?: number): void;
+    /**
+     * Commit any pending batched draws (see {@link fillCircle}). Safe to call when
+     * no batch is active (no-op). The {@link Scene} flushes at the end of each
+     * sibling group and frame.
+     */
+    flush(): void;
+    /**
+     * Create a linear gradient between two points with the given color stops.
+     *
+     * @param x0 - X of the gradient start point.
+     * @param y0 - Y of the gradient start point.
+     * @param x1 - X of the gradient end point.
+     * @param y1 - Y of the gradient end point.
+     * @param colorStops - Array of `{ stop, color }` pairs where `stop` is in `[0, 1]`.
+     * @returns An opaque gradient object suitable for {@link fill} or {@link stroke}.
+     */
+    createLinearGradient(x0: number, y0: number, x1: number, y1: number, colorStops: {
+        stop: number;
+        color: string;
+    }[]): any;
+}

package/dist/renderer/SVGRenderer.d.ts

@@ -0,0 +1,69 @@
+import { IRenderer } from './IRenderer';
+export interface SVGLinearGradient {
+    type: 'linear';
+    id?: string;
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+    colorStops: {
+        stop: number;
+        color: string;
+    }[];
+    createMatrix: number[];
+}
+export declare class SVGRenderer implements IRenderer {
+    private width;
+    private height;
+    private buffer;
+    private defsBuffer;
+    private currentPath;
+    private mStack;
+    private ma;
+    private mb;
+    private mc;
+    private md;
+    private me;
+    private mf;
+    private alphaStack;
+    private globalAlpha;
+    private clipDepthStack;
+    private clipDepth;
+    private clipCounter;
+    private batchCircles;
+    private batchMatrix;
+    private batchColor;
+    private batchAlpha;
+    private batchActive;
+    private gradientCounter;
+    private gradientCache;
+    constructor(width: number, height: number);
+    clear(): void;
+    save(): void;
+    restore(): void;
+    translate(dx: number, dy: number): void;
+    scale(sx: number, sy: number): void;
+    rotate(angle: number): void;
+    setGlobalAlpha(alpha: number): void;
+    beginPath(): void;
+    moveTo(x: number, y: number): void;
+    lineTo(x: number, y: number): void;
+    bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, y: number): void;
+    closePath(): void;
+    arc(x: number, y: number, r: number, startAngle: number, endAngle: number, ccw?: boolean): void;
+    roundRect(x: number, y: number, w: number, h: number, radii: number | number[]): void;
+    fill(colorOrGradient: string | SVGLinearGradient): void;
+    stroke(colorOrGradient: string | SVGLinearGradient, lineWidth?: number): void;
+    fillText(text: string, x: number, y: number, font: string, color: string | SVGLinearGradient): void;
+    fillCircle(cx: number, cy: number, radius: number, color: string, alpha?: number): void;
+    drawImage(source: any, dx: number, dy: number, dw: number, dh: number): void;
+    flush(): void;
+    createLinearGradient(x0: number, y0: number, x1: number, y1: number, colorStops: {
+        stop: number;
+        color: string;
+    }[]): SVGLinearGradient;
+    clip(x: number, y: number, width: number, height: number): void;
+    toXMLString(): string;
+    private resolveGradient;
+    private escapeXML;
+}

package/dist/renderer/WebGLPointRenderer.d.ts

@@ -0,0 +1,62 @@
+/**
+ * A GPU-accelerated layer that draws large sets of circles and rectangles in a
+ * couple of draw calls. Used by {@link Scene} (via `pointBackend: 'webgl'`) to
+ * render `getBatchCircle()` / `getBatchRect()` entities — the point-cloud /
+ * particle case where Canvas2D tops out at ~7 fps for 100k primitives.
+ */
+export interface PointRenderer {
+    /** Resize the backing buffer + GL viewport to a logical `w × h` (DPR applied). */
+    resize(width: number, height: number): void;
+    /** Begin a frame: reset the accumulated primitive buffers. */
+    begin(): void;
+    /** Add one circle in world (CSS-pixel) coordinates; `alpha` multiplies the color's. */
+    addCircle(x: number, y: number, radius: number, color: string, alpha?: number): void;
+    /**
+     * Add one rectangle: top-left at world `(x, y)`, `width × height` in world units,
+     * rotated `rotation` radians about `(x, y)`; `alpha` multiplies the color's.
+     */
+    addRect(x: number, y: number, width: number, height: number, color: string, alpha?: number, rotation?: number): void;
+    /**
+     * Upload a texture atlas used by {@link addSprite}. Pass any `TexImageSource`
+     * (HTMLImageElement, HTMLCanvasElement, ImageBitmap, …). Call once (or whenever
+     * the atlas changes) before adding sprites.
+     */
+    setTexture(source: TexImageSource): void;
+    /**
+     * Add one textured sprite sampling the atlas region `[u0,v0]–[u1,v1]` (UVs in
+     * `0..1`): top-left at world `(x, y)`, `width × height` in world units, rotated
+     * `rotation` radians about `(x, y)`. `color` multiplies the sampled texel
+     * (white = unchanged; use it to tint white glyphs); `alpha` multiplies further.
+     * No-op until a texture is set via {@link setTexture}.
+     */
+    addSprite(x: number, y: number, width: number, height: number, u0: number, v0: number, u1: number, v1: number, color?: string, alpha?: number, rotation?: number): void;
+    /**
+     * Upload an MSDF (multi-channel signed distance field) glyph atlas used by
+     * {@link addGlyph}, kept separate from the {@link setTexture} atlas so both can
+     * be active. `distanceRange` is the field's pixel range (the atlas JSON's
+     * `atlas.distanceRange`) — it drives the shader's edge sharpness. Pair with
+     * `MSDFFont.layout` to position the glyphs.
+     */
+    setMSDFTexture(source: TexImageSource, distanceRange: number): void;
+    /**
+     * Add one MSDF glyph quad sampling `[u0,v0]–[u1,v1]` (UVs in `0..1`): top-left
+     * at world `(x, y)`, `width × height` in world units. The fragment shader
+     * reconstructs a crisp, resolution-independent edge from the distance field, so
+     * glyphs stay sharp at any scale. `color` tints the glyph (default white);
+     * `alpha` multiplies coverage. No-op until {@link setMSDFTexture} is called.
+     */
+    addGlyph(x: number, y: number, width: number, height: number, u0: number, v0: number, u1: number, v1: number, color?: string, alpha?: number, rotation?: number): void;
+    /** Clear the layer and draw all accumulated primitives. */
+    flush(): void;
+    /** Release GL resources. */
+    destroy(): void;
+}
+/**
+ * Create a WebGL2-backed {@link PointRenderer} on `canvas`, or `null` when WebGL2
+ * (or shader compilation) is unavailable — callers fall back to Canvas2D.
+ *
+ * @param canvas - A dedicated canvas (WebGL2 context); should be stacked over the
+ *   scene's 2D canvas.
+ * @returns A point renderer, or `null` if WebGL2 isn't supported.
+ */
+export declare function createWebGLPointRenderer(canvas: HTMLCanvasElement): PointRenderer | null;

package/dist/renderer/WebGPUParticleSystemManager.d.ts

@@ -0,0 +1,14 @@
+import { ComputeParticleEntity } from '../tree/ComputeParticleEntity';
+export declare class WebGPUParticleSystemManager {
+    private device;
+    private computePipeline;
+    private renderPipeline;
+    private computeBindGroupLayout;
+    private renderBindGroupLayout;
+    constructor(device: GPUDevice);
+    initPipelines(format: GPUTextureFormat): void;
+    setupEntityResources(entity: ComputeParticleEntity): void;
+    recordComputePass(pass: GPUComputePassEncoder, entity: ComputeParticleEntity, dt: number, mouseX: number, mouseY: number, width: number, height: number): void;
+    recordRenderPass(pass: GPURenderPassEncoder, entity: ComputeParticleEntity): void;
+    destroy(): void;
+}

package/dist/renderer/colorParse.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Parsed color as normalized `[r, g, b, a]` floats in `[0, 1]`.
+ */
+export type RGBA = [number, number, number, number];
+/**
+ * Parse a CSS color string into normalized `[r, g, b, a]` floats.
+ *
+ * Fast paths handle `#rgb`/`#rgba`/`#rrggbb`/`#rrggbbaa` and `rgb()`/`rgba()`;
+ * other forms (named colors, `hsl()`, …) resolve via a cached 1×1 canvas when a
+ * DOM is available. Results are cached per input string and shared by identity,
+ * so callers must treat the returned array as read-only. Unparseable input with
+ * no DOM yields opaque black `[0, 0, 0, 1]`.
+ *
+ * @param css - A CSS color string, e.g. `'#38bdf8'` or `'rgba(0,0,0,.5)'`.
+ * @returns The cached `[r, g, b, a]` tuple in `[0, 1]`.
+ */
+export declare function parseColorToRGBA(css: string): RGBA;

package/dist/renderer/index.d.ts

@@ -0,0 +1,6 @@
+export * from './CanvasRenderer';
+export * from './SVGRenderer';
+export * from './WebGLPointRenderer';
+export * from './WebGPUParticleSystemManager';
+export * from './IRenderer';
+export * from './colorParse';

package/dist/text/ArabicShaper.d.ts

@@ -0,0 +1,10 @@
+export interface ShapedResult {
+    shapedText: string;
+    indexMap: Int32Array;
+}
+export declare class ArabicShaper {
+    private static MAPPINGS;
+    private static isHarakat;
+    private static getJoiningType;
+    static shapeArabic(text: string): ShapedResult;
+}

package/dist/text/BidiResolver.d.ts

@@ -0,0 +1,6 @@
+export declare class BidiResolver {
+    private static getDirectionClass;
+    static getBaseLevel(text: string): number;
+    static resolveLevels(text: string): Uint8Array;
+    static reorderVisual(nodes: any[], baseLevel: number): void;
+}