Context 注入服务
本页由当前 SDK 声明自动生成。
ctx.agentConversationService · ctx.appRouter · ctx.applicationExtensionStatus · ctx.applicationRemote · ctx.canvasCatalog · ctx.canvasCommands · ctx.canvasEdit · ctx.canvasLocate · ctx.canvasMenu · ctx.canvasNavigation · ctx.canvasPreparation · ctx.canvasPreparationView · ctx.canvasRecovery · ctx.canvasRemote · ctx.canvasRuntime · ctx.canvasScope · ctx.canvasSelection · ctx.canvasSession · ctx.canvasState · ctx.currentUser · ctx.dialogs · ctx.extensionFaults · ctx.extensionManager · ctx.focusExit · ctx.generationModelsStatus · ctx.hoverState · ctx.importService · ctx.inputScopes · ctx.log · ctx.mediaContent · ctx.mediaRemote · ctx.modelInteractions · ctx.nodeImplementations · ctx.pageLeave · ctx.parameterPreview · ctx.persistentSurfaces · ctx.runState · ctx.selection · ctx.settingsOpen · ctx.settingsRemote · ctx.slots · ctx.snippetCatalog · ctx.taskCatalog · ctx.taskNotifications · ctx.taskRemote · ctx.theme
ctx.agentConversationService
宿主 Agent 会话 service(Canvas page scope 提供) 。生成面板提交首轮与详情读模型共用; 业务生成扩展只消费它,不自行持久化会话。
export type AgentConversationService = AgentConversationView & { serviceConnectionDirectory?: () => Promise<AgentConversationResult<ServiceConnectionDirectory>>; manageServiceConnection?: (input: ServiceConnectionManagement) => Promise<AgentConversationResult<ServiceConnectionView>>; listServiceConnections?: () => Promise<AgentConversationResult<ServiceConnectionView[]>>; getDataScopeId?: () => string | null; invalidateDirectory: () => void; catalog: (adapterId?: string) => Promise<AgentConversationResult<AgentCatalogResponse>>; mcpStatus: () => Promise<AgentConversationResult<AgentMcpStatusResponse>>; listConversations: (canvasId: string) => Promise<AgentConversationResult<ConversationSummary[]>>; findConversationForTarget: (input: { contextKey?: string; canvasId: string; nodeId: string; connectionId?: string; }) => Promise<AgentConversationResult<{ conversation: ConversationSummary | null; }>>; clearContext: (input: { canvasId: string; nodeId: string; }) => Promise<AgentConversationResult<{ cleared: number; }>>; listConnections: (adapterId?: string) => Promise<AgentConversationResult<AgentConnectionView[]>>; switchConnection: (input: { canvasId: string; nodeId: string; connectionId: string; }) => Promise<AgentConversationResult<{ cleared: number; }>>; readConversation: (conversationId: string, cursor?: number) => Promise<AgentConversationResult<ConversationSnapshot>>; submitTurn: (input: AgentConversationSubmitInput & { requestId: string; }) => Promise<AgentConversationResult<AgentConversationSubmitResult>>; submitImageDirectorScene?: (input: AgentConversationSubmitInput & { requestId: string; }) => Promise<AgentConversationResult<AgentConversationSubmitResult>>; queryTurn: (requestId: string) => Promise<AgentConversationResult<{ conversation: ConversationSummary; turn: ConversationTurn; snapshot: ConversationSnapshot; }>>; locateTurnByRun: (runId: string) => Promise<AgentConversationResult<{ conversation: ConversationSummary; turn: ConversationTurn; snapshot: ConversationSnapshot; }>>; retryTextSave?: (requestId: string) => Promise<AgentConversationResult<{ turn: ConversationTurn; }>>; cancelTurn: (requestId: string) => Promise<AgentConversationResult<{ ok: true; }>>; linkRun: (requestId: string, input: { runId?: string; taskId?: string; }) => Promise<AgentConversationResult<{ turn: ConversationTurn; }>>; skillStep: (input: { canvasId: string; nodeId: string; }) => Promise<AgentConversationResult<{ step: SkillMediaStepView | null; }>>; skillSteps: (input: { canvasId: string; limit?: number; }) => Promise<AgentConversationResult<{ steps: SkillMediaStepView[]; }>>; skillStepDetail: (input: { canvasId: string; skillRunId: string; stepId: string; after?: number; }) => Promise<AgentConversationResult<{ step: SkillMediaStepView; events: Array<SkillStepUpdatedEvent & { sequence: number; }>; cursor: number; resetRequired: boolean; }>>; cancelSkillStep: (input: { canvasId: string; skillRunId: string; stepId: string; }) => Promise<AgentConversationResult<{ step: SkillMediaStepView; state: "cancel-requested" | "already-terminal"; }>>; regenerateSkillStep: (input: { canvasId: string; skillRunId: string; stepId: string; requestId: string; prompt?: string; modelKey?: string; parameters?: Record<string, unknown>; }) => Promise<AgentConversationResult<{ step: SkillMediaStepView; runId: string; }>>;};关联类型:AgentConversationService · AgentConversationView · AgentConversationResult · ServiceConnectionDirectory · ServiceConnectionManagement · ServiceConnectionView · AgentCatalogResponse · AgentMcpStatusResponse · ConversationSummary · AgentConnectionView · ConversationSnapshot · AgentConversationSubmitInput · AgentConversationSubmitResult · ConversationTurn · SkillMediaStepView · SkillStepUpdatedEvent
成员说明:
invalidateDirectory:配置保存后清除连接/模型目录请求缓存;不改变会话事实或草稿。catalog:读取 adapter 授权/能力/账户目录(真实状态,不自动换模型)。mcpStatus:内置 MCP 真实发现 + 外部连接指引(宿主投影) 。builtin.ready只来自后端 executed initialize/源码声明;external只是当前 origin 的 Streamable HTTP URL,复制地址不等于外部客户端已连接。listConversations:当前画布的会话列表(有界)。findConversationForTarget:按生成目标节点查找该节点当前会话(一个节点复用一条;design D8)。只读。 无则conversation: null(调用方据此新建);不改变导航或读模型。connectionId提供时只返回该来源连接下的会话。clearContext:清空节点上下文:解除该节点与当前会话的关联(归档旧会话,不删除历史;design D8)。 随后该节点提交将新建会话;同时清理本地读模型中该会话的 active/detail。listConnections:该 owner 可见的来源连接。只读。 宿主据此渲染来源/连接选择;按数据空间缓存成功结果及在途请求,失败保留原选择。switchConnection:显式切换来源连接:解除目标关联、归档旧会话(保留历史),下一次提交建立新来源会话。 活动回合由后端拒绝;成功后清理本地读模型并自增contextRevision,让宿主重新解析节点会话。readConversation:读取会话权威快照(消息/回合/事件),用于详情面板。submitTurn:从生成面板提交首轮:确保会话存在、接受回合并异步执行。 相同requestId(由调用方提供稳定身份)命中既有回合时返回reused: true,不再推理。queryTurn:按确切 requestId 查询回合与快照(断流/unknown 恢复;不重新 dispatch)。locateTurnByRun:按领域运行关联定位确切回合(活动/历史 Agent 记录 → 确切 request/run) 。 只匹配宿主已显式关联的 runId,绝不按 nodeId 跳到最近会话;只读,不 accept/dispatch。 无关联返回not-found,调用方据此保留原任务详情(不伪造对话)。retryTextSave:取消在途回合(不撤销已提交领域动作)。linkRun:由宿主领域链在 run/task 接受后显式关联(不从节点 active run 反推)。skillStep:按节点读取 Skill 步骤快照(无步骤时 step=null;轮询/刷新复用同一读入口)。skillSteps:画布内最近 Skill 步骤(活动面板投影;有界)。skillStepDetail:按步骤身份读取快照 + 事件重放(面板打开/断线恢复)。cancelSkillStep:用户停止:只请求取消当前尝试,不伪造已取消。regenerateSkillStep:用户改提示词并重新生成:创建递增 attempt,旧尝试保留可核对历史。
ctx.appRouter
应用级顶层页面 Router(App scope 提供)。
export interface AppRouterService { getLocation(): AppPageLocation; subscribe(listener: () => void): () => void; resolve(pathname: string, search: string): AppPageLocation; navigate(to: AppPageLocation): void; replace(to: AppPageLocation): void; navigatePath(pathname: string): void; currentScopeId(): string; subscribeScope(listener: (status: AppPageScopeStatus) => void): () => void;}关联类型:AppRouterService · AppPageLocation · AppPageScopeStatus
成员说明:
getLocation:当前活动 page location。resolve:解析 pathname 得到页面 identity(纯函数式,无副作用)。navigate:请求导航到目标 location(pushState + 切换 scope)。replace:用 replaceState 规范化当前 entry。不改变 back stack 长度。navigatePath:直接提交 pathname(Browser History 集成)。currentScopeId:当前活动 page scope 的稳定 identity。subscribeScope:订阅 scope 生命周期变化(诊断/测试)。
ctx.applicationExtensionStatus
站点应用插件状态读模型(Canvas page scope 提供) 。
export type ApplicationExtensionStatusService = { getSnapshot: () => ApplicationExtensionStatusSnapshot; subscribe: (listener: () => void) => () => void; refresh: () => Promise<void>; refreshChanges: () => Promise<void>; writeConfig: (input: Omit<ApplicationExtensionConfigWriteInput, "expectedRevision"> & { expectedRevision?: number; }) => Promise<ApplicationExtensionWriteResult>; start: () => void; stop: () => void; dispose: () => void;};关联类型:ApplicationExtensionStatusService · ApplicationExtensionStatusSnapshot · ApplicationExtensionConfigWriteInput · ApplicationExtensionWriteResult
成员说明:
refresh:拉取权威 snapshot(重连/丢失 cursor)。refreshChanges:增量刷新(旧响应不覆盖新状态)。writeConfig:管理员配置写入;成功后重取权威状态。start:启动/停止轮询。
ctx.applicationRemote
Application Remote:站点插件状态/管理 + Application 健康。
export type ApplicationRemote = { fetchSnapshot: () => Promise<ApplicationExtensionSnapshotResult>; fetchChanges: (after: number) => Promise<ApplicationExtensionChangesResult>; writeConfig: (input: ApplicationExtensionConfigWriteInput) => Promise<ApplicationExtensionWriteResult>; health: () => Promise<ApplicationHealthResult>; generationModels: { fetchSnapshot: () => ReturnType<GenerationModelsRemote["fetchSnapshot"]>; writeConfig: (input: import("@woohaa3/contracts").GenerationModelsWriteRequest) => ReturnType<GenerationModelsRemote["writeConfig"]>; }; transport: ApplicationRemoteTransport;};关联类型:ApplicationRemote · ApplicationExtensionSnapshotResult · ApplicationExtensionChangesResult · ApplicationExtensionConfigWriteInput · ApplicationExtensionWriteResult · ApplicationHealthResult · GenerationModelsRemote · GenerationModelsWriteRequest · ApplicationRemoteTransport
成员说明:
fetchSnapshot:权威状态 snapshot(不含秘密)。fetchChanges:有界增量;resyncRequired 时调用方必须重取 snapshot。writeConfig:管理员配置写入(浏览器不携带服务令牌;由同源 ingress 传递可信管理员上下文)。health:读取 Application liveness/readiness(只含状态与安全原因)。generationModels:生成模型策略。transport:通用插件 JSON/流式传输。 插件(如 ChatGPT)拥有自己的业务协议 adapter,但 MUST 复用本传输发起同源请求,携带同源会话 与取消信号,不自行创建针对服务的 fetch/EventSource。传输只做 HTTP/SSE 编解码与稳定错误映射, 不解释业务协议,也不持有服务间令牌。
ctx.canvasCatalog
多画布目录读模型。 跨 Canvas page transition 存活;不创建任何画布运行资源。
export interface CanvasCatalogService { getState(): CanvasCatalogState; subscribe(listener: () => void): () => void; load(force?: boolean): Promise<CanvasCatalogListResult>; loadMore(): Promise<void>; create(input?: { title?: string; }): Promise<CanvasCatalogCreateResult>; delete(canvasId: string, expectedRevision?: number): Promise<CanvasCatalogDeleteResult>; get(canvasId: string): Promise<CanvasCatalogSummaryResult>; invalidate(): void; dispose(): void;}关联类型:CanvasCatalogService · CanvasCatalogState · CanvasCatalogListResult · CanvasCatalogCreateResult · CanvasCatalogDeleteResult · CanvasCatalogSummaryResult
成员说明:
load:加载第一页(默认缓存命中直接返回;force 强制刷新)。loadMore:追加下一页。create:创建画布,成功后失效并刷新目录。delete:删除画布,成功后失效并刷新目录。 版本号缺省取当前目录条目的revision;条目不在当前页时必须显式给出。get:按 ID 读取摘要(用于校验显式 canvasId 是否存在/展示当前标题)。invalidate:失效缓存,使下一次load()重新请求。
ctx.canvasCommands
通用扩展画布命令提交能力。
扩展经此提交通用语义画布命令;只读会话拒绝。编辑扩展“添加到画布”用它提交 工程资产 + 输出资产 + 带工程的图片节点这一原子批次。
export type CanvasCommandsService = { isWritable(): boolean; submit(commands: readonly import("@woohaa3/contracts").CanvasCommand[], commandId: string): CanvasCommandsResult;};关联类型:CanvasCommandsService · CanvasCommand · CanvasCommandsResult
成员说明:
isWritable:会话是否可写(离线/同步未就绪/历史只读时为 false)。
ctx.canvasEdit
页面级画布编辑历史(撤销/重做、参数条目、冲突跳过) 。
export interface CanvasEditService { record(commands: readonly CanvasCommand[], label: string): Promise<CanvasEditRecordResult>; recordExternal(input: { id: string; label: string; revision?: number; undo: () => Promise<{ ok: true; } | { ok: false; reason: string; }>; redo: () => Promise<{ ok: true; } | { ok: false; reason: string; }>; }): CanvasEditRecordResult; recordParameter(input: { label: string; nodeId: string; modelKey: string; before: Record<string, unknown>; after: Record<string, unknown>; apply: (values: Record<string, unknown>) => void; }): void; undo(): Promise<{ ok: true; } | { ok: false; reason: string; }>; redo(): Promise<{ ok: true; } | { ok: false; reason: string; }>; skipConflict(entryId: string): boolean; getSnapshot(): CanvasEditSnapshot; subscribe(listener: (snapshot: CanvasEditSnapshot) => void): () => void; clear(): void;}关联类型:CanvasEditService · CanvasCommand · CanvasEditRecordResult · CanvasEditSnapshot
成员说明:
recordExternal:把已在权威端确认的动作加入同一条撤销时间线。undo/redo必须继续调用该动作所属的权威端口,并在回执/版本不确定时返回ok:false;journal 只在成功时移动指针,绝不因“请求已发出”推进历史。clear:切画布 / 刷新 / dispose。
ctx.canvasLocate
统一定位服务。
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;};关联类型:CanvasLocateService · LocateNodesResult
成员说明:
locateNodes:定位一批节点:select=false时不改选区(例如定位当前多选)。 默认保持缩放居中;fit 显式按实际呈现边界容纳整批节点。 返回ok:false表示目标已失效或宿主未就绪,不改变视口。locateSelection:定位当前选区中心(不改选区)。
ctx.canvasMenu
export interface CanvasMenuService { close(): void;}关联类型:CanvasMenuService
ctx.canvasNavigation
Canvas presentation navigation。 只在 Canvas page scope 提供。
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;}关联类型:CanvasNavigationService · 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:诊断。
ctx.canvasPreparation
首次打开准备读模型。 跨 Canvas page transition 存活;不创建任何画布运行资源。
export interface CanvasPreparationService { getState(): CanvasPreparationState; subscribe(listener: () => void): () => void; listSources(force?: boolean): Promise<void>; listAccessible(input: { sourceId: string; cursor: string | null; limit?: number; }): Promise<{ items: SourceCanvasSummary[]; nextCursor: string | null; }>; prepare(input: { canvasId: string; sourceId?: string; }): Promise<void>; observe(input: { canvasId: string; signal?: AbortSignal; }): Promise<PreparationState>; dispose(): void;}关联类型:CanvasPreparationService · CanvasPreparationState · SourceCanvasSummary · PreparationState
成员说明:
listAccessible:某来源下主体可访问的来源作品分页(受认证;供切换器来源分区)。prepare:显式准备:POST prepare 并进入轮询(幂等)。observe:观察一个 canvasId 的准备态:先 GET status,未 ready 时按 pollAfterMs 轮询。 传入 generation/AbortSignal 以隔离迟到响应;dispose/切换后不再发布。
ctx.canvasPreparationView
旧 ID 迁移准备态视图(preparation page scope 提供) 。
canvasPreparationView: { canvasId: string; jobId: string | null;};ctx.canvasRecovery
显式不支持画布的恢复页(recovery page scope 提供)。
export type CanvasRecoveryService = { canvasId: string | null; code: string; error: string;};成员说明:
canvasId:用户显式请求但不存在/解析失败的 canvasId;目录解析失败时为 null。
ctx.canvasRemote
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; }>>;}关联类型:CanvasRemoteService · 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)。
ctx.canvasRuntime
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;}关联类型:CanvasRuntimeService · 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:动画播放插件注册暂停钩子(对象编辑前暂停)。
ctx.canvasScope
当前 Canvas scope 身份。 只在 Canvas page scope 提供;extension 用它确定目标画布,不假定默认画布。
export type CanvasScopeService = { canvasId(): string;};关联类型:CanvasScopeService
成员说明:
canvasId:当前 scope 的稳定 canvasId。
ctx.canvasSelection
最近画布选择(App scope;用于缺省 canvasId 解析)。
export interface CanvasSelectionService { getRecentCanvasId(): string | null; setRecentCanvasId(canvasId: string | null): void;}ctx.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;}关联类型:CanvasSession · CanvasSessionStatus · CanvasCommand · CommandHandle
成员说明:
retry:从加载失败中重试(会重新走一次完整加载,期间整页显示启动态)。reconnect:显式重建画布连接。 用于断线只读/同步异常时的「重新连接」入口:不重载页面、不重开画布,也不把会话 打回启动态。已有 provider 时走物理连接重建(state vector 差量收敛);尚未建立 过连接时回落为一次完整 attach。幂等:重建进行中重复调用不叠加连接。requestHydrate:显式请求一次完整 hydrate(例如调试或恢复)。commandLifecycle:Yjs 命令生命周期注册表;宿主用它观察 pending/accepted/committed 状态。submitCommands:提交一个原子服务端命令批次。未同步(syncing/offline)时返回结构化失败, 不进入离线 outbox。isWritable:当前同步相位(供快捷键写入门禁判定)。shutdown:真正销毁会话。
ctx.canvasState
export type CanvasStoreFacade = { getCanvas(): ServerCanvas | null; getWorkingCanvas(): ServerCanvas | null; subscribe(listener: () => void): () => void;};关联类型:CanvasStoreFacade · ServerCanvas
ctx.currentUser
App scope 的身份与权限快照,独立管理页面共用。
currentUser: CurrentUserService;关联类型:CurrentUserService
ctx.dialogs
export interface DialogsService extends DialogHostApi { getSnapshot(): DialogHostSnapshot; subscribe(listener: (snapshot: DialogHostSnapshot) => void): () => void; top(): DialogInstance | null; find(instanceId: string): DialogInstance | null; requestCloseTop(): DialogCloseResult; requestClose(instanceId?: string): DialogCloseResult; registerCloseGuard(dialogId: string, guard: DialogCloseGuard): () => void; getDiagnostic(): string | null; resolveRenderer(dialogId: string): DialogRenderer | null; resolveAlertAction(key: string | undefined): (() => Promise<{ ok: true; } | { ok: false; error: string; }>) | null; isModalActive(): boolean; registerDialog(dialogId: string, registration: DialogRegistration): () => void; registerAlertAction(key: string, action: () => Promise<{ ok: true; } | { ok: false; error: string; }>): () => void; registeredDialogIds(): string[]; registerOpenParticipant(participant: DialogOpenParticipant): () => void;}关联类型:DialogsService · DialogHostApi · DialogHostSnapshot · DialogInstance · DialogCloseResult · DialogCloseGuard · DialogRenderer · DialogRegistration · DialogOpenParticipant
成员说明:
requestClose:请求关闭(缺省顶部):统一走 dismissible / busy / close guard 判定, 不绕过 guard 直接关闭。registerCloseGuard:注册某类 Dialog 的关闭请求 guard(instance-scoped 调用);返回注销函数。registerDialog:注册 definition + 可选 renderer;重复 ID 抛错并要求调用方回滚。registerAlertAction:注册一个异步 alert action;返回注销函数。registerOpenParticipant:注册 Dialog open pre-commit participant。 在纯校验通过、stack 提交前同步运行;返回 false 时拒绝打开。返回注销函数。replace:替换指定实例(缺省为顶部)的 payload;instanceId 不匹配时不动作。close:关闭指定实例及其显式子孙;缺省关闭顶部。setBusy:更新 busy;已关闭实例的迟到调用被忽略(返回 false)。
ctx.extensionFaults
扩展渲染故障与会话内熔断。
export interface ExtensionFaultService { report(failure: ExtensionRenderFailure): void; attach(extensionId: string, handle: ExtensionFaultHandle): () => void; isTripped(extensionId: string): boolean; stateOf(extensionId: string): ExtensionFaultState | null; reload(extensionId: string): boolean; diagnostics(): readonly ExtensionRenderFailedDiagnostic[]; subscribe(listener: () => void): () => void; version(): number;}关联类型:ExtensionFaultService · ExtensionRenderFailure · ExtensionFaultHandle · ExtensionFaultState · ExtensionRenderFailedDiagnostic
成员说明:
attach:装配方登记;返回注销函数(释放装配时调用)。重复登记同一扩展以最新为准。reload:解除熔断并请求重新装配;返回是否已发起。
ctx.extensionManager
插件管理 capability。 只暴露投影后的快照,不暴露底层 browser-local 原始配置。
export type ExtensionManagerFacade = { getSnapshot(): ExtensionManagerView; subscribe(listener: () => void): () => void; setEnabled(id: string, enabled: boolean): void; refresh(): void; setSiteEnabled(id: string, enabled: boolean): void; siteRows(): ExtensionSiteRow[]; canManageSite(): boolean; modelRows(): ExtensionModelRow[]; setModelEnabled(modelKey: string, enabled: boolean): void; setModelsEnabled(modelKeys: readonly string[], enabled: boolean): void; refreshModels(): Promise<void>; setModelDefault(modelKey: string, modelType: string): void;};关联类型:ExtensionManagerFacade · ExtensionManagerView · ExtensionSiteRow · ExtensionModelRow
成员说明:
setEnabled:写入一个可配置 optional 插件的浏览器本地目标状态(不改变当前 Fiber;下次启动生效)。refresh:触发刷新应用(生产实现为页面 reload)。setSiteEnabled:写入一个站点应用插件的目标配置(服务端权威;运行中生效,仅管理员可用)。siteRows:站点插件的实际状态(不含秘密;由服务端状态同步)。canManageSite:站点操作是否可用(管理员授权)。modelRows:生成模型行(服务端权威策略)。setModelEnabled:启用/停用一个生成模型(仅管理员)。setModelsEnabled:一次启用或关闭一批模型(仅管理员)。refreshModels:重新拉取生成模型策略(发现新模型后立刻看到现状)。setModelDefault:设置某类型的默认生成模型(仅管理员)。
ctx.focusExit
图片/模型聚焦编辑的异步退出协调器 。
export class FocusExitCoordinator { constructor(); register: (participant: FocusExitParticipant) => () => void; registerSwitchGate: (id: string, gate: FocusSwitchGate) => () => void; switchGate: () => string | null; hasUnsavedChanges: () => boolean; prepare: () => Promise<FocusExitResult>; abandonAll: () => void;}成员说明:
registerSwitchGate:注册活动操作门禁;返回注销函数。switchGate:首个非空门禁原因;全部通过返回 null(同步,供 Navigation transition 使用)。hasUnsavedChanges:是否有任一参与者存在未结算净变化(同步;Dialog pre-commit 门禁用)。prepare:结算全部脏参与者的异步准备。重复调用合并为同一次结算。 任一参与者失败即保留现场并返回失败(不继续退出、不清理其草稿)。abandonAll:用户明确放弃:调用每个脏参与者的 abandon(不回滚已提交内容)。
ctx.generationModelsStatus
生成模型状态读模型(Canvas page scope 提供) 。
export type GenerationModelsStatusService = { getSnapshot: () => GenerationModelsStatusSnapshot; subscribe: (listener: () => void) => () => void; refresh: () => Promise<void>; setEnabled: (modelKey: string, enabled: boolean) => Promise<{ ok: boolean; error?: string; }>; setEnabledMany: (modelKeys: readonly string[], enabled: boolean) => Promise<{ ok: boolean; error?: string; }>; setDefault: (modelKey: string, modelType: string) => Promise<{ ok: boolean; error?: string; }>; start: () => void; stop: () => void; dispose: () => void;};关联类型:GenerationModelsStatusService · GenerationModelsStatusSnapshot
成员说明:
setEnabledMany:一次启用或关闭一批模型。关闭时清掉这批里的默认标记。已删除的模型不动。
ctx.hoverState
受控只读画布 facade。 只读 canonical/working 快照与订阅;MUST NOT import 宿主内部 canvas store。
export type HoverStateService = { getNodeId(): string | null; subscribe(listener: () => void): () => void;};关联类型:HoverStateService
ctx.importService
export interface ImportService { requestFile(anchor: ImportAnchor): void; requestFiles(anchor: ImportAnchor): void; importBatch(input: ImportBatchInput): Promise<ImportBatchResult>; retryItem(itemId: string): Promise<{ ok: boolean; error?: string; }>; replaceSelectedImage(input: { file: File; nodeId: string; }): Promise<{ ok: boolean; error?: string; }>; getState(): ImportState; subscribe(listener: () => void): () => void;}关联类型:ImportService · ImportAnchor · ImportBatchInput · ImportBatchResult · ImportState
成员说明:
requestFile:打开单选文件选择器;选中后走批量 coordinator。requestFiles:打开可多选文件选择器;选中后走 importBatch。importBatch:批量 coordinator:逐文件独立原子提交,允许部分成功。retryItem:用当前页面存活期的 File 重试单个失败项。replaceSelectedImage:单图替换:上传新图片后以一个批次 upsert 资产并 patch 目标节点。
ctx.inputScopes
export interface InputScopesService { addGate(gate: () => boolean): () => void; addScope(scope: InputScope, gate: () => boolean): () => void; isActive(scope: InputScope): boolean; blocksCanvas(): boolean; blocksFocusInput(): boolean;}关联类型:InputScopesService · InputScope
成员说明:
addGate:注册一个门禁谓词(例如 modal 打开时返回 true)。addScope:注册到指定 scope 的门禁谓词;返回注销函数。blocksCanvas:modal/menu/editor 任一激活时,画布 pointer/keyboard/paste/drop 门禁为 true。blocksFocusInput:聚焦相机输入门禁。 focus 期间只有真正的 modal Dialog 才阻断主观察相机缩放/观察;非模态的 editor/history panel 与菜单 MUST NOT 抢走 focus canvas 上的滚轮/捏合/键盘飞行。
ctx.log
结构化日志出口。
前端实现只写 console:不落盘、不上报、不缓冲。宿主侧同名服务由
源码声明 提供;两者共用 contracts 的信封与脱敏表。
export type FrontendLogService = { scope(module: string): (event: Record<string, unknown>) => void; level(): LogLevel;};关联类型:FrontendLogService · LogLevel
成员说明:
scope:带module字段的结构化日志出口。level:当前生效级别。
ctx.mediaContent
export type MediaContentService = { register(provider: MediaContentProvider): () => void; describe(canvas: ServerCanvas, ref: MediaContentRef, kind: MediaContentKind): MediaContentSource; subscribe(listener: () => void): () => void; state(nodeId: string): MediaContentState | undefined; resolve(nodeId: string, operation: "resolvePreview" | "materialize" | "snapshot", requestId: string): Promise<StoredAsset | null>; freeze(canvas: ServerCanvas, nodeIds: readonly string[], requestId: string): Promise<ServerCanvas>; retry(nodeId: string): void;};关联类型:MediaContentService · MediaContentProvider · ServerCanvas · MediaContentRef · MediaContentKind · MediaContentSource · MediaContentState · StoredAsset
成员说明:
freeze:Snapshot a complete copy closure before creating any copied nodes.
ctx.mediaRemote
export interface MediaRemoteService { upload(input: { file: File; canvasId?: string; onProgress?: (percent: number) => void; signal?: AbortSignal; }): Promise<UploadMediaResult>; urlFor(storageKey: string, canvasId?: string): string; isAllowedUrl(url: string): boolean; resolveCanonicalUrl(asset: unknown, canvasId?: string): string | null;}关联类型:MediaRemoteService · UploadMediaResult
成员说明:
upload:上传一个文件;onProgress上报 0..100(可用时)。canvasId只在已知画布上下文传入,作为上传目标的?canvas=提示 (POST /api/media?canvas=<id>),让宿主把字节写入该画布对应的存储后端。urlFor:由稳定 storageKey 构造同源读取地址;canvasId可选(只在画布上下文附加提示)。isAllowedUrl:校验一个 canonical 资产 URL 是否为受控稳定同源引用。resolveCanonicalUrl:从 canonical asset 解析受控 URL;不合法返回 null。canvasId同上,仅作渲染提示。
ctx.modelInteractions
Canvas page scope 的模型交互注册表。
export interface ModelInteractionRegistry { register(definition: ModelInteractionDefinition): () => void; resolve(descriptor: ModelInteractionDescriptor): ModelInteractionDefinition | null; list(): readonly ModelInteractionSummary[]; subscribe(listener: () => void): () => void;}关联类型:ModelInteractionRegistry · ModelInteractionDefinition · ModelInteractionDescriptor · ModelInteractionSummary
成员说明:
register:注册一个 definition;返回幂等 disposer,重复{id,version}稳定拒绝。resolve:精确{id,version}解析;不隐式替代 generic。list:稳定顺序的诊断摘要(不含 component/closure)。subscribe:订阅注册/注销变化:Host 据此重新解析当前 interaction。 返回取消订阅函数;dispose 时清理全部 listener。
ctx.nodeImplementations
export class NodeImplementationRegistry { constructor(builtins?: ReadonlyMap<string, NodeCapabilities>); getRevision: () => number; resolve: (context: NodeCapabilityContext) => ResolvedNodeCapabilities; register: ({ type, capabilities }: NodeImplementation) => () => void; subscribe: (listener: () => void) => (() => void); clear: () => void;}关联类型:NodeImplementationRegistry · NodeCapabilities · NodeCapabilityContext · ResolvedNodeCapabilities · NodeImplementation
ctx.pageLeave
页面离开守卫(编辑扩展工作区,design D6)。
多文档工作区注册自己的未结算文档与串行结算;切换画布 / 离开页面先问它。
export class PageLeaveGuard { constructor(); register: (participant: LeaveGuardParticipant) => () => void; hasUnsaved: () => boolean; settle: () => Promise<LeaveResult>;}成员说明:
hasUnsaved:是否有任一参与者存在未结算文档(同步;beforeunload与导航前置检查用)。settle:串行结算全部参与者;重复调用合并(避免切画布与关闭窗口并发时保存两次)。
ctx.parameterPreview
export interface ParameterPreviewService { set(nodeId: string, patch: ParameterPatch, deadline?: number): void; get(nodeId: string): ParameterPatch | undefined; resolve(nodeId: string): void; clearAll(): void; entries(): ReadonlyMap<string, ParameterPreviewEntry>; subscribe(listener: () => void): () => void;}关联类型:ParameterPreviewService · ParameterPatch · ParameterPreviewEntry
ctx.persistentSurfaces
persistentSurfaces: PersistentSurfaces;关联类型:PersistentSurfaces
ctx.runState
统一生成运行状态(Canvas page scope 提供) 。
export type RunStateService = { getNodeSummary(canvasId: string, nodeId: string): import("@woohaa3/contracts").CanvasNodeRunSummary | null; subscribe(listener: () => void): () => void; snapshot(): { canvasId: string; summaries: ReadonlyMap<string, import("@woohaa3/contracts").CanvasNodeRunSummary>; records: readonly import("@woohaa3/contracts").CanvasOperationRecord[]; }; isBusy(canvasId: string, nodeId: string): boolean; currentOperationByNode(): ReadonlyMap<string, string>; subscribeCurrentOperations(listener: () => void): () => void; beginLocalOperation(input: { canvasId: string; nodeId: string; kind: import("@woohaa3/contracts").CanvasOperationKind; progress?: number; }): { operationId: string; finish: (outcome?: { error?: string; progress?: number; }) => void; };};关联类型:RunStateService · CanvasNodeRunSummary · CanvasOperationRecord · CanvasOperationKind
成员说明:
getNodeSummary:按(canvasId,nodeId)查询当前节点运行摘要;未知节点返回不存在。subscribe:订阅摘要变化(React/投影用)。snapshot:当前快照(供 scene 投影批量读取)。isBusy:该(canvasId,nodeId)是否已有运行中操作(门禁用)。currentOperationByNode:“当前生效版本”对应的操作身份映射(nodeId -> operationId) 。 有界派生:不读取完整历史,只用 working canvas 的nodeData.activeRunId与该节点已成功 结算的操作 identity 匹配。缺失/无法判定时不装饰,绝不本地猜测。beginLocalOperation:注册一个浏览器本地生成操作(截图/帧捕获/视频导出/本地编码)。 返回一个finish回调,由本地编码结束时按成功/失败结算。本地操作不写 canonical, 也不经 Task Service(design D8)。
ctx.selection
export interface SelectionService { getSnapshot(): SelectionSnapshot; subscribe(listener: () => void): () => void; setFromRuntime(raw: { nodeIds: readonly string[]; primaryNodeId: string | null; editingFocus: boolean; }, validNodeIds: ReadonlySet<string>): void; setKeyboardActive(active: boolean): void; reset(): void;}关联类型:SelectionService · SelectionSnapshot
ctx.settingsOpen
画布内设置的打开能力。
左下角入口、旧 /settings 兼容意图与其它指路操作都经它打开同一 singleton 弹窗;
不涉及 App Router/页面导航。渲染失败/空壳的恢复页 scope 也提供同一能力。
export type SettingsOpenService = { open: (input?: { canvasId?: string | null; section?: "backend" | "plugins" | "appearance" | "notifications" | "runtimes"; pluginId?: string; }) => Promise<{ ok: true; } | { ok: false; code: string; reason: string; }>;};关联类型:SettingsOpenService
成员说明:
open:打开设置弹窗。section落到左侧分区;pluginId再往里一步直接打开该插件详情——扩展需要一个 「点击我的入口就到我自己的配置面」的动作时用它(例如顶栏的接入徽标),不必先让用户 在插件列表里自己找。插件不存在时退回到section对应的列表,不报错:设置里少一个 插件不是调用方该处理的异常。
ctx.settingsRemote
宿主统一配置 remote(Canvas page scope / 画布壳 scope 提供) 。
/api/settings 的唯一读取出口;设置页、助手生成服务与画布引导都复用同一实例,
不各自新建 fetch 或轮询。
export type SettingsRemote = { fetchSnapshot(): Promise<SettingsRemoteResult>; setExtensionInstalled?(extensionId: string, installed: boolean): Promise<SettingsRemoteResult>; write(values: Record<string, SettingsWriteValue>): Promise<SettingsRemoteResult>; test?(values: Record<string, SettingsWriteValue>): Promise<SettingsTestRemoteResult>; setExtensionToggle?(extensionId: string, enabled: boolean): Promise<SettingsRemoteResult>;};关联类型:SettingsRemote · SettingsRemoteResult · SettingsWriteValue · SettingsTestRemoteResult
成员说明:
setExtensionInstalled:安装/卸载一个扩展目录(改名,下一次启动生效);与启停无关。test:测试配置项(不落盘)。setExtensionToggle:写一个 browser-local 插件的启停目标状态:宿主把extensions.<id>.enabled写进配置文件,并热生效。
ctx.slots
export interface SlotsService { register<S extends SlotName>(slot: S, contribution: SlotContribution<S>): () => void; list<S extends SlotName>(slot: S): ReadonlyArray<SlotContribution<S>>; subscribe(slot: SlotName, listener: () => void): () => void; version(): number;}关联类型:SlotsService · SlotName · SlotContribution
成员说明:
version:全局版本号,供诊断/测试。
ctx.snippetCatalog
feature-owned 片段目录 capability(由 prompt-snippets extension 提供)。
export type SnippetCatalogService = { getState(): SnippetCatalogState; getTagState(): SnippetCatalogTagState; subscribe(listener: () => void): () => void; setQuery(query: string): void; setFilter(filter: SnippetCatalogFilter): void; loadMore(): Promise<void>; refresh(): Promise<void>; loadTags(): Promise<void>; dispose(): void;};关联类型:SnippetCatalogService · SnippetCatalogState · SnippetCatalogTagState · SnippetCatalogFilter
ctx.taskCatalog
export interface TaskCatalogService { getState(): CatalogState; subscribe(listener: () => void): () => void; load(force?: boolean): Promise<void>; invalidate(): void;}关联类型:TaskCatalogService · CatalogState
成员说明:
invalidate:站点生成插件/模型策略变化时使目录失效并重取。
ctx.taskNotifications
App 级任务结果通知服务 。
唯一实例,归 App scope:关闭设置、释放 Canvas page、切到历史页都不停止它; 设置「通知」分区只订阅 snapshot 并调用具名操作。
export type NotificationServiceHandle = TaskNotificationService & { start(): Promise<void>; handleScopeChange(): Promise<void>;};关联类型:NotificationServiceHandle · TaskNotificationService
成员说明:
deliveries:最近投递(诊断/回归;有界)。start:启动观察(App scope 装配后调用一次)。handleScopeChange:数据范围变化(账号切换):重读偏好并为新范围重建基线。
ctx.taskRemote
export interface TaskRemoteService { fetchCatalog(): Promise<CanvasTaskCatalog>; createHistory(): TaskHistoryReader;}关联类型:TaskRemoteService · CanvasTaskCatalog · TaskHistoryReader
ctx.theme
页面级唯一主题 owner。
export interface ThemeService { getSnapshot(): AppThemeSnapshot; subscribe(listener: () => void): () => void; setPreset(preset: unknown): { ok: true; } | { ok: false; error: string; }; select(presetId: string): { ok: true; } | { ok: false; error: string; }; registerPreset(presetId: string, preset: unknown): void; presetIds(): readonly string[]; applyTo(root: HTMLElement): () => void; diagnostic(): string | null; dispose(): void;}关联类型:ThemeService · AppThemeSnapshot
成员说明:
getSnapshot:当前主题 snapshot(订阅后读取;同一引用的原子对象)。subscribe:订阅主题变化;返回退订函数。setPreset:用完整 preset 原子替换;非法输入整体拒绝并保留上一主题。select:按 id 选择已注册 preset。registerPreset:注册可由本地选择引用的具名 preset。presetIds:已注册、可供select选择的 preset id。applyTo:把当前 snapshot 写到主题根容器;返回撤销函数。diagnostic:最近一次非法切换的诊断(成功切换后清空)。dispose:释放:撤销订阅与根容器,不遗留 document 级监听。