@bloklabs/react 1.6.2 → 1.8.0

package/src/useBlok.ts

@@ -10,9 +10,15 @@ import {
   type BlockPortalRegistry,
 } from './block-portal-registry';
 import { setRegistry, removeRegistry } from './registry-map';
+import { setContentBaseline, removeContentBaseline } from './content-baseline-map';
 import { bindLiveToolConfigFunctions, buildLiveBlockConfig } from './live-tool-config';
-import { createEmittedEchoWindow, normalizeReadOnlyConfig, toRenderableData } from '@bloklabs/core/adapters';
-import type { Blok } from '@/types';
+import {
+  createEmittedEchoWindow,
+  equalsOutputData,
+  normalizeReadOnlyConfig,
+  toRenderableData,
+} from '@bloklabs/core/adapters';
+import type { Blok, LiveHandlers } from '@/types';
 import type { UseBlokConfig } from './types';
 
 interface EditorInstanceState {
@@ -135,12 +141,15 @@ export function useBlok(configInput: UseBlokConfig, deps?: DependencyList): Blok
   const depsToken = useMemo(() => ({}), deps ?? []);
 
   // Tracks the data the editor currently reflects — set when content is seeded
-  // or rendered (the reactive `data` effect below) AND when the editor emits its
-  // own serialized content via `onSave`. The latter is what makes a controlled
-  // `onSave -> setData -> data` round-trip a no-op: the echoed payload deep-equals
-  // this baseline, so the data effect skips the redundant render() (which would
-  // otherwise reset the caret). Declared here so the `onSave` wrapper below can
-  // update it before the consumer's setState re-runs the data effect.
+  // or rendered (the reactive `data` effect below), when the editor emits its
+  // own serialized content via `onSave`, and when an IMPERATIVE call changed the
+  // content out of band (the content-baseline channel registered below). The
+  // `onSave` writer is what makes a controlled `onSave -> setData -> data`
+  // round-trip a no-op: the echoed payload content-equals this baseline, so the
+  // data effect skips the redundant render() (which would otherwise reset the
+  // caret). Declared here so the `onSave` wrapper below can update it before the
+  // consumer's setState re-runs the data effect. `undefined` means "nothing
+  // recorded yet" — never an empty document.
   const lastRenderedDataRef = useRef(config.data);
   // Window of recently emitted `onSave` payloads. The baseline above only
   // remembers the LAST one, but a host that persists on save and refetches can
@@ -172,6 +181,19 @@ export function useBlok(configInput: UseBlokConfig, deps?: DependencyList): Blok
   // Last-applied tool-level `toolbox` setting per tool name (dedupe baseline for
   // the reactive toolbox effect below). Seeded from the construction-time tools.
   const appliedToolboxRef = useRef<Map<string, unknown>>(new Map());
+  // Live callback channel (see the handler-presence effect below): the current
+  // editor's stable per-handler wrappers (each forwards to the LATEST render's
+  // prop through `configRef`, so their identity never changes) and the presence
+  // actually installed on that editor — the dedupe baseline.
+  const handlerWrappersRef = useRef<LiveHandlers | null>(null);
+  const appliedHandlerPresenceRef = useRef<Record<keyof LiveHandlers, boolean>>({
+    onChange: false,
+    onSave: false,
+    onEnter: false,
+    onSubmit: false,
+    onBeforeRender: false,
+    onAfterRender: false,
+  });
 
   // Main lifecycle effect
   useEffect(() => {
@@ -212,6 +234,7 @@ export function useBlok(configInput: UseBlokConfig, deps?: DependencyList): Blok
     if (state.editor !== null && !state.isDestroyed) {
       removeHolder(state.editor);
       removeRegistry(state.editor);
+      removeContentBaseline(state.editor);
       try {
         state.editor.destroy();
       } catch {
@@ -259,60 +282,69 @@ export function useBlok(configInput: UseBlokConfig, deps?: DependencyList): Blok
       ])
     );
 
-    const blokConfig = {
-      ...currentConfig,
-      ...(liveTools === undefined ? {} : { tools: liveTools as UseBlokConfig['tools'] }),
-      holder,
-      onReady: (...args: Parameters<NonNullable<UseBlokConfig['onReady']>>): void => {
-        configRef.current.onReady?.(...args);
-      },
+    // Stable per-editor wrappers for the live callback config. Each forwards to
+    // the LATEST render's prop through `configRef`, so a consumer never has to
+    // freeze callback identities — and, because identity is fixed for the
+    // editor's life, only PRESENCE has to be synced afterwards (below).
+    const handlerWrappers: LiveHandlers = {
       onChange: (...args: Parameters<NonNullable<UseBlokConfig['onChange']>>): void => {
         configRef.current.onChange?.(...args);
       },
-      // Forward the return value: it is the "handled" signal the core acts on.
-      onEnter: (...args: Parameters<NonNullable<UseBlokConfig['onEnter']>>): boolean | void =>
-        configRef.current.onEnter?.(...args),
-    };
-
-    // Only attach onSubmit when the consumer opted in: its mere presence makes
-    // Enter serialize-and-submit instead of splitting a block, so an absent prop
-    // must stay absent. The wrapper reads through the ref so the latest callback
-    // is always used without recreating the editor.
-    if (currentConfig.onSubmit) {
-      blokConfig.onSubmit = (...args: Parameters<NonNullable<UseBlokConfig['onSubmit']>>): void => {
-        configRef.current.onSubmit?.(...args);
-      };
-    }
-
-    // Only attach onSave when the consumer opted in: its mere presence makes the
-    // core serialize on every change batch, so an absent prop must stay absent.
-    // The wrapper reads through the ref so the latest callback is always used.
-    if (currentConfig.onSave) {
-      blokConfig.onSave = (...args: Parameters<NonNullable<UseBlokConfig['onSave']>>): void => {
+      onSave: (...args: Parameters<NonNullable<UseBlokConfig['onSave']>>): void => {
         // Record the editor's own serialized output as the rendered baseline so a
         // controlled consumer echoing it straight back into `data` is a no-op —
         // no redundant render(), no caret reset, no round-trip recursion.
         lastRenderedDataRef.current = args[0];
         echoWindowRef.current.record(args[0]);
         configRef.current.onSave?.(...args);
-      };
-    }
-
-    // onBeforeRender / onAfterRender are opt-in (absent prop must stay absent so
-    // the core skips them). When present, route through the ref so the latest
-    // callback is always used without recreating the editor.
-    if (currentConfig.onBeforeRender) {
-      blokConfig.onBeforeRender = (
+      },
+      // Forward the return value: it is the "handled" signal the core acts on.
+      onEnter: (...args: Parameters<NonNullable<UseBlokConfig['onEnter']>>): boolean | void =>
+        configRef.current.onEnter?.(...args),
+      onSubmit: (...args: Parameters<NonNullable<UseBlokConfig['onSubmit']>>): void => {
+        configRef.current.onSubmit?.(...args);
+      },
+      onBeforeRender: (
         ...args: Parameters<NonNullable<UseBlokConfig['onBeforeRender']>>
       ): ReturnType<NonNullable<UseBlokConfig['onBeforeRender']>> =>
-        configRef.current.onBeforeRender?.(...args) ?? args[0];
-    }
-
-    if (currentConfig.onAfterRender) {
-      blokConfig.onAfterRender = (...args: Parameters<NonNullable<UseBlokConfig['onAfterRender']>>): void => {
+        configRef.current.onBeforeRender?.(...args) ?? args[0],
+      onAfterRender: (...args: Parameters<NonNullable<UseBlokConfig['onAfterRender']>>): void => {
         configRef.current.onAfterRender?.(...args);
-      };
-    }
+      },
+    };
+
+    handlerWrappersRef.current = handlerWrappers;
+
+    // Handler PRESENCE is load-bearing in core — an `onSubmit` turns Enter into
+    // serialize-and-submit, an `onSave` arms the change pipeline — so an absent
+    // prop must leave the key absent. Attach only the wrappers whose prop the
+    // consumer actually passed, and record what was installed so the effect
+    // below can push later presence flips instead of recreating the editor.
+    const handlerPresence: Record<keyof LiveHandlers, boolean> = {
+      onChange: currentConfig.onChange !== undefined,
+      onSave: currentConfig.onSave !== undefined,
+      onEnter: currentConfig.onEnter !== undefined,
+      onSubmit: currentConfig.onSubmit !== undefined,
+      onBeforeRender: currentConfig.onBeforeRender !== undefined,
+      onAfterRender: currentConfig.onAfterRender !== undefined,
+    };
+
+    appliedHandlerPresenceRef.current = handlerPresence;
+
+    const blokConfig = {
+      ...currentConfig,
+      ...(liveTools === undefined ? {} : { tools: liveTools as UseBlokConfig['tools'] }),
+      holder,
+      onReady: (...args: Parameters<NonNullable<UseBlokConfig['onReady']>>): void => {
+        configRef.current.onReady?.(...args);
+      },
+      ...(handlerPresence.onChange ? { onChange: handlerWrappers.onChange } : {}),
+      ...(handlerPresence.onSave ? { onSave: handlerWrappers.onSave } : {}),
+      ...(handlerPresence.onEnter ? { onEnter: handlerWrappers.onEnter } : {}),
+      ...(handlerPresence.onSubmit ? { onSubmit: handlerWrappers.onSubmit } : {}),
+      ...(handlerPresence.onBeforeRender ? { onBeforeRender: handlerWrappers.onBeforeRender } : {}),
+      ...(handlerPresence.onAfterRender ? { onAfterRender: handlerWrappers.onAfterRender } : {}),
+    };
 
     const blok = new BlokRuntime(blokConfig);
     state.editor = blok;
@@ -321,6 +353,19 @@ export function useBlok(configInput: UseBlokConfig, deps?: DependencyList): Blok
     constructedDataRef.current = currentConfig.data;
     setHolder(blok, holder);
     setRegistry(blok, registry);
+    // Imperative-content channel: `useBlokHandle().clear()` / `.render()` change
+    // the content OUT OF BAND of the reactive `data` effect below. They report
+    // the new content here so the dedupe baseline and the emitted-echo window
+    // (both read by that effect) describe the editor as it actually is —
+    // otherwise restoring a document the editor itself emitted is dismissed as
+    // an echo and never rendered.
+    setContentBaseline(blok, {
+      markRendered: (content): void => {
+        echoWindowRef.current.clear();
+        lastRenderedDataRef.current = content;
+        pendingDataRef.current = undefined;
+      },
+    });
 
     void blok.isReady
       .then(() => {
@@ -333,6 +378,7 @@ export function useBlok(configInput: UseBlokConfig, deps?: DependencyList): Blok
         if (state.editor === blok && !state.isDestroyed) {
           removeHolder(blok);
           removeRegistry(blok);
+          removeContentBaseline(blok);
           try {
             blok.destroy();
           } catch {
@@ -445,6 +491,74 @@ export function useBlok(configInput: UseBlokConfig, deps?: DependencyList): Blok
     }
   });
 
+  // Reactive: onChange
+  // Reactive: onSave
+  // Reactive: onEnter
+  // Reactive: onSubmit
+  // Reactive: onBeforeRender
+  // Reactive: onAfterRender
+  //
+  // Callback PRESENCE was frozen at construction, and in core the presence of a
+  // handler IS the semantics: an `onSubmit` makes Enter serialize-and-submit
+  // instead of splitting the block, an `onSave` arms the whole change-observation
+  // pipeline. A host whose "Enter sends" toggle (or `onSave` subscription) lives
+  // in React state therefore had to bump `deps` and destroy/rebuild the editor,
+  // losing caret and undo history. Instead, diff each handler's presence against
+  // what is installed and push genuine flips through the runtime `handlers.set`
+  // API — passing `undefined` for a prop that disappeared, which is what makes
+  // the change reversible rather than a one-way latch. Identity never changes
+  // (the wrappers forward through `configRef`), so only presence is diffed.
+  // Applies once the editor is ready — module APIs attach at isReady — and the
+  // ready transition re-renders, so a flip made earlier is not lost.
+  useEffect(() => {
+    const state = stateRef.current;
+    const wrappers = handlerWrappersRef.current;
+
+    if (state.editor === null || state.isDestroyed || !state.isEditorReady || wrappers === null) {
+      return;
+    }
+
+    const latest = configRef.current;
+    const applied = appliedHandlerPresenceRef.current;
+    const diff: LiveHandlers = {};
+    const changed: { value: boolean } = { value: false };
+
+    const sync = <K extends keyof LiveHandlers>(key: K, write: (value: LiveHandlers[K]) => void): void => {
+      const present = latest[key] !== undefined;
+
+      if (present === applied[key]) {
+        return;
+      }
+
+      applied[key] = present;
+      changed.value = true;
+      write(present ? wrappers[key] : undefined);
+    };
+
+    sync('onChange', (value) => {
+      diff.onChange = value;
+    });
+    sync('onSave', (value) => {
+      diff.onSave = value;
+    });
+    sync('onEnter', (value) => {
+      diff.onEnter = value;
+    });
+    sync('onSubmit', (value) => {
+      diff.onSubmit = value;
+    });
+    sync('onBeforeRender', (value) => {
+      diff.onBeforeRender = value;
+    });
+    sync('onAfterRender', (value) => {
+      diff.onAfterRender = value;
+    });
+
+    if (changed.value) {
+      state.editor.handlers.set(diff);
+    }
+  });
+
   // Reactive: readOnly (object form normalized so the effect deps are stable booleans).
   // The object form additionally syncs `hideControls` through the options
   // parameter of `readOnly.set` — a plain boolean prop keeps the historical
@@ -597,11 +711,12 @@ export function useBlok(configInput: UseBlokConfig, deps?: DependencyList): Blok
   //
   // `data` seeds the editor at construction. Afterwards, changing the prop to
   // new *content* re-renders the editor via the public render() API — no
-  // recreation. Updates are deep-equal–deduped against the editor's current
-  // content baseline (`lastRenderedDataRef`, declared above and also updated by
-  // the `onSave` wrapper) so a new reference with the same content — including
-  // the editor's own serialized output echoed back — is a no-op and won't
-  // clobber the caret. Renders are serialized so rapid changes can't overlap.
+  // recreation. Updates are content-deduped against the editor's current
+  // baseline (`lastRenderedDataRef`, declared above and also updated by the
+  // `onSave` wrapper and the imperative content-baseline channel) so a new
+  // reference with the same content — including the editor's own serialized
+  // output echoed back, however the host reshaped it in transit — is a no-op and
+  // won't clobber the caret. Renders are serialized so rapid changes can't overlap.
   const { data } = config;
   useEffect(() => {
     if (editor === null || data === undefined) {
@@ -644,7 +759,20 @@ export function useBlok(configInput: UseBlokConfig, deps?: DependencyList): Blok
     // Skip when the editor already reflects this content (last SUCCESSFUL render)
     // OR a render of the same content is already queued/in-flight — re-rendering
     // identical content would needlessly reset the caret.
-    if (deepEqual(data, lastRenderedDataRef.current) || deepEqual(data, pendingDataRef.current)) {
+    //
+    // Compared with the SAME structural lens the echo window uses
+    // (`equalsOutputData`, not a raw deep-equal): a host that persists the
+    // editor's own document and hands back a stripped copy — fresh `time`,
+    // dropped ids, no `lastEditedAt` stamp — is still echoing content the editor
+    // already shows. `undefined` means "nothing recorded yet", which is NOT an
+    // empty document, so it must never match.
+    const baseline = lastRenderedDataRef.current;
+    const inFlight = pendingDataRef.current;
+
+    if (
+      (baseline !== undefined && equalsOutputData(data, baseline)) ||
+      (inFlight !== undefined && equalsOutputData(data, inFlight))
+    ) {
       return;
     }
 
@@ -701,6 +829,7 @@ function deferDestroy(
     if (state.editor !== null) {
       removeHolder(state.editor);
       removeRegistry(state.editor);
+      removeContentBaseline(state.editor);
       try {
         state.editor.destroy();
       } catch {

package/src/useBlokHandle.ts

@@ -1,4 +1,6 @@
 import { useRef, useMemo, type RefCallback } from 'react';
+import { EMPTY_OUTPUT_DATA } from '@bloklabs/core/adapters';
+import { getContentBaseline } from './content-baseline-map';
 import type { Blok, OutputData, LooseOutputData } from '@/types';
 
 /**
@@ -32,12 +34,22 @@ export interface BlokEditorHandle {
    * @param atEnd - place the caret at the end of the focused block
    */
   focus(atEnd?: boolean): boolean;
-  /** Clear all content. Resolves immediately (no-op) before ready. */
+  /**
+   * Clear all content. Resolves immediately (no-op) before ready.
+   *
+   * Safe to mix with a controlled `data` prop: the adapter's content baseline is
+   * updated once the clear lands, so setting `data` back to the document the
+   * editor itself emitted re-renders it instead of being dismissed as an echo.
+   */
   clear(): Promise<void>;
   /** Serialize the current content, or resolve to `null` before ready. */
   save(): Promise<OutputData | null>;
   /**
    * Render new content in place. Resolves immediately (no-op) before ready.
+   *
+   * Safe to mix with a controlled `data` prop: the rendered document becomes the
+   * adapter's content baseline, so a later `data` change back to the previous
+   * document still re-renders.
    * @param data - the document to render
    */
   render(data: OutputData | LooseOutputData): Promise<void>;
@@ -81,11 +93,35 @@ export function useBlokHandle(): BlokEditorHandle {
       return instanceRef.current !== null;
     },
     focus: (atEnd?: boolean): boolean => instanceRef.current?.focus(atEnd) ?? false,
-    clear: (): Promise<void> => instanceRef.current?.clear() ?? Promise.resolve(),
+    // clear/render change the content OUT OF BAND of the controlled `data`
+    // effect, so they report the result to the adapter's content baseline (see
+    // content-baseline-map). Reported only once the call RESOLVES: a failed one
+    // leaves the editor on its previous content, and a baseline pointing at
+    // content the editor never showed would dedupe away the correcting update.
+    clear: (): Promise<void> => {
+      const instance = instanceRef.current;
+
+      if (instance === null) {
+        return Promise.resolve();
+      }
+
+      return instance.clear().then(() => {
+        getContentBaseline(instance)?.markRendered(EMPTY_OUTPUT_DATA);
+      });
+    },
     save: (): Promise<OutputData | null> =>
       instanceRef.current !== null ? instanceRef.current.save() : Promise.resolve(null),
-    render: (data: OutputData | LooseOutputData): Promise<void> =>
-      instanceRef.current?.render(data) ?? Promise.resolve(),
+    render: (data: OutputData | LooseOutputData): Promise<void> => {
+      const instance = instanceRef.current;
+
+      if (instance === null) {
+        return Promise.resolve();
+      }
+
+      return instance.render(data).then(() => {
+        getContentBaseline(instance)?.markRendered(data);
+      });
+    },
     setReadOnly: (state?: boolean): Promise<boolean> => {
       const instance = instanceRef.current;
 

package/types/index.d.ts

@@ -1,6 +1,6 @@
 import type { BlokConfig, BlockToolData, OutputBlockData, OutputData, LooseOutputData } from '@bloklabs/core';
 import type { BlocksToHtmlOptions } from '@bloklabs/core/view';
-import type { BlockAPI, BlockToolConstructable, ToolboxConfigEntry } from '@bloklabs/core';
+import type { BlockAPI, BlockOrigin, BlockToolConstructable, ToolboxConfigEntry } from '@bloklabs/core';
 import type { InlineToolConstructable, SanitizerConfig } from '@bloklabs/core';
 import type { API, MarkSnapshot, MarkSpec } from '@bloklabs/core';
 import type { Blok, EditorWidth, BlockRenderedPayload, BlocksRenderedPayload } from '@bloklabs/core';
@@ -35,6 +35,13 @@ export { getDirection, normalizeLocale } from '@bloklabs/core/locales';
  *   forwarded — it only affects the initial locale resolution.
  * - `data` — re-renders via `editor.render(value)` when the content changes
  *   (deep-equal–deduped and serialized; seeds the initial content at creation)
+ * - `onChange`, `onSave`, `onEnter`, `onSubmit`, `onBeforeRender`,
+ *   `onAfterRender` — calls `editor.handlers.set({ ... })` when a callback
+ *   APPEARS or DISAPPEARS. Callback presence is load-bearing in core (an
+ *   `onSubmit` turns Enter into serialize-and-submit; an `onSave` arms the
+ *   change pipeline), so dropping the prop UNSETS the handler rather than
+ *   leaving a stale one behind. Callback IDENTITY is always live — the adapter
+ *   forwards to the latest render, so you never need to memoize them.
  *
  * All other config is consumed once at editor creation.
  */
@@ -162,11 +169,21 @@ export interface BlokEditorHandle {
   readonly isReady: boolean;
   /** Focus the editor. Returns whether focus landed; `false` (no-op) before ready. */
   focus(atEnd?: boolean): boolean;
-  /** Clear all content. Resolves immediately (no-op) before ready. */
+  /**
+   * Clear all content. Resolves immediately (no-op) before ready. Safe to mix
+   * with a controlled `data` prop: the adapter's content baseline is updated
+   * once the clear lands, so setting `data` back to a document the editor itself
+   * emitted re-renders it instead of being dismissed as an echo.
+   */
   clear(): Promise<void>;
   /** Serialize the current content, or resolve to `null` before ready. */
   save(): Promise<OutputData | null>;
-  /** Render new content in place. Resolves immediately (no-op) before ready. */
+  /**
+   * Render new content in place. Resolves immediately (no-op) before ready. Safe
+   * to mix with a controlled `data` prop: the rendered document becomes the
+   * adapter's content baseline, so a later `data` change back to the previous
+   * document still re-renders.
+   */
   render(data: OutputData | LooseOutputData): Promise<void>;
   /** Set or toggle read-only mode. Resolves to the resulting state; `false` (no-op) before ready. */
   setReadOnly(state?: boolean): Promise<boolean>;
@@ -205,6 +222,17 @@ export declare function BlokProvider(props: {
 /** Reads the app-wide Blok defaults from the nearest `BlokProvider` (or `{}`). */
 export declare function useBlokDefaults(): Partial<UseBlokConfig>;
 
+/**
+ * The live Blok instance a component is rendered inside, or null before it
+ * exists. Inside a `createReactBlock` component this is the block's OWN editor —
+ * `createPortal` preserves the component tree's context — so
+ * `useBlocks(useBlokInstance())` works with no host plumbing, and makes a
+ * container block reactive to its own child tree (`useBlocks` re-renders on the
+ * editor's `block changed` event). Outside a `BlokContent`/`BlokEditor` subtree
+ * it returns null.
+ */
+export declare function useBlokInstance(): Blok | null;
+
 /**
  * A plain, serializable view of one block in the tree.
  *
@@ -671,6 +699,14 @@ export interface ReactBlockRenderProps<Data, Config = Record<string, unknown>> {
   commit: (patch: Partial<Data>) => void;
   /** This block's per-block API. */
   block: BlockAPI;
+  /**
+   * The EDITOR-level API this block belongs to (`api.blocks`, `api.caret`,
+   * `api.toolbar`…) — the same object a vanilla tool receives in its
+   * constructor. For the reactive, id/parentId-relative view of the tree (and
+   * to re-render when your own children change), pair `useBlocks` with
+   * `useBlokInstance()` instead; the api handle itself is not reactive.
+   */
+  api: API;
   /**
    * Read-only flag. Toggled IN PLACE by core's read-only switch (no remount,
    * ephemeral state survives). Honor it — a block that ignores it stays
@@ -686,9 +722,41 @@ export interface ReactBlockRenderProps<Data, Config = Record<string, unknown>> {
    */
   config: Readonly<Partial<Config>>;
   /** Engine-owned child slot — render `<BlockChildren />` for a container block. */
-  BlockChildren: React.ComponentType;
+  BlockChildren: React.ComponentType<BlockChildrenProps>;
+}
+
+/**
+ * One child's decoration: attribute name -> value. `null`/`undefined` removes
+ * the attribute; a boolean or number is stringified (so `false` writes
+ * `data-active="false"`, which CSS can select, rather than dropping the hook).
+ */
+export type ChildAttributes = Record<string, string | number | boolean | null | undefined>;
+
+/** Props of the engine-owned {@link ReactBlockRenderProps.BlockChildren} slot. */
+export interface BlockChildrenProps {
+  /**
+   * Per-child decoration, applied to each child's HOLDER after the holders are
+   * mounted. Named hooks (`data-step-index`, `data-active`…) replace positional
+   * `:nth-child()` CSS over Blok's holders, which breaks the moment a child is
+   * inserted, removed or reordered. The holders stay DIRECT children of the slot
+   * (core requires that for hierarchy reparenting and caret navigation), so
+   * decoration is attributes, never wrapper elements. Attributes the callback
+   * stops producing are removed on the next pass.
+   *
+   * Writing on a child's holder is inert by design; the guarantee stops at the
+   * holder and its `[data-blok-element-content]` wrapper — writing AT or BELOW a
+   * child's tool root DOES score as that child's edit.
+   */
+  childAttributes?: (child: BlockAPI, index: number) => ChildAttributes;
 }
 
+/**
+ * Every STATIC member of core's block-tool contract a React block may declare
+ * for itself. `toolbox` and `isReadOnlySupported` are excluded — the factory
+ * owns them.
+ */
+export type BlockToolStatics = Omit<BlockToolConstructable, 'toolbox' | 'isReadOnlySupported'>;
+
 /**
  * Props handed to a React block's `viewComponent` (the read-only renderer):
  * the entry props minus `commit` (no write path) and `readOnly` (always true).
@@ -739,11 +807,92 @@ export interface CreateReactBlockSpec<
    * omit it to keep the single-component in-place toggle.
    */
   viewComponent?: React.ComponentType<ReactBlockViewProps<Data, Config>>;
+  /**
+   * Static members of core's tool contract, forwarded verbatim onto the
+   * generated tool class (`ownsChildren`, `keepsChildrenOnEnter`,
+   * `conversionConfig`, `pasteConfig`, `sanitize`, `shortcut`, `upgradeData`…)
+   * — the single channel for everything core reads off the CLASS rather than
+   * the instance.
+   *
+   * `keepsChildrenOnEnter` is the per-tool Enter policy: declare it and Enter on
+   * this container's empty LAST child creates the new line INSIDE it instead of
+   * escaping to the container's parent (Blok's default, which is Notion's
+   * callout behaviour). It is policy the DOM cannot express — a callout renders
+   * the same nested-blocks slot as a column yet wants the escape — so a layout
+   * container (a card, a `steps` block) had to hijack the editor-global
+   * `config.onEnter` before it existed.
+   */
+  statics?: BlockToolStatics;
+  /**
+   * The element the +/drag toolbar should vertically center on — core's
+   * `getToolbarAnchorElement` hook, resolved against this block's host element
+   * on every call. A container block whose own chrome is not editable needs it:
+   * with no anchor, core centers the toolbar on the first `[contenteditable]`
+   * under the host, which for a container is its FIRST CHILD BLOCK. Return
+   * `null`/`undefined` (or omit) to keep core's default.
+   */
+  getToolbarAnchorElement?: (host: HTMLElement, block: BlockAPI) => HTMLElement | null | undefined;
   onRendered?: (block: BlockAPI) => void;
+  /**
+   * Fired ONCE per block instance, after the portal's FIRST commit — the first
+   * moment this block's rendered DOM exists (and, for a container, the moment
+   * `<BlockChildren />` has adopted the child holders). `onRendered` cannot mean
+   * that: core calls `rendered()` in the same tick as `render()`, before React
+   * has drawn anything.
+   *
+   * It is also the create-vs-restore signal: `context.origin` says whether the
+   * author just made this block (`user`/`api`/`convert`) or the document is
+   * being re-materialised (`load`/`replay`/`paste`), so a container can seed its
+   * default children here exactly once.
+   *
+   * To observe OTHER blocks settling — e.g. before placing the caret in a child
+   * you just inserted — listen for the `block:childrenMounted` editor event
+   * instead: `api.events.on('block:childrenMounted', ({ blockId, childIds }) => …)`.
+   */
+  onMounted?: (block: BlockAPI, context: ReactBlockMountedContext) => void;
+  /**
+   * The SEEDING hook: `onMounted`, narrowed to a genuine creation. Fired ONCE
+   * per block instance, after the portal's first commit, and only when the
+   * author just made this block (`origin` of `user`, `api` or `convert`) —
+   * never for a `load`/`replay`/`paste` restore, and never for the off-tree
+   * `probe` instance core builds to read a tool's default data.
+   *
+   * Prefer it over hand-testing `context.origin` in `onMounted`: the intuitive
+   * `origin === 'user'` check is wrong — it drops `api.blocks.insert(...)` and
+   * turn-into, so the container comes up empty for every path except a
+   * keystroke.
+   * @example
+   * ```tsx
+   * onCreated: (block, { api }) => {
+   *   if (block.getChildren().length === 0) {
+   *     api.blocks.insertInsideParent(block.id);
+   *   }
+   * }
+   * ```
+   */
+  onCreated?: (block: BlockAPI, context: ReactBlockMountedContext) => void;
   onMoved?: (block: BlockAPI) => void;
   onRemoved?: (block: BlockAPI) => void;
 }
 
+/**
+ * Second argument of {@link CreateReactBlockSpec.onMounted} and
+ * {@link CreateReactBlockSpec.onCreated}.
+ */
+export interface ReactBlockMountedContext {
+  /**
+   * Why this block instance was constructed. CREATION origins (`user`, `api`,
+   * `convert`) mean the author just made it, so seeding default children is
+   * correct; RESTORE origins (`load`, `replay`, `paste`) mean the document
+   * already says what the children are. `probe` is an off-tree instance built
+   * only to read a tool's default data and must not touch the block tree.
+   * Defaults to `'api'`.
+   */
+  origin: BlockOrigin;
+  /** The editor-level API (`api.blocks`, `api.caret`, `api.events`…). */
+  api: API;
+}
+
 /**
  * Author a first-party React block: returns a `BlockToolConstructable`
  * registered exactly like a vanilla tool (`tools: { type: createReactBlock(...) }`).
@@ -940,7 +1089,13 @@ export interface BlockPortalEntry {
  */
 export interface BlockPortalRegistry {
   register(id: string, entry: BlockPortalEntry): void;
-  unregister(id: string): void;
+  /**
+   * Remove the entry for `id`. Pass the caller's own `hostEl` to make the
+   * removal ownership-checked — the entry is deleted only when it is still the
+   * one that host registered, so a superseded owner's late teardown can never
+   * clobber a same-id re-register.
+   */
+  unregister(id: string, hostEl?: HTMLElement): void;
   setProps(id: string, props: Record<string, unknown>): void;
   /**
    * Replace the `config` prop of every entry registered under `toolName`, and