@bloklabs/react 1.4.2 → 1.4.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bloklabs/react",
-  "version": "1.4.2",
+  "version": "1.4.3",
   "description": "React block editor — official React bindings for Blok, the headless Notion-like rich text editor. Hooks and components that render blocks and save to JSON.",
   "license": "Apache-2.0",
   "author": "JackUait",
@@ -54,7 +54,7 @@
     "test": "yarn run -T vitest run"
   },
   "peerDependencies": {
-    "@bloklabs/core": "^1.4.2",
+    "@bloklabs/core": "^1.4.3",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   }

package/src/BlokContent.tsx

@@ -2,8 +2,44 @@ import { useEffect, useRef, forwardRef } from 'react';
 import { getHolder } from './holder-map';
 import { getRegistry } from './registry-map';
 import { BlockPortalHost } from './BlockPortalHost';
+import type { Blok } from '@/types';
 import type { BlokContentProps } from './types';
 
+/**
+ * Re-drive the boot-time URL-hash scroll now that the editor's holder is in the
+ * document. Reads the current hash, decodes it (falling back to the raw value on
+ * a malformed percent-sequence, which simply matches no block), and asks the
+ * editor to scroll — a one-shot drain of the navigation the constructor deferred
+ * because the holder was detached. No-op when the URL carries no hash.
+ * @param editor - the ready Blok instance whose holder just connected
+ */
+function drainDeferredHashScroll(editor: Blok): void {
+  if (typeof window === 'undefined') {
+    return;
+  }
+
+  const raw = window.location.hash.slice(1);
+
+  if (raw === '') {
+    return;
+  }
+
+  editor.blocks.scrollToBlock?.(safeDecodeHashFragment(raw));
+}
+
+/**
+ * Decodes a URL hash fragment, falling back to the raw value on a malformed
+ * percent-sequence (e.g. `%ZZ`) — which simply matches no block downstream.
+ * @param raw - hash fragment without the leading `#`
+ */
+function safeDecodeHashFragment(raw: string): string {
+  try {
+    return decodeURIComponent(raw);
+  } catch {
+    return raw;
+  }
+}
+
 /**
  * Component that provides the DOM mount point for a Blok editor.
  * Renders a <div> and adopts the editor's detached holder DOM into it.
@@ -38,6 +74,14 @@ export const BlokContent = forwardRef<HTMLDivElement, BlokContentProps>(
 
       containerRef.current.appendChild(holder);
 
+      // The editor rendered its seeded content into this holder while it was
+      // still detached from the document, so the boot-time URL-hash scroll —
+      // which queries the LIVE document — found nothing and deferred. Now that
+      // the holder is connected, drain that deferred navigation once via the
+      // public scroll API (a no-op when there's no matching hash/block), so
+      // consumers don't have to hand-roll a DOM-polling hook.
+      drainDeferredHashScroll(editor);
+
       return (): void => {
         holder.remove();
       };

package/src/BlokEditor.tsx

@@ -38,9 +38,9 @@ import type { UseBlokConfig } from './types';
  */
 export interface BlokEditorProps
   extends Omit<UseBlokConfig, 'onReady'>,
