跳转到内容

前端 SDK 导出:CanvasLocateService – ClockIcon

本页由当前 SDK 声明自动生成。 导入入口:@woohaa3/frontend/extension-api。

返回接口索引

CanvasLocateService · CanvasNavigationService · CanvasRemoteService · CanvasRunRequest · CanvasRunResult · CanvasRuntimeService · CanvasRuntimeStatus · CanvasScopeService · CanvasSession · CanvasSessionPhase · CanvasSessionStatus · CanvasSlotProps · CanvasStoreFacade · CanvasSwitcherIcon · CanvasSyncStatus · CatalogState · ChatIcon · CheckIcon · ChevronDownIcon · ChevronRightIcon · ClapperboardIcon · ClientMark · ClippingMaskIcon · ClockIcon

CanvasLocateService

export type CanvasLocateService = {
locateNodes(nodeIds: readonly string[], options?: {
select?: boolean;
fit?: boolean;
safeArea?: {
left: number;
top: number;
right: number;
bottom: number;
};
}): LocateNodesResult;
locateSelection(nodeIds: readonly string[]): LocateNodesResult;
};

关联类型:LocateNodesResult

成员说明:

  • locateNodes:定位一批节点:select=false 时不改选区(例如定位当前多选)。 默认保持缩放居中;fit 显式按实际呈现边界容纳整批节点。 返回 ok:false 表示目标已失效或宿主未就绪,不改变视口。
  • locateSelection:定位当前选区中心(不改选区)。

CanvasNavigationService

export interface CanvasNavigationService {
getSnapshot(): CanvasPresentationSnapshot;
subscribe(listener: () => void): () => void;
dispatch(intent: CanvasNavigationIntent): CanvasNavigationResult;
openPanel(route: CanvasPanelRoute): CanvasNavigationResult;
closePanel(panelType?: CanvasPanelType): CanvasNavigationResult;
openMenu(route: CanvasMenuRoute): CanvasNavigationResult;
closeMenu(): CanvasNavigationResult;
enterNodeFocus(input: {
nodeId: string;
kind: CanvasFocusKind;
owner?: "direct" | "history";
preserveOverviewReturn?: boolean;
}): CanvasNavigationResult;
enterDocumentWorkspace(documentId: string, options?: {
preserveOverviewReturn?: boolean;
}): CanvasNavigationResult;
exitNodeFocus(): CanvasNavigationResult;
openNodeHistory(input: {
nodeId: string;
kind: CanvasFocusKind;
}): CanvasNavigationResult;
closeNodeHistory(): CanvasNavigationResult;
invalidateNodeFocus(reason?: string): CanvasNavigationResult;
clearTransientSurfaces(): CanvasNavigationResult;
resetPresentation(): CanvasNavigationResult;
reconcile(validNodeIds: ReadonlySet<string>): CanvasNavigationResult;
openDialog(request: {
dialogId: string;
payload?: unknown;
}): {
ok: boolean;
error?: string;
};
requestOpenDialog(request: {
dialogId: string;
payload?: unknown;
canvasId?: string | null;
}): Promise<CanvasModalOpenResult>;
requestExitNodeFocus(): Promise<CanvasNavigationResult>;
requestEnterNodeFocus(input: {
nodeId: string;
kind: CanvasFocusKind;
owner?: "direct" | "history";
preserveOverviewReturn?: boolean;
signal?: AbortSignal;
}): Promise<CanvasNavigationResult>;
requestEnterDocumentWorkspace(documentId: string, options?: {
preserveOverviewReturn?: boolean;
}): Promise<CanvasNavigationResult>;
requestOpenNodeHistory(input: {
nodeId: string;
kind: CanvasFocusKind;
}): Promise<CanvasNavigationResult>;
requestCloseNodeHistory(): Promise<CanvasNavigationResult>;
registerPanel(definition: CanvasPanelDefinition): () => void;
registerMenu(definition: CanvasMenuDefinition): () => void;
resolvePanel(type: string): CanvasPanelDefinition | null;
resolveMenu(type: string): CanvasMenuDefinition | null;
panelAvailable(route: CanvasPanelRoute): boolean;
registerCleanup(key: string, cleanup: CanvasSurfaceCleanup): () => void;
registerNodeFocusGuard(id: string, guard: (input: {
nodeId: string;
kind: CanvasFocusKind;
owner: "direct" | "history";
preserveOverviewReturn?: boolean;
}) => string | null): () => void;
setFocusAdapter(adapter: CanvasLayoutAdapter): () => void;
getDiagnostic(): string | null;
}

关联类型:CanvasPresentationSnapshot · CanvasNavigationIntent · CanvasNavigationResult · CanvasPanelRoute · CanvasPanelType · CanvasMenuRoute · CanvasFocusKind · CanvasModalOpenResult · CanvasPanelDefinition · CanvasMenuDefinition · CanvasSurfaceCleanup · CanvasLayoutAdapter

