@ai-matrx/alchemy 0.6.2 → 0.8.2

package/dist/menu.d.ts

@@ -0,0 +1,834 @@
+import { TransferOutcome } from '@ai-matrx/kit/content-transfer';
+
+/**
+ * Matrx Alchemy — the menu model (CONTRACT §2.5).
+ *
+ * One model, many layouts. The model is framework-neutral: icons are KEYS,
+ * labels are already translated, nothing holds a handler — a node names its
+ * `actionId` and the engine runs it. Layouts rearrange; they never add, drop
+ * or rename a leaf (the Lossless Law).
+ */
+interface NodeBase {
+    id: string;
+    actionId?: string;
+}
+interface MenuItemNode extends NodeBase {
+    kind: "item";
+    label: string;
+    icon?: string;
+    iconTone?: string;
+    stateIcon?: {
+        icon: string;
+        spin?: boolean;
+    };
+    description?: string;
+    hint?: string;
+    pressed?: boolean;
+    destructive?: boolean;
+    /** Bar layout slot (primary buttons vs ⋯). Default "overflow". */
+    placement?: "primary" | "overflow" | "both";
+    preserveSelection?: boolean;
+    /** Only on the six universal verbs: greyed, the sentence as tooltip. */
+    unavailable?: {
+        sentence: string;
+    };
+}
+interface MenuSubmenuNode extends NodeBase {
+    kind: "submenu";
+    label: string;
+    icon?: string;
+    /** Rows load on open (the action's `expand`). */
+    lazy?: boolean;
+    loading?: boolean;
+    emptyLabel?: string;
+    placement?: "primary" | "overflow" | "both";
+    children: MenuNode[];
+}
+interface MenuCheckboxNode extends NodeBase {
+    kind: "checkbox";
+    label: string;
+    icon?: string;
+    description?: string;
+    checked: boolean;
+    placement?: "primary" | "overflow" | "both";
+}
+interface MenuLinkNode extends NodeBase {
+    kind: "link";
+    label: string;
+    icon?: string;
+    href: string;
+    target?: string;
+    placement?: "primary" | "overflow" | "both";
+}
+interface MenuLabelNode extends NodeBase {
+    kind: "label";
+    label: string;
+}
+interface MenuSeparatorNode extends NodeBase {
+    kind: "separator";
+}
+type MenuNode = MenuItemNode | MenuSubmenuNode | MenuCheckboxNode | MenuLinkNode | MenuLabelNode | MenuSeparatorNode;
+/** A node that does something when chosen. */
+type MenuLeafNode = MenuItemNode | MenuCheckboxNode | MenuLinkNode;
+type MenuGroup = "clipboard" | "tools" | "history" | "document" | "surface" | "ai" | "quick" | "editable" | "admin" | "surface-info" | "transfer";
+interface MenuSection {
+    id: string;
+    group: MenuGroup;
+    label?: string;
+    icon?: string;
+    primary?: boolean;
+    nodes: MenuNode[];
+}
+interface MenuModel {
+    header: {
+        label: "Selected" | "Content";
+        text: string;
+    } | null;
+    /** Classic order. Layouts rearrange; they never add, drop or rename a leaf. */
+    sections: MenuSection[];
+    /** Well-known nodes addressed by role id (the universal verbs by verb), never by label. */
+    roles: Record<string, string>;
+}
+type LayoutName = "bar" | "overflow" | "context" | "selection-toolbar" | "sheet" | "palette";
+type ContextArrangement = "classic" | "tiered" | "command";
+type Density = "comfortable" | "compact";
+interface ArrangedBar {
+    primary: MenuNode[];
+    overflow: MenuSection[];
+}
+interface ArrangedContext {
+    strip: MenuLeafNode[];
+    sections: MenuSection[];
+    filterable: boolean;
+}
+/** Drill-down, path-based. */
+interface ArrangedSheet {
+    strip: MenuLeafNode[];
+    root: MenuNode[];
+}
+/** The command palette (Linear): every leaf with its breadcrumb. */
+interface ArrangedPalette {
+    leaves: {
+        node: MenuLeafNode | MenuSubmenuNode;
+        breadcrumb: string[];
+    }[];
+}
+interface ArrangedSelectionToolbar {
+    strip: MenuNode[];
+    more: MenuSection[];
+}
+
+/**
+ * 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 ResolvedAction {
+    action: Action;
+    eligibility: Exclude<Eligibility, {
+        status: "absent";
+    }>;
+}
+
+/**
+ * buildMenuModel — WHAT exists at a click target, as one framework-neutral
+ * tree (CONTRACT §2.5). Categories GROUP, never gate: eligibility already ran
+ * in the registry; this only arranges the resolved set into sections.
+ */
+
+/** THE category → menu group table (CONTRACT §2.5). */
+declare const CATEGORY_GROUP: Readonly<Record<ActionCategory, MenuGroup>>;
+/** Classic order of the groups. `surface-info` is engine-built and always last. */
+declare const GROUP_ORDER: readonly MenuGroup[];
+interface BuildMenuModelOptions {
+    i18n?: I18nPort;
+    /** Content the menu acts on when nothing is selected. */
+    content?: string | null;
+}
+/** One resolved action → one model node (item, checkbox, link or lazy submenu). */
+declare function actionToNode(resolved: ResolvedAction, target: ClickTarget, options?: BuildMenuModelOptions): MenuNode;
+declare function buildMenuModel(target: ClickTarget, resolved: readonly ResolvedAction[], options?: BuildMenuModelOptions): MenuModel;
+/** Fill a lazy submenu's rows once they load (pure: returns a new model). */
+declare function withExpandedChildren(model: MenuModel, nodeId: string, children: MenuNode[] | "loading"): MenuModel;
+/** Find a node anywhere in a tree. */
+declare function findNode(nodes: readonly MenuNode[], id: string): MenuNode | null;
+
+/**
+ * Layouts — pure arrangements of one MenuModel (CONTRACT §2.5).
+ *
+ * Every layout is a function over the SAME model: it decides which nodes sit
+ * at the top level, which fold under a named submenu and which go into a
+ * strip. None adds, drops or renames a leaf — `leafIds(arranged)` equals
+ * `leafIds(model)` for every layout (THE LOSSLESS LAW, proven by test).
+ *
+ * The clipboard group IS the universal verb strip: in the strip layouts it is
+ * drawn icon-only; elsewhere its rows are drawn in place. Unavailable verbs
+ * (the only greyed nodes, R1 c) appear in every layout identically.
+ */
+
+/** A section with more rows than this folds under its label in tiered/command/sheet. */
+declare const INLINE_SECTION_MAX = 3;
+/**
+ * A section's heading is ONLY the name its actions declare (an approved
+ * heading the classic menu already uses: "Save as", "Copy as", "History").
+ * A group with no declared name has no heading and is never folded — its rows
+ * show inline. The package never coins a heading (chair ruling, ALC-15).
+ */
+declare function sectionLabel(section: MenuSection): string | null;
+type Arranged = MenuModel | ArrangedBar | ArrangedContext | ArrangedSheet | ArrangedPalette | ArrangedSelectionToolbar | MenuSection[];
+/** Proof obligation for every layout: its leaf set equals the model's (sorted, de-duplicated). */
+declare function leafIds(arranged: Arranged): readonly string[];
+declare function context(model: MenuModel, arrangement: ContextArrangement): ArrangedContext;
+/** ⋯ overflow: every section in classic order; long named sections fold under their own name. */
+declare function overflow(model: MenuModel): MenuSection[];
+/**
+ * The action bar: primary buttons inline, EVERYTHING else under ⋯. A "both"
+ * action is mirrored in both halves (the leaf set is still the model's).
+ * `mini` changes presentation only (icon-only primaries), never membership.
+ */
+declare function bar(model: MenuModel, _options?: {
+    mini?: boolean;
+}): ArrangedBar;
+/** Selection toolbar: the verbs plus primary actions as a strip; the rest under More. */
+declare function selectionToolbar(model: MenuModel): ArrangedSelectionToolbar;
+/**
+ * Mobile bottom sheet: the verb strip on top; primary and short sections
+ * inline; longer sections become one drill-down row named by the section.
+ * Consumes the model directly, so it can never drift from desktop.
+ */
+declare function sheet(model: MenuModel): ArrangedSheet;
+/** Command palette: every leaf flattened with its breadcrumb (Linear). */
+declare function palette(model: MenuModel): ArrangedPalette;
+/** Filter the palette by a query (every word must match label or breadcrumb). */
+declare function filterPalette(arranged: ArrangedPalette, query: string): ArrangedPalette;
+declare const layouts: {
+    bar: typeof bar;
+    overflow: typeof overflow;
+    context: typeof context;
+    selectionToolbar: typeof selectionToolbar;
+    sheet: typeof sheet;
+    palette: typeof palette;
+};
+
+/**
+ * N9: layout and density are a PERSON's choice layered over the organization
+ * default: persistence ("alchemy.menu.layout") → knobs.layout(org) → platform
+ * default (command / comfortable, Arman 2026-08-22).
+ */
+
+declare const PLATFORM_MENU_LAYOUT: {
+    context: ContextArrangementKnob;
+    density: DensityKnob;
+};
+declare const MENU_LAYOUT_SETTING = "alchemy.menu.layout";
+declare function resolveMenuLayout(ports: Pick<AlchemyHostPorts, "persistence" | "knobs">, organizationId: string | null): Promise<{
+    context: ContextArrangementKnob;
+    density: DensityKnob;
+}>;
+
+export { type ArrangedBar, type ArrangedContext, type ArrangedPalette, type ArrangedSelectionToolbar, type ArrangedSheet, type BuildMenuModelOptions, CATEGORY_GROUP, type ContextArrangement, type Density, GROUP_ORDER, INLINE_SECTION_MAX, type LayoutName, MENU_LAYOUT_SETTING, type MenuCheckboxNode, type MenuGroup, type MenuItemNode, type MenuLabelNode, type MenuLeafNode, type MenuLinkNode, type MenuModel, type MenuNode, type MenuSection, type MenuSeparatorNode, type MenuSubmenuNode, PLATFORM_MENU_LAYOUT, actionToNode, bar, buildMenuModel, context, filterPalette, findNode, layouts, leafIds, overflow, palette, resolveMenuLayout, sectionLabel, selectionToolbar, sheet, withExpandedChildren };