@agent-native/core 0.113.0 → 0.114.1

package/src/client/blocks/library/diff.config.ts

@@ -0,0 +1,115 @@
+import { z } from "zod";
+
+import type { BlockMdxConfig } from "../types.js";
+
+/**
+ * Pure (React-free) part of the PLAN-SPECIFIC diff block: its data schema and MDX
+ * round-trip config. Shared by the server MDX adapter (`plan-mdx.ts` via
+ * `plan-block-registry.ts`) and the client spec (`planBlocks.tsx`). Keeping this
+ * React-free means importing it into a server module never pulls React (or the
+ * `diff` line-differ used only by the renderer) into the Nitro/SSR bundle.
+ *
+ * The schema MUST stay data-compatible with the `diff` branch of `planBlockSchema`
+ * (`plan-content.ts`), and the MDX `tag` + flat attribute shape MUST match the
+ * `<Diff filename language mode before after />` self-closing encoding so stored
+ * `.mdx` round-trips. The `before`/`after` source lives in ATTRIBUTES (not MDX
+ * children) — the shared `prop()` encoder round-trips multiline strings cleanly,
+ * and keeping them attributes avoids the code being reflowed as prose.
+ */
+
+/** Rendering layout for the diff body. */
+export type DiffMode = "unified" | "split";
+
+/**
+ * One line-anchored note attached to a diff, mirroring the `annotated-code`
+ * annotation shape but adding `side`. The `lines` ref is 1-based against the
+ * chosen side's source: `side: "after"` (the default) targets the new file's
+ * line numbers, `side: "before"` the old file's. Optional ⇒ a diff without
+ * annotations renders exactly as before.
+ */
+export interface DiffAnnotation {
+  /** Which side the line ref targets; defaults to "after". */
+  side?: "before" | "after";
+  /** 1-based line ref against that side's text: "13" or "13-15" (inclusive). */
+  lines: string;
+  /** Optional short label shown before the note (e.g. "Validation"). */
+  label?: string;
+  /** The note prose (markdown), rendered through `ctx.renderMarkdown`. */
+  note: string;
+}
+
+export interface DiffData {
+  /** Optional file path shown in the header (e.g. `src/add.ts`). */
+  filename?: string;
+  /** Optional language label rendered as a chip (e.g. `ts`). Purely cosmetic. */
+  language?: string;
+  /** Original ("before") source. */
+  before: string;
+  /** New ("after") source. */
+  after: string;
+  /** Layout: split (default, side-by-side) or unified (one column). */
+  mode?: DiffMode;
+  /** Line-anchored notes over the before/after sides. */
+  annotations?: DiffAnnotation[];
+}
+
+/**
+ * A 1-based line reference: `"3"` or `"3-5"` (inclusive). Whitespace tolerant.
+ * Matches the `annotated-code` line-ref schema so both blocks validate refs
+ * identically.
+ */
+const lineRefSchema = z
+  .string()
+  .trim()
+  .regex(/^\d+(\s*-\s*\d+)?$/, {
+    message: 'lines must be a 1-based line ref like "3" or "3-5"',
+  })
+  .max(40);
+
+const diffAnnotationSchema = z.object({
+  side: z.enum(["before", "after"]).optional(),
+  lines: lineRefSchema,
+  label: z.string().trim().max(160).optional(),
+  note: z.string().trim().min(1).max(4_000),
+}) as z.ZodType<DiffAnnotation>;
+
+export const diffSchema = z.object({
+  filename: z.string().trim().max(400).optional(),
+  language: z.string().trim().max(40).optional(),
+  before: z.string().max(100_000),
+  after: z.string().max(100_000),
+  mode: z.enum(["unified", "split"]).optional(),
+  annotations: z.array(diffAnnotationSchema).max(80).optional(),
+}) as unknown as z.ZodType<DiffData>;
+
+/**
+ * MDX config: `filename`, `language`, `mode`, `before`, `after`, and
+ * `annotations` are flat attributes — the
+ * `<Diff id … filename language mode before after annotations />` self-closing
+ * form. Insertion order of `toAttrs` is the on-disk attribute order. `before`/
+ * `after` are multiline string attributes (round-trip through the shared `prop()`
+ * encoder); `annotations` is a JSON array attribute, encoded the same way as the
+ * `annotated-code` block. `fromAttrs` mirrors a forgiving parse (`before ?? ""`,
+ * `after ?? ""`, optional `filename`/`language`/`mode`/`annotations` undefined
+ * when absent) so a plan missing an attribute still parses without re-emitting
+ * unauthored empty arrays.
+ */
+export const diffMdx: BlockMdxConfig<DiffData> = {
+  tag: "Diff",
+  toAttrs: (data) => ({
+    filename: data.filename,
+    language: data.language,
+    mode: data.mode,
+    before: data.before,
+    after: data.after,
+    annotations: data.annotations,
+  }),
+  fromAttrs: (attrs) => ({
+    filename: attrs.string("filename"),
+    language: attrs.string("language"),
+    mode: attrs.string("mode") as DiffMode | undefined,
+    before: attrs.string("before") ?? "",
+    after: attrs.string("after") ?? "",
+    annotations: attrs.array<DiffAnnotation>("annotations"),
+  }),
+};

