@makaio/contracts 1.0.0-dev-1779051654000

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

@@ -0,0 +1,118 @@
+import type { MakaioBusLike } from '@makaio/framework/core';
+/**
+ * Context passed to bootstrap discovery and export operations.
+ * @typeParam TBus - Host bus shape supplied by the runtime.
+ */
+export interface BootstrapDiscoverContext<TBus extends MakaioBusLike = MakaioBusLike> {
+    /** Bus instance for querying the runtime. */
+    bus: TBus;
+    /** Active project identifier. */
+    projectId: string;
+    /** Absolute path to the project repository. */
+    repoPath: string;
+}
+/** Context for export operations - identical to discover context. */
+export type BootstrapExportContext<TBus extends MakaioBusLike = MakaioBusLike> = BootstrapDiscoverContext<TBus>;
+/** Context for import operations - extends discover context with the bootstrap folder path. */
+export interface BootstrapImportContext<TBus extends MakaioBusLike = MakaioBusLike> extends BootstrapDiscoverContext<TBus> {
+    /** Absolute path to the `.makaio/bootstrap/` folder being imported from. */
+    bootstrapFolderPath: string;
+}
+/** A single exportable or importable bootstrap asset. */
+export interface BootstrapAsset {
+    /** Identifier of the extension that owns this asset. */
+    extensionId: string;
+    /** Logical asset type (e.g. `'session'`, `'config'`). */
+    type: string;
+    /** Human-readable asset name. */
+    name: string;
+    /** Filename within the bootstrap folder. */
+    filename: string;
+    /** Whether the asset already exists in the target environment. */
+    exists?: boolean;
+    /** Identifier of an existing asset that would be replaced by import. */
+    existingId?: string;
+}
+/** Stable key type for bootstrap asset lookups. */
+export type BootstrapAssetKey = string;
+/**
+ * Build a stable key for a bootstrap asset.
+ * @param asset - The asset to key.
+ * @returns Stable asset key for UI state and list rendering.
+ */
+export declare function getBootstrapAssetKey(asset: BootstrapAsset): BootstrapAssetKey;
+/** Result of a single bootstrap import operation. */
+export interface BootstrapImportResult {
+    /** Whether the import succeeded. */
+    success: boolean;
+    /** Action taken during import. */
+    action: 'created' | 'replaced' | 'skipped';
+    /** Error message when `success` is `false`. */
+    error?: string;
+}
+/** User-selected action for a conflicting bootstrap asset. */
+export interface BootstrapChoice {
+    /** The conflicting asset. */
+    asset: BootstrapAsset;
+    /** Chosen resolution action. */
+    action: 'replace' | 'skip';
+}
+/** Result of a completed bootstrap operation (import or export). */
+export interface BootstrapResult {
+    /** The asset that was processed. */
+    asset: BootstrapAsset;
+    /** Action taken. */
+    action: 'replaced' | 'skipped' | 'created';
+    /** Error message when the operation failed. */
+    error?: string;
+}
+/** Result of a bootstrap export operation. */
+export interface BootstrapExportResult {
+    /** The asset that was exported. */
+    asset: BootstrapAsset;
+    /** Absolute path to the file that was written. */
+    filePath: string;
+    /** Error message when the export failed. */
+    error?: string;
+}
+/**
+ * Bootstrap capability contributed by an extension.
+ *
+ * Participates in project export (`discoverExportable` + `export`) and
+ * project import (`listImportable` + `import`) workflows.
+ * @typeParam TBus - Host bus shape supplied by the runtime.
+ */
+export interface ExtensionBootstrap<TBus extends MakaioBusLike = MakaioBusLike> {
+    /** Subfolder name within `.makaio/bootstrap/` for this extension's assets. */
+    folder: string;
+    /**
+     * List assets that can be imported from the bootstrap folder.
+     * @param ctx - Import context with bus, project, and bootstrap folder path.
+     * @param files - Files present in the bootstrap folder.
+     * @returns Assets available for import.
+     */
+    listImportable: (ctx: BootstrapImportContext<TBus>, files: string[]) => Promise<BootstrapAsset[]>;
+    /**
+     * Discover assets available for export from the current project.
+     * @param ctx - Discovery context with bus and project info.
+     * @returns Assets that can be exported.
+     */
+    discoverExportable: (ctx: BootstrapDiscoverContext<TBus>) => Promise<BootstrapAsset[]>;
+    /**
+     * Export a single asset and return its serialized content.
+     * @param ctx - Export context with bus and project info.
+     * @param asset - The asset to export.
+     * @returns Serialized content string written to the bootstrap folder.
+     */
+    export: (ctx: BootstrapExportContext<TBus>, asset: BootstrapAsset) => Promise<string>;
+    /**
+     * Import a single asset from its serialized content.
+     * @param ctx - Import context with bus, project, and bootstrap folder path.
+     * @param asset - The asset being imported.
+     * @param content - Serialized content string from the bootstrap folder.
+     * @param action - User-selected conflict resolution action.
+     * @returns Result of the import operation.
+     */
+    import: (ctx: BootstrapImportContext<TBus>, asset: BootstrapAsset, content: string, action: 'replace' | 'skip') => Promise<BootstrapImportResult>;
+}
+//# sourceMappingURL=bootstrap-types.d.ts.map

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

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