-    // `onChange`/`onError` are Blok config callbacks here — drop the DOM
-    // element's same-named event handlers so the config signatures win.
-    Omit<HTMLAttributes<HTMLDivElement>, 'style' | 'onChange' | 'onError'> {
+    // `onChange`/`onError`/`onSubmit` are Blok config callbacks here — drop the
+    // DOM element's same-named event handlers so the config signatures win.
+    Omit<HTMLAttributes<HTMLDivElement>, 'style' | 'onChange' | 'onError' | 'onSubmit'> {
   /**
    * When any value changes, the editor is destroyed and recreated. Keep each
    * value referentially stable (primitives or useMemo-stable objects) — a dep
@@ -67,6 +67,18 @@ export interface BlokEditorProps
    * never recreate the editor or re-fire `onReady`.
    */
   onReady?: (editor: Blok) => void;
+  /**
+   * Library-neutral shorthand for the active locale — a plain BCP-47 string
+   * (`'en'`, `'ru-RU'`, `'nb'`) the host owns and updates. It is normalized and
+   * routed to `editor.i18n.update({ locale })` in place (caret/undo survive),
+   * so a host with its own language switcher never has to build an `i18n`
+   * config object or destroy the editor. Pair it with the re-exported
+   * `getDirection`/`normalizeLocale` to compute `dir` yourself.
+   *
+   * Shorthand for `i18n={{ locale }}`: if both are given, this wins. For
+   * message overrides or an explicit direction, use the full `i18n` prop.
+   */
+  locale?: string;
   /**
    * Called after a batch render completes (core `blocks:rendered` event). The
    * declarative analog of `ref.current.on('blocks:rendered', …)` — mirrors the
@@ -96,7 +108,7 @@ const CONFIG_KEY_SET = new Set<string>(USE_BLOK_CONFIG_KEYS);
  * ```
  */
 export const BlokEditor = forwardRef<Blok | null, BlokEditorProps>(
-  function BlokEditor({ deps, onReady, onBlocksRendered, onBlockRendered, ...rest }, ref) {
+  function BlokEditor({ deps, onReady, locale, onBlocksRendered, onBlockRendered, ...rest }, ref) {
     const config: Record<string, unknown> = {};
     const divProps: Record<string, unknown> = {};
 
@@ -110,6 +122,16 @@ export const BlokEditor = forwardRef<Blok | null, BlokEditorProps>(
       }
     }
 
+    // `locale` is a neutral shorthand for `i18n.locale`. Fold it into the i18n
+    // config (winning over any locale already there) so the single reactive
+    // `i18n.update` path in `useBlok` carries it — no separate resolver. A fresh
+    // object each render is fine: that path is deep-equal–deduped.
+    if (locale !== undefined) {
+      const existingI18n = config.i18n as Record<string, unknown> | undefined;
+
+      config.i18n = { ...existingI18n, locale };
+    }
+
     const editor = useBlok(config, deps);
 
     useImperativeHandle<Blok | null, Blok | null>(ref, () => editor, [editor]);

package/src/BlokView.tsx

@@ -1,13 +1,15 @@
-import type { ReactNode } from 'react';
+import type { HTMLAttributes, ReactNode } from 'react';
 import type { BlocksToHtmlOptions } from '@bloklabs/core/view';
 import type { LooseOutputData, OutputData } from '@bloklabs/core';
 
 import { useBlokView } from './useBlokView';
 
 /**
- * Props for {@link BlokView}.
+ * Props for {@link BlokView}. Beyond the render options below, any standard
+ * `<div>` attribute (`id`, `style`, `data-*`, `aria-*`, event handlers, …) is
+ * forwarded onto the single wrapper element.
  */
-export interface BlokViewProps {
+export interface BlokViewProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
   /** Saved document to display (strict or loose wire shape; nullish tolerated). */
   data: OutputData | LooseOutputData | null | undefined;
   /** View schema from `defineBlokSchema` — display under the composition that produced the document. */
@@ -16,22 +18,40 @@ export interface BlokViewProps {
   renderers?: BlocksToHtmlOptions['renderers'];
   /** Unknown-tool policy (default 'skip'). */
   onUnknownBlock?: BlocksToHtmlOptions['onUnknownBlock'];
-  /** Class for the single wrapper div. */
-  className?: string;
+  /** Stamp `data-blok-tool="<type>"` on each block root as a styling hook (pairs with the opt-in view stylesheet). */
+  toolAttributes?: BlocksToHtmlOptions['toolAttributes'];
+  /** Stamp `data-blok-id="<id>"` on each block root (list items on their `<li>`) for "copy link to block" deep links. */
+  blockIds?: BlocksToHtmlOptions['blockIds'];
+  /** Pure URL rewrite hook for block URLs + inline anchors, run before the unsafe-scheme strip. */
+  transformUrl?: BlocksToHtmlOptions['transformUrl'];
 }
 
 /**
  * Display a saved Blok document synchronously — one `<div>` wrapper, no
- * editor chrome, no ids, no async, no effects. Content is mapped from the
- * sanitized view tree to real React elements (never
- * `dangerouslySetInnerHTML`), so it renders identically under SSR.
+ * editor chrome, no async, no effects. Content is mapped from the sanitized
+ * view tree to real React elements (never `dangerouslySetInnerHTML`), so it
+ * renders identically under SSR.
  *
- * @experimental Built on the `@experimental` ViewNode tree of
- * `@bloklabs/core/view` — not frozen until a second framework adapter
- * consumes it.
+ * This is the intended read-only path — reach for it instead of mounting the
+ * full editing runtime (`BlokEditor readOnly`), which ships toolbar, history,
+ * and mutation machinery to every viewer. Pair with `defineBlokSchema` to
+ * display custom-tool content under the exact sanitization that produced it.
+ *
+ * The props API is semver-stable. Only the raw `ViewNode` tree that the
+ * bindings map from (via `blocksToViewNodes`) remains `@experimental` — using
+ * `BlokView`/`useBlokView` never exposes you to it.
  */
-export const BlokView = ({ data, schema, renderers, onUnknownBlock, className }: BlokViewProps): ReactNode => {
-  const content = useBlokView(data, { schema, renderers, onUnknownBlock });
+export const BlokView = ({
+  data,
+  schema,
+  renderers,
+  onUnknownBlock,
+  toolAttributes,
+  blockIds,
+  transformUrl,
+  ...divProps
+}: BlokViewProps): ReactNode => {
+  const content = useBlokView(data, { schema, renderers, onUnknownBlock, toolAttributes, blockIds, transformUrl });
 
-  return <div className={className}>{content}</div>;
+  return <div {...divProps}>{content}</div>;
 };

package/src/config-keys.ts

@@ -33,6 +33,7 @@ export const USE_BLOK_CONFIG_KEYS = [
   'onSave',
   'onError',
   'onEnter',
+  'onSubmit',
   'onBeforeRender',
   'onAfterRender',
   'inlineToolbar',

package/src/createReactBlock.tsx

@@ -61,8 +61,8 @@ export type ReactBlockViewProps<Data, Config = Record<string, unknown>> = Omit<
   'commit' | 'readOnly'
 >;
 
-/** A toolbox entry whose `icon` may be a React element instead of an SVG string. */
-export type ReactToolboxConfigEntry = Omit<ToolboxConfigEntry, 'icon'> & {
+/** A toolbox entry whose `icon`/`title` may be a React element instead of a string. */
+export type ReactToolboxConfigEntry = Omit<ToolboxConfigEntry, 'icon' | 'title'> & {
   /**
    * Toolbox icon. Core's toolbox chrome consumes markup strings, but React
    * authors may pass the same element they render in the block body — the
@@ -71,6 +71,17 @@ export type ReactToolboxConfigEntry = Omit<ToolboxConfigEntry, 'icon'> & {
    * returned as-is and serialization retries on the next browser-side access.
    */
   icon?: string | ReactElement;
+  /**
+   * Toolbox label. A plain string is translated by core through the
+   * `toolNames.*` namespace as usual. A ReactElement instead renders live in
+   * the HOST's React tree (via the editor's shared BlockPortalHost), so the
+   * label tracks the host's OWN i18n — no mirroring of strings into Blok's
+   * dictionary. Pair a ReactElement title with `titleKey` so multilingual
+   * search still resolves an English term. Requires the editor to be created
+   * through `useBlok`/`BlokEditor` (which wires the portal registry); a
+   * ReactElement title is dropped when the tool is used with vanilla core.
+   */
+  title?: string | ReactElement;
 };
 
 /** Toolbox config for React blocks: single entry or several variants. */
@@ -133,6 +144,13 @@ export function createReactBlock<Data = BlockToolData, Config = Record<string, u
 }) & {
   readonly __isBlokReactBlock: true;
   readonly toolbox: ToolboxConfig | undefined;
+  /**
+   * Adapter-internal: builds a per-editor toolbox whose ReactElement titles are
+   * live portals registered in `registry`. Called by `useBlok`; returns
+   * undefined when no entry has a ReactElement title. Not part of the public
+   * tool contract.
+   */
+  __buildPortalToolbox(registry: BlockPortalRegistry, toolName: string): ToolboxConfig | undefined;
   readonly isReadOnlySupported: boolean;
 } {
   /**
@@ -162,35 +180,120 @@ export function createReactBlock<Data = BlockToolData, Config = Record<string, u
     return markup === '' ? null : markup;
   };
 
-  const convertToolbox = (): { value: ToolboxConfig | undefined; complete: boolean } => {
-    const status = { complete: true };
+  /**
+   * Convert one React toolbox entry to a core-valid entry: serialize a React
+   * icon to markup, and DROP a ReactElement title (core titles are
+   * string | HTMLElement only). A string title passes through untouched; the
+   * live element title is re-attached per-editor by `buildPortalToolbox`.
+   *
+   * `deferred` is true when icon serialization could not complete (SSR /
+   * mid-render) and must be retried; the entry is returned with its element
+   * icon left in place.
+   *
+   * @param entry - the authored React toolbox entry
+   */
+  const toCoreEntry = (
+    entry: ReactToolboxConfigEntry
+  ): { entry: ToolboxConfigEntry; deferred: boolean } => {
+    const { icon, title, ...rest } = entry;
+    const core: ToolboxConfigEntry = { ...(rest as ToolboxConfigEntry) };
+
+    if (typeof title === 'string') {
+      core.title = title;
+    }
 
-    const toEntry = (entry: ReactToolboxConfigEntry): ToolboxConfigEntry => {
-      if (!isValidElement(entry.icon)) {
-        return entry as ToolboxConfigEntry;
+    if (!isValidElement(icon)) {
+      if (icon !== undefined) {
+        core.icon = icon;
       }
 
-      const markup = renderElementToMarkup(entry.icon);
+      return { entry: core, deferred: false };
+    }
 
-      if (markup === null) {
-        // Leave the element in place (a consumer reading `toolbox` outside the
-        // browser can still use it) and skip caching so a later browser-side
-        // access serializes it properly.
-        status.complete = false;
+    const markup = renderElementToMarkup(icon);
 
-        return entry as ToolboxConfigEntry;
-      }
+    if (markup === null) {
+      // Serialization deferred (SSR / mid-render): leave the element in place
+      // and skip caching so a later browser-side access serializes it.
+      (core as ReactToolboxConfigEntry).icon = icon;
 
-      return { ...entry, icon: markup };
-    };
+      return { entry: core, deferred: true };
+    }
+
+    core.icon = markup;
+
+    return { entry: core, deferred: false };
+  };
+
+  const convertToolbox = (): { value: ToolboxConfig | undefined; complete: boolean } => {
+    if (spec.toolbox === undefined) {
+      return { value: undefined, complete: true };
+    }
+
+    const entries = Array.isArray(spec.toolbox) ? spec.toolbox : [spec.toolbox];
+    const converted = entries.map((entry) => toCoreEntry(entry));
+    const complete = converted.every((result) => !result.deferred);
+    const coreEntries = converted.map((result) => result.entry);
+    const value = Array.isArray(spec.toolbox) ? coreEntries : coreEntries[0];
+
+    return { value, complete };
+  };
 
+  /**
+   * Build a per-editor toolbox in which every ReactElement title is a live
+   * portal: a Blok-owned mutation-free host element registered in the editor's
+   * `registry`, into which the ReactNode renders through the shared
+   * BlockPortalHost — so the label tracks the host's own i18n.
+   *
+   * Returns undefined when no entry has a ReactElement title (nothing to
+   * override; the static string/`toolNames.*` path already covers it).
+   *
+   * @param registry - the editor's portal registry (from `useBlok`)
+   * @param toolName - the name the tool is registered under
+   */
+  const buildPortalToolbox = (
+    registry: BlockPortalRegistry,
+    toolName: string
+  ): ToolboxConfig | undefined => {
     if (spec.toolbox === undefined) {
-      return { value: undefined, complete: status.complete };
+      return undefined;
+    }
+
+    const entries = Array.isArray(spec.toolbox) ? spec.toolbox : [spec.toolbox];
+
+    // Nothing to override unless at least one entry has a ReactElement title;
+    // the static string/`toolNames.*` path already covers the rest.
+    if (!entries.some((entry) => isValidElement(entry.title))) {
+      return undefined;
     }
 
-    const value = Array.isArray(spec.toolbox) ? spec.toolbox.map(toEntry) : toEntry(spec.toolbox);
+    return entries.map((entry, index): ToolboxConfigEntry => {
+      const { entry: core } = toCoreEntry(entry);
+
+      if (!isValidElement(entry.title)) {
+        return core;
+      }
+
+      const host = document.createElement('span');
+
+      host.setAttribute('data-blok-mutation-free', 'true');
 
-    return { value, complete: status.complete };
+      const node = entry.title;
+      const TitleComponent: ComponentType<Record<string, unknown>> = (): ReactElement => <>{node}</>;
+
+      TitleComponent.displayName = `BlokToolboxTitle(${toolName})`;
+
+      // Unique within this per-editor registry; register() is idempotent, so a
+      // StrictMode double-build replaces rather than duplicates.
+      registry.register(`__blok-toolbox-title__:${toolName}:${index}`, {
+        hostEl: host,
+        component: TitleComponent,
+        props: {},
+        toolName,
+      });
+
+      return { ...core, titleEl: host };
+    });
   };
 
   /** Lazily-computed core-compatible toolbox (React element icons serialized once). */
@@ -247,6 +350,17 @@ export function createReactBlock<Data = BlockToolData, Config = Record<string, u
       return resolveToolbox();
     }
 
+    /**
+     * Adapter-internal (see the return-type doc): builds the per-editor toolbox
+     * override whose ReactElement titles are live portals in `registry`.
+     */
+    public static __buildPortalToolbox(
+      registry: BlockPortalRegistry,
+      toolName: string
+    ): ToolboxConfig | undefined {
+      return buildPortalToolbox(registry, toolName);
+    }
+
     /**
      * React blocks support read-only mode: `setReadOnly` pushes a new prop the
      * component reads, so the block re-renders read-only IN PLACE. Without this

package/src/createReactInlineTool.tsx

@@ -158,9 +158,11 @@ export function createReactInlineTool<Config = Record<string, unknown>, State =
 ): (new (options: InlineToolConstructorOptions) => InlineTool) & {
   readonly __isBlokReactInlineTool: true;
   readonly isInline: true;
+  readonly type: string;
   readonly title: string | undefined;
-  readonly titleKey: string | undefined;
+  readonly titleKey: string;
   readonly shortcut: string | undefined;
+  readonly mark: MarkSpec<State> | undefined;
   readonly sanitize: SanitizerConfig | undefined;
   readonly isReadOnlySupported: boolean;
 } {
@@ -169,18 +171,39 @@ export function createReactInlineTool<Config = Record<string, unknown>, State =
     public static readonly __isBlokReactInlineTool = true as const;
     public static readonly isInline = true as const;
 
+    /** The tool's type name — also the default translation key and mark tag context. */
+    public static get type(): string {
+      return spec.type;
+    }
+
     public static get title(): string | undefined {
       return spec.title;
     }
 
-    public static get titleKey(): string | undefined {
-      return spec.titleKey;
+    /**
+     * Translation key core i18n resolves as `toolNames.{titleKey}`. Defaults to
+     * the tool `type` so a custom mark localizes through the conventional
+     * `toolNames.{type}` key (as built-in tools do) instead of silently falling
+     * to the un-translated capitalized tool name. When the consumer supplies no
+     * matching i18n entry, core still falls through to that same label — the
+     * default is a no-op there and never a regression.
+     */
+    public static get titleKey(): string {
+      return spec.titleKey ?? spec.type;
     }
 
     public static get shortcut(): string | undefined {
       return spec.shortcut;
     }
 
+    /**
+     * The declared mark spec (if any). Exposed as a static so consumers can
+     * assert a tool's mark in unit tests without mocking the factory.
+     */
+    public static get mark(): MarkSpec<State> | undefined {
+      return spec.mark;
+    }
+
     public static get sanitize(): SanitizerConfig | undefined {
       if (spec.sanitize !== undefined) {
         return spec.sanitize;

package/src/index.ts

@@ -1,6 +1,12 @@
 export { useBlok } from './useBlok';
+// Host-i18n bridge (#41): re-export the direction/normalization helpers so a
+// host that owns its locale state can compute `dir` and validate tags without
+// deep-importing core. `<BlokEditor locale>` pairs with these.
+export { getDirection, normalizeLocale } from '@bloklabs/core/locales';
 export { BlokContent } from './BlokContent';
 export { BlokEditor } from './BlokEditor';
+export { useBlokHandle } from './useBlokHandle';
+export type { BlokEditorHandle } from './useBlokHandle';
 export { BlokProvider, useBlokDefaults } from './provide-blok';
 export type { UseBlokConfig, BlokContentProps } from './types';
 export type { BlokEditorProps } from './BlokEditor';

package/src/useBlok.ts

@@ -11,7 +11,7 @@ import {
 } from './block-portal-registry';
 import { setRegistry, removeRegistry } from './registry-map';
 import { bindLiveToolConfigFunctions, buildLiveBlockConfig } from './live-tool-config';
-import { createEmittedEchoWindow, normalizeReadOnlyConfig } from '@bloklabs/core/adapters';
+import { createEmittedEchoWindow, normalizeReadOnlyConfig, toRenderableData } from '@bloklabs/core/adapters';
 import type { Blok } from '@/types';
 import type { UseBlokConfig } from './types';
 
@@ -74,6 +74,24 @@ const injectPortalRegistry = (tools: unknown, registry: BlockPortalRegistry): un
       [BLOK_PORTAL_REGISTRY_CONFIG_KEY]: registry,
       [BLOK_TOOL_NAME_CONFIG_KEY]: name,
     };
+
+    // A React block tool whose toolbox title is a ReactElement needs a live
+    // portal that only the editor's registry can host. Build a per-editor
+    // toolbox override (element-title hosts registered now) and let core's
+    // per-tool `toolbox` setting carry it. Undefined = no ReactElement titles,
+    // so the static string/`toolNames.*` path is left untouched.
+    const buildPortalToolbox = (base.class as {
+      __buildPortalToolbox?: (r: BlockPortalRegistry, n: string) => unknown;
+    }).__buildPortalToolbox;
+
+    const portalToolbox = typeof buildPortalToolbox === 'function' && base.toolbox === undefined
+      ? buildPortalToolbox(registry, name)
+      : undefined;
+
+    if (portalToolbox !== undefined) {
+      base.toolbox = portalToolbox;
+    }
+
     result[name] = base;
   }
 
@@ -256,6 +274,16 @@ export function useBlok(configInput: UseBlokConfig, deps?: DependencyList): Blok
         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.
@@ -639,7 +667,9 @@ export function useBlok(configInput: UseBlokConfig, deps?: DependencyList): Blok
     pendingDataRef.current = data;
     renderChainRef.current = renderChainRef.current
       .catch(() => undefined)
-      .then(() => editor.render(data))
+      // `data` may be null here (a controlled "clear to empty"); render() throws
+      // on null, so normalize null → { blocks: [] } at the boundary.
+      .then(() => editor.render(toRenderableData(data)))
       .then(
         () => {
           lastRenderedDataRef.current = data;

package/src/useBlokHandle.ts

@@ -0,0 +1,101 @@
+import { useRef, useMemo, type RefCallback } from 'react';
+import type { Blok, OutputData, LooseOutputData } from '@/types';
+
+/**
+ * A typed, null-safe imperative handle for a Blok editor embedded via
+ * `<BlokEditor>`. Solves the "raw ref is `Blok | null` until ready" papercut:
+ * instead of every consumer re-declaring a `forwardRef`/`useImperativeHandle`
+ * with `?.` guards, `useBlokHandle()` returns this stable object whose methods
+ * safely no-op until the editor is ready.
+ *
+ * Attach it via `ref`: `<BlokEditor ref={handle.ref} … />`. The methods read the
+ * live instance through an internal ref, so they can be called from event
+ * handlers without re-subscribing, and they stay valid across re-renders.
+ *
+ * `current` / `isReady` are IMPERATIVE reads (they reflect the instance at call
+ * time and do NOT trigger a re-render when readiness flips). For render-reactive
+ * readiness use `useBlokReady`; drop to `current` when you need the full editor
+ * API beyond the handful of shortcuts below.
+ */
+export interface BlokEditorHandle {
+  /**
+   * Ref callback to attach to `<BlokEditor ref={handle.ref} />`. Stable across
+   * renders. Stores the live instance (or null before ready / after unmount).
+   */
+  readonly ref: RefCallback<Blok | null>;
+  /** The live editor instance, or null before ready / after unmount. */
+  readonly current: Blok | null;
+  /** True once the editor is ready (the ref has been populated). */
+  readonly isReady: boolean;
+  /**
+   * Focus the editor. Returns whether focus landed; `false` (no-op) before ready.
+   * @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(): 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.
+   * @param data - the document to render
+   */
+  render(data: OutputData | LooseOutputData): Promise<void>;
+  /**
+   * Set or toggle read-only mode. Resolves to the resulting state; `false`
+   * (no-op) before ready.
+   * @param state - explicit state; omit to toggle
+   */
+  setReadOnly(state?: boolean): Promise<boolean>;
+}
+
+/**
+ * Returns a stable, null-safe {@link BlokEditorHandle} for a `<BlokEditor>`.
+ *
+ * @example
+ * ```tsx
+ * const blok = useBlokHandle();
+ * return (
+ *   <>
+ *     <BlokEditor ref={blok.ref} tools={tools} data={data} />
+ *     <button onClick={() => blok.focus()}>Focus</button>
+ *     <button onClick={() => blok.save().then(onSubmit)}>Send</button>
+ *   </>
+ * );
+ * ```
+ */
+export function useBlokHandle(): BlokEditorHandle {
+  const instanceRef = useRef<Blok | null>(null);
+
+  // Built once and kept stable: every method reads the live instance through
+  // `instanceRef`, so the handle identity (and its ref callback) never changes
+  // across renders even as the underlying editor is created or destroyed.
+  return useMemo<BlokEditorHandle>(() => ({
+    ref: (node): void => {
+      instanceRef.current = node;
+    },
+    get current(): Blok | null {
+      return instanceRef.current;
+    },
+    get isReady(): boolean {
+      return instanceRef.current !== null;
+    },
+    focus: (atEnd?: boolean): boolean => instanceRef.current?.focus(atEnd) ?? false,
+    clear: (): Promise<void> => instanceRef.current?.clear() ?? Promise.resolve(),
+    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(),
+    setReadOnly: (state?: boolean): Promise<boolean> => {
+      const instance = instanceRef.current;
+
+      if (instance === null) {
+        return Promise.resolve(false);
+      }
+
+      // Resolve the toggle here (omitted `state` flips current) so we can use the
+      // non-deprecated `set()`, which requires an explicit target state.
+      return instance.readOnly.set(state ?? !instance.readOnly.isEnabled);
+    },
+  }), []);
+}