@vectojs/core 0.1.0 → 0.2.1

package/dist/index.d.mts

@@ -1,577 +0,0 @@
-import { E as Entity, I as IRenderer, B as Bounds } from './Entity-D-rfAFCf.mjs';
-export { A as A11yAttributes, a as BatchCircle, b as BatchRect, L as ListenerOptions, P as Point, V as VectoEvent, c as VectoJSEvent } from './Entity-D-rfAFCf.mjs';
-export { C as CanvasRenderer, a as ComputeParticleEntity, b as ComputeParticleOptions, P as PARTICLE_OFFSET_LIFE, c as PARTICLE_OFFSET_ORIGIN_X, d as PARTICLE_OFFSET_ORIGIN_Y, e as PARTICLE_OFFSET_POSITION_X, f as PARTICLE_OFFSET_POSITION_Y, g as PARTICLE_OFFSET_SIZE, h as PARTICLE_OFFSET_VELOCITY_X, i as PARTICLE_OFFSET_VELOCITY_Y, j as PARTICLE_STRIDE_FLOATS, k as PointRenderer, R as RGBA, S as SVGLinearGradient, l as SVGRenderer, W as WebGPUParticleSystemManager, m as createWebGLPointRenderer, p as parseColorToRGBA } from './index-ByBDSmMK.mjs';
-export { ExclusionRect, GlyphAtlas, GlyphMeasurer, LayoutEngine, LayoutNode, LayoutResult, LayoutResultBuffer, LayoutWorkerManager, LineSegment, PreparedGlyph, PreparedParagraph, PreparedText, PreparedWord, StyledSpan, TextStyle, computeLineSegments, createCanvasMeasurer } from './layout.mjs';
-export { ArabicShaper, BidiResolver, MSDFAtlasInfo, MSDFBounds, MSDFFont, MSDFFontData, MSDFGlyphDef, MSDFKerning, MSDFLayoutOptions, MSDFLayoutResult, MSDFMetrics, MSDFTextEntity, MSDFTextEntityOptions, PositionedGlyph, SVGEntity, ShapedResult } from './text.mjs';
-
-interface IWebGLPointRenderer {
-    resize(width: number, height: number): void;
-}
-type WebGLPointRendererCreator = (canvas: HTMLCanvasElement) => any;
-interface IWebGPUParticleSystemManager {
-    new (device: GPUDevice): any;
-    initPipelines(format: GPUTextureFormat): Promise<void> | void;
-    setupEntityResources(entity: any): void;
-    recordComputePass(pass: GPUComputePassEncoder, entity: any, dt: number, mouseX: number, mouseY: number, width: number, height: number): void;
-    recordRenderPass(renderPassEncoder: GPURenderPassEncoder, entity: any): void;
-    destroy(): void;
-}
-
-/**
- * Options for {@link Scene}.
- */
-interface SceneOptions {
-    /**
-     * Backend for `getBatchCircle()` point-cloud entities:
-     * - `'canvas'` (default): the Canvas2D order-preserving same-color batch.
-     * - `'webgl'`: a stacked WebGL2 layer drawing all such circles in one draw
-     *   call (10–100× throughput for 100k+). Auto-falls back to `'canvas'` when
-     *   WebGL2 is unavailable. The GL layer composites above the 2D content, so its
-     *   points don't interleave per-entity with 2D draws.
-     */
-    pointBackend?: 'canvas' | 'webgl';
-    /**
-     * Backend for particle simulation and rendering:
-     * - `'auto'` (default): tries WebGPU first, falls back to CPU if WebGPU is unavailable or fails.
-     * - `'webgpu'`: forces WebGPU.
-     * - `'cpu'`: forces CPU simulation and rendering (disabling WebGPU completely).
-     */
-    particleBackend?: 'auto' | 'webgpu' | 'cpu';
-    /**
-     * Render the accessibility/automation shadow nodes with a visible blue dashed
-     * outline (development aid). Default `false`: shadow nodes are transparent
-     * (`opacity:0`) — still operable by Playwright/assistive tech, but the canvas
-     * is the only thing seen.
-     */
-    debugA11y?: boolean;
-    /**
-     * Cap the render loop to at most this many frames per second (power saving —
-     * e.g. a quieter fan in a library). `0` (default) means uncapped (native
-     * refresh rate). Continuous animations still run, just less often. Also
-     * settable later via {@link Scene.maxFPS}.
-     */
-    maxFPS?: number;
-    /**
-     * When `true` (default), a system **prefers-reduced-motion** setting auto-caps
-     * the loop to {@link REDUCED_MOTION_FPS} (or the lower of that and `maxFPS`).
-     * Set `false` to ignore the OS setting.
-     */
-    respectReducedMotion?: boolean;
-    /**
-     * Throttle the accessibility/automation shadow-DOM sync to at most once per this
-     * many milliseconds. `0` (default) syncs every rendered frame. During heavy
-     * animation, a small value (e.g. `100`) keeps the a11y layer eventually
-     * consistent while sparing the per-frame DOM writes that can drag Canvas FPS.
-     * Also settable later via {@link Scene.a11ySyncInterval}.
-     */
-    a11ySyncInterval?: number;
-    /**
-     * Custom renderer implementation (e.g., ThreeRenderer from @vectojs/three).
-     * If provided, this renderer will be used for drawing rather than the default CanvasRenderer.
-     */
-    renderer?: IRenderer;
-    /**
-     * Disable the automatic registration of window resize listener.
-     * Useful when Vecto is running inside a custom layout container or offscreen canvas.
-     */
-    disableWindowResize?: boolean;
-}
-/** Frame-rate the loop is capped to when the OS requests reduced motion. */
-declare const REDUCED_MOTION_FPS = 30;
-interface A11yTreeNode {
-    id: string;
-    tag: string;
-    role?: string;
-    label?: string;
-    value?: string;
-    checked?: boolean;
-    expanded?: boolean;
-    valuemin?: string;
-    valuemax?: string;
-    children: A11yTreeNode[];
-}
-/**
- * Top-level orchestrator that owns the entity tree, drive the render loop,
- * and maintains the accessibility/automation shadow layer.
- *
- * Create one `Scene` per `<canvas>` element.  Add {@link Entity} objects via
- * {@link add}, then call {@link start} to begin the 60-FPS render loop.
- *
- * @example
- * const scene = new Scene(document.querySelector('canvas')!);
- * scene.add(new CircleEntity().setPosition(100, 100));
- * scene.start();
- */
-declare class Scene {
-    private static webglCreator;
-    private static webgpuManagerClass;
-    static registerWebGLPointRendererCreator(creator: WebGLPointRendererCreator): void;
-    static registerWebGPUParticleSystemManager(managerClass: any): void;
-    private root;
-    overlayRoot: Entity;
-    private renderer;
-    private isRunning;
-    private lastTime;
-    canvas: HTMLCanvasElement;
-    /**
-     * Redraw strategy:
-     * - `'always'` (default): re-render every animation frame (legacy behavior).
-     * - `'onDemand'`: only re-render when the scene is marked dirty (via
-     *   {@link markDirty}) or while an animation is pending. Ideal for static /
-     *   event-driven UIs where idle frames should cost ~0.
-     */
-    renderMode: 'always' | 'onDemand';
-    private dirty;
-    /**
-     * Frame-rate cap (power saving). `0` = uncapped (native refresh). When set,
-     * the loop renders at most `maxFPS` times per second; animations still run,
-     * just less often. See {@link SceneOptions.maxFPS}.
-     */
-    maxFPS: number;
-    /** Whether the OS prefers-reduced-motion setting auto-caps the loop. */
-    respectReducedMotion: boolean;
-    /** Cached media-query list; `.matches` is read live each frame. */
-    private reducedMotionQuery;
-    /**
-     * Throttle interval (ms) for the a11y/automation shadow sync. `0` = every
-     * frame. See {@link SceneOptions.a11ySyncInterval}.
-     */
-    a11ySyncInterval: number;
-    /** Timestamp of the last a11y sync, for throttling. */
-    private lastA11ySync;
-    /** True if we skipped an a11y sync during animation and need to sync when at rest. */
-    private a11yPendingSyncAfterAnimation;
-    private a11yRoot;
-    private a11yElements;
-    private resizeHandler;
-    private focusedA11yElement;
-    private caretBlinkTimer;
-    a11yNeedsReorder: boolean;
-    private portalRoot;
-    private fullViewportElements;
-    private normalElements;
-    private activeIds;
-    private activePortalsThisFrame;
-    private activePortalsPrevFrame;
-    private portalEntities;
-    private renderOrderCounter;
-    private pointRenderer;
-    private glCanvas;
-    private debugA11y;
-    width: number;
-    height: number;
-    private disableWindowResize;
-    private destroyed;
-    private device;
-    private deviceLost;
-    particleBackend: 'auto' | 'webgpu' | 'cpu';
-    private _webgpuDisabled;
-    get webgpuDisabled(): boolean;
-    set webgpuDisabled(value: boolean);
-    private recoveryTimerId;
-    private manager;
-    private initializingWebGPU;
-    private gpuCanvas;
-    private gpuContext;
-    private mouseX;
-    private mouseY;
-    private pointerMoveListener;
-    private pointerLeaveListener;
-    private hasWarnedZeroSize;
-    constructor(canvas: HTMLCanvasElement, options?: SceneOptions);
-    /**
-     * Expose the underlying {@link IRenderer} for advanced direct-draw operations.
-     *
-     * @returns The active renderer instance.
-     */
-    getRenderer(): IRenderer;
-    /**
-     * Add a top-level entity to the scene graph.
-     *
-     * @param entity - The entity to attach to the scene root.
-     * @returns `this` for method chaining.
-     * @example scene.add(new CircleEntity());
-     */
-    add(entity: Entity): this;
-    private removeA11yRecursively;
-    /**
-     * Remove a top-level entity from the scene graph and clean up its
-     * accessibility shadow elements recursively.
-     *
-     * @param entity - The entity to detach from the scene root.
-     * @returns `this` for method chaining.
-     */
-    remove(entity: Entity): this;
-    /**
-     * Tear down the a11y/automation shadow nodes for `entity` and its descendants
-     * without removing it from the scene graph. Components that manage dynamic
-     * interactive *child* entities (e.g. a {@link Entity}'s per-link hotspots) call
-     * this before discarding those children so their shadow `<a>`/controls don't
-     * leak (the per-frame `syncA11y` only creates/updates, it never prunes).
-     *
-     * @param entity - The subtree whose shadow nodes should be removed.
-     */
-    detachA11y(entity: Entity): void;
-    /**
-     * Add an overlay entity to the overlay root, bypassing main tree clipping bounds.
-     */
-    showOverlay(overlay: Entity): void;
-    /**
-     * Remove an overlay entity from the overlay root.
-     */
-    hideOverlay(overlay: Entity): void;
-    /**
-     * Tear down the Scene, halt the loop, and clean up event listeners and DOM elements.
-     */
-    destroy(): void;
-    private setupEvents;
-    /**
-     * Begin the `requestAnimationFrame` render loop.
-     *
-     * Idempotent — calling `start()` on an already-running scene is a no-op.
-     */
-    start(): void;
-    /** Schedule the next frame, or no-op where `requestAnimationFrame` is absent (SSR). */
-    private scheduleFrame;
-    /**
-     * Halt the render loop after the current frame completes.
-     *
-     * Call {@link start} again to resume rendering.
-     */
-    stop(): void;
-    /**
-     * Mark the scene as needing a redraw on the next frame.
-     *
-     * Only meaningful in `onDemand` {@link renderMode}: call it after mutating
-     * entity state outside of {@link Entity.animate} so the change is rendered.
-     */
-    markDirty(): void;
-    /** True when any node in the subtree has a pending animation. */
-    private hasAnyPendingAnimation;
-    /** True when any node in the subtree is interactive (drives a11y sync). */
-    private hasAnyInteractive;
-    private syncA11y;
-    private enforceA11yDomOrder;
-    getA11yTree(): A11yTreeNode[];
-    private renderPortalDOM;
-    private reconcilePortals;
-    /**
-     * The frame-rate cap actually in effect: the explicit {@link maxFPS}, further
-     * lowered to {@link REDUCED_MOTION_FPS} when the OS requests reduced motion
-     * (and {@link respectReducedMotion} is on). `0` means uncapped.
-     */
-    private effectiveMaxFPS;
-    private loop;
-    /**
-     * Render the entire scene graph onto the specified renderer.
-     *
-     * @param renderer - The renderer instance to draw to.
-     * @param dt - Delta time in milliseconds (default 0).
-     * @param time - Current absolute time in milliseconds (default 0).
-     */
-    render(renderer: IRenderer, dt?: number, time?: number): void;
-    /**
-     * Export the current scene state to a lightweight, flat SVG XML string.
-     */
-    toSVG(): string;
-    /**
-     * Manually resize the Scene's viewport.
-     */
-    resize(width: number, height: number): void;
-    /**
-     * Gets the accessibility DOM element projected for the given entity ID.
-     */
-    getA11yElement(entityId: string): HTMLElement | undefined;
-    /**
-     * Gets the root entity of the scene.
-     */
-    getRoot(): Entity;
-    /**
-     * Finds the topmost interactive entity at the given coordinates.
-     */
-    findEntityAt(x: number, y: number): Entity | null;
-    private initWebGPUContext;
-    private setupDeviceLostHandler;
-    private recreateWebGPUDeviceWithRetry;
-    private renderCPUParticles;
-    private findHitRecursively;
-}
-
-declare class TextEntity extends Entity {
-    text: string;
-    private atlas;
-    private layout;
-    private prepared;
-    private nodes;
-    fontSize: number;
-    fillStyle: string | any;
-    strokeStyle: string | any;
-    hoveredFillStyle: string | any;
-    lineWidth: number;
-    private isHovered;
-    constructor(text: string, atlas: any, maxWidth: number, fontSize?: number);
-    /**
-     * Replace the text content. Runs the **cold** measurement pass (re-segment +
-     * re-measure) since the glyphs changed, then re-lays out.
-     *
-     * @returns `this` for chaining.
-     */
-    setText(text: string): this;
-    /**
-     * Change the wrap width and reflow. Cheap **hot** path only — reuses the
-     * cached {@link PreparedText}, doing no re-segmentation or re-measurement.
-     * Ideal for responsive resize.
-     *
-     * @returns `this` for chaining.
-     */
-    setMaxWidth(maxWidth: number): this;
-    /** Hot pass: place the cached {@link PreparedText} and refresh the a11y box. */
-    private applyLayout;
-    isPointInside(globalX: number, globalY: number): boolean;
-    render(renderer: IRenderer): void;
-}
-
-declare class GridTextEntity extends Entity {
-    fontSize: number;
-    fillStyle: string;
-    grid: string[];
-    cols: number;
-    rows: number;
-    charWidth: number;
-    charHeight: number;
-    constructor(_atlas: any, fontSize?: number);
-    updateGrid(ascii: string[]): void;
-    isPointInside(_globalX: number, _globalY: number): boolean;
-    render(renderer: IRenderer): void;
-}
-
-/** One piecewise-cubic segment: x(t) and y(t) as `[a,b,c,d]` polynomial coefficients. */
-interface SplineSegment {
-    start_t: number;
-    end_t: number;
-    x_poly: number[];
-    y_poly: number[];
-}
-/**
- * Color of a spline equation: an `[r,g,b]` triple in `0..1`, a linear-gradient
- * descriptor, or `null` (use the entity's default color).
- */
-type SplineColor = [number, number, number] | {
-    stops: [number, [number, number, number]][];
-    start_pos: [number, number];
-    end_pos: [number, number];
-} | null;
-/** A single curve (one stroke color) made of consecutive {@link SplineSegment}s. */
-interface SplineEquation {
-    color_rgb: SplineColor;
-    data: SplineSegment[];
-}
-/** The native vectomancy `Spline` document. */
-interface SplineDocument {
-    type: 'Spline' | 'Polyline';
-    equations?: SplineEquation[];
-    paths?: {
-        color_rgb: SplineColor;
-        data: {
-            x: number;
-            y: number;
-        }[];
-    }[];
-    bounding_box?: [number, number, number, number];
-}
-/** Construction options for {@link SplineEntity}. */
-interface SplineOptions {
-    /** Stroke width in local units. Default `2`. */
-    lineWidth?: number;
-    /** Bake to an OffscreenCanvas once and `drawImage` each frame. Default `true`. */
-    cache?: boolean;
-    /** Color used when an equation's `color_rgb` is `null`. Default `#e2e8f0`. */
-    defaultColor?: string;
-    /**
-     * Hit-test strategy:
-     * - `'curve'` (default): precise — a point hits only within `lineWidth/2 +
-     *   hitTolerance` of an actual curve.
-     * - `'aabb'`: coarse — anywhere in the bounding box hits.
-     */
-    hitTest?: 'curve' | 'aabb';
-    /** Extra pick padding (local units) added to `lineWidth/2` in `'curve'` mode. Default `0`. */
-    hitTolerance?: number;
-}
-/** Cubic Bézier control points produced from a {@link SplineSegment}. */
-interface BezierControlPoints {
-    x0: number;
-    y0: number;
-    cp1x: number;
-    cp1y: number;
-    cp2x: number;
-    cp2y: number;
-    x3: number;
-    y3: number;
-}
-/**
- * Convert one cubic-polynomial segment to Bézier control points.
- *
- * For a coefficient vector `[a,b,c,d]` describing `f(t)=a+bt+ct²+dt³` on `t∈[0,1]`,
- * the equivalent Bézier control values are `a`, `a+b/3`, `a+2b/3+c/3`, `a+b+c+d`.
- * Applied independently to the x and y polynomials.
- *
- * @param seg - The polynomial segment.
- * @returns The cubic Bézier control points.
- */
-declare function polySegmentToBezier(seg: SplineSegment): BezierControlPoints;
-/**
- * Renders a native vectomancy `Spline` document (piecewise-cubic curves) to canvas.
- *
- * Bounds come from the document's `bounding_box` (or are computed from segment
- * endpoints), so the entity participates in {@link Scene} viewport culling. By
- * default the curves are baked once into an `OffscreenCanvas` and blitted each
- * frame; without `OffscreenCanvas` it strokes the Bézier paths per frame.
- *
- * @example
- * const doc = await loadSpline('/ast/logo.json');
- * scene.add(new SplineEntity(doc).setPosition(100, 100));
- */
-declare class SplineEntity extends Entity {
-    doc: SplineDocument;
-    lineWidth: number;
-    defaultColor: string;
-    hitTolerance: number;
-    private cache;
-    private hitMode;
-    private bounds;
-    private offscreen;
-    private baked;
-    /** Lazily-flattened polylines (one Float32Array of [x,y,...] per segment) for hit-testing. */
-    private polylines;
-    /**
-     * When `true`, the renderer draws a rounded-rect outline of the entity's
-     * local bounds after painting the curves. Useful for drag feedback and
-     * debugging hit areas. Defaults to `false`.
-     */
-    showBounds: boolean;
-    constructor(doc: SplineDocument, opts?: SplineOptions);
-    private computeBounds;
-    /** @inheritdoc */
-    getBounds(): Bounds;
-    /**
-     * AABB hit-test against the document bounds in world space.
-     *
-     * Curve-accurate hit-testing can be layered on later via {@link hitTestCurve};
-     * this method already calls it as a refinement when it is overridden.
-     */
-    isPointInside(globalX: number, globalY: number): boolean;
-    /**
-     * Curve-accurate refinement of {@link isPointInside}: hit only when the local
-     * point lies within `lineWidth/2 + hitTolerance` of an actual curve.
-     *
-     * Returns `null` in `hitTest: 'aabb'` mode (keep the bounding-box result).
-     * Curves are flattened to polylines once and cached. Override for custom logic.
-     *
-     * @param localX - X in the entity's local space.
-     * @param localY - Y in the entity's local space.
-     * @returns `true`/`false`, or `null` to keep the AABB result.
-     */
-    protected hitTestCurve(localX: number, localY: number): boolean | null;
-    /** Flatten every Bézier segment into a sampled polyline once, then cache. */
-    private getPolylines;
-    private resolveColor;
-    private strokeEquations;
-    /** Bake all equations into an OffscreenCanvas once (when available). */
-    private bake;
-    render(r: IRenderer): void;
-}
-/**
- * Fetch and parse a vectomancy `Spline` JSON document (browser only).
- *
- * @param url - URL of the `.json` spline document.
- * @returns The parsed {@link SplineDocument}.
- */
-declare function loadSpline(url: string): Promise<SplineDocument>;
-
-/**
- * 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.
- */
-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;
-}
-
-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;
-}
-
-declare class DOMPortalEntity extends Entity {
-    domElement: HTMLElement;
-    isDOMPortal: boolean;
-    private domListeners;
-    private resizeObserver;
-    cachedWidth: number;
-    cachedHeight: number;
-    lastWidth: string;
-    lastHeight: string;
-    lastTransform: string;
-    lastZIndex: string;
-    constructor(domElement: HTMLElement, width?: number, height?: number, id?: string);
-    isPointInside(globalX: number, globalY: number): boolean;
-    add(child: Entity): this;
-    render(): void;
-    destroy(): void;
-}
-
-export { type A11yTreeNode, type BezierControlPoints, Bounds, DOMPortalEntity, Entity, GridTextEntity, IRenderer, type IWebGLPointRenderer, type IWebGPUParticleSystemManager, REDUCED_MOTION_FPS, Scene, type SceneOptions, SpatialHashGrid, type SplineColor, type SplineDocument, SplineEntity, type SplineEquation, type SplineOptions, type SplineSegment, SpringPhysics, TextEntity, type WebGLPointRendererCreator, loadSpline, polySegmentToBezier };