package/dist/extension/contributions/hash-trigger-types.d.ts

@@ -0,0 +1,106 @@
+import type { MakaioBusLike } from '@makaio/framework/core';
+/** Pipeline stage a hash trigger participates in. */
+export type HashTriggerStage = 'gather' | 'transform' | 'action';
+/** Single suggestion entry returned by a hash trigger's suggest call. */
+export interface HashSuggestion {
+    /** Display label shown in the completion UI. */
+    label: string;
+    /** Human-readable explanation of the suggestion. */
+    description: string;
+    /** Whether this suggestion is a leaf (directly usable) or a group (opens sub-list). */
+    kind: 'leaf' | 'group';
+    /** Text inserted into the input when the suggestion is accepted. */
+    insertText: string;
+    /** Underlying value passed to execute when the suggestion is used. */
+    value: string;
+    /** Optional icon identifier for the suggestion entry. */
+    icon?: string;
+    /** Pipeline stage override for this particular suggestion. */
+    stage?: HashTriggerStage;
+}
+/** A single entry gathered by a gather-stage hash trigger. */
+export interface GatheredEntry {
+    /** Gathered content string. */
+    content: string;
+    /** Prefix token that matched this entry. */
+    prefix: string;
+    /** Argument portion of the matched hash value. */
+    argument: string;
+    /** Optional arbitrary metadata from the gatherer. */
+    metadata?: Record<string, unknown>;
+}
+/** Snapshot of all entries gathered by gather-stage triggers in this pipeline run. */
+export interface GatheredContext {
+    /** Immutable map of prefix → entry. */
+    entries: ReadonlyMap<string, GatheredEntry>;
+}
+/**
+ * Context passed to a hash trigger's suggest and execute methods.
+ * @typeParam TBus - Host bus shape supplied by the runtime.
+ */
+export interface HashTriggerContext<TBus extends MakaioBusLike = MakaioBusLike> {
+    /** Active session identifier, if any. */
+    sessionId?: string;
+    /** Active project identifier, if any. */
+    projectId?: string;
+    /** Current message text. */
+    message?: string;
+    /** Bus instance for trigger operations. */
+    bus: TBus;
+    /** Optional abort signal for cancellable operations. */
+    signal?: AbortSignal;
+    /** Entries gathered by earlier gather-stage triggers. */
+    gathered?: GatheredContext;
+}
+/** Static descriptor for a registered hash trigger. */
+export interface HashTriggerMetadata {
+    /** Prefix token this trigger responds to (e.g. `'@'`, `'#'`). */
+    prefix: string;
+    /** Human-readable explanation of what this trigger does. */
+    description: string;
+    /** Semantic version of this trigger. */
+    version: string;
+    /** Pipeline stage this trigger participates in. */
+    stage?: HashTriggerStage;
+    /** Names of triggers that must run before this one. */
+    runAfter?: string[];
+}
+/** Return value from a hash trigger's suggest call. */
+export interface HashTriggerSuggestResult {
+    /** Suggested completions. */
+    suggestions: HashSuggestion[];
+    /** Optional metadata about the result set. */
+    metadata?: {
+        /** Whether the result set was truncated due to size limits. */
+        truncated?: boolean;
+    };
+}
+/**
+ * A registered hash trigger that can suggest completions and execute values.
+ *
+ * Implement this interface and return instances from
+ * `MakaioExtension.triggers.createTriggers` so the runtime registers them
+ * with the HashTriggerService.
+ * @typeParam TBus - Host bus shape supplied by the runtime.
+ */
+export interface HashTrigger<TBus extends MakaioBusLike = MakaioBusLike> {
+    /** Static descriptor used for registration and pipeline ordering. */
+    metadata: HashTriggerMetadata;
+    /**
+     * Return completion suggestions for the current query.
+     * @param query - Text typed after the prefix token.
+     * @param context - Runtime context for this suggestion request.
+     * @returns Suggestion list with optional pagination metadata.
+     */
+    suggest(query: string, context: HashTriggerContext<TBus>): Promise<HashTriggerSuggestResult>;
+    /**
+     * Execute the selected value (optional).
+     *
+     * Called when the user accepts a suggestion whose `kind` is `'leaf'`.
+     * @param value - The accepted suggestion's `value` field.
+     * @param context - Runtime context for this execution.
+     * @returns Resolved content string inserted into the message.
+     */
+    execute?(value: string, context: HashTriggerContext<TBus>): Promise<string>;
+}
+//# sourceMappingURL=hash-trigger-types.d.ts.map