成员说明:

  • dispatch:串行 transition 入口。
  • enterDocumentWorkspace:进入/切换独立文档工作区呈现(不伪造节点;同一 documentId 重入为无操作)。
  • openDialog:Dialog facade(design D4):把打开请求交给 Dialog Service;Dialog 入栈前由 pre-commit participant 清理 menu/panel。
  • requestOpenDialog:受控异步模态打开。 与 openDialog 的区别:先经聚焦编辑结算(dirty focus 由用户决定保存/放弃,取消或失败 则不入栈也不清理现场),再打开 Dialog。请求串行处理,并校验原 canvas/focus generation: 等待期间切换画布、聚焦目标或 exit coordinator 状态改变时,迟到结果一律丢弃。
  • requestExitNodeFocus:请求受控退出聚焦 。 先经退出协调器异步结算净变化,成功后再 dispatch exit-node-focus;失败保留现场。 无净变化时同步可逆退出。重复请求合并。
  • requestEnterDocumentWorkspace:请求进入独立文档工作区呈现(先结算当前聚焦的净变化,再原子发布)。
  • requestCloseNodeHistory:取消聚焦历史:先复制返回意图,由退出协调器接管。
  • resolvePanel:解析当前注册的 panel/menu definition(供 Host 渲染)。
  • panelAvailable:route 对应的 definition 是否已注册且通过 payload 校验 。
  • registerCleanup:注册 panel/menu owner 的 surface cleanup;返回 disposer。
  • registerNodeFocusGuard:Feature readiness gate before entering node focus. A rejection preserves the canvas.
  • setFocusAdapter:注册 mode effect adapter(canvas-runtime)。
  • getDiagnostic:诊断。

CanvasRemoteService

export interface CanvasRemoteService {
issueWorldToolContext(input: import("@woohaa3/contracts").WorldToolContextRequest, signal?: AbortSignal): Promise<WorldRemoteOutcome<import("@woohaa3/contracts").WorldToolContextOutcome>>;
revokeWorldToolContext(input: import("@woohaa3/contracts").WorldToolContextRevokeInput, signal?: AbortSignal): Promise<WorldRemoteOutcome<{
ok: true;
} | import("@woohaa3/contracts").WorldAuthoringFailure>>;
saveWorldCamera(input: import("@woohaa3/contracts").WorldCameraSettingsSaveInput, signal?: AbortSignal): Promise<WorldRemoteOutcome<import("@woohaa3/contracts").WorldCameraSettingsSaveOutcome>>;
restoreWorldCamera(input: import("@woohaa3/contracts").WorldCameraRestoreInput, signal?: AbortSignal): Promise<WorldRemoteOutcome<import("@woohaa3/contracts").WorldCameraRestoreOutcome>>;
listWorldCameraHistory(input: import("@woohaa3/contracts").WorldCameraHistoryListInput, signal?: AbortSignal): Promise<WorldRemoteOutcome<import("@woohaa3/contracts").WorldCameraHistoryListOutcome>>;
prepareSceneArea(input: {
canvasId: string;
areaId: string;
}, signal?: AbortSignal): Promise<WorldRemoteOutcome<import("@woohaa3/contracts").WorldAuthoringPrepareOutcome>>;
executeSceneArea(input: import("@woohaa3/contracts").WorldAuthoringExecuteInput, signal?: AbortSignal): Promise<WorldRemoteOutcome<import("@woohaa3/contracts").WorldAuthoringExecuteOutcome>>;
listResourceEdits?(input: {
canvasId: string;
runId: string;
}, signal?: AbortSignal): Promise<{
ok: true;
commands: Array<{
commandId: string;
revision: number;
}>;
} | {
ok: false;
message: string;
}>;
replayResourceEdit?(input: {
canvasId: string;
sourceCommandId: string;
previousCommandId: string;
operationId: string;
direction: "undo" | "redo";
}, signal?: AbortSignal): Promise<{
ok: true;
commandId: string;
revision: number;
duplicate: boolean;
} | {
ok: false;
message: string;
}>;
historySceneArea(direction: "undo" | "redo", input: import("@woohaa3/contracts").WorldAuthoringHistoryInput, signal?: AbortSignal): Promise<WorldRemoteOutcome<import("@woohaa3/contracts").WorldAuthoringHistoryOutcome>>;
openCanvasSession(canvasId: string, roomEpoch: string | null): SyncSocket;
closeCanvasSession(): void;
reconnectCanvasSession(): void;
run(request: CanvasRunRequest): Promise<CanvasRunResult>;
freezeWorldCapture(input: {
cameraId: string;
requestId?: string;
signal?: AbortSignal;
}): Promise<CanvasCaptureFreezeResult>;
listPendingPageCaptures(signal?: AbortSignal): Promise<PageCapturePendingResult>;
reportPageCaptureProgress(input: import("@woohaa3/contracts").WorldCapturePageProgress, signal?: AbortSignal): Promise<boolean>;
retryPageCapture(cameraId: string, signal?: AbortSignal): Promise<boolean>;
listWorldCaptureStatuses(signal?: AbortSignal): Promise<WorldCaptureStatusResult>;
commitPageVideoCapture(input: {
attemptId?: string;
signal?: AbortSignal;
cameraId: string;
key: import("@woohaa3/contracts").WorldCaptureDynamicVersionKey;
mp4: Uint8Array;
width: number;
height: number;
}): Promise<CanvasCaptureFreezeResult>;
commitPageCapture(input: {
attemptId?: string;
signal?: AbortSignal;
cameraId: string;
key: import("@woohaa3/contracts").WorldCaptureVersionKey;
png: Uint8Array;
width: number;
height: number;
}): Promise<CanvasCaptureFreezeResult>;
cancel(input: {
nodeId: string;
runId: string;
}): Promise<CanvasCancelResult>;
reportModelScript(report: ModelScriptReport): Promise<void>;
listNodeHistory(input: {
canvasId: string;
nodeId: string;
cursor?: string;
limit?: number;
}): Promise<NodeHistoryResult<NodeGenerationHistoryListPage>>;
listCanvasHistory(input: {
canvasId: string;
summary?: boolean;
summaryNodeId?: string;
cursor?: string;
limit?: number;
kind?: string;
}): Promise<NodeHistoryResult<CanvasGenerationHistoryListPage>>;
getNodeHistoryDetail(input: {
canvasId: string;
nodeId: string;
entryId: string;
}): Promise<NodeHistoryResult<NodeGenerationHistoryDetail>>;
applyNodeHistory(input: {
canvasId: string;
nodeId: string;
entryId: string;
expectedCurrentIdentity?: string;
}): Promise<NodeHistoryResult<{
entryId: string;
revision: number;
alreadyCurrent: boolean;
}>>;
clearNodeHistory(input: {
canvasId: string;
nodeId: string;
}): Promise<NodeHistoryResult<{
removed: number;
}>>;
mergeNodeHistory(input: {
canvasId: string;
targetNodeId: string;
sourceNodeId: string;
operationId: string;
expectedSourceCurrentIdentity?: string;
expectedTargetCurrentIdentity?: string;
}): Promise<NodeHistoryResult<MergeNodeHistoryReceipt>>;
nodeHistoryPreviewUrl(input: {
canvasId: string;
nodeId: string;
entryId: string;
variant: "preview" | "poster";
}): string;
verifyImageProjectReferences(input: ImageProjectReferencesRequest): Promise<NodeHistoryResult<ImageProjectReferencesResult>>;
editBegin(input: EditSessionBeginRequest): Promise<NodeHistoryResult<EditSessionBeginResponse>>;
editComplete(input: EditSessionCompleteRequest): Promise<EditCompleteResult>;
editStatus(input: EditSessionStatusRequest): Promise<NodeHistoryResult<EditSessionCompletionReceipt>>;
editAbandon(input: EditSessionStatusRequest): Promise<NodeHistoryResult<{
status: "abandoned";
}>>;
taskActivitySnapshot(input: {
canvasId: string;
cursor?: string;
limit?: number;
}): Promise<NodeHistoryResult<CanvasTaskActivitySnapshot>>;
taskActivityChanges(input: CanvasActivityChangesQuery): Promise<NodeHistoryResult<CanvasTaskActivityEventBatch>>;
subscribeTaskActivity(input: {
canvasId: string;
cursor: number;
onRecord: (record: CanvasTaskActivity, cursor: number) => void;
onError?: (error: unknown) => void;
}): () => void;
listSnippets(query?: PromptSnippetListQuery): Promise<SnippetResult<PromptSnippetListResult>>;
getSnippet(snippetId: string): Promise<SnippetResult<PromptSnippet>>;
createSnippet(input: CreatePromptSnippetInput): Promise<SnippetResult<PromptSnippet>>;
updateSnippet(input: UpdatePromptSnippetInput): Promise<SnippetResult<PromptSnippet>>;
deleteSnippet(snippetId: string): Promise<SnippetResult<null>>;
listSnippetTags(): Promise<SnippetResult<SnippetTagWithCount[]>>;
createSnippetTag(input: CreatePromptSnippetTagInput): Promise<SnippetResult<PromptSnippetTag>>;
renameSnippetTag(input: RenamePromptSnippetTagInput): Promise<SnippetResult<PromptSnippetTag>>;
deleteSnippetTag(tagId: string): Promise<SnippetResult<null>>;
resolveSnippetMaterial(storageKey: string): Promise<SnippetResult<{
storageKey: string;
resolvable: boolean;
}>>;
}

