dsh-quick-actions 0.1.0-rc.3

package/lib/types/client/modal.d.ts

@@ -0,0 +1,55 @@
+import type { KeyboardEvent as ReactKeyboardEvent, MutableRefObject } from 'react';
+/** What {@link useModalKeys} hands a panel. */
+export interface ModalKeys<T extends HTMLElement> {
+    /** Put on the panel element itself; the Tab boundary is computed from its subtree. */
+    readonly panelRef: MutableRefObject<T | null>;
+    /** Put on the same element; handles Escape and the Tab boundary. */
+    readonly onKeyDown: (event: ReactKeyboardEvent<T>) => void;
+}
+/**
+ * Escape cancels, and Tab stays inside.
+ *
+ * The focusable set is recomputed on every keystroke rather than cached: a
+ * management panel grows a form, a form's Save button goes inert while a write
+ * is in flight, and a stale boundary would trap focus on a control that is no
+ * longer there.
+ */
+export declare function useModalKeys<T extends HTMLElement>(onCancel: () => void): ModalKeys<T>;
+/**
+ * Return focus to whatever opened this panel, when it closes (spec 8.4).
+ *
+ * The opener is captured in a layout effect, so it must be declared *before* any
+ * effect that moves focus into the panel: effects run in declaration order
+ * within a component, and layout effects run before passive ones, so the capture
+ * always sees the control the user actually activated.
+ *
+ * An opener that has since been unmounted — an action picked from a list that
+ * closed with it — is skipped rather than focused, and the caller is free to
+ * offer a fallback of its own.
+ *
+ * @param scope - the closing context's own element, for an editing context
+ * nested inside a panel (the management form inside the management panel).
+ * When the outer panel closes, React runs the outer cleanup first, the inner
+ * cleanup next, and only then removes the outer DOM: by the time the nested
+ * context returns focus, the panel has already handed it to *its* opener, and
+ * the nested opener is a control about to leave the document. So a nested
+ * context returns focus only while focus is still inside it (or fell to the
+ * body); focus that has already left belongs to whoever moved it.
+ */
+export declare function useFocusReturn(scope?: MutableRefObject<HTMLElement | null>): void;
+/** Move focus into a panel once, on open (spec 8.4). */
+export declare function useInitialFocus<T extends HTMLElement>(): MutableRefObject<T | null>;
+/**
+ * Move focus into a panel once, on open, addressing the target through the
+ * panel rather than through a ref (spec 8.4).
+ *
+ * `@deepseek-ai/dsh-client-ui-primitives` publishes no `forwardRef` at all, so
+ * an official `Button` or `Input` cannot carry one. Addressing the opening
+ * target by marker attribute — the way the Tab boundary above already addresses
+ * the focusable set — keeps that limitation in this one module instead of
+ * pushing every panel back onto native controls.
+ *
+ * @param container - the panel whose subtree holds the target.
+ * @param selector - CSS selector for the control that should open focused.
+ */
+export declare function useInitialFocusIn<T extends HTMLElement>(container: MutableRefObject<T | null>, selector: string): void;

package/lib/types/client/session/ConfirmPanel.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The send confirmation panel (spec 9.3).
+ *
+ * It shows the action's label and the complete text that will be submitted, and
+ * for a Command Send Action it also carries the notice spec 9.3 and 16.2 make
+ * mandatory: the text goes to DSH's own command adjudication path, and no native
+ * `/` suggestion menu appears here, so what is on screen is exactly what will be
+ * submitted. Nothing in this panel imitates that menu.
+ *
+ * Opening it does not touch the draft; cancelling — the button, Escape, or a
+ * click on the backdrop — has no side effect at all. The re-verification that
+ * follows a confirmation lives in the execution engine, not here.
+ */
+import type { ReactElement } from 'react';
+import type { PendingQuickActionConfirmation } from './execution.js';
+import type { Translate } from '../dsh.js';
+export interface ConfirmPanelProps {
+    readonly pending: PendingQuickActionConfirmation;
+    readonly t: Translate;
+    readonly onConfirm: () => void;
+    readonly onCancel: () => void;
+}
+export declare function ConfirmPanel({ pending, t, onConfirm, onCancel }: ConfirmPanelProps): ReactElement;