package/dist/extension/contributions/hash-trigger-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash-trigger-types.d.ts","sourceRoot":"","sources":["../../../src/extension/contributions/hash-trigger-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,qDAAqD;AACrD,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,CAAC;AAEjE,yEAAyE;AACzE,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IACpB,uFAAuF;IACvF,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB,oEAAoE;IACpE,UAAU,EAAE,MAAM,CAAC;IACnB,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,KAAK,CAAC,EAAE,gBAAgB,CAAC;CAC1B;AAED,8DAA8D;AAC9D,MAAM,WAAW,aAAa;IAC5B,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,sFAAsF;AACtF,MAAM,WAAW,eAAe;IAC9B,uCAAuC;IACvC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;CAC7C;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB,CAAC,IAAI,SAAS,aAAa,GAAG,aAAa;IAC5E,yCAAyC;IACzC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yCAAyC;IACzC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4BAA4B;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,GAAG,EAAE,IAAI,CAAC;IACV,wDAAwD;IACxD,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,yDAAyD;IACzD,QAAQ,CAAC,EAAE,eAAe,CAAC;CAC5B;AAED,uDAAuD;AACvD,MAAM,WAAW,mBAAmB;IAClC,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,WAAW,EAAE,MAAM,CAAC;IACpB,wCAAwC;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,uDAAuD;AACvD,MAAM,WAAW,wBAAwB;IACvC,6BAA6B;IAC7B,WAAW,EAAE,cAAc,EAAE,CAAC;IAC9B,8CAA8C;IAC9C,QAAQ,CAAC,EAAE;QACT,+DAA+D;QAC/D,SAAS,CAAC,EAAE,OAAO,CAAC;KACrB,CAAC;CACH;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW,CAAC,IAAI,SAAS,aAAa,GAAG,aAAa;IACrE,qEAAqE;IACrE,QAAQ,EAAE,mBAAmB,CAAC;IAC9B;;;;;OAKG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAAC;IAC7F;;;;;;;OAOG;IACH,OAAO,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC7E"}

package/dist/extension/contributions/index.d.ts

