Make plugin-declared Portable Text blocks editable in the admin (proposal for #637)

[all3f0r1]

Context

#637 reports that custom Portable Text block types declared by plugins (e.g. marketing.hero, marketing.text-image) are not editable in the admin: they show up as opaque [Marketing.hero] labels with no way to expand or modify their fields. The blocks render correctly on the site via <PortableText components={…} />, and the field data is intact in the DB — the gap is entirely in the admin editing surface.

Related: #84 (slash discoverability), #103 (toolbar intercepts PT clicks), #152 (marketplace plugins with PT blocks).

Per CONTRIBUTING.md, opening this in Ideas before any feature PR.

Problem (with file:line evidence)

The plugin API and runtime already declare and surface custom block schemas. The editor just doesn't read them.

1. Plugin API supports field schemas — packages/core/src/plugins/types.ts:1170-1183 defines PortableTextBlockConfig.fields?: PortableTextBlockField[] (Block Kit elements).
2. Runtime forwards them onto the manifest — packages/core/src/emdash-runtime.ts:1228-1267 exposes plugins[id].portableTextBlocks (with fields) on GET /_emdash/api/manifest.
3. Editor never consumes the manifest. In packages/core/src/components/InlinePortableTextEditor.tsx:
   • ptToPM (lines 415-430) coerces unknown block types into a pluginBlock node that only keeps { blockType, id } — every other field is dropped.
   • pmToPT (lines 205-210) serialises back as { _type, _key, id } — the PT → PM → PT round-trip is lossy and silently destroys structured field data.
   • useEditor({ extensions: [...] }) at lines 1700-1738 has no pluginBlock extension, no NodeView, no way to render the declared fields as inputs.
4. Slash menu is static — createSlashCommandsExtension(...) at line 1690 has no input from the manifest, which is the discoverability gap in Make custom blocks explorable #84.
5. (Bonus, Toolbar click handler intercepts portableText fields, preventing inline editing #103) the visual-editing toolbar at packages/core/src/visual-editing/toolbar.ts (~line 1200) has no portableText arm and falls through to openAdmin(), stealing clicks from the inline editor.

Proposed implementation

Five small, additive changes in the admin/editor — no DB migration, no schema change, no plugin API break.

1. Lossless pluginBlock TipTap node. Add a data: Record<string, unknown> attribute carrying the entire block payload minus _type / _key. Stays an atom — the React NodeView owns its layout.
2. Round-trip patches. ptToPM routes any block whose _type matches a registered plugin block into pluginBlock with data = { …rest }. pmToPT spreads data back out. Result: lossless round-trip even for blocks whose plugin is currently disabled.
3. Manifest hook. A usePluginBlocks() React hook returns a Map<qualifiedType, PortableTextBlockConfig & { pluginId }> from the cached admin manifest.
4. React NodeView driven by Block Kit. Looks up the config, renders the declared fields using the existing @emdash-cms/blocks renderer (packages/blocks/src/renderer.tsx) bound to node.attrs.data, and writes back via updateAttributes({ data }). This is the same renderer sandboxed plugins already use for settings UI, so trusted and sandboxed plugins both get an editable block UI for free — which is the missing piece for Marketplace support for native plugins with componentsEntry and Portable Text blocks #152.
5. Manifest-driven slash commands. One slash menu entry per registered block, initialising data from each field's default value. Closes Make custom blocks explorable #84.
6. (Optional, Toolbar click handler intercepts portableText fields, preventing inline editing #103) add a portableText/richtext arm to the toolbar switch that no-ops, letting the inline editor receive the click. One line.

Compatibility & migration

• Existing data. Blocks written by the old code path ({ _type, id }) keep working: the NodeView renders declared fields with their defaults if the corresponding key is missing in data.
• Plugins with no fields. Falls back to the existing simple URL/id input, so URL-style embed plugins behave exactly as today.
• Frontend <PortableText components=…> is unchanged — the JSON shape on disk stays the same.
• No new manifest field, no DB migration.

Worked example

A plugin declaring a marketing.hero block with headline, subheadline, image, ctaLabel, ctaHref fields. With the proposal applied, the block appears in the slash menu under "Marketing → Hero", inserts with field defaults, renders its fields as a Block Kit form inside the NodeView, and serialises to the same PT JSON the site-side components.types["marketing.hero"] already consumes.

Repo

Full design doc, file:line citations, and per-step code sketches:

👉 https://github.com/all3f0r1/emdash-637-pt-blocks-editable

The repo is not a PR. It exists so the API surface and per-file diff shape can be reviewed in one place before any code lands in packages/core. If the approach is approved here, the implementation is ~5 small commits, one per numbered file in proposal/.

Out of scope (deliberate)

• Reordering field schemas at runtime (covered by existing settings flow).
• Storing block-instances as first-class content entries (Make custom blocks explorable #84 mentions this as an alternative; much bigger design, not required to unblock Admin editor does not render editable fields for custom Portable Text block types #637).
• Visual styling of the NodeView beyond the existing admin form aesthetic.

Asks

1. Is the lossless data-attribute approach the right shape, or do you prefer modelling each plugin block as its own typed TipTap node (per-block extension generated from the manifest)?
2. Is @emdash-cms/blocks' renderer the right reuse target inside the editor, or does the admin already have a different form runtime I should reach for instead?
3. OK to roll the Toolbar click handler intercepts portableText fields, preventing inline editing #103 toolbar fix into the same change set, or keep it separate?

[all3f0r1]

Ping @ascorbic, I would like your insight on this, please.

EDIT: and... I just noticed the now-merged #610, which is very much overlapping my proposal. Should I just close it?

[ascorbic]

@all3f0r1 I think most of this should now be implemented, right?

[all3f0r1]

Yeah, I think so too. Feel free to close it.

[ascorbic]

Thanks for your help!