package/lib/types/client/session/availability.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Which control one Quick Action renders as, given its Session's execution
+ * state (spec 3, 9.2).
+ *
+ * Shared by every surface that offers an action for execution — the three
+ * layouts and the shared searchable action panel — so a control cannot explain
+ * itself one way in the ribbon and another way behind "more".
+ */
+import type { QuickActionSessionState } from './execution.js';
+import type { QuickActionUnavailableReason } from './guards.js';
+import type { ProjectedQuickAction } from '../../model/index.js';
+/**
+ * The reason this action cannot run right now, or `undefined` when it can.
+ *
+ * While a send holds the Session's single flight, only the action holding it
+ * explains itself as "sending"; the rest are simply unavailable while the
+ * Composer is busy with it (spec 9.5).
+ */
+export declare function unavailableReasonFor(action: ProjectedQuickAction, session: QuickActionSessionState): QuickActionUnavailableReason | undefined;

package/lib/types/client/session/execution.d.ts

@@ -0,0 +1,86 @@
+import type { QuickActionUnavailableReason } from './guards.js';
+import type { ComposerBlock, InputActions, InputState, SessionSnapshot } from '../dsh.js';
+import type { ProjectedQuickAction, QuickActionRef } from '../../model/index.js';
+/** The action awaiting the user's confirmation (spec 9.3). */
+export interface PendingQuickActionConfirmation {
+    readonly ref: QuickActionRef;
+    readonly label: string;
+    /** The complete text that will be submitted; the panel shows it verbatim. */
+    readonly text: string;
+    /** Whether this is a Command Send Action, so the panel can carry its notice. */
+    readonly command: boolean;
+}
+/** What the surfaces report after an execution attempt (spec 9.3, 9.5). */
+export type QuickActionFeedback = 
+/** A re-verification found the action, Session, draft or guard changed. */
+{
+    readonly kind: 'state-changed';
+}
+/** The text was loaded but the machine did not take it; the draft keeps it. */
+ | {
+    readonly kind: 'retained';
+}
+/** Nothing was loaded; the draft is untouched and the action can be retried. */
+ | {
+    readonly kind: 'failed';
+    readonly message: string;
+};
+/** Everything the surfaces render about this Session's execution state. */
+export interface QuickActionSessionState {
+    /** Why no action may run right now, or `undefined` when they may (spec 3). */
+    readonly unavailable: QuickActionUnavailableReason | undefined;
+    /** The confirmation panel's subject, when one is open. */
+    readonly confirming: PendingQuickActionConfirmation | undefined;
+    /** Whether a send holds this Session's single flight. */
+    readonly sending: boolean;
+    /** The action holding the flight, so its own control can show the state. */
+    readonly activeRef: QuickActionRef | undefined;
+    /** The last execution feedback, until dismissed or superseded. */
+    readonly feedback: QuickActionFeedback | undefined;
+}
+/** The per-Session engine as the surfaces consume it. */
+export interface QuickActionSessionEngine {
+    getSnapshot(): QuickActionSessionState;
+    subscribe(listener: () => void): () => void;
+    /**
+     * Publish the current DSH state into the engine. Called on every commit of
+     * the entry that owns the layout, and the only way a snapshot reaches here —
+     * the engine never subscribes to a DSH store of its own.
+     */
+    observe(input: InputState, session: SessionSnapshot, block: ComposerBlock | undefined): void;
+    /** Bind the live `InputActions` and the live Composer projection (spec 7.2). */
+    bind(face: InputActions | undefined, composer: readonly ProjectedQuickAction[]): void;
+    /** Begin one Quick Action: claims the single flight, or is ignored. */
+    activate(action: ProjectedQuickAction): void;
+    /** Confirm the pending action after re-verifying everything (spec 9.3). */
+    confirm(): void;
+    /** Cancel the pending confirmation with no side effect (spec 9.3). */
+    cancel(): void;
+    dismissFeedback(): void;
+    /**
+     * Drop everything that has not entered the official state machine — the
+     * Session-switch, layout-unmount and Slot-replacement rule of spec 7.2. A send
+     * the machine already accepted is left alone: it belongs to its own Session.
+     */
+    cancelPending(): void;
+    dispose(): void;
+}
+/** Create the execution engine for one Session. */
+export declare function createQuickActionSessionEngine(sessionId: string): QuickActionSessionEngine;
+/**
+ * The fiber-owned registry of per-Session engines.
+ *
+ * The engine is looked up by Session id rather than constructed by the surface,
+ * which is what keeps one lock per Session across a layout switch: the ribbon
+ * unmounts as the bar mounts, and the engine in between is the same object
+ * (spec 7.2). Engines live until the Client fiber unloads; each one is a handful
+ * of fields, and tying their lifetime to the fiber avoids a reference count that
+ * a double-invoked render could get wrong.
+ */
+export interface QuickActionSessionRegistry {
+    /** This Session's engine, created on first use. */
+    engineFor(sessionId: string): QuickActionSessionEngine;
+    /** Release every engine — the Client fiber's own disposer. */
+    dispose(): void;
+}
+export declare function createQuickActionSessionRegistry(): QuickActionSessionRegistry;

