@makaio/contracts 1.0.0-dev-1779051654000

package/dist/extension/contributions/session-event-action-types.d.ts

@@ -0,0 +1,275 @@
+import type { MakaioBusLike } from '@makaio/framework/core';
+import type { MakaioSessionEvent } from '../../session/types.js';
+import type { SessionMessage } from '../../session/schemas/message.js';
+import { SESSION_EVENT_TYPES } from '../../session/schemas/event.js';
+/** Keyboard modifier flags for an action shortcut. */
+export interface ActionShortcutModifiers {
+    /** Meta/Command key. */
+    meta?: boolean;
+    /** Alt/Option key. */
+    alt?: boolean;
+    /** Shift key. */
+    shift?: boolean;
+    /** Control key. */
+    ctrl?: boolean;
+}
+/** Full keyboard shortcut definition including modifiers and display metadata. */
+export interface ActionShortcut extends ActionShortcutModifiers {
+    /** Primary key character or name. */
+    key: string;
+    /** Human-readable label shown in keyboard shortcut hints. */
+    label: string;
+    /** Category grouping for the shortcut. */
+    category: ActionCategory;
+    /** Optional human-readable description. */
+    description?: string;
+    /** Whether the shortcut should not activate while focus is in an input field. */
+    skipInInputs?: boolean;
+    /** Optional context scope string or list of scopes. */
+    context?: string | string[];
+}
+/**
+ * Extension point for registering custom action categories.
+ *
+ * Extend via declaration merging from packages or UI layers.
+ * @example
+ * ```typescript
+ * declare module '@makaio/framework/contracts' {
+ *   interface ActionCategoryMap {
+ *     timeline: true;
+ *   }
+ * }
+ * ```
+ */
+export interface ActionCategoryMap {
+    /** Default category for uncategorized actions. */
+    general: true;
+}
+type RegisteredActionCategory = keyof ActionCategoryMap & string;
+/** Resolved action category type, extensible via {@link ActionCategoryMap} declaration merging. */
+export type ActionCategory = RegisteredActionCategory;
+/** Allowed message role values for event action entrypoints. */
+export type MessageRole = 'user' | 'assistant';
+/** Event filter that matches message events with optional role restriction. */
+export interface MessageEventFilter {
+    /** Discriminant: must be `'message'`. */
+    eventType: 'message';
+    /** Optional list of message roles this filter applies to. */
+    messageRole?: MessageRole[];
+}
+/** All core session event types except `'message'`. */
+type StructuralEventType = Exclude<(typeof SESSION_EVENT_TYPES)[number], 'message'>;
+/** Event filter that matches structural (non-message) session events. */
+export interface StructuralEventFilter {
+    /** The specific structural event type to match. */
+    eventType: StructuralEventType;
+}
+/** Union of message and structural event filters. */
+export type EventFilter = MessageEventFilter | StructuralEventFilter;
+/**
+ * Context passed to a session event action factory.
+ * @typeParam TBus - Host bus shape supplied by the runtime.
+ */
+export interface SessionEventActionContext<TBus extends MakaioBusLike = MakaioBusLike> {
+    /** Bus instance for registering action handlers. */
+    bus: TBus;
+    /** Name of the extension registering the action. */
+    extensionName: string;
+    /**
+     * Register one executable action with the owning session-event-action service.
+     *
+     * The service package owns the bus subjects and callback plumbing; extension
+     * contributors receive this factory through the contribution context instead
+     * of importing service implementation modules directly.
+     * @param options - Action declaration and runtime callbacks.
+     * @returns Serializable declaration plus unregister hook.
+     */
+    createAction: <TMode extends 'single' | 'multi', TRoles extends MessageRole[]>(options: SessionEventActionOptions<TMode, TRoles, TBus>) => CreateSessionEventActionResult;
+}
+/**
+ * Context passed to a session event action's `when` predicate.
+ * @typeParam TRoles - Message roles accepted by the action entrypoint.
+ * @typeParam TBus - Host bus shape supplied by the runtime.
+ */
+export interface WhenContext<TRoles extends MessageRole[] = MessageRole[], TBus extends MakaioBusLike = MakaioBusLike> {
+    /** The message event that triggered the predicate check. */
+    message: SessionMessage & {
+        role: TRoles[number];
+    };
+    /** Active session identifier. */
+    sessionId: string;
+    /** Bus instance for runtime queries. */
+    bus: TBus;
+}
+/**
+ * Context passed to a session event action's `onPickerOpen` callback.
+ * @typeParam TRoles - Message roles accepted by the action entrypoint.
+ * @typeParam TBus - Host bus shape supplied by the runtime.
+ */
+export interface PickerOpenContext<TRoles extends MessageRole[] = MessageRole[], TBus extends MakaioBusLike = MakaioBusLike> {
+    /** Entrypoint information for the action. */
+    entrypoint: {
+        /** The message that was actioned. */
+        messageId: string;
+        /** Full message object. */
+        message: SessionMessage & {
+            role: TRoles[number];
+        };
+    };
+    /** Active session identifier. */
+    sessionId: string;
+    /** Active project identifier. */
+    projectId?: string;
+    /** Bus instance for runtime queries. */
+    bus: TBus;
+}
+/** Configuration returned by `onPickerOpen` to control the event picker UI. */
+export interface PickerConfig {
+    /** Event IDs that should be pre-selected when the picker opens. */
+    preSelectedEventIds?: string[];
+    /** Maximum number of events that can be selected. */
+    maxSelections?: number;
+    /** Custom title for the picker dialog. */
+    title?: string;
+}
+/**
+ * Context passed to a session event action's `onSelectionChange` callback.
+ * @typeParam TBus - Host bus shape supplied by the runtime.
+ */
+export interface SelectionChangeContext<TBus extends MakaioBusLike = MakaioBusLike> {
+    /** Currently selected session events. */
+    selectedEvents: MakaioSessionEvent[];
+    /** Entrypoint information for the action. */
+    entrypoint: {
+        /** The message that was actioned. */
+        messageId: string;
+        /** Full message object. */
+        message: SessionMessage;
+    };
+    /** Active session identifier. */
+    sessionId: string;
+    /** Bus instance for runtime queries. */
+    bus: TBus;
+}
+/** Feedback returned by `onSelectionChange` to inform the picker UI. */
+export interface SelectionFeedback {
+    /** Estimated token count for the selected events. */
+    tokenEstimate?: number;
+    /** Warning message to display in the picker. */
+    warning?: string;
+    /** Error message that blocks confirmation. */
+    error?: string;
+}
+/** Context passed to a session event action's `onExecute` callback. */
+export interface ExecuteContext<TMode extends 'single' | 'multi' = 'single' | 'multi', TRoles extends MessageRole[] = MessageRole[], TBus extends MakaioBusLike = MakaioBusLike> {
+    /** Entrypoint information for the action. */
+    entrypoint: {
+        /** The message that was actioned. */
+        messageId: string;
+        /** Full message object. */
+        message: SessionMessage & {
+            role: TRoles[number];
+        };
+    };
+    /** Selected events when in multi-selection mode, otherwise `undefined`. */
+    selectedEvents: TMode extends 'multi' ? MakaioSessionEvent[] : undefined;
+    /** Active session identifier. */
+    sessionId: string;
+    /** Active project identifier. */
+    projectId?: string;
+    /** Bus instance for runtime queries. */
+    bus: TBus;
+}
+/** Result returned by a session event action's `onExecute` callback. */
+export interface ExecuteResult {
+    /** Whether execution succeeded. */
+    success: boolean;
+    /** Human-readable error message when `success` is `false`. */
+    error?: string;
+}
+/** Configuration for a session event action's message entrypoint. */
+export interface EntrypointConfig<TRoles extends MessageRole[] = MessageRole[]> {
+    /** Allowed message roles that can trigger this action. */
+    messageRole: TRoles;
+}
+/** Full options for defining a session event action. */
+export interface SessionEventActionOptions<TMode extends 'single' | 'multi' = 'single' | 'multi', TRoles extends MessageRole[] = MessageRole[], TBus extends MakaioBusLike = MakaioBusLike> {
+    /** Unique action identifier within the registering package. */
+    id: string;
+    /** Display label for the action. */
+    label: string;
+    /** Optional human-readable description. */
+    description?: string;
+    /** Optional icon identifier. */
+    icon?: string;
+    /** Message entrypoint configuration. */
+    entrypoint: EntrypointConfig<TRoles>;
+    /** Whether this action operates on a single event or multiple events. */
+    selectionMode: TMode;
+    /** Event type filters for multi-selection mode. */
+    applicableTo?: TMode extends 'multi' ? EventFilter[] : never;
+    /**
+     * Optional predicate that determines whether the action is available.
+     * @param ctx - Context with the triggering message.
+     * @returns `true` when the action should be shown.
+     */
+    when?: (ctx: WhenContext<TRoles, TBus>) => Promise<boolean>;
+    /**
+     * Optional callback invoked when the event picker opens.
+     * @param ctx - Context with entrypoint and session info.
+     * @returns Picker configuration, `false` to cancel, or `void`.
+     */
+    onPickerOpen?: TMode extends 'multi' ? (ctx: PickerOpenContext<TRoles, TBus>) => Promise<PickerConfig | false | void> : never;
+    /**
+     * Optional callback invoked when the event selection changes.
+     * @param ctx - Context with selected events.
+     * @returns Selection feedback to display in the picker.
+     */
+    onSelectionChange?: TMode extends 'multi' ? (ctx: SelectionChangeContext<TBus>) => Promise<SelectionFeedback | void> : never;
+    /** Category grouping for this action. */
+    category?: ActionCategory;
+    /** Optional keyboard shortcut. */
+    shortcut?: ActionShortcut;
+    /**
+     * Main execution callback invoked when the action is confirmed.
+     * @param ctx - Context with entrypoint, selected events, and bus.
+     * @returns Execution result, or `void` on success.
+     */
+    onExecute: (ctx: ExecuteContext<TMode, TRoles, TBus>) => Promise<ExecuteResult | void>;
+}
+/** Serializable declaration stored in registries and emitted over the bus. */
+export interface SessionEventActionDeclaration {
+    /** Unique action identifier. */
+    id: string;
+    /** Display label. */
+    label: string;
+    /** Optional description. */
+    description?: string;
+    /** Optional icon identifier. */
+    icon?: string;
+    /** Entrypoint configuration. */
+    entrypoint: EntrypointConfig;
+    /** Selection mode. */
+    selectionMode: 'single' | 'multi';
+    /** Event type filters (multi mode only). */
+    applicableTo?: EventFilter[];
+    /** Whether a `when` predicate was provided. */
+    hasWhenPredicate: boolean;
+    /** Whether an `onPickerOpen` callback was provided. */
+    hasPickerOpenCallback: boolean;
+    /** Whether an `onSelectionChange` callback was provided. */
+    hasSelectionChangeCallback: boolean;
+    /** Resolved action category. */
+    category: ActionCategory;
+    /** Optional keyboard shortcut. */
+    shortcut?: ActionShortcut;
+}
+/** Return value from `createSessionEventAction` — declaration plus unregister hook. */
+export interface CreateSessionEventActionResult {
+    /** Serializable declaration for registry and bus publication. */
+    declaration: SessionEventActionDeclaration;
+    /** Unregisters the action and cleans up bus subscriptions. */
+    unregister: () => void;
+}
+export {};
+//# sourceMappingURL=session-event-action-types.d.ts.map

