前端 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:请求受控退出聚焦 。 先经退出协调器异步结算净变化,成功后再 dispatchexit-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/admintaskRemote.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