rendx-engine 0.2.0

package/dist/main.d.cts

@@ -0,0 +1,880 @@
+import { vec2, mat2d } from 'gl-matrix';
+import { AO, ClipPath, GF, Mat2d, Point, GradientOptions, IGraphicsRenderer, Size } from 'rendx-core';
+import { BoundingBox } from 'rendx-bounding';
+import { Path } from 'rendx-path';
+
+type TransformStatus = 'start' | 'init' | 'waiting' | 'running' | 'last' | 'clear' | 'end';
+/**
+ * 动画变换基类
+ * 统一管理 duration / delay / easing / repeat 和时间状态机
+ * 子类只需实现 apply(t) 方法
+ */
+declare abstract class BaseTransform {
+    status: TransformStatus;
+    protected _duration: number;
+    protected _delay: number;
+    protected _easing: string;
+    protected _repeat: boolean;
+    protected _time: number;
+    /** 是否仍在活跃状态（未结束） */
+    get active(): boolean;
+    duration(time: number): this;
+    delay(time: number): this;
+    easing(easing: string): this;
+    repeat(repeat: boolean): this;
+    /** 子类实现具体的插值逻辑 */
+    protected abstract apply(t: number): void;
+    /** 动画结束时的清理，子类可覆盖 */
+    protected onEnd(): void;
+    interpolate(time: number): void;
+}
+
+interface TransformAttrs$1 {
+    translate?: [number, number, number, number];
+    rotate?: [number, number];
+    scale?: [number, number, number, number];
+}
+interface TransformValues {
+    tx: number;
+    ty: number;
+    sx: number;
+    sy: number;
+    rotate: number;
+}
+declare class GraphicsTransform extends BaseTransform {
+    V: TransformValues;
+    attrs: TransformAttrs$1;
+    values: Partial<TransformValues>;
+    constructor(values: TransformValues);
+    translate(x: number, y: number): this;
+    rotate(r: number): this;
+    scale(x: number, y: number): this;
+    protected apply(t: number): void;
+    protected onEnd(): void;
+}
+
+interface TransformAttrs {
+    opacity?: [number, number];
+    fill?: [string, string];
+    fillOpacity?: [number, number];
+    stroke?: [string, string];
+    strokeOpacity?: [number, number];
+    [key: string]: any;
+}
+declare class AttributeTransform extends BaseTransform {
+    V: AO;
+    attrs: TransformAttrs;
+    constructor(values: AO);
+    /** 设置属性动画目标值（属性应在调用前已设置初始值） */
+    attr(key: string, value: any): this;
+    protected apply(t: number): void;
+}
+
+/**
+ * 裁剪框动画，特有 init/clear 状态管理 clipPath 生命周期
+ * 覆盖基类 interpolate 实现自定义状态流
+ */
+declare class ClipBoxTransform extends BaseTransform {
+    #private;
+    type: 'lr' | 'rl' | 'tb' | 'bt' | undefined;
+    boundingBox: BoundingBox | null;
+    clipPath: ClipPath;
+    constructor(clipPath: ClipPath);
+    direction(type: 'lr' | 'rl' | 'tb' | 'bt'): this;
+    box(box: BoundingBox): this;
+    protected apply(_t: number): void;
+    interpolate(time: number): void;
+}
+
+interface ArcTransformValues {
+    startAngle: number;
+    endAngle: number;
+}
+declare class ArcTransform extends BaseTransform {
+    V: ArcTransformValues;
+    attrs: Partial<Record<keyof ArcTransformValues, [number, number]>>;
+    values: Partial<ArcTransformValues>;
+    constructor(values: ArcTransformValues);
+    startAngle(a: number): this;
+    endAngle(a: number): this;
+    protected apply(t: number): void;
+    protected onEnd(): void;
+}
+
+interface SectorTransformValues {
+    startAngle: number;
+    endAngle: number;
+    innerRadius: number;
+    outerRadius: number;
+}
+declare class SectorTransform extends BaseTransform {
+    V: SectorTransformValues;
+    attrs: Partial<Record<keyof SectorTransformValues, [number, number]>>;
+    values: Partial<SectorTransformValues>;
+    constructor(values: SectorTransformValues);
+    startAngle(a: number): this;
+    endAngle(a: number): this;
+    innerRadius(r: number): this;
+    outerRadius(r: number): this;
+    protected apply(t: number): void;
+    protected onEnd(): void;
+}
+
+declare class SimulatedEvent {
+    #private;
+    type: string;
+    target: Graphics;
+    currentTarget: Graphics;
+    nativeEvent: Event;
+    eventPhase: number;
+    bubbles: boolean;
+    timestamp: number;
+    offsetX: number;
+    offsetY: number;
+    worldX: number;
+    worldY: number;
+    truth: boolean;
+    constructor(type: string, target: Graphics, nativeEvent: Event);
+    get captureType(): string;
+    stopPropagation(): void;
+    /** 返回从 target 到 root 的路径（缓存） */
+    composedPath(): Graphics[];
+    copy(): SimulatedEvent;
+}
+
+declare class EventDispatcher {
+    last: SimulatedEvent | null;
+    eventMap: Record<string, (event: SimulatedEvent) => void>;
+    constructor();
+    exec(event: SimulatedEvent, node: Graphics): void;
+    capture(event: SimulatedEvent): void;
+    target(event: SimulatedEvent): void;
+    bubble(event: SimulatedEvent): void;
+    flow(event: SimulatedEvent): void;
+    process(event: SimulatedEvent): void;
+    simulateEnter(event: SimulatedEvent): void;
+    simulateLeave(event: SimulatedEvent): void;
+    simulateOver(event: SimulatedEvent): void;
+    simulateOut(event: SimulatedEvent): void;
+    normal(event: SimulatedEvent): void;
+    onPointerEnter(event: SimulatedEvent): void;
+    onPointerLeave(event: SimulatedEvent): void;
+    onPointerOver(event: SimulatedEvent): void;
+    onPointerOut(event: SimulatedEvent): void;
+    clear(): void;
+    dispose(): void;
+}
+
+interface EventListenerOptions {
+    once?: boolean;
+    capture?: boolean;
+}
+type EventListener = (...args: any[]) => void;
+declare class EventTarget {
+    #private;
+    dispatcher: EventDispatcher | null;
+    setDispatcher(dispatcher: EventDispatcher): void;
+    on(event: string, listener: EventListener, options?: EventListenerOptions): void;
+    off(event: string, listener: EventListener, options?: EventListenerOptions): void;
+    emit(event: string, payload?: any): void;
+    eventNames(): (string | symbol)[];
+    eventTypes(): string[];
+    listeners(event: string): ((...args: any[]) => void)[];
+    hasEvent(event: string): boolean;
+    dispatchEvent(evt: SimulatedEvent): void;
+}
+
+/**
+ * 场景图所有节点的基类。提供树操作、变换、脏标记、动画驱动等核心能力。
+ * type 编号：0=Graphics 基类，1=Scene，2=Group，3=Node，4=Layer
+ */
+declare class Graphics extends EventTarget {
+    #private;
+    type: number;
+    uid: string;
+    name: string;
+    className: string;
+    parent: Graphics | null;
+    children: Graphics[];
+    z: number;
+    visible: boolean;
+    display: boolean;
+    pointerEvents: boolean;
+    autoVisible: boolean;
+    autoDisplay: boolean;
+    autoPointerEvents: boolean;
+    autoNeedUpdate: boolean;
+    autoWorldMatrixNeedUpdate: boolean;
+    needUpdate: boolean;
+    worldMatrixNeedUpdate: boolean;
+    data: AO;
+    ez: number;
+    dirty: boolean;
+    _translate: vec2;
+    _rotate: number;
+    _scale: vec2;
+    /** 当前平移值 [tx, ty]（只读） */
+    get translation(): Readonly<vec2>;
+    /** 当前旋转弧度（只读） */
+    get rotation(): number;
+    /** 当前缩放值 [sx, sy]（只读） */
+    get scaling(): Readonly<vec2>;
+    matrix: mat2d;
+    worldMatrix: mat2d;
+    transform: GraphicsTransform | null;
+    setName(name: string): this;
+    setClassName(className: string): this;
+    addClassName(className: string): this;
+    hasClassName(className: string): boolean;
+    setVisible(visible: boolean, bySelf?: boolean): this;
+    setDisplay(display: boolean, bySelf?: boolean): this;
+    setPointerEvents(pointerEvents: boolean, bySelf?: boolean): this;
+    setDirty(dirty: boolean): this;
+    /**
+     * 添加子节点。若 child 已有 parent 会先移除。
+     * @param child - 要添加的场景图节点
+     */
+    add(child: Graphics): this;
+    unshift(child: Graphics): this;
+    remove(child: Graphics): this;
+    removeChildren(): this;
+    is(name: string): boolean;
+    equals(target: Graphics): boolean;
+    /**
+     * 按名称查找子节点
+     * @param name - 节点名称
+     * @param deep - 是否递归搜索子树（默认 false 仅搜索直接children）
+     */
+    find(name: string, deep?: boolean): Graphics | null;
+    /**
+     * 按 className 查询节点列表
+     * @param className - CSS 风格的类名
+     * @param deep - 是否递归搜索子树
+     */
+    query(className: string, deep?: boolean): Graphics[];
+    has(name: string, deep?: boolean): boolean;
+    root(): Graphics;
+    /** 根到当前节点的完整路径（从 root 到 this） */
+    path(): Graphics[];
+    source(target: Graphics): boolean;
+    /** 深度优先遍历子树，包含自身 */
+    traverse(fn: GF): void;
+    setZ(z: number): this;
+    getZIndex(): number;
+    /**
+     * 设置本地矩阵（直接覆盖 translate/rotate/scale 计算的结果）
+     * @param matrix - [a, b, c, d, e, f] 2x3 仿射矩阵
+     * @param needUpdate - 是否触发世界矩阵更新（默认 true）
+     */
+    setMatrix(matrix: Mat2d, needUpdate?: boolean): this;
+    setWorldMatrix(matrix: Mat2d, needUpdate?: boolean): this;
+    /**
+     * 设置平移
+     * @param tx - X 方向平移量（像素）
+     * @param ty - Y 方向平移量（像素）
+     */
+    translate(tx: number, ty: number): this;
+    translateX(tx: number): this;
+    translateY(ty: number): this;
+    translateXY(tx: number, ty: number): this;
+    rotate(radian: number): this;
+    rotateZ(radian: number): this;
+    scale(sx: number, sy: number): this;
+    scaleX(sx: number): this;
+    scaleY(sy: number): this;
+    scaleXY(sx: number, sy: number): this;
+    /** 启用几何变换动画（GraphicsTransform），可链式配置 duration/delay/easing */
+    useTransform(): this;
+    renderable(): boolean;
+    /** 检查是否需要重绘（自身或子树有脏标记/更新标记） */
+    sign(): boolean;
+    tick(time: number): void;
+    update(): void;
+    clear(): void;
+    dispose(): void;
+}
+
+type ShapeCommand = 'text' | 'circle' | 'rect' | 'line' | 'path' | 'image' | '';
+/**
+ * 图形形状基类。子类通过 from() 设置参数，build() 触发包围盒计算。
+ * command 指定渲染器的绘制方法：'text' | 'circle' | 'rect' | 'line' | 'path' | 'image'
+ */
+declare class Shape {
+    uid: string;
+    type: number;
+    name: string;
+    command: ShapeCommand;
+    boundingBox: BoundingBox;
+    creator: Path | null;
+    d: string;
+    p: Path2D | null;
+    autoNeedUpdate: boolean;
+    needUpdate: boolean;
+    setBox(box: BoundingBox): void;
+    /** 按属性名列表获取值（序列化用），避免 as any */
+    getProps(keys: string[]): unknown[];
+    /** 接收节点属性（子类按需 override，如 TextShape 用于文本测量） */
+    setAttrs(_attrs: AO): void;
+    options(..._args: any[]): void;
+    /** 子类覆写此方法设置形状参数（如 CircleShape.from(cx, cy, r)） */
+    from(..._args: any[]): void;
+    /** 构建形状：计算包围盒和路径数据，仅在 needUpdate 时执行 */
+    build(): void;
+    /** 返回 SVG 路径字符串（d 属性） */
+    path(): string;
+    /** 返回缓存的 Path2D 对象（用于 Canvas 命中检测） */
+    path2d(): Path2D;
+    box(): BoundingBox;
+    useTransform(): this;
+    tick(_time: number): void;
+    /**
+     * 点命中检测（默认使用包围盒，子类可覆写用 path2d 精确检测）
+     * @param point - 本地坐标 [x, y]
+     */
+    hit(point: Point): boolean;
+    clear(): void;
+    dispose(): void;
+}
+
+/**
+ * 视觉属性容器，管理 fill/stroke/opacity/fontSize 等渲染属性。
+ * 支持属性动画（AttributeTransform）和裁剪动画（ClipBoxTransform）。
+ */
+declare class Attributes {
+    #private;
+    uid: string;
+    name: string;
+    values: AO;
+    gradientOptions: GradientOptions | undefined;
+    clipPath: ClipPath | undefined;
+    autoNeedUpdate: boolean;
+    needUpdate: boolean;
+    transform: AttributeTransform | null;
+    clipBoxTransform: ClipBoxTransform | null;
+    set(key: string, value: any): this;
+    get(key: string): any;
+    /** 从对象批量设置属性（替换全部） */
+    from(attrs: AO): this;
+    /** 合并属性（保留已有值，追加新值） */
+    merge(attrs: AO): this;
+    /** 关联渐变配置 */
+    gradient(gradientOptions: GradientOptions): this;
+    /** 关联裁剪路径 */
+    clip(clipPath: ClipPath): this;
+    setBox(box: BoundingBox): this;
+    /** 启用属性动画（可对 opacity/fill/stroke 等做插值动画） */
+    useTransform(): this;
+    /** 启用裁剪框动画（lr/rl/tb/bt 方向的揭露动效） */
+    useClipBoxTransform(): this;
+    tick(time: number): this;
+    update(): void;
+    clear(): this;
+    dispose(): void;
+}
+
+declare function setCanvasRenderingContext2StrokeAttrs(ctx: OffscreenCanvasRenderingContext2D, attributes: AO): void;
+declare const isHit: (path: Path2D, point: Point, fill: string, stroke: string, strokeAttrs?: AO) => boolean;
+
+type ImageSource$1 = HTMLImageElement | ImageBitmap;
+declare class ImageLoader {
+    #private;
+    /** 全局回调：任何图片加载完成时触发（用于重启渲染循环） */
+    onChange: (() => void) | null;
+    load(src: string, onReady?: () => void): ImageSource$1 | null;
+    get(src: string): ImageSource$1 | null;
+    has(src: string): boolean;
+    clear(): void;
+}
+declare const imageLoader: ImageLoader;
+
+/**
+ * 叶子节点（type=3），场景图中的可渲染单元。
+ * 每个 Node 持有一个 Shape（几何形状）和一个 Attributes（视觉属性）。
+ *
+ * @example
+ * ```ts
+ * const node = Node.create('circle', { fill: 'red', stroke: '#000' });
+ * node.shape.from(100, 200, 50); // cx, cy, r
+ * node.translate(10, 20);
+ * scene.add(node);
+ * ```
+ */
+declare class Node extends Graphics {
+    #private;
+    type: number;
+    /** Shape 注册类型名（如 'rect', 'circle' 等），序列化时使用 */
+    shapeType: string;
+    shape: Shape;
+    attrs: Attributes;
+    /**
+     * 创建指定类型的节点（推荐使用此工厂方法而非直接 new）
+     * @param type - 形状类型：'circle' | 'rect' | 'line' | 'path' | 'text' | 'image'
+     * @param values - 视觉属性（fill/stroke/opacity/fontSize 等）
+     */
+    static create(type: string, values?: AO): Node;
+    constructor(shape: Shape, attrs: Attributes);
+    tick(time: number): void;
+    update(): void;
+    sign(): boolean;
+    /**
+     * 计算节点在世界坐标系中的轴对齐包围盒 (AABB)。
+     * 通过 worldMatrix 变换本地 boundingBox 的四个角点,
+     * 返回变换后的包围盒。若本地包围盒不可用，返回 null。
+     */
+    getWorldBBox(): BoundingBox | null;
+    /**
+     * 命中检测：将屏幕坐标通过逆世界矩阵变换为本地坐标，然后检测是否命中
+     * @param point - 场景坐标 [x, y]
+     * @returns 命中时返回自身，否则 undefined
+     */
+    hit(point: Point): this | undefined;
+}
+
+interface RendererConfig {
+    width: number;
+    height: number;
+    renderer?: 'svg' | 'canvas' | IGraphicsRenderer;
+    viewport?: [number, number, number, number];
+}
+declare class Renderer {
+    #private;
+    cfg: RendererConfig;
+    viewMatrix: mat2d;
+    constructor(cfg: Partial<RendererConfig>);
+    get el(): HTMLCanvasElement | SVGSVGElement;
+    /** 客户端坐标(clientX/Y) → 画布局部坐标 */
+    position(point: Point): Point;
+    resize(size: Size): void;
+    /** 绘制渲染队列 */
+    draw(queue: Node[]): void;
+    clear(): void;
+    dispose(): void;
+}
+
+/** 分组容器节点（type=2），不可渲染，用于组织场景图层级 */
+declare class Group extends Graphics {
+    type: number;
+}
+
+/**
+ * Layer — 分层渲染节点
+ * 每个 Layer 持有独立 Renderer（独立 Canvas/SVG 元素），实现多 Canvas 分层渲染。
+ * Layer 本身是 Group 子类，节点通过 layer.add(node) 挂入层中。
+ */
+declare class Layer extends Group {
+    #private;
+    type: number;
+    /** 层名称 */
+    layerName: string;
+    /** 层级序号（CSS z-index） */
+    layerIndex: number;
+    /** 独立渲染器 */
+    renderer: Renderer;
+    /** 是否为内置事件层（不可删除，不渲染内容） */
+    isEventLayer: boolean;
+    /** 是否启用视口裁剪（默认 true，Text 层等可关闭） */
+    culling: boolean;
+    constructor(name: string, index: number, cfg: Partial<RendererConfig>, isEventLayer?: boolean);
+    /** 获取当前层的渲染队列（仅 type=3 的 Node） */
+    getQueue(): Node[];
+    /** 层级是否需要重绘 */
+    sign(): boolean;
+    /** 绘制本层 */
+    draw(): void;
+    resize(size: {
+        width: number;
+        height: number;
+    }): void;
+    clear(): void;
+    dispose(): void;
+}
+
+/** 场景根节点（type=1），管理所有渲染层、提供命中检测和坐标映射 */
+declare class Scene extends Graphics {
+    #private;
+    type: number;
+    /** 有序层列表（按 layerIndex 排序） */
+    layers: Layer[];
+    /** 注册一个 Layer（由 App 调用） */
+    registerLayer(layer: Layer): void;
+    /** 按名称获取 Layer */
+    getLayer(name: string): Layer | undefined;
+    /** 移除 Layer（事件层不可移除） */
+    removeLayer(name: string): void;
+    /**
+     * 默认 add：添加到 default 层（向下兼容）
+     * 如果没有 layer，退回原行为（直接加到 Scene children）
+     */
+    add(child: Graphics): this;
+    /** 收集所有可渲染节点（type=3），按 ez 排序，带脏标记缓存 */
+    getQueue(): Node[];
+    /** 跨层命中检测：从最高层向下搜索 */
+    pick(point: Point): Node | undefined;
+    /**
+     * 屏幕坐标 → 场景坐标（通过逆 worldMatrix 变换，缓存逆矩阵）
+     * @param point - 画布像素坐标 [x, y]
+     */
+    position(point: Point): Point;
+    setMatrix(matrix: Mat2d, needUpdate?: boolean): this;
+}
+
+declare class SymbolShape extends Shape {
+    command: "path";
+    r: number;
+    symbol: string;
+    options(symbol: string): void;
+    from(r: number): void;
+    build(): void;
+    path(): string;
+    box(): BoundingBox;
+}
+
+declare class RoundShape extends Shape {
+    command: "path";
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    rx: number | number[] | undefined;
+    ry: number | number[] | undefined;
+    options(rx: number | number[] | undefined, ry?: number | number[] | undefined): void;
+    from(x: number, y: number, width: number, height: number): void;
+    build(): void;
+    path(): string;
+    box(): BoundingBox;
+}
+
+declare class CurveShape extends Shape {
+    command: "path";
+    segments: Point[][];
+    curve: string;
+    closed: boolean;
+    options(curve: string, closed: boolean): void;
+    from(segments: Point[][]): void;
+    build(): void;
+    path(): string;
+    box(): BoundingBox;
+}
+
+declare class AreaShape extends Shape {
+    command: "path";
+    upperSegments: Point[][];
+    lowerSegments: Point[][];
+    curve: string;
+    options(curve: string): void;
+    from(upperSegments: Point[][], lowerSegments: Point[][]): void;
+    build(): void;
+    path(): string;
+    box(): BoundingBox;
+}
+
+declare class PolygonShape extends Shape {
+    command: "path";
+    points: Point[];
+    curve: string;
+    closed: boolean;
+    options(curve: string, closed?: boolean): void;
+    from(points: Point[]): void;
+    build(): void;
+    path(): string;
+    box(): BoundingBox;
+}
+
+declare class SectorShape extends Shape {
+    command: "path";
+    r: number;
+    startAngle: number;
+    endAngle: number;
+    padAngle: number | undefined;
+    innerRadius: number;
+    outerRadius: number;
+    rc: number | number[] | undefined;
+    transform: SectorTransform | null;
+    options(rc: number | number[] | undefined): void;
+    from(r: number, startAngle: number, endAngle: number, innerRadius: number, outerRadius: number, padAngle?: number): void;
+    build(): void;
+    path(): string;
+    box(): BoundingBox;
+    useTransform(): this;
+    tick(time: number): this;
+}
+
+declare class ArcShape extends Shape {
+    command: "path";
+    r: number;
+    startAngle: number;
+    endAngle: number;
+    radius: number;
+    transform: ArcTransform | null;
+    from(r: number, startAngle: number, endAngle: number, radius: number): void;
+    build(): void;
+    path(): string;
+    box(): BoundingBox;
+    useTransform(): this;
+    tick(time: number): this;
+}
+
+declare class PathShape extends Shape {
+    command: "path";
+    from(d: string): void;
+}
+
+/**
+ * 文本测量函数签名。
+ * 接收文本内容和节点样式属性（含 fontSize、fontFamily 等），返回本地空间 BoundingBox。
+ * 返回 null 表示无法测量。
+ */
+type TextMeasureFn = (text: string, attrs: AO) => BoundingBox | null;
+/** 文本形状，支持自定义测量函数计算包围盒 */
+declare class TextShape extends Shape {
+    #private;
+    command: "text";
+    x: number;
+    y: number;
+    text: string;
+    /**
+     * 全局默认文本测量函数。
+     * 使用者通过 `TextShape.defaultMeasure = fn` 注入，
+     * 所有 TextShape 实例默认使用此函数（除非实例级覆盖）。
+     *
+     * @example
+     * ```ts
+     * import {getTextBoundingBox} from 'rendx-dom';
+     * TextShape.defaultMeasure = (text, attrs) =>
+     *   getTextBoundingBox({fontSize: attrs.fontSize, fontFamily: attrs.fontFamily}, text);
+     * ```
+     */
+    static defaultMeasure: TextMeasureFn | null;
+    /** 实例级文本测量函数，优先于 `defaultMeasure` */
+    measure: TextMeasureFn | null;
+    setAttrs(attrs: AO): void;
+    from(text: string, x: number, y: number): void;
+    build(): void;
+    box(): BoundingBox;
+    hit(_point: Point): boolean;
+}
+
+/** 线段形状 */
+declare class LineShape extends Shape {
+    command: "line";
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    /**
+     * 设置线段端点
+     * @param x1 - 起点 X
+     * @param y1 - 起点 Y
+     * @param x2 - 终点 X
+     * @param y2 - 终点 Y
+     */
+    from(x1: number, y1: number, x2: number, y2: number): void;
+    path2d(): Path2D;
+    box(): BoundingBox;
+}
+
+/** 矩形形状 */
+declare class RectShape extends Shape {
+    command: "rect";
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /**
+     * 设置矩形参数
+     * @param x - 左上角 X
+     * @param y - 左上角 Y
+     * @param width - 宽度
+     * @param height - 高度
+     */
+    from(x: number, y: number, width: number, height: number): void;
+    hit(point: Point): boolean;
+    box(): BoundingBox;
+}
+
+/** 圆形形状，用于 Scene Graph 中的圆形节点 */
+declare class CircleShape extends Shape {
+    command: "circle";
+    cx: number;
+    cy: number;
+    r: number;
+    /**
+     * 设置圆形参数
+     * @param cx - 圆心 X
+     * @param cy - 圆心 Y
+     * @param r - 半径
+     */
+    from(cx: number, cy: number, r: number): void;
+    hit(point: Point): boolean;
+    box(): BoundingBox;
+}
+
+type ImageSource = HTMLImageElement | ImageBitmap;
+declare class ImageShape extends Shape {
+    command: "image";
+    src: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    source: ImageSource | null;
+    from(src: string, x: number, y: number, width: number, height: number): this;
+    /** 直接传入已加载的图片对象（跳过 loader） */
+    fromElement(el: ImageSource, x: number, y: number, width: number, height: number): this;
+    hit(point: Point): boolean;
+    box(): BoundingBox;
+}
+
+declare const createShape: (type: string) => Shape;
+
+declare class EventObserver {
+    #private;
+    feats: Record<string, boolean>;
+    scene: Scene;
+    renderer: Renderer;
+    dispatcher: EventDispatcher;
+    constructor(scene: Scene, renderer: Renderer);
+    /** 幂等绑定：每种原生事件只注册一次 */
+    bindEvents(): void;
+    unbindEvents(): void;
+    dispose(): void;
+}
+
+interface RendxJSON {
+    version: 1;
+    width: number;
+    height: number;
+    layers: LayerJSON[];
+}
+interface LayerJSON {
+    name: string;
+    index: number;
+    culling?: boolean;
+    children: ChildJSON[];
+}
+type ChildJSON = NodeJSON | GroupJSON;
+interface GraphicsJSON {
+    name?: string;
+    className?: string;
+    z?: number;
+    visible?: boolean;
+    display?: boolean;
+    translate?: [number, number];
+    rotate?: number;
+    scale?: [number, number];
+    data?: AO;
+}
+interface NodeJSON extends GraphicsJSON {
+    type: 'node';
+    shapeType: string;
+    args: unknown[];
+    options?: unknown[];
+    attrs?: AO;
+    gradient?: GradientOptions;
+    clipPath?: ClipPath;
+}
+interface GroupJSON extends GraphicsJSON {
+    type: 'group';
+    children: ChildJSON[];
+}
+declare function serializeLayer(layer: Layer): LayerJSON;
+/** 序列化整个 App 场景为 JSON */
+declare function serialize(layers: Layer[], width: number, height: number): RendxJSON;
+/** 从 JSON 反序列化，创建层和节点（不包含 App 实例） */
+declare function deserialize(json: RendxJSON, cfg: Partial<RendererConfig>): Layer[];
+
+/**
+ * 插件接口
+ *
+ * 插件通过 `app.use(plugin)` 注册，框架会调用 `install(app)` 完成初始化。
+ * 当 App dispose 时，若插件提供了 `dispose` 方法，则会自动调用。
+ */
+interface Plugin {
+    /** 插件名称（用于去重和调试） */
+    name: string;
+    /** 安装插件，在 `app.use()` 时调用 */
+    install(app: App): void;
+    /** 当 App resize 时调用 */
+    resize?(width: number, height: number): void;
+    /** 卸载插件，在 `app.dispose()` 时自动调用 */
+    dispose?(): void;
+}
+
+interface AppConfig extends RendererConfig {
+    layers?: string[];
+    /** 是否监听容器尺寸变化自动 resize（默认 false） */
+    autoResize?: boolean;
+}
+/**
+ * Rendx 引擎顶层控制器，负责场景、渲染层、事件和插件的统一管理。
+ *
+ * @example
+ * ```ts
+ * const app = new App({ width: 800, height: 600 });
+ * app.mount(document.getElementById('container')!);
+ *
+ * const circle = Node.create('circle', { fill: '#f00' });
+ * circle.shape.from(400, 300, 50);
+ * app.scene.add(circle);
+ * app.render();
+ * ```
+ */
+declare class App {
+    #private;
+    cfg: AppConfig;
+    scene: Scene;
+    observer: EventObserver;
+    /** 挂载容器（供插件访问） */
+    get container(): HTMLDivElement | null;
+    /** 是否已挂载 */
+    get mounted(): boolean;
+    /**
+     * @param cfg - 引擎配置（width/height/layers/autoResize 等）
+     */
+    constructor(cfg?: Partial<AppConfig>);
+    /**
+     * 挂载到 DOM 容器，初始化渲染层并绑定事件。必须在 render() 之前调用。
+     * @param container - 目标 DOM 元素，引擎会在其中创建 Canvas 元素
+     */
+    mount(container: HTMLElement): this;
+    /** 添加渲染层 */
+    addLayer(name: string, index: number): Layer;
+    /** 获取层 */
+    getLayer(name: string): Layer | undefined;
+    /**
+     * 注册插件（同名插件不会重复注册）
+     * @param plugin - 实现 Plugin 接口的插件实例
+     */
+    use(plugin: Plugin): this;
+    /** 获取已注册的插件 */
+    getPlugin(name: string): Plugin | undefined;
+    /** 同步渲染一帧。适用于静态内容，仅重绘脏层 */
+    render(): void;
+    /** 请求异步渲染循环（rAF），有动画时自动继续，无变化时停止 */
+    requestRender(): void;
+    /**
+     * 调整画布尺寸，同步更新所有层、容器和视口矩阵
+     * @param width - 新宽度（像素）
+     * @param height - 新高度（像素）
+     */
+    resize(width: number, height: number): void;
+    clear(): void;
+    dispose(): void;
+    /** 将所有渲染层合成到一个 Canvas 上并返回 */
+    toCanvas(): HTMLCanvasElement;
+    /** 序列化所有渲染层的场景图为 JSON，可用于保存/回放 */
+    toJSON(): RendxJSON;
+    /**
+     * 从 JSON 快照创建新的 App 实例（静态工厂方法）
+     * @param json - 由 toJSON() 生成的场景快照
+     * @param cfg - 可选的额外配置（会与 json 中的 width/height 合并）
+     */
+    static fromJSON(json: RendxJSON, cfg?: Partial<AppConfig>): App;
+    /**
+     * 将 JSON 快照恢复到当前 App 实例（就地替换所有渲染层内容）。
+     * 与静态 fromJSON 不同，此方法不创建新 App，保留挂载状态和插件。
+     */
+    restoreFromJSON(json: RendxJSON): void;
+}
+
+export { App, type AppConfig, ArcShape, ArcTransform, AreaShape, AttributeTransform, Attributes, BaseTransform, type ChildJSON, CircleShape, ClipBoxTransform, CurveShape, EventDispatcher, type EventListener, type EventListenerOptions, EventObserver, EventTarget, Graphics, type GraphicsJSON, GraphicsTransform, Group, type GroupJSON, ImageShape, Layer, type LayerJSON, LineShape, Node, type NodeJSON, PathShape, type Plugin, PolygonShape, RectShape, Renderer, type RendererConfig, type RendxJSON, RoundShape, Scene, SectorShape, SectorTransform, Shape, type ShapeCommand, SimulatedEvent, SymbolShape, type TextMeasureFn, TextShape, type TransformStatus, createShape, deserialize, imageLoader, isHit, serialize, serializeLayer, setCanvasRenderingContext2StrokeAttrs };