关联类型:WorldToolContextRequest · WorldRemoteOutcome · WorldToolContextOutcome · WorldToolContextRevokeInput · WorldAuthoringFailure · WorldCameraSettingsSaveInput · WorldCameraSettingsSaveOutcome · WorldCameraRestoreInput · WorldCameraRestoreOutcome · WorldCameraHistoryListInput · WorldCameraHistoryListOutcome · WorldAuthoringPrepareOutcome · WorldAuthoringExecuteInput · WorldAuthoringExecuteOutcome · WorldAuthoringHistoryInput · WorldAuthoringHistoryOutcome · SyncSocket · CanvasRunRequest · CanvasRunResult · CanvasCaptureFreezeResult · PageCapturePendingResult · WorldCapturePageProgress · WorldCaptureStatusResult · WorldCaptureDynamicVersionKey · WorldCaptureVersionKey · CanvasCancelResult · ModelScriptReport · NodeHistoryResult · NodeGenerationHistoryListPage · CanvasGenerationHistoryListPage · NodeGenerationHistoryDetail · MergeNodeHistoryReceipt · ImageProjectReferencesRequest · ImageProjectReferencesResult · EditSessionBeginRequest · EditSessionBeginResponse · EditSessionCompleteRequest · EditCompleteResult · EditSessionStatusRequest · EditSessionCompletionReceipt · CanvasTaskActivitySnapshot · CanvasActivityChangesQuery · CanvasTaskActivityEventBatch · CanvasTaskActivity · PromptSnippetListQuery · SnippetResult · PromptSnippetListResult · PromptSnippet · CreatePromptSnippetInput · UpdatePromptSnippetInput · SnippetTagWithCount · CreatePromptSnippetTagInput · PromptSnippetTag · RenamePromptSnippetTagInput