package/src/client/blocks/library/file-tree.config.ts

@@ -0,0 +1,92 @@
+import { z } from "zod";
+
+import type { BlockMdxConfig } from "../types.js";
+
+/**
+ * Pure (React-free) part of the PLAN-SPECIFIC `file-tree` block: its data schema
+ * and MDX round-trip config. Shared by the server MDX adapter (`plan-mdx.ts` via
+ * `plan-block-registry.ts`) and the client spec (`planBlocks.tsx`). Keeping this
+ * React-free means importing it into a server module never pulls React into the
+ * Nitro/SSR bundle.
+ *
+ * The block renders a VS Code / GitHub-explorer style file/change tree: a flat
+ * list of `entries` (each a slash-delimited `path` with an optional change kind,
+ * note, and code snippet) from which the RENDERER derives the nested folder tree
+ * — the model never carries the folder structure, only the leaf paths. This keeps
+ * the data lean and the tree always consistent with the paths.
+ *
+ * The schema MUST stay data-compatible with the `file-tree` member of
+ * `planBlockSchema` (`plan-content.ts`), and the MDX `tag` (`FileTree`) +
+ * attribute shape MUST match it so stored `.mdx` round-trips: the whole `entries`
+ * array is one JSON prop (`<FileTree id … title entries={…} />`).
+ */
+
+/** The kind of change applied to a file, driving its change badge. */
+export type FileTreeChange = "added" | "modified" | "removed" | "renamed";
+
+export const FILE_TREE_CHANGES: FileTreeChange[] = [
+  "added",
+  "modified",
+  "removed",
+  "renamed",
+];
+
+/**
+ * One file in the tree. `path` is slash-delimited (`src/routes/git.ts`); the
+ * renderer derives the folder structure from its segments. `change` drives the
+ * change badge (A/M/D/R); `note` + `snippet` (with optional `language`) make the
+ * file row expandable to show why it changes and a code preview.
+ */
+export interface FileTreeEntry {
+  path: string;
+  change?: FileTreeChange;
+  note?: string;
+  snippet?: string;
+  language?: string;
+}
+
+export interface FileTreeData {
+  /** Optional heading shown above the tree (e.g. "Files touched"). */
+  title?: string;
+  entries: FileTreeEntry[];
+}
+
+const entrySchema = z.object({
+  path: z.string().trim().min(1).max(500),
+  change: z.enum(["added", "modified", "removed", "renamed"]).optional(),
+  note: z.string().trim().max(2_000).optional(),
+  snippet: z.string().max(50_000).optional(),
+  language: z.string().trim().max(40).optional(),
+}) as z.ZodType<FileTreeEntry>;
+
+/**
+ * Data-compatible with the inline `file-tree` member of `planBlockSchema`
+ * (`plan-content.ts`). `entries` is required (at least one file); `title` is
+ * optional so a fresh tree validates from a couple of files.
+ */
+export const fileTreeSchema = z.object({
+  title: z.string().trim().max(180).optional(),
+  entries: z.array(entrySchema).min(1).max(200),
+}) as unknown as z.ZodType<FileTreeData>;
+
+/**
+ * MDX config: `title` is a flat string attribute and the whole `entries` array is
+ * serialized as one JSON prop on a self-closing element — the `<FileTree id …
+ * title entries={…} />` form. `toAttrs` emits `title` then `entries` in a STABLE
+ * order (the shared `prop()` encoder drops `title` when it is undefined).
+ *
+ * `fromAttrs` tolerates missing/partial attributes for backward-compat: a missing
+ * `title` decodes to `undefined` and a missing `entries` decodes to `[]` so a
+ * plan written before this block existed still parses.
+ */
+export const fileTreeMdx: BlockMdxConfig<FileTreeData> = {
+  tag: "FileTree",
+  toAttrs: (data) => ({
+    title: data.title,
+    entries: data.entries,
+  }),
+  fromAttrs: (attrs) => ({
+    title: attrs.string("title"),
+    entries: attrs.array<FileTreeEntry>("entries") ?? [],
+  }),
+};

