@bloklabs/angular 1.16.0 → 2.0.0

package/types/bloklabs-angular.d.ts

@@ -1,7 +1,7 @@
 import * as i0 from "@angular/core";
-import { AfterViewInit, DoCheck, ElementRef, EnvironmentProviders, EventEmitter, InjectionToken, OnDestroy, Signal, Type } from "@angular/core";
+import { AfterViewInit, DoCheck, ElementRef, EnvironmentProviders, EventEmitter, InjectionToken, OnChanges, OnDestroy, Signal, SimpleChanges, Type } from "@angular/core";
 import { ControlValueAccessor } from "@angular/forms";
-import { API, BlockAPI, BlockMutationEvent, BlockOrigin, BlockPosition, BlockRenderedPayload, BlockToolConstructable, BlockToolConstructorOptions, BlockToolData, BlockTuneData, BlocksRenderedPayload, Blok, BlokConfig, EditorWidth, LooseOutputBlockData, LooseOutputData, MarkdownImportConfig, OutputBlockData, OutputData, ReadOnlyModeConfig, ResolvedTheme, ThemeMode, ToolboxConfig } from "@bloklabs/core";
+import { API, BlockAPI, BlockMutationEvent, BlockOrigin, BlockPosition, BlockRenderedPayload, BlockToolConstructable, BlockToolConstructorOptions, BlockToolData, BlockTuneData, BlocksRenderedPayload, Blok, BlokConfig, EditorWidth, LooseOutputData, MarkdownImportConfig, OutputBlockData, OutputData, ResolvedTheme, ThemeMode, ToolboxConfig } from "@bloklabs/core";
 /**
  * Configuration for the Angular adapter. Same as `BlokConfig` but without
  * `holder` (the adapter owns the host element), plus the reactive `width` prop.
@@ -364,12 +364,6 @@ export declare class BlokEditorComponent implements AfterViewInit, DoCheck, OnDe
     "blockRendered": "blockRendered";
   }, never, never, true, never>;
 }
-/**
- * The `collaboration` the given editor was constructed with.
- * @param editor - a Blok instance built by `BlokContentDirective`
- * @returns the mount-time collaboration config, `undefined` when there was none
- */
-declare function getConstructedCollaboration(editor: WeakKey): BlokAngularConfig['collaboration'];
 /**
  * Escape-hatch directive and lifecycle engine for Blok (mirrors React's
  * `useBlok` + `BlokContent`). Constructs a Blok instance into its own host
@@ -434,6 +428,29 @@ export declare class BlokContentDirective implements OnDestroy {
     "ready": "ready";
   }, never, never, true, never>;
 }
+/**
+ * Places the editor's page title in this element, through `editor.title.mount`.
+ * The editor needs `pageTitle` set; this only moves the title.
+ * On destroy the title goes back above the first block. Projected content is not rendered.
+ *
+ * ```html
+ * <blok-title [editor]="ed.instance()"></blok-title>
+ * <blok-editor #ed="blok" [config]="{ pageTitle: true }"></blok-editor>
+ * ```
+ */
+export declare class BlokTitleComponent implements OnChanges, OnDestroy {
+  private readonly host;
+  editor: Blok | null;
+  ngOnChanges(changes: SimpleChanges): void;
+  ngOnDestroy(): void;
+  static ɵfac: i0.ɵɵFactoryDeclaration<BlokTitleComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<BlokTitleComponent, "blok-title", never, {
+    "editor": {
+      "alias": "editor";
+      "required": false;
+    };
+  }, {}, never, never, true, never>;
+}
 /**
  * DI token holding app-wide Blok defaults (shared tools registry, default theme,
  * i18n). Merged under per-instance inputs by `BlokEditorComponent`.
@@ -512,6 +529,20 @@ interface InsertSpec {
    */
   caret?: CaretTarget;
 }
+/** Spec for {@link UseBlocksApi.create}. */
+interface CreateSpec {
+  type?: string;
+  data?: BlockToolData;
+  /** `null` is the root. Omitted: the `before`/`after` sibling's parent, or the root. */
+  parentId?: string | null;
+  /** Defaults to `'end'`. */
+  position?: InsertPosition;
+  id?: string;
+  tunes?: {
+    [name: string]: BlockTuneData;
+  };
+  focus?: boolean;
+}
 /**
  * One node of a pre-built nested subtree for {@link UseBlocksApi.insertTree}.
  *
@@ -618,7 +649,7 @@ interface UseBlocksApi {
    *
    * `config` (optional {@link MarkdownImportConfig}) is forwarded to the
    * converter so custom-tool consumers can map markdown nodes into their tools
-   * (`toolMap`/`onUnknownNode`), toggle GFM, or add micromark/mdast extensions.
+   * (`toolMap`/`onUnknownNode`) or toggle GFM.
    *
    * Returns ALL created {@link BlockNode}s in document order — including any the
    * markdown nested internally (e.g. a table's cell children), not just the
@@ -640,9 +671,12 @@ interface UseBlocksApi {
    * additive {@link insertMarkdown}). Async: the serializer is lazy-loaded, like
    * the importer. Markdown cannot express every block, so some structure is
    * dropped (table `colspan`/`rowspan`, heading columns). Returns `''` for an
-   * empty document. Pre-ready: resolves to `''`.
+   * empty document. Pre-ready: resolves to `''`. `title: true` writes the
+   * page title first, as core's does.
    */