成员说明:

  • openCanvasSession:打开当前 Canvas page 的 canvas-yjs 逻辑通道 。 物理 WebSocket 由 page-owned Canvas Session transport 唯一创建;这里只返回逻辑通道 transport,Yjs provider 不再自行创建 socket。
  • closeCanvasSession:关闭并释放 page-owned Canvas Session 物理连接(切换画布/离开页面/dispose scope)。 幂等;释放后 openCanvasSession 会重新建立一条连接。
  • reconnectCanvasSession:显式重建 page-owned Canvas Session 物理连接(不 dispose 通道订阅者)。 断线只读时由 CanvasSession 的重连入口调用:立即发起一次连接(取消退避等待), 各逻辑通道在 open 后自行重新握手(Yjs state vector / task activity cursor)。 未创建过物理连接时为空操作,调用方应改用完整 attach。
  • run:发起节点任务(最终由 Canvas Service 校验并提交 Task)。
  • freezeWorldCapture:T10: wait for the exact current framing and return a trusted frozen binding. A superseded/cancelled/old-version wait returns an explicit error, never another framing. Missing service/route fails closed.
  • listPendingPageCaptures:页面驱动取景:宿主登记的待渲染镜头清单(无则空数组)。
  • listWorldCaptureStatuses:镜头卡片状态:当前画布已观察镜头的 preview/ready/stale/failed。
  • commitPageVideoCapture:页面录制的动态镜头视频提交(浏览器 WebCodecs 编码后的 MP4)。
  • commitPageCapture:页面驱动取景:提交页面渲染的 PNG;版本已变返回 superseded。
  • reportModelScript:上报浏览器 model script 执行结果。
  • listNodeHistory:列出某节点的历史版本(画布授权;cursor 分页)。
  • listCanvasHistory:列出整张画布全部节点的历史版本 。
  • getNodeHistoryDetail:读取某历史条目的完整内容(按需)。
  • applyNodeHistory:恢复历史版本(原子;调用方负责仅在可写会话调用)。 expectedCurrentIdentity 为可选并发保护。
  • clearNodeHistory:清空某节点的全部历史版本(显式写操作)。 只删历史索引,不动画布内容、当前输出资产与 Media 对象;服务端在进行中生成或 未结算编辑会话时以 conflict 拒绝。
  • mergeNodeHistory:同类型节点合并到目标节点(不可撤销的原子写操作) 。 operationId 由调用方在打开确认框时生成,确认与重试复用同一个;服务端据此幂等, 响应丢失后重试返回首次回执(alreadyMerged: true)。
  • nodeHistoryPreviewUrl:受控预览 URL(模型缩略图 / 媒体预览 / 视频海报);只返回同源受控地址。
  • verifyImageProjectReferences:编辑完成面。 begin 捕获会话基线;complete 提交最终编辑版本;status 查询受保护回执; abandon 放弃尚未提交内容的 prepared 草稿。
  • taskActivitySnapshot:读取当前画布的安全任务活动快照(active + recent)。必须走画布授权面, 不得使用全局 operator/admin taskRemote.createHistory()。
  • taskActivityChanges:有限 JSON 活动增量(断线补偿/冷启动;不持有长连接) 。
  • subscribeTaskActivity:订阅当前画布任务活动的 task-activity 逻辑通道(共享 Canvas Session)。 返回取消订阅函数;连接重建由 page-owned session 统一负责(无独立 retry timer)。
  • resolveSnippetMaterial:目录素材 resolver:确认稳定 storageKey 可解析(不返回任何 URL)。

CanvasRunRequest

export type CanvasRunRequest = {
nodeId: string;
runId: string;
jobId: string;
modelKey: string;
prompt: string;
parameters: Record<string, unknown>;
worldCapture?: import("@woohaa3/contracts").WorldCaptureGenerationBinding;
};

关联类型:WorldCaptureGenerationBinding

成员说明:

  • worldCapture:T10 exact capture binding frozen at click time.

CanvasRunResult

export type CanvasRunResult = {
ok: true;
runId: string;
jobId: string;
} | {
ok: false;
error: string;
code?: string;
};

CanvasRuntimeService

