@ai-matrx/alchemy 0.6.2 → 0.8.2

package/dist/react-palette.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/react-palette.ts","../src/react/palette.tsx","../src/menu/layouts.ts","../src/react/engine.tsx","../src/declare/sensitivity.ts","../src/actions/projection.ts","../src/actions/run.ts","../src/menu/model.ts","../src/react/context.ts"],"sourcesContent":["/** `@ai-matrx/alchemy/react/palette` — the command palette layout. */\nexport { ActionPalette, type ActionPaletteProps } from \"./react/palette\";\n","\"use client\";\n/**\n * `@ai-matrx/alchemy/react/palette` — the command palette layout (Linear):\n * every leaf of the one model, flattened with its breadcrumb, type to filter.\n */\nimport * as React from \"react\";\nimport { CommandDialog, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList } from \"@ai-matrx/design-system\";\nimport { palette } from \"../menu/layouts\";\nimport type { ClickTarget } from \"../actions/types\";\nimport { useMenuEngine, type MenuEngineOptions } from \"./engine\";\n\nexport interface ActionPaletteProps extends MenuEngineOptions {\n  target: ClickTarget;\n  open: boolean;\n  onOpenChange(open: boolean): void;\n  placeholder?: string;\n}\n\nexport function ActionPalette({ target, open, onOpenChange, placeholder = \"Search actions…\", ...options }: ActionPaletteProps): React.ReactElement {\n  const engine = useMenuEngine(target, {\n    ...options,\n    active: open,\n    onRan: (id, r) => {\n      options.onRan?.(id, r);\n      onOpenChange(false);\n    },\n  });\n  const arranged = engine.model ? palette(engine.model) : { leaves: [] };\n  return (\n    <CommandDialog open={open} onOpenChange={onOpenChange}>\n      <CommandInput placeholder={placeholder} />\n      <CommandList data-alchemy-layout=\"palette\">\n        <CommandEmpty>No action matches.</CommandEmpty>\n        <CommandGroup>\n          {arranged.leaves.map(({ node, breadcrumb }) => {\n            const unavailable = node.kind === \"item\" ? node.unavailable : undefined;\n            return (\n              <CommandItem\n                key={node.id}\n                value={`${node.label} ${breadcrumb.join(\" \")} ${node.id}`}\n                data-alchemy-node={node.id}\n                disabled={Boolean(unavailable)}\n                onSelect={() => {\n                  if (node.kind === \"submenu\") void engine.expand(node.id);\n                  else if (node.kind === \"link\") window.location.assign(node.href);\n                  else void engine.run(node.id);\n                }}\n                className=\"gap-2\"\n              >\n                {\"icon\" in node ? engine.icon(node.icon) : null}\n                <span className=\"flex-1 truncate\">{node.label}</span>\n                <span className=\"text-xs text-muted-foreground\">{unavailable ? unavailable.sentence : breadcrumb.join(\" › \")}</span>\n              </CommandItem>\n            );\n          })}\n        </CommandGroup>\n      </CommandList>\n    </CommandDialog>\n  );\n}\n\nexport default ActionPalette;\n","/**\n * Layouts — pure arrangements of one MenuModel (CONTRACT §2.5).\n *\n * Every layout is a function over the SAME model: it decides which nodes sit\n * at the top level, which fold under a named submenu and which go into a\n * strip. None adds, drops or renames a leaf — `leafIds(arranged)` equals\n * `leafIds(model)` for every layout (THE LOSSLESS LAW, proven by test).\n *\n * The clipboard group IS the universal verb strip: in the strip layouts it is\n * drawn icon-only; elsewhere its rows are drawn in place. Unavailable verbs\n * (the only greyed nodes, R1 c) appear in every layout identically.\n */\nimport type {\n  ArrangedBar,\n  ArrangedContext,\n  ArrangedPalette,\n  ArrangedSelectionToolbar,\n  ArrangedSheet,\n  ContextArrangement,\n  MenuLeafNode,\n  MenuModel,\n  MenuNode,\n  MenuSection,\n  MenuSubmenuNode,\n} from \"./types\";\n\n/** A section with more rows than this folds under its label in tiered/command/sheet. */\nexport const INLINE_SECTION_MAX = 3;\n\n/**\n * A section's heading is ONLY the name its actions declare (an approved\n * heading the classic menu already uses: \"Save as\", \"Copy as\", \"History\").\n * A group with no declared name has no heading and is never folded — its rows\n * show inline. The package never coins a heading (chair ruling, ALC-15).\n */\nexport function sectionLabel(section: MenuSection): string | null {\n  return section.label ?? null;\n}\n\nfunction isLeaf(node: MenuNode): node is MenuLeafNode {\n  return node.kind === \"item\" || node.kind === \"checkbox\" || node.kind === \"link\";\n}\n\n/** Every actionable id in a node list, depth-first. A lazy submenu counts as one leaf. */\nfunction collect(nodes: readonly MenuNode[], out: string[]): void {\n  for (const n of nodes) {\n    if (isLeaf(n)) out.push(n.id);\n    else if (n.kind === \"submenu\") {\n      if (n.lazy) out.push(n.id);\n      else collect(n.children, out);\n    }\n  }\n}\n\ntype Arranged =\n  | MenuModel\n  | ArrangedBar\n  | ArrangedContext\n  | ArrangedSheet\n  | ArrangedPalette\n  | ArrangedSelectionToolbar\n  | MenuSection[];\n\n/** Proof obligation for every layout: its leaf set equals the model's (sorted, de-duplicated). */\nexport function leafIds(arranged: Arranged): readonly string[] {\n  const out: string[] = [];\n  if (Array.isArray(arranged)) {\n    for (const s of arranged) collect(s.nodes, out);\n  } else if (\"leaves\" in arranged) {\n    for (const l of arranged.leaves) out.push(l.node.id);\n  } else if (\"primary\" in arranged && \"overflow\" in arranged) {\n    collect(arranged.primary, out);\n    for (const s of arranged.overflow) collect(s.nodes, out);\n  } else if (\"root\" in arranged) {\n    collect(arranged.strip, out);\n    collect(arranged.root, out);\n  } else if (\"more\" in arranged) {\n    collect(arranged.strip, out);\n    for (const s of arranged.more) collect(s.nodes, out);\n  } else if (\"filterable\" in arranged) {\n    collect(arranged.strip, out);\n    for (const s of arranged.sections) collect(s.nodes, out);\n  } else {\n    for (const s of arranged.sections) collect(s.nodes, out);\n  }\n  return [...new Set(out)].sort();\n}\n\n/** Only a NAMED section folds; callers check `section.label` first. */\nfunction fold(section: MenuSection & { label: string }): MenuSubmenuNode {\n  return {\n    kind: \"submenu\",\n    id: `${section.id}:fold`,\n    label: section.label,\n    ...(section.icon !== undefined ? { icon: section.icon } : {}),\n    children: section.nodes,\n  };\n}\n\nfunction rowCount(nodes: readonly MenuNode[]): number {\n  return nodes.filter((n) => n.kind !== \"separator\" && n.kind !== \"label\").length;\n}\n\nfunction stripOf(model: MenuModel): MenuLeafNode[] {\n  const clipboard = model.sections.find((s) => s.group === \"clipboard\" && !s.primary);\n  return clipboard ? clipboard.nodes.filter(isLeaf) : [];\n}\n\nfunction clipboardRest(model: MenuModel): MenuNode[] {\n  const clipboard = model.sections.find((s) => s.group === \"clipboard\" && !s.primary);\n  return clipboard ? clipboard.nodes.filter((n) => !isLeaf(n) && n.kind === \"submenu\") : [];\n}\n\nfunction placementOf(node: MenuNode): \"primary\" | \"overflow\" | \"both\" {\n  return \"placement\" in node && node.placement ? node.placement : \"overflow\";\n}\n\n/** The historical flat column: every section top-level. */\nfunction classic(model: MenuModel): ArrangedContext {\n  return { strip: [], sections: model.sections, filterable: false };\n}\n\n/**\n * Tiered / command: the universal verbs as an icon strip; every other row by\n * its own name; the clicked target's (primary) section first, inline, heading\n * kept; a long non-primary section folds under ITS OWN label (never a coined\n * heading); History is the one approved grouping and already a group.\n */\nfunction tiered(model: MenuModel, filterable: boolean): ArrangedContext {\n  const strip = stripOf(model);\n  const hierarchical = model.sections.some((s) => s.primary);\n  const sections: MenuSection[] = [];\n  const rest = clipboardRest(model);\n  for (const s of model.sections) {\n    if (s.group === \"clipboard\" && !s.primary) {\n      if (rest.length) sections.push({ ...s, nodes: rest });\n      continue;\n    }\n    if (s.primary) {\n      sections.push(s);\n      continue;\n    }\n    if (!s.label || s.group === \"surface-info\" || rowCount(s.nodes) <= INLINE_SECTION_MAX) {\n      if (hierarchical) sections.push(s);\n      else {\n        const { label: _label, ...unlabelled } = s;\n        sections.push(unlabelled);\n      }\n      continue;\n    }\n    sections.push({ id: s.id, group: s.group, nodes: [fold({ ...s, label: s.label })] });\n  }\n  return { strip, sections, filterable };\n}\n\nexport function context(model: MenuModel, arrangement: ContextArrangement): ArrangedContext {\n  if (arrangement === \"classic\") return classic(model);\n  return tiered(model, arrangement === \"command\");\n}\n\n/**\n * A long NAMED section folds under its own name (\"Save as ▸\", \"Copy as ▸\");\n * primary sections and unnamed groups stay inline. Folding moves rows, never\n * renames or drops them, and never under a coined heading.\n */\nfunction foldNamed(sections: readonly MenuSection[]): MenuSection[] {\n  return sections.map((s) =>\n    s.label && !s.primary && rowCount(s.nodes) > INLINE_SECTION_MAX ? { id: s.id, group: s.group, nodes: [fold({ ...s, label: s.label })] } : s,\n  );\n}\n\n/** ⋯ overflow: every section in classic order; long named sections fold under their own name. */\nexport function overflow(model: MenuModel): MenuSection[] {\n  return foldNamed(model.sections);\n}\n\n/**\n * The action bar: primary buttons inline, EVERYTHING else under ⋯. A \"both\"\n * action is mirrored in both halves (the leaf set is still the model's).\n * `mini` changes presentation only (icon-only primaries), never membership.\n */\nexport function bar(model: MenuModel, _options: { mini?: boolean } = {}): ArrangedBar {\n  const primary: MenuNode[] = [];\n  const overflowSections: MenuSection[] = [];\n  for (const s of model.sections) {\n    const rest: MenuNode[] = [];\n    for (const n of s.nodes) {\n      if (n.kind === \"separator\" || n.kind === \"label\") {\n        rest.push(n);\n        continue;\n      }\n      const p = placementOf(n);\n      if (p === \"primary\" || p === \"both\") primary.push(n);\n      if (p === \"overflow\" || p === \"both\") rest.push(n);\n    }\n    if (rowCount(rest) > 0) overflowSections.push({ ...s, nodes: rest });\n  }\n  return { primary, overflow: foldNamed(overflowSections) };\n}\n\n/** Selection toolbar: the verbs plus primary actions as a strip; the rest under More. */\nexport function selectionToolbar(model: MenuModel): ArrangedSelectionToolbar {\n  const strip: MenuNode[] = [];\n  const more: MenuSection[] = [];\n  for (const s of model.sections) {\n    const rest: MenuNode[] = [];\n    for (const n of s.nodes) {\n      const inStrip = (s.group === \"clipboard\" && !s.primary && isLeaf(n)) || placementOf(n) !== \"overflow\";\n      if (inStrip) strip.push(n);\n      else rest.push(n);\n    }\n    if (rowCount(rest) > 0) more.push({ ...s, nodes: rest });\n  }\n  return { strip, more };\n}\n\n/**\n * Mobile bottom sheet: the verb strip on top; primary and short sections\n * inline; longer sections become one drill-down row named by the section.\n * Consumes the model directly, so it can never drift from desktop.\n */\nexport function sheet(model: MenuModel): ArrangedSheet {\n  const strip = stripOf(model);\n  const root: MenuNode[] = [];\n  const rest = clipboardRest(model);\n  for (const s of model.sections) {\n    const nodes = s.group === \"clipboard\" && !s.primary ? rest : s.nodes;\n    if (rowCount(nodes) === 0) continue;\n    if (root.length) root.push({ kind: \"separator\", id: `${s.id}:sep` });\n    if (s.primary || !s.label || rowCount(nodes) <= INLINE_SECTION_MAX) {\n      if (s.label) root.push({ kind: \"label\", id: `${s.id}:label`, label: s.label });\n      root.push(...nodes);\n    } else {\n      root.push(fold({ ...s, label: s.label, nodes }));\n    }\n  }\n  return { strip, root };\n}\n\n/** Command palette: every leaf flattened with its breadcrumb (Linear). */\nexport function palette(model: MenuModel): ArrangedPalette {\n  const leaves: ArrangedPalette[\"leaves\"] = [];\n  const walk = (nodes: readonly MenuNode[], trail: string[]) => {\n    for (const n of nodes) {\n      if (isLeaf(n)) leaves.push({ node: n, breadcrumb: trail });\n      else if (n.kind === \"submenu\") {\n        if (n.lazy) leaves.push({ node: n, breadcrumb: trail });\n        else walk(n.children, [...trail, n.label]);\n      }\n    }\n  };\n  for (const s of model.sections) walk(s.nodes, s.label ? [s.label] : []);\n  return { leaves };\n}\n\n/** Filter the palette by a query (every word must match label or breadcrumb). */\nexport function filterPalette(arranged: ArrangedPalette, query: string): ArrangedPalette {\n  const words = query.toLowerCase().split(/\\s+/).filter(Boolean);\n  if (!words.length) return arranged;\n  return {\n    leaves: arranged.leaves.filter((l) => {\n      const hay = `${l.node.label} ${l.breadcrumb.join(\" \")}`.toLowerCase();\n      return words.every((w) => hay.includes(w));\n    }),\n  };\n}\n\nexport const layouts = { bar, overflow, context, selectionToolbar, sheet, palette };\n","\"use client\";\n/**\n * The React half of T1e: one hook every renderer uses to resolve the registry\n * at a target, build the model and run a node. Handlers never live in a\n * renderer — they live in providers and run through `runAction`.\n *\n * The context object is shared through globalThis so every per-layout entry\n * (each bundled separately) reads the same provider (module state is banned\n * across dual-loader graphs).\n */\nimport * as React from \"react\";\nimport { runAction, type RunResult } from \"../actions/run\";\nimport type { ProjectionSource } from \"../actions/projection\";\nimport type { Action, ClickTarget, ResolveRestriction, ResolvedAction } from \"../actions/types\";\nimport { actionToNode, buildMenuModel, findNode, withExpandedChildren } from \"../menu/model\";\nimport type { MenuModel, MenuNode } from \"../menu/types\";\nimport { useAlchemyActions } from \"./context\";\n\nexport interface MenuEngineOptions {\n  restrict?: ResolveRestriction;\n  /** Raw sources for projection (the host's mounted surface / clicked item). */\n  source?: ProjectionSource;\n  /** Content the menu acts on when nothing is selected (header text). */\n  content?: string | null;\n  contentFingerprint?: string;\n  /** Called after a node ran (close the menu, announce). */\n  onRan?: (nodeId: string, result: RunResult) => void;\n  /** Resolve only while true (renderers resolve on open). Default true. */\n  active?: boolean;\n  /**\n   * Re-resolve when this changes even if the target object is the same (a\n   * host that keeps one target per mount and reads live state through it).\n   */\n  revision?: string | number;\n}\n\nexport interface MenuEngine {\n  model: MenuModel | null;\n  resolved: readonly ResolvedAction[];\n  run(nodeId: string): Promise<RunResult | null>;\n  expand(nodeId: string): Promise<void>;\n  /** The host's glyph for a key; `tone` is the action's colour class (iconTone). */\n  icon(key: string | undefined, tone?: string): React.ReactNode;\n}\n\nexport function useMenuEngine(target: ClickTarget | null, options: MenuEngineOptions = {}): MenuEngine {\n  const { registry, ports } = useAlchemyActions();\n  const [resolved, setResolved] = React.useState<readonly ResolvedAction[]>([]);\n  const [model, setModel] = React.useState<MenuModel | null>(null);\n  const [tick, setTick] = React.useState(0);\n  const expanded = React.useRef(new Map<string, Action>());\n  const active = options.active ?? true;\n  const optionsRef = React.useRef(options);\n  optionsRef.current = options;\n\n  React.useEffect(() => registry.subscribe(() => setTick((t) => t + 1)), [registry]);\n\n  React.useEffect(() => {\n    if (!target || !active) return;\n    let live = true;\n    void registry.resolve(target, optionsRef.current.restrict).then((list) => {\n      if (!live) return;\n      expanded.current.clear();\n      setResolved(list);\n      setModel(buildMenuModel(target, list, { ...(ports.i18n ? { i18n: ports.i18n } : {}), content: optionsRef.current.content ?? null }));\n    });\n    return () => {\n      live = false;\n    };\n  }, [registry, ports, target, active, tick, options.revision]);\n\n  // Live toggles (read-aloud, thumbs): re-build when an action's store changes.\n  React.useEffect(() => {\n    if (!target) return;\n    const offs = resolved\n      .map((r) => r.action.subscribe?.(() => setTick((t) => t + 1), target))\n      .filter((off): off is () => void => typeof off === \"function\");\n    return () => offs.forEach((off) => off());\n  }, [resolved, target]);\n\n  const findAction = React.useCallback(\n    (id: string): Action | undefined => resolved.find((r) => r.action.id === id)?.action ?? expanded.current.get(id),\n    [resolved],\n  );\n\n  const run = React.useCallback(\n    async (nodeId: string) => {\n      if (!target || !model) return null;\n      const node = model.sections.map((s) => findNode(s.nodes, nodeId)).find(Boolean) ?? null;\n      const action = findAction(node && \"actionId\" in node && node.actionId ? node.actionId : nodeId);\n      if (!action) return null;\n      const o = optionsRef.current;\n      const result = await runAction(action, target, {\n        ports,\n        ...(o.source ? { source: o.source } : {}),\n        ...(o.contentFingerprint ? { contentFingerprint: o.contentFingerprint } : {}),\n      });\n      o.onRan?.(nodeId, result);\n      return result;\n    },\n    [target, model, findAction, ports],\n  );\n\n  const expand = React.useCallback(\n    async (nodeId: string) => {\n      const action = findAction(nodeId);\n      if (!target || !action?.expand) return;\n      setModel((m) => (m ? withExpandedChildren(m, nodeId, \"loading\") : m));\n      try {\n        const children = await action.expand(target, new AbortController().signal);\n        const nodes: MenuNode[] = children.map((child) => {\n          expanded.current.set(child.id, child);\n          return actionToNode({ action: child, eligibility: { status: \"available\" } }, target, ports.i18n ? { i18n: ports.i18n } : {});\n        });\n        setModel((m) => (m ? withExpandedChildren(m, nodeId, nodes) : m));\n      } catch (error) {\n        ports.diagnostics.capture(error, { area: \"menu\", detail: { nodeId, stage: \"expand\" } });\n        setModel((m) => (m ? withExpandedChildren(m, nodeId, []) : m));\n      }\n    },\n    [findAction, target, ports],\n  );\n\n  const icon = React.useCallback(\n    (key: string | undefined, tone?: string): React.ReactNode => {\n      if (!key || !ports.icons) return null;\n      const Resolved = ports.icons.resolve(key) as React.ComponentType<{ className?: string; \"aria-hidden\"?: boolean }> | null;\n      return Resolved ? <Resolved className={`h-4 w-4 shrink-0 ${tone ?? \"\"}`} aria-hidden /> : null;\n    },\n    [ports.icons],\n  );\n\n  return { model, resolved, run, expand, icon };\n}\n","/**\n * Sensitivity defaults and resolution (CONTRACT §2.1). Its own module so the\n * lightweight entries (`/actions`, the T0 React host) can project without\n * pulling the declaration registry.\n */\nimport type { DeclaredValue, Sensitivity } from \"./types\";\n\nexport const DEFAULT_SENSITIVITY: Sensitivity = Object.freeze({\n  exportable: true,\n  classification: \"ordinary\",\n  includedByDefault: true,\n});\n\nexport function resolveSensitivity(value: Pick<DeclaredValue, \"sensitivity\">): Sensitivity {\n  return {\n    exportable: value.sensitivity?.exportable ?? DEFAULT_SENSITIVITY.exportable,\n    classification: value.sensitivity?.classification ?? DEFAULT_SENSITIVITY.classification,\n    includedByDefault: value.sensitivity?.includedByDefault ?? DEFAULT_SENSITIVITY.includedByDefault,\n  };\n}\n","/**\n * PROJECTION BEFORE PROVIDERS (CONTRACT §2.4).\n *\n * The only place a raw read (`MountedSurface.readValues`,\n * `InternalResolvedItem.readValues`) is consumed on behalf of an action.\n * What leaves is projected: a value is kept only when it is DECLARED, its\n * classification is \"ordinary\" and it is exportable. Everything removed is\n * recorded as an omission, so the person and the agent can see what was held\n * back. No caller can relax this.\n */\nimport { resolveSensitivity } from \"../declare/sensitivity\";\nimport type { InternalResolvedItem, MountedSurface } from \"../declare/host\";\nimport type { DeclaredValue, Json, LiveValues, ResolvedSurfaceDeclaration } from \"../declare/types\";\nimport type { ProjectedReads, ReadOmission } from \"./types\";\n\nexport interface ProjectionSource {\n  surface: MountedSurface | null;\n  declaration: ResolvedSurfaceDeclaration | null;\n  item: InternalResolvedItem | null;\n}\n\nfunction toJson(value: unknown): Json | undefined {\n  if (value === undefined || typeof value === \"function\" || typeof value === \"symbol\") return undefined;\n  if (value === null || typeof value === \"string\" || typeof value === \"boolean\") return value;\n  if (typeof value === \"number\") return Number.isFinite(value) ? value : null;\n  if (typeof value === \"bigint\") return value.toString();\n  if (value instanceof Date) return value.toISOString();\n  if (Array.isArray(value)) return value.map((v) => toJson(v) ?? null);\n  if (typeof value === \"object\") {\n    const out: { [key: string]: Json } = {};\n    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {\n      const j = toJson(v);\n      if (j !== undefined) out[k] = j;\n    }\n    return out;\n  }\n  return undefined;\n}\n\n/** Keep declared, ordinary, exportable values; record every removal. */\nexport function projectValues(\n  raw: Record<string, unknown>,\n  declared: readonly Pick<DeclaredValue, \"name\" | \"sensitivity\">[],\n  pathPrefix = \"\",\n): { values: Record<string, Json>; omissions: ReadOmission[] } {\n  const byName = new Map(declared.map((d) => [d.name, d]));\n  const values: Record<string, Json> = {};\n  const omissions: ReadOmission[] = [];\n  for (const [name, value] of Object.entries(raw)) {\n    const path = pathPrefix ? `${pathPrefix}.${name}` : name;\n    const decl = byName.get(name);\n    if (!decl) {\n      omissions.push({ path, reason: \"filtered\" });\n      continue;\n    }\n    const sensitivity = resolveSensitivity(decl);\n    if (sensitivity.classification !== \"ordinary\") {\n      omissions.push({ path, reason: \"excluded\", classification: sensitivity.classification });\n      continue;\n    }\n    if (!sensitivity.exportable) {\n      omissions.push({ path, reason: \"excluded\" });\n      continue;\n    }\n    const json = toJson(value);\n    if (json === undefined) continue;\n    values[name] = json;\n  }\n  return { values, omissions };\n}\n\nexport function createProjectedReads(source: ProjectionSource): ProjectedReads {\n  return {\n    async values(signal) {\n      if (!source.surface || !source.declaration) return { values: {}, omissions: [] };\n      const raw = await source.surface.readValues(signal);\n      const screenValues = source.declaration.values;\n      return projectValues(raw, screenValues);\n    },\n    async item(signal) {\n      const item = source.item;\n      if (!item || !source.declaration) return null;\n      const type = source.declaration.itemTypes?.find((t) => t.name === item.itemType);\n      if (!type) return { values: {}, omissions: [{ path: item.itemType, reason: \"filtered\" }] };\n      const raw = await item.readValues(signal);\n      return projectValues(raw, type.values, item.itemType);\n    },\n    async live(signal): Promise<LiveValues> {\n      if (!source.surface?.readLive) return {};\n      return source.surface.readLive(signal);\n    },\n  };\n}\n","/**\n * The one run path (T1e). Every layout runs an action through here, so the\n * sign-in-then-resume rule, projection and failure capture live once.\n */\nimport type { TransferOutcome } from \"@ai-matrx/kit/content-transfer\";\nimport type { AlchemyHostPorts } from \"../ports\";\nimport { createProjectedReads, type ProjectionSource } from \"./projection\";\nimport type { Action, ClickTarget } from \"./types\";\n\nexport interface RunActionOptions {\n  ports: AlchemyHostPorts;\n  /** Raw sources; projected before the action sees them. */\n  source?: ProjectionSource;\n  /** Stable fingerprint of the content, for sign-in-then-resume. */\n  contentFingerprint?: string;\n  signal?: AbortSignal;\n}\n\nexport type RunResult =\n  | { status: \"ran\"; outcome: TransferOutcome | void }\n  | { status: \"auth-pending\" }\n  | { status: \"failed\"; error: unknown };\n\nexport async function runAction(action: Action, target: ClickTarget, options: RunActionOptions): Promise<RunResult> {\n  const { ports } = options;\n  if (action.requiresAuth && !target.auth.authenticated) {\n    if (!ports.auth) {\n      // Unreachable through resolve (the action is absent without the port); guard direct callers.\n      ports.diagnostics.capture(new Error(`requiresAuth action \"${action.id}\" ran signed out with no auth port`), {\n        area: \"actions\",\n        detail: { actionId: action.id },\n      });\n      return { status: \"failed\", error: new Error(\"sign-in unavailable\") };\n    }\n    ports.auth.signInThenResume({ actionId: action.id, contentFingerprint: options.contentFingerprint ?? action.id });\n    return { status: \"auth-pending\" };\n  }\n  const reads = createProjectedReads(options.source ?? { surface: null, declaration: target.declaration, item: null });\n  const signal = options.signal ?? new AbortController().signal;\n  try {\n    const outcome = await action.run(target, { reads, ports, signal });\n    return { status: \"ran\", outcome };\n  } catch (error) {\n    ports.diagnostics.capture(error, { area: \"actions\", detail: { actionId: action.id, stage: \"run\" } });\n    const label = typeof action.label === \"string\" ? action.label : action.id;\n    ports.notify?.error(`${label} did not finish.`, \"Try again; if it keeps failing, report it from the feedback button.\");\n    return { status: \"failed\", error };\n  }\n}\n","/**\n * buildMenuModel — WHAT exists at a click target, as one framework-neutral\n * tree (CONTRACT §2.5). Categories GROUP, never gate: eligibility already ran\n * in the registry; this only arranges the resolved set into sections.\n */\nimport type { ActionCategory, ClickTarget, ResolvedAction } from \"../actions/types\";\nimport type { I18nPort } from \"../ports\";\nimport type { MenuGroup, MenuModel, MenuNode, MenuSection, MenuSubmenuNode } from \"./types\";\n\n/** THE category → menu group table (CONTRACT §2.5). */\nexport const CATEGORY_GROUP: Readonly<Record<ActionCategory, MenuGroup>> = {\n  clipboard: \"clipboard\",\n  copy: \"transfer\",\n  export: \"transfer\",\n  save: \"document\",\n  share: \"document\",\n  edit: \"editable\",\n  history: \"history\",\n  ai: \"ai\",\n  ask: \"ai\",\n  listen: \"tools\",\n  study: \"tools\",\n  app: \"tools\",\n  feedback: \"quick\",\n  creator: \"admin\",\n  admin: \"admin\",\n  \"surface-info\": \"surface-info\",\n};\n\n/** Classic order of the groups. `surface-info` is engine-built and always last. */\nexport const GROUP_ORDER: readonly MenuGroup[] = [\n  \"clipboard\",\n  \"editable\",\n  \"transfer\",\n  \"document\",\n  \"history\",\n  \"ai\",\n  \"tools\",\n  \"quick\",\n  \"surface\",\n  \"admin\",\n  \"surface-info\",\n];\n\nconst CATEGORY_ORDER: readonly ActionCategory[] = [\n  \"clipboard\",\n  \"edit\",\n  \"copy\",\n  \"export\",\n  \"save\",\n  \"share\",\n  \"history\",\n  \"ask\",\n  \"ai\",\n  \"listen\",\n  \"study\",\n  \"app\",\n  \"feedback\",\n  \"creator\",\n  \"admin\",\n  \"surface-info\",\n];\n\nexport interface BuildMenuModelOptions {\n  i18n?: I18nPort;\n  /** Content the menu acts on when nothing is selected. */\n  content?: string | null;\n}\n\nfunction translate(i18n: I18nPort | undefined, key: string, fallback: string): string {\n  if (!i18n) return fallback;\n  try {\n    return i18n.t(key, fallback);\n  } catch {\n    return fallback;\n  }\n}\n\n/** One resolved action → one model node (item, checkbox, link or lazy submenu). */\nexport function actionToNode(\n  resolved: ResolvedAction,\n  target: ClickTarget,\n  options: BuildMenuModelOptions = {},\n): MenuNode {\n  const { action, eligibility } = resolved;\n  const rawLabel = typeof action.label === \"function\" ? action.label(target) : action.label;\n  const label = translate(options.i18n, action.labelKey ?? action.id, rawLabel);\n  const base = {\n    id: action.id,\n    actionId: action.id,\n    ...(action.icon !== undefined ? { icon: action.icon } : {}),\n    ...(action.placement !== undefined ? { placement: action.placement } : {}),\n  };\n  if (action.expand) {\n    const node: MenuSubmenuNode = {\n      ...base,\n      kind: \"submenu\",\n      label,\n      lazy: true,\n      loading: false,\n      children: [],\n      ...(action.emptyLabel !== undefined ? { emptyLabel: action.emptyLabel } : {}),\n    };\n    return node;\n  }\n  if (action.href !== undefined) {\n    const href = typeof action.href === \"function\" ? action.href(target) : action.href;\n    return { ...base, kind: \"link\", label, href };\n  }\n  if (action.toggle) {\n    return {\n      ...base,\n      kind: \"checkbox\",\n      label,\n      checked: action.pressed?.(target) ?? false,\n      ...(action.description !== undefined ? { description: action.description } : {}),\n    };\n  }\n  const state = action.stateIcon?.(target) ?? null;\n  const pressed = action.pressed?.(target);\n  const hint = action.hint !== undefined ? translate(options.i18n, action.hintKey ?? `${action.id}.hint`, action.hint) : undefined;\n  return {\n    ...base,\n    kind: \"item\",\n    label,\n    ...(action.iconTone !== undefined ? { iconTone: action.iconTone } : {}),\n    ...(state ? { stateIcon: state } : {}),\n    ...(action.description !== undefined ? { description: action.description } : {}),\n    ...(hint !== undefined ? { hint } : {}),\n    ...(pressed !== undefined ? { pressed } : {}),\n    ...(action.destructive ? { destructive: true } : {}),\n    ...(action.preserveSelection ? { preserveSelection: true } : {}),\n    ...(eligibility.status === \"unavailable-verb\" ? { unavailable: { sentence: eligibility.sentence } } : {}),\n  };\n}\n\nexport function buildMenuModel(\n  target: ClickTarget,\n  resolved: readonly ResolvedAction[],\n  options: BuildMenuModelOptions = {},\n): MenuModel {\n  const ordered = resolved\n    .map((r, index) => ({ r, index }))\n    .sort((a, b) => {\n      const ca = CATEGORY_ORDER.indexOf(a.r.action.category);\n      const cb = CATEGORY_ORDER.indexOf(b.r.action.category);\n      if (ca !== cb) return ca - cb;\n      const oa = a.r.action.order ?? 0;\n      const ob = b.r.action.order ?? 0;\n      if (oa !== ob) return oa - ob;\n      return a.index - b.index;\n    })\n    .map((x) => x.r);\n\n  const sections = new Map<string, MenuSection>();\n  const roles: Record<string, string> = {};\n  // An explicit section sits in the group of its first-registered action and\n  // keeps its own row order (order, then registration) across categories.\n  const explicit = new Map<string, { group: MenuGroup; rows: { r: ResolvedAction; index: number }[] }>();\n  resolved.forEach((r, index) => {\n    const sec = r.action.section;\n    if (!sec) return;\n    const entry = explicit.get(sec.id) ?? { group: CATEGORY_GROUP[r.action.category], rows: [] };\n    entry.rows.push({ r, index });\n    explicit.set(sec.id, entry);\n  });\n  const placed = new Set<string>();\n  for (const r of ordered) {\n    const sec = r.action.section;\n    if (sec && placed.has(sec.id)) continue;\n    const group = sec ? (explicit.get(sec.id)?.group ?? CATEGORY_GROUP[r.action.category]) : CATEGORY_GROUP[r.action.category];\n    const sectionId = sec ? `section:${sec.id}` : group;\n    let section = sections.get(sectionId);\n    if (!section) {\n      section = {\n        id: sectionId,\n        group,\n        nodes: [],\n        ...(sec ? { label: translate(options.i18n, sec.labelKey ?? `section.${sec.id}`, sec.label) } : {}),\n        ...(sec?.icon !== undefined ? { icon: sec.icon } : {}),\n        ...(sec?.primary ? { primary: true } : {}),\n      };\n      sections.set(sectionId, section);\n    }\n    const rows = sec\n      ? (explicit.get(sec.id)?.rows ?? [])\n          .sort((x, y) => (x.r.action.order ?? 0) - (y.r.action.order ?? 0) || x.index - y.index)\n          .map((x) => x.r)\n      : [r];\n    if (sec) placed.add(sec.id);\n    for (const row of rows) {\n      section.nodes.push(actionToNode(row, target, options));\n      if (row.action.verb) roles[row.action.verb] = row.action.id;\n    }\n  }\n\n  const list = [...sections.values()].sort((a, b) => {\n    if (Boolean(a.primary) !== Boolean(b.primary)) return a.primary ? -1 : 1;\n    return GROUP_ORDER.indexOf(a.group) - GROUP_ORDER.indexOf(b.group);\n  });\n\n  const selected = target.selection?.text?.trim();\n  const content = options.content?.trim();\n  const header = selected\n    ? { label: \"Selected\" as const, text: target.selection?.text ?? \"\" }\n    : content\n      ? { label: \"Content\" as const, text: options.content ?? \"\" }\n      : null;\n\n  return { header, sections: list, roles };\n}\n\n/** Fill a lazy submenu's rows once they load (pure: returns a new model). */\nexport function withExpandedChildren(model: MenuModel, nodeId: string, children: MenuNode[] | \"loading\"): MenuModel {\n  const visit = (nodes: MenuNode[]): MenuNode[] =>\n    nodes.map((n) => {\n      if (n.kind !== \"submenu\") return n;\n      if (n.id === nodeId) {\n        return children === \"loading\" ? { ...n, loading: true } : { ...n, lazy: false, loading: false, children };\n      }\n      return { ...n, children: visit(n.children) };\n    });\n  return { ...model, sections: model.sections.map((s) => ({ ...s, nodes: visit(s.nodes) })) };\n}\n\n/** Find a node anywhere in a tree. */\nexport function findNode(nodes: readonly MenuNode[], id: string): MenuNode | null {\n  for (const n of nodes) {\n    if (n.id === id) return n;\n    if (n.kind === \"submenu\") {\n      const hit = findNode(n.children, id);\n      if (hit) return hit;\n    }\n  }\n  return null;\n}\n","/**\n * The shared React context (T0-safe: imports only React and types). Shared\n * through globalThis so every per-layout bundle reads the same provider.\n */\nimport * as React from \"react\";\nimport type { ActionRegistry } from \"../actions/types\";\nimport type { AlchemyHostPorts } from \"../ports\";\n\nexport interface AlchemyActionsValue {\n  registry: ActionRegistry;\n  ports: AlchemyHostPorts;\n}\n\nconst KEY = Symbol.for(\"ai-matrx.alchemy.actions-context\");\ntype Holder = { [KEY]?: React.Context<AlchemyActionsValue | null> };\nexport const AlchemyActionsContext: React.Context<AlchemyActionsValue | null> =\n  ((globalThis as Holder)[KEY] ??= React.createContext<AlchemyActionsValue | null>(null));\n\nexport function useAlchemyActions(): AlchemyActionsValue {\n  const value = React.useContext(AlchemyActionsContext);\n  if (!value) throw new Error(\"Alchemy actions: render inside <AlchemyActionsProvider> (@ai-matrx/alchemy/react/host).\");\n  return value;\n}\n"],"mappings":"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","names":["React","import_jsx_runtime"]}

package/dist/react-palette.d.cts

@@ -0,0 +1,359 @@
+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 = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+/** 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>;
+        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;
+    load(signal: AbortSignal): Promise<Json>;
+}
+interface RecentRequest {
+    method: string;
+    path: string;
+    status: string;
+    httpStatus?: number;
+    durationMs?: number;
+    requestId?: string;
+    client?: string;
+    requestBody?: Json;
+    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 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;
+}
+
+/**
+ * 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`.
+ */
+
+/** 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";
+interface ResolveRestriction {
+    exclude?: readonly string[];
+    categories?: readonly ActionCategory[];
+}
+
+/**
+ * `@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;
+};
+
+/**
+ * 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/palette` — the command palette layout (Linear):
+ * every leaf of the one model, flattened with its breadcrumb, type to filter.
+ */
+
+interface ActionPaletteProps extends MenuEngineOptions {
+    target: ClickTarget;
+    open: boolean;
+    onOpenChange(open: boolean): void;
+    placeholder?: string;
+}
+declare function ActionPalette({ target, open, onOpenChange, placeholder, ...options }: ActionPaletteProps): React.ReactElement;
+
+export { ActionPalette, type ActionPaletteProps };