@agent-native/core 0.113.0 → 0.114.0

package/src/client/blocks/server.ts

@@ -0,0 +1,170 @@
+/**
+ * `@agent-native/core/blocks/server` — the React-free subset of the block
+ * registry for server / agent code (MDX serialize/parse, the registry, schema
+ * introspection, the `markdown()` helper, agent schema export). Importing this
+ * entry never pulls React into the server bundle.
+ *
+ * A `BlockSpec` carries React (`Read`/`Edit`) and pure (`schema`/`mdx`) parts in
+ * the same object; the server path only touches `spec.schema` / `spec.mdx`. The
+ * app's registry module is shared by browser and server, but the server only
+ * ever calls these React-free functions on it.
+ */
+
+export {
+  defineBlock,
+  type BlockSpec,
+  type BlockPlacement,
+  type BlockMdxConfig,
+  type BlockAttrReader,
+  type MdxAttrValue,
+  type NestedBlock,
+} from "./types.js";
+
+export { BlockRegistry, registerBlocks } from "./registry.js";
+
+export {
+  markdown,
+  richtext,
+  introspect,
+  type FieldKind,
+  type FieldDescriptor,
+} from "./schema-form/introspect.js";
+
+export {
+  prop,
+  escapeAttr,
+  jsonExpression,
+  attributeValue,
+  createAttrReader,
+  childCodeFenceFields,
+  serializeChildCodeFenceFields,
+  serializeSpecBlock,
+  parseSpecBlock,
+  type MdxJsxNode,
+  type MdxAttrNode,
+  type SerializableBlock,
+  type ParsedBlockBase,
+} from "./mdx.js";
+
+export {
+  describeBlocksForAgent,
+  renderBlockVocabularyReference,
+  type BlockAgentDoc,
+} from "./agent.js";
+
+// Standard library registration (React-free). Server / shared registries call
+// `registerLibraryBlockConfigs(registry)` to register the whole standard library
+// as `Read: () => null` config stubs in one place, then add their app-specific
+// block configs on top. `libraryBlockConfigs` is the underlying ordered array.
+export {
+  libraryBlockConfigs,
+  registerLibraryBlockConfigs,
+  type LibraryBlockConfigOverrides,
+} from "./library/server-specs.js";
+
+// Standard block library — React-free schema + MDX config only. The React
+// `Read`/`Edit` live in `./library/checklist.tsx` (imported from the full
+// `@agent-native/core/blocks` entry), never from here.
+export {
+  checklistSchema,
+  checklistMdx,
+  type ChecklistData,
+  type ChecklistItem,
+} from "./library/checklist.config.js";
+export {
+  tableSchema,
+  tableMdx,
+  type TableData,
+} from "./library/table.config.js";
+export {
+  codeTabsSchema,
+  codeTabsMdx,
+  type CodeTabsData,
+  type CodeTabsTab,
+} from "./library/code-tabs.config.js";
+export {
+  htmlSchema,
+  htmlMdx,
+  type HtmlBlockData,
+} from "./library/html.config.js";
+export {
+  tabsSchema,
+  tabsMdx,
+  type TabsData,
+  type TabsOrientation,
+  type TabsTab,
+} from "./library/tabs.config.js";
+export {
+  columnsSchema,
+  columnsMdx,
+  type ColumnsData,
+  type ColumnsColumn,
+} from "./library/columns.config.js";
+export {
+  calloutSchema,
+  calloutMdx,
+  CALLOUT_TONES,
+  type CalloutData,
+  type CalloutTone,
+} from "./library/callout.config.js";
+
+// Dev-doc block library — React-free schema + MDX config only. The React
+// `Read`/`Edit` live in the matching `./library/<Name>Block.tsx` (imported from
+// the full `@agent-native/core/blocks` entry), never from here.
+export {
+  mermaidSchema,
+  mermaidMdx,
+  type MermaidData,
+} from "./library/mermaid.config.js";
+export {
+  apiEndpointSchema,
+  apiEndpointMdx,
+  API_ENDPOINT_METHODS,
+  API_PARAM_LOCATIONS,
+  type ApiEndpointData,
+  type ApiEndpointMethod,
+  type ApiEndpointParam,
+  type ApiEndpointRequest,
+  type ApiEndpointResponse,
+  type ApiParamLocation,
+} from "./library/api-endpoint.config.js";
+export {
+  dataModelSchema,
+  dataModelMdx,
+  DATA_MODEL_RELATION_KINDS,
+  type DataModelData,
+  type DataModelEntity,
+  type DataModelField,
+  type DataModelRelation,
+  type DataModelRelationKind,
+} from "./library/data-model.config.js";
+export {
+  diffSchema,
+  diffMdx,
+  type DiffData,
+  type DiffMode,
+} from "./library/diff.config.js";
+export {
+  fileTreeSchema,
+  fileTreeMdx,
+  FILE_TREE_CHANGES,
+  type FileTreeData,
+  type FileTreeEntry,
+  type FileTreeChange,
+} from "./library/file-tree.config.js";
+export {
+  jsonExplorerSchema,
+  jsonExplorerMdx,
+  type JsonExplorerData,
+} from "./library/json-explorer.config.js";
+export {
+  annotatedCodeSchema,
+  annotatedCodeMdx,
+  type AnnotatedCodeData,
+  type AnnotatedCodeAnnotation,
+} from "./library/annotated-code.config.js";
+export {
+  openApiSpecSchema,
+  openApiSpecMdx,
+  type OpenApiSpecData,
+} from "./library/openapi-spec.config.js";