export interface CanvasRuntimeService {
getStatus(): CanvasRuntimeStatus;
subscribe(listener: () => void): () => void;
load(): Promise<BevyRuntime>;
attach(canvas: HTMLCanvasElement): () => void;
controller(): InteractionController | null;
runtime(): BevyRuntime | null;
worldAnimationAssetStatus?(): string | null;
retryWorldAnimationAssets?(): void;
subscribeWorldAnimationAssets?(listener: () => void): () => void;
prepareWorldAnimation?(areaNodeId?: string | null): Promise<void>;
setCaptureAnimationTimes?(times: ReadonlyMap<string, number> | null): void;
captureWorldCameraRaw?(input: {
cameraId: string;
width: number;
height: number;
}): Promise<{
ok: true;
rgba: Uint8Array;
width: number;
height: number;
} | {
ok: false;
code: string;
}>;
captureWorldCamera?(input: {
cameraId: string;
width: number;
height: number;
}): Promise<{
ok: true;
png: Uint8Array;
} | {
ok: false;
code: string;
}>;
resourceResidencyDiagnostics?(): unknown;
cancelTransientGesture(): void;
lastPointerWorld(): {
x: number;
y: number;
} | null;
clientToWorld(client: {
x: number;
y: number;
}): {
x: number;
y: number;
} | null;
worldToClient(world: {
x: number;
y: number;
}): {
x: number;
y: number;
} | null;
historyDotScreenPoint?(nodeId: string, operationId: string): {
x: number;
y: number;
generation: number;
} | null;
queryDropTarget(point: {
x: number;
y: number;
}, excludedIds?: readonly string[]): InteractionQuery<string | null>;
viewportVersion(): number;
subscribeViewport(listener: () => void): () => void;
subscribeFrame?(listener: () => void): () => void;
sceneVersion?(): number;
subscribeScene?(listener: () => void): () => void;
nodeScreenRect(nodeId: string, part?: "scope-title" | "panel" | "action-toolbar"): import("@woohaa3/contracts").ScreenRect | null;
nodePresentationScreenRect?(nodeId: string): import("@woohaa3/contracts").ScreenRect | null;
setGhostNodes(nodes: readonly GhostRenderNode[]): void;
ghostNodes(): readonly GhostRenderNode[];
setPreviewUrls(urls: ReadonlyMap<string, string>): void;
enterDirectFocus(nodeId: string): boolean;
isFocused(): boolean;
modelFocusProjection(): ModelFocusProjection | null;
subscribeModelFocus(listener: () => void): () => void;
exitModelFocus(): void;
applyFocusTarget(target: CanvasFocusTarget | null, transition: {
preserveSession: boolean;
restoreDirectCamera?: boolean;
}): {
ok: true;
} | {
ok: false;
reason: string;
};
isImageFocusTargetValid(nodeId: string): boolean;
setImageFocusTargets(nodeIds: readonly string[]): void;
imageFocusProjection(): import("@woohaa3/contracts").BevyImageFocus | null;
setImageFocus(projection: import("@woohaa3/contracts").BevyImageFocus | null): void;
registerImageViewportTarget(target: FocusViewportTarget): () => void;
setImageFocusTexture(texture: {
nodeId: string;
width: number;
height: number;
pixels: import("@woohaa3/contracts").ImagePixelSource;
} | null): void;
setImageFocusDetails(frame: ImageFocusDetails | null): void;
setImageFocusPending(pending: boolean): void;
subscribeImageFocus(listener: () => void): () => void;
isVideoFocusTargetValid(nodeId: string): boolean;
setVideoFocusTargets(nodeIds: readonly string[]): void;
videoFocusProjection(): import("@woohaa3/contracts").BevyVideoFocus | null;
setVideoFocus(projection: import("@woohaa3/contracts").BevyVideoFocus | null): void;
setVideoFocusTexture(texture: {
nodeId: string;
width: number;
height: number;
pixels: Uint8Array;
} | null): void;
subscribeVideoFocus(listener: () => void): () => void;
setContentRect(input: {
right: number;
}): void;
setFocusContentRect(rect: FocusContentRect | null): void;
focusContentRect(): FocusContentRect | null;
subscribeFocusContentRect(listener: () => void): () => void;
focusTransitionPort(): FocusTransitionPort;
focusTransitionProgress(): import("@woohaa3/contracts").BevyFocusTransition | null;
acquireMediaBitmap(source: FocusMediaSource, pin?: string): Promise<FocusMediaLease | null>;
invalidateMediaSource(key: string): void;
acquireVideoLease(identity: VideoSourceIdentity, quality?: VideoQuality, pin?: string): VideoLease | null;
invalidateVideoSource(identity: VideoSourceIdentity): void;
setModelSceneOverride(input: {
nodeId: string;
override: {
version: string;
ops: readonly unknown[];
} | null;
}): void;
modelSceneOverride(nodeId: string): {
version: string;
ops: readonly unknown[];
} | null;
historyFocusNodeId(): string | null;
modelFocusMode(): "edit" | "history";
setModelEditor(editor: BevyModelEditor | null): void;
modelEditorState(): BevyModelEditor | null;
setAnimationPlayback(playback: import("@woohaa3/contracts").BevyAnimationPlayback | null): void;
worldAnimationState(): WorldAnimationState;
worldAnimationPlayheads(): ReadonlyMap<string, number>;
worldAnimationLoop(nodeId: string): boolean;
subscribeWorldAnimation(listener: () => void): () => void;
playWorldAnimation(): void;
pauseWorldAnimation(): void;
seekWorldAnimation(time: number): void;
setWorldAnimationLoop(loop: boolean): void;
animationPlaybackState(): import("@woohaa3/contracts").BevyAnimationPlayback | null;
notifyAnimationTime?(input: {
nodeId: string | null;
time: number;
playing: boolean;
}): void;
queryGizmoHit(input: GizmoQueryInput): GizmoHitResult | null;
setModelEditorShotGesture(handler: InteractionControllerOptions["shotGesture"] | null): void;
setModelEditorFocusGesture(handler: InteractionControllerOptions["focusGesture"] | null): void;
setShotWheel(handler: InteractionControllerOptions["shotWheel"] | null): void;
setAlignmentSnapPolicy?(policy: AlignmentSnapPolicy | null): void;
alignmentGuides?(): readonly AlignmentGuide[];
alignmentGuidesVersion?(): number;
interactionGeneration(): number;
pauseAnimation?(): void;
setAnimationPauseSink(sink: (() => void) | null): void;
}