@@ -0,0 +1,11 @@
+export type { HashTrigger, HashTriggerContext, HashTriggerMetadata, HashTriggerSuggestResult, HashTriggerStage, HashSuggestion, GatheredEntry, GatheredContext, } from './hash-trigger-types.js';
+export type { ExtensionBootstrap, BootstrapDiscoverContext, BootstrapExportContext, BootstrapImportContext, BootstrapAsset, BootstrapAssetKey, BootstrapImportResult, BootstrapChoice, BootstrapResult, BootstrapExportResult, } from './bootstrap-types.js';
+export { getBootstrapAssetKey } from './bootstrap-types.js';
+export type { SessionEventActionContext, SessionEventActionOptions, SessionEventActionDeclaration, CreateSessionEventActionResult, EntrypointConfig, EventFilter, MessageEventFilter, StructuralEventFilter, MessageRole, WhenContext, PickerOpenContext, PickerConfig, SelectionChangeContext, SelectionFeedback, ExecuteContext, ExecuteResult, ActionShortcut, ActionShortcutModifiers, ActionCategory, ActionCategoryMap, } from './session-event-action-types.js';
+export type { TileDeclaration, TileProps, TileRenderers, TileCapabilities, TileIconLoader } from './tile-types.js';
+export type { WidgetDeclaration, WidgetDefinition, WidgetProps, WidgetRenderers, WidgetSize } from './widget-types.js';
+export type { PageDeclaration, PageComponentProps, PageMode, SlotDeclaration, SlotContentDeclaration, SlotPlacementDeclaration, SlotId, WidgetSize as PageWidgetSize, } from './page-types.js';
+export type { ToolCallFormatterDeclaration, PluginFormattedToolCallOutput, PluginTransformedContent, PluginTransformedContentType, PluginToolCallFormatterInput, } from './tool-formatter-types.js';
+export type { MakaioWebUiRoute, MakaioWebUiLoader, MakaioWebUiAction, MakaioWebUiActions, MakaioWebUiComponentProps, PromisifiedActions, LoaderContext, ExtensionConfigComponentProps, ExtensionFieldTypeLoader, ExtensionConfigComponentLoader, } from './web-ui-types.js';
+export type { UiContextDimension, UiContextSnapshot, UiContextValueMap, UiNavigationLevel, UiNavigationLevelMap, UiRuntimeNavigationLevel, UiScope, UiScopeMap, } from './ui-context-types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/extension/contributions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/extension/contributions/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,WAAW,EACX,kBAAkB,EAClB,mBAAmB,EACnB,wBAAwB,EACxB,gBAAgB,EAChB,cAAc,EACd,aAAa,EACb,eAAe,GAChB,MAAM,yBAAyB,CAAC;AAEjC,YAAY,EACV,kBAAkB,EAClB,wBAAwB,EACxB,sBAAsB,EACtB,sBAAsB,EACtB,cAAc,EACd,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,EACf,eAAe,EACf,qBAAqB,GACtB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAE5D,YAAY,EACV,yBAAyB,EACzB,yBAAyB,EACzB,6BAA6B,EAC7B,8BAA8B,EAC9B,gBAAgB,EAChB,WAAW,EACX,kBAAkB,EAClB,qBAAqB,EACrB,WAAW,EACX,WAAW,EACX,iBAAiB,EACjB,YAAY,EACZ,sBAAsB,EACtB,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,cAAc,EACd,uBAAuB,EACvB,cAAc,EACd,iBAAiB,GAClB,MAAM,iCAAiC,CAAC;AAEzC,YAAY,EAAE,eAAe,EAAE,SAAS,EAAE,aAAa,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEnH,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,WAAW,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEvH,YAAY,EACV,eAAe,EACf,kBAAkB,EAClB,QAAQ,EACR,eAAe,EACf,sBAAsB,EACtB,wBAAwB,EACxB,MAAM,EACN,UAAU,IAAI,cAAc,GAC7B,MAAM,iBAAiB,CAAC;AAEzB,YAAY,EACV,4BAA4B,EAC5B,6BAA6B,EAC7B,wBAAwB,EACxB,4BAA4B,EAC5B,4BAA4B,GAC7B,MAAM,2BAA2B,CAAC;AAEnC,YAAY,EACV,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,yBAAyB,EACzB,kBAAkB,EAClB,aAAa,EACb,6BAA6B,EAC7B,wBAAwB,EACxB,8BAA8B,GAC/B,MAAM,mBAAmB,CAAC;AAE3B,YAAY,EACV,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,oBAAoB,EACpB,wBAAwB,EACxB,OAAO,EACP,UAAU,GACX,MAAM,uBAAuB,CAAC"}

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