-  exportMarkdown(): Promise<string>;
+  exportMarkdown(options?: {
+    title?: boolean;
+  }): Promise<string>;
   move(id: string, target: MoveTarget): void;
   nest(id: string, parentId: string): void;
   unnest(id: string): void;
@@ -761,6 +795,14 @@ interface UseBlocksApi {
    * dep array. Pre-ready: `null`.
    */
   insertInsideParent(parentId: string, insertIndex: number, childData?: BlockToolData): BlockNode | null;
+  /**
+   * Add a block the way a toolbox pick does, for a host button such as "New
+   * page" — delegates to core's `blocks.create`. Goes to the end of the root
+   * unless `parentId`/`position` say otherwise. Resolves `null` for an unknown
+   * tool or a place that does not exist; rejects with the tool's
+   * `prepareInsert` error, inserting nothing. Pre-ready: `null`.
+   */
+  create(spec?: CreateSpec): Promise<BlockNode | null>;
   /**
    * Replace the WHOLE document with blocks parsed from saved {@link OutputData}
    * (the `save()` shape) — delegates to core's `blocks.render`. Unlike
@@ -784,249 +826,6 @@ interface UseBlocksApi {
    */
   isSyncingFromYjs(): boolean;
 }
-/** The minimal slice of editor.blocks that the snapshot helpers read. */
-interface BlocksReader {
-  getBlocksCount(): number;
-  getBlockByIndex(index: number): {
-    id: string;
-    name: string;
-    parentId: string | null;
-  } | undefined;
-}
-/**
- * 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.
- */
-declare const snapshotNodes: (reader: BlocksReader) => BlockNode[];
-/** BlocksReader plus id→flat-index lookup. */
-interface IndexReader extends BlocksReader {
-  getBlockIndex(id: string): number | undefined;
-}
-/** Map of block id -> parentId, in flat order. */
-declare const parentMap: (reader: BlocksReader) => Map<string, string | null>;
-/** True if `id` descends from `ancestorId` via the parentId chain. */
-declare const isDescendantOf: (parentOf: Map<string, string | null>, id: string, ancestorId: string) => boolean;
-/**
- * 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.
- */
-declare const subtreeEndIndex: (reader: BlocksReader, index: number) => number;
-/**
- * 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.
- */
-declare const resolveInsertIndex: (reader: IndexReader, parentId: string | null, position: InsertPosition, replace?: boolean) => number;
-/** The flat toIndex for editor.blocks.move. */
-declare const resolveMoveIndex: (reader: IndexReader, target: MoveTarget) => number;
-/** Adapt the live editor to the IndexReader the snapshot helpers expect. */
-declare const readerFor: (editor: Blok) => IndexReader;
-/**
- * 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.
- */
-declare const EMPTY_API: UseBlocksApi;
-/**
- * Does a `block changed` event touch the subtree rooted at `withinId`?
- *
- * The reactivity filter behind `useBlocks(editor, { within })` in all three
- * adapters. Without it every consumer of `useBlocks` re-renders on every change
- * anywhere in the document — so a container block that only renders its own
- * children still re-rendered on each keystroke in an unrelated block, and a page
- * of N such containers turned one keystroke into N re-renders.
- *
- * INDETERMINATE READS AS "TOUCHED". The walk resolves ancestry through the LIVE
- * tree, and a removal commonly emits after the block is already gone, so its
- * parent chain cannot be read. Answering `false` there would leave a container
- * rendering a child that no longer exists; answering `true` costs one extra
- * render pass. Same for a payload with no readable target.
- *
- * Ancestry is walked UPWARD one `getById` at a time rather than snapshotted with
- * `parentMap`: this runs on every emission — i.e. on every keystroke — so it must
- * cost O(depth), not O(document).
- * @param editor - the live Blok instance
- * @param payload - the `block changed` payload
- * @param withinId - id of the block whose subtree is the scope
- * @returns true when the change is inside the scope (or cannot be placed)
- */
-declare const changeTouchesSubtree: (editor: Blok, payload: unknown, withinId: string) => boolean;
-/**
- * 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)
- */
-declare const createBlocksApiForEditor: (editor: Blok, onRead?: () => void) => UseBlocksApi;
-/**
- * Normalized shape of the `readOnly` config option
- */
-interface NormalizedReadOnlyConfig {
-  enabled: boolean;
-  hideControls: boolean;
-}
-/**
- * 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
- */
-declare function normalizeReadOnlyConfig(value: boolean | ReadOnlyModeConfig | undefined): NormalizedReadOnlyConfig;
-/**
- * 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
- */
-declare function deepEqual(a: unknown, b: unknown): boolean;
-type AnyOutputData = OutputData | LooseOutputData | null | undefined;
-/**
- * Options for {@link equalsOutputData}.
- */
-interface EqualsOutputDataOptions {
-  /**
-   * Ignore empty default blocks on both sides before comparing. A fresh editor
-   * always seeds one empty default paragraph, so a pristine document
-   * (`[{ type: 'paragraph', data: { text: '' } }]`) does not content-equal a
-   * saved-empty baseline (`[]`) by default. Turn this on for dirty-vs-baseline
-   * checks ("has the user actually typed anything?"): empty blocks of the
-   * default paragraph tool are dropped from both documents first, so pristine
-   * scaffolding and trailing empty lines don't register as a change. Empty
-   * NON-default blocks (a content-less divider, an empty image) are kept — they
-   * are meaningful content.
-   */
-  ignoreEmptyDefaultBlocks?: boolean;
-}
-/**
- * Structural equality for saved documents. Compares the `blocks` arrays
- * deeply; the volatile `time` and `version` envelope fields are ignored, so a
- * 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.
- * 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 —
- * see {@link EqualsOutputDataOptions}.
- * @param a - first document to compare
- * @param b - second document to compare
- * @param options - comparison options
- * @returns true when both documents hold structurally equal blocks
- */
-declare function equalsOutputData(a: AnyOutputData, b: AnyOutputData, options?: EqualsOutputDataOptions): boolean;
-/**
- * A bounded window of the editor's recently emitted `onSave` payloads, used by
- * the framework adapters to recognize controlled-`data` echoes. Deduping
- * against only the LAST emitted payload is not enough: a host that persists on
- * save and refetches can hand the adapter a STALE echo — an earlier save
- * arriving after a newer one already replaced the baseline — and re-rendering
- * it would clobber the caret and any content typed since. Matching is
- * structural ({@link equalsOutputData}), so envelopes reshaped in transit
- * (fresh `time`, stripped ids) still count as echoes.
- * @param capacity - number of payloads retained before the oldest is evicted
- * @returns the echo window
- */
-declare function createEmittedEchoWindow(capacity?: number): {
-  /** Records a payload the editor emitted via `onSave`. */
-  record(data: OutputData | LooseOutputData): void;
-  /** True when the document content-equals any recorded payload. */
-  matches(data: AnyOutputData): boolean;
-  /** Forgets all recorded payloads (external content took over). */
-  clear(): void;
-};
-/**
- * A shared, deeply frozen empty document. Consumers persisting editor content
- * repeatedly hand-write `{ blocks: [] }` for cleared/pristine baselines; this
- * is the canonical value to use instead. Frozen (blocks array included) so a
- * shared reference can never be mutated into a stale non-empty baseline.
- */
-declare const EMPTY_OUTPUT_DATA: OutputData;
-/**
- * Maps a controlled `data` value to something the editor's `render()` accepts.
- * A whole-document `null` — a controlled "clear to empty" — becomes
- * `{ blocks: [] }`; any real document passes through untouched.
- *
- * The framework adapters (React/Vue/Angular) route their reactive `data` path
- * through this so a `null` never reaches `render()`, whose strict guard reads
- * `data.blocks` and would throw on `null`. `undefined` (uncontrolled) is handled
- * by the adapters before this point, so it is intentionally not an input here.
- * @param data - a controlled document, or `null` for an empty document
- * @returns a document `render()` can consume
- */
-declare function toRenderableData(data: OutputData | LooseOutputData | null): OutputData | LooseOutputData;
-/**
- * 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, 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
- */
-declare function normalizeOutputBlocks(blocks: Array<OutputBlockData | LooseOutputBlockData>): OutputBlockData[];
-/**
- * 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 and a
- * non-empty `id` is kept; each
- * block is passed through {@link normalizeOutputBlocks}, so `null`/missing
- * `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`, 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
- */
-declare function normalizeOutputData(data: AnyOutputData): OutputData;
-/**
- * True when the document carries no user content: it is nullish, has no
- * blocks, or every block's data holds only empty values (see
- * {@link isEmptyValue}). Note that content-less visual blocks (e.g. a divider,
- * whose data is `{}`) count as empty — check `blocks.length` when mere block
- * presence matters.
- * @param data - document to inspect
- * @returns true when the document carries no user content
- */
-declare function isEmptyOutputData(data: AnyOutputData): boolean;
 /** One field of a block's prop schema. */
 interface PropSchemaEntry {
   /** Default value, used when the incoming data omits this key. */
@@ -1040,504 +839,6 @@ interface PropSchemaEntry {
  * written as its explicit default, never dropped).
  */
 type PropSchema = Record<string, PropSchemaEntry>;
-/**
- * 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.
- */
-declare const fillDefaults: <Data>(schema: PropSchema, data: Record<string, unknown>) => Readonly<Data>;
-/**
- * Every child slot carries one of these — first-party containers and every
- * adapter's `<BlockChildren>` alike. `BlockHierarchy` reads the same selector,
- * so the two sides agree on which blocks own a slot.
- */
-declare const CHILD_SLOT_SELECTOR = "[data-blok-toggle-children], [data-blok-nested-blocks]";
-/**
- * Parents that place their children themselves (per cell / per view). Their
- * descendants must never be pulled into an enclosing slot.
- */
-declare const SELF_PLACING_PARENTS: ReadonlySet<string>;
-/**
- * A slotless block renders its children as flat sibling holders right after
- * itself, in whatever slot holds the block — the same as nesting at root.
- * @param block - the block to test
- */
-declare const isSlotless: (block: {
-  holder: HTMLElement;
-  name?: string;
-}) => boolean;
-/**
- * The blocks a container slot hosts: its children, each followed by the
- * descendants of a slotless child (depth-first, flat order). A child that owns a
- * slot keeps its own descendants.
- * @param children - the container block's model children, in model order
- * @param getChildren - model children of a block, by id
- */
-declare const withSlotlessDescendants: <T extends {
-  holder: HTMLElement;
-  id?: string;
-  name?: string;
-}>(children: T[], getChildren: (id: string) => T[]) => T[];
-/**
- * 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 — 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)`).
- */
-declare const mountChildBlocks: (container: HTMLElement, children: {
-  holder: HTMLElement;
-}[]) => void;
-/**
- * One child's decoration: attribute name → value. `null`/`undefined` removes the
- * attribute; a boolean or number is stringified (so `false` writes
- * `data-active="false"`, which CSS can select, rather than dropping the hook).
- */
-type ChildAttributes$1 = Record<string, string | number | boolean | null | undefined>;
-/** The minimum a child must expose for a decoration pass. */
-interface DecoratableChild {
-  id: string;
-  holder: HTMLElement;
-}
-/**
- * A per-child decorator: what to write for the child at `index`.
- *
- * Generic over the child so an adapter can declare its decorators in terms of the
- * full `BlockAPI` its authors receive. A non-generic `(child: DecoratableChild)`
- * parameter would REJECT those: a function that demands a full BlockAPI is not
- * assignable to one promising to accept the structural minimum.
- */
-type ChildAttributesFn$1<Child extends DecoratableChild = DecoratableChild> = (child: Child, index: number) => ChildAttributes$1;
-/** What the previous decoration pass wrote for one child, so it can be undone. */
-interface StampedChild {
-  /** The element written to — a holder for one ledger, a content wrapper for the other. */
-  target: HTMLElement;
-  names: string[];
-}
-/** The ledgers a container keeps between passes; create one per child slot. */
-interface ChildDecorationLedger {
-  holders: Map<string, StampedChild>;
-  contents: Map<string, StampedChild>;
-}
-/**
- * A fresh pair of ledgers for one container's child slot.
- * @returns empty holder/content ledgers
- */
-declare const createChildDecorationLedger: () => ChildDecorationLedger;
-/**
- * Decorate a container's children: named attributes on each child's HOLDER and,
- * separately, on each child's `[data-blok-element-content]` wrapper.
- *
- * The single implementation behind the React, Vue and Angular per-child
- * decoration channels, so the three cannot drift on which element a hook lands
- * on or on when a dropped hook is cleaned up.
- *
- * BOTH levels exist because core's child-holder decoration law blesses both, and
- * a container needs both: the holder is the child's outer box (rails, indices,
- * hover states), while the content wrapper is where the child's own text box
- * begins — which is what a numbered rail or a connector line has to align to.
- * With only the holder reachable, a container had to encode core's wrapper chain
- * in its own CSS (`[data-step] > [data-blok-element-content] > …`) and broke
- * whenever that chain changed. Neither hook may introduce an element: holders
- * stay DIRECT children of the slot because core's reparenting and caret
- * sibling checks compare `holder.parentElement` by identity.
- *
- * Both are inert with respect to change tracking: core's mutation filter drops a
- * holder- or content-targeted attribute record for the CHILD block (both are
- * ancestors of the child's tool element, not descendants) and scores it
- * mutation-free for the CONTAINER (whose own `data-blok-mutation-free` host is
- * the nearest such ancestor).
- * @param ledger - the slot's ledgers from {@link createChildDecorationLedger}
- * @param children - the container's model children, in model order
- * @param decorators - the authored per-child decorators
- * @param decorators.childAttributes - written on each child's holder
- * @param decorators.childContentAttributes - written on each child's content wrapper
- */
-declare const applyChildDecoration: <Child extends DecoratableChild>(ledger: ChildDecorationLedger, children: Child[], decorators: {
-  childAttributes?: ChildAttributesFn$1<Child>;
-  childContentAttributes?: ChildAttributesFn$1<Child>;
-}) => void;
-/**
- * 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.
- */
-declare const DATA_ATTR: {
-  /** Interface type identifier (blok, inline-toolbar, tooltip) */
-  readonly interface: "data-blok-interface";
-  /** Block element wrapper */
-  readonly element: "data-blok-element";
-  /** Block element content wrapper */
-  readonly elementContent: "data-blok-element-content";
-  /** Editor wrapper container */
-  readonly 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. */
-  readonly instance: "data-blok-instance";
-  /** Redactor zone */
-  readonly 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). */
-  readonly rendered: "data-blok-rendered";
-  /** Present on the editor wrapper while the loading skeleton owns it.
-   *  Public styling hook. */
-  readonly loading: "data-blok-loading";
-  /** The loading skeleton overlay (a wrapper child, never inside the redactor). */
-  readonly loadingSkeleton: "data-blok-loading-skeleton";
-  /** One skeleton row; the value is its kind: heading | paragraph | list. */
-  readonly skeletonBar: "data-blok-skeleton-bar";
-  /** Blok version number stamped on the editor wrapper (e.g. '1.10.0', 'dev').
-   *  Consumed by browser extensions to identify the running version. */
-  readonly version: "data-blok-version";
-  /** Block unique identifier */
-  readonly id: "data-blok-id";
-  readonly pageId: "data-blok-page-id";
-  /** Block component/tool type */
-  readonly component: "data-blok-component";
-  /** Tool type attribute */
-  readonly tool: "data-blok-tool";
-  readonly blockContextMenu: "data-blok-block-context-menu";
-  /** Block nesting depth (derived from the parentId chain) */
-  readonly depth: "data-blok-depth";
-  /** Flat list-nesting indentation level (0 = root); tool-agnostic, mirrors list depth */
-  readonly indent: "data-blok-indent";
-  /** Header tool's heading level (1-6). Public styling hook — keyed by level rather
-   *  than by tag name, so a level remapped to a custom tag via `levelOverrides[n].tag`
-   *  (types/tools/header.d.ts) still matches its level's typography rules. */
-  readonly headingLevel: "data-blok-heading-level";
-  /** Element is hidden from view */
-  readonly hidden: "data-blok-hidden";
-  /** Element is disabled and non-interactive */
-  readonly disabled: "data-blok-disabled";
-  /** Element is focused via keyboard navigation */
-  readonly focused: "data-blok-focused";
-  /** On a popover once a navigation key moved its cursor; gates the focus ring */
-  readonly keyboardNavigated: "data-blok-keyboard-navigated";
-  /** Block is selected */
-  readonly selected: "data-blok-selected";
-  /** On a block's spotlight target while it is being pointed out (Show in the failed-image notice) */
-  readonly spotlight: "data-blok-spotlight";
-  /** Marks the element inside a block that Show points at, e.g. the image's error card */
-  readonly spotlightTarget: "data-blok-spotlight-target";
-  /** Marks the control inside a spotlight target that receives focus, e.g. Retry */
-  readonly spotlightFocus: "data-blok-spotlight-focus";
-  /** Block is stretched */
-  readonly stretched: "data-blok-stretched";
-  /** Editor or element is empty */
-  readonly empty: "data-blok-empty";
-  /** Present on the editor wrapper while read-only mode is active.
-   *  Public styling hook — lets hosts key rules off the editing state
-   *  without JS. Deliberately does NOT collapse the gutter: plain
-   *  read-only still shows the block-hover copy-link control there, and
-   *  in-place readOnly.set() flips must not shift the layout. */
-  readonly readonly: "data-blok-readonly";
-  /** Present on the editor wrapper while read-only mode hides ALL editor
-   *  controls (readOnly: { hideControls: true }). Public styling hook —
-   *  drives the gutter auto-collapse for genuinely chromeless read-only. */
-  readonly controlsHidden: "data-blok-controls-hidden";
-  /** Present on the editor wrapper when config.hideToolbar is true.
-   *  Public styling hook — drives the gutter auto-collapse (the gutter
-   *  exists solely to house the toolbar's +/⠿ controls). */
-  readonly toolbarHidden: "data-blok-toolbar-hidden";
-  /** Which gutter the floating block controls occupy: 'left' (default,
-   *  inline-start) or 'right' (inline-end). Written on the editor wrapper from
-   *  config.toolbarPosition and kept in sync by `toolbar.setPosition()`.
-   *  Public styling hook — drives the gutter swap and the actions-bar side. */
-  readonly toolbarPosition: "data-blok-toolbar-position";
-  /** Content alignment mode (left, center, right) */
-  readonly contentAlign: "data-blok-content-align";
-  /** Right-to-left mode */
-  readonly rtl: "data-blok-rtl";
-  /** Editor content width mode (present with value "full" for wide mode; absent = narrow) */
-  readonly width: "data-blok-width";
-  /** Present on the editor wrapper when config.style.nativeSelection is true.
-   *  Public styling hook — disables Blok's ::selection repaint (preflight.css)
-   *  and re-points the fake-background highlight at the UA Highlight color
-   *  (colors.css), so selection falls back to native/host-defined colors. */
-  readonly nativeSelection: "data-blok-native-selection";
-  /** Present on the editor wrapper while a cross-block TEXT selection is painted.
-   *  Suppresses the engine's own ::selection paint (main.css) so the
-   *  ::highlight() sub-ranges are the only thing drawn — Chromium and Firefox
-   *  paint such a range natively too and would otherwise double it up. */
-  readonly crossSelection: "data-blok-cross-selection";
-  /** Block is being dragged */
-  readonly dragging: "data-blok-dragging";
-  /** Multiple blocks being dragged */
-  readonly draggingMulti: "data-blok-dragging-multi";
-  /** Block is being duplicated (Alt+drag) */
-  readonly duplicating: "data-blok-duplicating";
-  /** Drag handle element */
-  readonly dragHandle: "data-blok-drag-handle";
-  /** Toolbar element */
-  readonly toolbar: "data-blok-toolbar";
-  /** The floating block-controls bar (plus button + drag/settings handle)
-   *  inside the toolbar. Public styling hook — the side it docks to is driven
-   *  from the wrapper's `data-blok-toolbar-position`. */
-  readonly toolbarActions: "data-blok-toolbar-actions";
-  /** Settings toggler button */
-  readonly settingsToggler: "data-blok-settings-toggler";
-  /** Toolbox is open */
-  readonly toolboxOpened: "data-blok-toolbox-opened";
-  /** Block settings is open */
-  readonly blockSettingsOpened: "data-blok-block-settings-opened";
-  /** Element is opened (generic) */
-  readonly opened: "data-blok-opened";
-  /** Root popover element */
-  readonly popover: "data-blok-popover";
-  /** Popover container wrapper */
-  readonly popoverContainer: "data-blok-popover-container";
-  /** Popover items list */
-  readonly popoverItems: "data-blok-popover-items";
-  /** Custom, engine-independent scrollbar thumb overlaid on the popover items */
-  readonly popoverScrollbar: "data-blok-popover-scrollbar";
-  /** Stamped on the custom scrollbar thumb while it is being dragged (keeps it revealed) */
-  readonly popoverScrollbarDragging: "data-blok-dragging";
-  /** Stamped on a scroll container while it is actively scrolling (reveals the auto-hidden scrollbar thumb) */
-  readonly scrolling: "data-blok-scrolling";
-  /** Popover overlay element */
-  readonly popoverOverlay: "data-blok-popover-overlay";
-  /** Popover custom content area */
-  readonly popoverCustomContent: "data-blok-popover-custom-content";
-  /** Popover custom class */
-  readonly popoverCustomClass: "data-blok-popover-custom-class";
-  /** Inline popover variant */
-  readonly popoverInline: "data-blok-popover-inline";
-  /** Popover is open */
-  readonly popoverOpened: "data-blok-popover-opened";
-  /** Popover opens upward */
-  readonly popoverOpenTop: "data-blok-popover-open-top";
-  /** Popover opens leftward */
-  readonly popoverOpenLeft: "data-blok-popover-open-left";
-  /** Nested popover indicator */
-  readonly nested: "data-blok-nested";
-  /** Nesting level value */
-  readonly nestedLevel: "data-blok-nested-level";
-  /** Group label for promoted search results from nested children */
-  readonly promotedGroupLabel: "data-blok-promoted-group-label";
-  /** A nested child shown in the host menu's search results. The convert-menu styles skip it, so the host keeps its own layout. */
-  readonly promotedItem: "data-blok-promoted-item";
-  /** Group label for top-level matches in search results */
-  readonly topLevelGroupLabel: "data-blok-top-level-group-label";
-  /** Header container */
-  readonly popoverHeader: "data-blok-popover-header";
-  /** Header text element */
-  readonly popoverHeaderText: "data-blok-popover-header-text";
-  /** Back button in nested popover */
-  readonly popoverHeaderBackButton: "data-blok-popover-header-back-button";
-  /** Item container */
-  readonly popoverItem: "data-blok-popover-item";
-  /** Item icon wrapper */
-  readonly popoverItemIcon: "data-blok-popover-item-icon";
-  /** Chevron icon for nested items */
-  readonly popoverItemIconChevronRight: "data-blok-popover-item-icon-chevron-right";
-  /** Item title text */
-  readonly popoverItemTitle: "data-blok-popover-item-title";
-  /** Item secondary title */
-  readonly popoverItemSecondaryTitle: "data-blok-popover-item-secondary-title";
-  /** Item is active/selected */
-  readonly popoverItemActive: "data-blok-popover-item-active";
-  /** Item's child menu is currently open — keeps the trigger looking selected */
-  readonly popoverItemChildrenOpen: "data-blok-popover-item-children-open";
-  /** Confirmation state */
-  readonly popoverItemConfirmation: "data-blok-popover-item-confirmation";
-  /** Disable hover styling */
-  readonly popoverItemNoHover: "data-blok-popover-item-no-hover";
-  /** Disable focus handling */
-  readonly popoverItemNoFocus: "data-blok-popover-item-no-focus";
-  /** Destructive action item (e.g. delete) */
-  readonly popoverItemDestructive: "data-blok-popover-item-destructive";
-  /** Separator item */
-  readonly popoverItemSeparator: "data-blok-popover-item-separator";
-  /** Separator line element */
-  readonly popoverItemSeparatorLine: "data-blok-popover-item-separator-line";
-  /** HTML-based item */
-  readonly popoverItemHtml: "data-blok-popover-item-html";
-  /** Item has child menu */
-  readonly hasChildren: "data-blok-has-children";
-  /** Item name identifier */
-  readonly itemName: "data-blok-item-name";
-  /** No search results shown */
-  readonly nothingFoundDisplayed: "data-blok-nothing-found-displayed";
-  /** Selection overlay */
-  readonly overlay: "data-blok-overlay";
-  /** Overlay container */
-  readonly overlayContainer: "data-blok-overlay-container";
-  /** Selection rectangle */
-  readonly overlayRectangle: "data-blok-overlay-rectangle";
-  /** Overlay is hidden */
-  readonly overlayHidden: "data-blok-overlay-hidden";
-  /** Fake cursor indicator */
-  readonly fakeCursor: "data-blok-fake-cursor";
-  /** Fake background for selection */
-  readonly fakeBackground: "data-blok-fake-background";
-  /** Auto-scroll zone (top/bottom) */
-  readonly scrollZone: "data-blok-scroll-zone";
-  /** Scroll is locked */
-  readonly scrollLocked: "data-blok-scroll-locked";
-  /** Hard scroll lock */
-  readonly scrollLockedHard: "data-blok-scroll-locked-hard";
-  /** Shadow caret element */
-  readonly shadowCaret: "data-blok-shadow-caret";
-  /** Placeholder text */
-  readonly placeholder: "data-blok-placeholder";
-  /** Active placeholder text */
-  readonly placeholderActive: "data-blok-placeholder-active";
-  /** 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`. */
-  readonly columns: "data-blok-columns";
-  /** A single column inside a columns row. */
-  readonly column: "data-blok-column";
-  /** Drag-to-resize separator between two adjacent columns. Present only in
-   *  edit mode — the separators ARE the gutter there. */
-  readonly 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. */
-  readonly columnsStaticGutter: "data-blok-columns-static-gutter";
-  /** 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. */
-  readonly nestedBlocks: "data-blok-nested-blocks";
-  /** A drop zone. Empty value: an empty container's placeholder (an empty
-   *  tab); while the block's own holder shows one without the `hidden` class,
-   *  a drop on the block nests the dragged blocks as its first children.
-   *  A block id (a tab pill): a drop on the zone appends the dragged blocks
-   *  as the LAST children of that block. */
-  readonly dropInto: "data-blok-drop-into";
-  /** Set by core on a named drop zone while it is the drop target. */
-  readonly dropIntoActive: "data-blok-drop-into-active";
-  /** A container's empty-state hint that stands in for its first child block
-   *  (empty tab, empty toggle body). It is not a block, so hovering or pressing
-   *  it shows no block toolbar; the block a click creates gets its own. */
-  readonly childStandIn: "data-blok-child-stand-in";
-  /** Element excluded from mutation tracking */
-  readonly mutationFree: "data-blok-mutation-free";
-  /** Tool UI inside a block that is not the user's content (a list marker, a
-   *  checkbox, a code block's language button and line numbers). `Block.isEmpty`
-   *  and the block's copied HTML skip it. Never put it on an element that holds
-   *  child blocks or the user's text: that content would be skipped too. */
-  readonly chrome: "data-blok-chrome";
-  /** Marks a subtree whose keyboard belongs to the Tool that rendered it, not to
-   *  the editor. Blok's block-level keydown/keyup handling stands down entirely
-   *  for events originating inside it — Escape, Tab, the arrows, "/" and the
-   *  Enter/Backspace/Delete structural keys all reach the element untouched.
-   *
-   *  Blok already exempts native `<input>`/`<textarea>` from the STRUCTURAL keys
-   *  (Enter/Backspace/Delete and "/") because those are contenteditable-shaped
-   *  and would splice the document around a form field. Escape/Tab/arrows are
-   *  deliberately NOT exempt — they are how a user leaves a field. That default
-   *  is right for a one-line title input and wrong for a field with its own
-   *  keyboard semantics (Tab between sub-fields, Escape to cancel an edit, arrows
-   *  to walk a suggestion list), which is exactly what this attribute is for.
-   *  Public authoring hook. */
-  readonly keyboardOwner: "data-blok-keyboard-owner";
-  /** Marks a subtree whose links belong to the tool: Blok's link hover card
-   *  and link-click navigation stand down inside it. For a link the tool opens
-   *  and previews itself (the page block). Public authoring hook. */
-  readonly linkOwner: "data-blok-link-owner";
-  /** Block has navigation focus */
-  readonly navigationFocused: "data-blok-navigation-focused";
-  /** Flipper navigation target */
-  readonly flipperNavigationTarget: "data-blok-flipper-navigation-target";
-  /** Inline toolbar enabled on external element */
-  readonly inlineToolbar: "data-blok-inline-toolbar";
-  /** Link tool is active */
-  readonly linkToolActive: "data-blok-link-tool-active";
-  /** Link tool unlink mode */
-  readonly linkToolUnlink: "data-blok-link-tool-unlink";
-  /** Link tool input is opened */
-  readonly linkToolInputOpened: "data-blok-link-tool-input-opened";
-  /** Bold collapsed length tracking */
-  readonly boldCollapsedLength: "data-blok-bold-collapsed-length";
-  /** Bold collapsed active state */
-  readonly boldCollapsedActive: "data-blok-bold-collapsed-active";
-  /** Bold previous length tracking */
-  readonly boldPrevLength: "data-blok-bold-prev-length";
-  /** Bold leading whitespace */
-  readonly boldLeadingWs: "data-blok-bold-leading-ws";
-  /** Bold marker */
-  readonly boldMarker: "data-blok-bold-marker";
-  /** Tooltip is shown */
-  readonly shown: "data-blok-shown";
-  /** Tooltip placement */
-  readonly placement: "data-blok-placement";
-  /** Bounce in animation */
-  readonly bounceIn: "data-blok-bounce-in";
-  /** Live region announcer */
-  readonly announcer: "data-blok-announcer";
-  /** Stub block element */
-  readonly stub: "data-blok-stub";
-  /** Stub info section */
-  readonly stubInfo: "data-blok-stub-info";
-  /** Stub title */
-  readonly stubTitle: "data-blok-stub-title";
-  /** Stub subtitle */
-  readonly stubSubtitle: "data-blok-stub-subtitle";
-  /** Slash search active on content editable */
-  readonly slashSearch: "data-blok-slash-search";
-  /** Test identifier (for E2E tests) */
-  readonly testid: "data-blok-testid";
-  /** Force hover state (for tests/storybook) */
-  readonly forceHover: "data-blok-force-hover";
-};
-/**
- * Type for DATA_ATTR keys
- */
-type DataAttrKey = keyof typeof DATA_ATTR;
-/**
- * Type for DATA_ATTR values
- */
-type DataAttrValue = (typeof DATA_ATTR)[DataAttrKey];
-/**
- * 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"]'
- */
-declare const createSelector: (attr: DataAttrValue, value?: string | boolean) => string;
-/**
- * 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`.
- */
-declare const BlockChildrenMounted = "block:childrenMounted";
 /**
  * Every STATIC member of core's block-tool contract an Angular block may declare
  * for itself — `ownsChildren`, `keepsChildrenOnEnter`, `conversionConfig`,
@@ -1623,6 +924,19 @@ interface CreateAngularBlockSpec<Data = BlockToolData> {
    * @param block - this block's per-block API
    */
   onNavigationEnter?: (event: KeyboardEvent, block: BlockAPI) => boolean;
