@modular/sdk/view
208 exports in 5 groups.
Interfaces130
- HostActionContextinterfaceThe context an interceptor runs in, not the one a handler runs in. It is deliberately narrower than ContextBase.
- HostActionEnvelopeinterfaceOne action in flight, with everything an interceptor needs to judge it. The envelope answers who asked, from where, in what scope, and with what input.
- StateDefinitionBoundaryPropsinterfacechildren, observeStateDefinitions, onError, onSettled
- ViewContextProviderPropsinterfacechildren, value
- AiAgentHandleinterfaceid, config(), metadata(), run(), spawn()
- AiAgentMetadatainterfacedescription, id, model, name, tools
- AiAgentsApiinterfacefind(), get(), list(), observe()
- AiAttachmentBaseinterfacedisplayKind, label
- AiBinaryAttachmentinterfacecontentType, data, displayKind, kind, label
- AiErrorSignalinterfacekind, message
- AiHookRunSignalinterfacehookType, kind, status, stopReason, systemMessage, toolName, turnId
- AiInputRequestSignalinterfacekind, prompt, requestId, turnId
- AiModelInfointerfaceid, name, vendor
- AiModelsApiinterfacelist()
- AiNotificationMessageinterfaceA system event delivered into a session.
- AiPendingConfirmationSignalinterfacecallId, kind, message, title, turnId
- AiPromptMessageinterfaceA prompt for the model to act on.
- AiReasoningSignalinterfacekind, text
- AiResourceAttachmentinterfacecontentType, displayKind, kind, label, uri
- AiRunResultinterfaceThe finished answer from AiSessionHandle.run.
- AiRuntimeApiinterfaceThe AI surface available to a mod: one-shot questions, durable sessions, declared agents, model routes, and transcription.
- AiSendOptionsinterfaceExtra input for a single prompt.
- AiSessionConfiginterfaceOverrides applied when creating a session.
- AiSessionForkConfiginterfaceforeground, metadata
- AiSessionHandleinterfaceA live handle to one durable AI session. A session owns a conversation: its history, its model, its working directory, and its place in the session tree.
- AiSessionMetadatainterfaceid, isArchived, lineage, metadata, model, resource, status, title, updatedAt, workingDirectory
- AiSessionsApiinterfaceThe workspace's session catalog: create sessions, look them up, and manage their lifecycle. Reach for this when you need a session that is not the one you are running in.
- AiTextAttachmentinterfacedisplayKind, kind, label, modelRepresentation
- AiTextDeltaSignalinterfacekind, text
- AiToolCallCompleteSignalinterfacecallId, kind, ok, turnId
- AiToolCallStartSignalinterfacecallId, kind, toolName, turnId
- AiToolDeclarationinterfacedescription, inputSchema, name
- AiToolInputSchemainterface$id, $schema, additionalProperties, default, description, enum, format, id, items, properties, required, title, type
- AiToolOutputinterfacecontent, mimeType
- AiToolResultinterfaceoutput, text
- AiTurnCancelledSignalinterfacekind, turnId
- AiTurnCompleteSignalinterfacekind, turnId
- AiTurnHandleinterfaceA handle to one in-flight or finished turn. Returned by AiSessionHandle.send when you need to watch a turn as it runs or cancel it.
- AiViewApiinterfaceThe AI surface available to a mod: one-shot questions, durable sessions, declared agents, model routes, and transcription.
- AiViewToolsApiinterfaceregister()
- AuthGetSessionOptionsinterfacecreateIfNone
- AuthViewApiinterfacegetSession()
- CommandInvocationinterfaceThe call that started the current command run.
- CommandsViewApiinterfaceRuns a registered command by id, including commands the host and other mods own. This is the escape hatch for behaviour that has no host action behind it. The command id and its arguments are untyped, so when an action exists for what you want, `ctx.action(...)` is the better call: it checks the input and the result against the action's schema.
- ContextBaseinterfaceEverything every handler in a mod can reach. The shape is a split: state and events are how you read the app, actions are how you change it.
- Disposableinterfacedispose()
- EditorSelectionChangedEventinterfacechangedAt, current, previous
- EventEmitResultinterfaceeventId, kind
- EventOccurrenceinterfaceOne delivery of an event to your listener. Dispatch through `occurrence.action(...)` rather than `ctx.action(...)` when you react to an event.
- HostActionAbortSignalinterfaceaborted, reason, addEventListener(), removeEventListener()
- HostActionBlockReasoninterfacecode, message
- HostActionClientRunOptionsinterfacesignal
- HostActionDescriptorDtointerfaceWhat `ctx.describeAction(...)` returns: an action's title, parameters, and stability, keyed by its canonical id.
- HostActionDidCommitEventinterfaceaction, actionId, afterRevision, beforeRevision, completedAt, result, traceId
- HostActionEnvelopeDtointerfaceactionId, actor, id, parentActionId, parentSpanId, scope, source, startedAt, traceId, workflowId
- HostActionInterceptorRegistrationSnapshotinterfaceactionId, activationOrdinal, actor, hook, id, phase, priority, registrationOrdinal, scope, source
- HostActionParameterDtointerfacedescription, name, optional, schema
- HostActionRunnerinterfaceDispatches actions from inside an interceptor, where `ctx.action(...)` of the outer context is not in reach.
- HostActionSchemaDtointerfacename, schema
- HostActionTraceinterfaceactionId, actionRunId, actor, descriptor, events, id, parentSpanId, scope, source, workflowId
- HostClipboardCapabilitiesinterfaceClipboard writes available to an interceptor.
- HostContextinterfaceThe context for code the host runs inside the renderer itself: editor extensions, canvas elements, and React UI reached through `useMod()`. It carries the same capabilities as a view minus the panel.
- HostEventCapabilitiesinterfaceCommit notifications available to an interceptor.
- HostEventDescriptorDtointerfaceWhat `ctx.describeEvent(...)` returns: the shape and documentation of one host event.
- HostHookClientinterfaceRegisters interceptors at runtime. Use this when the decision needs code.
- HostTraceContextinterfaceThe trace the current action is being recorded under.
- LoggerinterfaceYour mod's log channel in the host. Use it instead of `console`, which is forbidden at module top level.
- ModularActionDescriptorDtointerfacedefaultScope, effects, id, input, owner, parameters, result, stability, title
- ModularActionMapinterfaceThe catalog of host owned actions, each mapped to its input and result shapes.
- ModularEventDescriptorDtointerfaceid, owner, schema, sensitivity, stability
- ModularEventMapinterfaceeditor.selectionChanged, host.action.didCommit, multiplayer.presenceChanged
- OwnedStateinterfaceA writable handle to state your own mod declared. Returned by `ctx.state(declaration)` when you pass the value you built with state.
- PermissionClientinterfaceReads what the user has granted, denied, and is being asked right now. This is an observation surface.
- PermissionDecisionRecordDtointerfacecapability, createdAt, decision, grantId, id, powers, reason, requestId, scope, subject, target
- PermissionGrantDtointerfacecapability, createdAt, decision, declarationHash, duration, expiresAt, id, powers, reason, scope, subject, target
- PermissionIdentityDtointerfacekind
- PermissionPendingRequestDtointerfacecreatedAt, id, reason, request
- PermissionPreferenceFactDtointerfaceid, reason, scope, source, value
- PermissionSnapshotDtointerfacegrants, pendingRequests, preferenceFacts, recentDecisions
- ReadonlySignalinterfaceA value you can read now and be told about later. The host hands these out for state it owns, so a mod never polls.
- StateinterfaceA read-only handle to one state value. Returned by `ctx.state('editor.selection')` and the other built-in state names.
- StateSnapshotinterfaceaccessScope, capturedAt, descriptor, id, kind, previous, revision, value
- UiActioninterfaceid, label, role
- UiCancellationTokeninterfaceisCancellationRequested, onCancellationRequested()
- UiCapabilityinterfacedialog, notification, progress, quickInput
- UiConfirmDialogRequestinterfacecancelAction, detail, message, primaryAction, secondaryAction, title
- UiDialogCapabilityinterfaceconfirm()
- UiInputRequestinterfaceplaceholder, prompt, title, value
- UiNotificationCapabilityinterfaceerror(), info(), warning()
- UiNotificationRequestinterfaceactions, detail, message, modal
- UiProgressCapabilityinterfacewithProgress()
- UiProgressOptionsinterfacecancellable, location, title
- UiProgressReportinterfaceincrement, message
- UiProgressReporterinterfacereport()
- UiQuickInputCapabilityinterfaceinput(), pick()
- UiQuickPickIteminterfacedescription, detail, id, label
- UiQuickPickRequestinterfaceitems, placeholder, title
- ViewContextinterfaceThe context a panel declared with `view(...)` receives, through `useViewContext()`. The two members that only exist here are `viewId` and `diagnostics`: a view is a panel the host mounts, so it has an identity in the layout and it owes the host a report on whether it rendered.
- ViewDiagnosticsinterfaceHow a view tells the host whether it actually rendered. The runtime graph and the eval harness read only this channel.
- WidgetsViewApiinterfaceControls the floating surfaces your mod declared with `widget(...)`. Widgets are declared once and shown on demand.
- WorkbenchApiinterfaceapplyLayout(), createStatusBarItem(), open()
- WorkbenchColorThemeinterfacekind
- WorkbenchEditorLayoutGroupPlaninterfacegroups, size
- WorkbenchEditorLayoutPlaninterfacegroups, orientation
- WorkbenchEditorLayoutStateinterfacegroupCount, orientation
- WorkbenchLayoutinterfaceeditor, zones
- WorkbenchLayoutApplyResultinterfaceapplied, changed, warnings
- WorkbenchLayoutApplyWarninginterfacecode, message
- WorkbenchLayoutContainerTargetinterfacefocus, id, kind
- WorkbenchLayoutPlaninterfaceeditor, zones
- WorkbenchLayoutViewTargetinterfacefocus, id, kind
- WorkbenchOpenResultinterfaceopened
- WorkbenchOpenUriTargetinterfaceallowContributedOpeners, external, fromUserGesture, kind, openToSide, uri
- WorkbenchOpenViewContainerTargetinterfacefocus, id, kind
- WorkbenchOpenViewTargetinterfacefocus, id, kind
- WorkbenchOpenWalkthroughCategoryTargetinterfacecategory, inactive, kind, openToSide, step
- WorkbenchOpenWalkthroughHomeTargetinterfacecategory, inactive, kind, openToSide, step
- WorkbenchStatusBarIteminterfaceid, dispose(), hide(), show(), update()
- WorkbenchStatusBarItemOptionsinterfacealignment, command, priority, text, tooltip
- WorkbenchViewPlacementPlaninterfaceactive, id, visible
- WorkbenchWindowStateinterfaceactive, focused
- WorkbenchZoneLayoutPlaninterfaceactive, size, views, visible
- WorkbenchZoneSizePlaninterfaceheight, width
- WorkbenchZoneStateinterfacevisible
- WorkspaceApiinterfacefs, getConfiguration(), getFolders(), onDidChangeConfiguration(), onDidChangeFolders(), updateConfiguration()
- WorkspaceConfigurationChangeinterfaceaffectsConfiguration()
- WorkspaceDirEntryinterfacename, type
- WorkspaceFileStatinterfacectime, mtime, size, type
- WorkspaceFileSysteminterfacecreateDirectory(), delete(), readDirectory(), readFile(), rename(), stat(), writeFile()
- WorkspaceFolderinterfaceindex, name, uri
Types70
- CanonicalHostActionInputtypeThe input shape of an action addressed by its canonical id. Same resolution as ModularActionInput, minus the bare command id case.
- CanonicalHostActionResulttypeThe result shape of an action addressed by its canonical id.
- HostActionInterceptortypeMiddleware around one action. Call `next(action.input)` to let it run untouched.
- HostActionNexttypeHands control to the rest of the interceptor chain and then to the action owner. Pass the input through unchanged to observe, or pass a rewritten input to change what actually runs.
- ModularActionInputtypeThe payload an action accepts, resolved from the reference you name.
- ModularActionReferencetypeWhat you may pass to `ctx.action(...)` and friends. Either a host action id or a bare command id.
- ModularActionResulttypeWhat an action resolves to, resolved from the reference you name.
- NormalizeHostActionReferencetypeAlias of NormalizeModularActionReference.
- ViewRenderOutcometypeHow a render attempt settled.
- AiAttachmenttypeAiTextAttachment | AiBinaryAttachment | AiResourceAttachment
- AiAutoApproveLeveltype'default' | 'autoApprove' | 'autopilot'
- AiHookRunStatustype'completed' | 'failed' | 'blocked' | 'timedOut'
- AiHookTypetype'SessionStart' | 'SessionEnd' | 'UserPromptSubmit' | 'PreToolUse' | 'PostToolUse' | 'PreCompact' | 'SubagentStart' | 'SubagentStop' | 'Stop' | 'ErrorOccurred'
- AiJsonSchemaTypetype'string' | 'number' | 'integer' | 'boolean' | 'null' | 'array' | 'object'
- AiMessagetypeWhat a mod puts into a session.
- AiRunnerIdtype'graph' | 'codex' | 'claude-sdk'
- AiSessionDeleteResulttype{ kind: 'deleted' } | { kind: 'cancelled' }
- AiSessionDisplayMetadatatypeImmutable presentation metadata for a session. At least one field is required.
- AiSessionLineagetype{ kind: 'root' } | { depth: number; forkedAt: string; kind: 'fork'; parentRunnerId: AiRunnerId; parentSessionId: SessionId; parentTurnOrdinal: number; parentUserMessageId?: string } | { depth: number; kind: 'spawn'; parentChatUri: string; parentSessionId: SessionId; spawnedAt: string; trigger: AiSpawnTrigger }
- AiSessionSignaltypeAiTextDeltaSignal | AiReasoningSignal | AiToolCallStartSignal | AiToolCallCompleteSignal | AiPendingConfirmationSignal | AiInputRequestSignal | AiTurnCompleteSignal | AiTurnCancelledSignal | AiErrorSignal | AiHookRunSignal
- AiSessionStatustype'idle' | 'inProgress' | 'needsInput' | 'completed' | 'error'
- AiSpawnTriggertype{ commandId: string; kind: 'command' } | { kind: 'tool'; toolCallId: ToolCallId }
- AiToolHandlertype(input: AiToolInput) => Promise<AiToolHandlerResult>
- AiToolHandlerResulttypestring | AiToolResult
- AiToolInputtypeRecord<string, unknown>
- AiTurnDeliverytype{ kind: 'delivered'; value: unknown } | { kind: 'none' }
- AiTurnPendingSnapshottype{ kind: 'queued'; sessionId: SessionId; submissionId: SubmissionId } | { kind: 'running'; sessionId: SessionId; submissionId: SubmissionId; turnId: TurnId } | { kind: 'needsInput'; sessionId: SessionId; submissionId: SubmissionId; turnId: TurnId }
- AiTurnSnapshottypeAiTurnPendingSnapshot | AiTurnTerminalSnapshot
- AiTurnTargettype{ kind: 'queued' } | { kind: 'turn'; turnId: TurnId }
- AiTurnTerminalSnapshottype{ delivery: AiTurnDelivery; kind: 'completed'; result: AiRunResult; sessionId: SessionId; submissionId: SubmissionId; turnId: TurnId } | { error: { message: string }; kind: 'failed'; sessionId: SessionId; submissionId: SubmissionId; target: AiTurnTarget } | { kind: 'cancelled'; sessionId: SessionId; submissionId: SubmissionId; target: AiTurnTarget }
- CommandContexttypeThe context a `command(...)` handler receives. `command` is what it adds: the id that ran and the arguments it was given, which is how one handler can serve a palette entry, a keybinding, and a programmatic call.
- CommandHostActionIdtypeA command id in host action form, `command:notes.copy-upper`.
- CommandIdtypeThe id you gave a command in `command({ id })`, for example `'notes.copy-upper'`.
- EditorSelectiontypeLexicalEditorSelection | MonacoEditorSelection
- EditorSelectionBasetypez.infer<typeof editorSelectionBaseSchema>
- FocusedEditorGroupTabStatetypez.infer<typeof focusedEditorGroupTabStateSchema>
- HostActionIdtypeThe canonical id of any action, host owned or command backed. Canonical means commands carry the `command:` prefix.
- HostActionInputtypeAlias of ModularActionInput.
- HostActionInterceptorPhasetype'host-policy' | 'workspace-policy' | 'mod' | 'mod-view' | 'agent'
- HostActionReferencetypeAlias of ModularActionReference, used where the surrounding API is spelled in host action terms.
- HostActionResulttypeAlias of ModularActionResult.
- HostActionSourcetype{ commandId: string; kind: 'command' } | { commandId: string; kind: 'keybinding' } | { componentId: string; kind: 'ui' } | { kind: 'agent-tool'; toolName: string } | { kind: 'mod-api'; modId: ModId } | { callbackId: string; kind: 'callback' } | { kind: 'host' }
- HostActionStabilitytype'internal' | 'experimental' | 'stable'
- HostActionTraceEventtype{ actionId: string; actionRunId: string; actor: HostActor; kind: 'action-started'; source: HostActionSource } | { kind: 'interceptor-started'; registration: HostActionInterceptorRegistrationSnapshot } | { changedInput: boolean; kind: 'interceptor-continued'; registration: HostActionInterceptorRegistrationSnapshot } | { kind: 'interceptor-replaced'; registration: HostActionInterceptorRegistrationSnapshot } | { kind: 'interceptor-completed'; registration: HostActionInterceptorRegistrationSnapshot } | { kind: 'interceptor-timed-out'; registration: HostActionInterceptorRegistrationSnapshot; timeoutMs: number } | { kind: 'action-aborted'; message: string; registration?: HostActionInterceptorRegistrationSnapshot } | { kind: 'owner-started' } | { kind: 'owner-completed' } | { kind: 'action-blocked'; reason: HostActionBlockReason; registration?: HostActionInterceptorRegistrationSnapshot } | { kind: 'action-failed'; message: string; registration?: HostActionInterceptorRegistrationSnapshot } | { afterRevision: number; beforeRevision: number; kind: 'action-committed' }
- HostActortype{ kind: 'user' } | { kind: 'agent'; runner: 'codex' | 'claude' } | { kind: 'mod'; modId: ModId } | { kind: 'mod-view'; modId: ModId; viewId: string } | { kind: 'host' }
- HostEffecttype'read-state' | 'write-state' | 'mutate-editor' | 'mutate-workspace' | 'send-terminal-text' | 'write-clipboard' | 'write-filesystem' | 'network' | 'capture-audio' | 'ui'
- HostEventIdtypestring
- HostScopetype{ kind: 'root' } | { kind: 'workspace'; workspaceId: string } | { editorId: string; kind: 'editor'; workspaceId?: string } | { kind: 'session'; sessionId: string; workspaceId?: string } | { kind: 'agent-panel'; panelId: string; sessionId?: string; workspaceId?: string } | { kind: 'view'; modId: ModId; viewId: string; workspaceId?: string }
- LexicalEditorSelectiontypez.infer<typeof lexicalEditorSelectionSchema>
- ModIdtypez.infer<typeof modIdSchema>
- ModularCommandReferencetypeA command named in author-facing code, without the `command:` prefix.
- ModularEventIdtypeThe id of a host event you can subscribe to with `ctx.on(...)`, for example `'editor.selectionChanged'`.
- ModularStaticActionReferencetypeA host owned action named in author-facing code.
- MonacoEditorSelectiontypez.infer<typeof monacoEditorSelectionSchema>
- NormalizeModularActionReferencetypeMaps a written reference to the canonical id it dispatches to. A host action id passes through unchanged.
- PublicHookActionReferencetypeRejects an already prefixed command id where an author is meant to write the plain one. Resolves to `never` for `command:foo`, which turns the mistake into a compile error at the call site instead of a silent `command:command:foo`.
- SlashCommandContexttypeThe context a `slashCommand(...)` handler receives. `session` is what it adds: the conversation the user typed the slash command into.
- StaticHostActionIdtypeThe id of an action the host itself owns, for example `'clipboard.writeText'`. These are fixed by the host and fully typed: their input and result shapes live in ModularActionMap.
- UiActionResulttype{ actionId: string; kind: 'action' } | { kind: 'dismissed' } | { kind: 'cancelled' }
- UiInputResulttype{ kind: 'submitted'; value: string } | { kind: 'cancelled' }
- UiQuickPickResulttype{ itemId: string; kind: 'picked' } | { kind: 'cancelled' }
- UiSeveritytype'info' | 'warning' | 'error'
- WorkbenchColorThemeKindtype'light' | 'dark' | 'high-contrast' | 'high-contrast-light'
- WorkbenchEditorLayoutOrientationtype'horizontal' | 'vertical'
- WorkbenchLayoutZoneIdtype'panel-left' | 'panel-right' | 'panel-bottom'
- WorkbenchOpenTargettypeWorkbenchOpenUriTarget | WorkbenchOpenViewTarget | WorkbenchOpenViewContainerTarget | WorkbenchOpenWalkthroughTarget
- WorkbenchOpenWalkthroughTargettypeWorkbenchOpenWalkthroughHomeTarget | WorkbenchOpenWalkthroughCategoryTarget
- WorkbenchStatusBarAlignmenttype'left' | 'right'
- WorkbenchViewActivationPlantypeWorkbenchLayoutViewTarget | WorkbenchLayoutContainerTarget
- WorkspaceFileTypetype'unknown' | 'file' | 'directory' | 'symlink'
Functions6
- useModStatefunction<TValue>(state: State<TValue>) => StateSnapshot<TValue>
- useViewContextfunction() => ViewContext
- ViewContextProviderfunction(props: ViewContextProviderProps) => ReactNode
- commandActionIdfunctionTurns a command id into its host action id by adding the `command:` prefix.
- commandIdFromActionIdfunctionRecovers the command id from a host action id. Returns `undefined` for a host owned action, which is how you tell the two kinds of id apart.
- normalizeHostActionIdfunctionResolves a written reference to the canonical id the host dispatches on. A known host action id is returned as is.