package/dist/extension/contributions/session-event-action-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-event-action-types.d.ts","sourceRoot":"","sources":["../../../src/extension/contributions/session-event-action-types.ts"],"names":[],"mappings":"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"}

package/dist/extension/contributions/tile-types.d.ts

@@ -0,0 +1,143 @@
+import type { ComponentType } from 'react';
+import type { UiContextDimension, UiScope } from './ui-context-types.js';
+/** Optional feature flags a tile can declare. */
+export interface TileCapabilities {
+    /** Whether this tile supports fullscreen mode. */
+    supportsFullscreen?: boolean;
+}
+/**
+ * Props passed to tile components.
+ *
+ * Tiles do not receive host context as direct props; hosts expose context
+ * through their UI runtime.
+ */
+export interface TileProps {
+    /** Optional class name for styling. */
+    className?: string;
+}
+/**
+ * Icon loader for a tile.
+ *
+ * Lazy-loads an icon component (typically from `lucide-react`).
+ * @example
+ * ```typescript
+ * icon: () => import('lucide-react').then(m => ({ default: m.Terminal }))
+ * ```
+ */
+export type TileIconLoader = () => Promise<{
+    default: ComponentType<{
+        size?: number;
+    }>;
+}>;
+/**
+ * Platform renderers for a tile.
+ *
+ * SEAM: Currently supports React; additional platforms can be added as optional
+ * keys without breaking existing declarations.
+ */
+export interface TileRenderers {
+    /**
+     * React renderer for the web UI.
+     *
+     * Lazy-loaded component module with a default export that accepts
+     * {@link TileProps}.
+     */
+    react: () => Promise<{
+        default: ComponentType<TileProps>;
+    }>;
+    /**
+     * SEAM: Future platform renderers (e.g. `reactNative`, `electron`).
+     *
+     * Additional platforms can be added here as optional keys.
+     */
+    [platform: string]: (() => Promise<{
+        default: ComponentType<TileProps>;
+    }>) | undefined;
+}
+/**
+ * Tile declaration contributed by a package.
+ *
+ * Packages declare tiles they provide for pane placement. These are registered
+ * with `TileRegistry` and shown in the "Add Pane" palette.
+ * @example
+ * ```typescript
+ * const terminalExtension: MakaioExtension = {
+ *   name: 'terminal',
+ *   ui: {
+ *     tiles: [
+ *       {
+ *         id: 'status',
+ *         name: 'Status',
+ *         description: 'Runtime status panel',
+ *         scope: 'global',
+ *         icon: () => import('lucide-react').then(m => ({ default: m.Activity })),
+ *         allowMultiple: true,
+ *         capabilities: { supportsFullscreen: true },
+ *         renderers: {
+ *           react: () => import('./ui/StatusTile.js'),
+ *         },
+ *       },
+ *     ],
+ *   },
+ * };
+ * ```
+ */
+export interface TileDeclaration {
+    /**
+     * Unique tile identifier.
+     *
+     * Must be unique across all packages. Use the package name as a prefix to
+     * avoid collisions.
+     * @example `'status'`, `'session-summary'`
+     */
+    id: string;
+    /**
+     * Display name for the tile.
+     *
+     * Human-readable name shown in the "Add Pane" palette.
+     * @example `'Status'`, `'Session Summary'`
+     */
+    name: string;
+    /**
+     * Optional description of tile purpose.
+     *
+     * Shown in the "Add Pane" palette below the name.
+     */
+    description?: string;
+    /**
+     * Tile scope — where the tile is available.
+     *
+     * Defaults to `'any'` when not specified.
+     */
+    scope?: UiScope;
+    /**
+     * Icon loader for the tile.
+     *
+     * Lazy-loads an icon component for the "Add Pane" palette. Required for
+     * tiles to appear in the palette.
+     */
+    icon: TileIconLoader;
+    /**
+     * Whether multiple instances of this tile are allowed simultaneously.
+     *
+     * Defaults to `true`. When `false`, only one instance can exist at a time.
+     */
+    allowMultiple?: boolean;
+    /** Optional capability flags for the tile. */
+    capabilities?: TileCapabilities;
+    /**
+     * Context dimensions this tile's state depends on.
+     *
+     * When declared, the host can remount the tile when any listed dimension
+     * changes to prevent stale in-memory state from leaking across contexts.
+     */
+    contextDependencies?: UiContextDimension[];
+    /**
+     * Platform-specific renderers.
+     *
+     * Maps platform names to lazy-loaded component modules. At minimum, the
+     * `'react'` platform is required for the web UI.
+     */
+    renderers: TileRenderers;
+}
+//# sourceMappingURL=tile-types.d.ts.map