package/src/client/blocks/library/html.config.ts

@@ -0,0 +1,79 @@
+import { z } from "zod";
+
+import type { BlockMdxConfig } from "../types.js";
+
+/**
+ * Pure (React-free) part of the standard HTML / Tailwind block: its data schema
+ * and MDX round-trip config. Shared by the React spec (`html.tsx`) and any
+ * server-side / agent registry (e.g. the plan app's `plan-block-registry.ts`),
+ * so importing it into a server module never pulls React in.
+ *
+ * This is the registry form of the plan `custom-html` block. The schema MUST
+ * stay data-compatible with the `custom-html` branch of the plan
+ * `planBlockSchema` (bounded `html`, optional bounded `css`, optional trimmed
+ * `caption`, all rejecting full-document / script markup) so a registered block
+ * still validates through the app's generic `update-block` re-validation. The
+ * MDX `tag` (`HtmlBlock`) + flat `html`/`css`/`caption` attribute shape MUST
+ * match the legacy `<HtmlBlock … html css caption />` encoding
+ * (`plan-mdx.ts` `serializeBlock`/`parseBlock`) so stored `.mdx` round-trips
+ * byte-compatibly.
+ */
+
+export interface HtmlBlockData {
+  /** Bounded HTML fragment (no html/head/body/script/style document markup). */
+  html: string;
+  /** Optional bounded CSS, scoped into the sandboxed iframe. */
+  css?: string;
+  /** Optional short caption rendered under the rendered fragment. */
+  caption?: string;
+}
+
+/**
+ * Rejects full HTML documents, executable/structural tags, and JS/data URLs.
+ * Kept byte-identical to the plan `noFullHtmlDocument` refine so the registry
+ * schema accepts exactly what `planBlockSchema` accepts (and nothing it would
+ * reject). Defense in depth — the block also renders inside a sandboxed iframe.
+ */
+const unsafeHtmlPattern =
+  /(?:<!doctype|<\/?(?:html|head|body|script|style|iframe|object|embed|link|meta|base|form)[\s>/]|\b(?:javascript|data:text\/html)\s*:|\bsrcdoc\s*=|\bon[a-z][\w:-]*\s*=)/i;
+
+const noFullHtmlDocument = (value: string) => !unsafeHtmlPattern.test(value);
+
+export const htmlSchema = z
+  .object({
+    html: z.string().max(100_000).refine(noFullHtmlDocument, {
+      message:
+        "Custom HTML blocks must be bounded fragments without html/head/body/script/style tags.",
+    }),
+    css: z
+      .string()
+      .max(50_000)
+      .refine(noFullHtmlDocument, {
+        message: "Custom CSS blocks must not include document or script tags.",
+      })
+      .optional(),
+    caption: z.string().trim().max(400).optional(),
+  })
+  .strict() as unknown as z.ZodType<HtmlBlockData>;
+
+/**
+ * MDX config: `html`, `css`, and `caption` are flat attributes (no children) —
+ * exactly the legacy `<HtmlBlock id … html css caption />` self-closing form.
+ * Insertion order of `toAttrs` is the on-disk attribute order, so it stays
+ * `html` → `css` → `caption` to match `plan-mdx.ts:serializeBlock`. `fromAttrs`
+ * mirrors the legacy parse defaults (`html ?? ""`, `css`/`caption` undefined
+ * when absent).
+ */
+export const htmlMdx: BlockMdxConfig<HtmlBlockData> = {
+  tag: "HtmlBlock",
+  toAttrs: (data) => ({
+    html: data.html,
+    css: data.css,
+    caption: data.caption,
+  }),
+  fromAttrs: (attrs) => ({
+    html: attrs.string("html") ?? "",
+    css: attrs.string("css"),
+    caption: attrs.string("caption"),
+  }),
+};