package/lib/types/client/session/guards.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The send preconditions of spec 9.2, derived from nothing but the public
+ * per-Session snapshots a dock Slot entry receives.
+ *
+ * Both functions are total over the published `InputState` and the published
+ * `SessionSnapshot`: every field of the public Input snapshot is accounted for
+ * here or explained as deliberately not a precondition, because spec 9.5 makes
+ * that exact field set the only evidence this feature may judge a send by.
+ */
+import type { ComposerBlock, InputState, SessionSnapshot } from '../dsh.js';
+/** Why no Quick Action may execute in this Composer right now (spec 3, 9.2). */
+export type QuickActionUnavailableReason = 
+/** The draft holds text, an attachment or a reference chip (Occupied Draft). */
+'occupied-draft'
+/** The input machine is mid-adjudication, mid-submit, or in command mode. */
+ | 'composer-busy'
+/** A feature-owned Composer block is raised for this Session. */
+ | 'composer-blocked'
+/** The Session was removed. */
+ | 'session-removed'
+/** A continuable subagent whose parent is not available: the composer is inert. */
+ | 'parent-offline'
+/** This Session already has a send in flight (spec 9.5 single-flight). */
+ | 'sending';
+/**
+ * Whether the draft is occupied (spec 9.2). Occupancy is any text — pure
+ * whitespace included, so the raw string is compared against `''` and never
+ * trimmed — any attachment, and any rich reference.
+ *
+ * The public snapshot exposes exactly `{ draft, attachmentIds, draftRev, phase,
+ * claim?, occurrences, queue }`. Occupancy reads three of them:
+ *
+ * - `draft` — the clipboard-text projection of the whole document. Compared
+ *   against `''`, so a snapshot without it is occupied for the same reason
+ *   {@link holdsContent} gives;
+ * - `attachmentIds` — the ordered draft attachments, and the only public
+ *   attachment field there is. Since 0.1.5-rc.1 it admits any attachment kind,
+ *   not just images;
+ * - `occurrences` — the reference chips. They are already expanded inside
+ *   `draft`, so this test is redundant today; it is kept because a future chip
+ *   whose clipboard projection is empty must still count as content the send
+ *   action would carry away.
+ *
+ * The remaining fields are not occupancy: `draftRev` is a revision counter,
+ * `phase`/`claim` are the submit plane (handled by {@link composerGate}), and
+ * `queue` is the Session's transient inbox, which spec 9.2 explicitly allows a
+ * send to join.
+ */
+export declare function isOccupiedDraft(input: InputState): boolean;
+/**
+ * The composer-level guard, reproducing the shipped send button's own
+ * conditions from public state alone (spec 9.2).
+ *
+ * `disabled` in spec 9.2's list is the shipped bar's inert state, which is
+ * reached only without a Session or on the blank-session hero. Neither can
+ * occur here: both dock Slots are session-scoped, and the Quick Action surfaces
+ * render only where the Resident Composer predicate holds.
+ */
+export declare function composerGate(input: InputState, session: SessionSnapshot, block: ComposerBlock | undefined): QuickActionUnavailableReason | undefined;