package/dist/extension/contributions/tile-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tile-types.d.ts","sourceRoot":"","sources":["../../../src/extension/contributions/tile-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAC3C,OAAO,KAAK,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAEzE,iDAAiD;AACjD,MAAM,WAAW,gBAAgB;IAC/B,kDAAkD;IAClD,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,OAAO,CAAC;IAAE,OAAO,EAAE,aAAa,CAAC;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,CAAC,CAAC;AAE1F;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,KAAK,EAAE,MAAM,OAAO,CAAC;QAAE,OAAO,EAAE,aAAa,CAAC,SAAS,CAAC,CAAA;KAAE,CAAC,CAAC;IAE5D;;;;OAIG;IACH,CAAC,QAAQ,EAAE,MAAM,GAAG,CAAC,MAAM,OAAO,CAAC;QAAE,OAAO,EAAE,aAAa,CAAC,SAAS,CAAC,CAAA;KAAE,CAAC,CAAC,GAAG,SAAS,CAAC;CACxF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;OAMG;IACH,EAAE,EAAE,MAAM,CAAC;IACX;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;;OAKG;IACH,IAAI,EAAE,cAAc,CAAC;IACrB;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,8CAA8C;IAC9C,YAAY,CAAC,EAAE,gBAAgB,CAAC;IAChC;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAC3C;;;;;OAKG;IACH,SAAS,EAAE,aAAa,CAAC;CAC1B"}