package/src/client/blocks/library/html.tsx

@@ -0,0 +1,258 @@
+import { IconCode, IconEdit, IconX } from "@tabler/icons-react";
+import { useEffect, useId, useState } from "react";
+
+import { AiEditableFieldLabel } from "../AiEditableField.js";
+import { defineBlock } from "../types.js";
+import type { BlockReadProps, BlockEditProps } from "../types.js";
+import { htmlSchema, htmlMdx, type HtmlBlockData } from "./html.config.js";
+import { useIsDark } from "./wireframe-kit.js";
+
+/**
+ * Standard library HTML / Tailwind block. The registry form of the plan
+ * `custom-html` block: an author-supplied HTML (+ optional CSS) fragment
+ * rendered inside a sandboxed iframe, with an inline source editor.
+ *
+ * Security: the fragment is rendered in a `sandbox="allow-same-origin"` iframe
+ * with `referrerPolicy="no-referrer"` — no scripts execute — and the schema's
+ * `noFullHtmlDocument` refine rejects document/script/handler markup before it
+ * is ever stored. When the app injects `ctx.sanitizeHtml`, the fragment + CSS
+ * are additionally sanitized before being placed in the iframe `srcDoc`.
+ *
+ * Styling uses app-agnostic shadcn utility classes (`border`, `bg-muted`,
+ * `text-muted-foreground`) so the block renders cleanly in any template, not
+ * just the plan app.
+ */
+
+/** Build the iframe document for a fragment, applying app sanitization if given. */
+function buildSrcDoc(
+  data: HtmlBlockData,
+  theme: "light" | "dark",
+  sanitize?: (html: string, css?: string) => string,
+): string {
+  const css = data.css ?? "";
+  const body = sanitize ? sanitize(data.html, data.css) : data.html;
+  // The iframe is isolated from the host's `.dark` class and CSS variables, so
+  // bridge the current theme explicitly and expose the same semantic tokens that
+  // generated wireframe/diagram HTML already uses.
+  return `<!doctype html><html data-theme="${theme}"><head><style>:root{color-scheme:light;--wf-paper:#fbfaf6;--wf-card:#ffffff;--wf-ink:#1f1f1d;--wf-muted:#6f6a63;--wf-line:#ded8ce;--wf-radius:12px;--plan-document:var(--wf-paper);--plan-block:var(--wf-card);--plan-text:var(--wf-ink);--plan-muted:var(--wf-muted);--plan-line:var(--wf-line)}:root[data-theme="dark"]{color-scheme:dark;--wf-paper:#201f1c;--wf-card:#2a2825;--wf-ink:#ece8e1;--wf-muted:#9a948b;--wf-line:#43403a;--plan-document:var(--wf-paper);--plan-block:var(--wf-card);--plan-text:var(--wf-ink);--plan-muted:var(--wf-muted);--plan-line:var(--wf-line)}html,body{margin:0;min-height:100%;font-family:Inter,system-ui,sans-serif;color:var(--wf-ink);background:var(--wf-paper)}*{box-sizing:border-box}${css}</style></head><body>${body}</body></html>`;
+}
+
+function HtmlPreview({
+  data,
+  title,
+  sanitize,
+}: {
+  data: HtmlBlockData;
+  title?: string;
+  sanitize?: (html: string, css?: string) => string;
+}) {
+  const isDark = useIsDark();
+  const theme = isDark ? "dark" : "light";
+  return (
+    <>
+      <iframe
+        title={title || "Custom HTML block"}
+        srcDoc={buildSrcDoc(data, theme, sanitize)}
+        sandbox="allow-same-origin"
+        referrerPolicy="no-referrer"
+        className="mt-4 h-[360px] w-full rounded-xl border bg-muted"
+      />
+      {data.caption && (
+        <p className="mt-3 text-sm text-muted-foreground">{data.caption}</p>
+      )}
+    </>
+  );
+}
+
+/** Read-only renderer: the sandboxed iframe preview plus an optional caption. */
+export function HtmlReadBlock({
+  data,
+  blockId,
+  title,
+  ctx,
+}: BlockReadProps<HtmlBlockData>) {
+  return (
+    <section className="plan-block group" data-block-id={blockId}>
+      {title && <div className="plan-block-label">{title}</div>}
+      <HtmlPreview data={data} title={title} sanitize={ctx.sanitizeHtml} />
+    </section>
+  );
+}
+
+/**
+ * Custom editor: an "Edit source" toggle that flips between the live preview and
+ * inline HTML + CSS textareas (ported from the plan `CustomHtmlBlock`). The
+ * title is rendered by the registry's edit-mode section wrapper, so this only
+ * renders the toggle + content. Edits commit the merged data via `onChange`,
+ * which the app routes through its generic `update-block` patch (re-validated by
+ * the app schema).
+ */
+export function HtmlEditBlock({
+  data,
+  onChange,
+  editable,
+  blockId,
+  title,
+  summary,
+  ctx,
+}: BlockEditProps<HtmlBlockData>) {
+  const htmlId = useId();
+  const cssId = useId();
+  const captionId = useId();
+  const [editing, setEditing] = useState(false);
+  const [html, setHtml] = useState(data.html);
+  const [css, setCss] = useState(data.css ?? "");
+  const [caption, setCaption] = useState(data.caption ?? "");
+
+  useEffect(() => {
+    setHtml(data.html);
+    setCss(data.css ?? "");
+    setCaption(data.caption ?? "");
+  }, [data]);
+
+  const fieldAction = (
+    field: "HTML fragment" | "CSS" | "Caption",
+    value: string,
+  ) => ({
+    blockId,
+    blockType: "custom-html",
+    blockTitle: title,
+    blockSummary: summary,
+    fieldValue: value,
+    draftScope: `block:custom-html:${blockId}:${field.toLowerCase().replace(/[^a-z0-9]+/g, "-")}`,
+    disabled: !editable,
+    instructions:
+      "Update the plan with update-visual-plan using a targeted update-block content patch for this custom-html block id. Preserve unrelated HTML/CSS/caption fields unless the requested edit requires changing them.",
+    companionFields: [
+      { label: "HTML fragment", value: html || "(empty)", language: "html" },
+      { label: "CSS", value: css || "(empty)", language: "css" },
+      { label: "Caption", value: caption || "(empty)", language: "text" },
+    ],
+  });
+
+  return (
+    <div className="plan-html-block group" data-an-block-edit>
+      <div className="flex items-start justify-end gap-4">
+        {editable && (
+          <button
+            type="button"
+            data-plan-interactive
+            aria-label={editing ? "Cancel editing source" : "Edit source"}
+            className="inline-flex size-8 items-center justify-center rounded-md text-muted-foreground transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
+            onClick={() => setEditing((value) => !value)}
+          >
+            {editing ? (
+              <IconX className="size-4" />
+            ) : (
+              <IconEdit className="size-4" />
+            )}
+          </button>
+        )}
+      </div>
+      {editing ? (
+        <div className="mt-2 grid gap-3" data-plan-interactive>
+          <div className="group/field grid gap-1.5">
+            <AiEditableFieldLabel
+              htmlFor={htmlId}
+              label="HTML fragment"
+              ctx={ctx}
+              action={fieldAction("HTML fragment", html)}
+            />
+            <textarea
+              id={htmlId}
+              value={html}
+              disabled={!editable}
+              onChange={(event) => setHtml(event.target.value)}
+              className="flex min-h-48 w-full rounded-md border border-input bg-transparent px-3 py-2 font-mono text-sm placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50"
+              placeholder="HTML fragment"
+            />
+          </div>
+          <div className="group/field grid gap-1.5">
+            <AiEditableFieldLabel
+              htmlFor={cssId}
+              label="CSS"
+              ctx={ctx}
+              action={fieldAction("CSS", css)}
+            />
+            <textarea
+              id={cssId}
+              value={css}
+              disabled={!editable}
+              onChange={(event) => setCss(event.target.value)}
+              className="flex min-h-32 w-full rounded-md border border-input bg-transparent px-3 py-2 font-mono text-sm placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50"
+              placeholder="Optional CSS"
+            />
+          </div>
+          <div className="group/field grid gap-1.5">
+            <AiEditableFieldLabel
+              htmlFor={captionId}
+              label="Caption"
+              ctx={ctx}
+              action={fieldAction("Caption", caption)}
+            />
+            <input
+              id={captionId}
+              type="text"
+              value={caption}
+              disabled={!editable}
+              onChange={(event) => setCaption(event.target.value)}
+              className="flex h-9 w-full rounded-md border border-input bg-transparent px-3 text-sm placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50"
+              placeholder="Optional caption"
+            />
+          </div>
+          <div className="flex justify-end gap-2">
+            <button
+              type="button"
+              data-plan-interactive
+              className="inline-flex h-9 items-center rounded-md px-4 text-sm font-medium text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+              onClick={() => setEditing(false)}
+            >
+              Cancel
+            </button>
+            <button
+              type="button"
+              data-plan-interactive
+              className="inline-flex h-9 items-center rounded-md bg-primary px-4 text-sm font-medium text-primary-foreground transition-colors hover:bg-primary/90"
+              onClick={() => {
+                onChange({
+                  ...data,
+                  html,
+                  css: css || undefined,
+                  caption: caption || undefined,
+                });
+                setEditing(false);
+              }}
+            >
+              Save
+            </button>
+          </div>
+        </div>
+      ) : (
+        <HtmlPreview data={data} title={title} sanitize={ctx.sanitizeHtml} />
+      )}
+    </div>
+  );
+}
+
+/**
+ * The standard HTML / Tailwind block spec. Both apps register this; the plan app
+ * registers the matching React-free `{ schema, mdx }` server-side via
+ * `html.config.ts`. `empty()` seeds a friendly starter fragment for slash
+ * insertion.
+ */
+export const htmlBlock = defineBlock<HtmlBlockData>({
+  type: "custom-html",
+  schema: htmlSchema,
+  mdx: htmlMdx,
+  Read: HtmlReadBlock,
+  Edit: HtmlEditBlock,
+  placement: ["block"],
+  // Config-driven: the render (a sandboxed card) differs from its source, so edit
+  // the html/css/caption from a corner button + panel rather than always-inline.
+  editSurface: "panel",
+  label: "HTML / Tailwind",
+  icon: IconCode,
+  description:
+    "An author-supplied HTML (with optional CSS) fragment rendered in a sandboxed iframe, with inline source editing.",
+  empty: () => ({ html: '<div class="p-6">Edit this HTML fragment…</div>' }),
+});

