@agent-native/core 0.113.0 → 0.114.0

package/src/client/blocks/mdx.ts

@@ -0,0 +1,364 @@
+import type { BlockRegistry } from "./registry.js";
+import type { BlockSpec, BlockAttrReader, MdxAttrValue } from "./types.js";
+
+/**
+ * Registry-driven MDX serialize/parse, plus the shared encoder primitives that
+ * are the round-trip contract. This module is React-free so the server MDX
+ * adapter (`plan-mdx.ts`) and the agent schema export can import it. The encoder
+ * + estree literal walker are kept BYTE-FOR-BYTE identical to the originals in
+ * `plan-mdx.ts` — `plan-mdx.ts` re-imports them so nothing else there changes
+ * and stored `.mdx` files round-trip the same.
+ */
+
+/* -------------------------------------------------------------------------- */
+/* Serialize-side encoder primitives (moved verbatim from plan-mdx.ts)        */
+/* -------------------------------------------------------------------------- */
+
+export function jsonExpression(value: unknown): string {
+  return JSON.stringify(value, null, 2);
+}
+
+export function escapeAttr(value: string): string {
+  return value
+    .replace(/&/g, "&")
+    .replace(/"/g, """)
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+/**
+ * Encode a single attribute. Returns "" (the attribute is dropped) for
+ * undefined/null; a bare/`={false}` flag for booleans; `={n}` for numbers; a
+ * quoted string when it matches the safe charset and is short, else a JSON
+ * expression. Objects/arrays always serialize as a JSON expression.
+ */
+export function prop(name: string, value: unknown): string {
+  if (value === undefined || value === null) return "";
+  if (typeof value === "boolean") {
+    return value ? ` ${name}` : ` ${name}={false}`;
+  }
+  if (typeof value === "number") return ` ${name}={${value}}`;
+  if (typeof value === "string") {
+    if (/^[\w .:/@#,+()[\]-]+$/.test(value) && value.length < 140) {
+      return ` ${name}="${escapeAttr(value)}"`;
+    }
+    return ` ${name}={${jsonExpression(value)}}`;
+  }
+  return ` ${name}={${jsonExpression(value)}}`;
+}
+
+/* -------------------------------------------------------------------------- */
+/* Parse-side attribute resolution (moved verbatim from plan-mdx.ts)          */
+/* -------------------------------------------------------------------------- */
+
+/** Minimal MDX AST node shape (subset of the remark-mdx jsx element). */
+export type MdxAttrNode = {
+  type: string;
+  name?: string;
+  value?: string | null | MdxAttrExpression;
+};
+
+type MdxAttrExpression = {
+  type: string;
+  value: string;
+  data?: unknown;
+};
+
+type EstreeTemplateElement = {
+  type: string;
+  value?: { cooked?: string | null; raw?: string };
+};
+
+type EstreeNode = {
+  type: string;
+  value?: unknown;
+  name?: string;
+  expression?: EstreeNode;
+  body?: EstreeNode[];
+  elements?: Array<EstreeNode | null>;
+  properties?: EstreeNode[];
+  key?: EstreeNode;
+  computed?: boolean;
+  argument?: EstreeNode;
+  operator?: string;
+  quasis?: EstreeTemplateElement[];
+  expressions?: EstreeNode[];
+};
+
+export type MdxJsxNode = {
+  type: string;
+  name?: string;
+  attributes?: MdxAttrNode[];
+  children?: unknown[];
+  [key: string]: unknown;
+};
+
+function findAttribute(
+  node: MdxJsxNode,
+  name: string,
+): MdxAttrNode | undefined {
+  return node.attributes?.find(
+    (attr) => attr.type === "mdxJsxAttribute" && attr.name === name,
+  );
+}
+
+export function attributeValue(attr: MdxAttrNode | undefined): unknown {
+  if (!attr) return undefined;
+  if (attr.value === null || attr.value === undefined) return true;
+  if (typeof attr.value === "string") return attr.value;
+  const astValue = literalExpressionValue(attr.value);
+  if (astValue !== undefined) return astValue;
+  const expression = attr.value.value.trim();
+  if (!expression) return undefined;
+  if (expression === "undefined") return undefined;
+  try {
+    return JSON.parse(expression);
+  } catch {
+    throw new Error(
+      `Unsupported MDX attribute expression for "${attr.name}": {${expression}}. Use literal values or valid JSON.`,
+    );
+  }
+}
+
+function literalExpressionValue(expression: MdxAttrExpression): unknown {
+  const estree = (expression.data as { estree?: EstreeNode } | undefined)
+    ?.estree;
+  const statement = estree?.body?.[0];
+  if (!statement || statement.type !== "ExpressionStatement") return undefined;
+  return literalNodeValue(statement.expression);
+}
+
+function literalNodeValue(node: EstreeNode | undefined | null): unknown {
+  if (!node) return undefined;
+  if (node.type === "Literal") return node.value;
+  if (node.type === "TemplateLiteral") {
+    // A template literal WITH `${…}` interpolations can't be evaluated
+    // statically — fail loudly so the import errors instead of falling through
+    // to a confusing JSON parse error or silently dropping the attribute.
+    if ((node.expressions?.length ?? 0) > 0) {
+      throw new Error(
+        "Template literal attribute values may not contain ${…} expressions; use a static string.",
+      );
+    }
+    // A template literal with no expressions is a static string:
+    // `<div>hi</div>` → "<div>hi</div>".
+    return node.quasis?.[0]?.value?.cooked ?? "";
+  }
+  if (node.type === "ArrayExpression") {
+    return (node.elements ?? []).map((item) => literalNodeValue(item));
+  }
+  if (node.type === "ObjectExpression") {
+    const out: Record<string, unknown> = {};
+    for (const property of node.properties ?? []) {
+      if (property.type !== "Property" || property.computed) return undefined;
+      const key = property.key;
+      const rawKey =
+        key?.type === "Identifier"
+          ? key.name
+          : key?.type === "Literal" && typeof key.value === "string"
+            ? key.value
+            : undefined;
+      if (!rawKey) return undefined;
+      const value = literalNodeValue(property.value as EstreeNode | undefined);
+      if (value !== undefined) out[rawKey] = value;
+    }
+    return out;
+  }
+  if (node.type === "UnaryExpression") {
+    const value = literalNodeValue(node.argument);
+    if (typeof value !== "number") return undefined;
+    if (node.operator === "-") return -value;
+    if (node.operator === "+") return value;
+  }
+  if (node.type === "Identifier") {
+    if (node.name === "undefined") return undefined;
+    if (node.name === "NaN") return Number.NaN;
+    if (node.name === "Infinity") return Infinity;
+  }
+  return undefined;
+}
+
+/** Build a {@link BlockAttrReader} bound to one parsed JSX node. */
+export function createAttrReader(node: MdxJsxNode): BlockAttrReader {
+  const read = (name: string) => attributeValue(findAttribute(node, name));
+  return {
+    raw: read,
+    string(name) {
+      const value = read(name);
+      return typeof value === "string" ? value : undefined;
+    },
+    number(name) {
+      const value = read(name);
+      return typeof value === "number" ? value : undefined;
+    },
+    bool(name) {
+      const value = read(name);
+      return typeof value === "boolean" ? value : undefined;
+    },
+    array(name) {
+      const value = read(name);
+      return Array.isArray(value) ? (value as never[]) : undefined;
+    },
+    object(name) {
+      const value = read(name);
+      return value && typeof value === "object" ? (value as never) : undefined;
+    },
+  };
+}
+
+type MdxCodeNode = {
+  type?: unknown;
+  lang?: unknown;
+  value?: unknown;
+};
+
+function codeFenceFor(value: string): string {
+  const longestBacktickRun =
+    value.match(/`+/g)?.reduce((max, run) => Math.max(max, run.length), 0) ?? 0;
+  return "`".repeat(Math.max(3, longestBacktickRun + 1));
+}
+
+function codeFenceLang(value: unknown): string | undefined {
+  return typeof value === "string"
+    ? value.trim().split(/\s+/)[0]?.toLowerCase()
+    : undefined;
+}
+
+/**
+ * Convert named MDX child code fences into block data fields. This keeps source
+ * authoring normal Markdown/MDX while letting block specs opt into conventions
+ * such as "```html" -> data.html and "```css" -> data.css.
+ */
+export function childCodeFenceFields<TData extends object>(
+  childNodes: unknown[],
+  fieldsByLang: Record<string, keyof TData & string>,
+): Partial<TData> {
+  const out: Partial<TData> = {};
+  for (const node of childNodes as MdxCodeNode[]) {
+    if (!node || node.type !== "code" || typeof node.value !== "string") {
+      continue;
+    }
+    const field = fieldsByLang[codeFenceLang(node.lang) ?? ""];
+    if (field) {
+      (out as Record<string, string>)[field] = node.value;
+    }
+  }
+  return out;
+}
+
+/**
+ * Serialize selected string data fields as named child code fences. Uses a fence
+ * length that cannot be closed by the field body.
+ */
+export function serializeChildCodeFenceFields<TData extends object>(
+  data: TData,
+  fieldsByLang: Record<string, keyof TData & string>,
+): string {
+  const fences: string[] = [];
+  const record = data as Record<string, unknown>;
+  for (const [lang, field] of Object.entries(fieldsByLang)) {
+    const value = record[field];
+    if (typeof value !== "string" || value.length === 0) continue;
+    const fence = codeFenceFor(value);
+    fences.push(`${fence}${lang}\n${value.trimEnd()}\n${fence}`);
+  }
+  return fences.length ? `\n${fences.join("\n\n")}\n` : "";
+}
+
+/* -------------------------------------------------------------------------- */
+/* Registry serialize / parse                                                 */
+/* -------------------------------------------------------------------------- */
+
+/** The base-attribute + body shape every block carries. */
+export interface SerializableBlock {
+  id: string;
+  title?: string;
+  summary?: string;
+  editable?: boolean;
+  data: unknown;
+}
+
+/** Base block attributes parsed from a node, before the type-specific data. */
+export interface ParsedBlockBase {
+  id: string;
+  title?: string;
+  summary?: string;
+  editable?: boolean;
+}
+
+/**
+ * Serialize a block to its MDX element using its spec. Byte output MUST match
+ * the legacy `serializeBlock` for every converted block: base attrs
+ * (`id,title,summary,editable`) first, then the spec's `toAttrs` in insertion
+ * order, then either nested children, prose children, or self-closing.
+ */
+export function serializeSpecBlock(
+  spec: BlockSpec<any>,
+  block: SerializableBlock,
+): string {
+  const base =
+    prop("id", block.id) +
+    prop("title", block.title) +
+    prop("summary", block.summary) +
+    prop("editable", block.editable);
+
+  const attrs = spec.mdx.toAttrs(block.data);
+  const childrenField = spec.mdx.childrenField;
+  const attrStr = Object.entries(attrs)
+    .filter(([key]) => key !== childrenField)
+    .map(([key, value]) => prop(key, value as MdxAttrValue | undefined))
+    .join("");
+
+  const tag = spec.mdx.tag;
+
+  // Custom nested-MDX children (e.g. wireframe Screen/kit tree).
+  if (spec.mdx.serializeChildren) {
+    const children = spec.mdx.serializeChildren(block.data);
+    if (!children.trim()) return `<${tag}${base}${attrStr} />`;
+    return `<${tag}${base}${attrStr}>\n${children}\n</${tag}>`;
+  }
+
+  // Prose children (rich-text, callout): body is a trimmed markdown string.
+  if (childrenField) {
+    const body = String(
+      (block.data as Record<string, unknown>)[childrenField] ?? "",
+    ).trim();
+    return `<${tag}${base}${attrStr}>\n\n${body}\n\n</${tag}>`;
+  }
+
+  // Self-closing structured block.
+  return `<${tag}${base}${attrStr} />`;
+}
+
+/**
+ * Parse one MDX JSX node into a block via the registry, if its tag is
+ * registered. Returns `null` for unregistered tags so the caller can fall back
+ * to its legacy parser. `base` is the already-extracted id/title/summary/
+ * editable; `children` is the stringified prose children.
+ */
+export function parseSpecBlock(
+  registry: BlockRegistry,
+  node: MdxJsxNode,
+  base: ParsedBlockBase,
+  children: string,
+  idContext: string,
+): { type: string; data: unknown } | null {
+  const tag = node.name;
+  if (!tag) return null;
+  const spec = registry.getByTag(tag);
+  if (!spec) return null;
+
+  const reader = createAttrReader(node);
+  let data: unknown;
+  if (spec.mdx.parseChildren) {
+    const fromAttrs = spec.mdx.fromAttrs(reader, children);
+    const fromChildren = spec.mdx.parseChildren(
+      node.children ?? [],
+      `${idContext}-${base.id}`,
+    );
+    data = { ...(fromAttrs as object), ...(fromChildren as object) };
+  } else {
+    data = spec.mdx.fromAttrs(reader, children);
+  }
+  return { type: spec.type, data };
+}

package/src/client/blocks/provider.tsx

@@ -0,0 +1,51 @@
+import { createContext, useContext, type ReactNode } from "react";
+
+import type { BlockRegistry } from "./registry.js";
+import type { BlockRenderContext } from "./types.js";
+
+/**
+ * React provision for the block registry. The registry itself is a per-app
+ * module singleton (so the server MDX serializer/parser and the agent schema
+ * export can import it outside React); this thin context threads that singleton
+ * plus the runtime {@link BlockRenderContext} (asset resolver, action caller,
+ * inline markdown editor, …) into the renderer, and lets tests swap registries.
+ */
+
+interface BlockRegistryValue {
+  registry: BlockRegistry;
+  ctx: BlockRenderContext;
+}
+
+const BlockRegistryContext = createContext<BlockRegistryValue | null>(null);
+
+export function BlockRegistryProvider({
+  registry,
+  ctx,
+  children,
+}: {
+  registry: BlockRegistry;
+  ctx: BlockRenderContext;
+  children: ReactNode;
+}) {
+  return (
+    <BlockRegistryContext.Provider value={{ registry, ctx }}>
+      {children}
+    </BlockRegistryContext.Provider>
+  );
+}
+
+/** Read the active registry + render context. Throws outside a provider. */
+export function useBlockRegistry(): BlockRegistryValue {
+  const value = useContext(BlockRegistryContext);
+  if (!value) {
+    throw new Error(
+      "useBlockRegistry must be used inside a <BlockRegistryProvider>.",
+    );
+  }
+  return value;
+}
+
+/** Read the active registry + render context, or `null` outside a provider. */
+export function useOptionalBlockRegistry(): BlockRegistryValue | null {
+  return useContext(BlockRegistryContext);
+}

package/src/client/blocks/registry.ts

@@ -0,0 +1,83 @@
+import type { BlockSpec, BlockPlacement } from "./types.js";
+
+/**
+ * In-memory block registry. Holds two lookups: by runtime `type` (render +
+ * serialize side) and by MDX `tag` (parse side). The registry is a plain object
+ * usable both inside React (via the context provider) and outside it (the
+ * server MDX serializer/parser, agent schema export) — mirroring how the legacy
+ * `BLOCK_COMPONENTS` set and `serializeBlock`/`parseBlock` are plain functions.
+ */
+export class BlockRegistry {
+  private byType = new Map<string, BlockSpec<any>>();
+  private byTag = new Map<string, BlockSpec<any>>();
+
+  /**
+   * Register (or re-register) a block spec. Last registration wins: re-registering
+   * an existing block `type` (or MDX `tag`) OVERRIDES the previous spec rather than
+   * throwing. This lets an app intentionally override a shared library block with
+   * its own variant, and makes module-level registration idempotent under dev HMR
+   * (which can re-run a registration module against a registry that survived the
+   * reload). When a re-registered type changes its MDX tag, the stale tag mapping
+   * is dropped so `getByTag` can't return an orphaned spec.
+   */
+  register(spec: BlockSpec<any>): void {
+    const prevForType = this.byType.get(spec.type);
+    if (prevForType && prevForType.mdx.tag !== spec.mdx.tag) {
+      this.byTag.delete(prevForType.mdx.tag);
+    }
+    this.byType.set(spec.type, spec);
+    this.byTag.set(spec.mdx.tag, spec);
+  }
+
+  get(type: string): BlockSpec<any> | undefined {
+    return this.byType.get(type);
+  }
+
+  getByTag(tag: string): BlockSpec<any> | undefined {
+    return this.byTag.get(tag);
+  }
+
+  has(type: string): boolean {
+    return this.byType.has(type);
+  }
+
+  hasTag(tag: string): boolean {
+    return this.byTag.has(tag);
+  }
+
+  /** All registered MDX tags — replaces the hardcoded `BLOCK_COMPONENTS` set. */
+  tags(): Set<string> {
+    return new Set(this.byTag.keys());
+  }
+
+  /**
+   * The set of registered block `type`s whose specs declare
+   * `notionCompatible: true` — i.e. they round-trip to Notion-Flavored Markdown
+   * and may sync to Notion. Apps use this as the registry-backed part of their
+   * Notion gating allowlist; prose-only NFM analogs that are not registry atoms
+   * (rich-text, callout) are NOT in here — apps union those in separately.
+   */
+  notionCompatibleTypes(): Set<string> {
+    const types = new Set<string>();
+    for (const spec of this.byType.values()) {
+      if (spec.notionCompatible) types.add(spec.type);
+    }
+    return types;
+  }
+
+  /** All registered specs, optionally filtered by placement. */
+  list(placement?: BlockPlacement): BlockSpec<any>[] {
+    const all = [...this.byType.values()];
+    return placement
+      ? all.filter((spec) => spec.placement.includes(placement))
+      : all;
+  }
+}
+
+/** Register a batch of specs in order. */
+export function registerBlocks(
+  registry: BlockRegistry,
+  specs: BlockSpec<any>[],
+): void {
+  for (const spec of specs) registry.register(spec);
+}

package/src/client/blocks/schema-form/introspect.ts

@@ -0,0 +1,201 @@
+import { z, type ZodType, type ZodTypeAny } from "zod";
+
+/**
+ * Schema introspection for the auto-editor. Walks a block's zod `data` schema
+ * and classifies each top-level field into a {@link FieldKind} the
+ * `SchemaBlockEditor` knows how to render.
+ *
+ * zod v4 note: schemas expose `_def.type` (a string discriminator) rather than
+ * v3's `typeName`. Object shape is `_def.shape`, array element is `_def.element`,
+ * enum options are `.options`. `.describe()` does NOT propagate through
+ * `.optional()`/`.default()`/`.nullable()` to the outer schema, so `unwrap`
+ * inherits the innermost description while peeling wrapper layers.
+ */
+
+const MD_TAG = "x-an-field:markdown";
+const RT_TAG = "x-an-field:richtext";
+
+/**
+ * Tag a string schema so the auto-editor renders it with the shared inline
+ * rich-markdown editor (Notion-style editing) instead of a plain textarea.
+ * Survives `.optional()` because `unwrap` reads the inner description.
+ */
+export function markdown(schema: ZodTypeAny = z.string()): ZodTypeAny {
+  return schema.describe(MD_TAG);
+}
+
+/** Alias for {@link markdown} — tags a string field as rich text. */
+export function richtext(schema: ZodTypeAny = z.string()): ZodTypeAny {
+  return schema.describe(RT_TAG);
+}
+
+export type FieldKind =
+  | "markdown"
+  | "richtext"
+  | "text"
+  | "longtext"
+  | "number"
+  | "boolean"
+  | "enum"
+  | "array"
+  | "object"
+  | "unsupported";
+
+export interface FieldDescriptor {
+  key: string;
+  /** Humanized key for the field label. */
+  label: string;
+  kind: FieldKind;
+  optional: boolean;
+  enumValues?: string[];
+  /** Element schema for arrays / inner schema for objects. */
+  inner?: ZodTypeAny;
+  /** Element descriptors for object fields (one level of nesting). */
+  fields?: FieldDescriptor[];
+  /** Description tag, when present (used to detect markdown/richtext). */
+  description?: string;
+}
+
+function defType(schema: ZodTypeAny): string | undefined {
+  return (schema?._def as { type?: string } | undefined)?.type;
+}
+
+/** Peel optional/default/nullable/refine wrappers; keep the innermost description. */
+function unwrap(schema: ZodTypeAny): {
+  schema: ZodTypeAny;
+  optional: boolean;
+  description?: string;
+} {
+  let current = schema;
+  let optional = false;
+  let description: string | undefined = current?.description;
+  // Bound the loop so a malformed schema can never spin forever.
+  for (let i = 0; i < 12; i++) {
+    const type = defType(current);
+    const inner = (current._def as { innerType?: ZodTypeAny } | undefined)
+      ?.innerType;
+    if (type === "optional" || type === "nullable" || type === "nullish") {
+      optional = true;
+    } else if (type === "default" || type === "catch" || type === "readonly") {
+      // not optional per se, but a wrapper to peel
+    } else {
+      break;
+    }
+    if (!inner) break;
+    current = inner;
+    description = description ?? current.description;
+  }
+  return { schema: current, optional, description };
+}
+
+function humanize(key: string): string {
+  return key
+    .replace(/[_-]+/g, " ")
+    .replace(/([a-z])([A-Z])/g, "$1 $2")
+    .replace(/^\w/, (c) => c.toUpperCase());
+}
+
+function classify(schema: ZodTypeAny, description?: string): FieldKind {
+  if (description === MD_TAG) return "markdown";
+  if (description === RT_TAG) return "richtext";
+  const type = defType(schema);
+  switch (type) {
+    case "string": {
+      // A long max length implies a textarea; otherwise a single-line input.
+      const checks = (schema._def as { checks?: unknown[] } | undefined)
+        ?.checks;
+      const max = readMaxLength(checks);
+      return max !== undefined && max > 240 ? "longtext" : "text";
+    }
+    case "number":
+    case "bigint":
+      return "number";
+    case "boolean":
+      return "boolean";
+    case "enum":
+      return "enum";
+    case "array":
+      return "array";
+    case "object":
+      return "object";
+    default:
+      return "unsupported";
+  }
+}
+
+function readMaxLength(checks: unknown[] | undefined): number | undefined {
+  if (!checks) return undefined;
+  for (const check of checks) {
+    const def = (
+      check as { _zod?: { def?: { check?: string; maximum?: number } } }
+    )?._zod?.def;
+    if (def?.check === "max_length" && typeof def.maximum === "number") {
+      return def.maximum;
+    }
+    // Fallback for shapes that expose the bound directly.
+    const direct = check as { kind?: string; value?: number; maximum?: number };
+    if (direct?.kind === "max" && typeof direct.value === "number") {
+      return direct.value;
+    }
+    if (typeof direct?.maximum === "number") return direct.maximum;
+  }
+  return undefined;
+}
+
+function objectShape(schema: ZodTypeAny): Record<string, ZodTypeAny> | null {
+  const rawShape = (schema._def as { shape?: unknown } | undefined)?.shape;
+  if (!rawShape) return null;
+  const shape = typeof rawShape === "function" ? rawShape() : rawShape;
+  return shape && typeof shape === "object"
+    ? (shape as Record<string, ZodTypeAny>)
+    : null;
+}
+
+function describeField(key: string, raw: ZodTypeAny): FieldDescriptor {
+  const { schema, optional, description } = unwrap(raw);
+  const kind = classify(schema, description);
+  const descriptor: FieldDescriptor = {
+    key,
+    label: humanize(key),
+    kind,
+    optional,
+    description,
+  };
+  if (kind === "enum") {
+    const options = (schema as { options?: unknown[] }).options;
+    descriptor.enumValues = Array.isArray(options)
+      ? options.map((value) => String(value))
+      : [];
+  } else if (kind === "array") {
+    const element = (schema._def as { element?: ZodTypeAny } | undefined)
+      ?.element;
+    descriptor.inner = element;
+    const elementShape = element ? objectShape(unwrap(element).schema) : null;
+    if (elementShape) {
+      descriptor.fields = Object.entries(elementShape).map(
+        ([childKey, child]) => describeField(childKey, child),
+      );
+    }
+  } else if (kind === "object") {
+    descriptor.inner = schema;
+    const shape = objectShape(schema);
+    if (shape) {
+      descriptor.fields = Object.entries(shape).map(([childKey, child]) =>
+        describeField(childKey, child),
+      );
+    }
+  }
+  return descriptor;
+}
+
+/**
+ * Introspect a block's `data` schema into a flat list of field descriptors. The
+ * input is unwrapped to its object schema first (so an `.optional()`-wrapped or
+ * `.refine()`-wrapped object still yields its fields).
+ */
+export function introspect(schema: ZodType<unknown>): FieldDescriptor[] {
+  const { schema: unwrapped } = unwrap(schema as ZodTypeAny);
+  const shape = objectShape(unwrapped);
+  if (!shape) return [];
+  return Object.entries(shape).map(([key, child]) => describeField(key, child));
+}