@ai-matrx/alchemy

Alchemy is Matrx’s content-to-AI toolkit. Alchemy Menu is its small, reusable copy, preparation and export control. This distribution ships the shared core, React controls, CSS and SVG; it contains no parallel implementation. It sits below @ai-matrx/agents and never depends on it.

One menu, ready to use

import { AlchemyMenu } from "@ai-matrx/alchemy/react";
import "@ai-matrx/alchemy/styles.css";

export function TaskActions({ task }: { task: { id: string; title: string; description: string } }) {
  return <AlchemyMenu
    sourceId={`task:${task.id}`}
    label={task.title}
    human={() => task.description}
    json={() => task}
    agent={() => ({
      kind: "task",
      location: "Task detail",
      description: "Current task, including unsaved changes",
      data: task,
    })}
  />;
}

The transparent icon opens ordinary copy, Markdown, formatted HTML with plain-text fallback, JSON, direct AI context, preparation, and downloads. No chevron, icon library or Tailwind build is required. Semantic HSL tokens inherit the host’s Matrx theme; neutral defaults work without one. Set sourceId from the record identity when a mounted control can switch records. Lazy getters run when content is captured.

Preparation supports editable drafts, detail presets, structural reductions, omissions and undo. Supplying table rows adds relevant spreadsheet formats; registered exporters and page actions retain the same captured-source boundary. An absent AI provider leaves manual preparation available without showing dead AI controls.

Portal and Tap Target

Portal is the default mark in every Matrx host. Default glass/transparent controls use the actual Tap Target primitive with sidebar-parity 18px artwork, 1.75 stroke and shell icon colors in a 32px desktop target; coarse pointers retain 44px. Use triggerVariant="glass" in headers and triggerVariant="transparent" for content actions. triggerVariant="outline" uses the canonical outlined Button for dense toolbars (28px target and 16px artwork, matching the Data toolbar). AlchemyMenu sizes xs and toolbar select compact 28px targets with 14px artwork for glass/transparent controls. icon="copy-transform" is an optional package variant; both marks ship as SVG assets. Future host marks extend this typed icon set rather than replacing the trigger or adding page CSS.

import { ContentTransferMenu } from "@ai-matrx/alchemy/react";

<ContentTransferMenu source={{ kind: "markdown", text: content }} />
<ContentTransferMenu source={{ kind: "text", text: title }} triggerVariant="glass" />
// Inside a mounted ContentTransferSurfaceProvider, no source prop is needed:
<ContentTransferMenu />

Even a plain source has format copy/download, a source-labelled AI context envelope, manual editing, detail/character limits, and undo. The authenticated host adds six AI preparation recipes and the available Matrx destinations. Table sources add selection, filtering, sorting, column choice, row limits, CSV/TSV and Excel. A manually edited draft is the content sent to destinations; actions incompatible with its new shape disappear.

Extend the shared menu

The Copy/Download selector uses one format palette. Additional formats use the same tiles; quick copy, preparation, alternate context, and page operations use shared groups. Supply capabilities and descriptors rather than rendering another menu.

• Use human, json, and agent getters for different representations of the same content.
• Use export.sheetRows and export.sheetColumns for a table; spreadsheet formats become available automatically.
• Use export.items[].build for a custom file's bytes, MIME type, extension, and optional filename. It appears in Download. An onSelect callback takes precedence over build and remains a page action.
• Use aiVariants for alternate sources, aiCustom for source settings, and groomer for per-section detail. They enter the same preparation workspace.
• Use the lower-level ContentTransferMenu and its capability provider for format adapters and projected page actions. sourceFormats={false} suppresses source formats in a file/action-only control; an action's placement: "download" places a genuine download in the palette.

Labels and hints wrap within the shared geometry. Preserve stable IDs, eligibility checks, capture boundaries, and honest outcomes. Do not add per-page Copy/Download lists, bypass the shared transport, or restyle the menu for a particular integration.

Table exports and live references

Register tableDataFormat for flat JSON keyed by display labels and tableSchemaFormat for source identity, projected schema and rows. Ordinary JSON retains machine keys; duplicate display labels are disambiguated without dropping values. Both adapters read the current projected draft, including filtering, sorting and visible columns. The readable format also opts Email JSON into that representation.