关联类型:CanvasRuntimeStatus · BevyRuntime · InteractionController · InteractionQuery · ScreenRect · GhostRenderNode · ModelFocusProjection · CanvasFocusTarget · BevyImageFocus · FocusViewportTarget · ImagePixelSource · ImageFocusDetails · BevyVideoFocus · FocusContentRect · FocusTransitionPort · BevyFocusTransition · FocusMediaSource · FocusMediaLease · VideoSourceIdentity · VideoQuality · VideoLease · BevyModelEditor · BevyAnimationPlayback · WorldAnimationState · GizmoQueryInput · GizmoHitResult · InteractionControllerOptions · AlignmentSnapPolicy · AlignmentGuide

成员说明:

  • load:装载 Bevy 运行时(幂等)。
  • attach:挂载 DOM canvas:创建 interaction controller + texture sync;返回卸载函数。
  • worldAnimationAssetStatus:录制期间临时固定导演区动画采样时间;null 恢复实时播放。
  • captureWorldCameraRaw:裸 RGBA 帧(动态镜头逐帧编码,不经过 PNG)。
  • lastPointerWorld:最近一次有效画布指针的世界坐标。 缺失时返回 null,调用方回退到本地视口中心。
  • clientToWorld:把 client 坐标(clientX/clientY)换算成画布世界坐标。 未挂载控制器时返回 null;不读写服务端 viewport。
  • worldToClient:把世界坐标换算成 client 坐标(含 canvas 外框偏移)。 供导入预览等瞬时 DOM overlay 定位;未挂载控制器时返回 null。
  • queryDropTarget:通用 drop target 查询。 未挂载控制器时返回 unavailable;调用方 MUST NOT 回退 TS 矩形几何。
  • viewportVersion:本地视口版本号;随 pan/zoom 递增(供 overlay 用 useSyncExternalStore 重排)。
  • subscribeFrame:每个画布刷新帧通知;用于需要跟随画布拖动的瞬时 DOM overlay。
  • sceneVersion:Read-only geometry invalidation after scene/position/view submission; no frame heartbeat.
  • nodeScreenRect:单节点当前屏幕矩形(CSS px,含 canvas 外框偏移) 。 使用唯一本地视口与 working 拖动/改尺寸预览;未挂载控制器或节点不存在返回 null。 part: "action-toolbar" 返回 accepted 卡片矩形或世界模型/导演区真实投影,隐藏节点为空; Web 动作栏据此锚定,不持久化横条位置、不建第二相机。
  • nodePresentationScreenRect:Accepted renderer presentation bounds, including collapse, ancestor drag previews and composite scopes. Hidden nodes return null.
  • setGhostNodes:上传中导入的幽灵节点。 设为空数组即清除。实现负责触发一次 scene flush。
  • setPreviewUrls:幽灵节点本地预览 URL(nodeId → object URL);由导入服务写入,供纹理同步使用。
  • enterDirectFocus:以 canonical nodeId 直接进入聚焦(Canvas Navigation focus adapter 调用) 。
  • isFocused:是否仍有活动模型聚焦(Canvas Navigation focus adapter 用)。
  • modelFocusProjection:当前模型聚焦瞬时投影;未聚焦返回 null。 该投影不进入 ServerCanvas / CanvasCommand / Y.Doc。
  • subscribeModelFocus:订阅模型聚焦投影变化(进入/退出/相机移动);供 overlay UI(如「返回」按钮与 历史面板随聚焦关闭)用 useSyncExternalStore 重排。返回退订函数。
  • exitModelFocus:退出模型聚焦并恢复进入前的 2D 视口(无聚焦时 no-op)。
  • applyFocusTarget:应用完整 focus target transition(Canvas Navigation focus adapter) 。
  • isImageFocusTargetValid:有效图片焦点目标。
  • setImageFocusTargets:宿主推入有效图片焦点目标集合。
  • imageFocusProjection:当前图片聚焦投影;未聚焦返回 null。
  • setImageFocus:由图片编辑 feature 推入/清除图片聚焦投影。
  • registerImageViewportTarget:把图片取景作为画布输入的当前目标;返回注销函数。
  • setImageFocusPending:图片聚焦已进入、但编辑器还没接管画面(引擎或首帧未就绪)。 这段时间没有任何编辑面消费输入,画布仍必须可滚动/平移,因此滚轮与 Space 平移按普通 画布处理(否则图片聚焦的“取景目标缺失”分支会把滚轮吃掉,表现为画布卡死)。 首帧提交、退出聚焦或覆盖层卸载时清除。
  • subscribeImageFocus:订阅图片聚焦投影变化。
  • isVideoFocusTargetValid:有效视频焦点目标。
  • setVideoFocusTargets:宿主推入有效视频焦点目标集合。
  • videoFocusProjection:当前视频聚焦投影;未聚焦返回 null。
  • setVideoFocus:由视频聚焦 feature 推入/清除视频聚焦投影。
  • subscribeVideoFocus:订阅视频聚焦投影变化。
  • setContentRect:投影右侧实际占用区域(CSS content rect);0 表示无遮挡。
  • setFocusContentRect:Complete focus content rectangle; owned by the shared workspace 。
  • focusTransitionPort:Canvas Runtime scope 的唯一聚焦过渡时间源 。 feature 通过该端口申请二维取景过渡;MUST NOT 自带独立 rAF/计时器。
  • focusTransitionProgress:当前三维聚焦过渡公共进度快照 。 无活动三维过渡返回 null;由 Canvas Runtime 每帧投影进渲染快照,Rust 据此求值相机姿态, 不再独立计时。图片/视频二维聚焦不经此通道(保持单一驱动)。
  • acquireMediaBitmap:有界媒体资源 store:以稳定来源 identity 取得共享 CPU 位图 lease 。 由 Canvas Runtime scope 唯一持有;feature(图片/视频 editor)通过 lease 复用已解码位图, 不各自持有解码器。MUST NOT 暴露 store 内部缓存结构(仅返回 lease 句柄)。 未挂载/解码失败返回 null;调用方保留上一合法表示。
  • invalidateMediaSource:丢弃某来源缓存(换源/设备恢复);无引用时关闭位图。
  • acquireVideoLease:取得某视频来源的独占 consumer lease 。 canonical direct/history 来源的隐藏解码元素由 Canvas Runtime 唯一持有;卡片与聚焦通过该 lease 接管同一来源,不各自创建第二个解码器。已有 consumer 持有时返回 null(不抢占); 片场内部视频不进入本 registry。
  • invalidateVideoSource:丢弃某视频来源(删除/换源/设备恢复)。
  • setModelSceneOverride:设置/清除本地已校验模型 Scene IR snapshot override(只影响聚焦 ModelRoot,不写规范状态)。
  • modelSceneOverride:读取本地已校验模型 Scene IR override(供聚焦目标解析合并)。
  • historyFocusNodeId:当前模型历史聚焦 owner 的 nodeId;无则 null。
  • modelFocusMode:当前聚焦编辑模式。 历史 owner 活跃返回 "history"(只读),否则 "edit"。
  • setModelEditor:推入/清除当前模型编辑 gizmo 与镜头工具瞬时态 。
  • modelEditorState:当前编辑 gizmo 瞬时态;无编辑返回 null。
  • setAnimationPlayback:推入/清除活动动画节点播放瞬时投影 。 由持有动画播放会话的插件提供;传 null 表示无活动动画节点。实现负责触发一次 scene flush。
  • worldAnimationState:Active director playback, independent of selection and assistant execution.
  • worldAnimationPlayheads:Remembered director playheads, including unselected areas; excludes capture overrides.
  • animationPlaybackState:当前活动动画节点播放投影;无则 null。
  • notifyAnimationTime:片场唯一播放头通知。 由动画播放控制器每帧调用;只把时间转给片场媒体会话,不改变动画投影。
  • queryGizmoHit:模型编辑 gizmo 命中与轴拖动约束(Bevy WASM 相机/bounds 事实源) 。
  • setModelEditorShotGesture:注入/替换镜头 pose 手势处理器 。
  • setModelEditorFocusGesture:注入/替换镜头焦点三轴位移手势处理器 。
  • setShotWheel:注入主画面滚轮/捏合:直接编辑且有选中镜头时改镜头 distance。
  • setAlignmentSnapPolicy:注入/替换拖动吸附策略(内置插件 alignment-guides;传 null 关闭吸附)。 策略只做几何求解,宿主负责在拖动预览里叠加位移与绘制参考线。
  • alignmentGuides:当前拖动的辅助对齐线(世界坐标);未挂载或不在拖动中时为空。
  • alignmentGuidesVersion:参考线版本号;内容变化才递增(供覆盖层决定是否重绘)。
  • interactionGeneration:当前已接受的 interaction generation(供对象 picking 的 generation 守卫)。
  • pauseAnimation:暂停活动动画播放头。 无活动播放或未接线时为 no-op。
  • setAnimationPauseSink:动画播放插件注册暂停钩子(对象编辑前暂停)。

