@bloklabs/angular 1.1.1

package/fesm2022/bloklabs-angular.mjs

@@ -0,0 +1,2735 @@
+import * as i0 from '@angular/core';
+import { InjectionToken, makeEnvironmentProviders, Injector, createComponent, inject, ElementRef, NgZone, PLATFORM_ID, EnvironmentInjector, ApplicationRef, ErrorHandler, EventEmitter, signal, afterNextRender, Output, Input, Directive, computed, effect, forwardRef, ViewChild, ChangeDetectionStrategy, Component, DestroyRef } from '@angular/core';
+import { NG_VALUE_ACCESSOR } from '@angular/forms';
+import { isPlatformBrowser } from '@angular/common';
+import { Blok } from '@bloklabs/core';
+
+/**
+ * DI token holding app-wide Blok defaults (shared tools registry, default theme,
+ * i18n). Merged under per-instance inputs by `BlokEditorComponent`.
+ */
+const BLOK_DEFAULT_CONFIG = new InjectionToken('BLOK_DEFAULT_CONFIG');
+/**
+ * Standalone provider registering app-wide Blok defaults.
+ *
+ * @example
+ * ```ts
+ * bootstrapApplication(AppComponent, {
+ *   providers: [provideBlok({ theme: 'dark', tools: sharedTools })],
+ * });
+ * ```
+ */
+function provideBlok(defaults) {
+    return makeEnvironmentProviders([{ provide: BLOK_DEFAULT_CONFIG, useValue: defaults }]);
+}
+
+// packages/angular/src/block-context.ts
+/** DI token carrying the per-block render context into the authored component. */
+const BLOK_BLOCK_CONTEXT = new InjectionToken('BLOK_BLOCK_CONTEXT');
+
+// packages/angular/src/block-portal-registry.ts
+/**
+ * Tool-config key carrying the editor's portal registry into a
+ * `createAngularBlock` tool. The tool is constructed by CORE (outside any Angular
+ * injection context), so it cannot `inject()` — the directive injects the
+ * editor-scoped registry through each Angular-block tool's `config`, and the tool
+ * reads it back from there.
+ */
+const BLOK_PORTAL_REGISTRY_CONFIG_KEY = '__blokAngularPortalRegistry';
+/**
+ * Create a fresh portal registry bound to a live Angular environment. One per
+ * editor instance (associated via the registry map). The injectors/appRef are
+ * passed in (captured by the directive in an injection context) because the
+ * registry itself is built outside one.
+ */
+const createBlockPortalRegistry = (envInjector, appRef, errorHandler) => {
+    const mounted = new Map();
+    // Change detection runs outside NgZone here; a throwing author component must
+    // degrade to a blank holder, not break core's block insertion.
+    const safe = (fn) => {
+        try {
+            fn();
+        }
+        catch (error) {
+            errorHandler.handleError(error);
+        }
+    };
+    const teardown = (id) => {
+        const entry = mounted.get(id);
+        if (entry === undefined) {
+            return;
+        }
+        const { ref, injector } = entry;
+        // Capture host before deletion so we can clear it below.
+        const hostEl = ref.location.nativeElement;
+        mounted.delete(id);
+        appRef.detachView(ref.hostView);
+        ref.destroy();
+        // `Injector.create({ parent })` returns an injector that is NOT torn down by
+        // `ref.destroy()`. We must destroy it explicitly to prevent one small injector
+        // accumulating per block over a long editor session.
+        const destroyable = injector;
+        destroyable.destroy?.();
+        // createComponent({ hostElement }) renders INTO an external div. Angular's
+        // destroy() tears down the component instance and CD but does NOT clear the
+        // host's DOM children — we must do it explicitly.
+        hostEl.replaceChildren();
+    };
+    return {
+        register(id, entry) {
+            // Idempotent: replace any prior mount for this id.
+            teardown(id);
+            // The context is provided through an ELEMENT injector (a node injector),
+            // so it is destroyed automatically with the component view — no leaked
+            // EnvironmentInjector. The shared app envInjector is the parent, so author
+            // blocks still see app-level providers (HttpClient, etc.).
+            const elementInjector = Injector.create({
+                providers: [{ provide: BLOK_BLOCK_CONTEXT, useValue: entry.context }],
+                parent: envInjector,
+            });
+            safe(() => {
+                const ref = createComponent(entry.component, {
+                    environmentInjector: envInjector,
+                    elementInjector,
+                    hostElement: entry.hostEl,
+                });
+                appRef.attachView(ref.hostView);
+                mounted.set(id, { ref, injector: elementInjector });
+                // createComponent does not auto-run CD; render synchronously into the
+                // (still-detached) host before core inserts it into the document.
+                ref.changeDetectorRef.detectChanges();
+            });
+        },
+        unregister(id) {
+            teardown(id);
+        },
+        flush(id) {
+            const entry = mounted.get(id);
+            if (entry === undefined) {
+                return;
+            }
+            safe(() => entry.ref.changeDetectorRef.detectChanges());
+        },
+        destroyAll() {
+            for (const id of Array.from(mounted.keys())) {
+                teardown(id);
+            }
+        },
+    };
+};
+
+/**
+ * Associates each live Blok instance with its portal registry. `BlokContentDirective`
+ * sets it at creation so consumers (and future composables) can reach an editor's
+ * registry. WeakMap → no leak when the editor is destroyed.
+ */
+const registries = new WeakMap();
+function setRegistry(editor, registry) {
+    registries.set(editor, registry);
+}
+function getRegistry(editor) {
+    return registries.get(editor);
+}
+function removeRegistry(editor) {
+    registries.delete(editor);
+}
+
+/**
+ * Escape-hatch directive and lifecycle engine for Blok (mirrors React's
+ * `useBlok` + `BlokContent`). Constructs a Blok instance into its own host
+ * element and tears it down on destroy.
+ *
+ * The editor renders directly into the directive's host element — so the host
+ * IS the holder. This sidesteps the fact that Blok core exposes no public
+ * `holder` accessor: the adapter never has to read it back, it owns it.
+ *
+ * `BlokEditorComponent` applies this directive to its internal `<div>` and reads
+ * the instance back; consumers can also use it directly for full control:
+ * `<div blokContent [config]="cfg" (ready)="onReady($event)"></div>`.
+ *
+ * Implementation note: classic `@Input()`/`@Output()` are used (not signal
+ * `input()`/`output()`) because the repo's Vitest+Analog harness compiles the
+ * adapter via JIT, which does not register signal-based members. `instance`
+ * remains a plain `signal` (runtime API, JIT-safe) for reactive consumption.
+ */
+class BlokContentDirective {
+    host = inject(ElementRef);
+    ngZone = inject(NgZone);
+    isBrowser = isPlatformBrowser(inject(PLATFORM_ID));
+    /**
+     * App-wide defaults from `provideBlok()`, merged UNDER the bound `[config]` so
+     * the escape-hatch path honors them just like `<blok-editor>` (which also
+     * merges, idempotently). Mirrors React's `useBlok` merging context defaults.
+     */
+    defaults = inject(BLOK_DEFAULT_CONFIG, { optional: true }) ?? {};
+    // Captured in the injection context (field initializers) so the registry can
+    // mount author components via createComponent — core constructs tools outside
+    // Angular DI and cannot inject these itself.
+    envInjector = inject(EnvironmentInjector);
+    appRef = inject(ApplicationRef);
+    errorHandler = inject(ErrorHandler);
+    /** Construction-time Blok config (everything except `holder`, which the directive owns). */
+    config = {};
+    /** Changing this input's identity (after the first build) destroys + recreates the editor. */
+    set recreateKey(value) {
+        const changed = this.built && value !== this.currentKey;
+        this.currentKey = value;
+        if (changed) {
+            this.current?.destroy();
+            this.build();
+        }
+    }
+    /** Emits the live Blok instance once it is ready, after `instance` is populated. */
+    ready = new EventEmitter();
+    /** The live Blok instance, or null before `isReady` resolves / after destroy. */
+    instance = signal(null, ...(ngDevMode ? [{ debugName: "instance" }] : []));
+    /** The editor created by the most recent construction; used as the staleness key. */
+    current = null;
+    destroyed = false;
+    built = false;
+    currentKey;
+    /** The portal registry for the current editor (Angular-block mounting). */
+    registry;
+    constructor() {
+        // afterNextRender is browser-only (skipped during SSR) and runs after the
+        // host element exists and inputs are bound.
+        afterNextRender(() => {
+            // afterNextRender is browser-only by contract, but guard explicitly so the
+            // editor is never constructed during SSR / on a non-browser platform.
+            if (this.destroyed || !this.isBrowser) {
+                return;
+            }
+            this.build();
+            this.built = true;
+        });
+    }
+    /** Construct a Blok into the host element and publish it once ready. */
+    build() {
+        this.destroyed = false;
+        this.instance.set(null);
+        // Tear down any registry from a superseded editor (recreate path) before
+        // building a new one.
+        this.registry?.destroyAll();
+        // Merge provideBlok defaults under the bound config (instance wins; tools
+        // registries compose across both layers rather than replacing).
+        const merged = { ...this.defaults, ...this.config };
+        if (this.defaults.tools !== undefined || this.config.tools !== undefined) {
+            merged.tools = { ...this.defaults.tools, ...this.config.tools };
+        }
+        // Create the editor-scoped portal registry and thread it into every
+        // Angular-block tool's config (vanilla tools pass through untouched).
+        const registry = createBlockPortalRegistry(this.envInjector, this.appRef, this.errorHandler);
+        this.registry = registry;
+        merged.tools = injectPortalRegistry(merged.tools, registry);
+        // Construct outside Angular's zone so the editor's internal DOM churn never
+        // schedules change detection.
+        const blok = this.ngZone.runOutsideAngular(() => new Blok({
+            ...merged,
+            holder: this.host.nativeElement,
+        }));
+        this.current = blok;
+        setRegistry(blok, registry);
+        void blok.isReady.then(() => this.ngZone.run(() => {
+            // Guard on the constructor-returned reference (not isReady's resolved
+            // value): a superseded or torn-down editor must not publish itself.
+            if (this.current !== blok || this.destroyed) {
+                return;
+            }
+            this.instance.set(blok); // assign FIRST…
+            this.ready.emit(blok); // …THEN emit, so consumers see a populated instance.
+        }));
+    }
+    ngOnDestroy() {
+        this.destroyed = true;
+        this.registry?.destroyAll();
+        if (this.current !== null) {
+            removeRegistry(this.current);
+        }
+        this.current?.destroy();
+        this.current = null;
+        this.registry = undefined;
+        this.instance.set(null);
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.25", ngImport: i0, type: BlokContentDirective, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "20.3.25", type: BlokContentDirective, isStandalone: true, selector: "[blokContent]", inputs: { config: "config", recreateKey: "recreateKey" }, outputs: { ready: "ready" }, ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.25", ngImport: i0, type: BlokContentDirective, decorators: [{
+            type: Directive,
+            args: [{
+                    selector: '[blokContent]',
+                    standalone: true,
+                }]
+        }], ctorParameters: () => [], propDecorators: { config: [{
+                type: Input
+            }], recreateKey: [{
+                type: Input
+            }], ready: [{
+                type: Output
+            }] } });
+/**
+ * Return a NEW tools map (never mutate the consumer's config) where each
+ * Angular-block tool carries the portal registry under
+ * BLOK_PORTAL_REGISTRY_CONFIG_KEY in its `config`. Vanilla tools are returned
+ * unchanged. Handles both entry shapes: a bare constructor and `{ class, config }`.
+ */
+function injectPortalRegistry(tools, registry) {
+    if (tools === undefined) {
+        return tools;
+    }
+    const result = {};
+    for (const [name, entry] of Object.entries(tools)) {
+        const asObject = entry;
+        const toolClass = (typeof entry === 'function' ? entry : asObject?.class);
+        if (toolClass?.__isBlokAngularBlock === true) {
+            const base = typeof entry === 'function' ? { class: entry } : { ...asObject };
+            result[name] = {
+                ...base,
+                config: { ...(base.config ?? {}), [BLOK_PORTAL_REGISTRY_CONFIG_KEY]: registry },
+            };
+        }
+        else {
+            result[name] = entry;
+        }
+    }
+    return result;
+}
+
+/**
+ * Thrown when a block tool cannot be resolved during a creation/conversion
+ * operation (insert, insertMany/composeBlock, composeBlockData, convert).
+ *
+ * A typed error lets adapters (React/Vue/Angular useBlocks) distinguish a
+ * genuinely-unknown tool — an EXPECTED, recoverable outcome they surface as a
+ * `null`/`[]` no-op — from a real bug, WITHOUT brittle `message.includes('not
+ * found')` substring matching (which both mis-catches unrelated errors whose
+ * message happens to contain "not found" and breaks under message localization).
+ */
+class ToolNotFoundError extends Error {
+    toolName;
+    /**
+     * @param toolName - the tool type that could not be resolved
+     * @param message - optional override; defaults to a descriptive message
+     */
+    constructor(toolName, message) {
+        super(message ?? `Block Tool «${toolName}» not found.`);
+        this.toolName = toolName;
+        this.name = 'ToolNotFoundError';
+    }
+}
+
+/**
+ * ID generation utilities
+ */
+// nanoid replaced with inline crypto implementation for the Angular adapter bundle.
+const _ID_CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-';
+const _nanoid = (n) => {
+    const buf = crypto.getRandomValues(new Uint8Array(n));
+    return Array.from(buf, (b) => _ID_CHARS[b % 64]).join('');
+};
+const nanoid = _nanoid;
+/**
+ * Constants for ID generation
+ */
+const ID_RANDOM_MULTIPLIER = 100_000_000; // 1e8
+const HEXADECIMAL_RADIX = 16;
+/**
+ * Create a block id
+ * @returns unique block ID
+ */
+const generateBlockId = () => {
+    const idLen = 10;
+    return nanoid(idLen);
+};
+/**
+ * Nanoid-compatible block ID pattern: exactly 10 URL-safe characters (A-Z, a-z, 0-9, _, -)
+ */
+const BLOCK_ID_PATTERN = /^[A-Za-z0-9_-]{10}$/;
+/**
+ * Returns true if the given string is a valid block ID (nanoid format).
+ * @param id - string to check
+ */
+const isValidBlockId = (id) => BLOCK_ID_PATTERN.test(id);
+/**
+ * Returns random generated identifier
+ * @param prefix - identifier prefix
+ * @returns unique identifier with prefix
+ */
+const generateId = (prefix = '') => {
+    return `${prefix}${(Math.floor(Math.random() * ID_RANDOM_MULTIPLIER)).toString(HEXADECIMAL_RADIX)}`;
+};
+
+/**
+ * Enumerate the editor's blocks once into BlockNode records, in flat order,
+ * deriving each node's contentIds from the children that name it as parent.
+ */
+const snapshotNodes = (reader) => {
+    const count = reader.getBlocksCount();
+    const flat = Array.from({ length: count }, (_, i) => reader.getBlockByIndex(i))
+        .filter((b) => b !== undefined)
+        .map((b) => ({ id: b.id, type: b.name, parentId: b.parentId }));
+    const childrenByParent = new Map();
+    for (const b of flat) {
+        if (b.parentId === null) {
+            continue;
+        }
+        const bucket = childrenByParent.get(b.parentId) ?? [];
+        bucket.push(b.id);
+        childrenByParent.set(b.parentId, bucket);
+    }
+    return flat.map((b) => ({
+        id: b.id,
+        type: b.type,
+        parentId: b.parentId,
+        contentIds: childrenByParent.get(b.id) ?? [],
+    }));
+};
+/** Flat indices of a parent's direct children, ascending. Empty if none. */
+const childFlatIndices = (reader, parentId) => {
+    const count = reader.getBlocksCount();
+    return Array.from({ length: count }, (_, i) => i).filter((i) => reader.getBlockByIndex(i)?.parentId === parentId);
+};
+/** Map of block id -> parentId, in flat order. */
+const parentMap = (reader) => {
+    const count = reader.getBlocksCount();
+    const entries = Array.from({ length: count }, (_, i) => reader.getBlockByIndex(i))
+        .filter((b) => b !== undefined)
+        .map((b) => [b.id, b.parentId]);
+    return new Map(entries);
+};
+/** True if `id` descends from `ancestorId` via the parentId chain. */
+const isDescendantOf = (parentOf, id, ancestorId) => {
+    const parent = parentOf.get(id) ?? null;
+    if (parent === null) {
+        return false;
+    }
+    return parent === ancestorId || isDescendantOf(parentOf, parent, ancestorId);
+};
+/**
+ * The flat index of the last block in the contiguous subtree rooted at `index`.
+ * In flat (DFS) order a block's descendants sit immediately after it, so this
+ * walks forward while blocks remain descendants of the block at `index`.
+ * Returns `index` itself when the block has no descendants.
+ */
+const subtreeEndIndex = (reader, index) => {
+    const root = reader.getBlockByIndex(index);
+    if (root === undefined) {
+        return index;
+    }
+    const parentOf = parentMap(reader);
+    const count = reader.getBlocksCount();
+    // Walk forward from index+1 while blocks remain descendants (DFS contiguity).
+    // The subtree ends just before the first non-descendant, or at the last block
+    // when every follower is a descendant.
+    const followers = Array.from({ length: count - (index + 1) }, (_, k) => index + 1 + k);
+    const breakAt = followers.find((i) => {
+        const b = reader.getBlockByIndex(i);
+        return b === undefined || !isDescendantOf(parentOf, b.id, root.id);
+    });
+    return breakAt === undefined ? count - 1 : breakAt - 1;
+};
+/**
+ * The flat index at which a new block should be inserted.
+ *
+ * `replace` flips the meaning of a before/after `position`: under replace the
+ * ref IS the block being overwritten (a "turn into"), not a sibling anchor, so
+ * it resolves to the ref's OWN flat slot regardless of which parent it lives in
+ * — bypassing the sibling-relative parent guard that would otherwise redirect a
+ * nested target to the requested parent's end and replace the wrong block.
+ */
+const resolveInsertIndex = (reader, parentId, position, replace = false) => {
+    if (typeof position === 'object') {
+        const ref = 'before' in position ? position.before : position.after;
+        const refIndex = reader.getBlockIndex(ref);
+        if (replace && refIndex !== undefined) {
+            return refIndex;
+        }
+        const refParent = refIndex === undefined ? undefined : reader.getBlockByIndex(refIndex)?.parentId ?? null;
+        // before/after is sibling-relative: the ref must be a child of the requested
+        // parent. When the ref is missing or lives in a DIFFERENT parent, the
+        // parentId constraint wins — fall back to appending at the end of the
+        // requested parent rather than splicing into an unrelated subtree (the
+        // cross-parent mis-place) or silently landing at the document end.
+        if (refIndex === undefined || refParent !== parentId) {
+            return resolveInsertIndex(reader, parentId, 'end');
+        }
+        // 'after' must clear the ref's entire subtree, not just the ref node, or the
+        // new block splits the ref's descendants in flat (DFS) order.
+        return 'before' in position ? refIndex : subtreeEndIndex(reader, refIndex) + 1;
+    }
+    if (parentId === null) {
+        return position === 'start' ? 0 : reader.getBlocksCount();
+    }
+    const parentIndex = reader.getBlockIndex(parentId);
+    if (parentIndex === undefined) {
+        return reader.getBlocksCount();
+    }
+    if (position === 'start') {
+        const childIndices = childFlatIndices(reader, parentId);
+        return childIndices.length === 0 ? parentIndex + 1 : childIndices[0];
+    }
+    // 'end': insert after the parent's last descendant.
+    return subtreeEndIndex(reader, parentIndex) + 1;
+};
+/** The flat toIndex for editor.blocks.move. */
+const resolveMoveIndex = (reader, target) => {
+    if ('toIndex' in target) {
+        // Blok's Blocks.move() silently no-ops on an out-of-range index, so clamp
+        // an explicit toIndex into [0, count-1] rather than dropping the move.
+        const lastIndex = Math.max(0, reader.getBlocksCount() - 1);
+        return Math.min(Math.max(target.toIndex, 0), lastIndex);
+    }
+    const ref = 'before' in target ? target.before : target.after;
+    const refIndex = reader.getBlockIndex(ref);
+    if (refIndex === undefined) {
+        return reader.getBlocksCount();
+    }
+    // 'after' must clear the ref's entire subtree (see resolveInsertIndex), or the
+    // moved block lands among the ref's descendants instead of past them.
+    return 'before' in target ? refIndex : subtreeEndIndex(reader, refIndex) + 1;
+};
+
+// src/components/utils/blocks-api.ts
+/** Adapt the live editor to the IndexReader the snapshot helpers expect. */
+const readerFor = (editor) => {
+    const blocks = editor.blocks;
+    return {
+        getBlocksCount: () => blocks.getBlocksCount(),
+        getBlockByIndex: (i) => {
+            const b = blocks.getBlockByIndex(i);
+            return b === undefined ? undefined : { id: b.id, name: b.name, parentId: b.parentId };
+        },
+        getBlockIndex: (id) => blocks.getBlockIndex(id),
+    };
+};
+/**
+ * Stable API returned while the editor is null (before the adapter resolves).
+ * Every read returns empty/null and every MUTATOR is a no-op — EXCEPT
+ * `transact`/`transactWithoutCapture`, which still invoke their callback so a
+ * consumer wrapping conditional work in `transact` still runs that work even
+ * pre-ready.
+ */
+const EMPTY_API = {
+    getById: () => null,
+    getChildren: () => [],
+    insert: () => null,
+    insertMany: () => [],
+    insertTree: () => null,
+    insertMarkdown: async () => [],
+    exportMarkdown: async () => '',
+    move: () => undefined,
+    nest: () => undefined,
+    unnest: () => undefined,
+    remove: () => undefined,
+    update: () => undefined,
+    convert: () => undefined,
+    // Not a no-op: still runs the callback (see EMPTY_API doc above).
+    transact: (fn) => fn(),
+    // Like transact, still runs the callback even pre-ready.
+    transactWithoutCapture: (fn) => fn(),
+    getBlocksCount: () => 0,
+    getCurrentBlockIndex: () => -1,
+    getBlockByIndex: () => null,
+    getBlockByElement: () => null,
+    getBlockData: () => null,
+    getBlockIndex: () => null,
+    composeBlockData: async () => ({}),
+    renderFromHTML: async () => undefined,
+    insertOutputData: () => [],
+    splitBlock: () => null,
+    insertInsideParent: () => null,
+    render: async () => undefined,
+    clear: async () => undefined,
+    isSyncingFromYjs: () => false,
+};
+/**
+ * Build the framework-agnostic, id/parentId-relative block-tree API over a LIVE
+ * editor. Mutators route through the editor-level `blocks` API (core's
+ * chokepoints), so undo/redo and Yjs sync are inherited rather than
+ * re-implemented; readers enumerate the live tree on every call.
+ *
+ * This is the shared engine behind both the React (`useSyncExternalStore`) and
+ * Vue (`shallowRef` version) `useBlocks` wrappers — one implementation so the
+ * two adapters cannot drift. Each adapter supplies the `onRead` seam:
+ *
+ * - React leaves it the default no-op: `useSyncExternalStore` re-renders the
+ *   whole component on `block changed`, and the reads run live during that
+ *   render, so no per-call dependency tracking is needed.
+ * - Vue passes `() => { void version.value }` so a read inside a `computed` /
+ *   template touches the reactive version ref and re-runs on every structural
+ *   mutation.
+ *
+ * `onRead` is invoked at the top of every read method; mutators never call it.
+ * The editor MUST be the raw (non-proxied) instance — adapters `toRaw`-unwrap
+ * before calling, so a Vue reactive proxy never reaches core (Risk R0).
+ *
+ * @param editor - the live Blok instance (never null; callers gate on EMPTY_API)
+ * @param onRead - reactivity seam called at the start of each read (default no-op)
+ */
+const createBlocksApiForEditor = (editor, onRead = () => undefined) => {
+    const reader = readerFor(editor);
+    const getById = (id) => {
+        onRead();
+        const nodes = snapshotNodes(reader);
+        return nodes.find((n) => n.id === id) ?? null;
+    };
+    const getChildren = (parentId) => {
+        onRead();
+        return snapshotNodes(reader).filter((n) => n.parentId === parentId);
+    };
+    const transact = (fn) => {
+        if (editor.blocks.transact !== undefined) {
+            editor.blocks.transact(fn);
+        }
+        else {
+            fn();
+        }
+    };
+    /** Flat list of id + all transitive descendants, via the parentId graph. */
+    const collectSubtreeIds = (rootId) => {
+        const nodes = snapshotNodes(reader);
+        const childrenOf = new Map();
+        for (const n of nodes) {
+            if (n.parentId === null) {
+                continue;
+            }
+            const bucket = childrenOf.get(n.parentId) ?? [];
+            bucket.push(n.id);
+            childrenOf.set(n.parentId, bucket);
+        }
+        const out = [];
+        const visited = new Set();
+        const stack = [rootId];
+        // A parentId cycle (possible from a concurrent remote Yjs reparent) would
+        // make this DFS spin forever — track visited ids and skip re-entry so each
+        // block is emitted at most once and the traversal always terminates.
+        while (stack.length > 0) {
+            const id = stack.pop();
+            if (visited.has(id)) {
+                continue;
+            }
+            visited.add(id);
+            out.push(id);
+            const kids = childrenOf.get(id);
+            if (kids !== undefined) {
+                stack.push(...kids);
+            }
+        }
+        return out;
+    };
+    /** Each subtree member's parentId, captured from the current snapshot. */
+    const captureSubtreeParents = (rootId) => {
+        const parentOf = new Map(snapshotNodes(reader).map((n) => [n.id, n.parentId]));
+        return collectSubtreeIds(rootId).map((id) => ({ id, parentId: parentOf.get(id) ?? null }));
+    };
+    /**
+     * Relocate id AND its whole subtree to sit contiguously starting at a
+     * PRE-removal flat slot. Blok's Blocks.move() is post-removal index space and
+     * only carries DOM-contained descendants (resortNestedBlocks) — indent /
+     * parentId-nested children are NOT, so move each subtree member that a single
+     * root move didn't already pull into place. Keeps the flat array DFS-contiguous,
+     * the invariant the flat-index insert API and getChildren ordering depend on.
+     */
+    const relocateSubtree = (rootId, preRemovalSlot) => {
+        // Subtree members in current flat (document) order — root first.
+        const members = collectSubtreeIds(rootId)
+            .map((id) => ({ id, idx: editor.blocks.getBlockIndex(id) }))
+            .filter((m) => m.idx !== undefined)
+            .sort((a, b) => a.idx - b.idx)
+            .map((m) => m.id);
+        const rootFrom = editor.blocks.getBlockIndex(rootId);
+        if (rootFrom === undefined) {
+            return 'blocked';
+        }
+        // Self-overlap guard. `preRemovalSlot` is the destination the caller
+        // computed as the END of the (new or former) parent's WHOLE subtree — and
+        // when that parent is an ANCESTOR of the relocating block (always so for
+        // unnest, and for a nest into a block this one already sits under), that
+        // span still CONTAINS this block's own subtree. Moving the root to a slot
+        // at the tail of (or inside) its own footprint splices it in right after
+        // one of its OWN descendants; core's post-move auto-heal then reparents the
+        // block under that descendant (setBlockParent(B, B) when the neighbour is
+        // the block's last child), which BlockHierarchy REFUSES with a thrown cycle
+        // error — crashing the caller. But the block is already DFS-contiguous at
+        // that destination (its subtree is the tail of the parent's subtree), so
+        // the relocation is a no-op: skip the move and report 'skipped', leaving the
+        // caller to assert the reparent. Window: `rootFrom < preRemovalSlot <=
+        // subtreeEnd + 1`. A backward move (`preRemovalSlot <= rootFrom`) or a
+        // genuine forward move past unrelated content (`preRemovalSlot > subtreeEnd
+        // + 1`) is untouched.
+        //
+        // 'skipped' (vs 'moved') is reported DISTINCTLY because no `editor.blocks.
+        // move()` ran — so core's post-move parent auto-heal never fired. nest/unnest
+        // re-assert the root's parent explicitly (reparentSubtree), so they don't
+        // care; but move() leans on that auto-heal for the root's parent-adoption, so
+        // it must apply the adopted parent itself on this path (see move()).
+        const subtreeEnd = collectSubtreeIds(rootId)
+            .map((memberId) => editor.blocks.getBlockIndex(memberId))
+            .filter((i) => i !== undefined)
+            .reduce((max, i) => Math.max(max, i), rootFrom);
+        if (preRemovalSlot > rootFrom && preRemovalSlot <= subtreeEnd + 1) {
+            return 'skipped';
+        }
+        // Defensive clamp into [0, count-1]: Blok's move() silently no-ops on an
+        // out-of-range index, so an over-large preRemovalSlot would strand the
+        // root instead of appending it. (In practice resolveInsertIndex stays in
+        // range; this guards a concurrently-shrunk tree.)
+        const lastIndex = Math.max(0, editor.blocks.getBlocksCount() - 1);
+        const rootTarget = Math.min(Math.max(rootFrom < preRemovalSlot ? preRemovalSlot - 1 : preRemovalSlot, 0), lastIndex);
+        editor.blocks.move(rootTarget, rootFrom);
+        // Detect a BLOCKED relocation: Blok's move() clamps a cross-`column`-
+        // boundary move to a no-op. If the root could not reach its target (it
+        // didn't move and wasn't already there), the relocation failed — report
+        // it so the caller skips the reparent that would otherwise corrupt DFS
+        // contiguity (a child wedged outside its parent's flat run). A legitimate
+        // no-op (already at target, rootFrom === rootTarget) still counts as
+        // relocated so an in-place nest/unnest reparents as intended.
+        if (rootFrom !== rootTarget && editor.blocks.getBlockIndex(rootId) === rootFrom) {
+            return 'blocked';
+        }
+        // Place each descendant immediately after the previously-positioned member,
+        // re-reading the anchor's LIVE index every iteration. A cached root index
+        // (rootNew + k + 1) only holds for a BACKWARD relocation, where descendants
+        // already sit after the root. For a FORWARD relocation each descendant
+        // move() splices an element out from BEFORE the root, sliding the root (and
+        // a cached index) down one slot per step — so the target overshoots, trips
+        // Blocks.move()'s out-of-range no-op guard, and strands the descendant.
+        // Re-anchoring to the predecessor's current slot absorbs the drift in both
+        // directions and keeps the subtree DFS-contiguous. A descendant already in
+        // place (carried by resortNestedBlocks for a DOM-nested child) is skipped.
+        // The anchor for the k-th descendant is the (k-1)-th — read live each step.
+        const descendants = members.filter((memberId) => memberId !== rootId);
+        descendants.forEach((memberId, k) => {
+            const anchorId = k === 0 ? rootId : descendants[k - 1];
+            const from = editor.blocks.getBlockIndex(memberId);
+            const anchor = editor.blocks.getBlockIndex(anchorId);
+            if (from === undefined || anchor === undefined) {
+                return;
+            }
+            const target = anchor + 1;
+            if (from !== target) {
+                editor.blocks.move(from < target ? target - 1 : target, from);
+            }
+        });
+        return 'moved';
+    };
+    // Reparent `id` (root → newParentId, descendants → their original parent).
+    // Re-asserting after relocateSubtree heals move()'s auto-reparent (which sets
+    // a moved block's parentId to its new neighbour) and never relocates the flat
+    // array, so contiguity established by relocateSubtree is preserved.
+    const reparentSubtree = (members, rootId, newParentId) => {
+        for (const m of members) {
+            editor.blocks.setBlockParent(m.id, m.id === rootId ? newParentId : m.parentId);
+        }
+    };
+    // Re-assert ONLY the descendants' captured parents after a subtree relocation,
+    // leaving the ROOT's parent as core's post-move auto-heal set it — used by
+    // move(), whose documented side effect is that the root ADOPTS the parent of
+    // the slot it lands in while its subtree travels with it.
+    const reassertDescendantParents = (members, rootId) => {
+        members
+            .filter((m) => m.id !== rootId)
+            .forEach((m) => editor.blocks.setBlockParent(m.id, m.parentId));
+    };
+    /**
+     * Whether `id` is a DIRECT child of a `column` block. Column membership is
+     * owned by the drag UI, so a programmatic nest/unnest that would change it is
+     * a graceful no-op (see the nest/unnest docs). Checking this EXPLICITLY makes
+     * that contract reliable: relying on core's move-clamp alone leaks, because
+     * when the relocation needs no actual move (a tail column child already sits
+     * at its relocation target) no boundary-crossing move fires, so nothing
+     * clamps and the reparent would slip through.
+     */
+    const isColumnChild = (id) => {
+        const parent = getById(id)?.parentId ?? null;
+        return parent !== null && getById(parent)?.type === 'column';
+    };
+    /**
+     * Nest `id` (and its whole subtree) under `parentId`, as one undo step.
+     * No-op when either id is unknown (probed via the silent snapshot, NOT
+     * getBlockIndex, which warns on unknown ids), or when `parentId` is `id`
+     * itself or one of `id`'s own descendants — that would form a cycle, which
+     * core's setBlockParent THROWS on, so the hook guards it up front.
+     *
+     * Column boundary caveat: nesting a block that lives inside a `column`, or
+     * nesting directly INTO one, is a GRACEFUL no-op — column membership is owned
+     * by the drag UI. This is detected explicitly (via the block's and target's
+     * parent type), so the no-op holds even when no boundary-crossing move fires.
+     * Returns void.
+     */
+    const nest = (id, parentId) => {
+        if (getById(parentId) === null || getById(id) === null) {
+            return;
+        }
+        // Cycle guard: a block can't become a child of itself or of one of its
+        // own descendants. Without this, the relocate/reparent reaches core's
+        // setBlockParent, which throws on a cycle and crashes the caller.
+        if (parentId === id || isDescendantOf(parentMap(reader), parentId, id)) {
+            return;
+        }
+        // Column-boundary no-op: pulling a block out of a `column`, or pushing one
+        // directly into a column, changes column membership — owned by the drag UI.
+        if (isColumnChild(id) || getById(parentId)?.type === 'column') {
+            return;
+        }
+        // Relocate id's whole subtree to after the new parent's existing subtree,
+        // THEN assert the parents. Blok keeps the flat array as the canonical
+        // document order, and the flat-index insert API only resolves a parent's
+        // "end" slot when that parent's descendants are contiguous — a bare reparent
+        // (no relocation) would wedge unrelated blocks between the parent and its new
+        // child, corrupting later inserts/reads. Mirrors the drag move-then-reparent.
+        //
+        // Only reparent when the relocation actually placed the block: a clamped
+        // cross-column move leaves it where it was, and reparenting in place would
+        // break DFS contiguity.
+        const members = captureSubtreeParents(id);
+        transact(() => {
+            // reparentSubtree sets the root's parent EXPLICITLY, so nest is correct on
+            // both the 'moved' and 'skipped' paths — it only bails on a 'blocked'
+            // (clamped cross-column) relocation.
+            if (relocateSubtree(id, resolveInsertIndex(reader, parentId, 'end')) !== 'blocked') {
+                reparentSubtree(members, id, parentId);
+            }
+        });
+    };
+    /**
+     * Promote `id` (and its subtree) to root, as one undo step. No-op when the
+     * id is unknown or already at root. Same column-boundary caveat as
+     * {@link nest}: unnesting a `column` member out to root is a graceful no-op
+     * (column membership changes go through the drag UI). Returns void.
+     */
+    const unnest = (id) => {
+        const node = getById(id);
+        if (node === null) {
+            return;
+        }
+        const parentId = node.parentId;
+        if (parentId === null) {
+            return;
+        }
+        // Column-boundary no-op: a column member is detached only via the drag UI.
+        if (isColumnChild(id)) {
+            return;
+        }
+        // Move id's subtree out past its former parent's whole subtree before
+        // clearing the parent, so the promoted block doesn't strand itself between
+        // the parent and its remaining children (which would break contiguity).
+        // As with nest, only clear the parent when the relocation succeeded — a
+        // clamped cross-column move must stay a graceful no-op.
+        const members = captureSubtreeParents(id);
+        transact(() => {
+            // As with nest, reparentSubtree asserts the root's (null) parent on both
+            // 'moved' and 'skipped'; only a 'blocked' clamp keeps it a no-op.
+            if (relocateSubtree(id, resolveInsertIndex(reader, parentId, 'end')) !== 'blocked') {
+                reparentSubtree(members, id, null);
+            }
+        });
+    };
+    const remove = (id) => {
+        if (editor.blocks.getBlockIndex(id) === undefined) {
+            return;
+        }
+        // Remove the block AND its descendants. Blok's single-block delete promotes
+        // a (non-columns) container's children to root, which would orphan the
+        // nested structure the caller meant to discard. Delete deepest-first (by
+        // descending flat index) so a parent is childless by the time it's deleted
+        // (no promotion). One undo step.
+        //
+        // Re-resolve each member's index by id AT DELETE TIME rather than reusing a
+        // pre-captured snapshot: a core delete can cascade (deleting a column's last
+        // child auto-removes the empty column) or shift indices, so a stale index
+        // could target the wrong — or an already-gone — block.
+        const orderedIds = collectSubtreeIds(id)
+            .map((subId) => ({ subId, index: editor.blocks.getBlockIndex(subId) }))
+            .filter((m) => m.index !== undefined)
+            .sort((a, b) => b.index - a.index)
+            .map((m) => m.subId);
+        transact(() => {
+            for (const subId of orderedIds) {
+                const index = editor.blocks.getBlockIndex(subId);
+                // Already removed by a cascading delete of one of its descendants.
+                if (index === undefined) {
+                    continue;
+                }
+                void editor.blocks.delete(index, false);
+            }
+        });
+    };
+    /**
+     * Move `id` to a flat slot, as a single operation. No-op when `id` is
+     * unknown (probed via the silent snapshot, NOT getBlockIndex, which warns on
+     * unknown ids); when a relative `{ before|after }` target references `id`
+     * itself, one of its descendants (a block can't be a sibling of its own
+     * child), or a ref that does not exist (an unresolved relative target must
+     * not silently dump the block at the document end); or for ANY absolute
+     * `{ toIndex }` of a block that HAS descendants (a multi-block subtree can't
+     * land on one index — see the subtree note below). Guards run BEFORE the
+     * index is resolved into a final move.
+     *
+     * Parent-adoption side effect: `before`/`after` make the moved block a
+     * SIBLING of the ref — it adopts the REF's parent (moving before/after a
+     * child of a container nests it into that container; moving before/after a
+     * root block unnests it to root). `after` clears the ref's WHOLE subtree, so
+     * the block lands past the ref's descendants, not among them. The adopted
+     * parent is the ref's — NOT the parent of whatever block happens to sit at the
+     * landing slot, which would nest under the ref for `after` a ref-with-children.
+     * Use {@link nest}/{@link unnest} to change the parent without choosing a
+     * sibling slot. Returns void.
+     *
+     * Subtree-aware: a block WITH descendants relocates its WHOLE subtree as one
+     * undo step (core's single move() carries only DOM-contained descendants, so
+     * a naive move would strand indent/parentId-nested children before their
+     * parent and corrupt DFS contiguity). Only relative `{ before|after }`
+     * targets name an unambiguous slot for a multi-block subtree; an absolute
+     * `{ toIndex }` of a block that HAS descendants is ambiguous (k blocks can't
+     * all land on one index) and is a graceful no-op — use `{ before|after }` to
+     * relocate a subtree.
+     */
+    const move = (id, target) => {
+        // Silent existence probe (NOT getBlockIndex, which warns on unknown ids).
+        if (getById(id) === null) {
+            return;
+        }
+        // id is known, so getBlockIndex won't warn.
+        const fromIndex = editor.blocks.getBlockIndex(id);
+        if (fromIndex === undefined) {
+            return;
+        }
+        if (!('toIndex' in target)) {
+            const ref = 'before' in target ? target.before : target.after;
+            // A relative target can't reference the block itself or any of its own
+            // descendants — a block can't become a sibling of its child.
+            if (ref === id || isDescendantOf(parentMap(reader), ref, id)) {
+                return;
+            }
+            // An unresolved relative ref must NOT fall through to a relocate-to-end:
+            // a missing target is a no-op, not a surprise jump to the document end.
+            if (getById(ref) === null) {
+                return;
+            }
+        }
+        // NB: an absolute { toIndex } needs no early guard here. A block WITH
+        // descendants no-ops EVERY toIndex move in the subtree branch below
+        // (ambiguous for a multi-block subtree); a leaf has no own-subtree range to
+        // land inside. So a dedicated "toIndex inside own subtree" guard would be
+        // dead code — the subtree-branch no-op already covers the cycle it guarded.
+        // Subtree-aware relocation. A block WITH descendants can't ride a single
+        // core move(): core carries only DOM-contained descendants (resortNested
+        // Blocks), so indent/parentId-nested children are left at their old slot —
+        // stranded BEFORE their now-moved parent in flat order, breaking the DFS
+        // contiguity getChildren ordering and flat-index inserts depend on, and
+        // corrupting saved document order. Relocate the whole subtree (as
+        // nest/unnest do) and re-assert each descendant's own parent; the ROOT
+        // keeps the parent core's post-move auto-heal gives it — move()'s
+        // documented parent-adoption side effect — so only descendants are
+        // re-parented. A blocked relocation (a clamped cross-`column` move) leaves
+        // everything in place, a graceful no-op like nest/unnest. An absolute
+        // { toIndex } is ambiguous for a multi-block subtree (see the move() doc),
+        // so it is a graceful no-op here — relative targets relocate the subtree.
+        // A leaf block (no descendants) falls through to the single-move fast path.
+        const subtreeMembers = captureSubtreeParents(id);
+        if (subtreeMembers.length > 1) {
+            if ('toIndex' in target) {
+                return;
+            }
+            const preRemovalSlot = resolveMoveIndex(reader, target);
+            // The relative ref whose parent the moved block adopts (toIndex returned
+            // above, so target is { before | after }).
+            const ref = 'before' in target ? target.before : target.after;
+            transact(() => {
+                const outcome = relocateSubtree(id, preRemovalSlot);
+                if (outcome === 'blocked') {
+                    return;
+                }
+                reassertDescendantParents(subtreeMembers, id);
+                // Adopt the REF's parent (sibling-of-ref) on BOTH the 'moved' and
+                // 'skipped' paths. The position is already sibling-of-ref: resolveMoveIndex
+                // clears the ref's WHOLE subtree for `after` and uses the ref's own slot
+                // for `before`, so id lands as the ref's sibling. The parent must match.
+                // Core's post-move auto-heal does NOT give that — it adopts the parent of
+                // the block at the landing SLOT (pre-removal), which for `after` a
+                // ref-with-descendants is the ref's last descendant (parent = the ref →
+                // nests id UNDER the ref) and for `before` a ref whose flat predecessor
+                // sits in another container is that predecessor's parent. On the 'skipped'
+                // path no move() ran, so no auto-heal fired at all. Assert ref.parentId so
+                // position and parent agree regardless of path. Guarded (mirrors
+                // insertWithinTransaction) so a same-container reorder — the common case,
+                // where the landed parent already matches — fires no redundant reparent.
+                // Can't cycle: ref is neither id nor a descendant (guarded above), so
+                // ref's parent is outside id's subtree.
+                const intendedParent = getById(ref)?.parentId ?? null;
+                if ((getById(id)?.parentId ?? null) !== intendedParent) {
+                    editor.blocks.setBlockParent(id, intendedParent);
+                }
+            });
+            return;
+        }
+        const resolved = resolveMoveIndex(reader, target);
+        // Blok's Blocks.move() removes the block (splice fromIndex) BEFORE
+        // re-inserting at toIndex, so toIndex lives in the POST-removal index
+        // space. For a relative (before/after) forward move the reference index
+        // shifts down by one once the block is removed, so compensate — this also
+        // keeps a move-to-end within Blok's `toIndex < length` bound. A literal
+        // { toIndex } is the caller's explicit final resting index: pass through.
+        const isRelative = !('toIndex' in target);
+        const toIndex = isRelative && fromIndex < resolved ? resolved - 1 : resolved;
+        if (!isRelative) {
+            // Absolute { toIndex }: the caller chose the slot, so let core's auto-heal
+            // adopt that slot's container (the documented absolute-move semantics).
+            editor.blocks.move(toIndex, fromIndex);
+            return;
+        }
+        // Relative leaf move: same sibling-of-ref rule as the subtree branch — the
+        // moved block adopts the REF's parent, not the landing-slot neighbour's
+        // (which auto-heal would give: the ref's descendant for `after`, or a
+        // cross-container predecessor for `before`). Assert it in the same undo step
+        // as the move, guarded so a same-container reorder fires no redundant
+        // reparent. Can't cycle: ref is guarded to be neither id nor a descendant,
+        // and a leaf has no descendants for ref's parent to fall inside.
+        const ref = 'before' in target ? target.before : target.after;
+        transact(() => {
+            editor.blocks.move(toIndex, fromIndex);
+            const intendedParent = getById(ref)?.parentId ?? null;
+            if ((getById(id)?.parentId ?? null) !== intendedParent) {
+                editor.blocks.setBlockParent(id, intendedParent);
+            }
+        });
+    };
+    /**
+     * Perform one insert (create + intended-parent assertion) WITHOUT opening a
+     * transaction — the caller owns the undo grouping. `insert` wraps a single
+     * call in its own transact; `insertMany` shares ONE transact across the whole
+     * batch so the bulk insert is a single undo step. Returns the created node,
+     * or null when nothing was inserted (idempotent hit returns the existing
+     * node; a guard failure returns null).
+     */
+    const insertWithinTransaction = (spec) => {
+        const parentId = spec.parentId ?? null;
+        const position = spec.position ?? 'end';
+        const data = spec.data ?? {};
+        // Programmatic insert must not steal the caret unless explicitly asked.
+        const needToFocus = spec.focus ?? false;
+        const replace = spec.replace ?? false;
+        // Every pre-insert guard (id-exists, dangling-parent, missing-ref) and the
+        // replace-parent lookup used to call `getById`, which re-enumerates the
+        // WHOLE tree each time — O(probes·n) per spec, O(k·probes·n) per batch.
+        // The tree can't change until `editor.blocks.insert` runs below, so take
+        // ONE snapshot here and resolve every pre-insert probe against it.
+        const preById = new Map(snapshotNodes(reader).map((n) => [n.id, n]));
+        const probe = (id) => preById.get(id) ?? null;
+        // Idempotent insert-if-absent: a stable explicit id that already exists
+        // returns the existing node without inserting a duplicate, so a re-running
+        // effect is safe. Probe via the silent snapshot getById, NOT
+        // editor.blocks.getBlockIndex — the latter logs a `warn` for any unknown
+        // id, which would spam the console on this (expected-absent) happy path.
+        //
+        // Skipped under `replace`: a replace is an explicit overwrite, not an
+        // insert, so an existing id must not short-circuit it (the two would
+        // otherwise silently conflict and replace nothing).
+        if (spec.id !== undefined && !replace) {
+            const existing = probe(spec.id);
+            if (existing !== null) {
+                // Insert-if-absent hit: the block already existed, nothing was created.
+                // insert() still returns the existing node (documented), but insertMany
+                // must EXCLUDE it from its created[] result — hence created: false.
+                return { node: existing, created: false };
+            }
+        }
+        // A dangling parentId would make core throw (dev) or silently misplace the
+        // block at the document end (prod). Honor the null contract instead. Probe
+        // via the silent snapshot getById, NOT editor.blocks.getBlockIndex, which
+        // logs a `warn` for any unknown id and would spam the console on this
+        // expected-absent no-op path. Skipped under replace: a replace ignores
+        // parentId entirely (the overwritten block's own parent governs), so a
+        // stale parentId must not abort the overwrite.
+        if (!replace && parentId !== null && probe(parentId) === null) {
+            return { node: null, created: false };
+        }
+        // A replace targets the before/after ref block ITSELF (the "turn into"
+        // block being overwritten), not a sibling anchor. It therefore REQUIRES an
+        // object position naming that ref:
+        //   - with position 'start'/'end' (or omitted) there is no target ref, so
+        //     a replace has nothing to overwrite — return null rather than silently
+        //     overwriting whatever block happens to sit at the resolved slot;
+        //   - with an object position whose ref doesn't exist there is likewise
+        //     nothing to overwrite — return null instead of falling through to
+        //     resolveInsertIndex's end-slot fallback (which would insert/replace at
+        //     the wrong place and reparent a dangling target).
+        // Validation is skipped for a plain insert (above), so this is the only
+        // guard that protects the replace path.
+        if (replace) {
+            if (typeof position !== 'object') {
+                return { node: null, created: false };
+            }
+            const replaceTargetRef = 'before' in position ? position.before : position.after;
+            if (probe(replaceTargetRef) === null) {
+                return { node: null, created: false };
+            }
+        }
+        // A plain insert with an object position naming a ref that does NOT exist
+        // must be a no-op (return null), NOT a silent append at the document/parent
+        // end. resolveInsertIndex falls back to the end slot for an unresolved ref,
+        // which would dump the block somewhere surprising — a DX footgun. Mirror
+        // move(), which already bails on a missing relative ref. (Skipped under
+        // replace: the block above already validated the replace ref.)
+        if (!replace && typeof position === 'object') {
+            const positionTargetRef = 'before' in position ? position.before : position.after;
+            if (probe(positionTargetRef) === null) {
+                return { node: null, created: false };
+            }
+        }
+        const flatIndex = resolveInsertIndex(reader, parentId, position, replace);
+        // A replace is a positional type-swap that PRESERVES the replaced block's
+        // parent link, so the intended parent is the target's existing parent, not
+        // the caller's (root-defaulting) parentId. Capture it from the pre-insert
+        // snapshot so the post-insert assertion re-nests the replacement correctly
+        // instead of un-nesting it to root. A plain insert uses parentId as-is.
+        const positionRef = (() => {
+            if (typeof position !== 'object') {
+                return null;
+            }
+            return 'before' in position ? position.before : position.after;
+        })();
+        const replaceRef = replace ? positionRef : null;
+        const intendedParentId = replaceRef !== null ? probe(replaceRef)?.parentId ?? null : parentId;
+        const created = (() => {
+            try {
+                return editor.blocks.insert(spec.type, data, {}, flatIndex, needToFocus, replace, spec.id, spec.tunes);
+            }
+            catch (error) {
+                // The only EXPECTED throw here is an unknown/missing tool — core throws
+                // a typed ToolNotFoundError. (A missing replace TARGET is a bare Error,
+                // not this type, so it would re-throw — but the replace ref is already
+                // pre-validated above, so it never reaches here.) Honor the null contract
+                // for ToolNotFoundError; re-throw anything else so a genuine
+                // bug surfaces instead of being masked as a null return. Keyed on the
+                // error TYPE, not a 'not found' substring, so an unrelated error whose
+                // message happens to contain "not found" is not wrongly swallowed.
+                if (error instanceof ToolNotFoundError) {
+                    return null;
+                }
+                throw error;
+            }
+        })();
+        if (created === undefined || created === null) {
+            return { node: null, created: false };
+        }
+        // Assert the intended parent. Core derives a new block's parent from its
+        // flat predecessor, so a block appended right after a `column` child is
+        // auto-nested into that column. We know the caller's intent: for a
+        // parented insert set the parent; for a root insert (parentId === null)
+        // override back to root ONLY if core nested it, keeping the natural
+        // `insert({ position: 'end' })` a root sibling instead of a stowaway. For
+        // a replace, intendedParentId is the overwritten block's own parent, so
+        // the replacement keeps its place in the tree.
+        // ONE post-insert snapshot for both the landed-parent check and the return
+        // node (was two separate getById enumerations). A freshly-created block has
+        // no children, so reparenting it only flips its own parentId — its derived
+        // contentIds stay `[]`. We therefore reconstruct the corrected node in place
+        // rather than re-enumerating the tree a third time after setBlockParent.
+        const createdNode = snapshotNodes(reader).find((n) => n.id === created.id) ?? null;
+        const landedParentId = createdNode?.parentId ?? null;
+        const node = landedParentId === intendedParentId
+            ? createdNode
+            : (() => {
+                editor.blocks.setBlockParent(created.id, intendedParentId);
+                return createdNode === null ? null : { ...createdNode, parentId: intendedParentId };
+            })();
+        // Position the caret inside the freshly-created block when the caller asked
+        // for a specific spot (beyond the boolean `focus`). Applied only on a real
+        // creation — an insert-if-absent hit returned earlier, so it never reaches
+        // here. setToBlock takes the block id directly.
+        if (spec.caret !== undefined) {
+            editor.caret.setToBlock(created.id, spec.caret.position ?? 'default', spec.caret.offset ?? 0);
+        }
+        return { node, created: true };
+    };
+    /**
+     * Insert one block. Returns the created {@link BlockNode}, or null when the
+     * insert is rejected — an unknown tool type (core "…not found"), a dangling
+     * `parentId`, or a `replace` whose target ref doesn't exist. An explicit
+     * `id` that already exists is insert-if-absent: the existing node is returned
+     * and nothing is created (skipped under `replace`, which is an explicit
+     * overwrite). Validation runs BEFORE the slot is resolved; a `replace`
+     * preserves the overwritten block's parent. Always one atomic undo step.
+     *
+     * The returned node is a fresh-snapshot view (its `contentIds` are derived
+     * per call) — read it immediately; do NOT place it in a `useMemo`/`useEffect`
+     * dependency array expecting per-mutation identity.
+     */
+    const insert = (spec = {}) => {
+        // Mutable property on a const holder (no `let`): the node captured from
+        // inside the transact closure for the post-transact return.
+        const result = { node: null };
+        // Always atomic: a single undo step removes the new block (and, for a
+        // parented insert, its reparent) — and gives the insert its own boundary
+        // instead of merging into adjacent typing history.
+        transact(() => {
+            // insert() returns the resolved node — including an insert-if-absent hit's
+            // existing node (documented) — so it reads only `.node`, not `.created`.
+            result.node = insertWithinTransaction(spec).node;
+        });
+        return result.node;
+    };
+    const insertMany = (specs) => {
+        // An empty batch opens no transaction (no spurious undo boundary).
+        if (specs.length === 0) {
+            return [];
+        }
+        const created = [];
+        // ONE transact for the whole batch → a single atomic undo step. Each spec
+        // still runs the full single-insert path (parent assertion, positioning).
+        // Per the documented contract, the result holds ONLY successfully-created
+        // nodes: specs that fail to insert (null node) AND insert-if-absent hits
+        // (existing block, created: false) are both dropped.
+        transact(() => {
+            for (const spec of specs) {
+                const result = insertWithinTransaction(spec);
+                if (result.created && result.node !== null) {
+                    created.push(result.node);
+                }
+            }
+        });
+        return created;
+    };
+    /**
+     * Insert a pre-built nested subtree as ONE atomic operation. See the
+     * {@link UseBlocksApi.insertTree} contract. Flattens the spec to a DFS
+     * pre-order `OutputBlockData[]` — wiring every node's `parent`/`content`
+     * links from ids generated up front — then delegates to core's tree-aware
+     * `blocks.insertMany` inside a single transact.
+     */
+    const insertTree = (spec) => {
+        const parentId = spec.parentId ?? null;
+        const position = spec.position ?? 'end';
+        // Dangling root parentId: mirror `insert`'s guard via the silent snapshot
+        // getById (NOT getBlockIndex, which warns on unknown ids). Reject so the
+        // subtree isn't silently dumped at the document end.
+        if (parentId !== null && getById(parentId) === null) {
+            return null;
+        }
+        // Dangling relative position ref: an object { before|after } naming a block
+        // that does not exist must be a no-op, NOT a silent append at the document
+        // end (resolveInsertIndex's unresolved-ref fallback). Mirror insert()'s
+        // missing-ref guard and reject before flattening anything.
+        if (typeof position === 'object') {
+            const positionTargetRef = 'before' in position ? position.before : position.after;
+            if (getById(positionTargetRef) === null) {
+                return null;
+            }
+        }
+        // Every node needs a stable id BEFORE flattening so parent/content links
+        // can reference siblings/children. Respect an explicit node id; generate
+        // one (core's nanoid scheme) otherwise.
+        const flat = [];
+        // Collision guard: an explicit id that already exists in the tree (or is
+        // reused within this same spec) would create a duplicate-id block,
+        // corrupting every id-keyed lookup (getById, parent/content links). A tree
+        // insert always creates fresh blocks (it is NOT insert-if-absent), so a
+        // collision is rejected up front — nothing is inserted and null is
+        // returned, mirroring insert's null contract. Generated ids never collide.
+        // Mutable property on a const holder (no `let`): flipped from inside the
+        // recursive visit when a colliding explicit id is seen.
+        const usedIds = new Set();
+        const collision = { hit: false };
+        // Pre-order DFS: push self FIRST, then recurse each child, so the flat
+        // array is DFS-contiguous (the invariant core's insertMany + the hook's
+        // getChildren depend on). `content` is the live child-id array, filled as
+        // each child is visited and returns its id. The root's `parent` is the
+        // resolved placement parent (undefined for root level); children's `parent`
+        // is their enclosing node's id.
+        const visit = (node, parent) => {
+            if (node.id !== undefined && (usedIds.has(node.id) || getById(node.id) !== null)) {
+                collision.hit = true;
+            }
+            const id = node.id ?? generateBlockId();
+            usedIds.add(id);
+            const content = [];
+            const flatNode = {
+                id,
+                // `type` is OMITTED (not present-with-undefined) when absent so core's
+                // `type || defaultBlock` fallback resolves the default block cleanly.
+                ...(node.type !== undefined ? { type: node.type } : {}),
+                data: node.data ?? {},
+                content,
+                ...(node.tunes !== undefined ? { tunes: node.tunes } : {}),
+                ...(parent !== undefined ? { parent } : {}),
+            };
+            flat.push(flatNode);
+            for (const child of node.children ?? []) {
+                content.push(visit(child, id));
+            }
+            return id;
+        };
+        const rootId = visit(spec, parentId ?? undefined);
+        // A colliding explicit id is rejected before any insert (see usedIds doc).
+        if (collision.hit) {
+            return null;
+        }
+        const flatIndex = resolveInsertIndex(reader, parentId, position);
+        // ONE transact for the whole subtree → a single atomic undo step. Core's
+        // insertMany composes EVERY node before inserting any, so an unknown tool
+        // type throws a typed ToolNotFoundError with nothing inserted. Honor the
+        // same null-on-unknown-tool contract as insert/insertMany rather than
+        // surfacing the throw to the caller; re-throw any other (genuine-bug)
+        // error. Keyed on the error TYPE, not a 'not found' substring.
+        try {
+            transact(() => {
+                editor.blocks.insertMany(flat, flatIndex);
+            });
+        }
+        catch (error) {
+            if (error instanceof ToolNotFoundError) {
+                return null;
+            }
+            throw error;
+        }
+        return getById(rootId);
+    };
+    /**
+     * Convert markdown to blocks and insert them ADDITIVELY — see the
+     * {@link UseBlocksApi.insertMarkdown} doc for the full contract. Async
+     * because the converter is lazy-loaded; the insert itself is one atomic
+     * undo step. parentId nesting is supported: top-level converted blocks are
+     * reparented under parentId, internally-nested ones keep their parent.
+     */
+    const insertMarkdown = async (markdown, options) => {
+        const parentId = options?.parentId ?? null;
+        const position = options?.position ?? 'end';
+        // A dangling parentId is a no-op (no insert), matching `insert`/`insertMany`.
+        if (parentId !== null && getById(parentId) === null) {
+            return [];
+        }
+        // A dangling relative position ref is likewise a no-op (no insert), NOT a
+        // silent append at the document end — mirror insert()/insertTree's guard.
+        if (typeof position === 'object') {
+            const positionTargetRef = 'before' in position ? position.before : position.after;
+            if (getById(positionTargetRef) === null) {
+                return [];
+            }
+        }
+        // Lazy-load the converter (dynamic import mirrors core's markdown lazy
+        // loading and keeps the parser out of the main bundle) and run it,
+        // forwarding the optional MarkdownImportConfig so custom-tool consumers can
+        // map markdown nodes into their tools (gfm toggle, toolMap, extensions).
+        // Both awaits can fail — a chunk-load error or a malformed-markdown throw;
+        // swallow them and return [] so a converter failure is a graceful no-op
+        // (matching update/convert) rather than an unhandled promise rejection in
+        // the caller. This await resolves BEFORE the synchronous transact.
+        // Mutable property on a const holder (no `let`): captured from the try.
+        const conversion = { blocks: [] };
+        try {
+            const { markdownToBlocks } = await import('@bloklabs/core/markdown');
+            conversion.blocks = await markdownToBlocks(markdown, options?.config);
+        }
+        catch (error) {
+            // Graceful no-op: a converter failure (chunk-load or parse error) returns
+            // [] rather than surfacing an unhandled rejection to the caller. But
+            // surface it to the console so a genuine converter bug is DISTINGUISHABLE
+            // from empty markdown (which returns [] via the blocks.length === 0 path
+            // below, without ever reaching this catch) instead of being swallowed
+            // silently and losing all diagnostics.
+            console.warn('useBlocks.insertMarkdown: markdown conversion failed', error);
+            return [];
+        }
+        const blocks = conversion.blocks;
+        // Empty / whitespace-only markdown opens no transaction (no undo boundary).
+        if (blocks.length === 0) {
+            return [];
+        }
+        // Re-validate the parent AFTER the await: the pre-await existence check can
+        // go stale if the parent was removed while the converter was in flight.
+        // Stamping a now-dangling parent would orphan the blocks instead of the
+        // promised [] no-op, so re-check and bail out here.
+        if (parentId !== null && getById(parentId) === null) {
+            return [];
+        }
+        // Re-validate the relative position ref after the await too: the target
+        // could have been removed while the converter was in flight, in which case
+        // inserting at the stale slot would surprise the caller. No-op instead.
+        if (typeof position === 'object') {
+            const positionTargetRef = 'before' in position ? position.before : position.after;
+            if (getById(positionTargetRef) === null) {
+                return [];
+            }
+        }
+        // Nest under the parent by stamping `parent` on each TOP-LEVEL block (one
+        // the converter left un-parented). Blocks the markdown nested internally
+        // (their `parent` already points at a sibling in this batch) are untouched,
+        // so the import's own structure is preserved.
+        const seeded = parentId === null
+            ? blocks
+            : blocks.map((block) => block.parent === undefined || block.parent === null
+                ? { ...block, parent: parentId }
+                : block);
+        const flatIndex = resolveInsertIndex(reader, parentId, position);
+        // Mutable property on a const holder (no `let`): captured from inside the
+        // transact closure. insertMany returns BlockAPI[] (each has `.id`) — the
+        // reliable record of what was created, since the converter's ids may not
+        // survive composition. ONE transact → a single atomic undo step.
+        const result = { created: [] };
+        // The insert lives OUTSIDE the conversion try/catch, so an unknown mapped
+        // tool (core throws a typed ToolNotFoundError) would otherwise surface as an
+        // unhandled promise rejection. Honor the same null-on-unknown-tool contract
+        // as insertTree — return [] — and re-throw any other (genuine-bug) error.
+        // Keyed on the error TYPE, not a 'not found' substring.
+        try {
+            transact(() => {
+                result.created = editor.blocks.insertMany(seeded, flatIndex);
+            });
+        }
+        catch (error) {
+            if (error instanceof ToolNotFoundError) {
+                return [];
+            }
+            throw error;
+        }
+        return result.created
+            .map((block) => getById(block.id))
+            .filter((node) => node !== null);
+    };
+    const update = (id, data, tunes) => {
+        // Silent existence probe (NOT getBlockIndex, which warns on unknown ids).
+        if (getById(id) === null) {
+            return;
+        }
+        // Core update is async and forms its own undo/Yjs step, so it is NOT
+        // wrapped in transact (that would close the group before the write lands).
+        // Swallow any rejection so it can't surface as an unhandled rejection.
+        void Promise.resolve(editor.blocks.update(id, data, tunes)).catch(() => undefined);
+    };
+    const convert = (id, newType, dataOverrides, options) => {
+        if (getById(id) === null) {
+            return;
+        }
+        // Core convert is async and rejects when a tool lacks a conversionConfig.
+        // Like update, it owns its own history step (no transact). Position the
+        // caret only AFTER a successful convert (matching the in-editor keyboard
+        // turn-into, which preserves the caret) when the caller asked for it.
+        // Swallow the rejection so a non-convertible block is a graceful no-op —
+        // and on rejection the caret is left untouched.
+        void Promise.resolve(editor.blocks.convert(id, newType, dataOverrides))
+            .then((converted) => {
+            if (options?.caret !== undefined) {
+                // Core convert routes through replace(), which regenerates the block
+                // id — the resolved BlockAPI carries the NEW id. Target it (falling
+                // back to the original only if a faithless path resolves nothing) so
+                // the caret lands in the converted block instead of a stale id.
+                const targetId = converted?.id ?? id;
+                editor.caret.setToBlock(targetId, options.caret.position ?? 'default', options.caret.offset ?? 0);
+            }
+        })
+            .catch(() => undefined);
+    };
+    const transactWithoutCapture = (fn) => {
+        if (editor.blocks.transactWithoutCapture !== undefined) {
+            editor.blocks.transactWithoutCapture(fn);
+        }
+        else {
+            fn();
+        }
+    };
+    const getBlocksCount = () => {
+        onRead();
+        return editor.blocks.getBlocksCount();
+    };
+    const getCurrentBlockIndex = () => {
+        onRead();
+        return editor.blocks.getCurrentBlockIndex();
+    };
+    const getBlockByIndex = (index) => {
+        onRead();
+        const block = editor.blocks.getBlockByIndex(index);
+        return block === undefined ? null : getById(block.id);
+    };
+    const getBlockByElement = (element) => {
+        onRead();
+        const block = editor.blocks.getBlockByElement(element);
+        return block === undefined ? null : getById(block.id);
+    };
+    const composeBlockData = (toolName) => editor.blocks.composeBlockData(toolName);
+    const getBlockData = (id) => {
+        // Silent existence probe via the snapshot getById (NOT editor.blocks.getById,
+        // which logs a `warn` for an unknown id) so a miss is a quiet null, matching
+        // getBlockIndex and the other id-taking readers.
+        if (getById(id) === null) {
+            return null;
+        }
+        const block = editor.blocks.getById(id);
+        if (block === null) {
+            return null;
+        }
+        // preservedData/preservedTunes are core's SYNCHRONOUS last-extracted view —
+        // the same snapshot clipboard ops read. Returning it (rather than the async
+        // save()) keeps this reader synchronous so a block can be read and re-inserted
+        // (duplicated) inside one render/handler without the ref escape hatch.
+        return { data: block.preservedData, tunes: block.preservedTunes };
+    };
+    const getBlockIndex = (id) => {
+        if (getById(id) === null) {
+            // Silent existence probe (NOT editor.blocks.getBlockIndex, which warns on
+            // unknown ids) so a miss is a quiet null, matching every other reader.
+            return null;
+        }
+        return editor.blocks.getBlockIndex(id) ?? null;
+    };
+    const renderFromHTML = (html) => editor.blocks.renderFromHTML(html);
+    const splitBlock = (currentBlockId, currentBlockData, newBlockType, newBlockData, insertIndex) => {
+        // Silent no-op for an unknown current block, matching every other id-taking
+        // mutator. Probe via the snapshot getById (NOT getBlockIndex, which warns).
+        if (getById(currentBlockId) === null) {
+            return null;
+        }
+        // A negative insertIndex is malformed — core would forward it to a splice
+        // (which counts from the array end) and silently split at the wrong slot.
+        // Honor the silent-no-op convention instead (consistent with
+        // insertOutputData's negative-index guard): return null without touching core.
+        if (insertIndex < 0) {
+            return null;
+        }
+        // An unknown newBlockType makes core's compose path throw a typed
+        // ToolNotFoundError — honor the null contract (mirroring insert/insertTree);
+        // re-throw any other (genuine-bug) error. Keyed on the error TYPE.
+        const created = (() => {
+            try {
+                return editor.blocks.splitBlock(currentBlockId, currentBlockData, newBlockType, newBlockData, insertIndex);
+            }
+            catch (error) {
+                if (error instanceof ToolNotFoundError) {
+                    return null;
+                }
+                throw error;
+            }
+        })();
+        return created === undefined || created === null ? null : getById(created.id);
+    };
+    const insertOutputData = (blocks, options) => {
+        // An empty batch opens no transaction (no spurious undo boundary).
+        if (blocks.length === 0) {
+            return [];
+        }
+        // A negative index is malformed — core throws a bare validation Error. Honor
+        // the silent-no-op convention instead: return [] without inserting (no
+        // transaction, no surprise end-append), consistent with the rest of the API.
+        if (options?.index !== undefined && options.index < 0) {
+            return [];
+        }
+        // ONE transact for the whole batch → a single atomic undo step. Delegates
+        // to core's raw insertMany, which honors each block's parent/content links.
+        // Honor the same null/[]-on-unknown-tool contract as insertTree (core throws
+        // a typed ToolNotFoundError); re-throw any other (genuine-bug) error.
+        const result = { created: [] };
+        try {
+            transact(() => {
+                result.created =
+                    options?.index !== undefined
+                        ? editor.blocks.insertMany(blocks, options.index)
+                        : editor.blocks.insertMany(blocks);
+            });
+        }
+        catch (error) {
+            if (error instanceof ToolNotFoundError) {
+                return [];
+            }
+            throw error;
+        }
+        return result.created
+            .map((block) => getById(block.id))
+            .filter((node) => node !== null);
+    };
+    /**
+     * Insert one child block under `parentId` at flat `insertIndex`, atomically.
+     * Delegates to core's `insertInsideParent`, which groups the block creation
+     * AND the parent assignment into a single undo entry itself — so this is NOT
+     * wrapped in the hook's `transact` (that would be a redundant nested group).
+     * A dangling parentId is a no-op (null), mirroring `insert`'s parent guard;
+     * an unknown child tool throws a typed ToolNotFoundError from core's compose
+     * path — honor the null contract and re-throw anything else (genuine bug).
+     */
+    const insertInsideParent = (parentId, insertIndex, childData) => {
+        // Silent existence probe (NOT getBlockIndex, which warns on unknown ids).
+        if (getById(parentId) === null) {
+            return null;
+        }
+        const created = (() => {
+            try {
+                return editor.blocks.insertInsideParent(parentId, insertIndex, childData);
+            }
+            catch (error) {
+                if (error instanceof ToolNotFoundError) {
+                    return null;
+                }
+                throw error;
+            }
+        })();
+        return created === undefined || created === null ? null : getById(created.id);
+    };
+    /**
+     * Replace the whole document with saved {@link OutputData} — a document-LOAD
+     * primitive (clears existing content first), the counterpart of the additive
+     * {@link insertOutputData}. Pure delegation to core's async `render`.
+     */
+    const render = (data) => editor.blocks.render(data);
+    /** Remove every block — document reset. Pure delegation to core's async `clear`. */
+    const clear = () => editor.blocks.clear();
+    /**
+     * Serialize the document to Markdown — the read-side twin of
+     * {@link UseBlocksApi.insertMarkdown}. Pure delegation to core's async
+     * `exportMarkdown` (which lazy-loads the serializer).
+     */
+    const exportMarkdown = () => editor.blocks.exportMarkdown();
+    /**
+     * The LIVE Yjs-sync flag, read at call time (the api handle is memoized, so a
+     * cached property would go stale). Pure delegation to core's read-only flag.
+     */
+    const isSyncingFromYjs = () => {
+        onRead();
+        return editor.blocks.isSyncingFromYjs;
+    };
+    // Every key is listed EXPLICITLY — do NOT spread `...EMPTY_API` here. The
+    // return is typed `UseBlocksApi`, so an explicit list makes a forgotten live
+    // wiring a COMPILE error (missing property). Spreading EMPTY_API would instead
+    // backfill the missing key with its pre-ready no-op stub, silently shipping a
+    // method that does nothing when the editor IS ready — a hole no key-presence
+    // test can catch (the key is present, just wrong). Keep it exhaustive.
+    return {
+        getById,
+        getChildren,
+        insert,
+        insertMany,
+        insertTree,
+        insertMarkdown,
+        exportMarkdown,
+        move,
+        nest,
+        unnest,
+        remove,
+        update,
+        convert,
+        transact,
+        transactWithoutCapture,
+        getBlocksCount,
+        getCurrentBlockIndex,
+        getBlockByIndex,
+        getBlockByElement,
+        getBlockData,
+        getBlockIndex,
+        composeBlockData,
+        renderFromHTML,
+        insertOutputData,
+        splitBlock,
+        insertInsideParent,
+        render,
+        clear,
+        isSyncingFromYjs,
+    };
+};
+
+/**
+ * Single source of truth for interpreting the `readOnly` config option.
+ * The object form always means read-only is enabled.
+ * @param value - raw `readOnly` value from BlokConfig
+ */
+function normalizeReadOnlyConfig(value) {
+    if (typeof value === 'object' && value !== null) {
+        return { enabled: true, hideControls: value.hideControls === true };
+    }
+    return { enabled: value === true, hideControls: false };
+}
+
+/**
+ * Structural deep equality for JSON-like values (Blok `OutputData`).
+ *
+ * Framework-agnostic: shared by the React and Angular adapters to dedupe
+ * reactive `data` updates so identical content does not trigger a redundant
+ * re-render that would clobber the caret/selection. Handles the value shapes
+ * that appear in editor data: plain objects, arrays, and primitives (including
+ * `null`/`undefined`).
+ * @param a - first value to compare
+ * @param b - second value to compare
+ * @returns true when both values are structurally equal
+ */
+function deepEqual(a, b) {
+    if (a === b) {
+        return true;
+    }
+    if (typeof a !== 'object' || a === null || typeof b !== 'object' || b === null) {
+        return false;
+    }
+    const aIsArray = Array.isArray(a);
+    const bIsArray = Array.isArray(b);
+    if (aIsArray !== bIsArray) {
+        return false;
+    }
+    if (aIsArray && bIsArray) {
+        if (a.length !== b.length) {
+            return false;
+        }
+        return a.every((item, index) => deepEqual(item, b[index]));
+    }
+    const aObj = a;
+    const bObj = b;
+    const aKeys = Object.keys(aObj);
+    const bKeys = Object.keys(bObj);
+    if (aKeys.length !== bKeys.length) {
+        return false;
+    }
+    return aKeys.every((key) => Object.prototype.hasOwnProperty.call(bObj, key) && deepEqual(aObj[key], bObj[key]));
+}
+
+// src/shared/prop-schema.ts
+/**
+ * Fill a data object against the schema: every schema key present, incoming
+ * value when defined else the schema default, and ONLY schema keys (so `save()`
+ * is never partial). Returns a frozen plain object — safe to hand straight to
+ * core's per-key Yjs sync.
+ */
+const fillDefaults = (schema, data) => {
+    const result = {};
+    for (const key of Object.keys(schema)) {
+        result[key] = data[key] !== undefined ? data[key] : schema[key].default;
+    }
+    return Object.freeze(result);
+};
+
+/**
+ * Centralized data attributes used across the Blok editor.
+ * This is the single source of truth for all data-blok-* attributes.
+ *
+ * Exported as Blok.DATA_ATTR for users.
+ *
+ * Naming convention:
+ * - Remove 'data-blok-' prefix and convert to camelCase
+ * - Global attributes: hidden, disabled, focused
+ * - Component prefixed: popover, popoverItem, toolbar, etc.
+ */
+const DATA_ATTR = {
+    // ============================================
+    // Core Element Identifiers
+    // ============================================
+    /** Interface type identifier (blok, inline-toolbar, tooltip) */
+    interface: 'data-blok-interface',
+    /** Block element wrapper */
+    element: 'data-blok-element',
+    /** Block element content wrapper */
+    elementContent: 'data-blok-element-content',
+    /** Editor wrapper container */
+    editor: 'data-blok-editor',
+    /** Redactor zone */
+    redactor: 'data-blok-redactor',
+    /** Present on the editor wrapper once a `blocks.render()` batch has finished
+     *  inserting blocks into the DOM; removed while a re-render is in flight.
+     *  Acts as a stable render-readiness gate for consumers (e.g. E2E waits). */
+    rendered: 'data-blok-rendered',
+    // ============================================
+    // Block Identifiers
+    // ============================================
+    /** Block unique identifier */
+    id: 'data-blok-id',
+    /** Block component/tool type */
+    component: 'data-blok-component',
+    /** Tool type attribute */
+    tool: 'data-blok-tool',
+    /** Block nesting depth (derived from the parentId chain) */
+    depth: 'data-blok-depth',
+    /** Flat list-nesting indentation level (0 = root); tool-agnostic, mirrors list depth */
+    indent: 'data-blok-indent',
+    // ============================================
+    // Global States
+    // ============================================
+    /** Element is hidden from view */
+    hidden: 'data-blok-hidden',
+    /** Element is disabled and non-interactive */
+    disabled: 'data-blok-disabled',
+    /** Element is focused via keyboard navigation */
+    focused: 'data-blok-focused',
+    /** Block is selected */
+    selected: 'data-blok-selected',
+    /** Block is stretched */
+    stretched: 'data-blok-stretched',
+    /** Editor or element is empty */
+    empty: 'data-blok-empty',
+    // ============================================
+    // Editor Modes
+    // ============================================
+    /** Content alignment mode (left, center, right) */
+    contentAlign: 'data-blok-content-align',
+    /** Right-to-left mode */
+    rtl: 'data-blok-rtl',
+    /** Editor content width mode (present with value "full" for wide mode; absent = narrow) */
+    width: 'data-blok-width',
+    // ============================================
+    // Drag and Drop
+    // ============================================
+    /** Block is being dragged */
+    dragging: 'data-blok-dragging',
+    /** Multiple blocks being dragged */
+    draggingMulti: 'data-blok-dragging-multi',
+    /** Block is being duplicated (Alt+drag) */
+    duplicating: 'data-blok-duplicating',
+    /** Drag handle element */
+    dragHandle: 'data-blok-drag-handle',
+    // ============================================
+    // Toolbar
+    // ============================================
+    /** Toolbar element */
+    toolbar: 'data-blok-toolbar',
+    /** Settings toggler button */
+    settingsToggler: 'data-blok-settings-toggler',
+    /** Toolbox is open */
+    toolboxOpened: 'data-blok-toolbox-opened',
+    /** Block settings is open */
+    blockSettingsOpened: 'data-blok-block-settings-opened',
+    /** Element is opened (generic) */
+    opened: 'data-blok-opened',
+    // ============================================
+    // Popover Container
+    // ============================================
+    /** Root popover element */
+    popover: 'data-blok-popover',
+    /** Popover container wrapper */
+    popoverContainer: 'data-blok-popover-container',
+    /** Popover items list */
+    popoverItems: 'data-blok-popover-items',
+    /** Custom, engine-independent scrollbar thumb overlaid on the popover items */
+    popoverScrollbar: 'data-blok-popover-scrollbar',
+    /** Stamped on the custom scrollbar thumb while it is being dragged (keeps it revealed) */
+    popoverScrollbarDragging: 'data-blok-dragging',
+    /** Stamped on a scroll container while it is actively scrolling (reveals the auto-hidden scrollbar thumb) */
+    scrolling: 'data-blok-scrolling',
+    /** Popover overlay element */
+    popoverOverlay: 'data-blok-popover-overlay',
+    /** Popover custom content area */
+    popoverCustomContent: 'data-blok-popover-custom-content',
+    /** Popover custom class */
+    popoverCustomClass: 'data-blok-popover-custom-class',
+    /** Inline popover variant */
+    popoverInline: 'data-blok-popover-inline',
+    /** Popover is open */
+    popoverOpened: 'data-blok-popover-opened',
+    /** Popover opens upward */
+    popoverOpenTop: 'data-blok-popover-open-top',
+    /** Popover opens leftward */
+    popoverOpenLeft: 'data-blok-popover-open-left',
+    // ============================================
+    // Popover Nesting
+    // ============================================
+    /** Nested popover indicator */
+    nested: 'data-blok-nested',
+    /** Nesting level value */
+    nestedLevel: 'data-blok-nested-level',
+    /** Group label for promoted search results from nested children */
+    promotedGroupLabel: 'data-blok-promoted-group-label',
+    /** Group label for top-level matches in search results */
+    topLevelGroupLabel: 'data-blok-top-level-group-label',
+    // ============================================
+    // Popover Header
+    // ============================================
+    /** Header container */
+    popoverHeader: 'data-blok-popover-header',
+    /** Header text element */
+    popoverHeaderText: 'data-blok-popover-header-text',
+    /** Back button in nested popover */
+    popoverHeaderBackButton: 'data-blok-popover-header-back-button',
+    // ============================================
+    // Popover Items
+    // ============================================
+    /** Item container */
+    popoverItem: 'data-blok-popover-item',
+    /** Item icon wrapper */
+    popoverItemIcon: 'data-blok-popover-item-icon',
+    /** Chevron icon for nested items */
+    popoverItemIconChevronRight: 'data-blok-popover-item-icon-chevron-right',
+    /** Item title text */
+    popoverItemTitle: 'data-blok-popover-item-title',
+    /** Item secondary title */
+    popoverItemSecondaryTitle: 'data-blok-popover-item-secondary-title',
+    /** Item is active/selected */
+    popoverItemActive: 'data-blok-popover-item-active',
+    /** Confirmation state */
+    popoverItemConfirmation: 'data-blok-popover-item-confirmation',
+    /** Disable hover styling */
+    popoverItemNoHover: 'data-blok-popover-item-no-hover',
+    /** Disable focus handling */
+    popoverItemNoFocus: 'data-blok-popover-item-no-focus',
+    /** Destructive action item (e.g. delete) */
+    popoverItemDestructive: 'data-blok-popover-item-destructive',
+    /** Separator item */
+    popoverItemSeparator: 'data-blok-popover-item-separator',
+    /** Separator line element */
+    popoverItemSeparatorLine: 'data-blok-popover-item-separator-line',
+    /** HTML-based item */
+    popoverItemHtml: 'data-blok-popover-item-html',
+    /** Item has child menu */
+    hasChildren: 'data-blok-has-children',
+    /** Item name identifier */
+    itemName: 'data-blok-item-name',
+    /** No search results shown */
+    nothingFoundDisplayed: 'data-blok-nothing-found-displayed',
+    // ============================================
+    // Overlay / Selection
+    // ============================================
+    /** Selection overlay */
+    overlay: 'data-blok-overlay',
+    /** Overlay container */
+    overlayContainer: 'data-blok-overlay-container',
+    /** Selection rectangle */
+    overlayRectangle: 'data-blok-overlay-rectangle',
+    /** Overlay is hidden */
+    overlayHidden: 'data-blok-overlay-hidden',
+    /** Fake cursor indicator */
+    fakeCursor: 'data-blok-fake-cursor',
+    /** Fake background for selection */
+    fakeBackground: 'data-blok-fake-background',
+    // ============================================
+    // Scroll
+    // ============================================
+    /** Auto-scroll zone (top/bottom) */
+    scrollZone: 'data-blok-scroll-zone',
+    /** Scroll is locked */
+    scrollLocked: 'data-blok-scroll-locked',
+    /** Hard scroll lock */
+    scrollLockedHard: 'data-blok-scroll-locked-hard',
+    // ============================================
+    // Caret
+    // ============================================
+    /** Shadow caret element */
+    shadowCaret: 'data-blok-shadow-caret',
+    // ============================================
+    // Placeholders
+    // ============================================
+    /** Placeholder text */
+    placeholder: 'data-blok-placeholder',
+    /** Active placeholder text */
+    placeholderActive: 'data-blok-placeholder-active',
+    // ============================================
+    // Nested Blocks
+    // ============================================
+    /** Container that hosts nested block holders (table cells, toggle/callout/header children).
+     *  Used as a universal guard: before moving a block holder via appendChild,
+     *  check `holder.closest([nestedBlocks])` — if truthy, the holder is already
+     *  claimed by another container and must not be stolen. */
+    nestedBlocks: 'data-blok-nested-blocks',
+    // ============================================
+    // Mutation Tracking
+    // ============================================
+    /** Element excluded from mutation tracking */
+    mutationFree: 'data-blok-mutation-free',
+    // ============================================
+    // Navigation
+    // ============================================
+    /** Block has navigation focus */
+    navigationFocused: 'data-blok-navigation-focused',
+    /** Flipper navigation target */
+    flipperNavigationTarget: 'data-blok-flipper-navigation-target',
+    // ============================================
+    // Inline Toolbar
+    // ============================================
+    /** Inline toolbar enabled on external element */
+    inlineToolbar: 'data-blok-inline-toolbar',
+    // ============================================
+    // Link Tool
+    // ============================================
+    /** Link tool is active */
+    linkToolActive: 'data-blok-link-tool-active',
+    /** Link tool unlink mode */
+    linkToolUnlink: 'data-blok-link-tool-unlink',
+    /** Link tool input is opened */
+    linkToolInputOpened: 'data-blok-link-tool-input-opened',
+    // ============================================
+    // Bold Tool
+    // ============================================
+    /** Bold collapsed length tracking */
+    boldCollapsedLength: 'data-blok-bold-collapsed-length',
+    /** Bold collapsed active state */
+    boldCollapsedActive: 'data-blok-bold-collapsed-active',
+    /** Bold previous length tracking */
+    boldPrevLength: 'data-blok-bold-prev-length',
+    /** Bold leading whitespace */
+    boldLeadingWs: 'data-blok-bold-leading-ws',
+    /** Bold marker */
+    boldMarker: 'data-blok-bold-marker',
+    // ============================================
+    // Tooltip
+    // ============================================
+    /** Tooltip is shown */
+    shown: 'data-blok-shown',
+    /** Tooltip placement */
+    placement: 'data-blok-placement',
+    // ============================================
+    // Notifier
+    // ============================================
+    /** Bounce in animation */
+    bounceIn: 'data-blok-bounce-in',
+    // ============================================
+    // Announcer (Accessibility)
+    // ============================================
+    /** Live region announcer */
+    announcer: 'data-blok-announcer',
+    // ============================================
+    // Stub Block
+    // ============================================
+    /** Stub block element */
+    stub: 'data-blok-stub',
+    /** Stub info section */
+    stubInfo: 'data-blok-stub-info',
+    /** Stub title */
+    stubTitle: 'data-blok-stub-title',
+    /** Stub subtitle */
+    stubSubtitle: 'data-blok-stub-subtitle',
+    // ============================================
+    // Slash Search
+    // ============================================
+    /** Slash search active on content editable */
+    slashSearch: 'data-blok-slash-search',
+    // ============================================
+    // Testing
+    // ============================================
+    /** Test identifier (for E2E tests) */
+    testid: 'data-blok-testid',
+    /** Force hover state (for tests/storybook) */
+    forceHover: 'data-blok-force-hover',
+};
+/**
+ * Helper function to create a CSS selector from an attribute
+ *
+ * @param attr - The data attribute name from DATA_ATTR
+ * @param value - Optional value for the attribute (defaults to presence selector)
+ * @returns CSS selector string
+ *
+ * @example
+ * createSelector(DATA_ATTR.element) // '[data-blok-element]'
+ * createSelector(DATA_ATTR.selected, true) // '[data-blok-selected="true"]'
+ * createSelector(DATA_ATTR.tool, 'paragraph') // '[data-blok-tool="paragraph"]'
+ */
+const createSelector = (attr, value) => {
+    if (value === undefined) {
+        return `[${attr}]`;
+    }
+    return `[${attr}="${value}"]`;
+};
+
+/**
+ * Mount child block holders into a container, skipping children that are
+ * already in place or claimed by another nested-blocks container.
+ *
+ * Used by toggle, header, column, and callout tools to reconcile child holders
+ * during the `rendered()` lifecycle hook.
+ */
+const mountChildBlocks = (container, children) => {
+    for (const child of children) {
+        if (child.holder.parentElement === container) {
+            continue;
+        }
+        const nested = child.holder.closest(`[${DATA_ATTR.nestedBlocks}]`);
+        // Claim a holder stranded in the column_list ROW. A drag reparent into a
+        // column drops the moved holder directly into the [data-blok-columns] row
+        // (itself a nested-blocks container that wraps each column's own container).
+        // Left there it renders as a rogue new column, so pull it down into THIS
+        // column container where it belongs. Scoped to the column_list row
+        // specifically — claiming from arbitrary ancestor containers would let one
+        // table cell steal a paragraph transiently parked in an outer container.
+        if (nested !== null &&
+            nested !== container &&
+            nested.hasAttribute('data-blok-columns') &&
+            nested.contains(container)) {
+            container.appendChild(child.holder);
+            continue;
+        }
+        // Otherwise leave holders that already live inside another nested container
+        // (a sibling, or a deeper nesting within this one) where they are.
+        if (nested !== null) {
+            continue;
+        }
+        container.appendChild(child.holder);
+    }
+};
+
+/**
+ * The blessed all-in-one Angular component for embedding Blok (mirrors React's
+ * `BlokEditor`). Delegates instance lifecycle to an internal `BlokContentDirective`
+ * and layers the typed reactive input/output API on top.
+ *
+ * Reactive inputs (`readOnly`, `theme`, `width`, `placeholder`, `autofocus`) are
+ * synced in place after mount via effects; everything else seeds construction.
+ *
+ * Implementation note: classic `@Input()`/`@ViewChild()` decorators are used
+ * (not signal `input()`/`viewChild()`) for JIT compatibility — see
+ * `BlokContentDirective`. Each reactive input is backed by an internal `signal`
+ * so effect-based syncing still works; the public template API is unchanged.
+ */
+class BlokEditorComponent {
+    ngZone = inject(NgZone);
+    /** App-wide defaults from `provideBlok()`; merged UNDER per-instance inputs. */
+    defaults = inject(BLOK_DEFAULT_CONFIG, { optional: true }) ?? {};
+    contentQuery;
+    /** Signal bridge for the @ViewChild directive so effects react to its arrival. */
+    content = signal(null, ...(ngDevMode ? [{ debugName: "content" }] : []));
+    /**
+     * Output half of two-way `[(data)]`. Emits the editor's serialized content on
+     * every change. Wiring the core `onSave` callback is gated on this being
+     * observed, since its mere presence makes the core serialize on every batch.
+     */
+    /** Emits the live Blok instance once ready, after `instance()` is populated. */
+    ready = new EventEmitter();
+    dataChange = new EventEmitter();
+    /** Fires with the full serialized content on every change (notification half). */
+    save = new EventEmitter();
+    /** Raw block mutation channel (core `onChange`). */
+    change = new EventEmitter();
+    /** Fires after the editor finishes (re-)rendering (core `onAfterRender`). */
+    afterRender = new EventEmitter();
+    /** Fires with the resolved theme whenever it changes (core `onThemeChange`). */
+    themeChange = new EventEmitter();
+    /** Fires after a batch render completes (core `blocks:rendered` event). */
+    blocksRendered = new EventEmitter();
+    /** Fires for each block rendered into the DOM (core `block:rendered` event). */
+    blockRendered = new EventEmitter();
+    /**
+     * Transform hook applied to blocks before render (core `onBeforeRender`). Must
+     * return the (possibly modified) block list. An input, not an output, because
+     * it returns a value.
+     */
+    onBeforeRender;
+    /**
+     * Transform hook applied to pasted HTML (core `onBeforePaste`). Returns the
+     * (possibly modified) html, or null to drop the paste.
+     */
+    onBeforePaste;
+    // ---- Reactive inputs (signal-backed setters; synced in place, never recreate) ----
+    // Default undefined (not false) so an unset input falls back to a provideBlok
+    // default; the readOnly effect / buildConfig coerce undefined to false.
+    readOnly$ = signal(undefined, ...(ngDevMode ? [{ debugName: "readOnly$" }] : []));
+    set readOnly(value) {
+        this.readOnly$.set(value);
+    }
+    theme$ = signal(undefined, ...(ngDevMode ? [{ debugName: "theme$" }] : []));
+    set theme(value) {
+        this.theme$.set(value);
+    }
+    width$ = signal(undefined, ...(ngDevMode ? [{ debugName: "width$" }] : []));
+    set width(value) {
+        this.width$.set(value);
+    }
+    placeholder$ = signal(undefined, ...(ngDevMode ? [{ debugName: "placeholder$" }] : []));
+    set placeholder(value) {
+        this.placeholder$.set(value);
+    }
+    autofocus$ = signal(false, ...(ngDevMode ? [{ debugName: "autofocus$" }] : []));
+    set autofocus(value) {
+        this.autofocus$.set(value);
+    }
+    // ---- Reactive content (seeds construction, then re-renders on change) ----
+    data$ = signal(undefined, ...(ngDevMode ? [{ debugName: "data$" }] : []));
+    set data(value) {
+        this.data$.set(value);
+    }
+    // ---- Construction-only seed inputs (read once at construction) ----
+    tools;
+    /**
+     * Escape hatch: a full config object for keys without a dedicated input
+     * (i18n, sanitizer, minHeight, inlineToolbar, …). Layered between provideBlok
+     * defaults and the discrete inputs.
+     */
+    config;
+    /** Changing this input's identity destroys and recreates the editor (≙ React `deps`). */
+    recreateKey;
+    /**
+     * Content the editor currently reflects. Set when seeded or rendered (the data
+     * effect below). A controlled `data` echo that deep-equals this baseline is a
+     * no-op, so it won't clobber the caret. Renders are serialized via `renderChain`.
+     */
+    lastRenderedData;
+    seededEditor = null;
+    renderChain = Promise.resolve();
+    /** Registered by `ControlValueAccessor.registerOnChange` (Angular forms). */
+    cvaOnChange;
+    cvaOnTouched;
+    /**
+     * Core `onSave` wrapper. Records the editor's own serialized output as the
+     * rendered baseline BEFORE notifying Angular, so a controlled consumer echoing
+     * it straight back into `data` deep-equals the baseline and is deduped to a
+     * no-op (no redundant render, no caret reset). Re-enters the Angular zone since
+     * the editor runs outside it.
+     */
+    coreOnSave = (data) => {
+        this.lastRenderedData = data;
+        this.ngZone.run(() => {
+            this.dataChange.emit(data);
+            this.save.emit(data);
+            this.cvaOnChange?.(data);
+            this.cvaOnTouched?.();
+        });
+    };
+    /** Live Blok instance, or null until `isReady` resolves / after destroy. */
+    instance = computed(() => this.content()?.instance() ?? null, ...(ngDevMode ? [{ debugName: "instance" }] : []));
+    /** Guards `ready` to one emission per editor instance. */
+    lastReadyInstance = null;
+    /**
+     * Construction config handed to the directive. Seeds the editor's initial
+     * values; the directive only reads it once (at construction), so post-mount
+     * changes to construction-only inputs are no-ops by design.
+     */
+    buildConfig() {
+        // Precedence: provideBlok defaults < [config] escape hatch < discrete inputs.
+        const cfg = { ...this.defaults, ...this.config };
+        cfg.readOnly = this.readOnly$() ?? this.config?.readOnly ?? this.defaults.readOnly ?? false;
+        // tools registries are MERGED (not replaced) across all three layers so a
+        // shared registry composes with per-instance additions.
+        if (this.tools !== undefined ||
+            this.config?.tools !== undefined ||
+            this.defaults.tools !== undefined) {
+            cfg.tools = { ...this.defaults.tools, ...this.config?.tools, ...this.tools };
+        }
+        const data = this.data$();
+        if (data !== undefined) {
+            cfg.data = data;
+        }
+        const theme = this.theme$();
+        if (theme !== undefined) {
+            cfg.theme = theme;
+        }
+        const width = this.width$();
+        if (width !== undefined) {
+            cfg.width = width;
+        }
+        const placeholder = this.placeholder$();
+        if (placeholder !== undefined) {
+            cfg.placeholder = placeholder;
+        }
+        // Opt-in: only attach each core callback when the consumer actually consumes
+        // it (an observed output, a registered forms hook, or a provided transform).
+        // Their mere presence makes the core serialize / run hooks on every change.
+        if (this.dataChange.observed || this.save.observed || this.cvaOnChange !== undefined) {
+            cfg.onSave = this.coreOnSave;
+        }
+        if (this.change.observed) {
+            cfg.onChange = (api, event) => this.ngZone.run(() => this.change.emit({ api, event }));
+        }
+        if (this.afterRender.observed) {
+            cfg.onAfterRender = (api) => this.ngZone.run(() => this.afterRender.emit(api));
+        }
+        if (this.themeChange.observed) {
+            cfg.onThemeChange = (resolved) => this.ngZone.run(() => this.themeChange.emit(resolved));
+        }
+        // Transforms run synchronously inside core's render/paste pipeline and must
+        // return a value — never wrap them in ngZone.run.
+        const beforeRender = this.onBeforeRender;
+        if (beforeRender !== undefined) {
+            cfg.onBeforeRender = (blocks) => beforeRender(blocks);
+        }
+        const beforePaste = this.onBeforePaste;
+        if (beforePaste !== undefined) {
+            cfg.onBeforePaste = (html) => beforePaste(html);
+        }
+        return cfg;
+    }
+    ngAfterViewInit() {
+        this.content.set(this.contentQuery ?? null);
+    }
+    // ---- Curated imperative facade (delegates to the live instance; no-ops until ready) ----
+    /** Serialize the current content. Resolves undefined until the editor is ready. */
+    save$() {
+        return this.instance()?.save();
+    }
+    /** Move the caret into the editor. */
+    focus(atEnd) {
+        this.instance()?.focus(atEnd);
+    }
+    /** Replace the editor content. Resolves undefined until the editor is ready. */
+    render(data) {
+        return this.instance()?.render(data);
+    }
+    constructor() {
+        // Each effect reads `instance()` so it re-applies once the editor appears
+        // (the Angular analog of React's `editor` effect-dependency).
+        effect(() => {
+            const editor = this.instance();
+            const readOnly = this.readOnly$();
+            if (editor) {
+                void editor.readOnly.set(readOnly ?? normalizeReadOnlyConfig(this.config?.readOnly).enabled);
+            }
+        });
+        effect(() => {
+            const editor = this.instance();
+            const theme = this.theme$();
+            if (editor && theme !== undefined) {
+                editor.theme.set(theme);
+            }
+        });
+        effect(() => {
+            const editor = this.instance();
+            const width = this.width$();
+            if (editor && width !== undefined) {
+                editor.width.set(width);
+            }
+        });
+        effect(() => {
+            const editor = this.instance();
+            const placeholder = this.placeholder$();
+            if (editor && placeholder !== undefined) {
+                editor.placeholder.set(placeholder);
+            }
+        });
+        effect(() => {
+            const editor = this.instance();
+            if (editor && this.autofocus$()) {
+                editor.focus();
+            }
+        });
+        // Reactive content. `data` seeds the editor at construction; afterwards a new
+        // *content* value re-renders via the public render() API (deep-equal-deduped
+        // and serialized, so an unchanged reference — including the editor's own
+        // echoed output — is a no-op and never clobbers the caret).
+        effect(() => {
+            const editor = this.instance();
+            const data = this.data$();
+            if (!editor || data === undefined) {
+                return;
+            }
+            // A freshly created editor was already seeded with `data` at construction;
+            // record it without re-rendering.
+            if (this.seededEditor !== editor) {
+                this.seededEditor = editor;
+                this.lastRenderedData = data;
+                return;
+            }
+            if (deepEqual(data, this.lastRenderedData)) {
+                return;
+            }
+            this.lastRenderedData = data;
+            this.renderChain = this.renderChain.catch(() => undefined).then(() => editor.render(data));
+        });
+        // Emit `ready` once per editor, after `instance()` is populated so a consumer
+        // reading the component/ref instance inside the handler sees it.
+        effect(() => {
+            const editor = this.instance();
+            if (editor && editor !== this.lastReadyInstance) {
+                this.lastReadyInstance = editor;
+                this.ready.emit(editor);
+            }
+        });
+        // Subscribe to the editor's rendered-lifecycle events once it exists (gated on
+        // the outputs being observed). `onCleanup` unsubscribes when the instance is
+        // replaced or the component is destroyed.
+        effect((onCleanup) => {
+            const editor = this.instance();
+            if (!editor) {
+                return;
+            }
+            const handlers = [];
+            if (this.blocksRendered.observed) {
+                const handler = (payload) => this.ngZone.run(() => this.blocksRendered.emit(payload));
+                editor.on('blocks:rendered', handler);
+                handlers.push(['blocks:rendered', handler]);
+            }
+            if (this.blockRendered.observed) {
+                const handler = (payload) => this.ngZone.run(() => this.blockRendered.emit(payload));
+                editor.on('block:rendered', handler);
+                handlers.push(['block:rendered', handler]);
+            }
+            onCleanup(() => {
+                for (const [name, handler] of handlers) {
+                    editor.off(name, handler);
+                }
+            });
+        });
+    }
+    // ---- ControlValueAccessor (optional forms integration) ----
+    /** Seeds/renders an externally-set form value through the same dedup machinery. */
+    writeValue(value) {
+        this.data$.set(value ?? undefined);
+    }
+    registerOnChange(fn) {
+        this.cvaOnChange = fn;
+    }
+    registerOnTouched(fn) {
+        this.cvaOnTouched = fn;
+    }
+    /** Form disabled state maps to the editor's read-only mode (via the readOnly effect). */
+    setDisabledState(isDisabled) {
+        this.readOnly$.set(isDisabled);
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.25", ngImport: i0, type: BlokEditorComponent, deps: [], target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "14.0.0", version: "20.3.25", type: BlokEditorComponent, isStandalone: true, selector: "blok-editor", inputs: { onBeforeRender: "onBeforeRender", onBeforePaste: "onBeforePaste", readOnly: "readOnly", theme: "theme", width: "width", placeholder: "placeholder", autofocus: "autofocus", data: "data", tools: "tools", config: "config", recreateKey: "recreateKey" }, outputs: { ready: "ready", dataChange: "dataChange", save: "save", change: "change", afterRender: "afterRender", themeChange: "themeChange", blocksRendered: "blocksRendered", blockRendered: "blockRendered" }, providers: [
+            {
+                provide: NG_VALUE_ACCESSOR,
+                useExisting: forwardRef(() => BlokEditorComponent),
+                multi: true,
+            },
+        ], viewQueries: [{ propertyName: "contentQuery", first: true, predicate: BlokContentDirective, descendants: true }], exportAs: ["blok"], ngImport: i0, template: `<div blokContent [config]="buildConfig()" [recreateKey]="recreateKey"></div>`, isInline: true, dependencies: [{ kind: "directive", type: BlokContentDirective, selector: "[blokContent]", inputs: ["config", "recreateKey"], outputs: ["ready"] }], changeDetection: i0.ChangeDetectionStrategy.OnPush });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.25", ngImport: i0, type: BlokEditorComponent, decorators: [{
+            type: Component,
+            args: [{
+                    selector: 'blok-editor',
+                    standalone: true,
+                    changeDetection: ChangeDetectionStrategy.OnPush,
+                    exportAs: 'blok',
+                    imports: [BlokContentDirective],
+                    template: `<div blokContent [config]="buildConfig()" [recreateKey]="recreateKey"></div>`,
+                    providers: [
+                        {
+                            provide: NG_VALUE_ACCESSOR,
+                            useExisting: forwardRef(() => BlokEditorComponent),
+                            multi: true,
+                        },
+                    ],
+                }]
+        }], ctorParameters: () => [], propDecorators: { contentQuery: [{
+                type: ViewChild,
+                args: [BlokContentDirective]
+            }], ready: [{
+                type: Output
+            }], dataChange: [{
+                type: Output
+            }], save: [{
+                type: Output
+            }], change: [{
+                type: Output
+            }], afterRender: [{
+                type: Output
+            }], themeChange: [{
+                type: Output
+            }], blocksRendered: [{
+                type: Output
+            }], blockRendered: [{
+                type: Output
+            }], onBeforeRender: [{
+                type: Input
+            }], onBeforePaste: [{
+                type: Input
+            }], readOnly: [{
+                type: Input
+            }], theme: [{
+                type: Input
+            }], width: [{
+                type: Input
+            }], placeholder: [{
+                type: Input
+            }], autofocus: [{
+                type: Input
+            }], data: [{
+                type: Input
+            }], tools: [{
+                type: Input
+            }], config: [{
+                type: Input
+            }], recreateKey: [{
+                type: Input
+            }] } });
+
+// packages/angular/src/createAngularBlock.ts
+/**
+ * Author a first-party Angular block. Returns a `BlockToolConstructable`
+ * registered exactly like a vanilla tool (`tools: { type: { class:
+ * createAngularBlock(...) } }`).
+ *
+ * The factory owns the host element (`data-blok-mutation-free`), a frozen
+ * defaults-filled data mirror, and signals the component reads. It mounts the
+ * component into the host via the editor's shared portal registry (the analog of
+ * Vue's Teleport registry), bridging Blok's block lifecycle to Angular:
+ * - `render()` creates the host and registers the portal entry (mounted sync).
+ * - `setData()` dedups, swaps the reactive snapshot, flushes CD, resolves true.
+ * - `save()` returns the complete frozen mirror (never the DOM, never partial).
+ * - `commit()` merges a patch and fires `dispatchChange` exactly once.
+ * - `setReadOnly()` flips a reactive flag and flushes CD (in-place, no remount).
+ * - `removed()`/`destroy()` unregister the portal (deterministic unmount).
+ */
+function createAngularBlock(spec) {
+    return class AngularBlockTool {
+        /** Marker so the directive can detect Angular-block tools and inject the registry. */
+        static __isBlokAngularBlock = true;
+        static get toolbox() {
+            return spec.toolbox;
+        }
+        /**
+         * Angular blocks support read-only mode: `setReadOnly` flips a reactive flag
+         * the component reads, so the block re-renders read-only IN PLACE. Without
+         * this static, core's ReadOnly module throws when read-only is enabled and an
+         * Angular block is present.
+         */
+        static get isReadOnlySupported() {
+            return true;
+        }
+        blockApi;
+        registry;
+        pointerDrag;
+        dataSig;
+        readOnlySig;
+        ctx;
+        mirror;
+        /** Dedup baseline: skip a redundant flush of identical data. */
+        lastRendered;
+        hostEl = null;
+        /** Last host passed to ctx.mountChildren, re-mounted on each data change. */
+        childHost = null;
+        /** True while a pointer drag suppresses dispatchChange. */
+        pendingDispatch = false;
+        constructor(options) {
+            this.blockApi = options.block;
+            const config = (options.config ?? {});
+            this.registry = config[BLOK_PORTAL_REGISTRY_CONFIG_KEY];
+            // Read the LIVE pointer-drag flag so a mid-drag commit can be deferred
+            // (core silently drops a dispatchChange while a drag is active).
+            const api = options.api;
+            this.pointerDrag = () => api?.blocks?.isPointerDragActive === true;
+            this.mirror = fillDefaults(spec.propSchema, (options.data ?? {}));
+            this.lastRendered = this.mirror;
+            this.dataSig = signal(this.mirror, ...(ngDevMode ? [{ debugName: "dataSig" }] : []));
+            this.readOnlySig = signal(options.readOnly, ...(ngDevMode ? [{ debugName: "readOnlySig" }] : []));
+            this.ctx = {
+                data: this.dataSig.asReadonly(),
+                commit: this.commit,
+                block: this.blockApi,
+                readOnly: this.readOnlySig.asReadonly(),
+                mountChildren: this.mountChildren,
+            };
+        }
+        render() {
+            const host = document.createElement('div');
+            // Core's MutationObserver ignores this subtree, so Angular's DOM writes
+            // never register as a user edit.
+            host.setAttribute('data-blok-mutation-free', 'true');
+            this.hostEl = host;
+            this.registry?.register(this.blockApi.id, {
+                hostEl: host,
+                component: spec.component,
+                context: this.ctx,
+            });
+            return host;
+        }
+        rendered() {
+            spec.onRendered?.(this.blockApi);
+        }
+        save() {
+            return this.mirror;
+        }
+        async setData(newData) {
+            const next = fillDefaults(spec.propSchema, (newData ?? {}));
+            // Dedup: identical data → skip the flush, but still return true so core
+            // keeps the block in place (no remount).
+            if (deepEqual(next, this.lastRendered)) {
+                return true;
+            }
+            this.mirror = next;
+            this.lastRendered = next;
+            this.dataSig.set(next);
+            // Synchronous CD: core drives setData outside NgZone, so nothing else
+            // schedules a render. Never throw (a throw would make core remount).
+            this.registry?.flush(this.blockApi.id);
+            this.remountChildren();
+            // Resolve after a microtask for interface symmetry with the async core
+            // setData contract; CD has already flushed synchronously above.
+            await Promise.resolve();
+            return true;
+        }
+        /**
+         * In-place read-only toggle. Flips the reactive flag the component reads via
+         * `ctx.readOnly`, then flushes CD so the block re-renders read-only WITHOUT a
+         * remount (ephemeral state survives). A prototype method (not an arrow field)
+         * so core's `supportsInPlaceReadOnly` — which probes the PROTOTYPE — selects
+         * the in-place path.
+         */
+        setReadOnly(state) {
+            this.readOnlySig.set(state);
+            this.registry?.flush(this.blockApi.id);
+        }
+        moved() {
+            // No remount: core relocates the host element; the mounted view rides along
+            // as its DOM children.
+            spec.onMoved?.(this.blockApi);
+        }
+        removed() {
+            this.registry?.unregister(this.blockApi.id);
+            spec.onRemoved?.(this.blockApi);
+        }
+        destroy() {
+            // Idempotent with removed(); unregister is safe when already absent.
+            this.registry?.unregister(this.blockApi.id);
+        }
+        /** Container blocks: remember the host and (re)mount the real child holders. */
+        mountChildren = (host) => {
+            this.childHost = host;
+            host.setAttribute(DATA_ATTR.nestedBlocks, '');
+            this.remountChildren();
+        };
+        remountChildren() {
+            if (this.childHost !== null) {
+                mountChildBlocks(this.childHost, this.blockApi.getChildren());
+            }
+        }
+        /**
+         * The only data write path. Merges the patch into the frozen mirror, swaps
+         * the reactive snapshot, flushes CD, and fires dispatchChange EXACTLY once —
+         * deferring it while a pointer drag is active (core would otherwise silently
+         * drop it).
+         */
+        commit = (patch) => {
+            const next = fillDefaults(spec.propSchema, {
+                ...this.mirror,
+                ...patch,
+            });
+            this.mirror = next;
+            this.lastRendered = next;
+            this.dataSig.set(next);
+            this.registry?.flush(this.blockApi.id);
+            this.remountChildren();
+            this.flushDispatch();
+        };
+        /** Dispatch the change, or retry on the next frame if a drag is in progress. */
+        flushDispatch() {
+            if (!this.pointerDrag()) {
+                this.pendingDispatch = false;
+                this.blockApi.dispatchChange();
+                return;
+            }
+            if (this.pendingDispatch) {
+                return;
+            }
+            this.pendingDispatch = true;
+            const retry = () => {
+                if (this.pointerDrag()) {
+                    requestAnimationFrame(retry);
+                    return;
+                }
+                this.pendingDispatch = false;
+                this.blockApi.dispatchChange();
+            };
+            requestAnimationFrame(retry);
+        }
+    };
+}
+
+// packages/angular/src/useBlocks.ts
+const BLOCK_CHANGED_EVENT = 'block changed';
+/**
+ * Angular factory exposing an id/parentId-relative, reactive view of the block
+ * tree. Reads refresh whenever the editor emits `block changed`; mutators route
+ * through the editor-level `blocks` API (core's chokepoints), so undo/redo and
+ * Yjs sync are inherited rather than re-implemented.
+ *
+ * The block-tree logic is framework-agnostic and lives in the shared
+ * {@link createBlocksApiForEditor} core — the SAME implementation behind React's
+ * and Vue's `useBlocks`, so all three adapters expose the identical 28-method
+ * surface and cannot drift. This wrapper supplies only Angular's reactivity:
+ *
+ * - A private `version` signal is bumped on every `block changed`. The shared API
+ *   is built with an `onRead` seam (`() => { version() }`) that every read method
+ *   calls, so reading inside a `computed`/template tracks `version` and re-runs on
+ *   each structural mutation.
+ * - The bound API is rebuilt (via `bindToEditor`, called eagerly on first call and
+ *   then tracked by an `effect` for subsequent identity changes) when the editor
+ *   IDENTITY changes; the returned facade is stable across that swap.
+ *
+ * Call it in an injection context (component constructor / field initializer),
+ * passing the editor signal (e.g. `BlokEditorComponent.instance` /
+ * `BlokContentDirective.instance`). Pre-ready (editor null) the bound API is the
+ * shared {@link EMPTY_API}: every mutator a no-op, reads empty/null — except
+ * `transact`/`transactWithoutCapture`, which still run their callback.
+ *
+ * Note: Angular 20's `effect()` is scheduled (not eager) — it does not fire
+ * synchronously on first call. The initial binding therefore runs synchronously
+ * in the `injectBlocks` body itself (mirroring Vue's `{ immediate: true }` watch),
+ * and the effect re-binds only on subsequent editor identity changes. When the
+ * effect fires for the first time with the same editor already bound, the guard
+ * `ed === sub.editor` makes it a no-op, so no double-subscription occurs.
+ *
+ * @param editor - a signal of the Blok instance, or null pre-ready
+ */
+function injectBlocks(editor) {
+    // Bumped on every `block changed`; the shared API's read methods touch it (via
+    // the onRead seam) so template/computed reads stay reactive.
+    const version = signal(0, ...(ngDevMode ? [{ debugName: "version" }] : []));
+    const touch = () => {
+        version();
+    };
+    // The API bound to the CURRENT editor; EMPTY_API while null. A signal so the
+    // facade's reads track the editor-identity swap.
+    const bound = signal(EMPTY_API, ...(ngDevMode ? [{ debugName: "bound" }] : []));
+    // One subscription record (no `let` reassignment), re-bound on editor change.
+    const sub = { editor: null, handler: null };
+    const unsubscribe = () => {
+        if (sub.editor !== null && sub.handler !== null) {
+            sub.editor.off(BLOCK_CHANGED_EVENT, sub.handler);
+        }
+        sub.editor = null;
+        sub.handler = null;
+    };
+    /**
+     * Bind to `ed` if the identity has changed. Guards `ed === sub.editor` so a
+     * deferred first effect-run with the same editor already bound is a no-op
+     * (no double-subscription). Called synchronously on first call (immediate
+     * binding) and then re-tracked by the effect below (future identity changes).
+     */
+    const bindToEditor = (ed) => {
+        if (ed === sub.editor) {
+            return; // Same editor already bound; nothing to do.
+        }
+        unsubscribe();
+        // A changed editor identity is itself a reason to re-read.
+        version.update((v) => v + 1);
+        if (ed === null) {
+            bound.set(EMPTY_API);
+            return;
+        }
+        const handler = () => {
+            version.update((v) => v + 1);
+        };
+        ed.on(BLOCK_CHANGED_EVENT, handler);
+        sub.editor = ed;
+        sub.handler = handler;
+        bound.set(createBlocksApiForEditor(ed, touch));
+    };
+    // Run the initial binding SYNCHRONOUSLY so the returned facade is immediately
+    // usable (Angular's effect() is deferred — it does not fire on the same tick).
+    // This mirrors Vue's `watch(..., { immediate: true })`.
+    bindToEditor(editor());
+    // Re-bind when the editor identity changes. Angular 20 permits signal writes
+    // inside effect() by default (allowSignalWrites option was removed in v20).
+    effect(() => {
+        bindToEditor(editor());
+    });
+    inject(DestroyRef).onDestroy(unsubscribe);
+    // A stable facade whose methods delegate to the currently-bound API. Reading
+    // `bound()` tracks the editor swap; shared reads track `version` via onRead.
+    // Every key listed EXPLICITLY (no spread) so a forgotten delegation is a
+    // COMPILE error against UseBlocksApi rather than a silently-missing method.
+    return {
+        getById: (id) => bound().getById(id),
+        getChildren: (parentId) => bound().getChildren(parentId),
+        insert: (spec) => bound().insert(spec),
+        insertMany: (specs) => bound().insertMany(specs),
+        insertTree: (spec) => bound().insertTree(spec),
+        insertMarkdown: (markdown, options) => bound().insertMarkdown(markdown, options),
+        exportMarkdown: () => bound().exportMarkdown(),
+        move: (id, target) => bound().move(id, target),
+        nest: (id, parentId) => bound().nest(id, parentId),
+        unnest: (id) => bound().unnest(id),
+        remove: (id) => bound().remove(id),
+        update: (id, data, tunes) => bound().update(id, data, tunes),
+        convert: (id, newType, dataOverrides, options) => bound().convert(id, newType, dataOverrides, options),
+        transact: (fn) => bound().transact(fn),
+        transactWithoutCapture: (fn) => bound().transactWithoutCapture(fn),
+        getBlocksCount: () => bound().getBlocksCount(),
+        getCurrentBlockIndex: () => bound().getCurrentBlockIndex(),
+        getBlockByIndex: (index) => bound().getBlockByIndex(index),
+        getBlockByElement: (element) => bound().getBlockByElement(element),
+        getBlockData: (id) => bound().getBlockData(id),
+        getBlockIndex: (id) => bound().getBlockIndex(id),
+        composeBlockData: (toolName) => bound().composeBlockData(toolName),
+        renderFromHTML: (html) => bound().renderFromHTML(html),
+        insertOutputData: (blocks, options) => bound().insertOutputData(blocks, options),
+        splitBlock: (currentBlockId, currentBlockData, newBlockType, newBlockData, insertIndex) => bound().splitBlock(currentBlockId, currentBlockData, newBlockType, newBlockData, insertIndex),
+        insertInsideParent: (parentId, insertIndex, childData) => bound().insertInsideParent(parentId, insertIndex, childData),
+        render: (data) => bound().render(data),
+        clear: () => bound().clear(),
+        isSyncingFromYjs: () => bound().isSyncingFromYjs(),
+    };
+}
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { BLOK_BLOCK_CONTEXT, BLOK_DEFAULT_CONFIG, BlokContentDirective, BlokEditorComponent, createAngularBlock, injectBlocks, provideBlok };
+//# sourceMappingURL=bloklabs-angular.mjs.map