ranuts 0.2.0-alpha.1 → 0.4.0-alpha.1

package/dist/src/utils/visual/render/batchRenderer.d.ts

@@ -4,39 +4,41 @@ import type { Batch } from '@/utils/visual/render/utils/batch';
 import type { IApplicationOptions } from '@/utils/visual/types';
 export declare abstract class BatchRenderer extends Renderer {
     /**
-     * 上次构建大数组时的场景结构版本号（每个渲染器实例独立）。与根节点的 structureVersion
-     * 不一致时说明场景结构变了（增删节点 / 重绘），需要重建；否则只做逐帧 transform 更新。
-     * 初值 -1 保证首帧一定构建。基于版本号对比，多个渲染器共享同一场景也不会互相“消费”脏标记。
+     * The scene structure version at the last rebuild, held per renderer instance. When it
+     * differs from the root's structureVersion the scene changed (a node was added or removed,
+     * or a shape redrawn) and the big array must be rebuilt; otherwise only per-frame transform
+     * updates are needed. Starting at -1 guarantees a build on the first frame. Comparing
+     * versions rather than consuming a dirty flag lets several renderers share one scene.
      */
     protected builtVersion: number;
     /**
-     * 顶点个数
+     * Vertex count
      */
     protected vertexCount: number;
     /**
-     * 顶点下标个数
+     * Index count
      */
     protected indexCount: number;
     protected batches: Array<Batch | undefined>;
     protected batchesCount: number;
     /**
-     * 顶点数组 float32 视图
+     * Float32 view over the vertex array
      */
     protected vertFloatView: Float32Array;
     /**
-     * 顶点数组 Uint32 视图
+     * Uint32 view over the vertex array
      */
     protected vertIntView: Uint32Array;
     /**
-     * 顶点下标数组
+     * Index array
      */
     protected indexBuffer: Uint32Array;
     /**
-     * 当前的 webGL｜webGPU vertex buffer 的长度
+     * Current length of the WebGL/WebGPU vertex buffer
      */
     protected curVertBufferLength: number;
     /**
-     * 当前的 webGL｜webGPU index buffer 的长度
+     * Current length of the WebGL/WebGPU index buffer
      */
     protected curIndexBufferLength: number;
     constructor(options: IApplicationOptions);
@@ -44,35 +46,35 @@ export declare abstract class BatchRenderer extends Renderer {
     protected startBuild(): void;
     protected buildEnd(): void;
     /**
-     * 如果现有的 typed array 放不下了，则新建一个
+     * Allocate a bigger typed array when the current one can no longer hold the data
      */
     protected resizeBufferIfNeeded(): void;
     /**
-     * 将数据打包到大数组里
+     * Pack the data into the big array
      */
     protected packData(): void;
     /**
-     * 调用 webGL 或 webGPU 的绘制 api 将内容绘制出来
+     * Draw via the WebGL or WebGPU drawing API
      */
     protected abstract draw(): void;
     /**
-     * 更新更新 vertex buffer 和 index buffer
+     * Update the vertex and index buffers
      */
     protected abstract updateBuffer(): void;
     /**
-     * 设置投影矩阵，这是为了适配 canvas 元素的尺寸
+     * Set the projection matrix, which adapts to the canvas element's size
      */
     protected abstract setProjectionMatrix(): void;
     /**
-     * 更新 stage 的 transform 对应的 uniform 变量
+     * Update the uniform holding the stage's transform
      */
     protected abstract setRootTransform(a: number, b: number, c: number, d: number, tx: number, ty: number): void;
     /**
-     * 更新子节点的 transform
+     * Update the children's transforms
      */
     protected updateChildrenTransform(rootContainer: Container): void;
     /**
-     * 更新节点的位置信息并渲染
+     * Update node positions and render
      */
     render(rootContainer: Container): void;
 }

package/dist/src/utils/visual/render/utils/batch/index.d.ts

@@ -3,44 +3,44 @@ import type { Container } from '@/utils/visual/vertex/container';
 import type { Fill } from '@/utils/visual/style';
 import type { Graphics } from '@/utils/visual/graphics';
 /**
- * 构建大数组
+ * Build the big array
  */
 export declare const buildArray: (batchRenderer: BatchRenderer, container: Container) => void;
 /**
- * 更新大数组
+ * Update the big array
  */
 export declare const updateArray: (floatView: Float32Array, container: Container) => void;
 export declare abstract class Batch {
     /**
-     * 顶点个数
+     * Vertex count
      */
     vertexCount: number;
     /**
-     * 顶点下标个数
+     * Index count
      */
     indexCount: number;
     /**
-     * rgba 的小端序形式
+     * rgba packed little-endian
      */
     rgba: number;
     /**
-     * 顶点数据在大数组中的起点
+     * Where this batch's vertices start in the big array
      */
     vertexStart: number;
     /**
-     * 顶点下标数据在大数组中的起点
+     * Where this batch's indices start in the big array
      */
     indexStart: number;
     /**
-     * 将顶点数据写入大数组中
+     * Write the vertex data into the big array
      */
     abstract packVertices(floatView: Float32Array, intView: Uint32Array): void;
     /**
-     * 将顶点下标数据写入大数组中
+     * Write the index data into the big array
      */
     abstract packIndices(int32: Uint32Array): void;
     /**
-     * 在大数组中更新顶点位置数据
+     * Update the vertex positions inside the big array
      */
     abstract updateVertices(floatView: Float32Array): void;
 }
@@ -66,15 +66,15 @@ export declare class GraphicsBatchPool extends BatchPool {
 }
 export declare class GraphicsBatch extends Batch {
     /**
-     * 顶点部分在 geometry.vertices 中的起始下标
+     * Where this part's vertices start in geometry.vertices
      */
     vertexOffset: number;
     /**
-     * 顶点下标部分在 geometry.indices 中的起始下标
+     * Where this part's indices start in geometry.indices
      */
     indexOffset: number;
     /**
-     * 对应的 Graphics 实例
+     * The Graphics instance this belongs to
      */
     graphics: Graphics;
     packVertices(floatView: Float32Array, intView: Uint32Array): void;

package/dist/src/utils/visual/render/utils/float.d.ts

@@ -5,28 +5,28 @@ export declare class CustomFloatArray {
     private float32;
     private _data;
     /**
-     * 获取长度
+     * Current length
      */
     get length(): number;
     /**
-     * 拼接一个 number 数组
+     * Append an array of numbers
      */
     concat(arr: number[]): void;
     /**
-     * 插入数据
-     * @param num 要插入的数
+     * Push one value
+     * @param num the value to push
      */
     push(num: number): void;
     /**
-     * 扩容
+     * Grow the backing buffer
      */
     expandCapacity(): void;
     /**
-     * 以从 0 到 this.length 的这段 buffer 为底层，建立 Float32Array 视图并返回
+     * A Float32Array view over the buffer from 0 to this.length
      */
     get data(): Float32Array;
     /**
-     * 清空
+     * Clear
      */
     clear(): void;
 }
@@ -37,27 +37,27 @@ export declare class CustomIntArray {
     private int32;
     private _data;
     /**
-     * 获取长度
+     * Current length
      */
     get length(): number;
     /**
-     * 拼接一个 number 数组
+     * Append an array of numbers
      */
     concat(arr: number[]): void;
     /**
-     * 拼接一个UInt16数组
+     * Append a UInt16 array
      */
     concatUInt16(uint16: Uint32Array): void;
     /**
-     * 扩容
+     * Grow the backing buffer
      */
     expandCapacity(): void;
     /**
-     * 以从 0 到 this.length 的这段 buffer 为底层，建立 Uint32Array 视图并返回
+     * A Uint32Array view over the buffer from 0 to this.length
      */
     get data(): Uint32Array;
     /**
-     * 清空
+     * Clear
      */
     clear(): void;
 }

package/dist/src/utils/visual/render/utils/verticy.d.ts

@@ -1,13 +1,13 @@
 import type { GraphicsData } from '@/utils/visual/graphics/graphicsData';
 import type { GraphicsGeometry } from '@/utils/visual/graphics/graphicsGeometry';
 /**
- * 将一个图形顶点化
- * @param data 子图形data
+ * Turn a shape into vertices
+ * @param data the sub-shape's data
  */
 export declare const buildVertices: (data: GraphicsData) => void;
 export declare const triangulateFill: (data: GraphicsData, geometry: GraphicsGeometry) => void;
 export declare const getNormalVector: (x: number, y: number, lineWidth: number) => [number, number];
 /**
- * 构建描边的顶点 & 对其进行三角剖分
+ * Build the stroke's vertices and triangulate them
  */
 export declare const triangulateStroke: (data: GraphicsData, geometry: GraphicsGeometry) => void;

package/dist/src/utils/visual/render/utils/webgl/initShader.d.ts

@@ -1,7 +1,8 @@
 import type { WebGLRenderer } from '@/utils/visual/render/webGlRenderer';
 /**
- * 设置顶点属性布局。调用前需保证目标 ARRAY_BUFFER 已经绑定。
- * 顶点格式与共享批处理管线（BatchRenderer）一致：position(2×Float32) + color(4×Uint8, 归一化)，stride = BYTES_PER_VERTEX。
+ * Set the vertex attribute layout. The target ARRAY_BUFFER must already be bound.
+ * The vertex format matches the shared batching pipeline (BatchRenderer):
+ * position (2×Float32) + colour (4×Uint8, normalised), stride = BYTES_PER_VERTEX.
  */
 export declare const setupVertexLayout: (gl: WebGLRenderingContext, program: WebGLProgram) => void;
 export declare const initShader: (renderer: WebGLRenderer) => WebGLProgram;

package/dist/src/utils/visual/render/utils/webgpu/shaders.d.ts

@@ -1,8 +1,8 @@
 /**
- * 顶点着色器
+ * Vertex shader
  */
 export declare const vertexShaderSource = "\n@group(0) @binding(0) var<uniform> u_root_transform: mat3x3<f32>;\n@group(0) @binding(1) var<uniform> u_projection_matrix: mat3x3<f32>;\n\nstruct VertOutput {\n  @builtin(position) v_position: vec4<f32>,\n  @location(0) v_color : vec4<f32>,\n};\n\n@vertex\nfn main(\n  @location(0) a_position: vec2<f32>,\n  @location(1) a_color: vec4<f32>,\n) -> VertOutput {\n  let v_position = vec4<f32>((u_projection_matrix * u_root_transform * vec3<f32>(a_position, 1.0)).xy, 0.0, 1.0);\n\n  let v_color = a_color;\n\n  return VertOutput(v_position, v_color);\n}\n";
 /**
- * 片元着色器
+ * Fragment shader
  */
 export declare const fragmentShaderSource = "\n@fragment\nfn main(\n  @location(0) v_color : vec4<f32>,\n) -> @location(0) vec4<f32> {\n  return v_color;\n}\n";

package/dist/src/utils/visual/render/webGPURenderer.d.ts

@@ -7,23 +7,23 @@ export declare class WebGPURenderer extends BatchRenderer {
     private renderPassDescriptor;
     private options;
     /**
-     * 顶点的 webGPU buffer
+     * WebGPU buffer holding the vertices
      */
     private gpuVertexBuffer;
     /**
-     * 顶点下标的 webGPU buffer
+     * WebGPU buffer holding the vertex indices
      */
     private gpuIndexBuffer;
     /**
-     * 投影矩阵的 webGPU buffer
+     * WebGPU buffer holding the projection matrix
      */
     private projectionMatBuffer;
     /**
-     * stage 的变换矩阵的 webGPU buffer
+     * WebGPU buffer holding the stage's transform matrix
      */
     private stageMatBuffer;
     /**
-     * uniform 变量的 bind group
+     * Bind group for the uniforms
      */
     private uniformBindGroup;
     constructor(options: IApplicationOptions);
@@ -35,15 +35,15 @@ export declare class WebGPURenderer extends BatchRenderer {
     protected setRootTransform(a: number, b: number, c: number, d: number, tx: number, ty: number): void;
     protected setProjectionMatrix(): void;
     /**
-     * 初始化 pipeline
+     * Initialise the pipeline
      */
     private createPipeline;
     /**
-     * 初始化 device
+     * Initialise the device
      */
     private initDevice;
     /**
-     * 初始化 renderPassDescriptor
+     * Initialise the renderPassDescriptor
      */
     private initRenderPassDescriptor;
 }

package/dist/src/utils/visual/vertex/container.d.ts

@@ -7,68 +7,69 @@ export declare class Container extends Vertex {
     isSort: boolean;
     type: string;
     /**
-     * 所有子元素
+     * Every child
      */
     readonly children: Container[];
     /**
-     * 用来标记 worldTransform 是否发生了改变
+     * Marks whether worldTransform changed
      */
     protected worldId: number;
     /**
-     * 所有 batch
+     * Every batch
      */
     protected batches: Batch[];
     /**
-     * batch 总数
+     * Number of batches
      */
     protected batchCount: number;
     /**
-     * 场景结构版本号（仅根节点上的值有意义）。任何会改变“大数组该长什么样”的操作
-     * （增删子节点、Graphics 重绘）都会冒泡到根节点并使其 +1，渲染器据此决定是否重建大数组。
+     * Scene structure version (only meaningful on the root). Anything that changes what the
+     * big array should look like — adding or removing a child, a Graphics redraw — bubbles to
+     * the root and increments it, and the renderer uses that to decide whether to rebuild.
      */
     structureVersion: number;
     constructor();
     /**
-     * 标记场景结构已变化：冒泡到根节点并递增其版本号，触发下一帧的大数组重建。
+     * Mark the scene structure as changed: bubble to the root and bump its version, so the next frame rebuilds the big array.
      */
     protected markStructureDirty: () => void;
     /**
-     * @description: 添加子元素
+     * @description: Add a child
      * @param {Container} child
      * @return {*}
      */
     addChild: (child: Container) => void;
     /**
-     * @description:删除子元素
+     * @description: Remove a child
      * @param {Container} child
      * @return {void}
      */
     removeChild: (child: Container) => void;
     /**
-     * @description: 根据 z-index 排序子元素
+     * @description: Sort children by z-index
      * @return {*}
      */
     sortChildren: () => void;
     /**
-     * 渲染自身，在 container 上面没有东西要渲染，所以这个函数的内容为空
+     * Render itself — a container has nothing to render, so this is empty
      */
     protected renderCanvas(_render: CanvasRenderer): void;
     /**
-     * 递归渲染以自身为根的整棵节点树
+     * Recursively render the whole tree rooted here
      */
     renderCanvasRecursive: (render: CanvasRenderer) => void;
     /**
-     * 递归更新当前元素以及所有子元素的 transform
+     * Recursively update this element's transform and every child's
      */
     updateTransform: () => void;
     containsPoint: (p: Point) => boolean;
     /**
-     * 构建自身的 batch。组容器自身没有可渲染内容，子类（如 Graphics）会重写此方法。
-     * WebGL / WebGPU 后端统一通过 BatchRenderer 的 buildArray 递归调用本方法。
+     * Build its own batches. A group has no content of its own, so subclasses such as
+     * Graphics override this. Both GPU backends reach it through BatchRenderer's buildArray.
      */
     buildBatches(_batchRenderer: BatchRenderer): void;
     /**
-     * 更新自身的所有 batch 对应的大数组中的顶点
+     * Update this node's batched vertices inside the big array
      */
     updateBatches(_floatView: Float32Array): void;
 }

package/dist/src/utils/worker.d.ts

@@ -0,0 +1,125 @@
+/**
+ * A request/response wrapper over a Web Worker.
+ *
+ * A native worker only knows "post a message" and "receive a message" — there is no notion
+ * of a request and its response: send two tasks concurrently, get two messages back, and
+ * there is no way to tell which is which. The standard fix is to number each request and
+ * echo that number in the response; this class packages that correlation logic (ids, a
+ * pending table, progress events, rejecting every in-flight request when the worker
+ * crashes) into something reusable.
+ *
+ * It also owns the worker's lifecycle: **the worker is created on the first `send`** (heavy
+ * work should not start at page load), and `dispose()` terminates it and rejects in-flight
+ * requests; a later `send` rebuilds it.
+ */
+/** A response must at least echo the request id so the two can be paired */
+export interface WorkerResponseBase {
+    operationId: number;
+    type?: string;
+}
+export interface WorkerClientOptions<Res extends WorkerResponseBase, Progress> {
+    /** How to create the worker, e.g. `() => new Worker(new URL('./my.worker.ts', import.meta.url), { type: 'module' })` */
+    create: () => Worker;
+    /** Whether this is a progress message — it does not settle the request, it only calls onProgress. Defaults to `type === 'progress'` */
+    isProgress?: (response: Res) => boolean;
+    /** Extract the progress payload from a progress message. Defaults to `response.progress` */
+    getProgress?: (response: Res) => Progress;
+    /** Whether this is an error message. Defaults to `type === 'error'` */
+    isError?: (response: Res) => boolean;
+    /** Error message text. Defaults to `response.message` */
+    getErrorMessage?: (response: Res) => string;
+    /** Per-request timeout in milliseconds; omit for none. A timeout only rejects that request, it does not terminate the worker */
+    timeout?: number;
+}
+/**
+ * @description: A worker client with request ids. The request type `Req` is defined by the
+ * caller; the client only fills in `operationId` and routes each response back to the right
+ * promise.
+ *
+ * @example
+ * ```ts
+ * const client = new WorkerClient<MyRequest, MyResponse, { progress: number }>({
+ *   create: () => new Worker(new URL('./nlp.worker.ts', import.meta.url), { type: 'module' }),
+ * });
+ * const loaded = await client.send({ type: 'load', modelId }, (p) => render(p.progress));
+ * client.dispose();
+ * ```
+ * The worker side only has to echo the `operationId` it received:
+ * ```ts
+ * self.onmessage = ({ data }) => self.postMessage({ operationId: data.operationId, type: 'result', ... });
+ * ```
+ */
+export declare class WorkerClient<Req extends object, Res extends WorkerResponseBase, Progress = unknown> {
+    private worker;
+    private nextOperationId;
+    private pending;
+    private options;
+    constructor(options: WorkerClientOptions<Res, Progress>);
+    /** Whether the worker has been created (it is created on the first `send`) */
+    get active(): boolean;
+    /** Number of in-flight requests */
+    get pendingCount(): number;
+    /**
+     * @description: Send one request and await its matching response
+     * @param {Req} request request body (`operationId` is filled in by the client — do not pass it)
+     * @param {Function} onProgress progress callback, fired on progress messages without settling the request
+     * @param {Transferable[]} transfer objects whose ownership is transferred (ArrayBuffer and friends, avoiding the structured-clone copy)
+     * @return {Promise<Res>}
+     */
+    send: (request: Req, onProgress?: (progress: Progress) => void, transfer?: Transferable[]) => Promise<Res>;
+    /** @description: Terminate the worker and reject every in-flight request; the next `send` rebuilds it */
+    dispose: () => void;
+    private getWorker;
+    private settle;
+    private handleMessage;
+    private rejectAll;
+}
+/** A request always carries the id the client stamped on it */
+export interface WorkerRequestBase {
+    operationId: number;
+    type?: string;
+}
+/** Handed to the handler so it can stream progress for the request it is currently serving */
+export interface WorkerHandlerContext<Progress> {
+    /** Post a progress update. Does not settle the request; may be called any number of times. */
+    progress: (payload: Progress) => void;
+}
+export interface ServeWorkerOptions {
+    /**
+     * Where to listen. Defaults to `self` — override for a `MessagePort`, a nested worker, or
+     * a test double.
+     */
+    scope?: {
+        addEventListener: (type: 'message', listener: (event: MessageEvent) => void) => void;
+        removeEventListener: (type: 'message', listener: (event: MessageEvent) => void) => void;
+        postMessage: (message: unknown, transfer?: Transferable[]) => void;
+    };
+    /** Response `type` for a successful reply that the handler returned bare (non-object). Default `'result'`. */
+    resultType?: string;
+}
+/**
+ * @description: Serve requests inside a Web Worker, mirroring {@link WorkerClient} on the
+ * other end. Reads `operationId` off each request, awaits your handler, and posts the reply
+ * back with that same id.
+ *
+ * Failures become `{ operationId, type: 'error', message }` — the envelope `WorkerClient`
+ * rejects on by default. **Both synchronous throws and rejected promises are caught**: a sync
+ * throw inside `onmessage` would otherwise escape to the worker's error handler, which carries
+ * no id, so the client could only fail *every* in-flight request instead of the one that broke.
+ *
+ * @param {Function} handler receives the request and a context whose `progress()` streams updates
+ * @param {ServeWorkerOptions} options
+ * @return {Function} stop — removes the listener
+ * @example
+ * ```ts
+ * // my.worker.ts
+ * serveWorker<MyRequest, MyResponse, ModelProgress>(async (request, { progress }) => {
+ *   if (request.type === 'load') {
+ *     const device = await load(request.modelId, (p) => progress(p));
+ *     return { type: 'loaded', device };
+ *   }
+ *   return { type: 'result', scores: await classify(request.lines) };
+ * });
+ * ```
+ */
+export declare const serveWorker: <Req extends WorkerRequestBase, Res extends object = object, Progress = unknown>(handler: (request: Req, context: WorkerHandlerContext<Progress>) => Promise<Res> | Res, options?: ServeWorkerOptions) => (() => void);