CanvasRuntimeStatus

export type CanvasRuntimeStatus = {
phase: "booting" | "ready" | "error";
error: string | null;
};

CanvasScopeService

当前 Canvas page scope 身份(宿主注入;extension 用它确定目标画布,不假定默认画布)。

export type CanvasScopeService = {
canvasId(): string;
};

成员说明:

  • canvasId:当前 scope 的稳定 canvasId。

CanvasSession

export interface CanvasSession {
getStatus(): CanvasSessionStatus;
subscribe(listener: (status: CanvasSessionStatus) => void): () => void;
retry(): Promise<void>;
reconnect(): Promise<void>;
requestHydrate(): void;
commandLifecycle(): CommandLifecycleRegistry | null;
submitCommands(commands: readonly CanvasCommand[], commandId: string): {
ok: true;
handle: CommandHandle;
} | {
ok: false;
reason: string;
code?: string;
};
isWritable(): boolean;
shutdown(): void;
}

关联类型:CanvasSessionStatus · CanvasCommand · CommandHandle

成员说明:

  • retry:从加载失败中重试(会重新走一次完整加载,期间整页显示启动态)。
  • reconnect:显式重建画布连接。 用于断线只读/同步异常时的「重新连接」入口:不重载页面、不重开画布,也不把会话 打回启动态。已有 provider 时走物理连接重建(state vector 差量收敛);尚未建立 过连接时回落为一次完整 attach。幂等:重建进行中重复调用不叠加连接。
  • requestHydrate:显式请求一次完整 hydrate(例如调试或恢复)。
  • commandLifecycle:Yjs 命令生命周期注册表;宿主用它观察 pending/accepted/committed 状态。
  • submitCommands:提交一个原子服务端命令批次。未同步(syncing/offline)时返回结构化失败, 不进入离线 outbox。
  • isWritable:当前同步相位(供快捷键写入门禁判定)。
  • shutdown:真正销毁会话。

CanvasSessionPhase

export type CanvasSessionPhase = "loading" | "ready" | "error";

CanvasSessionStatus

export type CanvasSessionStatus = {
phase: CanvasSessionPhase;
error: string | null;
hydrated: boolean;
remote: CanvasSyncStatus;
};