package/lib/types/client/surfaces/ActionFace.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The visible face of one Quick Action — the shared action control of spec 14's
+ * `src/client/surfaces/` boundary.
+ *
+ * Three places offer an action to the user: a layout's control, the shared
+ * searchable action panel's list item, and the management list's row. All three
+ * must read the same, because the Command marker is only meaningful if it looks
+ * and means the same wherever it appears, and the emoji is only decoration if it
+ * is `aria-hidden` in every one of them (spec 8.4).
+ *
+ * It renders a fragment, not an element: each caller owns its own control — a
+ * `<button>`, a list row — and its own layout box.
+ */
+import type { ReactElement } from 'react';
+import type { ProjectedQuickAction } from '../../model/index.js';
+import type { Translate } from '../dsh.js';
+export interface ActionFaceProps {
+    readonly action: ProjectedQuickAction;
+    readonly t: Translate;
+}
+export declare function ActionFace({ action, t }: ActionFaceProps): ReactElement;

package/lib/types/client/surfaces/ErrorBoundary.d.ts

@@ -0,0 +1,31 @@
+/**
+ * One Slot entry's local error boundary (spec 7.3).
+ *
+ * A render error inside the Quick Action surfaces replaces the Quick Action
+ * area and nothing else: the Composer, its draft and its submit button keep
+ * working, and the user can ask for the surface back. Retrying remounts the
+ * subtree by changing its key, so a transient failure clears without a reload.
+ *
+ * DSH's own submission errors never reach here — they are reported by the
+ * Composer, and this feature must not repeat them (spec 9.5).
+ */
+import { Component } from 'react';
+import type { ErrorInfo, ReactNode } from 'react';
+import type { Translate } from '../dsh.js';
+export interface SurfaceErrorBoundaryProps {
+    readonly t: Translate;
+    readonly children: ReactNode;
+}
+interface SurfaceErrorBoundaryState {
+    readonly failed: boolean;
+    /** Bumped on retry so the failing subtree is rebuilt rather than reused. */
+    readonly attempt: number;
+}
+export declare class SurfaceErrorBoundary extends Component<SurfaceErrorBoundaryProps, SurfaceErrorBoundaryState> {
+    state: SurfaceErrorBoundaryState;
+    static getDerivedStateFromError(): Partial<SurfaceErrorBoundaryState>;
+    componentDidCatch(error: Error, info: ErrorInfo): void;
+    private readonly retry;
+    render(): ReactNode;
+}
+export {};

package/lib/types/client/surfaces/QuickActionsSurface.d.ts

@@ -0,0 +1,17 @@
+import type { ReactElement } from 'react';
+import type { QuickActionSessionState } from '../session/execution.js';
+import type { ProjectedQuickAction, QuickActionLayout } from '../../model/index.js';
+import type { Translate } from '../dsh.js';
+export interface QuickActionsSurfaceProps {
+    readonly layout: QuickActionLayout;
+    /** The Composer projection, in the shared order (hidden actions already gone). */
+    readonly actions: readonly ProjectedQuickAction[];
+    readonly session: QuickActionSessionState;
+    readonly t: Translate;
+    readonly onActivate: (action: ProjectedQuickAction) => void;
+    readonly onConfirm: () => void;
+    readonly onCancelConfirm: () => void;
+    readonly onDismissFeedback: () => void;
+    readonly onManage: () => void;
+}
+export declare function QuickActionsSurface(props: QuickActionsSurfaceProps): ReactElement;

