@bloklabs/angular 1.7.0 → 1.8.0

package/fesm2022/bloklabs-angular.mjs

@@ -1,5 +1,5 @@
 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 { InjectionToken, makeEnvironmentProviders, signal, inject, Injector, createComponent, ElementRef, NgZone, PLATFORM_ID, EnvironmentInjector, ApplicationRef, ErrorHandler, EventEmitter, 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';
@@ -27,6 +27,42 @@ function provideBlok(defaults) {
 /** DI token carrying the per-block render context into the authored component. */
 const BLOK_BLOCK_CONTEXT = new InjectionToken('BLOK_BLOCK_CONTEXT');
 
+// packages/angular/src/blok-instance.ts
+/**
+ * DI token carrying the LIVE editor instance (as a signal) into every block
+ * mounted by `createAngularBlock`. `BlokContentDirective` publishes its own
+ * `instance` signal through it, so the value is null before the editor is ready
+ * and after teardown — matching the React/Vue adapters' pre-ready contract.
+ *
+ * Provided on the block's ELEMENT injector by the portal registry, so it is
+ * per-EDITOR: two editors on one page each publish their own instance.
+ */
+const BLOK_EDITOR_INSTANCE = new InjectionToken('BLOK_EDITOR_INSTANCE');
+/** Stable "no editor here" signal for components mounted outside an editor. */
+const NO_EDITOR = signal(null).asReadonly();
+/**
+ * The live Blok instance the component is mounted inside, as a signal, or a
+ * signal of null before it exists. Inside a `createAngularBlock` component this
+ * is the block's OWN editor — so a block can drive the tree it lives in without
+ * the host prop-drilling the instance into it:
+ *
+ * ```ts
+ * private readonly editor = injectBlokInstance();
+ * private readonly blocks = injectBlocks(this.editor);
+ * ```
+ *
+ * That pairing is also what makes a container block REACTIVE to its own child
+ * tree: `injectBlocks` refreshes on the editor's `block changed` event, which
+ * core emits for every structural mutation — including children the adapter
+ * itself never sees (a pasted paragraph, a Tab-indent from the keyboard).
+ *
+ * Call it in an injection context (a field initializer or the constructor).
+ * Outside an editor it returns a signal of null.
+ */
+function injectBlokInstance() {
+    return inject(BLOK_EDITOR_INSTANCE, { optional: true }) ?? NO_EDITOR;
+}
+
 // packages/angular/src/block-portal-registry.ts
 /**
  * Tool-config key carrying the editor's portal registry into a
@@ -41,8 +77,18 @@ const BLOK_PORTAL_REGISTRY_CONFIG_KEY = '__blokAngularPortalRegistry';
  * 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.
+ *
+ * `editor` is the directive's own instance signal. It is passed at CREATION
+ * (before the editor exists) rather than set later precisely because it is a
+ * signal: blocks mounted during boot read null and re-read the real instance
+ * once it resolves.
+ * @param envInjector - the app environment injector (parent of each block's)
+ * @param appRef - the ApplicationRef each mounted block view is attached to
+ * @param errorHandler - where a throwing author component is reported
+ * @param editor - signal of the live Blok instance, published to blocks via
+ *   {@link BLOK_EDITOR_INSTANCE}; omit for registries with no editor to publish
  */
-const createBlockPortalRegistry = (envInjector, appRef, errorHandler) => {
+const createBlockPortalRegistry = (envInjector, appRef, errorHandler, editor) => {
     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.
@@ -54,7 +100,7 @@ const createBlockPortalRegistry = (envInjector, appRef, errorHandler) => {
             errorHandler.handleError(error);
         }
     };
-    const teardown = (id) => {
+    const teardown = (id, ownerHostEl) => {
         const entry = mounted.get(id);
         if (entry === undefined) {
             return;
@@ -62,6 +108,10 @@ const createBlockPortalRegistry = (envInjector, appRef, errorHandler) => {
         const { ref, injector } = entry;
         // Capture host before deletion so we can clear it below.
         const hostEl = ref.location.nativeElement;
+        // A superseded owner may not destroy the mount that replaced it.
+        if (ownerHostEl !== undefined && hostEl !== ownerHostEl) {
+            return;
+        }
         mounted.delete(id);
         appRef.detachView(ref.hostView);
         ref.destroy();
@@ -84,7 +134,14 @@ const createBlockPortalRegistry = (envInjector, appRef, errorHandler) => {
             // 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 }],
+                providers: [
+                    { provide: BLOK_BLOCK_CONTEXT, useValue: entry.context },
+                    // Per-EDITOR, so two editors on one page each publish their own
+                    // instance to their own blocks.
+                    ...(editor === undefined
+                        ? []
+                        : [{ provide: BLOK_EDITOR_INSTANCE, useValue: editor }]),
+                ],
                 parent: envInjector,
             });
             safe(() => {
@@ -100,8 +157,8 @@ const createBlockPortalRegistry = (envInjector, appRef, errorHandler) => {
                 ref.changeDetectorRef.detectChanges();
             });
         },
-        unregister(id) {
-            teardown(id);
+        unregister(id, hostEl) {
+            teardown(id, hostEl);
         },
         flush(id) {
             const entry = mounted.get(id);
@@ -219,7 +276,11 @@ class BlokContentDirective {
         }
         // 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.instance` is handed over at creation: it is a SIGNAL, so blocks
+        // mounted during boot read null and re-read the real editor once isReady
+        // resolves — no ordering problem, and `injectBlokInstance()` inside a block
+        // component tracks the swap.
+        const registry = createBlockPortalRegistry(this.envInjector, this.appRef, this.errorHandler, this.instance);
         this.registry = registry;
         merged.tools = injectPortalRegistry(merged.tools, registry);
         // Construct outside Angular's zone so the editor's internal DOM churn never
@@ -1746,21 +1807,46 @@ function deepEqual(a, b) {
  * - emptiness, to decide whether a document carries any user content
  *   (placeholder states, "save" button gating, skipping empty submissions).
  *
- * Both accept the loose wire shape (`data: null`, `id: null`, nullish
- * documents) so backend DTOs can be passed as-is.
+ * Both accept the loose wire shape (`data: null`, `id: null`, `parent: null`,
+ * `content: null`, nullish documents) so backend DTOs can be passed as-is.
  */
 /**
- * Compares two blocks structurally. The `id` participates only when BOTH
- * blocks carry one: the editor mints a fresh id whenever content arrives
- * without one (see {@link normalizeOutputBlocks}), so an id-less origin
+ * Normalizes one block from the loose wire shape into the strict saved shape.
+ * The single definition of how the wire spells "absent": `null`/`''` ids and
+ * parents, `null`/`[]` content, `null`/missing data. Shared by
+ * {@link normalizeOutputBlocks} and {@link equalsOutputBlock} so a DTO and its
+ * saved echo are judged under the same rules.
+ * @param block - a block in either the strict or the loose wire shape
+ * @returns the block in the strict saved shape
+ */
+function normalizeOutputBlock(block) {
+    const { id, data, parent, content, ...rest } = block;
+    return {
+        ...rest,
+        ...(typeof id === 'string' && id !== '' ? { id } : {}),
+        ...(typeof parent === 'string' && parent !== '' ? { parent } : {}),
+        ...(Array.isArray(content) && content.length > 0 ? { content } : {}),
+        data: data ?? {},
+    };
+}
+/**
+ * Compares two blocks structurally. Both sides are normalized first
+ * ({@link normalizeOutputBlock}), so the loose wire spellings of "absent"
+ * (`parent: null`, `content: null`, `data: null`) equal the saved shape that
+ * omits them. The `id` participates only when BOTH blocks carry one: the editor
+ * mints a fresh id whenever content arrives without one, so an id-less origin
  * document must still compare equal to its saved echo.
+ *
+ * Edit metadata (`lastEditedAt`/`lastEditedBy`) never participates: it records
+ * WHO touched the block and WHEN, not what it says, so a document whose only
+ * delta is a stamp is not a content change.
  * @param a - first block to compare
  * @param b - second block to compare
  * @returns true when the blocks are structurally equal
  */
 function equalsOutputBlock(a, b) {
-    const { id: idA, ...restA } = a;
-    const { id: idB, ...restB } = b;
+    const { id: idA, lastEditedAt: _editedAtA, lastEditedBy: _editedByA, ...restA } = normalizeOutputBlock(a);
+    const { id: idB, lastEditedAt: _editedAtB, lastEditedBy: _editedByB, ...restB } = normalizeOutputBlock(b);
     const hasIdA = typeof idA === 'string' && idA !== '';
     const hasIdB = typeof idB === 'string' && idB !== '';
     if (hasIdA && hasIdB && idA !== idB) {
@@ -1803,7 +1889,9 @@ function comparableBlocks(data, options) {
  * document round-tripped through `save()` compares equal to its echo. Block
  * ids are compared only when both sides carry one — the editor mints fresh
  * ids for id-less content, so a legacy document still equals its saved echo.
- * Nullish documents compare equal to `{ blocks: [] }`.
+ * Edit metadata (`lastEditedAt`/`lastEditedBy`) is ignored for the same reason:
+ * it records who touched a block and when, not what it says. Nullish documents
+ * compare equal to `{ blocks: [] }`.
  *
  * Pass `{ ignoreEmptyDefaultBlocks: true }` for dirty-vs-baseline checks so a
  * pristine editor (one empty default paragraph) equals a saved-empty baseline —
@@ -1877,33 +1965,30 @@ function toRenderableData(data) {
 /**
  * Normalizes blocks from the loose wire shape into the strict saved shape at
  * the editor's input boundaries: a `null`/missing `data` becomes `{}`, a
- * `null`/empty `id` is dropped so the block factory generates a fresh one.
- * Idempotent — strict blocks pass through unchanged (shallow-copied).
+ * `null`/empty `id` is dropped so the block factory generates a fresh one, and
+ * nullish/empty hierarchy references (`parent`, `content`) are dropped so a
+ * root-level, childless block is spelled the one way the editor and `save()`
+ * both spell it — absent. Idempotent — strict blocks pass through unchanged
+ * (shallow-copied).
  * @param blocks - blocks in either the strict or the loose wire shape
  * @returns blocks in the strict saved shape
  */
 function normalizeOutputBlocks(blocks) {
-    return blocks.map((block) => {
-        const { id, data, ...rest } = block;
-        return {
-            ...rest,
-            ...(typeof id === 'string' && id !== '' ? { id } : {}),
-            data: data ?? {},
-        };
-    });
+    return blocks.map(normalizeOutputBlock);
 }
 /**
  * Normalizes a whole loose wire document into the strict saved
  * {@link OutputData} shape at an input boundary. A nullish document becomes
  * `{ blocks: [] }`; `null` envelope fields (`time`/`version`) are dropped; each
  * block is passed through {@link normalizeOutputBlocks}, so `null`/missing
- * `data` becomes `{}` and `null`/empty ids are dropped for regeneration.
+ * `data` becomes `{}`, `null`/empty ids are dropped for regeneration and
+ * nullish/empty `parent`/`content` references are dropped as absent.
  *
  * Unlike a hand-written `blocks.map(...)` mapper, this preserves every block
- * passthrough field — `tunes`, `parent`, `content`, `indent`, edit metadata —
- * so a backend DTO can be turned into strict `OutputData` without silently
- * losing hierarchy or tunes. Idempotent: a strict document passes through
- * unchanged (shallow-copied).
+ * passthrough field — `tunes`, real `parent`/`content` references, `indent`,
+ * edit metadata — so a backend DTO can be turned into strict `OutputData`
+ * without silently losing hierarchy or tunes. Idempotent: a strict document
+ * passes through unchanged (shallow-copied).
  * @param data - a document in the strict or loose wire shape, or nullish
  * @returns the document in the strict saved shape
  */
@@ -1993,6 +2078,11 @@ const DATA_ATTR = {
     elementContent: 'data-blok-element-content',
     /** Editor wrapper container */
     editor: 'data-blok-editor',
+    /** Per-instance discriminator on the editor wrapper (a monotonic counter, as a
+     *  string). Two editors on one page share every other scope attribute, so this
+     *  is what lets a page-level stylesheet — Blok's own injected `style.fontSize`
+     *  sheet, or a host rule — address ONE editor. Public styling hook. */
+    instance: 'data-blok-instance',
     /** Redactor zone */
     redactor: 'data-blok-redactor',
     /** Present on the editor wrapper once a `blocks.render()` batch has finished
@@ -2206,6 +2296,24 @@ const DATA_ATTR = {
     /** Active placeholder text */
     placeholderActive: 'data-blok-placeholder-active',
     // ============================================
+    // Columns Layout
+    // ============================================
+    /** The columns row rendered by the column_list tool (the flex container).
+     *  Public styling hook — its direct `[data-blok-element]` children are the
+     *  column holders, whose shrink floor reads `--blok-column-min-width` and
+     *  whose gutter reads `--blok-column-gutter`. */
+    columns: 'data-blok-columns',
+    /** A single column inside a columns row. */
+    column: 'data-blok-column',
+    /** Drag-to-resize separator between two adjacent columns. Present only in
+     *  edit mode — the separators ARE the gutter there. */
+    columnResizer: 'data-blok-column-resizer',
+    /** Present on a columns row whose gutter comes from the container's own
+     *  column-gap instead of from resizer elements. Set in read-only mode, where
+     *  no resizers are built — the discriminator between an editable row and a
+     *  published one. */
+    columnsStaticGutter: 'data-blok-columns-static-gutter',
+    // ============================================
     // Nested Blocks
     // ============================================
     /** Container that hosts nested block holders (table cells, toggle/callout/header children).
@@ -2312,31 +2420,208 @@ const createSelector = (attr, value) => {
     return `[${attr}="${value}"]`;
 };
 
+/**
+ * HTML manipulation utilities
+ */
+/**
+ * Strips fake background wrapper elements from HTML content.
+ * These elements are used by the inline toolbar for visual selection highlighting
+ * and should not be persisted in saved data.
+ * @param html - HTML content that may contain fake background elements
+ * @returns HTML content with fake background wrappers removed but their content preserved
+ */
+const stripFakeBackgroundElements = (html) => {
+    if (!html || !html.includes('data-blok-fake-background')) {
+        return html;
+    }
+    const tempDiv = document.createElement('div');
+    tempDiv.innerHTML = html;
+    const fakeBackgrounds = tempDiv.querySelectorAll('[data-blok-fake-background="true"]');
+    fakeBackgrounds.forEach((element) => {
+        const parent = element.parentNode;
+        if (!parent) {
+            return;
+        }
+        while (element.firstChild) {
+            parent.insertBefore(element.firstChild, element);
+        }
+        parent.removeChild(element);
+    });
+    return tempDiv.innerHTML;
+};
+/**
+ * Repositions an already-attached node within `parent`, inserting it before
+ * `reference` (or at the end when `reference` is null), while preserving the
+ * node's live state — an iframe keeps its loaded document, media keeps playing,
+ * form fields keep focus and value.
+ *
+ * A plain insertBefore/appendChild detaches and re-attaches the node, which
+ * resets exactly that state (re-parented iframes reload). The browser's
+ * state-preserving move (`moveBefore`, Chrome 133+) avoids the detach; we fall
+ * back to insertBefore where it is unavailable or throws (e.g. cross-document
+ * moves, or a node that is not connected).
+ */
+const statefulMove = (parent, node, reference) => {
+    if (reference === node) {
+        return;
+    }
+    if (typeof parent.moveBefore === 'function' && node.isConnected && parent.isConnected) {
+        try {
+            parent.moveBefore(node, reference);
+            return;
+        }
+        catch {
+            // moveBefore enforces stricter invariants than insertBefore (same
+            // document, connected node); fall back to a plain, state-resetting insert.
+        }
+    }
+    parent.insertBefore(node, reference);
+};
+/**
+ * Moves `node` to sit immediately before `reference`, preserving live state.
+ * @see statefulMove
+ */
+const moveElementBefore = (node, reference) => {
+    const parent = reference.parentNode;
+    if (parent instanceof Element) {
+        statefulMove(parent, node, reference);
+    }
+};
+/**
+ * Moves `node` to sit immediately after `reference`, preserving live state.
+ * @see statefulMove
+ */
+const moveElementAfter = (node, reference) => {
+    const parent = reference.parentNode;
+    if (parent instanceof Element) {
+        statefulMove(parent, node, reference.nextSibling);
+    }
+};
+/**
+ * Moves `node` to the end of `parent`'s children, preserving live state.
+ * @see statefulMove
+ */
+const moveElementToEnd = (parent, node) => {
+    statefulMove(parent, node, null);
+};
+
+/**
+ * Captures focus + caret, but only the part of it that lives inside `holder` —
+ * a selection anywhere else is none of this move's business and must be left
+ * exactly as it is.
+ * @param holder - the holder about to be moved
+ * @returns the snapshot, or null when the caret is elsewhere
+ */
+const captureCaretWithin = (holder) => {
+    const ownerDocument = holder.ownerDocument;
+    const activeElement = ownerDocument.activeElement;
+    const focused = activeElement instanceof HTMLElement && holder.contains(activeElement) ? activeElement : null;
+    const selection = ownerDocument.defaultView?.getSelection() ?? null;
+    const range = selection !== null && selection.rangeCount > 0 ? selection.getRangeAt(0) : null;
+    const rangeInside = range !== null && holder.contains(range.startContainer) && holder.contains(range.endContainer);
+    if (focused === null && !rangeInside) {
+        return null;
+    }
+    return {
+        focused,
+        start: rangeInside && range !== null ? [range.startContainer, range.startOffset] : null,
+        end: rangeInside && range !== null ? [range.endContainer, range.endOffset] : null,
+    };
+};
+/**
+ * Re-applies a snapshot, but only where the move actually destroyed it —
+ * a browser with the state-preserving move keeps focus and the caret itself,
+ * and re-setting an identical range there would emit a spurious
+ * `selectionchange` at every container render.
+ * @param snapshot - what {@link captureCaretWithin} read, or null
+ */
+const restoreCaret = (snapshot) => {
+    if (snapshot === null) {
+        return;
+    }
+    const { focused, start, end } = snapshot;
+    if (focused !== null && focused.isConnected && focused.ownerDocument.activeElement !== focused) {
+        focused.focus({ preventScroll: true });
+    }
+    if (start === null || end === null || !start[0].isConnected) {
+        return;
+    }
+    const ownerDocument = start[0].ownerDocument;
+    const selection = ownerDocument?.defaultView?.getSelection() ?? null;
+    if (ownerDocument === null || selection === null) {
+        return;
+    }
+    const live = selection.rangeCount > 0 ? selection.getRangeAt(0) : null;
+    const intact = live !== null &&
+        live.startContainer === start[0] &&
+        live.startOffset === start[1] &&
+        live.endContainer === end[0] &&
+        live.endOffset === end[1];
+    if (intact) {
+        return;
+    }
+    const range = ownerDocument.createRange();
+    range.setStart(start[0], start[1]);
+    range.setEnd(end[0], end[1]);
+    selection.removeAllRanges();
+    selection.addRange(range);
+};
 /**
  * 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.
+ * Used by toggle, header, column, and callout tools — and by the React, Vue and
+ * Angular block adapters — to reconcile child holders during the `rendered()`
+ * lifecycle hook. It is the standing DOM↔model reconciler for container blocks:
+ * safe to call on every render, and the only thing that heals a child holder
+ * that core parked outside the container while the container's own slot had not
+ * been created yet.
+ * @param container - the container element child holders belong in; usually the
+ *   element carrying `data-blok-nested-blocks`.
+ * @param children - the container block's MODEL children, in model order (e.g.
+ *   `api.blocks.getChildren(blockId)`).
  */
 const mountChildBlocks = (container, children) => {
-    for (const child of children) {
+    /**
+     * Places a holder at its MODEL position: before the first later child that is
+     * already mounted here, or at the end when there is none. A plain appendChild
+     * would put a reclaimed middle child last — children [A, B, C] with only B
+     * stranded would render A, C, B.
+     *
+     * The move goes through the state-preserving helpers rather than raw
+     * insertBefore/appendChild: re-parenting a live node runs the DOM removing
+     * steps, which blur the focused contenteditable and relocate every live Range
+     * out of the moved subtree — the user's caret vanishes to <body> mid-typing.
+     * Where the browser has no state-preserving move, the caret is put back by
+     * hand around the move.
+     * @param holder - the holder to mount
+     * @param index - the holder's position in `children`
+     */
+    const mountAtModelPosition = (holder, index) => {
+        const anchor = children
+            .slice(index + 1)
+            .find(next => next.holder.parentElement === container)?.holder ?? null;
+        const caret = captureCaretWithin(holder);
+        anchor !== null ? moveElementBefore(holder, anchor) : moveElementToEnd(container, holder);
+        restoreCaret(caret);
+    };
+    for (const [index, child] of children.entries()) {
         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
+        // Claim a holder stranded in an ANCESTOR nested container. Callers pass
+        // this container's own MODEL children, and a container that ENCLOSES this
+        // one can never be a legitimate home for them — that is model/DOM
+        // divergence by definition. Two ways to get there: 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);
+        // (where it renders as a rogue extra column), and a newly inserted first
+        // child is anchored as the container block's DOM *sibling*, i.e. inside
+        // whatever nested container encloses it — permanent when the destination
+        // slot had not committed yet (a framework adapter's portal commits a render
+        // later than core inserts), because nothing else ever re-runs the mount.
+        if (nested !== null && nested !== container && nested.contains(container)) {
+            mountAtModelPosition(child.holder, index);
             continue;
         }
         // Otherwise leave holders that already live inside another nested container
@@ -2344,10 +2629,26 @@ const mountChildBlocks = (container, children) => {
         if (nested !== null) {
             continue;
         }
-        container.appendChild(child.holder);
+        mountAtModelPosition(child.holder, index);
     }
 };
 
+/**
+ * Fired when a CONTAINER block's child holders have been mounted into its
+ * child slot — the moment the child DOM has settled and a caret set into a
+ * freshly inserted child sticks.
+ *
+ * Emitted by the React, Vue and Angular block adapters, whose portals commit a
+ * frame AFTER core's `rendered()` hook; a vanilla container tool mounts its
+ * children synchronously inside `rendered()`, so for those `block:rendered`
+ * already means "settled". It fires on every reconciliation pass of the slot,
+ * not only the first, so treat it as a settle signal rather than a change
+ * signal.
+ *
+ * Public event name: `block:childrenMounted`.
+ */
+const BlockChildrenMounted = 'block:childrenMounted';
+
 /**
  * The blessed all-in-one Angular component for embedding Blok (mirrors React's
  * `BlokEditor`). Delegates instance lifecycle to an internal `BlokContentDirective`
@@ -2361,8 +2662,8 @@ const mountChildBlocks = (container, children) => {
  * `styleTokens` through `editor.tokens.set()` (replace semantics),
  * `i18n` through `editor.i18n.update()` (deep-equal–deduped; seeded at
  * construction so the locale resolves during boot) and `data`
- * through `editor.render()` (deep-equal–deduped); everything else seeds
- * construction.
+ * through `editor.render()` (content-deduped via `equalsOutputData`); everything
+ * else seeds construction.
  *
  * Implementation note: classic `@Input()`/`@ViewChild()` decorators are used
  * (not signal `input()`/`viewChild()`) for JIT compatibility — see
@@ -2495,9 +2796,12 @@ class BlokEditorComponent {
     /** 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`.
+     * Content the editor currently reflects. Set when seeded, when the data effect
+     * renders, when the editor emits its own output (`coreOnSave`) and when the
+     * imperative `render()` facade lands. A controlled `data` echo that
+     * content-equals this baseline is a no-op, so it won't clobber the caret.
+     * Renders are serialized via `renderChain`. `undefined` means "nothing recorded
+     * yet" — never an empty document.
      */
     lastRenderedData;
     /** Last token set pushed through `tokens.set`, for deep-equal deduping. */
@@ -2519,16 +2823,91 @@ class BlokEditorComponent {
      * 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.
+     *
+     * Falls back to an escape-hatch `[config]` callback when nothing Angular-side
+     * consumes the save — the baseline is recorded either way, so the controlled
+     * `data` dedupe works on both paths.
      */
-    coreOnSave = (data) => {
+    coreOnSave = (data, api) => {
         this.lastRenderedData = data;
-        this.ngZone.run(() => {
-            this.dataChange.emit(data);
-            this.save.emit(data);
-            this.cvaOnChange?.(data);
-            this.cvaOnTouched?.();
-        });
+        if (this.hasSaveConsumer()) {
+            this.ngZone.run(() => {
+                this.dataChange.emit(data);
+                this.save.emit(data);
+                this.cvaOnChange?.(data);
+                this.cvaOnTouched?.();
+            });
+            return;
+        }
+        this.escapeHatchConfig().onSave?.(data, api);
     };
+    /**
+     * Stable wrappers for the remaining live callbacks. Each resolves its target
+     * at call time (an observed output, else the `[config]` escape hatch), so a
+     * pushed handler never goes stale and only PRESENCE has to be synced.
+     */
+    coreOnChange = (api, event) => {
+        if (this.change.observed) {
+            this.ngZone.run(() => this.change.emit({ api, event }));
+            return;
+        }
+        this.escapeHatchConfig().onChange?.(api, event);
+    };
+    coreOnAfterRender = (api) => {
+        if (this.afterRender.observed) {
+            this.ngZone.run(() => this.afterRender.emit(api));
+            return;
+        }
+        this.escapeHatchConfig().onAfterRender?.(api);
+    };
+    /*
+     * Transforms run synchronously inside core's render pipeline and must return a
+     * value — never wrap them in ngZone.run.
+     */
+    coreOnBeforeRender = (blocks) => {
+        const transform = this.onBeforeRender ?? this.escapeHatchConfig().onBeforeRender;
+        return transform?.(blocks) ?? blocks;
+    };
+    coreOnEnter = (event, api) => this.escapeHatchConfig().onEnter?.(event, api);
+    coreOnSubmit = (data, api) => {
+        this.escapeHatchConfig().onSubmit?.(data, api);
+    };
+    /** provideBlok defaults merged under the `[config]` escape hatch. */
+    escapeHatchConfig() {
+        return { ...this.defaults, ...this.config };
+    }
+    /** True when an output, a two-way binding or Angular forms consumes `onSave`. */
+    hasSaveConsumer() {
+        return this.dataChange.observed || this.save.observed || this.cvaOnChange !== undefined;
+    }
+    /**
+     * The live callbacks this component currently wires into core, keyed by
+     * handler name — `undefined` for the ones nothing consumes.
+     *
+     * PRESENCE is the semantics in core (an `onSubmit` turns Enter into
+     * serialize-and-submit, an `onSave` arms the change-observation pipeline), so
+     * an unconsumed callback must stay absent. One source of truth for both the
+     * construction config and the runtime sync in `ngDoCheck`, so the two cannot
+     * drift.
+     * @returns the wrappers to install, `undefined` where nothing is wired
+     */
+    liveHandlers() {
+        const cfg = this.escapeHatchConfig();
+        return {
+            onChange: this.change.observed || cfg.onChange !== undefined ? this.coreOnChange : undefined,
+            onSave: this.hasSaveConsumer() || cfg.onSave !== undefined ? this.coreOnSave : undefined,
+            onEnter: cfg.onEnter !== undefined ? this.coreOnEnter : undefined,
+            onSubmit: cfg.onSubmit !== undefined ? this.coreOnSubmit : undefined,
+            onBeforeRender: this.onBeforeRender !== undefined || cfg.onBeforeRender !== undefined
+                ? this.coreOnBeforeRender
+                : undefined,
+            onAfterRender: this.afterRender.observed || cfg.onAfterRender !== undefined
+                ? this.coreOnAfterRender
+                : undefined,
+        };
+    }
+    /** Handler presence installed on the live editor (the sync dedupe baseline). */
+    appliedHandlers = {};
     /** Live Blok instance, or null until `isReady` resolves / after destroy. */
     instance = computed(() => this.content()?.instance() ?? null, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "instance" }] : /* istanbul ignore next */ []));
@@ -2589,27 +2968,24 @@ class BlokEditorComponent {
         if (i18n !== undefined) {
             cfg.i18n = i18n;
         }
-        // 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));
-        }
+        // Opt-in: only attach each live callback when the consumer actually consumes
+        // it (an observed output, a registered forms hook, a provided transform or an
+        // escape-hatch config callback). Their mere presence makes the core serialize
+        // / run hooks on every change. The same map drives the runtime sync in
+        // `ngDoCheck`, so construction and post-mount can never disagree.
+        const handlers = this.liveHandlers();
+        cfg.onChange = handlers.onChange;
+        cfg.onSave = handlers.onSave;
+        cfg.onEnter = handlers.onEnter;
+        cfg.onSubmit = handlers.onSubmit;
+        cfg.onBeforeRender = handlers.onBeforeRender;
+        cfg.onAfterRender = handlers.onAfterRender;
+        this.appliedHandlers = handlers;
         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);
-        }
+        // Transforms run synchronously inside core's paste pipeline and must return a
+        // value — never wrap them in ngZone.run.
         const beforePaste = this.onBeforePaste;
         if (beforePaste !== undefined) {
             cfg.onBeforePaste = (html) => beforePaste(html);
@@ -2623,6 +2999,62 @@ class BlokEditorComponent {
     ngAfterViewInit() {
         this.content.set(this.contentQuery ?? null);
     }
+    /**
+     * Reactive callback presence.
+     *
+     * Callback wiring was decided once, at construction, and in core the presence
+     * of a handler IS the semantics: an `onSubmit` makes Enter serialize-and-submit
+     * instead of splitting the block, an `onSave` arms the whole change-observation
+     * pipeline. A `[config]` swap, an `*ngIf`-gated `(save)` output or a
+     * `registerOnChange` from Angular forms arriving after mount therefore needed a
+     * `recreateKey` bump — destroying the editor and losing caret and undo history.
+     *
+     * Diff the wired handlers against what is installed and push genuine flips
+     * through the runtime `handlers.set` API, writing `undefined` for a handler
+     * that lost its consumer so the change stays reversible. `ngDoCheck` (not an
+     * `effect`) because `EventEmitter.observed` and the plain `@Input` transforms
+     * are not signals; the comparison is six identity checks against stable
+     * wrappers, so an unchanged cycle pushes nothing.
+     */
+    ngDoCheck() {
+        const editor = this.instance();
+        if (editor === null) {
+            return;
+        }
+        const desired = this.liveHandlers();
+        const applied = this.appliedHandlers;
+        const diff = {};
+        const changed = { value: false };
+        const sync = (key, write) => {
+            if (desired[key] === applied[key]) {
+                return;
+            }
+            applied[key] = desired[key];
+            changed.value = true;
+            write(desired[key]);
+        };
+        sync('onChange', (value) => {
+            diff.onChange = value;
+        });
+        sync('onSave', (value) => {
+            diff.onSave = value;
+        });
+        sync('onEnter', (value) => {
+            diff.onEnter = value;
+        });
+        sync('onSubmit', (value) => {
+            diff.onSubmit = value;
+        });
+        sync('onBeforeRender', (value) => {
+            diff.onBeforeRender = value;
+        });
+        sync('onAfterRender', (value) => {
+            diff.onAfterRender = value;
+        });
+        if (changed.value) {
+            editor.handlers.set(diff);
+        }
+    }
     // ---- Curated imperative facade (delegates to the live instance; no-ops until ready) ----
     /** Serialize the current content. Resolves undefined until the editor is ready. */
     save$() {
@@ -2632,9 +3064,24 @@ class BlokEditorComponent {
     focus(atEnd) {
         this.instance()?.focus(atEnd);
     }
-    /** Replace the editor content. Resolves undefined until the editor is ready. */
+    /**
+     * Replace the editor content. Resolves undefined until the editor is ready.
+     *
+     * Safe to mix with a controlled `[data]` input: the rendered document becomes
+     * the content baseline once the call lands, so a later `[data]` change back to
+     * the previous document still re-renders instead of being deduped against a
+     * baseline the editor no longer reflects. Recorded only on the resolved path —
+     * a failed render leaves the editor on its previous content.
+     * @param data - the document to render
+     */
     render(data) {
-        return this.instance()?.render(data);
+        const editor = this.instance();
+        if (editor === null) {
+            return undefined;
+        }
+        return editor.render(data).then(() => {
+            this.lastRenderedData = data;
+        });
     }
     constructor() {
         // Each effect reads `instance()` so it re-applies once the editor appears
@@ -2755,7 +3202,14 @@ class BlokEditorComponent {
                 this.lastRenderedData = data;
                 return;
             }
-            if (deepEqual(data, this.lastRenderedData)) {
+            // Structural comparison (`equalsOutputData`, not a raw deep-equal): a host
+            // that persists the editor's own document and hands back a stripped copy —
+            // fresh `time`, dropped ids, no `lastEditedAt` stamp — is still echoing
+            // content the editor already shows, and re-rendering it would reset the
+            // caret for zero visual change. `undefined` means "nothing recorded yet",
+            // which is NOT an empty document, so it must never match.
+            const baseline = this.lastRenderedData;
+            if (baseline !== undefined && equalsOutputData(data, baseline)) {
                 return;
             }
             this.lastRenderedData = data;
@@ -2895,6 +3349,76 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImpor
             }] } });
 
 // packages/angular/src/createAngularBlock.ts
+/** Statics the generated class owns; an authored `statics` bag can never take them over. */
+const RESERVED_STATICS = ['toolbox', 'isReadOnlySupported', '__isBlokAngularBlock'];
+/**
+ * Origins that mean "the author just made this block" — the only ones that fire
+ * {@link CreateAngularBlockSpec.onCreated}. Written as an allow-list so a future
+ * core origin fails CLOSED (no creation signal) instead of silently opting in.
+ *
+ * `undefined` is included because core always supplies an origin: an absent one
+ * means a host hand-built the constructor options, which is an explicit
+ * creation — the same reading core's own container tools apply.
+ *
+ * Note what is NOT the axis here: `origin === 'user'`. A container gated on that
+ * alone would refuse to seed for `api.blocks.insert('steps')` and for a
+ * turn-into, leaving an empty, unusable container.
+ */
+const CREATION_ORIGINS = new Set([
+    undefined,
+    'user',
+    'api',
+    'convert',
+]);
+/**
+ * Apply one pass of per-child holder attributes and clear the previous pass's
+ * leftovers — including on a child that has since left the container, which
+ * would otherwise keep a dead index forever.
+ * @param stamped - the container's ledger of what the last pass wrote (mutated)
+ * @param children - the container's model children, in model order
+ * @param decorate - the authored per-child decorator, if any
+ */
+const applyChildAttributes = (stamped, children, decorate) => {
+    const next = new Map();
+    children.forEach((child, index) => {
+        const names = [];
+        for (const [name, value] of Object.entries(decorate?.(child, index) ?? {})) {
+            if (value === null || value === undefined) {
+                child.holder.removeAttribute(name);
+                continue;
+            }
+            child.holder.setAttribute(name, String(value));
+            names.push(name);
+        }
+        next.set(child.id, { holder: child.holder, names });
+    });
+    for (const [id, previous] of stamped) {
+        const current = next.get(id);
+        previous.names
+            .filter(name => current === undefined || !current.names.includes(name))
+            .forEach(name => previous.holder.removeAttribute(name));
+    }
+    stamped.clear();
+    next.forEach((entry, id) => stamped.set(id, entry));
+};
+/**
+ * Announce that a container's child holders have settled in its slot — the
+ * signal a host waits on before putting the caret into a freshly inserted
+ * child.
+ *
+ * Optional-chained: the editor always supplies `events`, but a host unit test
+ * may hand a block a partial `api`, and an observability signal must never be
+ * able to break a render.
+ * @param api - the editor-level API
+ * @param blockId - the container block's id
+ * @param children - the container's model children, in model order
+ */
+const emitChildrenMounted = (api, blockId, children) => {
+    api?.events?.emit(BlockChildrenMounted, {
+        blockId,
+        childIds: children.map(child => child.id),
+    });
+};
 /**
  * Author a first-party Angular block. Returns a `BlockToolConstructable`
  * registered exactly like a vanilla tool (`tools: { type: { class:
@@ -2912,7 +3436,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImpor
  * - `removed()`/`destroy()` unregister the portal (deterministic unmount).
  */
 function createAngularBlock(spec) {
-    return class AngularBlockTool {
+    const AngularBlockTool = class AngularBlockTool {
         /** Marker so the directive can detect Angular-block tools and inject the registry. */
         static __isBlokAngularBlock = true;
         static get toolbox() {
@@ -2928,6 +3452,8 @@ function createAngularBlock(spec) {
             return true;
         }
         blockApi;
+        /** The editor-level API, handed to the component as `ctx.api`. */
+        api;
         registry;
         pointerDrag;
         dataSig;
@@ -2939,26 +3465,39 @@ function createAngularBlock(spec) {
         hostEl = null;
         /** Last host passed to ctx.mountChildren, re-mounted on each data change. */
         childHost = null;
+        /** Last per-child decorator passed to ctx.mountChildren; re-applied on each remount. */
+        childAttributes;
+        /** What the last decoration pass wrote, so a dropped key is cleaned up. */
+        stampedChildren = new Map();
+        /** Why core built this instance — gates `onCreated`, handed to `onMounted`. */
+        origin;
+        /** True once the post-mount hooks fired; a repeated rendered() must not re-fire them. */
+        mountSignalled = false;
         /** 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];
+            this.api = options.api;
             // 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;
+            const drag = options.api;
+            this.pointerDrag = () => drag?.blocks?.isPointerDragActive === true;
             this.mirror = fillDefaults(spec.propSchema, (options.data ?? {}));
             this.lastRendered = this.mirror;
             this.dataSig = signal(this.mirror, /* @ts-ignore */
             ...(ngDevMode ? [{ debugName: "dataSig" }] : /* istanbul ignore next */ []));
             this.readOnlySig = signal(options.readOnly, /* @ts-ignore */
             ...(ngDevMode ? [{ debugName: "readOnlySig" }] : /* istanbul ignore next */ []));
+            // Absent origin means a caller that predates the signal; 'api' is core's
+            // own default, so it is never mistaken for a user gesture.
+            this.origin = options.origin ?? 'api';
             this.ctx = {
                 data: this.dataSig.asReadonly(),
                 commit: this.commit,
                 block: this.blockApi,
+                api: this.api,
                 readOnly: this.readOnlySig.asReadonly(),
                 mountChildren: this.mountChildren,
             };
@@ -2978,6 +3517,25 @@ function createAngularBlock(spec) {
         }
         rendered() {
             spec.onRendered?.(this.blockApi);
+            // register() mounted the component and ran its first change detection
+            // synchronously inside render(), and core has now put the host in the
+            // document — so this is the settled moment. Once per instance: core
+            // re-runs rendered() for a re-materialised block, and a repeated creation
+            // signal would seed a container's default children twice. With no
+            // registry (vanilla core, no directive) nothing was ever mounted, so
+            // there is no settle to report — matching React/Vue, where the signal
+            // originates in the component itself.
+            if (this.registry === undefined || this.mountSignalled) {
+                return;
+            }
+            this.mountSignalled = true;
+            const context = { origin: this.origin, api: this.api };
+            spec.onMounted?.(this.blockApi, context);
+            // Creation-only, and after onMounted: a seeding hook must see whatever
+            // the mount hook already put in place.
+            if (CREATION_ORIGINS.has(this.origin)) {
+                spec.onCreated?.(this.blockApi, context);
+            }
         }
         save() {
             return this.mirror;
@@ -3012,29 +3570,55 @@ function createAngularBlock(spec) {
             this.readOnlySig.set(state);
             this.registry?.flush(this.blockApi.id);
         }
+        /**
+         * Core's toolbar-anchor hook. Always defined so the delegation is one
+         * `typeof … === 'function'` probe away, and always resolved fresh against
+         * the LIVE host — the anchor element is Angular-rendered, so it does not
+         * exist yet when the tool is constructed and may be replaced on any change
+         * detection pass. A spec without a resolver returns undefined, which is
+         * exactly what core's default positioning already assumes.
+         */
+        getToolbarAnchorElement() {
+            const host = this.hostEl;
+            if (host === null || spec.getToolbarAnchorElement === undefined) {
+                return undefined;
+            }
+            return spec.getToolbarAnchorElement(host, this.blockApi) ?? undefined;
+        }
         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);
+            // Ownership-scoped: core composes a REPLACEMENT block (which mounts under
+            // the SAME id) before it tears this one down, so an unqualified unregister
+            // here would destroy the live componentRef and blank the block.
+            this.registry?.unregister(this.blockApi.id, this.hostEl ?? undefined);
             spec.onRemoved?.(this.blockApi);
         }
         destroy() {
             // Idempotent with removed(); unregister is safe when already absent.
-            this.registry?.unregister(this.blockApi.id);
+            this.registry?.unregister(this.blockApi.id, this.hostEl ?? undefined);
         }
-        /** Container blocks: remember the host and (re)mount the real child holders. */
-        mountChildren = (host) => {
+        /**
+         * Container blocks: remember the host (and any per-child decorator) and
+         * (re)mount the real child holders.
+         */
+        mountChildren = (host, childAttributes) => {
             this.childHost = host;
+            this.childAttributes = childAttributes;
             host.setAttribute(DATA_ATTR.nestedBlocks, '');
             this.remountChildren();
         };
         remountChildren() {
-            if (this.childHost !== null) {
-                mountChildBlocks(this.childHost, this.blockApi.getChildren());
+            if (this.childHost === null) {
+                return;
             }
+            const children = this.blockApi.getChildren();
+            mountChildBlocks(this.childHost, children);
+            applyChildAttributes(this.stampedChildren, children, this.childAttributes);
+            emitChildrenMounted(this.api, this.blockApi.id, children);
         }
         /**
          * The only data write path. Merges the patch into the frozen mirror, swaps
@@ -3082,6 +3666,22 @@ function createAngularBlock(spec) {
             requestAnimationFrame(retry);
         }
     };
+    // Forward the authored statics onto the generated class. `defineProperty`
+    // (not assignment) because `toolbox`/`isReadOnlySupported` are accessors and a
+    // plain write would throw in strict mode; the reserved list keeps a stray bag
+    // from taking those — or the adapter's own marker — over.
+    for (const [key, value] of Object.entries(spec.statics ?? {})) {
+        if (RESERVED_STATICS.includes(key)) {
+            continue;
+        }
+        Object.defineProperty(AngularBlockTool, key, {
+            value,
+            writable: true,
+            enumerable: true,
+            configurable: true,
+        });
+    }
+    return AngularBlockTool;
 }
 
 // packages/angular/src/useBlocks.ts
@@ -3266,5 +3866,5 @@ function injectBlokReady(options = {}) {
  * Generated bundle index. Do not edit.
  */
 
-export { BLOK_BLOCK_CONTEXT, BLOK_DEFAULT_CONFIG, BlokContentDirective, BlokEditorComponent, createAngularBlock, injectBlocks, injectBlokReady, provideBlok };
+export { BLOK_BLOCK_CONTEXT, BLOK_DEFAULT_CONFIG, BLOK_EDITOR_INSTANCE, BlokContentDirective, BlokEditorComponent, createAngularBlock, injectBlocks, injectBlokInstance, injectBlokReady, provideBlok };
 //# sourceMappingURL=bloklabs-angular.mjs.map