package/dist/extension/contributions/tool-formatter-types.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Tool call formatter types for package declarations.
+ *
+ * Defines the formatter declaration shape that packages use to contribute tool
+ * call formatters. The UI layer bridges these declarations to the
+ * `ToolCallFormatterRegistry`.
+ * @packageDocumentation
+ */
+import type { PayloadFilter } from '@makaio/framework/core';
+/** Discriminated content types for formatted tool call output. */
+export type PluginTransformedContentType = 'markdown';
+/** Formatted content block for tool call display. */
+export interface PluginTransformedContent {
+    /** Content rendering strategy. */
+    type: PluginTransformedContentType;
+    /** Content string interpreted according to `type`. */
+    content: string;
+}
+/**
+ * Output from a tool call formatter (package-side declaration).
+ *
+ * All fields are optional — formatters can override any subset.
+ */
+export interface PluginFormattedToolCallOutput {
+    /** Replaces the tool name in the block header. */
+    label?: string;
+    /** Replaces the Arguments section. */
+    content?: PluginTransformedContent;
+    /** Replaces the Output section rendering. */
+    outputContent?: PluginTransformedContent;
+}
+/** Input shape passed to a formatter's `format` function. */
+export interface PluginToolCallFormatterInput {
+    /** Name of the tool being called. */
+    toolName: string;
+    /** Arguments passed to the tool. */
+    args: Record<string, unknown>;
+    /** Current status of the tool call. */
+    status: 'pending' | 'running' | 'completed' | 'error';
+    /** Output from the tool when the call has completed. */
+    output?: string;
+}
+/**
+ * A tool call formatter declaration contributed by a package.
+ *
+ * Structurally compatible with `ToolCallFormatterDefinition` used by the
+ * UI registry, so the package loader can register declarations directly
+ * without bridging.
+ */
+export interface ToolCallFormatterDeclaration {
+    /** Unique identifier for this formatter. */
+    id: string;
+    /**
+     * Declarative filter matched against the tool call input shape.
+     *
+     * Uses a `PayloadFilter` with dot-path support (e.g. `'args.subagent_type'`).
+     * All conditions are ANDed.
+     */
+    filter: PayloadFilter;
+    /**
+     * Priority for ordering when multiple formatters match.
+     *
+     * Lower number = higher priority (checked first). Default: `50`.
+     */
+    priority: number;
+    /**
+     * Pure function that transforms a tool call block into formatted output.
+     *
+     * Returns `undefined` if the formatter decides not to handle this specific
+     * call, falling through to the next formatter.
+     * @param input - The tool call block data.
+     * @returns Formatted output, or `undefined` to skip to the next formatter.
+     */
+    format: (input: PluginToolCallFormatterInput) => PluginFormattedToolCallOutput | undefined;
+}
+//# sourceMappingURL=tool-formatter-types.d.ts.map

