@moyarich/console-core 0.1.0 → 0.2.0

package/README.md

@@ -4,6 +4,8 @@ A React console toolkit for **capturing and displaying runtime output**.
 
 Bring browser-style `console.*` messages, inspectable JavaScript values, and ANSI-formatted process output into your application. Console works well in code playgrounds, developer tools, embedded previews, and applications connected to remote runtimes.
 
+[Documentation and live examples](https://moyarich.github.io/console/)
+
 ## Features
 
 - **Structured messages:** Render familiar console levels and inspect JavaScript values.
@@ -20,7 +22,22 @@ Console handles presentation and message transport; your application remains in
 npm install @moyarich/console
 ```
 
-Requires React 18 or newer. The package includes TypeScript declarations and loads its core stylesheet automatically.
+Requires React 18 or newer. If your application does not already include React, install it too:
+
+```bash
+npm install react react-dom
+```
+
+The package includes TypeScript declarations and loads its core stylesheet automatically.
+
+### GitHub Packages setup
+
+For installations from GitHub Packages, configure the scope and authenticate with a GitHub personal access token that has `read:packages` access:
+
+```bash
+npm config set @moyarich:registry https://npm.pkg.github.com
+npm login --scope=@moyarich --registry=https://npm.pkg.github.com
+```
 
 ## Quick start
 
@@ -50,6 +67,7 @@ Use the console-compatible producer from event handlers or runtime callbacks to
 - [Console examples and guides](packages/console/examples/page.mdx)
 - [High-volume output accessibility](packages/console/examples/36-high-volume-accessibility/page.mdx)
 - [Virtualized output guide](packages/console/examples/38-virtualization/page.mdx)
+- [Console lifecycle callback contracts](docs/console-lifecycle.md)
 
 ## Packages and addons
 
@@ -70,6 +88,7 @@ Console is a family of independently installable packages. Start with `@moyarich
 | `@moyarich/console-addon-markdown`             | Render GitHub Flavored Markdown                             |
 | `@moyarich/console-addon-metadata`             | Display message metadata                                    |
 | `@moyarich/console-addon-navigation`           | Navigate between messages                                   |
+| `@moyarich/console-addon-persistence`          | Save output through configurable persistence adapters       |
 | `@moyarich/console-addon-process-state`        | Represent process execution state                           |
 | `@moyarich/console-addon-resizable`            | Resize the console frame                                    |
 | `@moyarich/console-addon-search`               | Search console output                                       |
@@ -82,3 +101,14 @@ Core console features work without optional addons. Each addon is installed sepa
 ## License
 
 MIT
+
+## Local development
+
+Run `npm run dev` to start the playground and Storybook together:
+
+- Playground: <http://localhost:5173/>
+- Storybook: <http://localhost:5173/storybook/>
+
+Both support hot reload and link to each other. Ctrl+C stops both servers. Storybook runs internally on port 6007; set `DEV_PORT` or `STORYBOOK_DEV_PORT` to change the ports.
+
+Use `npm run dev:playground` or `npm run storybook` to start an individual server. Run `npx playwright test -c playwright.dev.config.ts` to check navigation and live connections through the unified server.

package/dist/index.d.cts

@@ -0,0 +1,648 @@
+/** Version of the public addon-host contract. */
+export declare const CONSOLE_ADDON_API_VERSION = "1";
+/** Resource that can be released deterministically. */
+export interface ConsoleDisposable {
+    dispose(): void;
+}
+/** Cleanup value optionally returned from {@link ConsoleAddon.activate}. */
+export type ConsoleAddonCleanup = void | (() => void) | ConsoleDisposable;
+/**
+ * A console addon owns lifecycle only. Feature-specific behavior is registered
+ * through extension points and services on the addon host.
+ */
+export interface ConsoleAddon {
+    /**
+     * Stable, package-qualified identifier used for lifecycle management and
+     * duplicate detection. Prefer the npm package name, or
+     * `<package>:<feature>` when one package provides multiple addons.
+     */
+    readonly id: string;
+    /** Activates the addon against one scoped console host. */
+    activate(host: ConsoleAddonHost): ConsoleAddonCleanup;
+}
+/** Typed token identifying a multi-provider extension point. */
+/**
+ * Describes how multiple contributions to the same extension point compose.
+ *
+ * Contributions are always resolved in deterministic extension order:
+ * higher `priority` first, then registration order for equal priorities.
+ *
+ * - `"pipeline"`: every contribution runs sequentially. Each stage receives
+ *   the immutable state produced by preceding stages.
+ * - `"first-result"`: contributions are tried in order until one handles the
+ *   input and returns a result.
+ * - `"collect"`: all applicable contributions are accumulated in order.
+ * - `"all"`: every contribution must accept/pass the input. Hosts may
+ *   short-circuit once the result is known.
+ * - `"middleware"`: contributions wrap the next contribution/default
+ *   behavior, with the earliest resolved contribution forming the outer layer.
+ */
+export type ConsoleExtensionComposition = "pipeline" | "first-result" | "collect" | "all" | "middleware";
+/** Typed metadata token identifying one multi-provider extension contract. */
+export interface ConsoleExtensionPoint<T> {
+    /** Stable package-independent identifier used by the extension registry. */
+    readonly id: string;
+    /**
+     * Declares the host's composition semantics when multiple contributions are
+     * registered for this point.
+     */
+    readonly composition: ConsoleExtensionComposition;
+    /** Type-only marker for the contribution accepted by this point. */
+    readonly __consoleExtensionType?: T;
+}
+/** Ordering metadata for one extension contribution. */
+export interface ConsoleExtensionRegistrationOptions {
+    /** Optional identifier unique within this extension point. */
+    readonly id?: string;
+    /**
+     * Higher priorities are resolved before lower priorities.
+     * Equal priorities preserve registration order.
+     * @default 0
+     */
+    readonly priority?: number;
+}
+/**
+ * Registry for ordered, multi-provider console extensions.
+ *
+ * The registry owns ordering only. The host implements the behavior described
+ * by each extension point's `composition` metadata.
+ */
+export interface ConsoleExtensionRegistry {
+    /**
+     * Registers one contribution.
+     *
+     * Contributions with higher priorities resolve first. Equal priorities keep
+     * registration order. Disposing the returned handle removes the contribution.
+     */
+    register<T>(point: ConsoleExtensionPoint<T>, contribution: T, options?: ConsoleExtensionRegistrationOptions): ConsoleDisposable;
+    /**
+     * Returns contributions in effective execution/rendering order.
+     *
+     * The returned order is higher priority first and stable registration order
+     * for equal priorities.
+     */
+    getAll<T>(point: ConsoleExtensionPoint<T>): readonly T[];
+    /** Subscribes to extension registration and disposal changes. */
+    subscribe(listener: () => void): ConsoleDisposable;
+}
+/** Typed token identifying a single-provider service. */
+export interface ConsoleServiceToken<T> {
+    readonly id: string;
+    readonly __consoleServiceType?: T;
+}
+/** Registry for shared core/addon APIs and stateful services. */
+export interface ConsoleServiceRegistry {
+    has<T>(token: ConsoleServiceToken<T>): boolean;
+    get<T>(token: ConsoleServiceToken<T>): T | undefined;
+    require<T>(token: ConsoleServiceToken<T>): T;
+    provide<T>(token: ConsoleServiceToken<T>, service: T): ConsoleDisposable;
+    subscribe(listener: () => void): ConsoleDisposable;
+}
+/** Stable identifier for optional host functionality. */
+export interface ConsoleCapability {
+    readonly id: string;
+}
+/** Read-only capability discovery available to addons. */
+export interface ConsoleCapabilityRegistry {
+    has(capability: ConsoleCapability): boolean;
+    getAll(): readonly ConsoleCapability[];
+}
+/** Disposable collection owned by one addon activation. */
+export interface ConsoleDisposableScope extends ConsoleDisposable {
+    add<T extends ConsoleDisposable>(disposable: T): T;
+    defer(cleanup: () => void): ConsoleDisposable;
+}
+/** Public surface supplied to one addon activation. */
+export interface ConsoleAddonHost {
+    readonly version: string;
+    readonly extensions: ConsoleExtensionRegistry;
+    readonly services: ConsoleServiceRegistry;
+    readonly capabilities: ConsoleCapabilityRegistry;
+    readonly scope: ConsoleDisposableScope;
+}
+/** Options used to construct an addon manager. */
+export interface CreateConsoleAddonManagerOptions {
+    readonly version?: string;
+    readonly capabilities?: readonly ConsoleCapability[];
+}
+/** Loads addons and owns the registries shared by those addon activations. */
+export interface ConsoleAddonManager extends ConsoleDisposable {
+    readonly version: string;
+    readonly extensions: ConsoleExtensionRegistry;
+    readonly services: ConsoleServiceRegistry;
+    readonly capabilities: ConsoleCapabilityRegistry;
+    load(addon: ConsoleAddon): ConsoleDisposable;
+    unload(id: string): boolean;
+    has(id: string): boolean;
+}
+/**
+ * Creates a typed multi-provider extension-point token.
+ *
+ * @param id Stable identifier for the extension contract.
+ * @param composition How a host composes multiple registered contributions.
+ * @defaultValue composition `"collect"`
+ */
+export declare function createConsoleExtensionPoint<T>(id: string, composition?: ConsoleExtensionComposition): ConsoleExtensionPoint<T>;
+/** Creates an independent extension registry for advanced/headless hosts. */
+export declare function createConsoleExtensionRegistry(): ConsoleExtensionRegistry;
+/** Creates a typed single-provider service token. */
+export declare function createConsoleServiceToken<T>(id: string): ConsoleServiceToken<T>;
+/** Creates an independent service registry for advanced/headless hosts. */
+export declare function createConsoleServiceRegistry(): ConsoleServiceRegistry;
+/** Creates a stable capability identifier. */
+export declare function createConsoleCapability(id: string): ConsoleCapability;
+/** Creates an independent read-only capability registry. */
+export declare function createConsoleCapabilityRegistry(capabilities?: readonly ConsoleCapability[]): ConsoleCapabilityRegistry;
+/** Creates an idempotent disposable collection. */
+export declare function createConsoleDisposableScope(): ConsoleDisposableScope;
+/**
+ * Creates an addon manager suitable for UI or headless console hosts.
+ *
+ * Each loaded addon receives a scoped host. Registrations made through that
+ * host are automatically removed when the addon is unloaded.
+ */
+export declare function createConsoleAddonManager(options?: CreateConsoleAddonManagerOptions): ConsoleAddonManager;
+/** Structured console message method understood by console hosts. */
+export type ConsoleMethod = "log" | "debug" | "info" | "warn" | "error" | "assert" | "dir" | "table" | "count" | "timeEnd" | "trace" | "group" | "groupCollapsed";
+/** Rendering/data mode understood by console hosts. */
+export type ConsoleMode = "console" | "terminal";
+/** Structured message shared by hosts, transports, and addons. */
+export interface ConsoleMessageData {
+    id?: string;
+    method: ConsoleMethod;
+    data: unknown[];
+    depth: number;
+    timestamp?: number;
+    source?: string;
+    columns?: string[];
+    expandLevel?: number;
+    showNonenumerable?: boolean;
+}
+/** Context used to decide whether one structured console message is visible. */
+export interface ConsoleMessageFilterContext {
+    readonly message: ConsoleMessageData;
+    readonly index: number;
+    readonly messages: readonly ConsoleMessageData[];
+}
+/** Predicate used to decide whether a structured console message is visible. */
+export type ConsoleMessageFilter = (context: ConsoleMessageFilterContext) => boolean;
+export interface RunOutput {
+    messages: ConsoleMessageData[];
+    error?: string;
+}
+export interface DirOptions {
+    depth?: number | null;
+    showHidden?: boolean;
+}
+export type ConsoleEvent = {
+    type: "message";
+    message: ConsoleMessageData;
+} | {
+    type: "clear";
+};
+export interface ConsoleTransportEnvelope {
+    type: "CONSOLE_PANEL";
+    version: 1;
+    channel: string;
+    event: ConsoleEvent;
+}
+export type ConsoleOutputStream = "stdout" | "stderr";
+export type ConsoleProcessOutputMetadata = Readonly<Record<string, unknown>>;
+export interface ConsoleStdoutEntry {
+    id?: string;
+    data: string;
+    stream?: ConsoleOutputStream;
+    metadata?: ConsoleProcessOutputMetadata;
+}
+export interface ConsoleLink {
+    text: string;
+    start: number;
+    end: number;
+    target?: string;
+    title?: string;
+    action?: (context: ConsoleLinkActionContext) => void;
+}
+export interface ConsoleLinkProviderContext {
+    readonly text: string;
+    readonly mode: ConsoleMode;
+    readonly value?: unknown;
+    readonly propertyKey?: string;
+    readonly index?: number;
+    readonly id?: string;
+    readonly stream?: ConsoleOutputStream;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+export interface ConsoleLinkActionContext extends ConsoleLinkProviderContext {
+    readonly link: ConsoleLink;
+    readonly providerId?: string;
+}
+export interface ConsoleLinkProvider {
+    readonly id?: string;
+    provideLinks(context: ConsoleLinkProviderContext): readonly ConsoleLink[] | undefined | void;
+}
+export interface ConsoleProcessOutput {
+    readonly data: string;
+    readonly structuredValue?: unknown;
+    readonly links?: readonly ConsoleLink[];
+    readonly metadata: ConsoleProcessOutputMetadata;
+}
+export interface ConsoleProcessControlEvent {
+    readonly type: string;
+    readonly data?: Readonly<Record<string, unknown>>;
+}
+export interface ConsoleProcessControlOutput {
+    readonly data: string;
+    readonly metadata: ConsoleProcessOutputMetadata;
+}
+export interface ConsoleProcessControlParserContext {
+    readonly output: ConsoleProcessControlOutput;
+    readonly entry: ConsoleStdoutEntry | string;
+    readonly index: number;
+    readonly id?: string;
+    readonly stream?: ConsoleOutputStream;
+}
+export interface ConsoleProcessControlParserResult {
+    data?: string;
+    metadata?: Readonly<Record<string, unknown>>;
+    events?: readonly ConsoleProcessControlEvent[];
+    omit?: boolean;
+}
+export interface ConsoleProcessControlParser {
+    readonly id?: string;
+    parse(context: ConsoleProcessControlParserContext): ConsoleProcessControlParserResult | undefined | void;
+    reset?(): void;
+}
+export interface ConsoleProcessOutputProcessorContext {
+    readonly output: ConsoleProcessOutput;
+    readonly entry: ConsoleStdoutEntry | string;
+    readonly index: number;
+    readonly text: string;
+    readonly id?: string;
+    readonly stream?: ConsoleOutputStream;
+}
+export interface ConsoleProcessOutputProcessorResult {
+    data?: string;
+    structuredValue?: unknown;
+    links?: readonly ConsoleLink[];
+    metadata?: Readonly<Record<string, unknown>>;
+}
+export interface ConsoleProcessOutputProcessor {
+    readonly id?: string;
+    process(context: ConsoleProcessOutputProcessorContext): ConsoleProcessOutputProcessorResult | undefined | void;
+}
+export interface ConsoleResolvedProcessOutputEntry {
+    readonly entry: ConsoleStdoutEntry;
+    readonly output: ConsoleProcessOutput;
+}
+export type ConsoleProcessViewEntry = ConsoleResolvedProcessOutputEntry;
+export interface ConsoleStructuredOutputParserContext {
+    readonly text: string;
+    readonly entry: ConsoleStdoutEntry | string;
+    readonly index: number;
+    readonly id?: string;
+    readonly stream?: ConsoleOutputStream;
+    readonly metadata?: ConsoleProcessOutputMetadata;
+}
+export type ConsoleStructuredOutputParser = (context: ConsoleStructuredOutputParserContext) => unknown | undefined;
+export interface ConsoleStructuredDataSnapshot {
+    readonly mode: "console";
+    readonly all: readonly ConsoleMessageData[];
+    readonly visible: readonly ConsoleMessageData[];
+}
+export interface ConsoleProcessDataSnapshot {
+    readonly mode: "terminal";
+    readonly rawEntries: readonly (ConsoleStdoutEntry | string)[];
+    readonly all: readonly ConsoleProcessViewEntry[];
+    readonly visible: readonly ConsoleProcessViewEntry[];
+    readonly controlEvents?: readonly ConsoleProcessControlEvent[];
+}
+export type ConsoleDataSnapshot = ConsoleStructuredDataSnapshot | ConsoleProcessDataSnapshot;
+export interface ConsoleDataService {
+    getSnapshot(): ConsoleDataSnapshot;
+    subscribe(listener: () => void): ConsoleDisposable;
+}
+export interface ConsoleScrollOptions {
+    behavior?: ScrollBehavior;
+    block?: ScrollLogicalPosition;
+    inline?: ScrollLogicalPosition;
+}
+export interface ConsoleViewportService {
+    scrollToTop(): void;
+    scrollToBottom(): void;
+    scrollToMessage(id: string, options?: ConsoleScrollOptions): boolean;
+    isAtBottom(): boolean;
+    isAtTop(): boolean;
+    focus(): void;
+}
+export interface ConsoleActionContextBase {
+    readonly mode: ConsoleMode;
+    readonly hasMessages: boolean;
+}
+export interface ConsoleSurfaceActionContext extends ConsoleActionContextBase {
+    readonly kind: "console";
+}
+export interface ConsoleObjectActionContext extends ConsoleActionContextBase {
+    readonly kind: "object";
+    readonly value: object;
+}
+export interface ConsoleMessageActionContext extends ConsoleActionContextBase {
+    readonly kind: "message";
+    readonly message: ConsoleMessageData;
+    readonly index: number;
+    readonly messages: readonly ConsoleMessageData[];
+}
+export type ConsoleContextMenuActionContext = ConsoleSurfaceActionContext | ConsoleObjectActionContext | ConsoleMessageActionContext;
+export type ConsoleActionPredicate<TContext> = boolean | ((context: TContext) => boolean);
+export type ConsoleActionVariant = "default" | "danger";
+/**
+ * UI payloads are generic so the core addon SDK does not depend on React.
+ * React hosts specialize this type to ReactNode.
+ */
+export interface ConsoleAction<TContext, TUi = unknown> {
+    id: string;
+    label: TUi;
+    ariaLabel?: string;
+    icon?: TUi;
+    variant?: ConsoleActionVariant;
+    separatorBefore?: boolean;
+    visible?: ConsoleActionPredicate<TContext>;
+    disabled?: ConsoleActionPredicate<TContext>;
+    onSelect: (context: TContext) => void | Promise<void>;
+}
+export type ConsolePanelAction<TUi = unknown> = ConsoleAction<ConsoleSurfaceActionContext, TUi>;
+export type ConsoleContextMenuAction<TUi = unknown> = ConsoleAction<ConsoleContextMenuActionContext, TUi>;
+export type ConsoleMessageAction<TUi = unknown> = ConsoleAction<ConsoleMessageActionContext, TUi>;
+export interface ConsoleKeyboardShortcutContext {
+    readonly mode: ConsoleMode;
+    readonly hasMessages: boolean;
+    readonly isEmpty: boolean;
+}
+export interface ConsoleKeyboardShortcut {
+    readonly id: string;
+    readonly key: string;
+    readonly altKey?: boolean;
+    readonly ctrlKey?: boolean;
+    readonly metaKey?: boolean;
+    readonly shiftKey?: boolean;
+    readonly allowInEditable?: boolean;
+    readonly preventDefault?: boolean;
+    readonly stopPropagation?: boolean;
+    when?: (context: ConsoleKeyboardShortcutContext) => boolean;
+    onTrigger: (context: ConsoleKeyboardShortcutContext) => void | Promise<void>;
+}
+export type ConsolePanelElementPlacement = "header-start" | "header-end" | "before-output" | "after-output" | "footer";
+export interface ConsolePanelElementContext {
+    readonly mode: ConsoleMode;
+    readonly hasMessages: boolean;
+    readonly isEmpty: boolean;
+}
+export interface ConsolePanelElement<TUi = unknown> {
+    readonly id: string;
+    readonly placement: ConsolePanelElementPlacement;
+    render: (context: ConsolePanelElementContext) => TUi | undefined;
+}
+export type ConsoleMessageDecorationPlacement = "gutter" | "before" | "after" | "badge" | "overlay";
+export interface ConsoleMessageDecorationContext {
+    readonly message: ConsoleMessageData;
+    readonly index: number;
+    readonly messages: readonly ConsoleMessageData[];
+    readonly placement: ConsoleMessageDecorationPlacement;
+}
+export interface ConsoleMessageDecoration<TUi = unknown> {
+    readonly id: string;
+    readonly placement: ConsoleMessageDecorationPlacement;
+    match?: (context: ConsoleMessageDecorationContext) => boolean;
+    render: (context: ConsoleMessageDecorationContext) => TUi | undefined;
+}
+export type ConsoleOutputRendererContext<TUi = unknown> = {
+    readonly mode: "console";
+    readonly messages: readonly ConsoleMessageData[];
+    readonly renderDefault: () => TUi;
+} | {
+    readonly mode: "terminal";
+    readonly entries: readonly (ConsoleStdoutEntry | string)[];
+    readonly renderDefault: () => TUi;
+};
+export interface ConsoleOutputRenderer<TUi = unknown> {
+    mode?: ConsoleMode;
+    match?: (context: ConsoleOutputRendererContext<TUi>) => boolean;
+    render: (context: ConsoleOutputRendererContext<TUi>) => TUi | undefined;
+}
+export type ConsoleOutputEntryDecoratorContext<TUi = unknown> = {
+    readonly mode: "console";
+    readonly message: ConsoleMessageData;
+    readonly index: number;
+    readonly id?: string;
+    readonly renderDefault: () => TUi;
+} | {
+    readonly mode: "terminal";
+    readonly entry: ConsoleStdoutEntry;
+    readonly index: number;
+    readonly id?: string;
+    readonly renderDefault: () => TUi;
+};
+/** Wraps one fully rendered output entry, preserving its interactive children. */
+export interface ConsoleOutputEntryDecorator<TUi = unknown> {
+    render(context: ConsoleOutputEntryDecoratorContext<TUi>): TUi | undefined;
+}
+export interface ConsoleFrameDecoratorContext<TUi = unknown> {
+    readonly mode: ConsoleMode;
+    readonly renderDefault: () => TUi;
+}
+export interface ConsoleFrameDecorator<TUi = unknown> {
+    render: (context: ConsoleFrameDecoratorContext<TUi>) => TUi | undefined;
+}
+export interface ConsoleEmptyStateRendererContext<TUi = unknown> {
+    readonly mode: ConsoleMode;
+    readonly hasMessages: boolean;
+    readonly message: string;
+    readonly renderDefault: () => TUi;
+}
+export interface ConsoleEmptyStateRenderer<TUi = unknown> {
+    readonly mode?: ConsoleMode;
+    match?: (context: ConsoleEmptyStateRendererContext<TUi>) => boolean;
+    render: (context: ConsoleEmptyStateRendererContext<TUi>) => TUi | undefined;
+}
+/** A presentation-only match range within the rendered text (UTF-16 offsets). */
+export interface ConsoleTextHighlightRange {
+    readonly start: number;
+    readonly end: number;
+    readonly active?: boolean;
+}
+/** Optional, reactive addon-provided text highlights. Does not change source output. */
+export interface ConsoleTextHighlightProvider {
+    subscribe(listener: () => void): () => void;
+    getSnapshot(): unknown;
+    getRanges(text: string, context: ConsoleLinkProviderContext): readonly ConsoleTextHighlightRange[];
+}
+export interface ConsoleMessageTextProviderContext {
+    readonly message: ConsoleMessageData;
+    readonly index: number;
+    readonly messages: readonly ConsoleMessageData[];
+}
+export interface ConsoleMessageTextProvider {
+    readonly id?: string;
+    provideText: (context: ConsoleMessageTextProviderContext) => string | readonly string[] | undefined;
+}
+export interface ConsoleMessageRendererContext<TUi = unknown> {
+    readonly message: ConsoleMessageData;
+    readonly index: number;
+    readonly messages: readonly ConsoleMessageData[];
+    readonly renderDefault: () => TUi;
+}
+export interface ConsoleMessageRenderer<TUi = unknown> {
+    readonly method?: ConsoleMethod;
+    match?: (context: ConsoleMessageRendererContext<TUi>) => boolean;
+    render: (context: ConsoleMessageRendererContext<TUi>) => TUi | undefined;
+}
+export interface ConsoleValueRendererContext<TUi = unknown> {
+    readonly value: unknown;
+    readonly propertyKey?: string;
+    readonly depth: number;
+    readonly type: string;
+    readonly renderDefault: () => TUi;
+}
+export interface ConsoleValueRenderer<TUi = unknown> {
+    readonly type?: string;
+    match?: (context: ConsoleValueRendererContext<TUi>) => boolean;
+    render: (context: ConsoleValueRendererContext<TUi>) => TUi | undefined;
+}
+/** Built-in capabilities understood by the standard console host. */
+export declare const consoleCapabilities: Readonly<{
+    react: ConsoleCapability;
+    dom: ConsoleCapability;
+    structuredMessages: ConsoleCapability;
+    processOutput: ConsoleCapability;
+}>;
+/** Shared service tokens used by console hosts and addons. */
+export declare const consoleServices: Readonly<{
+    viewport: ConsoleServiceToken<ConsoleViewportService>;
+    data: ConsoleServiceToken<ConsoleDataService>;
+}>;
+/** Shared extension-point tokens used by console hosts and addons. */
+/**
+ * Built-in extension contracts supported by Console hosts.
+ *
+ * Each point declares its composition strategy so addon authors can determine
+ * whether registration order affects transformation, matching, rendering, or
+ * collection behavior directly from IDE hover information.
+ */
+export declare const consoleExtensionPoints: Readonly<{
+    /**
+     * Parses stateful controls from raw process chunks before CR/newline
+     * normalization.
+     *
+     * @composition pipeline Each parser receives the output of preceding parsers.
+     */
+    processControlParser: ConsoleExtensionPoint<ConsoleProcessControlParser>;
+    /**
+     * Transforms/enriches normalized process output before structured parsing.
+     *
+     * @composition pipeline Each processor receives accumulated prior output.
+     */
+    processOutputProcessor: ConsoleExtensionPoint<ConsoleProcessOutputProcessor>;
+    /**
+     * Promotes process text to structured values.
+     *
+     * @composition first-result The first parser returning a value wins.
+     */
+    structuredOutputParser: ConsoleExtensionPoint<ConsoleStructuredOutputParser>;
+    /**
+     * Discovers application-specific interactive link ranges.
+     *
+     * @composition collect All providers contribute; earlier overlapping ranges win.
+     */
+    linkProvider: ConsoleExtensionPoint<ConsoleLinkProvider>;
+    /**
+     * Replaces the complete output surface.
+     *
+     * @composition first-result The first renderer returning a value wins.
+     */
+    outputRenderer: ConsoleExtensionPoint<ConsoleOutputRenderer<unknown>>;
+    /**
+     * Structurally wraps the complete Console frame.
+     *
+     * @composition middleware Earlier contributions become outer wrappers.
+     */
+    outputEntryDecorator: ConsoleExtensionPoint<ConsoleOutputEntryDecorator<unknown>>;
+    frameDecorator: ConsoleExtensionPoint<ConsoleFrameDecorator<unknown>>;
+    /**
+     * Customizes the empty-output surface without replacing normal output.
+     *
+     * @composition first-result The first matching renderer returning a value wins.
+     */
+    emptyStateRenderer: ConsoleExtensionPoint<ConsoleEmptyStateRenderer<unknown>>;
+    /**
+     * Adds persistent addon UI to generic panel placements.
+     *
+     * @composition collect All matching elements render in resolved order.
+     */
+    panelElement: ConsoleExtensionPoint<ConsolePanelElement<unknown>>;
+    /**
+     * Contributes structured-message visibility predicates.
+     *
+     * @composition all A message must pass every registered filter.
+     */
+    messageFilter: ConsoleExtensionPoint<ConsoleMessageFilter>;
+    /**
+     * Replaces one structured-message row.
+     *
+     * @composition first-result The first matching renderer returning a value wins.
+     */
+    messageRenderer: ConsoleExtensionPoint<ConsoleMessageRenderer<unknown>>;
+    /**
+     * Adds UI around a structured message without replacing its renderer.
+     *
+     * @composition collect All matching decorations render in resolved order.
+     */
+    messageDecoration: ConsoleExtensionPoint<ConsoleMessageDecoration<unknown>>;
+    /**
+     * Contributes logical searchable/plain text for structured messages.
+     *
+     * @composition collect Text from all providers is accumulated in resolved order.
+     */
+    /** A single presentation-only provider for inline text highlighting. */
+    textHighlightProvider: ConsoleExtensionPoint<ConsoleTextHighlightProvider>;
+    messageTextProvider: ConsoleExtensionPoint<ConsoleMessageTextProvider>;
+    /**
+     * Replaces rendering for an individual structured value.
+     *
+     * @composition first-result The first matching renderer returning a value wins.
+     */
+    valueRenderer: ConsoleExtensionPoint<ConsoleValueRenderer<unknown>>;
+    /**
+     * Contributes keyboard commands scoped to the focused Console.
+     *
+     * @composition first-result The first matching enabled shortcut handles the event.
+     */
+    keyboardShortcut: ConsoleExtensionPoint<ConsoleKeyboardShortcut>;
+    /**
+     * Adds Console-level actions.
+     *
+     * @composition collect All visible actions are accumulated in resolved order.
+     */
+    panelAction: ConsoleExtensionPoint<ConsolePanelAction<unknown>>;
+    /**
+     * Adds context-menu actions for Console, object, or message targets.
+     *
+     * @composition collect All visible actions are accumulated in resolved order.
+     */
+    contextMenuAction: ConsoleExtensionPoint<ConsoleContextMenuAction<unknown>>;
+    /**
+     * Adds actions scoped to one structured message.
+     *
+     * @composition collect All visible actions are accumulated in resolved order.
+     */
+    messageAction: ConsoleExtensionPoint<ConsoleMessageAction<unknown>>;
+}>;
+/** Converts rich JavaScript values into a stable JSON-safe representation. */
+export declare function serializeConsoleValue(value: unknown, options?: {
+    maxDepth?: number;
+    maxEntries?: number;
+}): unknown;
+/** Normalizes a value for readable object-copy output. */
+export declare function normalizeConsoleValue(value: unknown, seen?: WeakSet<object>): unknown;
+/** Formats an inspectable object as readable JSON. */
+export declare function formatConsoleObjectForCopy(value: object): string;
+/** Clipboard helper shared by browser-hosted addons and the React host. */
+export declare function writeClipboardText(value: string): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moyarich/console-core",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Core addon SDK and runtime contracts for @moyarich/console hosts and addons.",
   "license": "MIT",
   "type": "module",
@@ -9,9 +9,14 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
     }
   },
   "files": [
@@ -21,7 +26,7 @@
     "registry": "https://npm.pkg.github.com"
   },
   "scripts": {
-    "build": "vite build && tsc -p tsconfig.build.json",
+    "build": "vite build && tsc -p tsconfig.build.json && node ../../scripts/prepare-cjs-types.mjs",
     "typecheck": "tsc --noEmit",
     "prepack": "node -e \"require('node:fs').copyFileSync('../../README.md', 'README.md')\"",
     "postpack": "node -e \"require('node:fs').rmSync('README.md', { force: true })\""
@@ -46,5 +51,10 @@
     "extensions",
     "developer-tools",
     "typescript"
-  ]
+  ],
+  "publisher": "moyarich",
+  "author": "Moya Richards",
+  "engines": {
+    "node": ">=24"
+  }
 }