package/src/client/blocks/library/json-explorer.config.ts

@@ -0,0 +1,74 @@
+import { z } from "zod";
+
+import type { BlockMdxConfig } from "../types.js";
+
+/**
+ * Pure (React-free) part of the PLAN-SPECIFIC `json-explorer` block: its data
+ * schema and MDX round-trip config. Shared by the server MDX adapter
+ * (`plan-mdx.ts` via `plan-block-registry.ts`) and the client spec
+ * (`planBlocks.tsx`). Keeping this React-free means importing it into a server
+ * module never pulls React into the Nitro/SSR bundle.
+ *
+ * The block renders a browser-devtools / Postman-style collapsible JSON tree:
+ * object/array nodes show a chevron + a one-line summary ("{…} 3 keys" /
+ * "[…] 5 items") and expand/collapse; leaf values are type-colored (string =
+ * green, number = blue, boolean = violet, null = muted). The raw JSON TEXT is
+ * the source of truth (`json`), so authoring round-trips losslessly even when
+ * the JSON is invalid — the reader parses defensively and falls back to the raw
+ * text on a parse error rather than throwing.
+ *
+ * The schema MUST stay data-compatible with the inline `json-explorer` member of
+ * `planBlockSchema` (`plan-content.ts`), and the MDX `tag` (`Json`) +
+ * attribute shape MUST match the `<Json title json collapsedDepth />` encoding so
+ * stored `.mdx` round-trips. `json` lives in the `json` ATTRIBUTE (not MDX
+ * children) — the shared `prop()` encoder round-trips multiline strings cleanly,
+ * and keeping it an attribute avoids the payload being reflowed as prose.
+ */
+
+export const JSON_EXPLORER_DEFAULT_COLLAPSED_DEPTH = 2;
+export const JSON_EXPLORER_MAX_COLLAPSED_DEPTH = 20;
+
+export interface JsonExplorerData {
+  /** Optional heading shown above the tree. */
+  title?: string;
+  /** Raw JSON text — the source of truth, parsed defensively at render time. */
+  json: string;
+  /**
+   * Depth beyond which nodes start collapsed (default 2). Nodes at a depth `<`
+   * this value render expanded; deeper nodes render collapsed until clicked.
+   */
+  collapsedDepth?: number;
+}
+
+export const jsonExplorerSchema = z.object({
+  title: z.string().trim().max(200).optional(),
+  json: z.string().max(200_000),
+  collapsedDepth: z
+    .number()
+    .int()
+    .min(0)
+    .max(JSON_EXPLORER_MAX_COLLAPSED_DEPTH)
+    .optional(),
+}) as unknown as z.ZodType<JsonExplorerData>;
+
+/**
+ * MDX config: `title`, `json`, and `collapsedDepth` are flat attributes — the
+ * `<Json id … title json collapsedDepth />` self-closing form. Insertion order
+ * of `toAttrs` is the on-disk attribute order (`title` → `json` →
+ * `collapsedDepth`). `fromAttrs` mirrors a forgiving parse (`json ?? ""`,
+ * `title`/`collapsedDepth` undefined when absent) so a plan missing an attribute
+ * still parses.
+ */
+export const jsonExplorerMdx: BlockMdxConfig<JsonExplorerData> = {
+  tag: "Json",
+  toAttrs: (data) => ({
+    title: data.title,
+    json: data.json,
+    collapsedDepth: data.collapsedDepth,
+  }),
+  fromAttrs: (attrs) => ({
+    json: attrs.string("json") ?? "",
+    title: attrs.string("title"),
+    collapsedDepth: attrs.number("collapsedDepth"),
+  }),
+};

