@ai-matrx/alchemy 0.6.2 → 0.8.2

package/dist/react-host.d.cts

@@ -0,0 +1,820 @@
+import * as React from 'react';
+import { TransferOutcome } from '@ai-matrx/kit/content-transfer';
+
+/**
+ * Matrx Alchemy — Declare types (CONTRACT §2.1).
+ *
+ * A declaration is plain JSON data (chair ruling N2): no functions, no classes,
+ * no React. Runtime behaviour lives in `MountedSurface` (`/declare/host`) and in
+ * handler registrations, never here. Zero React, zero `@ai-matrx/agents`.
+ */
+type Json$1 = null | boolean | number | string | Json$1[] | {
+    [key: string]: Json$1;
+};
+/** Unchanged from `ui_surface_value_type_chk`. */
+type ValueType = "string" | "number" | "boolean" | "object" | "array" | "document";
+type Classification = "ordinary" | "secret" | "credential";
+/** Persisted (CONTRACT §2.7). Projection enforces it before any value leaves. */
+interface Sensitivity {
+    /** false = never leaves through Operate. Default true. */
+    exportable: boolean;
+    /** secret/credential are always excluded; no caller can relax this. Default "ordinary". */
+    classification: Classification;
+    /** Pre-checked in the preparation workspace. Default true. */
+    includedByDefault: boolean;
+}
+interface ValueGroup {
+    key: string;
+    label: string;
+    sortOrder: number;
+    description?: string;
+}
+/** The four runtime slots a capture fills (absorbs page-capture). */
+type LiveSlot = "selection" | "on-demand" | "errors" | "requests";
+interface DeclaredValue {
+    name: string;
+    label: string;
+    description: string;
+    valueType: ValueType;
+    /** Registered content-ir kind key (DB: kind_key). */
+    valueKind?: string;
+    alwaysAvailable: boolean;
+    typicalCharCount: number;
+    autoContext?: boolean;
+    group?: string;
+    sortOrder?: number;
+    sensitivity?: Partial<Sensitivity>;
+    /** Filled at capture time from a live slot instead of the scope. */
+    liveSlot?: LiveSlot;
+    /** "request" values drop out of "Only the data". Default "data". */
+    role?: "data" | "request";
+}
+/** Where a write lands. "stream" = applied live, op by op, into an editable text. */
+type WriteMode = "draft" | "entity" | "ui" | "stream";
+/** Who may apply WITHOUT a click. "queued" = filed for an organization's review. */
+type ApplyPolicy = "manual" | "ask" | "auto" | "queued";
+/** The WidgetHandle text op set, unchanged in meaning. */
+type StreamOp = "replace" | "insert_before" | "insert_after" | "prepend" | "append" | "patch";
+interface WriteTarget {
+    name: string;
+    label: string;
+    description: string;
+    valueType: ValueType;
+    valueKind?: string;
+    /** Read twin (evidence loop). Required when patchable or mode === "stream". */
+    updatesValue?: string;
+    patchable?: boolean;
+    approvalComparison?: "text-replacement";
+    mode: WriteMode;
+    /** Required iff mode === "stream". */
+    streamOps?: readonly StreamOp[];
+    /** Default "manual". Binding overrides may only tighten. */
+    applyPolicy?: ApplyPolicy;
+    destination?: boolean;
+    /** Present when the target writes into an item rather than the screen. */
+    itemType?: string;
+    group?: string;
+    sortOrder?: number;
+}
+/** One kind of thing inside a screen (a row, a message, a code block, a card). */
+interface ItemType {
+    name: string;
+    label: string;
+    description: string;
+    /** Value names that together identify one item. */
+    identity: readonly string[];
+    levels?: readonly string[];
+    entityType?: string;
+    values: readonly DeclaredValue[];
+    writeTargets?: readonly WriteTarget[];
+}
+type Readiness = "verified" | "partial" | "stub";
+/** `ui_surface_execution_mode_check`, unchanged. */
+type ExecutionMode = "python-stream" | "nextjs-stream" | "browser-realtime" | "local-runtime";
+interface ConfigNamespaceDeclaration {
+    namespace: string;
+    label: string;
+    description: string;
+}
+interface EvidenceSourceDeclaration {
+    kind: "processed_document";
+    idValue: string;
+    fileIdValue?: string;
+    labelValue?: string;
+    representation?: "clean" | "raw";
+}
+/**
+ * One screen's declaration. Owning packages add fields (agent roles, client
+ * tools) as EXTENSION SLOTS — by interface extension or declaration merging —
+ * and register a `DeclarationExtension` so validation and the sync cover them.
+ */
+interface SurfaceDeclaration {
+    surfaceName: string;
+    /** REQUIRED. `ui_surface.client_name`; must equal the surfaceName prefix. */
+    client: string;
+    /** REQUIRED. `ui_surface.execution_mode`. */
+    executionMode: ExecutionMode;
+    /** REQUIRED. `ui_surface.description` ("" only where the live row is empty). */
+    description: string;
+    label: string;
+    readiness: Readiness;
+    readinessNote?: string;
+    urlPattern?: string;
+    inheritsFrom?: string;
+    intro?: string;
+    overlayId?: string;
+    values: readonly DeclaredValue[];
+    groups?: readonly ValueGroup[];
+    writeTargets?: readonly WriteTarget[];
+    itemTypes?: readonly ItemType[];
+    liveSlots?: readonly LiveSlot[];
+    configNamespaces?: readonly ConfigNamespaceDeclaration[];
+    evidenceSources?: readonly EvidenceSourceDeclaration[];
+    skipBaselineValues?: boolean;
+}
+type ValueProvenance = {
+    kind: "own";
+} | {
+    kind: "inherited";
+    from: string;
+} | {
+    kind: "baseline";
+};
+type ResolvedValue = DeclaredValue & {
+    provenance: ValueProvenance;
+    groupKey: string;
+    /** Defaults filled. */
+    resolvedSensitivity: Sensitivity;
+};
+interface ResolvedSurfaceDeclaration extends SurfaceDeclaration {
+    contentHash: string;
+    values: readonly ResolvedValue[];
+    groups: readonly ValueGroup[];
+}
+/**
+ * ITEM KEYS. A value or write target is identified by (surfaceName, itemType ?? "", name).
+ * The qualified key "<itemType>.<name>" names an item value; a bare name is a screen value.
+ */
+type QualifiedValueKey = string;
+/** Live slot payloads (page-capture's shapes, kept). */
+interface LiveValues {
+    selection?: {
+        choices: Record<string, Json$1>;
+        text: string | null;
+    };
+    "on-demand"?: readonly OnDemandSection[];
+    errors?: readonly string[];
+    requests?: readonly RecentRequest[];
+}
+interface OnDemandSection {
+    id: string;
+    title: string;
+    description?: string;
+    role: "data" | "request";
+    brief?: Json$1;
+    load(signal: AbortSignal): Promise<Json$1>;
+}
+interface RecentRequest {
+    method: string;
+    path: string;
+    status: string;
+    httpStatus?: number;
+    durationMs?: number;
+    requestId?: string;
+    client?: string;
+    requestBody?: Json$1;
+    requestBodyNote?: string;
+    errorSentence?: string;
+    timestamp: number;
+}
+/** RAW-FREE. What leaves the package about a clicked item. */
+interface ResolvedItem {
+    itemType: string;
+    identity: Record<string, string>;
+    level?: string;
+    readOnly: boolean;
+}
+
+/**
+ * The click target (CONTRACT §2.4) in its own module: `/ports` references it,
+ * and `/ports` must stay free of every other package (types only).
+ */
+
+/** The six universal verbs — the ONLY rows that may grey (R1 c). */
+declare const UNIVERSAL_VERBS: readonly ["copy", "cut", "paste", "undo", "redo", "find"];
+type UniversalVerb = (typeof UNIVERSAL_VERBS)[number];
+/** The transfer Payload's kinds (`actions/types.ts` asserts equality at compile time). */
+type PayloadKind = "text" | "markdown" | "json" | "rows" | "registered";
+/** What eligibility is computed from: everything declared at the click target. */
+interface ClickTarget {
+    surface: {
+        instanceId: string;
+        surfaceName: string;
+    } | null;
+    /** The resolved declaration (inheritance applied). Eligibility decides by KEY existence over it. */
+    declaration: ResolvedSurfaceDeclaration | null;
+    /** Declared value keys with a read path here (screen names + qualified item keys). Key existence, not population. */
+    valueKeys: ReadonlySet<QualifiedValueKey>;
+    /** Scope chain, most general first: ["global", "<domain>", "<surfaceName>"]. */
+    scopeChain: readonly string[];
+    /** The surface's explicit exclusions (the one override). */
+    excludedActionIds: ReadonlySet<string>;
+    item: ResolvedItem | null;
+    level: string | null;
+    /** Offsets + the live range handle, editable or not. */
+    selection: {
+        text: string;
+        type: "editable" | "non-editable";
+        start: number;
+        end: number;
+        /** Opaque host handle (DOM Range / element) used to restore or stream into the selection. */
+        handle?: unknown;
+    } | null;
+    /** Payload kinds a capture of this target would produce (from declared value types/kinds). */
+    payloadKinds: readonly PayloadKind[];
+    /** Declared targets writable on this target right now. */
+    writable: readonly WriteTarget[];
+    readOnly: boolean;
+    /** True when any declared value here is secret/credential or non-exportable. */
+    restricted: boolean;
+    organizationId: string | null;
+    auth: {
+        authenticated: boolean;
+        admin: boolean;
+        creator: boolean;
+    };
+    /**
+     * Host-owned context a provider reads to act (the rich-document source, the
+     * editable field's callbacks). Opaque to the package; never crosses into the
+     * model. Providers that need it narrow it themselves.
+     */
+    host?: unknown;
+}
+
+/**
+ * `@ai-matrx/alchemy/ports` — the host ports (Matrx Alchemy CONTRACT §2.2).
+ *
+ * The app binds these ONCE, at its boundary (where the Alchemy host is
+ * mounted). The package never imports the host.
+ *
+ * ── Ports arrive with the wave that needs them (chair ruling N8) ────────────
+ *
+ * This entry declares only the ports the current waves use:
+ *
+ *   ALC-13  `kinds` (content-ir's validator, injected), `diagnostics` (required)
+ *   ALC-14  `identity`, `persistence`
+ *   ALC-15  `store`, `notify`, `overlay`, `icons`, `knobs`, `i18n`, `auth`, `dialogs`
+ *
+ *   ALC-16  `transport`, `assets`, `server`
+ *
+ * ALC-17 adds approvals/bodies/receipts.
+ *
+ * ── Absent-port semantics ───────────────────────────────────────────────────
+ *
+ * Every port except `diagnostics` is OPTIONAL. A port the host does not bind
+ * means that capability is ABSENT: the actions, formats or writes that need
+ * it are not offered at all. A missing port is never stubbed, never faked
+ * with a default that pretends to work, and never shown as a dead control.
+ *
+ *   kinds        absent → kind validation is absent (no value can be checked,
+ *                         so a kind-bearing write is not offered)
+ *   diagnostics  REQUIRED → nothing fails silently; contract breaks land here
+ *   identity     absent → organization-scoped declarations are absent
+ *   persistence  absent → per-person settings are absent (organization and
+ *                         platform defaults apply)
+ *   store        absent → actions that read named host state or run named
+ *                         host commands are absent
+ *   notify       absent → outcomes are not announced (diagnostics still captures)
+ *   overlay      absent → actions that open an overlay or navigate are absent
+ *   icons        absent → rows render label-only (a key is never shown as text)
+ *   knobs        absent → the platform default layout/density applies
+ *   i18n         absent → labels as written
+ *   auth         absent → a signed-out person does not see requiresAuth actions
+ *                         (sign-in-then-resume is the capability that is missing)
+ *   dialogs      absent → actions that need a host dialog are absent
+ *
+ * Types only: this entry has no runtime code.
+ */
+/** JSON as it crosses a port. */
+type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+/**
+ * content-ir's kind validator, injected so Alchemy validates without
+ * importing the app or the kind catalog. The host builds it from
+ * `@ai-matrx/content-ir`'s `createKindValidator` over its own
+ * `SchemaSourcePort` (which content-ir defines and exports; Alchemy never
+ * declares it).
+ *
+ * `unverifiable: true` marks a verdict where the kind could not be checked
+ * (not registered, no schema, uncompilable schema, catalog unreachable) — a
+ * skip, which is never a pass.
+ */
+interface KindValidatorPort {
+    validate(kindKey: string, value: unknown, signal: AbortSignal): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        sentence: string;
+        remedy: string;
+        unverifiable?: true;
+    }>;
+}
+
+/** Where contract breaks are captured. Required: nothing fails silently. */
+interface DiagnosticsPort {
+    capture(error: unknown, context: {
+        area: "declare" | "operate" | "write" | "actions" | "menu";
+        detail: Json;
+    }): void;
+}
+/** Who is using the app right now, and in which organization. */
+interface IdentityPort {
+    /** `null` while the host has no resolved identity yet. */
+    current(): {
+        userId: string;
+        organizationId: string | null;
+        isAuthenticated: boolean;
+        isAdmin: boolean;
+    } | null;
+    /** Called whenever `current()` may answer differently; returns unsubscribe. */
+    onChange(listener: () => void): () => void;
+}
+/** Per-person settings (layout, density, transfer preferences), layered by the host's settings system. */
+interface PersistencePort {
+    readSetting<T extends Json>(key: string): Promise<T | null>;
+    writeSetting(key: string, value: Json): Promise<void>;
+}
+/** Neutral state access: named reads and named commands. No Redux type or dispatch crosses this line. */
+interface StorePort {
+    /** A named, typed read the host registered ("activeConversationId", "organizationName"). */
+    read<T extends Json>(key: string): T | null;
+    /** A named command the host registered ("tasks.setPendingSource"); resolves with its result. */
+    command(name: string, input: Json): Promise<Json | void>;
+    subscribe(key: string, listener: () => void): () => void;
+}
+interface NotifyPort {
+    success(sentence: string): void;
+    info(sentence: string): void;
+    /** Every failure names its remedy. */
+    error(sentence: string, remedy: string): void;
+}
+/** Overlays are dispatched through the host; the menu never renders a modal. */
+interface OverlayHostPort {
+    open(overlayId: string, data: Json, instanceId?: string): void;
+    close(overlayId: string, instanceId?: string): void;
+    navigate(href: string): void;
+}
+/** Icon key → the host's icon component. The model only ever holds keys. */
+interface IconResolverPort {
+    resolve(key: string): unknown | null;
+}
+type ContextArrangementKnob = "classic" | "tiered" | "command";
+type DensityKnob = "comfortable" | "compact";
+/** ORGANIZATION defaults only; every method takes the organization. */
+interface MenuKnobsPort {
+    /** Replaces the constant PLACEMENT_LABEL_OVERRIDE. */
+    placementLabel(placement: string, organizationId: string | null): string | null;
+    /** Replaces the constant DEFAULT_PLACEMENT_MODE. */
+    placementMode(placement: string, organizationId: string | null): "show" | "hide";
+    /** The organization's default layout and density (platform default when null: command / comfortable). */
+    layout(organizationId: string | null): {
+        context: ContextArrangementKnob;
+        density: DensityKnob;
+    } | null;
+}
+/** Label translation. Absent = labels as written. */
+interface I18nPort {
+    t(key: string, fallback: string): string;
+}
+/** Sign in, then resume the action the person picked. */
+interface AuthResumePort {
+    isSignedIn(): boolean;
+    /** Stash {actionId, target fingerprint} and open sign-in; after sign-in the next matching menu host resumes it. */
+    signInThenResume(pending: {
+        actionId: string;
+        contentFingerprint: string;
+    }): void;
+    takePending(contentFingerprint: string): {
+        actionId: string;
+    } | null;
+}
+/** Per-instance host dialogs (today's RichDocumentActionContextCallbacks). */
+interface HostDialogsPort {
+    requestDelete?(target: ClickTarget): void;
+    requestConvert?(target: ClickTarget): void;
+    requestEditHistory?(target: ClickTarget): void;
+    requestFullPrint?(target: ClickTarget): void;
+    requestSaveTable?(table: {
+        headers: string[];
+        rows: string[][];
+    }): void;
+    requestFlashcard?(answer: string): void;
+}
+/** The ports a host binds. Optional = absent capability when unbound (see above). */
+interface AlchemyHostPorts {
+    kinds?: KindValidatorPort;
+    /** REQUIRED from ALC-13 (the only non-optional port): contract breaks are captured here. */
+    diagnostics: DiagnosticsPort;
+    identity?: IdentityPort;
+    persistence?: PersistencePort;
+    store?: StorePort;
+    notify?: NotifyPort;
+    overlay?: OverlayHostPort;
+    icons?: IconResolverPort;
+    /** Organization defaults for menu knobs; a person's own choice is layered over them via persistence (N9). */
+    knobs?: MenuKnobsPort;
+    i18n?: I18nPort;
+    auth?: AuthResumePort;
+    dialogs?: HostDialogsPort;
+    /** Clipboard and download for this runtime (the browser default ships in /operate). */
+    transport?: TransportPort;
+    /** Private or signed images → share-safe URLs before HTML is sealed. Absent = images keep their URL. */
+    assets?: AssetResolverPort;
+    /** Present when the host can reach aidream server operations; absent = server formats are not offered. */
+    server?: ServerPort;
+}
+/** A transferable artifact as the transport sees it (structurally `@ai-matrx/alchemy/operate`'s Artifact). */
+interface TransportArtifact {
+    format: string;
+    plainText: string;
+    html?: string;
+    file?: {
+        filename: string;
+        mime: string;
+        bytes: Uint8Array;
+    };
+}
+type TransportOutcome = {
+    status: "success";
+    delivered: "clipboard" | "download-started";
+    mimeTypes: string[];
+} | {
+    status: "degraded";
+    delivered: "plain-text";
+    reason: string;
+} | {
+    status: "cancelled";
+} | {
+    status: "error";
+    code: string;
+    message: string;
+    retryable: boolean;
+};
+/** Clipboard and download for a non-browser runtime (MV3 service worker, Tauri — CONTRACT R8). */
+interface TransportPort {
+    copy(artifact: TransportArtifact, signal: AbortSignal): Promise<TransportOutcome>;
+    download(artifact: TransportArtifact, signal: AbortSignal): Promise<TransportOutcome>;
+}
+interface AssetResolverPort {
+    resolve(url: string, signal: AbortSignal): Promise<{
+        url: string;
+    } | null>;
+}
+type ServerResult = {
+    status: "bytes";
+    filename: string;
+    mime: string;
+    bytes: Uint8Array;
+    notices: readonly {
+        code: string;
+        sentence: string;
+        remedy: string;
+    }[];
+} | {
+    status: "receipt";
+    receipt: {
+        status: string;
+        sentence: string;
+        remedy?: string;
+    };
+};
+interface ServerPort {
+    call(operationId: string, input: Json, signal: AbortSignal): Promise<ServerResult>;
+}
+
+/**
+ * Matrx Alchemy — Actions types (CONTRACT §2.4).
+ *
+ * One registry of everything a person can do to a thing. Providers plug in;
+ * eligibility is computed from what is declared at the click target; duplicate
+ * ids are refused; an action that does not apply is ABSENT (chair ruling R1).
+ *
+ * Framework-neutral: zero React, zero `@ai-matrx/agents`. Icons are string KEYS
+ * resolved by the host's `IconResolverPort`; labels go through `I18nPort`.
+ */
+
+/**
+ * Chair ruling R1: an action that does not apply or cannot run now is ABSENT.
+ * Only the six universal verbs may answer "unavailable-verb": greyed in the
+ * strip/bar, the sentence as tooltip. `requiresAuth` is NOT unavailability.
+ */
+type Eligibility = {
+    status: "absent";
+} | {
+    status: "available";
+} | {
+    status: "unavailable-verb";
+    verb: UniversalVerb;
+    sentence: string;
+};
+/** rich-document's ActionCategory, unchanged, plus the three the context menu groups by. */
+type ActionCategory = "feedback" | "copy" | "export" | "save" | "edit" | "share" | "creator" | "app" | "listen" | "study" | "ask" | "ai" | "admin" | "clipboard" | "history" | "surface-info";
+/**
+ * An optional named section inside the action's group (a grid's cell / row /
+ * column). `primary` marks the thing the person clicked: every layout renders
+ * it first, inline, heading kept (context-menu-v3's primary section law).
+ */
+interface ActionSection {
+    id: string;
+    label: string;
+    labelKey?: string;
+    icon?: string;
+    primary?: boolean;
+}
+interface Action {
+    /** Globally unique. A duplicate is refused (never overwritten). */
+    id: string;
+    /** The provider that registered it — filled by the registry. */
+    provider?: string;
+    /** Resolved through I18nPort.t(labelKey ?? id, label). */
+    label: string | ((target: ClickTarget) => string);
+    labelKey?: string;
+    /** Icon KEY resolved by IconResolverPort — the model stays framework-neutral. */
+    icon?: string;
+    /** Host styling hint for the glyph (rich-document iconColor). Renderers may ignore it. */
+    iconTone?: string;
+    /** Replaces `icon` while a state holds (a spinner while speaking). */
+    stateIcon?(target: ClickTarget): {
+        icon: string;
+        spin?: boolean;
+    } | null;
+    hint?: string;
+    hintKey?: string;
+    description?: string;
+    category: ActionCategory;
+    /** Which universal verb this clipboard action is (addressed by role in every layout). */
+    verb?: UniversalVerb;
+    order?: number;
+    /** Bar layout slot. Default "overflow". */
+    placement?: "primary" | "overflow" | "both";
+    section?: ActionSection;
+    /** A signed-out person still sees it; running goes through AuthResumePort (sign in, then resume). */
+    requiresAuth?: boolean;
+    /** Declared write targets this action lands through. Absent on a read-only target. */
+    writes?: readonly string[];
+    destructive?: boolean;
+    preserveSelection?: boolean;
+    /** Link rows navigate instead of running. */
+    href?: string | ((target: ClickTarget) => string);
+    eligible(target: ClickTarget): Eligibility;
+    /** Toggle/pressed state: a pressed button or a checked row. */
+    pressed?(target: ClickTarget): boolean;
+    /** Present = the row is a checkbox (pressed is its state). */
+    toggle?: boolean;
+    subscribe?(onChange: () => void, target: ClickTarget): () => void;
+    /** Submenus whose rows load on open (agent lists). */
+    expand?(target: ClickTarget, signal: AbortSignal): Promise<readonly Action[]>;
+    /** Shown centred when `expand` resolves empty. */
+    emptyLabel?: string;
+    run(target: ClickTarget, context: ActionRunContext): Promise<TransferOutcome | void> | TransferOutcome | void;
+}
+/** One removed read, recorded (kit content-transfer's omission shape). */
+interface ReadOmission {
+    path: string;
+    reason: "excluded" | "filtered";
+    classification?: "secret" | "credential";
+}
+/**
+ * PROJECTION BEFORE PROVIDERS. Providers never receive a raw read. Every read
+ * they can make is projected first: secret and credential values, values
+ * declared `exportable: false`, and values nobody declared are removed, with an
+ * omission recorded. Raw reads never leave the package.
+ */
+interface ProjectedReads {
+    values(signal: AbortSignal): Promise<{
+        values: Record<string, Json$1>;
+        omissions: readonly ReadOmission[];
+    }>;
+    item(signal: AbortSignal): Promise<{
+        values: Record<string, Json$1>;
+        omissions: readonly ReadOmission[];
+    } | null>;
+    live(signal: AbortSignal): Promise<LiveValues>;
+}
+/**
+ * What a running action receives. `door` (ALC-17) and `operate` (ALC-16) join
+ * with their waves; until then those capabilities are absent (N8).
+ */
+interface ActionRunContext {
+    reads: ProjectedReads;
+    ports: AlchemyHostPorts;
+    signal: AbortSignal;
+}
+interface ActionProvider {
+    id: string;
+    /** T0 providers are known at mount; T1 providers load with the menu on first open. */
+    tier: "T0" | "T1";
+    /**
+     * The ids this provider can ever yield, when known up front. Lets the
+     * registry refuse a duplicate at registration instead of at first open.
+     */
+    declaredIds?(): readonly string[];
+    actions(target: ClickTarget): readonly Action[] | Promise<readonly Action[]>;
+}
+interface ResolvedAction {
+    action: Action;
+    eligibility: Exclude<Eligibility, {
+        status: "absent";
+    }>;
+}
+interface ResolveRestriction {
+    exclude?: readonly string[];
+    categories?: readonly ActionCategory[];
+}
+interface ActionRegistry {
+    /** Throws DuplicateActionError naming both providers; nothing is overwritten. */
+    register(provider: ActionProvider): () => void;
+    /** restrict: a host may remove ids or categories, never add ineligible ones. */
+    resolve(target: ClickTarget, restrict?: ResolveRestriction): Promise<readonly ResolvedAction[]>;
+    /** Registered provider ids, in registration order. */
+    providers(): readonly string[];
+    /** Change notification (a provider registered or unregistered). */
+    subscribe(listener: () => void): () => void;
+}
+
+/**
+ * `@ai-matrx/alchemy/declare/host` — HOST-BINDING types only (CONTRACT §2.1, §2.6).
+ * Never imported by providers (`/declare`, `/actions`, `/menu`, `/operate` see only
+ * the raw-free `ResolvedItem`). Types only: no runtime code.
+ */
+
+interface ItemAnchor {
+    /** The host element the person clicked. */
+    element: unknown;
+    level?: string;
+}
+/** Raw item reads: consumed only by projection and the write handler that owns the target. */
+interface InternalResolvedItem extends ResolvedItem {
+    readValues(signal: AbortSignal): Promise<Record<string, unknown>>;
+}
+/** A mounted instance of a declared surface. Structural handle, never a global name lookup. */
+interface MountedSurface {
+    instanceId: string;
+    surfaceName: string;
+    isMounted(): boolean;
+    /** Same revision before and after a read, or capture refuses with "surface-changed". */
+    getRevision?(): string;
+    unsavedChanges?(): boolean;
+    readValues(signal: AbortSignal): Promise<Record<string, unknown>>;
+    readLive?(signal: AbortSignal): Promise<LiveValues>;
+    resolveItem?(anchor: ItemAnchor): InternalResolvedItem | null;
+}
+
+interface ProjectionSource {
+    surface: MountedSurface | null;
+    declaration: ResolvedSurfaceDeclaration | null;
+    item: InternalResolvedItem | null;
+}
+
+/**
+ * The one run path (T1e). Every layout runs an action through here, so the
+ * sign-in-then-resume rule, projection and failure capture live once.
+ */
+
+type RunResult = {
+    status: "ran";
+    outcome: TransferOutcome | void;
+} | {
+    status: "auth-pending";
+} | {
+    status: "failed";
+    error: unknown;
+};
+
+type ContextArrangement = "classic" | "tiered" | "command";
+type Density = "comfortable" | "compact";
+
+/**
+ * The React half of T1e: one hook every renderer uses to resolve the registry
+ * at a target, build the model and run a node. Handlers never live in a
+ * renderer — they live in providers and run through `runAction`.
+ *
+ * The context object is shared through globalThis so every per-layout entry
+ * (each bundled separately) reads the same provider (module state is banned
+ * across dual-loader graphs).
+ */
+
+interface MenuEngineOptions {
+    restrict?: ResolveRestriction;
+    /** Raw sources for projection (the host's mounted surface / clicked item). */
+    source?: ProjectionSource;
+    /** Content the menu acts on when nothing is selected (header text). */
+    content?: string | null;
+    contentFingerprint?: string;
+    /** Called after a node ran (close the menu, announce). */
+    onRan?: (nodeId: string, result: RunResult) => void;
+    /** Resolve only while true (renderers resolve on open). Default true. */
+    active?: boolean;
+    /**
+     * Re-resolve when this changes even if the target object is the same (a
+     * host that keeps one target per mount and reads live state through it).
+     */
+    revision?: string | number;
+}
+
+/**
+ * `@ai-matrx/alchemy/react/sheet` — the mobile bottom-sheet layout, T1m.
+ * T1's twin over the SAME model (`sheet(model)`), so mobile can never drift
+ * from desktop. Path-based drill-down: a list of submenu ids re-resolved
+ * against the live model every render, so loading agents update in place.
+ */
+
+interface ActionSheetProps extends MenuEngineOptions {
+    target: ClickTarget;
+    open: boolean;
+    onOpenChange(open: boolean): void;
+    title?: string;
+}
+declare function ActionSheet({ target, open, onOpenChange, title, ...options }: ActionSheetProps): React.ReactElement;
+
+declare const __sheet_ActionSheet: typeof ActionSheet;
+type __sheet_ActionSheetProps = ActionSheetProps;
+declare namespace __sheet {
+  export { __sheet_ActionSheet as ActionSheet, type __sheet_ActionSheetProps as ActionSheetProps, ActionSheet as default };
+}
+
+/**
+ * `@ai-matrx/alchemy/react/menu` — the right-click (context) layout, T1.
+ * Reached only through the T0 shell's dynamic import (`/react/host`); it
+ * draws `context(model, arrangement)` at the pointer. classic · tiered ·
+ * command (type-to-filter over every leaf with its breadcrumb).
+ */
+
+interface ContextMenuPanelProps extends MenuEngineOptions {
+    target: ClickTarget;
+    /** Viewport coordinates of the gesture. */
+    point: {
+        x: number;
+        y: number;
+    };
+    open: boolean;
+    onOpenChange(open: boolean): void;
+    arrangement?: ContextArrangement;
+    density?: Density;
+}
+declare function ContextMenuPanel({ target, point, open, onOpenChange, arrangement, density, ...options }: ContextMenuPanelProps): React.ReactElement;
+
+declare const __menu_ContextMenuPanel: typeof ContextMenuPanel;
+type __menu_ContextMenuPanelProps = ContextMenuPanelProps;
+declare namespace __menu {
+  export { __menu_ContextMenuPanel as ContextMenuPanel, type __menu_ContextMenuPanelProps as ContextMenuPanelProps, ContextMenuPanel as default };
+}
+
+/**
+ * The shared React context (T0-safe: imports only React and types). Shared
+ * through globalThis so every per-layout bundle reads the same provider.
+ */
+
+interface AlchemyActionsValue {
+    registry: ActionRegistry;
+    ports: AlchemyHostPorts;
+}
+declare function useAlchemyActions(): AlchemyActionsValue;
+
+interface AlchemyActionsProviderProps {
+    ports: AlchemyHostPorts;
+    /** Share one registry across providers; default: one per provider mount. */
+    registry?: ActionRegistry;
+    children: React.ReactNode;
+}
+declare function AlchemyActionsProvider({ ports, registry, children }: AlchemyActionsProviderProps): React.ReactElement;
+/** Register a provider for the lifetime of the calling component. Duplicate ids throw (refused). */
+declare function useRegisterActionProvider(provider: ActionProvider | null): void;
+type MenuModule = typeof __menu;
+type SheetModule = typeof __sheet;
+interface ActionMenuTriggerProps extends MenuEngineOptions {
+    /** Build the target at gesture time (selection captured then). */
+    resolveTarget(gesture: {
+        element: Element;
+        selectionText: string;
+        editable: boolean;
+    }): ClickTarget | null;
+    children: React.ReactElement;
+    arrangement?: "classic" | "tiered" | "command";
+    density?: "comfortable" | "compact";
+    /** Force a renderer; default: sheet below 768px or on coarse pointers. */
+    mobile?: boolean;
+    /**
+     * The wrapped surface is an editor that wires text mutation into the menu,
+     * so the menu takes its right-click. Otherwise a live text field keeps its
+     * native menu (Paste, spellcheck, autofill).
+     */
+    editable?: boolean;
+    /** Override the lazy loaders (tests, custom bundlers). */
+    loadMenu?: () => Promise<Pick<MenuModule, "ContextMenuPanel">>;
+    loadSheet?: () => Promise<Pick<SheetModule, "ActionSheet">>;
+}
+declare function ActionMenuTrigger({ resolveTarget, children, arrangement, density, mobile, editable, loadMenu, loadSheet, ...options }: ActionMenuTriggerProps): React.ReactElement;
+
+export { ActionMenuTrigger, type ActionMenuTriggerProps, AlchemyActionsProvider, type AlchemyActionsProviderProps, type AlchemyActionsValue, useAlchemyActions, useRegisterActionProvider };