package/dist/extension/contributions/tool-formatter-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-formatter-types.d.ts","sourceRoot":"","sources":["../../../src/extension/contributions/tool-formatter-types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,kEAAkE;AAClE,MAAM,MAAM,4BAA4B,GAAG,UAAU,CAAC;AAEtD,qDAAqD;AACrD,MAAM,WAAW,wBAAwB;IACvC,kCAAkC;IAClC,IAAI,EAAE,4BAA4B,CAAC;IACnC,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,6BAA6B;IAC5C,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,OAAO,CAAC,EAAE,wBAAwB,CAAC;IACnC,6CAA6C;IAC7C,aAAa,CAAC,EAAE,wBAAwB,CAAC;CAC1C;AAED,6DAA6D;AAC7D,MAAM,WAAW,4BAA4B;IAC3C,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,uCAAuC;IACvC,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,OAAO,CAAC;IACtD,wDAAwD;IACxD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,4BAA4B;IAC3C,4CAA4C;IAC5C,EAAE,EAAE,MAAM,CAAC;IACX;;;;;OAKG;IACH,MAAM,EAAE,aAAa,CAAC;IACtB;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;;OAOG;IACH,MAAM,EAAE,CAAC,KAAK,EAAE,4BAA4B,KAAK,6BAA6B,GAAG,SAAS,CAAC;CAC5F"}

