@vectojs/core 0.1.0 → 0.2.1

package/dist/tree/Scene.d.ts

@@ -0,0 +1,302 @@
+export interface IWebGLPointRenderer {
+    resize(width: number, height: number): void;
+}
+export type WebGLPointRendererCreator = (canvas: HTMLCanvasElement) => any;
+export 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;
+}
+import { Entity } from './Entity';
+import { IRenderer } from '../renderer/IRenderer';
+/**
+ * Options for {@link Scene}.
+ */
+export 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;
+    /**
+     * Enable automatic throttling to 2 FPS when the scene is static (no active transitions
+     * and not marked dirty) to save power/CPU. Default is `true`.
+     */
+    autoThrottle?: boolean;
+}
+/** Frame-rate the loop is capped to when the OS requests reduced motion. */
+export declare const REDUCED_MOTION_FPS = 30;
+export 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();
+ */
+export 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;
+    /** Whether to throttle rendering to 2 FPS when the scene is static to save power. */
+    autoThrottle: boolean;
+    /**
+     * 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;
+    /** True when the OS asks for reduced motion and we respect it. Read by the animation drivers. */
+    get prefersReducedMotion(): boolean;
+    /**
+     * 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;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectojs/core",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "publishConfig": {
     "access": "public"
   },
@@ -35,17 +35,17 @@
       "require": "./dist/index.js"
     },
     "./layout": {
-      "types": "./dist/layout.d.ts",
+      "types": "./dist/layout/index.d.ts",
       "import": "./dist/layout.mjs",
       "require": "./dist/layout.js"
     },
     "./renderer": {
-      "types": "./dist/renderer.d.ts",
+      "types": "./dist/renderer/index.d.ts",
       "import": "./dist/renderer.mjs",
       "require": "./dist/renderer.js"
     },
     "./text": {
-      "types": "./dist/text.d.ts",
+      "types": "./dist/text/index.d.ts",
       "import": "./dist/text.mjs",
       "require": "./dist/text.js"
     }
@@ -54,7 +54,7 @@
     "dist"
   ],
   "scripts": {
-    "build": "node scripts/build-worker.js && tsup",
+    "build": "node scripts/build-worker.js && tsup && tsc -p tsconfig.build.json",
     "test": "vitest run"
   },
   "dependencies": {},