关联类型:CanvasSessionPhase · CanvasSyncStatus

成员说明:

  • hydrated:是否已把规范画布交给渲染运行时(Bevy ready + 首个快照)。
  • remote:服务端 Yjs 同步状态(唯一持久化路径)。

CanvasSlotProps

export type CanvasSlotProps = {
revision: number;
canvas?: import("@woohaa3/contracts").ServerCanvas | null;
writable: boolean;
sync?: SyncStatusView;
onReconnect?: () => void;
focus?: {
nodeId: string;
kind: string;
} | null;
modalActive?: boolean;
};

关联类型:ServerCanvas · SyncStatusView

成员说明:

  • sync:派生后的同步状态展示模型。 可选:旧调用方(如 media-import overlay、测试)可继续只传 { revision, writable }。
  • onReconnect:断线/异常时状态气泡里的「重新连接」动作 。 由 CanvasHost 从 CanvasSession 派生;宿主渲染状态气泡时据此提供显式恢复入口。
  • focus:当前 node-focus 的节点与 kind;未聚焦为 null 。
  • modalActive:当前是否有模态 Dialog 处于栈顶(宿主由 Dialog Service 派生的通用门禁)。 通用工作区贡献据此在模态打开时暂停/停止自身瞬态(如试玩会话、capture);模态关闭 只不恢复,绝不自动重启。 宿主不知道任何具体业务,只暴露该通用布尔。

CanvasStoreFacade

受控只读画布 facade(宿主注入;extension MUST NOT import 宿主内部 canvas store)。

getCanvas 返回 canonical(Yjs 派生、只读)画布;getWorkingCanvas 返回含本地未提交预览的 working projection(缺失时回退 canonical)。subscribe 通知任一只读快照变化。

export type CanvasStoreFacade = {
getCanvas(): ServerCanvas | null;
getWorkingCanvas(): ServerCanvas | null;
subscribe(listener: () => void): () => void;
};

关联类型:ServerCanvas

CanvasSwitcherIcon

export const CanvasSwitcherIcon: { ({ size, strokeWidth, absoluteStrokeWidth, ...rest }: UiIconProps): React.JSX.Element; displayName: string; };

关联类型:UiIconProps

CanvasSyncStatus

export type CanvasSyncStatus = {
mode: "remote" | "offline" | "disabled";
phase: CanvasSyncPhase;
confirmedRevision: number | null;
pendingCount: number;
error: string | null;
offlineReason?: CanvasSyncOfflineReason | null;
reconnecting?: boolean;
readOnly?: boolean;
readOnlyReason?: string | null;
};

关联类型:CanvasSyncPhase · CanvasSyncOfflineReason

成员说明:

  • mode:remote:已与后端建立同步;offline:断线只读;disabled:同步不可用。
  • offlineReason:断线来源;仅 mode === "offline" 时有意义,省略按 session-closed 解释。
  • reconnecting:重建连接(显式重连或浏览器恢复联网)是否仍在进行:进行中时按钮置灰。
  • readOnly:内容权限只读(服务端判定,与断线无关)。 与 mode === "offline" 是两件事:链路可能完全正常,只是这个账号在这张画布上没有 写权限(viewer 协作者、只读链接、或者根本不是这张画布的参与者)。界面据此显示常驻 只读提示,并禁用生成/编辑入口——不能等到第一次服务端写入被拒绝才告诉用户。
  • readOnlyReason:只读原因(面向用户的一句话);readOnly 为真时展示。

CatalogState

export type CatalogState = {
status: "loading";
} | {
status: "ready";
catalog: CanvasTaskCatalog;
} | {
status: "error";
error: string;
};

关联类型:CanvasTaskCatalog

ChatIcon

对话类扩展。

export const ChatIcon: { ({ size, strokeWidth, absoluteStrokeWidth, ...rest }: UiIconProps): React.JSX.Element; displayName: string; };

关联类型:UiIconProps

CheckIcon

export const CheckIcon: { ({ size, strokeWidth, absoluteStrokeWidth, ...rest }: UiIconProps): React.JSX.Element; displayName: string; };

关联类型:UiIconProps

ChevronDownIcon

export const ChevronDownIcon: { ({ size, strokeWidth, absoluteStrokeWidth, ...rest }: UiIconProps): React.JSX.Element; displayName: string; };

关联类型:UiIconProps

ChevronRightIcon

export const ChevronRightIcon: { ({ size, strokeWidth, absoluteStrokeWidth, ...rest }: UiIconProps): React.JSX.Element; displayName: string; };

关联类型:UiIconProps

ClapperboardIcon

片场 / 影片。

export const ClapperboardIcon: { ({ size, strokeWidth, absoluteStrokeWidth, ...rest }: UiIconProps): React.JSX.Element; displayName: string; };

关联类型:UiIconProps

ClientMark

export type ClientMark = {
viewBox: string;
render: (suffix: string) => ReactNode;
};

ClippingMaskIcon

图层剪贴到下方基底。

export const ClippingMaskIcon: { ({ size, strokeWidth, absoluteStrokeWidth, ...rest }: UiIconProps): React.JSX.Element; displayName: string; };

关联类型:UiIconProps

ClockIcon

export const ClockIcon: { ({ size, strokeWidth, absoluteStrokeWidth, ...rest }: UiIconProps): React.JSX.Element; displayName: string; };

关联类型:UiIconProps