package/src/client/blocks/library/mermaid.config.ts

@@ -0,0 +1,49 @@
+import { z } from "zod";
+
+import type { BlockMdxConfig } from "../types.js";
+
+/**
+ * Pure (React-free) part of the PLAN-SPECIFIC mermaid block: its data schema and
+ * MDX round-trip config. Shared by the server MDX adapter (`plan-mdx.ts` via
+ * `plan-block-registry.ts`) and the client spec (`planBlocks.tsx`). Keeping this
+ * React-free means importing it into a server module never pulls React (or the
+ * client-only `mermaid` runtime) into the Nitro/SSR bundle.
+ *
+ * The schema MUST stay data-compatible with the `mermaid` branch of
+ * `planBlockSchema` (`plan-content.ts`), and the MDX `tag` + flat `source` /
+ * `caption` attribute shape MUST match the `<Mermaid source caption />` encoding
+ * so stored `.mdx` round-trips. The diagram code lives in the `source` ATTRIBUTE
+ * (not MDX children) — the shared `prop()` encoder round-trips multiline strings
+ * cleanly, and keeping it an attribute avoids the source being reflowed as prose.
+ */
+
+export interface MermaidData {
+  /** Mermaid diagram definition (flowchart/sequence/etc.) edited as raw text. */
+  source: string;
+  /** Optional short caption rendered (muted) under the diagram. */
+  caption?: string;
+}
+
+export const mermaidSchema = z.object({
+  source: z.string().max(50_000),
+  caption: z.string().trim().max(400).optional(),
+}) as unknown as z.ZodType<MermaidData>;
+
+/**
+ * MDX config: `source` and `caption` are flat attributes — the `<Mermaid id …
+ * source caption />` self-closing form. Insertion order of `toAttrs` is the
+ * on-disk attribute order (`source` → `caption`). `fromAttrs` mirrors a
+ * forgiving parse (`source ?? ""`, `caption` undefined when absent) so a plan
+ * missing the attribute still parses.
+ */
+export const mermaidMdx: BlockMdxConfig<MermaidData> = {
+  tag: "Mermaid",
+  toAttrs: (data) => ({
+    source: data.source,
+    caption: data.caption,
+  }),
+  fromAttrs: (attrs) => ({
+    source: attrs.string("source") ?? "",
+    caption: attrs.string("caption"),
+  }),
+};