@agent-native/core 0.42.0 → 0.43.0

package/dist/client/blocks/types.js.map

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

package/dist/client/rich-markdown-editor/DragHandle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DragHandle.d.ts","sourceRoot":"","sources":["../../../src/client/rich-markdown-editor/DragHandle.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAQzC,OAAO,KAAK,EAAE,IAAI,IAAI,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAChE,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD;;;;;;;;GAQG;AACH,eAAO,MAAM,oCAAoC,2BAA2B,CAAC;AAE7E,MAAM,WAAW,iBAAiB;IAChC;;;;;;;;OAQG;IACH,eAAe,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,CAAC,OAAO,EAAE;QAC9B,IAAI,EAAE,UAAU,CAAC;QACjB,IAAI,EAAE,eAAe,CAAC;QACtB,GAAG,EAAE,MAAM,CAAC;KACb,KAAK,OAAO,CAAC;IACd;;;;OAIG;IACH,uBAAuB,CAAC,EAAE,CACxB,IAAI,EAAE,OAAO,EACb,OAAO,EAAE;QACP,IAAI,EAAE,UAAU,CAAC;QACjB,IAAI,EAAE,eAAe,CAAC;QACtB,GAAG,EAAE,MAAM,CAAC;QACZ,UAAU,EAAE,UAAU,CAAC;KACxB,KACE,IAAI,CAAC;IACV;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,qBAAqB,KAAK,OAAO,CAAC;CACzE;AAuBD,MAAM,MAAM,uBAAuB,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;AAE5E,MAAM,MAAM,qBAAqB,GAAG;IAClC,IAAI,EAAE,UAAU,CAAC;IACjB,UAAU,EAAE,UAAU,CAAC;IACvB,UAAU,EAAE,eAAe,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,eAAe,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,uBAAuB,CAAC;CACpC,CAAC;AAuTF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,UAAU,mCAu6BrB,CAAC"}
+{"version":3,"file":"DragHandle.d.ts","sourceRoot":"","sources":["../../../src/client/rich-markdown-editor/DragHandle.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAQzC,OAAO,KAAK,EAAE,IAAI,IAAI,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAChE,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD;;;;;;;;GAQG;AACH,eAAO,MAAM,oCAAoC,2BAA2B,CAAC;AAE7E,MAAM,WAAW,iBAAiB;IAChC;;;;;;;;OAQG;IACH,eAAe,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,CAAC,OAAO,EAAE;QAC9B,IAAI,EAAE,UAAU,CAAC;QACjB,IAAI,EAAE,eAAe,CAAC;QACtB,GAAG,EAAE,MAAM,CAAC;KACb,KAAK,OAAO,CAAC;IACd;;;;OAIG;IACH,uBAAuB,CAAC,EAAE,CACxB,IAAI,EAAE,OAAO,EACb,OAAO,EAAE;QACP,IAAI,EAAE,UAAU,CAAC;QACjB,IAAI,EAAE,eAAe,CAAC;QACtB,GAAG,EAAE,MAAM,CAAC;QACZ,UAAU,EAAE,UAAU,CAAC;KACxB,KACE,IAAI,CAAC;IACV;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,qBAAqB,KAAK,OAAO,CAAC;CACzE;AAqCD,MAAM,MAAM,uBAAuB,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;AAE5E,MAAM,MAAM,qBAAqB,GAAG;IAClC,IAAI,EAAE,UAAU,CAAC;IACjB,UAAU,EAAE,UAAU,CAAC;IACvB,UAAU,EAAE,eAAe,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,eAAe,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,uBAAuB,CAAC;CACpC,CAAC;AAiWF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,UAAU,mCA67BrB,CAAC"}

package/dist/client/rich-markdown-editor/DragHandle.js

@@ -12,9 +12,23 @@ import { Plugin, PluginKey, NodeSelection, TextSelection, } from "@tiptap/pm/sta
 export const DEFAULT_DRAG_HANDLE_WRAPPER_SELECTOR = ".visual-editor-wrapper";
 const dragHandleKey = new PluginKey("dragHandle");
 const HOVER_SIDE_OUTSET_REM = 8;
-const SIDE_DROP_ZONE_RATIO = 0.28;
-const SIDE_DROP_ZONE_MIN_PX = 48;
-const SIDE_DROP_ZONE_MAX_PX = 140;
+// Notion-style side drop: drag a block to a neighbour's LEFT/RIGHT region and it
+// builds (or joins) a column layout instead of reordering. The activation region
+// has to be GENEROUS or the gesture is dead for a real human — a natural drag
+// releases somewhere over the block's body, nowhere near a thin edge sliver. The
+// old values (28% of width, capped at 140px, AND only the vertical middle 60%)
+// left a wide ~820px plan block with two ~17%-of-width edge slivers in a 35px-tall
+// band as the ONLY column targets — ~66% of the block (the whole centre) plus the
+// top/bottom only ever reordered, so "drag side by side" essentially never made
+// columns. Now each side claims ~a third of the width across the FULL block
+// height, with a middle band always preserved for before/after reorder.
+const SIDE_DROP_ZONE_RATIO = 0.33;
+const SIDE_DROP_ZONE_MIN_PX = 56;
+const SIDE_DROP_ZONE_MAX_PX = 320;
+// Never let the two side zones swallow the whole block: keep at least the middle
+// ~10% of the width as the before/after reorder band so dropping over the centre
+// still moves the block above/below the target (Notion keeps reorder reachable).
+const SIDE_DROP_ZONE_MAX_WIDTH_FRACTION = 0.45;
 const DRAG_HANDLE_MENU_STYLE_ID = "an-rich-md-drag-menu-styles";
 const DRAG_HANDLE_MENU_WIDTH = 220;
 const DRAG_HANDLE_MENU_GAP = 6;
@@ -22,6 +36,12 @@ const DRAG_HANDLE_MENU_VIEWPORT_PADDING = 8;
 const dragHandleRegistrations = new Set();
 let dragHandleGlobalHoverListeners = 0;
 let activeDragRegistration = null;
+// The registration whose grip is currently shown. Used to keep that grip alive
+// while the cursor travels from a block's body to its grip, even when the grip
+// sits in a contested gap (an inter-column gap or a tab body's left offset)
+// where another editor's wide forgiving zone would otherwise re-win the hover
+// and hide the grip out from under the approaching cursor.
+let activeHoverRegistration = null;
 const clamp = (value, min, max) => Math.min(Math.max(value, min), max);
 const editorArea = (registration) => {
     const rect = registration.view.dom.getBoundingClientRect();
@@ -32,6 +52,7 @@ const updateRegisteredHover = (clientX, clientY) => {
         for (const registration of dragHandleRegistrations) {
             registration.hideHover?.();
         }
+        activeHoverRegistration = null;
         return;
     }
     const candidates = [];
@@ -48,6 +69,34 @@ const updateRegisteredHover = (clientX, clientY) => {
             registration.hideHover?.();
         }
     }
+    // Grip keepalive. Once a block's grip is showing, hold it while the cursor
+    // travels LEFT of that block's content toward its grip glyph — within the
+    // block's own vertical row and no further left than the glyph itself. This is
+    // what makes grips grabbable for blocks that are NOT flush with the page's
+    // left gutter (a right column, a tab body): their grip sits in a gap that the
+    // neighbour's wide forgiving zone also claims, so the normal picker would flip
+    // hover to the neighbour mid-approach and the grip would vanish before the
+    // cursor reaches it. The keepalive only bridges the body→grip gap — it does
+    // NOT fire while the cursor is over content (so the innermost/nested picking
+    // and gutter-grab rules below still decide there) and the row guard stops it
+    // from sticking the grip across vertical moves to another block's row.
+    if (activeHoverRegistration) {
+        const held = candidates.find((candidate) => candidate.registration === activeHoverRegistration);
+        const grip = activeHoverRegistration.gripRect?.();
+        if (held &&
+            grip &&
+            clientY >= held.block.rect.top &&
+            clientY < held.block.rect.bottom &&
+            clientX >= grip.left - 4 &&
+            clientX < held.block.rect.left) {
+            for (const registration of dragHandleRegistrations) {
+                if (registration !== held.registration)
+                    registration.hideHover?.();
+            }
+            held.registration.showHoverBlock?.(held.block);
+            return;
+        }
+    }
     // Pick which editor owns the grip when several register a hover block at this
     // point. Nested region editors (e.g. each column inside a `columns` block) tile
     // their container's whole footprint AND extend a wide forgiving zone
@@ -101,6 +150,7 @@ const updateRegisteredHover = (clientX, clientY) => {
             registration.hideHover?.();
     }
     active?.registration.showHoverBlock?.(active.block);
+    activeHoverRegistration = active?.registration ?? null;
 };
 const handleGlobalHoverMove = (event) => {
     updateRegisteredHover(event.clientX, event.clientY);
@@ -613,18 +663,17 @@ export const DragHandle = Extension.create({
                 return null;
             let placement;
             const withinBlockY = clientY >= block.rect.top && clientY <= block.rect.bottom;
-            const withinSideDropBand = clientY >= block.rect.top + block.rect.height * 0.2 &&
-                clientY <= block.rect.bottom - block.rect.height * 0.2;
-            const sideZoneWidth = clamp(block.rect.width * SIDE_DROP_ZONE_RATIO, SIDE_DROP_ZONE_MIN_PX, SIDE_DROP_ZONE_MAX_PX);
+            // Side (column) zones span the FULL block height — only the horizontal
+            // position decides column-vs-reorder. Restricting to the vertical middle
+            // (the old 0.2 band) made the already-tiny edge slivers nearly unhittable.
+            const sideZoneWidth = Math.min(clamp(block.rect.width * SIDE_DROP_ZONE_RATIO, SIDE_DROP_ZONE_MIN_PX, SIDE_DROP_ZONE_MAX_PX), block.rect.width * SIDE_DROP_ZONE_MAX_WIDTH_FRACTION);
             if (registration.handleDrop &&
                 withinBlockY &&
-                withinSideDropBand &&
                 clientX <= block.rect.left + sideZoneWidth) {
                 placement = "left";
             }
             else if (registration.handleDrop &&
                 withinBlockY &&
-                withinSideDropBand &&
                 clientX >= block.rect.right - sideZoneWidth) {
                 placement = "right";
             }
@@ -706,11 +755,21 @@ export const DragHandle = Extension.create({
             const wrapperRect = wrapper.getBoundingClientRect();
             const editorRect = target.view.dom.getBoundingClientRect();
             session.dropTarget = target;
-            if (target.placement === "left" || target.placement === "right") {
-                const left = target.placement === "left" ? target.rect.left : target.rect.right;
-                session.dropLine.style.left = `${left - wrapperRect.left}px`;
+            // A column (side) drop and a reorder (before/after) drop both draw the
+            // `.notion-drop-indicator`, but they mean very different things, so the
+            // column case carries a modifier class apps style distinctly (a bolder,
+            // glowing vertical bar) — without a clear cue a human can't tell they've
+            // entered column-build mode before releasing.
+            const isColumnDrop = target.placement === "left" || target.placement === "right";
+            session.dropLine.classList.toggle("notion-drop-indicator--column", isColumnDrop);
+            if (isColumnDrop) {
+                // A vertical bar centred on the seam at the target's left/right edge,
+                // spanning the block's full height.
+                const SIDE_BAR_WIDTH = 4;
+                const seam = target.placement === "left" ? target.rect.left : target.rect.right;
+                session.dropLine.style.left = `${seam - wrapperRect.left - SIDE_BAR_WIDTH / 2}px`;
                 session.dropLine.style.top = `${target.rect.top - wrapperRect.top}px`;
-                session.dropLine.style.width = "3px";
+                session.dropLine.style.width = `${SIDE_BAR_WIDTH}px`;
                 session.dropLine.style.height = `${target.rect.height}px`;
                 return;
             }
@@ -939,6 +998,9 @@ export const DragHandle = Extension.create({
                         findHoverBlock: (clientX, clientY) => findForgivingBlock(editorView, clientX, clientY),
                         showHoverBlock: (block) => showHandleForBlock(editorView, block),
                         hideHover: () => hideHandle(),
+                        gripRect: () => handle && handle.style.display !== "none"
+                            ? handle.getBoundingClientRect()
+                            : null,
                     };
                     currentRegistration = registration;
                     dragHandleRegistrations.add(registration);
@@ -1010,6 +1072,9 @@ export const DragHandle = Extension.create({
                             if (activeDragRegistration === registration) {
                                 activeDragRegistration = null;
                             }
+                            if (activeHoverRegistration === registration) {
+                                activeHoverRegistration = null;
+                            }
                             handle?.remove();
                             handle = null;
                             currentRegistration = null;