package/dist/extension/contributions/ui-context-types.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Extension point for UI scope identifiers.
+ *
+ * Hosts and extensions add host-specific scopes via declaration
+ * merging. Framework defaults stay host-agnostic.
+ */
+export interface UiScopeMap {
+    /** Available in framework-global contexts. */
+    global: true;
+    /** Available regardless of active UI context. */
+    any: true;
+}
+/** UI scope identifier, extensible via {@link UiScopeMap}. */
+export type UiScope = keyof UiScopeMap & string;
+/**
+ * Extension point for UI navigation levels.
+ *
+ * Hosts add domain levels through declaration merging.
+ */
+export interface UiNavigationLevelMap {
+    /** Root shell level with no host context implied. */
+    root: true;
+    /** Available at every registered navigation level. */
+    any: true;
+}
+/** UI navigation level, extensible via {@link UiNavigationLevelMap}. */
+export type UiNavigationLevel = keyof UiNavigationLevelMap & string;
+/**
+ * Runtime UI navigation level.
+ *
+ * Runtime context snapshots describe the active renderer surface. The `'any'`
+ * level is reserved for definition matching and is never an active navigation
+ * level.
+ */
+export type UiRuntimeNavigationLevel = Exclude<UiNavigationLevel, 'any'>;
+/**
+ * Extension point for typed UI context values.
+ *
+ * Keys are context dimensions; values are the serializable values exposed for
+ * that dimension in a host context snapshot.
+ */
+export interface UiContextValueMap {
+    /** Active session identifier, if the framework shell has one. */
+    session: string;
+}
+/** UI context dimension identifier, extensible via {@link UiContextValueMap}. */
+export type UiContextDimension = keyof UiContextValueMap & string;
+/** Snapshot of host UI context passed to contributed UI. */
+export interface UiContextSnapshot {
+    /** Active navigation level for the renderer surface. */
+    readonly level: UiRuntimeNavigationLevel;
+    /** Active context values keyed by registered context dimension. */
+    readonly values: Partial<{
+        readonly [K in UiContextDimension]: UiContextValueMap[K] | null;
+    }>;
+}
+//# sourceMappingURL=ui-context-types.d.ts.map

package/dist/extension/contributions/ui-context-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-context-types.d.ts","sourceRoot":"","sources":["../../../src/extension/contributions/ui-context-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,8CAA8C;IAC9C,MAAM,EAAE,IAAI,CAAC;IACb,iDAAiD;IACjD,GAAG,EAAE,IAAI,CAAC;CACX;AAED,8DAA8D;AAC9D,MAAM,MAAM,OAAO,GAAG,MAAM,UAAU,GAAG,MAAM,CAAC;AAEhD;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,qDAAqD;IACrD,IAAI,EAAE,IAAI,CAAC;IACX,sDAAsD;IACtD,GAAG,EAAE,IAAI,CAAC;CACX;AAED,wEAAwE;AACxE,MAAM,MAAM,iBAAiB,GAAG,MAAM,oBAAoB,GAAG,MAAM,CAAC;AAEpE;;;;;;GAMG;AACH,MAAM,MAAM,wBAAwB,GAAG,OAAO,CAAC,iBAAiB,EAAE,KAAK,CAAC,CAAC;AAEzE;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,iFAAiF;AACjF,MAAM,MAAM,kBAAkB,GAAG,MAAM,iBAAiB,GAAG,MAAM,CAAC;AAElE,4DAA4D;AAC5D,MAAM,WAAW,iBAAiB;IAChC,wDAAwD;IACxD,QAAQ,CAAC,KAAK,EAAE,wBAAwB,CAAC;IACzC,mEAAmE;IACnE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;QACvB,QAAQ,EAAE,CAAC,IAAI,kBAAkB,GAAG,iBAAiB,CAAC,CAAC,CAAC,GAAG,IAAI;KAChE,CAAC,CAAC;CACJ"}