跳转到内容

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

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;
};

关联类型:CanvasRecoveryService

成员说明:

  • 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/admin taskRemote.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;
}

关联类型:CanvasSelectionService

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 级监听。