@@ -0,0 +1,168 @@
+import type { ComponentType } from 'react';
+import type { UiNavigationLevel, UiScope } from './ui-context-types.js';
+/**
+ * Widget size values used for slot declarations in page layouts.
+ */
+export type WidgetSize = 'small' | 'medium' | 'large' | 'full-width';
+/**
+ * Normalized slot identifiers for page layout regions.
+ */
+export type SlotId = 'main' | 'sidebar-left' | 'sidebar-right' | 'detail-panel' | 'bottom-panel' | 'widget-zone';
+/**
+ * Page mode controlling sidebar navigation behavior.
+ *
+ * - `'switch'`: Takes over the workspace; shown in the sidebar "Navigate" section
+ * - `'peek'`: Small overlay that preserves existing state
+ * - `'cover'`: Full-viewport overlay that preserves existing state
+ */
+export type PageMode = 'switch' | 'peek' | 'cover';
+/** Props passed to all page components. */
+export interface PageComponentProps {
+    /** Optional CSS class name for the page container. */
+    className?: string;
+    /** Current internal route within the page. */
+    internalRoute?: string | null;
+    /**
+     * Callback for internal navigation within the page.
+     * @param route - The new internal route path.
+     */
+    onNavigate?: (route: string) => void;
+}
+/** Slot definition for package declarations (fully serializable). */
+export interface SlotDeclaration {
+    /** Slot identifier. */
+    id: SlotId;
+    /** Human-readable slot name. */
+    name: string;
+    /** Sizes accepted by this slot. */
+    acceptsSizes: WidgetSize[];
+    /** Minimum column width in pixels. */
+    minColumnWidth: number;
+    /** Maximum number of columns. */
+    maxColumns: number;
+    /** Whether the slot can be collapsed. */
+    collapsible?: boolean;
+    /** Whether the slot starts collapsed. */
+    defaultCollapsed?: boolean;
+}
+/** Content reference for a slot placement (view or widget). */
+export type SlotContentDeclaration = {
+    type: 'view';
+    viewId: string;
+    props?: Record<string, unknown>;
+} | {
+    type: 'widget';
+    widgetId: string;
+    config?: Record<string, unknown>;
+};
+/** Placement declaration with a mandatory flag and optional position. */
+export interface SlotPlacementDeclaration {
+    /**
+     * Stable unique identifier for this placement.
+     *
+     * Used as a React key and for layout persistence.
+     */
+    instanceId: string;
+    /** Content reference for this placement. */
+    content: SlotContentDeclaration;
+    /** Whether this placement is mandatory (cannot be removed by the user). */
+    mandatory: boolean;
+    /** Optional grid position. */
+    position?: {
+        col: number;
+        row: number;
+    };
+}
+/**
+ * Page declaration for packages.
+ *
+ * Fully serializable — lazy-loads any custom components. To also register the
+ * page in sidebar navigation (`PageDefinitionRegistry`), provide `mode`,
+ * `level`, and `component`. The package loader will bridge this declaration to
+ * a `PageDefinition` entry automatically.
+ * @example
+ * ```typescript
+ * // Minimal page (slot-layout system only, no sidebar entry):
+ * { id: 'my-page', name: 'My Page', scope: 'any', slots: [], defaultContent: {} }
+ *
+ * // Page with sidebar navigation entry:
+ * {
+ *   id: 'my-page',
+ *   name: 'My Page',
+ *   scope: 'any',
+ *   mode: 'switch',
+ *   level: 'any',
+ *   component: () => import('./MyPage.js'),
+ *   slots: [],
+ *   defaultContent: {},
+ * }
+ * ```
+ */
+export interface PageDeclaration {
+    /**
+     * Unique page identifier.
+     *
+     * Will be namespaced to `'<package-name>:<page-id>'` by the loader.
+     */
+    id: string;
+    /** Human-readable name. */
+    name: string;
+    /** Optional description shown in page listings. */
+    description?: string;
+    /**
+     * Route path relative to the package mount point.
+     * @example `'dashboard'` becomes `/extensions/my-package/dashboard`
+     */
+    route?: string;
+    /** UI scope for this page context. */
+    scope: UiScope;
+    /** Slot definitions for this page's layout. */
+    slots: SlotDeclaration[];
+    /** Default content per slot. */
+    defaultContent: Partial<Record<SlotId, SlotPlacementDeclaration[]>>;
+    /** Optional page-level icon (lazy-loaded). */
+    icon?: () => Promise<{
+        default: ComponentType<{
+            size?: number;
+        }>;
+    }>;
+    /** Optional page-level layout constraints. */
+    layout?: {
+        /** Minimum page width in pixels. */
+        minWidth?: number;
+    };
+    /**
+     * Navigation mode for sidebar registration.
+     *
+     * When provided alongside `level` and `component`, the package loader
+     * registers this page in the sidebar navigation (`PageDefinitionRegistry`).
+     * Omit to register in the slot-layout system only (`pageRegistry`).
+     */
+    mode?: PageMode;
+    /**
+     * Navigation level for sidebar registration.
+     *
+     * Required when `mode` is provided.
+     */
+    level?: UiNavigationLevel;
+    /**
+     * Lazy-loaded page component for sidebar navigation.
+     *
+     * Required when `mode` is provided. Must return a module with a default
+     * export that accepts {@link PageComponentProps}.
+     * @example
+     * ```typescript
+     * () => import('./MyPage.js').then(m => ({ default: m.MyPage }))
+     * ```
+     */
+    component?: () => Promise<{
+        default: ComponentType<PageComponentProps>;
+    }>;
+    /**
+     * Display order in sidebar (lower = first).
+     *
+     * Only used when `mode` is provided. Defaults to `50` when omitted.
+     */
+    order?: number;
+}
+//# sourceMappingURL=page-types.d.ts.map

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

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