package/src/client/blocks/types.ts

@@ -0,0 +1,415 @@
+import type { FC } from "react";
+import type { ZodType } from "zod";
+
+/**
+ * Block-registry contract. A `BlockSpec` describes one document block end to end:
+ * its data shape (`schema`), how it round-trips to MDX source (`mdx`), how it
+ * renders read-only (`Read`) and how it is edited (`Edit`, or an auto-generated
+ * schema-driven editor when omitted), where it can be placed (`placement`), and
+ * metadata for menus / agent schema export.
+ *
+ * The registry runs ALONGSIDE existing per-block code (the plan `PlanBlockView`
+ * switch + `serializeBlock`/`parseBlock`). Renderers check the registry first;
+ * unregistered block types fall through to the legacy code path unchanged. The
+ * MDX `tag` and attribute shape for a converted block MUST match the historical
+ * encoding (e.g. `<Callout tone>…body…</Callout>`) so stored `.mdx` files still
+ * parse byte-compatibly.
+ */
+
+/** Where a block can be placed in a document. */
+export type BlockPlacement = "block" | "inline";
+
+/** How visual blocks decide whether to draw an outer surface frame. */
+export type BlockVisualFrame = "auto" | "show" | "hide";
+
+/**
+ * A serialized MDX/NFM attribute value before the shared `prop()` encoder runs.
+ * `prop()` decides string-vs-JSON encoding; this is just the value domain.
+ */
+export type MdxAttrValue =
+  | string
+  | number
+  | boolean
+  | unknown[]
+  | Record<string, unknown>;
+
+/**
+ * Type-narrowed reader over the resolved MDX attributes of a parsed block node.
+ * The values are already estree/JSON-resolved by the shared attribute reader
+ * (the same engine `plan-mdx.ts` uses), so a spec's `fromAttrs` never touches
+ * the AST directly.
+ */
+export interface BlockAttrReader {
+  string(name: string): string | undefined;
+  number(name: string): number | undefined;
+  bool(name: string): boolean | undefined;
+  array<T = unknown>(name: string): T[] | undefined;
+  object<T = unknown>(name: string): T | undefined;
+  raw(name: string): unknown;
+}
+
+/**
+ * Maps a block's validated data to/from its MDX component representation.
+ * `tag` is the JSX component name in source (e.g. "Callout"). It MUST match the
+ * historical name in `plan-mdx.ts` `BLOCK_COMPONENTS` / stored `.mdx` files or
+ * existing plans break.
+ */
+export interface BlockMdxConfig<TData> {
+  /** JSX component name in MDX source. Stable contract — never rename. */
+  tag: string;
+  /**
+   * Encode `data` → a flat attribute bag. The registry serializer runs each
+   * value through the shared `prop()` encoder (string-vs-JSON heuristic) and
+   * preserves insertion order, so write the keys in the exact historical order.
+   * Return `undefined` for a key (or omit it) to drop the attribute. When
+   * `childrenField` is set, that field is excluded from the attribute bag.
+   */
+  toAttrs: (data: TData) => Record<string, MdxAttrValue | undefined>;
+  /**
+   * Decode resolved attributes (+ optional children markdown) → data. Must
+   * tolerate missing/partial attributes for backward-compat (mirror today's
+   * `?? []` / `?? ""` defaults).
+   */
+  fromAttrs: (attrs: BlockAttrReader, children: string) => TData;
+  /**
+   * When set, this data field is a markdown string serialized as MDX *children*
+   * between the open/close tags (prose-bearing blocks: rich-text, callout)
+   * rather than as a prop — so the body survives as real, inline-editable MDX
+   * prose in source.
+   */
+  childrenField?: keyof TData & string;
+  /**
+   * Opt-in custom children serializer/parser for blocks whose internals are
+   * nested MDX components or named child code fences rather than a single
+   * markdown string. When `serializeChildren` is present it overrides
+   * `childrenField`. `parseChildren` may also be used as a parse-only adapter
+   * for backward-compatible child forms.
+   */
+  serializeChildren?: (data: TData) => string;
+  parseChildren?: (childNodes: unknown[], idContext: string) => Partial<TData>;
+}
+
+/**
+ * App-injected capabilities. Core blocks stay app-agnostic by taking these
+ * rather than importing app services — mirroring `createImageExtension`'s
+ * `onImageUpload` injection. Provided via `BlockRegistryProvider`.
+ */
+export interface BlockRenderContext {
+  /** Markdown dialect for the auto-editor's rich-text field. */
+  dialect?: "gfm" | "nfm";
+  /** Document text direction inferred by the host app. */
+  textDirection?: "ltr" | "rtl";
+  /**
+   * Host default for visual wireframe/diagram frames when block data leaves
+   * `frame` unset or set to `auto`. Plans/recaps usually show a frame; docs can
+   * hide it by default and let individual blocks opt back in.
+   */
+  visualFrame?: Exclude<BlockVisualFrame, "auto">;
+  /** Resolve an asset id → displayable URL. */
+  resolveAssetSrc?: (assetId: string) => string | undefined;
+  /** Open the shared asset picker (returns the chosen asset). */
+  pickAsset?: () => Promise<{ assetId: string; url?: string } | null>;
+  /** Upload a local file, returns a hosted URL. */
+  uploadFile?: (file: File) => Promise<{ url: string; assetId?: string }>;
+  /** Call an app action by name (for blocks that fetch live data). */
+  callAction?: (name: string, args: unknown) => Promise<unknown>;
+  /** Sanitizer for HTML-bearing blocks. Provided by the app/core. */
+  sanitizeHtml?: (html: string, css?: string) => string;
+  /**
+   * Render a markdown string with the app's read-only markdown renderer. Lets a
+   * core block (whose `Read` lives in core) defer prose rendering to the app's
+   * markdown reader (e.g. the plan `PlanMarkdownReader`) without importing it.
+   */
+  renderMarkdown?: (
+    markdown: string,
+    options?: { className?: string },
+  ) => React.ReactNode;
+  /**
+   * Static capture mode: render every code/diff line annotation as a visible
+   * inline overlay instead of requiring hover.
+   */
+  showCodeAnnotationOverlays?: boolean;
+  /**
+   * Optional placement policy for line-anchored code/diff annotations.
+   * Hosts can keep the default right-first hover behavior, or ask annotations to
+   * prefer a margin side and become persistent whenever that margin has room.
+   */
+  codeAnnotationLayout?: {
+    /** Preferred side for hover cards when that side has a clean gutter. */
+    hoverSide?: "left" | "right";
+    /**
+     * Final hover fallback when neither side has a clean gutter. `"below"` keeps
+     * the legacy line-below behavior; `"left"`/`"right"` overlap the card from
+     * that code edge with a small overhang.
+     */
+    hoverFallbackSide?: "left" | "right" | "below";
+    /** Show all annotation cards by default when the requested margin fits. */
+    showByDefaultWhenRoom?: boolean;
+    /**
+     * When margin annotations are enabled, choose how many cards become visible
+     * without hover. Defaults to all for callers using the legacy boolean.
+     */
+    defaultVisibleAnnotations?: "all" | "first";
+    /** Margin side for persistent cards; `"auto"` tries hoverSide, then the other side. */
+    marginSide?: "left" | "right" | "auto";
+  };
+  /**
+   * Render an inline, editable rich-markdown field. The auto-editor calls this
+   * for a `markdown()`-tagged field so the app owns the editor wiring (collab,
+   * autosave debounce, dialect) rather than core hardcoding it.
+   */
+  renderMarkdownEditor?: (props: {
+    value: string;
+    onChange: (next: string) => void;
+    editable: boolean;
+    blockId?: string;
+    className?: string;
+    ariaLabel?: string;
+  }) => React.ReactNode;
+  /**
+   * Render an app-owned edit-by-prompt affordance ("Describe a change…") for a focused/editable block
+   * field. Core block editors pass the current field value and nearby companion
+   * fields; the host app decides how to collect the prompt and route it to the
+   * agent sidebar. This keeps reusable core blocks from importing app-specific
+   * popover/composer code while still exposing a generic AI edit hook.
+   */
+  renderAiFieldAction?: (props: BlockAiFieldActionProps) => React.ReactNode;
+  /**
+   * Render a nested child block through the app's own block dispatcher. Container
+   * blocks whose `Read`/`Edit` live in core (e.g. tabs) call this to render each
+   * child so the recursion keeps flowing through the SAME app renderer the
+   * top-level document uses — registered children render via their spec, and
+   * unregistered (not-yet-converted) children still fall through the app's legacy
+   * switch. This is the coexistence seam: a core container never has to know
+   * about app-specific child block types. Returns `null`/`undefined` when no
+   * dispatcher is wired (read-only/SSR-only contexts can omit it).
+   */
+  renderBlock?: (props: {
+    block: NestedBlock;
+    /** Commit a replacement for this child block (edit mode only). */
+    onChange?: (next: NestedBlock) => void;
+    /** Whether the parent container is being edited. */
+    editing?: boolean;
+    /** Tighten embedded visuals in dense contexts (e.g. tab panes). */
+    compactVisuals?: boolean;
+  }) => React.ReactNode;
+  /**
+   * Render a nested editable block list through the host app's document editor.
+   * Container blocks such as columns call this for each editable region so slash
+   * commands, nested structured blocks, and ordinary prose behave like the
+   * top-level document while the container still persists its normalized runtime
+   * data. Source adapters may still expose a human-friendly nested MDX form
+   * (for example `<Columns><Column>markdown</Column></Columns>`) and normalize it
+   * into these block arrays at runtime.
+   */
+  renderBlocksEditor?: (props: {
+    blocks: NestedBlock[];
+    onChange: (blocks: NestedBlock[]) => void;
+    editable: boolean;
+    containerBlockId: string;
+    regionId: string;
+    regionLabel?: string;
+    /** Tighten embedded visuals in dense regions such as tab panes. */
+    compactVisuals?: boolean;
+  }) => React.ReactNode;
+  /**
+   * Wrap a block's edit form in an app-provided "panel" surface (e.g. a shadcn
+   * Popover anchored to the corner edit button) for `editSurface: "panel"`
+   * blocks. Core renders the rendered `Read` view plus a corner trigger button
+   * and the form, then hands them here so the app owns the overlay primitive
+   * (core stays shadcn-free, mirroring `renderMarkdownEditor`). When omitted, a
+   * panel-mode block falls back to inline editing. `title` is the block label.
+   */
+  renderEditSurface?: (props: {
+    title: string;
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    trigger: React.ReactNode;
+    children: React.ReactNode;
+    /** Compact action menus omit host block-edit chrome such as edit-by-prompt. */
+    variant?: "panel" | "menu";
+    /** Metadata for host-provided contextual controls such as the edit-by-prompt CTA. */
+    blockId?: string;
+    blockType?: string;
+    blockTitle?: string;
+    blockSummary?: string;
+    blockData?: unknown;
+  }) => React.ReactNode;
+  /**
+   * Submit a respondent's answers from a `question-form` / `visual-questions`
+   * block back to the host. The app decides how to route the summary (e.g. send
+   * to the inline agent, copy to clipboard). Core blocks call this through the
+   * context so they never import app-specific submit wiring; omit it and the
+   * block degrades to a no-op submit.
+   */
+  onQuestionFormSubmit?: (summary: string) => void;
+}
+
+export interface BlockAiFieldActionProps {
+  blockId: string;
+  blockType: string;
+  blockTitle?: string;
+  blockSummary?: string;
+  fieldLabel: string;
+  fieldValue: string;
+  draftScope: string;
+  disabled?: boolean;
+  /**
+   * Human-readable instructions for the host agent prompt. Mention how to patch
+   * the block and which sibling fields should be preserved.
+   */
+  instructions: string;
+  companionFields?: Array<{
+    label: string;
+    value: string;
+    language?: string;
+  }>;
+}
+
+/**
+ * The minimal shape of a nested child block passed to {@link
+ * BlockRenderContext.renderBlock}. It mirrors the app's block union loosely (the
+ * app casts it back to its own block type) — a discriminating `type`, a stable
+ * `id`, optional heading/summary, and the type-specific `data`.
+ */
+export interface NestedBlock {
+  type: string;
+  id: string;
+  title?: string;
+  summary?: string;
+  data: unknown;
+  [key: string]: unknown;
+}
+
+export interface BlockContainerRegion {
+  id: string;
+  label?: string;
+  blocks: NestedBlock[];
+}
+
+export interface BlockContainerSpec<TData> {
+  regions: (data: TData) => BlockContainerRegion[];
+  updateRegion: (data: TData, regionId: string, blocks: NestedBlock[]) => TData;
+  addRegion?: (data: TData, afterRegionId?: string) => TData;
+  removeRegion?: (data: TData, regionId: string) => TData;
+  reorderRegion?: (
+    data: TData,
+    fromRegionId: string,
+    toRegionId: string,
+  ) => TData;
+}
+
+export type BlockDataChangeMeta = {
+  containerRegion?: {
+    regionId: string;
+    blocks: NestedBlock[];
+  };
+};
+
+/** Props passed to a block's read-only renderer. */
+export interface BlockReadProps<TData> {
+  data: TData;
+  /** Stable block id (for anchors, comment targeting, source patches). */
+  blockId: string;
+  /** Block heading, when present. */
+  title?: string;
+  /** Block trailing summary, when present. */
+  summary?: string;
+  /** Injected app capabilities. */
+  ctx: BlockRenderContext;
+  /** Tighten embedded visuals in dense contexts such as tabs and question cards. */
+  compactVisuals?: boolean;
+}
+
+/** Props passed to a block's editor (custom or schema-generated). */
+export interface BlockEditProps<TData> {
+  data: TData;
+  onChange: (next: TData, meta?: BlockDataChangeMeta) => void;
+  editable: boolean;
+  blockId: string;
+  title?: string;
+  summary?: string;
+  /** Injected app capabilities. */
+  ctx: BlockRenderContext;
+}
+
+export interface BlockSpec<TData = unknown> {
+  /** Discriminator. Equals the runtime block `type`. */
+  type: string;
+  /** Zod schema for `data`. Drives validation AND the schema-auto-editor. */
+  schema: ZodType<TData>;
+  /** MDX round-trip config. */
+  mdx: BlockMdxConfig<TData>;
+  /** Read-only renderer (replaces a `PlanBlockView` switch branch / NodeView). */
+  Read: FC<BlockReadProps<TData>>;
+  /**
+   * Optional editor. When omitted, the registry renders the schema-driven
+   * `SchemaBlockEditor` generated from `schema`. Supply for full control
+   * (wireframe canvas, diagram editor).
+   */
+  Edit?: FC<BlockEditProps<TData>>;
+  /** Allowed placements: `["block"]`, `["inline"]`, or both. */
+  placement: BlockPlacement[];
+  /**
+   * When `true`, this block's data maps to a Notion-Flavored-Markdown (NFM)
+   * analog and therefore round-trips into a Notion page. Apps can derive
+   * registry-backed Notion allowlists with
+   * {@link BlockRegistry.notionCompatibleTypes} instead of hand-maintaining
+   * per-app sets. Set it on registry-atom blocks with an NFM counterpart
+   * (checklist, table); leave it `false`/undefined on dev-doc blocks
+   * (api-endpoint, openapi-spec, data-model, diff, file-tree, json-explorer,
+   * annotated-code, mermaid, custom-html, tabs, code-tabs) and visual/plan-only
+   * blocks (wireframe, diagram). Prose blocks that aren't registry atoms
+   * (rich-text, callout) carry their NFM analog through the prose path, not this
+   * flag.
+   */
+  notionCompatible?: boolean;
+  /**
+   * How the block is edited in a `block`-placed document:
+   * - `"inline"` — the `Edit`/auto-form renders in place for direct
+   *   manipulation of authored content (prose, checklist text, table cells,
+   *   code bodies). Schema-ish metadata such as tone/type, tab labels,
+   *   language, density, or structural settings should still be tucked behind a
+   *   contextual edit/settings affordance inside the custom `Edit`.
+   * - `"panel"` — the block shows its rendered `Read` view with a corner edit
+   *   button that opens the `Edit`/auto-form in an app-provided panel (popover).
+   *   Best for config-driven blocks whose render differs from their props
+   *   (custom HTML, charts, any user-registered block).
+   * - `"container"` — the block renders its `Edit` in place, and that editor
+   *   may call `ctx.renderBlocksEditor` for nested block regions with normal
+   *   slash commands and nested structured blocks.
+   * - `"none"` — the block renders its `Read` view in edit mode and exposes no
+   *   block data form. Use for blocks whose whole-block operations live in the
+   *   editor chrome/menu rather than a custom or schema-generated editor.
+   * Defaults to `"inline"` when a custom `Edit` is supplied, else `"panel"`
+   * (auto-form blocks are property forms, ideal for a panel). The app must wire
+   * `ctx.renderEditSurface` for `"panel"` to take effect; otherwise it falls
+   * back to inline.
+   */
+  editSurface?: "inline" | "panel" | "container" | "none";
+  /**
+   * Optional generic contract for content-bearing container blocks. Keep this
+   * runtime-oriented: it describes editable regions over normalized block arrays;
+   * source formats can provide readable nested MDX adapters independently.
+   */
+  container?: BlockContainerSpec<TData>;
+  /** Human label for menus + agent schema export. */
+  label: string;
+  /** Tabler icon component for UI menus (never emoji/robot/sparkle). */
+  icon?: FC<{ size?: number; className?: string }>;
+  /** One-line description for the agent schema export. */
+  description: string;
+  /** Optional default `data` factory for slash-menu insertion (an empty block). */
+  empty?: () => TData;
+  /**
+   * Optional block-specific source-patch handlers, generalizing bespoke ops
+   * like `update-custom-html`. Keyed by op name; the registry dispatches a
+   * matching patch op here. Generic ops (`update-block` shallow-merge) need none.
+   */
+  patches?: Record<string, (data: TData, op: Record<string, unknown>) => TData>;
+}
+
+/** Identity helper for authoring a spec with full type inference. */
+export function defineBlock<TData>(spec: BlockSpec<TData>): BlockSpec<TData> {
+  return spec;
+}