package/lib/types/client/surfaces/entries.d.ts

@@ -0,0 +1,27 @@
+import type { ReactElement } from 'react';
+import type { ResidentComposerRegistry } from './residency.js';
+import type { QuickActionSessionRegistry } from '../session/execution.js';
+import type { QuickActionsController } from '../controller.js';
+import type { ComposerBlocks, ComposerDockProps, InputDockProps } from '../dsh.js';
+/** Everything the Slot entries reach outside React. */
+export interface QuickActionSurfaceDeps {
+    readonly controller: QuickActionsController;
+    readonly sessions: QuickActionSessionRegistry;
+    readonly residency: ResidentComposerRegistry;
+    /**
+     * Resolves `ctx.conversation.blocks`, the registry face documented as "how a
+     * plugin the composer cannot import makes a session's input inert". It is the
+     * only public reading of the `blocked` guard of spec 9.2, and it is reached
+     * through `ctx.get`, which the Cordis reflection layer documents as a read
+     * "without the inject requirement" — so the Client's declared dependencies
+     * stay exactly the four of spec 7.3. Absent, the guard degrades to "not
+     * blocked" rather than guessing from the DOM.
+     */
+    readonly blocks: () => ComposerBlocks | undefined;
+}
+/** Build both Slot entry components over one set of fiber-owned dependencies. */
+export declare function createQuickActionDockEntries(deps: QuickActionSurfaceDeps): {
+    readonly InputDock: (props: InputDockProps) => ReactElement;
+    readonly ComposerDock: (props: ComposerDockProps) => ReactElement;
+    readonly ManagerDock: (props: InputDockProps) => ReactElement;
+};

package/lib/types/client/surfaces/layout.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The width and density rules of spec 8.2, as pure functions.
+ *
+ * The geometry itself is CSS (see `src/styles/`), because the two docks sit in
+ * different boxes: the ribbon renders outside the InputBar, which owns the side
+ * clearance, so it must subtract that clearance itself; the bar renders inside
+ * the InputBar, whose padding already is the clearance, so it takes the full
+ * width. Both are then capped by the card's own max width and centred, which is
+ * what makes their outer edges line up with the input box.
+ *
+ * What is left over is the part that cannot be expressed in CSS: how many
+ * leading actions the `bar` layout shows before the rest fold into "more", and
+ * which density the surface renders at. Both are decided here so the rules can
+ * be pinned by tests rather than by a screenshot.
+ */
+/** How the surface presents itself at the current width (spec 8.2). */
+export type SurfaceDensity = 'wide' | 'narrow';
+/**
+ * Below this surface width the layout drops secondary information — the section
+ * title — and tightens its spacing. It never changes the outer width, and it
+ * never drops a control's visible text label (spec 8.2, 8.4).
+ *
+ * Sized against the viewports spec 13.3 requires: a desktop or ~768px viewport
+ * leaves the composer far above this, and a ~360px viewport lands well below it.
+ */
+export declare const NARROW_SURFACE_WIDTH = 480;
+export declare function densityFor(width: number): SurfaceDensity;
+/** One measured row of the `bar` layout. */
+export interface BarFitInput {
+    /** Usable inner width of the action row. */
+    readonly available: number;
+    /** Measured width of each action control, in the shared order. */
+    readonly widths: readonly number[];
+    /** Width the always-visible controls ("more", "manage") need to keep. */
+    readonly reserved: number;
+    /** Gap between adjacent controls. */
+    readonly gap: number;
+}
+/**
+ * How many leading actions the `bar` layout shows (spec 8.1). The rest fold into
+ * the shared action panel behind "more", and the management entry stays visible
+ * whatever the answer is.
+ *
+ * Before the first measurement — a fresh mount, or a headless environment with
+ * no layout — every width reads as zero. That answers "all of them": showing the
+ * full row and letting the browser's own overflow handle it for one frame is
+ * better than flashing a "more" button that the next frame withdraws.
+ */
+export declare function fitActionCount(input: BarFitInput): number;