+  /**
+   * Core's `isReadOnly` hook: true when this block takes no edits from the
+   * user or an agent while the editor stays editable (no delete, move, merge,
+   * nesting or undo into it). Asked on each gesture; a throw counts as true.
+   * @param block - this block's per-block API
+   */
+  isReadOnly?: (block: BlockAPI) => boolean;
+  /**
+   * Core's `isDataReadOnly` hook: true when only this block's own data is
+   * frozen and its children stay open. A throw counts as true.
+   * @param block - this block's per-block API
+   */
+  isDataReadOnly?: (block: BlockAPI) => boolean;
   /** Optional lifecycle callbacks mapped from Blok's block hooks. */
   onRendered?: (block: BlockAPI) => void;
   /**
@@ -1676,7 +990,10 @@ interface CreateAngularBlockSpec<Data = BlockToolData> {
    */
   onCreated?: (block: BlockAPI, context: AngularBlockMountedContext) => void;
   onMoved?: (block: BlockAPI) => void;
-  onRemoved?: (block: BlockAPI) => void;
+  /** `removal.deleted` is true when a local edit deleted the block (see BlockTool.removed). */
+  onRemoved?: (block: BlockAPI, removal?: {
+    deleted: boolean;
+  }) => void;
 }
 /**
  * Author a first-party Angular block. Returns a `BlockToolConstructable`
@@ -1701,9 +1018,13 @@ export declare function createAngularBlock<Data = BlockToolData>(spec: CreateAng
   setReadOnly(state: boolean): void;
   getToolbarAnchorElement(): HTMLElement | undefined;
   onNavigationEnter(event: KeyboardEvent): boolean;
+  isReadOnly(): boolean;
+  isDataReadOnly(): boolean;
   rendered(): void;
   moved(): void;
-  removed(): void;
+  removed(removal?: {
+    deleted: boolean;
+  }): void;
   destroy(): void;
 }) & BlockToolStatics & {
   readonly __isBlokAngularBlock: true;
@@ -1935,4 +1256,4 @@ export declare const BLOK_EDITOR_INSTANCE: InjectionToken<Signal<Blok | null>>;
  * Outside an editor it returns a signal of null.
  */
 export declare function injectBlokInstance(): Signal<Blok | null>;
-export type { AngularBlockMountedContext, AngularBlockRenderContext, BlockNode, BlockToolStatics, BlokAngularConfig, BlokReadyScope, CaretTarget, ChildAttributes, ChildAttributesFn, CreateAngularBlockSpec, InjectBlocksOptions, InjectBlokReadyOptions, InsertPosition, InsertSpec, MoveTarget, PropSchema, PropSchemaEntry, TreeInsertSpec, UseBlocksApi };
+export type { AngularBlockMountedContext, AngularBlockRenderContext, BlockNode, BlockToolStatics, BlokAngularConfig, BlokReadyScope, CaretTarget, ChildAttributes, ChildAttributesFn, CreateAngularBlockSpec, CreateSpec, InjectBlocksOptions, InjectBlokReadyOptions, InsertPosition, InsertSpec, MoveTarget, PropSchema, PropSchemaEntry, TreeInsertSpec, UseBlocksApi };