@sliiu/present-renderer 0.0.0-stage → 0.1.1

package/dist/types/chart-ex-render.d.ts

@@ -0,0 +1,79 @@
+import type { ChartDef } from "@sliiu/present-core";
+export declare const CHART_EX_PALETTE: string[];
+export interface Plot {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export interface ChartExSlice {
+    label: string;
+    value: number;
+    color: string;
+}
+export interface TreemapCell extends ChartExSlice {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export interface SunburstArc extends ChartExSlice {
+    cx: number;
+    cy: number;
+    r0: number;
+    r1: number;
+    a0: number;
+    a1: number;
+}
+export interface WaterfallBar extends ChartExSlice {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    kind: "increase" | "decrease" | "total";
+}
+export interface FunnelSeg extends ChartExSlice {
+    points: [number, number][];
+}
+export interface ColumnBar extends ChartExSlice {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export interface ParetoLayout {
+    bars: ColumnBar[];
+    line: [number, number][];
+}
+export interface BoxWhiskerBar {
+    label: string;
+    color: string;
+    cx: number;
+    whiskerLow: number;
+    q1: number;
+    median: number;
+    q3: number;
+    whiskerHigh: number;
+    boxW: number;
+}
+export interface RegionRow extends ChartExSlice {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export declare function layoutHistogram(slices: ChartExSlice[], plot: Plot): ColumnBar[];
+export declare function layoutPareto(slices: ChartExSlice[], plot: Plot): ParetoLayout;
+export declare function layoutBoxWhisker(slices: ChartExSlice[], plot: Plot): BoxWhiskerBar[];
+export declare function layoutRegion(slices: ChartExSlice[], plot: Plot): RegionRow[];
+export declare function normalizeChartExSlices(def: ChartDef, opts?: {
+    preserveSign?: boolean;
+}): ChartExSlice[];
+/** Slice-and-dice treemap — 足够表达占比结构，编辑预览用。 */
+export declare function layoutTreemap(slices: ChartExSlice[], plot: Plot): TreemapCell[];
+/** 单层 sunburst：内环空心 + 外环扇区（扁平 categories）。 */
+export declare function layoutSunburst(slices: ChartExSlice[], plot: Plot): SunburstArc[];
+export declare function layoutWaterfall(slices: ChartExSlice[], plot: Plot): WaterfallBar[];
+export declare function layoutFunnel(slices: ChartExSlice[], plot: Plot): FunnelSeg[];
+export declare function sunburstArcPath(arc: SunburstArc): string;
+export declare function polygonPath(points: [number, number][]): string;

package/dist/types/chart-geom.d.ts

@@ -0,0 +1,112 @@
+import type { BarChartDef, ChartDef, ChartSeries, SurfaceChartDef } from "@sliiu/present-core";
+export interface PlotRect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export interface IsoQuad {
+    pts: Array<{
+        x: number;
+        y: number;
+    }>;
+    color: string;
+    stroke: boolean;
+}
+/** 散点 / 组合图系列的 (x,y) 点：优先 series.points，否则用分类下标 + values。 */
+export declare function seriesXyPoints(def: ChartDef, s: ChartSeries): Array<{
+    x: number;
+    y: number;
+    z?: number;
+}>;
+export declare function linearFit(xs: number[], ys: number[]): {
+    a: number;
+    b: number;
+} | null;
+/** Rough advance of `text` at `size` px: CJK glyphs are square, Latin about 0.58em. Legend rows used `length × 6` and overprinted CJK series names. */
+export declare function estimateTextWidth(text: string, size: number): number;
+/**
+ * Bottom padding of the plot: room for the category labels (they used to be drawn 14px under
+ * the plot into an 8px pad, and the legend was then drawn over them) plus a legend row.
+ */
+export declare function chartPadding(def: ChartDef, textSize: number): {
+    bottom: number;
+    legend: number;
+};
+/**
+ * Geometry shared by the bar renderer and the data-label overlay. Labels used to be placed on
+ * the line chart's x positions (i · w/(n−1)), so on a clustered column chart every label sat a
+ * bar to the right of its column and clustered labels overprinted each other.
+ */
+export interface BarGeometry {
+    isHoriz: boolean;
+    stacked: boolean;
+    ticks: number[];
+    tmin: number;
+    tmax: number;
+    /** Width (columns) or height (bars) of one category group. */
+    groupStep: number;
+    /** Width of the cluster inside a group (70 % of the group). */
+    inner: number;
+    /** Width of one bar in the cluster (the whole cluster when stacked). */
+    barW: number;
+    /** Per-category totals; used for percent-stacked scaling. */
+    totals: number[];
+}
+export declare function barGeometry(def: BarChartDef, plot: PlotRect, sharedTicks?: number[]): BarGeometry;
+export interface BarLabelAnchor {
+    x: number;
+    y: number;
+    anchor: "middle" | "start" | "end";
+    /** Where the text sits relative to `y`: above it (bottom baseline), centred on it, or below it (top). */
+    baseline: "bottom" | "middle" | "top";
+}
+/**
+ * Where the value label of series `si`, category `ci` goes: just past the free end of a
+ * clustered bar (above a column, right of a horizontal bar), or centred in a stacked segment.
+ * `stackBefore` is the signed running total of the segments under this one (stacked only).
+ */
+export declare function barLabelAnchor(geo: BarGeometry, plot: PlotRect, si: number, ci: number, v: number, stackBefore?: number): BarLabelAnchor;
+export declare function applyValueAxisScale(yMin: number, yMax: number, def: ChartDef): {
+    yMin: number;
+    yMax: number;
+};
+/**
+ * 曲面图等距网格：系列 = Y 行，分类 = X 列，values = Z。
+ * 单系列时沿 Y 挤一条薄带，避免退化成折线。
+ */
+export declare function surfaceIsoQuads(def: SurfaceChartDef, plot: PlotRect): IsoQuad[];
+export declare function comboXyPlotX(xVal: number, cats: string[], plot: PlotRect, xs: number[]): number;
+export declare function pointLabelText(def: ChartDef, s: ChartSeries, i: number, v: number): string | undefined;
+/** 3D 柱/条预览的挤出偏移（view3D rotX/rotY → 屏幕位移）。 */
+export declare function chart3DOffset(def: ChartDef): {
+    dx: number;
+    dy: number;
+} | null;
+export interface ChartTextStyle {
+    /** Title / data-label colour. */
+    text: string;
+    /** Axis tick / category / legend label colour. */
+    muted: string;
+    /** Axis line colour. */
+    axis: string;
+    /** Gridline colour. */
+    grid: string;
+    /** Label font size in px (OOXML default 10pt ≈ 13px). */
+    size: number;
+}
+/**
+ * Chart-wide text and line colours. `def.textColor` / `def.lineColor` (chartSpace txPr, axis spPr)
+ * win; otherwise the neutral greys PowerPoint uses on a white chart area. A single text colour
+ * gives labels at full strength and ticks / legend at 75% towards the line colour so a dark-theme
+ * chart keeps the same hierarchy a light one has.
+ */
+export declare function chartTextStyle(def: Pick<ChartDef, "textColor" | "textSize" | "lineColor">): ChartTextStyle;
+/** Linear mix of two #rrggbb colours; `t` = weight of `b`. */
+export declare function mixHex(a: string, b: string, t: number): string;
+/**
+ * "Nice" value-axis ticks: about `count` steps at 1 / 2 / 5 × 10ⁿ. (0..1500 → 0, 500, 1000, 1500;
+ * not one line per hundred.)
+ */
+export declare function niceTicks(min: number, max: number, count?: number): number[];
+export declare function shadeHex(color: string, factor: number): string;

package/dist/types/chart-svg.d.ts

@@ -0,0 +1,2 @@
+import type { ChartShape } from "@sliiu/present-core";
+export declare function renderChart(g: SVGGElement, shape: ChartShape): void;

package/dist/types/compose.d.ts

@@ -0,0 +1,2 @@
+import type { Layer, Slide, SlideMaster } from "@sliiu/present-core";
+export declare function composeSlideForRender(slide: Slide, masters: SlideMaster[] | undefined): Layer[];

package/dist/types/effect-clip.d.ts

@@ -0,0 +1,10 @@
+import type { Rect } from "@sliiu/present-core";
+export interface EffectGeom {
+    filter: string;
+    prLst: string | undefined;
+    progress: number;
+    bbox: Rect;
+    transition?: "in" | "out" | "none";
+}
+export declare function effectClipPathD(geom: EffectGeom): string;
+export declare function effectClipUsesEvenOdd(geom: EffectGeom): boolean;

package/dist/types/entrance-hide.d.ts

@@ -0,0 +1,16 @@
+import { type Slide } from "@sliiu/present-core";
+import type { Scene } from "./scene-node.js";
+/**
+ * 放映专用：按当前 timing 把 entrance 目标在 scene 上藏起来（opacity=0 / 段落级 hide）。
+ *
+ * 编辑器会 `forceVisibleForEdit`，让入场图形在编辑态全部可见；分享 / 导出 / 直播快照
+ * 打的是这份数据。播放器必须在这里重算 hidden-until-entrance，不能依赖 shape.opacity。
+ */
+export declare function applyEntranceHideToScene(scene: Scene, slide: Slide): void;
+/**
+ * 放映缩略图 / 下一张预览：画出设计稿，而不是「点击前隐藏」的初态。
+ *
+ * 进入放映时编辑器会把 entrance 目标的 opacity 写回 0。播放舞台要这个初态，
+ * 缩略图如果跟着藏，演讲者看到的是空白页。只改 scene，不改 slide 数据。
+ */
+export declare function revealDesignedAppearance(scene: Scene, slide: Slide): void;

package/dist/types/font-stack.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Font fallback for the browser. OOXML names one typeface per run ("Inter", "Songti SC"); when the
+ * machine lacks it PowerPoint substitutes a face of the same class (sans / serif / mono), but a
+ * browser given a bare unknown family falls back to its default — usually a serif — so a sans deck
+ * comes up in Times. Append the class-matched generic (plus CJK faces so Han glyphs never hit a
+ * Latin-only fallback) to every family that is not already a stack.
+ */
+/** `family` as a CSS font-family list with a class-matched generic fallback appended. */
+export declare function withFontFallback(family: string | undefined | null): string;

package/dist/types/hit-geom.d.ts

@@ -0,0 +1,15 @@
+import type { SceneNode } from "./scene-node.js";
+/**
+ * 撤销单个 SceneNode 的绘制变换，与 canvas/svg backend 对偶：
+ * translate(tx,ty) → rotate around bbox center → scale around center。
+ */
+export declare function inverseSceneNode(n: SceneNode, x: number, y: number): {
+    x: number;
+    y: number;
+};
+/** 世界坐标 → 该节点未旋转 bbox 空间（含祖先 group 变换）。 */
+export declare function worldToLocal(node: SceneNode, x: number, y: number): {
+    x: number;
+    y: number;
+};
+export declare function hitTestNodeBBox(node: SceneNode, worldX: number, worldY: number): boolean;

package/dist/types/hybrid-backend.d.ts

@@ -0,0 +1,21 @@
+import type { Scene } from "./scene-node.js";
+import { SvgBackend } from "./svg-backend.js";
+export interface HybridBackendOptions {
+    background?: string;
+    interactive?: boolean;
+    /** 传给 SVG 段。false 时伸出幻灯片的矢量形状仍画在工作区里。 */
+    clipToSlide?: boolean;
+}
+export declare class HybridBackend {
+    readonly host: HTMLElement;
+    readonly svg: SvgBackend;
+    private wrapper;
+    private backends;
+    constructor(scene: Scene, container: HTMLElement, opts?: HybridBackendOptions);
+    get svgRoot(): SVGSVGElement;
+    /** 同步刷新所有子 backend；详见 SvgBackend.flush。 */
+    flush(): void;
+    /** 等待所有 live 3D（WebGLShapeBackend）首帧就绪——截图 / visual-compare 前调。 */
+    waitForReady(): Promise<void>;
+    destroy(): void;
+}

package/dist/types/hybrid-segments.d.ts

@@ -0,0 +1,11 @@
+import type { SceneNode } from "./scene-node.js";
+export type HybridSegKind = "canvas" | "svg" | "webgl" | "webglm3d";
+export interface HybridSegment {
+    kind: HybridSegKind;
+    ids: string[];
+}
+/**
+ * 按绘制顺序切段。组合不单独成段：非 3D 子形状留在组合被归入的那一类（图片在组合里
+ * 仍走 SVG），3D 子形状在它自己的 z 序位置拆成 webgl 段，这样字可以盖在挤出体上面。
+ */
+export declare function buildHybridSegments(children: SceneNode[]): HybridSegment[];

package/dist/types/index.d.ts

@@ -0,0 +1,24 @@
+export * from "./scene-node.js";
+export { applyEntranceHideToScene, revealDesignedAppearance } from "./entrance-hide.js";
+export * from "./compose.js";
+export * from "./svg-backend.js";
+export * from "./canvas-backend.js";
+export * from "./hybrid-backend.js";
+export { WebGLShapeBackend, type WebGLShapeBackendOptions } from "./webgl-shape-backend.js";
+export { WebGLModel3DBackend, type WebGLModel3DBackendOptions } from "./webgl-model3d-backend.js";
+export { stageChromeBackground } from "./stage-chrome.js";
+export { mountMorphTransitionLayers, type MorphTransitionMount } from "./morph-transition.js";
+export * from "./selection.js";
+export { renderPaint, applyStroke as applySvgStroke } from "./paint-svg.js";
+export { paintToCanvasStyle, applyStroke as applyCanvasStroke, getImage, waitForImagesLoaded } from "./paint-canvas.js";
+export { getVideoPosterFrame, waitForVideoFrames } from "./video-frame.js";
+export { getModel3DPreviewFrame, waitForModel3DFrames } from "./model3d-frame.js";
+export { renderChart } from "./chart-svg.js";
+export { drawChartCanvas } from "./chart-canvas.js";
+export { effectClipPathD, effectClipUsesEvenOdd } from "./effect-clip.js";
+export * from "./text-shared.js";
+export * from "./text-stacked.js";
+export { runLinkAt, hitTestTextRunAt } from "./text-hit.js";
+export { worldToLocal, hitTestNodeBBox, inverseSceneNode } from "./hit-geom.js";
+export { shapeFrontImageSrc } from "./shape-front.js";
+export { warpActive, sampleWarpPath, placeGlyphsOnWarp } from "./text-warp.js";

package/dist/types/linked-src.d.ts

@@ -0,0 +1,13 @@
+/** 浏览器无法加载 `file:` 外链图；画带文件名的占位，避免空白碎图。
+ *  Node 下若本地文件仍在，读成 data URL 仅供预览，**不改 IR 的 src**（否则 round-trip 会丢掉 r:link）。
+ */
+export declare function isFileLinkedSrc(src: string | undefined): boolean;
+export declare function linkedImageLabel(src: string): string;
+export declare function linkedImagePlaceholderDataUri(src: string, w?: number, h?: number): string;
+export declare function displayImageSrc(src: string, w?: number, h?: number): string;
+export declare function drawLinkedImagePlaceholder(ctx: CanvasRenderingContext2D, bbox: {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}, src: string): void;

package/dist/types/metafile-preview.d.ts

@@ -0,0 +1,11 @@
+export declare const METAFILE_MARKER_SRC: string;
+export declare function isMetafileDataUrl(src: string): boolean;
+/** EMF 签名在偏移 40（" EMF"）。可放置 WMF 以 0x9AC6CDD7 开头。 */
+export declare function isMetafileBytes(bytes: Uint8Array, mime?: string): boolean;
+/**
+ * 画布该用的地址。
+ * 返回空字符串表示图元文件还在转，调用方先留白，完成后再画。
+ * 转失败返回虚线占位。普通图片原样返回。
+ */
+export declare function previewImageSrc(src: string, img: HTMLImageElement | undefined, onReady?: () => void): string;
+export declare function waitForMetafilePreviews(): Promise<void>;

package/dist/types/model3d-frame.d.ts

@@ -0,0 +1,8 @@
+import * as THREE from "three";
+import type { Model3DShape } from "@sliiu/present-core";
+export declare function loadGltfScene(src: string): Promise<THREE.Object3D>;
+export declare function applyModel3DCameraPose(cam: THREE.PerspectiveCamera, latDeg: number, lonDeg: number, dist?: number): void;
+export declare function applyModel3DCamera(cam: THREE.PerspectiveCamera, s: Model3DShape): void;
+export declare function applyModel3DTransform(root: THREE.Object3D, s: Model3DShape): void;
+export declare function getModel3DPreviewFrame(s: Model3DShape, onReady?: () => void): HTMLImageElement | null;
+export declare function waitForModel3DFrames(timeoutMs?: number): Promise<void>;

package/dist/types/model3d-render.d.ts

@@ -0,0 +1,4 @@
+import type { Model3DShape } from "@sliiu/present-core";
+export declare function model3DDisplaySrc(s: Model3DShape, onReady?: () => void): string | undefined;
+export declare function drawModel3DCanvas(ctx: CanvasRenderingContext2D, s: Model3DShape, onReady?: () => void): void;
+export declare function renderModel3DSvg(container: SVGGElement, s: Model3DShape, onReady?: () => void): void;

package/dist/types/morph-transition.d.ts

@@ -0,0 +1,15 @@
+import type { Scene } from "./scene-node.js";
+export interface MorphTransitionMount {
+    ghost: HTMLElement;
+    target: HTMLElement;
+    cleanup(): void;
+}
+/**
+ * Mount SVG shape layers for morph (FLIP) when the live stage lacks per-shape DOM
+ * ids (canvas / hybrid bitmap segments). Pure-SVG stages only need the ghost overlay.
+ */
+export declare function mountMorphTransitionLayers(stageWrap: HTMLElement, stage: HTMLElement, prevScene: Scene, curScene: Scene, opts?: {
+    ghostZIndex?: number;
+    stageZIndex?: number;
+    chromeBg?: string;
+}): MorphTransitionMount;

package/dist/types/node-affine.d.ts

@@ -0,0 +1,22 @@
+import type { SceneNode } from "./scene-node.js";
+/** 2D 仿射：x' = a x + c y + e，y' = b x + d y + f。与 SVG / Canvas 的矩阵一致。 */
+export interface Aff {
+    a: number;
+    b: number;
+    c: number;
+    d: number;
+    e: number;
+    f: number;
+}
+export declare function affMul(m: Aff, n: Aff): Aff;
+/** 单个节点的 SVG 变换：先绕 bbox 中心旋转缩放，再平移 tx/ty。 */
+export declare function nodeAffine(node: SceneNode): Aff;
+/** 从最外层祖先乘到自身。幻灯片根是恒等变换，乘进去不改变结果。 */
+export declare function accumulatedAffine(node: SceneNode): Aff;
+/**
+ * wrapper 已放在 slide 坐标 (originX, originY)。CSS transform-origin 为 0 0 时，
+ * 用这个矩阵才能让视觉位置等于 accumulatedAffine。
+ */
+export declare function cssAffineForBox(m: Aff, originX: number, originY: number): Aff;
+export declare function chainOpacity(node: SceneNode): number;
+export declare function chainHidden(node: SceneNode): boolean;

package/dist/types/ole-render.d.ts

@@ -0,0 +1,7 @@
+import type { OleObjectShape } from "@sliiu/present-core";
+/** Full-bleed package preview (not icon mode). */
+export declare function oleUsesPackagePreview(s: OleObjectShape): boolean;
+/** Canvas / export path: package preview or icon tile + filename. */
+export declare function drawOleCanvas(ctx: CanvasRenderingContext2D, s: OleObjectShape): void;
+/** SVG preview path — package preview via image / PDF embed, else icon placeholder. */
+export declare function renderOleSvg(container: SVGGElement, s: OleObjectShape): void;

package/dist/types/paint-canvas.d.ts

@@ -0,0 +1,22 @@
+import type { Paint, Rect, Stroke } from "@sliiu/present-core";
+export declare function getImage(src: string, onLoad?: () => void): HTMLImageElement;
+/**
+ * 等待 imageCache 里所有尚未落定的图片 load/error 完成。
+ *
+ * 截图 / PDF 导出前必须调用：CanvasBackend（以及 image-paint 填充）只在
+ * `img.complete && naturalWidth > 0` 时才 drawImage，否则静默跳过。导出时若不等待图片
+ * 解码完成，就会随机丢图——同一份 deck 先后导出 PNG / PDF 结果不一致正是这个原因。
+ *
+ * 调用前应先让 backend 跑过一次绘制（flush），把所有 src 注册进 imageCache 并开始加载。
+ * 每张图带超时兜底，避免坏链 / 慢图把导出永久卡死。
+ */
+export declare function waitForImagesLoaded(timeoutMs?: number): Promise<void>;
+/**
+ * shapeHint：承载填充的形状轮廓类别，仅影响 gradFill path="shape"（等值线沿轮廓）
+ * 的解释——矩形轮廓走精确的"矩形框带"pattern，其它轮廓退回径向近似。
+ */
+export declare function paintToCanvasStyle(ctx: CanvasRenderingContext2D, paint: Paint | undefined, bbox: Rect, onAsset?: () => void, shapeHint?: "rect" | "ellipse" | "other"): string | CanvasGradient | CanvasPattern;
+export declare function adjustImage(img: HTMLImageElement, adj: import("@sliiu/present-core").ImageColorAdjust): HTMLCanvasElement;
+/** 图片已加载时返回调色后的 data URL，供 SVG `<image href>` 使用。 */
+export declare function rasterizedAdjustHref(src: string, adj: import("@sliiu/present-core").ImageColorAdjust, onLoad?: () => void): string | undefined;
+export declare function applyStroke(ctx: CanvasRenderingContext2D, stroke: Stroke | undefined, bbox: Rect, onAsset?: () => void): boolean;

package/dist/types/paint-svg.d.ts

@@ -0,0 +1,19 @@
+import type { Paint, Stroke } from "@sliiu/present-core";
+export interface PaintAttrs {
+    paint: string;
+    opacity?: number;
+    defNode?: SVGElement;
+    defId?: string;
+}
+/**
+ * shapeHint：承载该填充的形状轮廓类别，仅影响 gradFill path="shape" 的解释
+ * （ECMA-376 §20.1.8.30 <a:path path="shape"> = 渐变等值线沿形状轮廓）——
+ * 矩形轮廓走精确的"矩形框带"渲染，椭圆等其它轮廓走椭圆 radial 近似。
+ */
+export declare function renderPaint(paint: Paint | undefined, defs: SVGDefsElement, bbox?: {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}, onAsset?: () => void, shapeHint?: "rect" | "ellipse" | "other"): PaintAttrs;
+export declare function applyStroke(el: SVGGraphicsElement, stroke: Stroke | undefined, defs: SVGDefsElement, idPrefix?: string): void;

package/dist/types/scene-node.d.ts

@@ -0,0 +1,128 @@
+import type { Animatable } from "@sliiu/present-animation";
+import type { ClipState, Paint, Shape, Slide } from "@sliiu/present-core";
+export interface ParaOverride {
+    opacity?: number;
+    tx?: number;
+    ty?: number;
+    scale?: number;
+    scaleX?: number;
+    scaleY?: number;
+    rotation?: number;
+    visible?: boolean;
+    clip?: ClipState;
+    fillColor?: string;
+    fontColor?: string;
+    fontSize?: number;
+    fontWeight?: number | string;
+    fontStyle?: boolean;
+    fontFamily?: string;
+    underline?: string;
+}
+/** iterate 子目标上的属性叠在段落动画之上（同名字段以后者为准）。 */
+export declare function mergeParaOverrides(base?: ParaOverride, over?: ParaOverride): ParaOverride | undefined;
+export interface CharRangeOverride extends ParaOverride {
+    start: number;
+    end: number;
+    unit: "char" | "word";
+}
+export type PropertyListener = (key: string, value: unknown, node: SceneNode) => void;
+export declare class SceneNode implements Animatable {
+    readonly id: string;
+    shape: Shape;
+    parent: SceneNode | null;
+    children: SceneNode[];
+    layerId: string;
+    tx: number;
+    ty: number;
+    scale: number;
+    scaleX: number;
+    scaleY: number;
+    rotation: number;
+    /** 动画写入的旋转增量。渲染角 = shape.transform.rotation + animRotation。 */
+    animRotation: number;
+    opacity: number;
+    widthScale: number;
+    heightScale: number;
+    clip: ClipState | null;
+    fillOverride: string | null;
+    strokeOverride: string | null;
+    strokeWidthOverride: number | null;
+    visibleOverride: boolean | null;
+    paraOverrides: Map<number, ParaOverride>;
+    charOverrides: Map<number, Map<string, CharRangeOverride>>;
+    mediaEl: HTMLMediaElement | null;
+    private lastMediaAction;
+    private listeners;
+    constructor(shape: Shape, layerId: string);
+    private shapeRotation;
+    on(fn: PropertyListener): () => void;
+    private fire;
+    /**
+     * 触发一次 backend redraw 而**不**改变任何节点 / shape 属性。用于离屏光栅 3D 烘焙
+     * 把结果写进 shape.meta3D.bakedSrc 副通道后，让 SvgBackend / CanvasBackend 重画读取
+     * 新的 bakedSrc（既不污染 shape.src/bbox，也不影响 live WebGL 视图）。
+     */
+    markDirty(): void;
+    /**
+     * 内部用：跳过外部 setProperty 的开关 / 派发逻辑，直接把 opacity 强制设为 v 并
+     * 通知 listener。专门给 ParagraphAnimatable / CharRangeAnimatable 在 reveal
+     * 文字时同步解除 ancestor group hide 用，避免在每次字符 reveal 都走完整 setProperty
+     * switch（性能 + 也避免触发不必要 fire-key 字符串）。
+     */
+    forceOpacity(v: number): void;
+    setProperty(key: string, value: unknown): void;
+    private applyEffectClip;
+    getProperty(key: string): unknown;
+    walk(fn: (n: SceneNode) => void): void;
+    findById(id: string): SceneNode | null;
+    resetAnimState(): void;
+    setParaProperty(idx: number, key: string, value: unknown): void;
+    getParaProperty(idx: number, key: string): unknown;
+    setCharRangeProperty(paraIdx: number, unit: "char" | "word", start: number, end: number, key: string, value: unknown): void;
+    getCharRangeProperty(paraIdx: number, unit: "char" | "word", start: number, end: number, key: string): unknown;
+}
+export declare function netFlipParity(node: SceneNode): {
+    x: number;
+    y: number;
+};
+export declare class ParagraphAnimatable implements Animatable {
+    readonly node: SceneNode;
+    readonly paraIdx: number;
+    constructor(node: SceneNode, paraIdx: number);
+    setProperty(key: string, value: unknown): void;
+    getProperty(key: string): unknown;
+}
+export declare class CharRangeAnimatable implements Animatable {
+    readonly node: SceneNode;
+    readonly paraIdx: number;
+    readonly unit: "char" | "word";
+    readonly start: number;
+    readonly end: number;
+    constructor(node: SceneNode, paraIdx: number, unit: "char" | "word", start: number, end: number);
+    setProperty(key: string, value: unknown): void;
+    getProperty(key: string): unknown;
+}
+export declare function resolveAnimatable(scene: Scene, id: string): Animatable | null;
+export interface Scene {
+    width: number;
+    height: number;
+    background?: Shape | null;
+    slide: Slide;
+    layerNodes: Map<string, SceneNode[]>;
+    root: SceneNode;
+}
+export interface CreateSceneOptions {
+    masters?: import("@sliiu/present-core").SlideMaster[];
+}
+export declare function createScene(slide: Slide, size: {
+    width: number;
+    height: number;
+}, options?: CreateSceneOptions): Scene;
+/** `useBgFill`：用幻灯片合成背景填形状，坐标系对齐整页而不是 shape bbox。 */
+export declare function shapeRenderFill(s: Shape, scene: Scene, node?: SceneNode): Paint | undefined;
+export declare function shapeRenderFillBBox(s: Shape, scene: Scene, node?: SceneNode): {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};

package/dist/types/selection.d.ts

@@ -0,0 +1,22 @@
+import type { Rect } from "@sliiu/present-core";
+import type { Scene, SceneNode } from "./scene-node.js";
+export interface HitOptions {
+    ignoreLocked?: boolean;
+}
+export declare class Selection {
+    private ids;
+    private listeners;
+    get(): string[];
+    has(id: string): boolean;
+    set(ids: string[]): void;
+    add(id: string): void;
+    remove(id: string): void;
+    toggle(id: string): void;
+    clear(): void;
+    on(fn: (ids: Set<string>) => void): () => void;
+    private fire;
+}
+export declare function nodeWorldBBox(node: SceneNode): Rect;
+export declare function hitTest(scene: Scene, x: number, y: number, opts?: HitOptions): SceneNode | null;
+export declare function pointInNode(node: SceneNode, x: number, y: number): boolean;
+export declare function attachPointerSelection(hostEl: HTMLElement, scene: Scene, selection: Selection): () => void;

package/dist/types/shape-effects.d.ts

@@ -0,0 +1,13 @@
+import type { GlowEffect, ReflectionEffect, ShadowEffect, Shape, SoftEdgeEffect } from "@sliiu/present-core";
+export interface CollectedShapeEffects {
+    outer: ShadowEffect[];
+    glow: GlowEffect[];
+    inner?: ShadowEffect;
+    softEdge?: SoftEdgeEffect;
+    reflection?: ReflectionEffect;
+}
+export declare function collectShapeEffects(s: Shape): CollectedShapeEffects;
+export declare function hasAnyEffect(fx: CollectedShapeEffects): boolean;
+export declare function effectHexWithAlpha(color: string, alpha: number): string;
+/** outer shadow + glow 的 CSS filter 链（SVG style.filter / Canvas ctx.filter 通用）。 */
+export declare function cssFilterForEffects(fx: CollectedShapeEffects): string;

package/dist/types/shape-front.d.ts

@@ -0,0 +1,4 @@
+import type { Shape } from "@sliiu/present-core";
+import type { Scene } from "./scene-node.js";
+/** 文字 3D 的正面：字形画进 PNG，再贴到挤出体上。非文字返回 undefined。 */
+export declare function shapeFrontImageSrc(scene: Scene, shape: Shape): string | undefined;

package/dist/types/stage-chrome.d.ts

@@ -0,0 +1,8 @@
+import type { Slide } from "@sliiu/present-core";
+/**
+ * CSS background for the stage / hybrid wrapper chrome around the scene.
+ * When the slide has a painted background, createScene injects a full-slide
+ * __bg_* shape — a second opaque underlay would show through image alpha or
+ * mask gradient edges. Use white only when the slide has no background paint.
+ */
+export declare function stageChromeBackground(slide?: Slide): string;