package/lib/types/client/surfaces/residency.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The Resident Composer predicate (spec 2.3, 8.1; spec 15, decision 6).
+ *
+ * ## Why a predicate is needed at all
+ *
+ * The two dock Slots this feature registers into do not have the same reach:
+ *
+ * - `conversation.composer.dock` — "Ambient entries below the composer card" —
+ *   is rendered by the shipped `InputBar` under
+ *   `variant === 'composer' && input !== undefined && sessionId !== undefined`.
+ *   The blank-session hero renders the same bar with `variant: 'hero'`, and that
+ *   branch renders no composer dock at all.
+ * - `conversation.input.dock` — "Full-width entries above the composer card" —
+ *   is rendered by `ConversationRoot` from the composer stack, which is shared
+ *   by the hero and the resident composer. Its `zone` owner prop only requires
+ *   a Session and an Input, so the entry *does* mount on the hero.
+ *
+ * So the input dock alone cannot tell a Resident Composer from a hero, and the
+ * first release must render in one and never the other.
+ *
+ * ## The predicate
+ *
+ * A `conversation.composer.dock` entry is mounted **if and only if** the shipped
+ * composer is in its resident, session-backed variant. That mount is therefore
+ * DSH's own public statement of residency, and this registry is how the input
+ * dock reads it: the composer-dock entry marks its Session resident while it is
+ * mounted, and the input-dock entry renders the current layout only while the
+ * mark stands.
+ *
+ * It is a contract-level signal, not a guess: no DOM is measured, no private
+ * Composer state is read, and the shipped hero branch is not re-derived here —
+ * which is what spec 8.1 forbids ("不得通过 DOM 或私有 Composer 状态猜测来规避").
+ * The mark is published from a layout effect, so a hero that becomes resident
+ * brings the layout up in the same commit rather than the next one; and if that
+ * ever slipped a frame, it would slip in the required direction — the hard rule
+ * is that nothing appears on the hero, never that it appears instantly.
+ *
+ * Takeover composers need no predicate of their own: when a `conversation.composer`
+ * chain entry wins, the renderer keeps the resident fallback mounted but hides
+ * its wrapper, so both docks — and everything in them — go with it.
+ */
+/** Which Sessions currently have a Resident Composer on screen. */
+export interface ResidentComposerRegistry {
+    /**
+     * Mark one Session's Composer resident. The disposer withdraws the mark, and
+     * marks are counted, so a remount that overlaps its own unmount cannot leave
+     * the Session looking non-resident.
+     */
+    mark(sessionId: string): () => void;
+    isResident(sessionId: string): boolean;
+    /**
+     * The Session that owns anything global, or `undefined` when none is resident.
+     *
+     * The centralized management panel is global state rendered from a
+     * session-scoped Slot (spec 8.1 asks for it to be registered independently,
+     * and this release has no Slot outside a Session to register into). So if two
+     * Resident Composers were ever on screen at once, both entries would render
+     * the same overlay. Electing one owner — the Session that has been resident
+     * longest, which is stable while it stays mounted — is what keeps the panel
+     * single.
+     */
+    primarySessionId(): string | undefined;
+    subscribe(listener: () => void): () => void;
+}
+export declare function createResidentComposerRegistry(): ResidentComposerRegistry;

package/lib/types/host/config.d.ts