Supply table.availableScopes, table.initialScope and optional table.scopeLabels with loaders that honestly capture each scope. The preparation workspace retains drafts per scope. Provide references with explicit registered entity identities and a provider reference port that validates and builds the canonical envelope. These are live saved references, independent of content filters and draft edits. referenceActions can open the existing advanced picker. Never infer an entity from a title.

A provider email port enables CSV, JSON and Markdown email actions. The package shows the exact sealed file and adjustments before explicit Send; the host delivers the same filename, MIME and bytes to the authenticated account. Share/access controls stay separate. Standard table copy configuration also accepts references, rowReferences and triggerVariant.

Integrate Matrx services once

The Matrx service adapter lives in @ai-matrx/agents, which sits above Alchemy. Import MatrxContentTransferProvider from @ai-matrx/agents/content-transfer/react, and createMatrxTransferPorts(bindings) / createMatrxTransferActions(ports) from @ai-matrx/agents/content-transfer. The provider accepts the canonical transport, authenticated database read port, current organization getter and source application, and supplies the declared durable AI preparation job to descendant Alchemy menus. Mount it at an identity boundary so changing user or organization cannot reuse another identity’s prepared run. Bind existing Notes, Documents, Workbooks, task, attachment, Code and chat openers once and register the returned actions through the provider's capabilities.actions; menus inherit Save to Matrx and Continue with AI groups.

Openers report that an editor was opened, not that the item was saved. Save-and-attach preserves the created note if the destination picker fails. New-chat/window handoffs attach captured content as a text resource, leave the human composer empty and never auto-run. Connected tools are selected through the existing assistant Chat Options picker; this is not an automatic MCP invocation.

For an exact mounted declared surface, use createSurfaceTransferHandle from /core and ContentTransferSurfaceProvider from /react. Bind its scope getter and mounted predicate to that instance. Never look up a same-named surface globally. Standard Matrx tables include shared row and toolbar controls by default; copy={false} opts out. Custom tables can use the lower-level ContentTransferMenu source/table contract.

Framework-neutral use

import { capture, createDraft, serialize } from "@ai-matrx/alchemy/core";

const { snapshot } = await capture(
  { kind: "text", text: "Hello" },
  new AbortController().signal,
);
const artifact = serialize(createDraft(snapshot), "plain");

| Entry | Exports | |---|---| | /core (also package root) | Capture, projection, preparation, serializers, artifacts and transport. | | /react | AlchemyMenu, lower-level ContentTransferMenu, surface/provider bindings and React glyph. | | /operate write door | createWriteDoor({ ports, declarations }): every write to a declared target (person, menu, destination, agent, applet, automation) returns a Receipt — applied (maybe with a warning), queued or refused with a sentence and a remedy. Bind it as the door host port and register a headless handler per destination. | | /ports | Host port types only (AlchemyHostPorts, KindValidatorPort, DiagnosticsPort, IdentityPort, PersistencePort). A host binds them once at its boundary; an unbound optional port means that capability is absent, never stubbed. | | /actions | The one action registry, plus surface Actions: ActionDeclaration/ActionInfo, projections from write targets, client tools and ui.ui_surface_action rows, resolveActionChain (child wins by name) and the one runner runSurfaceAction (server, mandate, navigate, page). | | /surface | The one SurfacePort runtime: readSurfaceChain(client, surfaceName, { maxDepth?, organizationIds? }) reads a surface's Actions from ui.ui_surface* through the viewer's client (organization extensions apply only to their members), and createSurfacePort(opts) mounts it, holds its values and runs its Actions (page Actions travel on the "actions" stream and are answered with completeAction). | | /checks | The one surface sync. It writes only declared_by: "code" rows and never reports a database-declared row as stale or orphaned. | | /styles.css | Self-contained menu and workspace styling. | | /alchemy.svg, /portal.svg, /copy-transform.svg | Packaged icon assets; Portal is default. |

The registry installation canary requires the sibling kit and design-system releases first, and fails if installing Alchemy pulls in @ai-matrx/agents. Stylesheets import the canonical design-system styling; SVG assets are copied from their one source at build time.