@@ -0,0 +1,18 @@
+import type { PresetCatalog } from '../model/index.js';
+/** What a Host composition may declare for this plugin. */
+export interface ComposerQuickActionsConfig {
+    /** Preset Quick Actions appended after the package's built-in manifest. */
+    readonly presets?: readonly unknown[];
+}
+export type ComposerQuickActionsConfigResult = {
+    readonly ok: true;
+    readonly catalog: PresetCatalog;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/**
+ * Read one Host composition config into the authoritative catalog.
+ * @param config - the composition entry's config, absent when nothing was declared.
+ */
+export declare function readComposerQuickActionsConfig(config: unknown): ComposerQuickActionsConfigResult;

package/lib/types/host/index.d.ts

@@ -0,0 +1,38 @@
+import type { CanonicalRewriteOutcome, SettingsRewriteProvider } from './settings.js';
+import type { PresetCatalog } from '../model/index.js';
+/**
+ * The read-only catalog projection published to Clients (spec 6.2, 17.2). It is
+ * the catalog itself under the name the spec gives it — one shape, so the Host
+ * cannot publish something the model never validated.
+ */
+export type CatalogSnapshot = PresetCatalog;
+/**
+ * The Host settings provider as this plugin uses it: namespace registration plus
+ * the fenced write face. Declared structurally so the Host is testable against a
+ * controlled fake; the real `SettingsProvider` satisfies it.
+ */
+export interface QuickActionsSettingsProvider extends SettingsRewriteProvider {
+    register(ns: string, schema: unknown, options?: unknown): unknown;
+}
+/** The running Host, owned by the fiber that started it. */
+export interface QuickActionsHost {
+    /** Settles when the startup canonical rewrite has been attempted. */
+    readonly ready: Promise<CanonicalRewriteOutcome>;
+    /**
+     * The read-only Remote payload (spec 6.2): lossless JSON, no Settings CRUD.
+     * Each call hands back a detached copy, so a consumer cannot reach the
+     * authoritative catalog through the value it was given.
+     */
+    describeCatalog(): Promise<CatalogSnapshot>;
+}
+/**
+ * Load the catalog, register both namespaces and canonicalize the stored section.
+ *
+ * An invalid preset configuration throws before anything is registered: the
+ * catalog is author-owned, so a mistake fails plugin loading rather than
+ * silently shipping a partial catalog (spec 5.1).
+ *
+ * @param settings - the Host settings provider.
+ * @param config - the Host composition entry's config.
+ */
+export declare function startQuickActionsHost(settings: QuickActionsSettingsProvider, config: unknown): QuickActionsHost;

package/lib/types/host/presets.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The package's built-in Preset Quick Action manifest — component 1 of the
+ * Preset Catalog (spec 5.1), declared ahead of the Host composition's
+ * `Config.presets`.
+ *
+ * These are author-facing product copy in one language; changing a label or a
+ * text is a product decision, not an implementation one.
+ *
+ * Two rules bind any edit here:
+ *
+ * - A Preset Action ID is permanent. Label, icon and text may change under the
+ *   same id, but `kind` and `confirm` are the immutable safety behaviour
+ *   signature — changing either needs a new id (spec 5.1). Editing a text so it
+ *   crosses the Command Send Action boundary counts as crossing that signature.
+ * - Adding an entry is additive: a new id appends to the end of every existing
+ *   user's order and rewrites no stored data (spec 5.3).
+ *
+ * `summarize` and `explain` carry new ids rather than reusing
+ * `summarize-thread` and `explain-last-change`: those two shipped on the
+ * default `confirm: true`, and turning confirmation off is exactly the
+ * signature change the first rule reserves a new id for. The old ids simply
+ * leave the catalog, which the model already handles — a stored preference for
+ * an id no longer in the catalog is kept as a tombstone, neither shown nor
+ * counted (spec 5.3).
+ */
+export declare const BUILT_IN_PRESETS: readonly unknown[];