@bloklabs/angular 1.2.6 → 1.4.0

package/types/bloklabs-angular.d.ts

@@ -0,0 +1,752 @@
+import * as i0 from '@angular/core';
+import { AfterViewInit, EventEmitter, OnDestroy, InjectionToken, EnvironmentProviders, Type, Signal, ElementRef } from '@angular/core';
+import { ControlValueAccessor } from '@angular/forms';
+import { BlokConfig, EditorWidth, Blok, OutputData, API, BlockMutationEvent, ResolvedTheme, BlocksRenderedPayload, BlockRenderedPayload, OutputBlockData, ThemeMode, LooseOutputData, BlockToolData, BlockTuneData, MarkdownImportConfig, ToolboxConfig, BlockAPI, BlockToolConstructorOptions } 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.
+ * Mirrors the React adapter's `UseBlokConfig`.
+ */
+type BlokAngularConfig = Omit<BlokConfig, 'holder'> & {
+    /** Editor content width mode. Synced reactively after mount via `editor.width.set()`. */
+    width?: EditorWidth;
+};
+
+/**
+ * The blessed all-in-one Angular component for embedding Blok (mirrors React's
+ * `BlokEditor`). Delegates instance lifecycle to an internal `BlokContentDirective`
+ * and layers the typed reactive input/output API on top.
+ *
+ * Reactive inputs (`readOnly`, `hideToolbar`, `inlineToolbar`, `theme`,
+ * `width`, `placeholder`, `autofocus`, `styleTokens`, `i18n`, `data`) are
+ * synced in place after mount via effects — `hideToolbar` through
+ * `editor.toolbar.setHidden()`, `inlineToolbar` through
+ * `editor.tools.setInlineToolbar()` (content-compared),
+ * `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.
+ *
+ * Implementation note: classic `@Input()`/`@ViewChild()` decorators are used
+ * (not signal `input()`/`viewChild()`) for JIT compatibility — see
+ * `BlokContentDirective`. Each reactive input is backed by an internal `signal`
+ * so effect-based syncing still works; the public template API is unchanged.
+ */
+declare class BlokEditorComponent implements AfterViewInit, ControlValueAccessor {
+    private readonly ngZone;
+    /** App-wide defaults from `provideBlok()`; merged UNDER per-instance inputs. */
+    private readonly defaults;
+    private contentQuery?;
+    /** Signal bridge for the @ViewChild directive so effects react to its arrival. */
+    private readonly content;
+    /**
+     * Output half of two-way `[(data)]`. Emits the editor's serialized content on
+     * every change. Wiring the core `onSave` callback is gated on this being
+     * observed, since its mere presence makes the core serialize on every batch.
+     */
+    /** Emits the live Blok instance once ready, after `instance()` is populated. */
+    readonly ready: EventEmitter<Blok>;
+    readonly dataChange: EventEmitter<OutputData>;
+    /** Fires with the full serialized content on every change (notification half). */
+    readonly save: EventEmitter<OutputData>;
+    /** Raw block mutation channel (core `onChange`). */
+    readonly change: EventEmitter<{
+        api: API;
+        event: BlockMutationEvent | BlockMutationEvent[];
+    }>;
+    /** Fires after the editor finishes (re-)rendering (core `onAfterRender`). */
+    readonly afterRender: EventEmitter<API>;
+    /** Fires with the resolved theme whenever it changes (core `onThemeChange`). */
+    readonly themeChange: EventEmitter<ResolvedTheme>;
+    /** Fires after a batch render completes (core `blocks:rendered` event). */
+    readonly blocksRendered: EventEmitter<BlocksRenderedPayload>;
+    /** Fires for each block rendered into the DOM (core `block:rendered` event). */
+    readonly blockRendered: EventEmitter<BlockRenderedPayload>;
+    /**
+     * Transform hook applied to blocks before render (core `onBeforeRender`). Must
+     * return the (possibly modified) block list. An input, not an output, because
+     * it returns a value.
+     */
+    onBeforeRender?: (blocks: OutputBlockData[]) => OutputBlockData[];
+    /**
+     * Transform hook applied to pasted HTML (core `onBeforePaste`). Returns the
+     * (possibly modified) html, or null to drop the paste.
+     */
+    onBeforePaste?: (html: string) => string | null;
+    private readonly readOnly$;
+    set readOnly(value: BlokConfig['readOnly'] | undefined);
+    private readonly hideToolbar$;
+    set hideToolbar(value: boolean | undefined);
+    private readonly inlineToolbar$;
+    set inlineToolbar(value: boolean | string[] | undefined);
+    private readonly theme$;
+    set theme(value: ThemeMode | undefined);
+    private readonly width$;
+    set width(value: EditorWidth | undefined);
+    private readonly placeholder$;
+    set placeholder(value: string | false | undefined);
+    /**
+     * Theme tokens. Construction-only config forced hosts with a live light/dark
+     * toggle to recreate the editor or hand-write the global stylesheet Blok
+     * already injects; this drives the runtime `tokens` API instead.
+     */
+    private readonly styleTokens$;
+    set styleTokens(value: Record<string, string> | undefined);
+    /**
+     * Locale, host message overrides and text direction. `config.i18n` was
+     * consumed once at boot, so a host driving a language switcher had to
+     * recreate the editor (losing caret, focus and undo stack) to relabel the
+     * UI; this drives the runtime `i18n.update` API instead. `defaultLocale` is
+     * not forwarded — it only affects the INITIAL locale resolution.
+     */
+    private readonly i18n$;
+    set i18n(value: BlokConfig['i18n'] | undefined);
+    private readonly autofocus$;
+    set autofocus(value: boolean | undefined);
+    private readonly data$;
+    set data(value: OutputData | LooseOutputData | undefined);
+    tools?: BlokConfig['tools'];
+    /**
+     * Escape hatch: a full config object for keys without a dedicated input
+     * (sanitizer, minHeight, …). Layered between provideBlok
+     * defaults and the discrete inputs.
+     */
+    config?: Partial<BlokAngularConfig>;
+    /** Changing this input's identity destroys and recreates the editor (≙ React `deps`). */
+    recreateKey: unknown;
+    /**
+     * 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`.
+     */
+    private lastRenderedData?;
+    /** Last token set pushed through `tokens.set`, for deep-equal deduping. */
+    private appliedTokens?;
+    /** Last i18n config pushed through `i18n.update`, for deep-equal deduping. */
+    private appliedI18n?;
+    /** Editor instance the i18n baseline above belongs to. */
+    private i18nAppliedFor;
+    /** Last value pushed through `tools.setInlineToolbar`, for content-compare deduping. */
+    private appliedInlineToolbar?;
+    private seededEditor;
+    private renderChain;
+    /** Registered by `ControlValueAccessor.registerOnChange` (Angular forms). */
+    private cvaOnChange?;
+    private cvaOnTouched?;
+    /**
+     * Core `onSave` wrapper. Records the editor's own serialized output as the
+     * rendered baseline BEFORE notifying Angular, so a controlled consumer echoing
+     * it straight back into `data` deep-equals the baseline and is deduped to a
+     * no-op (no redundant render, no caret reset). Re-enters the Angular zone since
+     * the editor runs outside it.
+     */
+    private readonly coreOnSave;
+    /** Live Blok instance, or null until `isReady` resolves / after destroy. */
+    readonly instance: i0.Signal<Blok | null>;
+    /** Guards `ready` to one emission per editor instance. */
+    private lastReadyInstance;
+    /**
+     * Construction config handed to the directive. Seeds the editor's initial
+     * values; the directive only reads it once (at construction), so post-mount
+     * changes to construction-only inputs are no-ops by design.
+     */
+    buildConfig(): Partial<BlokAngularConfig>;
+    ngAfterViewInit(): void;
+    /** Serialize the current content. Resolves undefined until the editor is ready. */
+    save$(): Promise<OutputData> | undefined;
+    /** Move the caret into the editor. */
+    focus(atEnd?: boolean): void;
+    /** Replace the editor content. Resolves undefined until the editor is ready. */
+    render(data: OutputData | LooseOutputData): Promise<void> | undefined;
+    constructor();
+    /** Seeds/renders an externally-set form value through the same dedup machinery. */
+    writeValue(value: OutputData | LooseOutputData | null): void;
+    registerOnChange(fn: (data: OutputData) => void): void;
+    registerOnTouched(fn: () => void): void;
+    /** Form disabled state maps to the editor's read-only mode (via the readOnly effect). */
+    setDisabledState(isDisabled: boolean): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<BlokEditorComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<BlokEditorComponent, "blok-editor", ["blok"], { "onBeforeRender": { "alias": "onBeforeRender"; "required": false; }; "onBeforePaste": { "alias": "onBeforePaste"; "required": false; }; "readOnly": { "alias": "readOnly"; "required": false; }; "hideToolbar": { "alias": "hideToolbar"; "required": false; }; "inlineToolbar": { "alias": "inlineToolbar"; "required": false; }; "theme": { "alias": "theme"; "required": false; }; "width": { "alias": "width"; "required": false; }; "placeholder": { "alias": "placeholder"; "required": false; }; "styleTokens": { "alias": "styleTokens"; "required": false; }; "i18n": { "alias": "i18n"; "required": false; }; "autofocus": { "alias": "autofocus"; "required": false; }; "data": { "alias": "data"; "required": false; }; "tools": { "alias": "tools"; "required": false; }; "config": { "alias": "config"; "required": false; }; "recreateKey": { "alias": "recreateKey"; "required": false; }; }, { "ready": "ready"; "dataChange": "dataChange"; "save": "save"; "change": "change"; "afterRender": "afterRender"; "themeChange": "themeChange"; "blocksRendered": "blocksRendered"; "blockRendered": "blockRendered"; }, never, never, true, never>;
+}
+
+/**
+ * Escape-hatch directive and lifecycle engine for Blok (mirrors React's
+ * `useBlok` + `BlokContent`). Constructs a Blok instance into its own host
+ * element and tears it down on destroy.
+ *
+ * The editor renders directly into the directive's host element — so the host
+ * IS the holder. This sidesteps the fact that Blok core exposes no public
+ * `holder` accessor: the adapter never has to read it back, it owns it.
+ *
+ * `BlokEditorComponent` applies this directive to its internal `<div>` and reads
+ * the instance back; consumers can also use it directly for full control:
+ * `<div blokContent [config]="cfg" (ready)="onReady($event)"></div>`.
+ *
+ * Implementation note: classic `@Input()`/`@Output()` are used (not signal
+ * `input()`/`output()`) because the repo's Vitest+Analog harness compiles the
+ * adapter via JIT, which does not register signal-based members. `instance`
+ * remains a plain `signal` (runtime API, JIT-safe) for reactive consumption.
+ */
+declare class BlokContentDirective implements OnDestroy {
+    private readonly host;
+    private readonly ngZone;
+    private readonly isBrowser;
+    /**
+     * App-wide defaults from `provideBlok()`, merged UNDER the bound `[config]` so
+     * the escape-hatch path honors them just like `<blok-editor>` (which also
+     * merges, idempotently). Mirrors React's `useBlok` merging context defaults.
+     */
+    private readonly defaults;
+    private readonly envInjector;
+    private readonly appRef;
+    private readonly errorHandler;
+    /** Construction-time Blok config (everything except `holder`, which the directive owns). */
+    config: Partial<BlokAngularConfig>;
+    /** Changing this input's identity (after the first build) destroys + recreates the editor. */
+    set recreateKey(value: unknown);
+    /** Emits the live Blok instance once it is ready, after `instance` is populated. */
+    readonly ready: EventEmitter<Blok>;
+    /** The live Blok instance, or null before `isReady` resolves / after destroy. */
+    readonly instance: i0.WritableSignal<Blok | null>;
+    /** The editor created by the most recent construction; used as the staleness key. */
+    private current;
+    private destroyed;
+    private built;
+    private currentKey;
+    /** The portal registry for the current editor (Angular-block mounting). */
+    private registry;
+    constructor();
+    /** Construct a Blok into the host element and publish it once ready. */
+    private build;
+    ngOnDestroy(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<BlokContentDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<BlokContentDirective, "[blokContent]", never, { "config": { "alias": "config"; "required": false; }; "recreateKey": { "alias": "recreateKey"; "required": false; }; }, { "ready": "ready"; }, never, never, true, never>;
+}
+
+/**
+ * DI token holding app-wide Blok defaults (shared tools registry, default theme,
+ * i18n). Merged under per-instance inputs by `BlokEditorComponent`.
+ */
+declare const BLOK_DEFAULT_CONFIG: InjectionToken<Partial<BlokAngularConfig>>;
+/**
+ * Standalone provider registering app-wide Blok defaults.
+ *
+ * @example
+ * ```ts
+ * bootstrapApplication(AppComponent, {
+ *   providers: [provideBlok({ theme: 'dark', tools: sharedTools })],
+ * });
+ * ```
+ */
+declare function provideBlok(defaults: Partial<BlokAngularConfig>): EnvironmentProviders;
+
+/**
+ * Where to place the caret within a block. `position` selects the input
+ * (`'start'`/`'end'`/`'default'`) and `offset` is the character offset within it
+ * — the same shape core's `caret.setToBlock` accepts.
+ */
+interface CaretTarget {
+    position?: 'start' | 'end' | 'default';
+    offset?: number;
+}
+/**
+ * A plain, serializable view of one block in the tree.
+ *
+ * Snapshot-volatile: every read allocates a fresh `BlockNode`, and `contentIds`
+ * is DERIVED per read from the children that currently name this block as parent
+ * (it is not a stored field). Read a node in render and re-read after a change —
+ * don't stash one in a `useMemo`/`useEffect` dependency array expecting stable
+ * identity; depend on the `id` instead.
+ */
+interface BlockNode {
+    id: string;
+    type: string;
+    parentId: string | null;
+    contentIds: readonly string[];
+}
+/** Where to place a block among its siblings. */
+type InsertPosition = 'start' | 'end' | {
+    before: string;
+} | {
+    after: string;
+};
+interface InsertSpec {
+    type?: string;
+    data?: BlockToolData;
+    parentId?: string | null;
+    position?: InsertPosition;
+    /**
+     * Move the caret into the new block. Defaults to `false`: a programmatic
+     * insert from React must not steal focus from wherever the user is typing.
+     * Set `true` for an explicit "add a block and start editing it" flow.
+     */
+    focus?: boolean;
+    /**
+     * Replace the block at the resolved slot instead of inserting a new one — a
+     * programmatic "turn into". Combine with a `position` that targets the block
+     * to replace, e.g. `{ position: { before: id }, replace: true }`.
+     */
+    replace?: boolean;
+    /**
+     * Explicit id for the new block (generated when omitted). Passing a stable id
+     * makes the insert idempotent: if a block with this id already exists the
+     * existing node is returned and nothing is inserted ("insert if absent"),
+     * so an effect that re-runs won't create duplicates.
+     */
+    id?: string;
+    /** Block tune data to apply at creation, keyed by tune name. */
+    tunes?: {
+        [name: string]: BlockTuneData;
+    };
+    /**
+     * Place the caret inside the newly-created block at a specific position/offset
+     * (e.g. `{ offset: 3 }`). Implies focus. Applied ONLY when a block is actually
+     * created — an insert-if-absent hit (existing id) does not move the caret.
+     * Use this instead of the boolean `focus` when you need a specific offset.
+     */
+    caret?: CaretTarget;
+}
+/**
+ * One node of a pre-built nested subtree for {@link UseBlocksApi.insertTree}.
+ *
+ * Each node maps to one block; `children` are inserted nested under it (their
+ * `parentId` set to this node's id) in array order, recursively. Placement
+ * options (`parentId`/`position`) are ROOT-ONLY — they position the whole
+ * subtree among existing blocks and are ignored on nested children, whose parent
+ * is always their enclosing node.
+ */
+interface TreeInsertSpec {
+    type?: string;
+    data?: BlockToolData;
+    tunes?: {
+        [name: string]: BlockTuneData;
+    };
+    /**
+     * Explicit id for this node (generated when omitted). Unlike `insert`, this is
+     * NOT insert-if-absent: a tree insert always creates fresh blocks. A colliding
+     * id — one that already exists in the document, or is reused by another node
+     * in the same spec — is REJECTED up front: nothing is inserted and `insertTree`
+     * returns `null` (a duplicate id would corrupt every id-keyed lookup).
+     */
+    id?: string;
+    /** Direct children, inserted nested under this node, in array order. */
+    children?: TreeInsertSpec[];
+    /** Root-only: where to place the whole subtree. Ignored on nested children. */
+    parentId?: string | null;
+    /** Root-only: slot among siblings of `parentId`. Ignored on nested children. */
+    position?: InsertPosition;
+}
+/**
+ * Where to move an existing block.
+ *
+ * `before`/`after` are POSITION targets, not parent assignments: the block is
+ * relocated to that flat slot and — because Blok keeps the flat array as the
+ * canonical document order — ADOPTS the parent of wherever it lands. Moving a
+ * nested block to `{ after: someRootBlock }` therefore unnests it to root, and
+ * moving a root block in among a container's children nests it. Use
+ * `nest`/`unnest` when you want to change the parent without choosing a sibling
+ * slot. `toIndex` is an absolute flat index (clamped into range).
+ */
+type MoveTarget = {
+    before: string;
+} | {
+    after: string;
+} | {
+    toIndex: number;
+};
+interface UseBlocksApi {
+    getById(id: string): BlockNode | null;
+    getChildren(parentId: string | null): BlockNode[];
+    /**
+     * Insert one block; returns the created node or null when rejected (unknown
+     * tool type, dangling `parentId`, or a `replace` whose target is missing). An
+     * explicit `id` that already exists is insert-if-absent (returns the existing
+     * node, creates nothing). Atomic — one undo step. The returned node is
+     * {@link BlockNode}-volatile; read it now, don't put it in a dep array.
+     */
+    insert(spec?: InsertSpec): BlockNode | null;
+    /**
+     * Insert several blocks atomically, in array order, as ONE undo step. Each
+     * spec is a full {@link InsertSpec} (own type/data/parentId/position), routed
+     * through the same single-`insert` path, so per-spec parent assertion and
+     * positioning still apply. Specs that fail to insert (e.g. a dangling
+     * parentId, or a replace whose target is missing) are dropped; the returned
+     * array holds only the successfully created nodes. An empty input is a no-op
+     * (returns `[]`, opens no transaction). Like `insert`, the returned nodes are
+     * fresh-snapshot volatile — read them now, don't stash them in dep arrays.
+     */
+    insertMany(specs: InsertSpec[]): BlockNode[];
+    /**
+     * Insert a pre-built NESTED subtree in ONE atomic operation (one undo step).
+     * Each {@link TreeInsertSpec} node becomes a block; its `children` are inserted
+     * nested under it (recursively, in array order) so the whole hierarchy lands in
+     * a single call — no follow-up `nest` round-trips. Delegates to core's
+     * tree-aware `blocks.insertMany`, which composes the flat DFS pre-order array
+     * honoring each node's `parent`/`content` links.
+     *
+     * Placement is root-only: the root node's `parentId`/`position` position the
+     * whole subtree among existing blocks (default: appended at the document end);
+     * nested children ignore those fields (their parent is their enclosing node). A
+     * dangling root `parentId` is rejected — nothing is inserted and `null` is
+     * returned (mirrors {@link insert}). Returns the root {@link BlockNode}, which
+     * is fresh-snapshot volatile — read it now, don't stash it in a dep array.
+     */
+    insertTree(spec: TreeInsertSpec): BlockNode | null;
+    /**
+     * Convert a Markdown string to blocks and insert them ADDITIVELY at a
+     * position, WITHOUT clearing the document (unlike core's `importMarkdown` /
+     * `renderFromHTML`, which replace the whole document). This is the React
+     * "paste markdown → blocks appear" path.
+     *
+     * Async: the markdown converter is lazy-loaded (kept out of the main bundle),
+     * so this is the ONE async creator in the API — `await` the returned promise.
+     * The whole batch is inserted as a single atomic undo step.
+     *
+     * `position` (default `'end'`) places the converted run among `parentId`'s
+     * children (or root siblings when `parentId` is omitted/null), reusing the
+     * same `start`/`end`/`before`/`after` semantics as {@link insert}.
+     *
+     * `parentId` (default `null` = root) nests the import: every TOP-LEVEL
+     * converted block (one the converter left un-parented) is reparented under
+     * `parentId`, while blocks the markdown nested internally (e.g. table-cell
+     * children) keep their intra-import parent. A dangling `parentId` is a no-op
+     * (returns `[]`, opens no transaction), matching {@link insert}.
+     *
+     * `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.
+     *
+     * 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
+     * top-level run (this differs from {@link insertTree}, which returns only the
+     * root). Empty or whitespace-only markdown, a dangling `parentId` (checked
+     * again after the async convert, so a parent removed mid-flight also no-ops),
+     * and a converter failure (chunk-load or parse error, swallowed) all return
+     * `[]` and open no transaction. The nodes are fresh-snapshot volatile — read
+     * them now, don't stash them in dep arrays.
+     */
+    insertMarkdown(markdown: string, options?: {
+        parentId?: string | null;
+        position?: InsertPosition;
+        config?: MarkdownImportConfig;
+    }): Promise<BlockNode[]>;
+    /**
+     * Serialize the WHOLE document to a Markdown string — the outbound twin of
+     * core's `blocks.exportMarkdown` (and the read-side counterpart of the
+     * 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 `''`.
+     */
+    exportMarkdown(): Promise<string>;
+    move(id: string, target: MoveTarget): void;
+    nest(id: string, parentId: string): void;
+    unnest(id: string): void;
+    remove(id: string): void;
+    /**
+     * Update a block's data and/or tunes by id. Delegates to core's async
+     * `blocks.update`, which forms its OWN undo step — the call is NOT wrapped in
+     * `transact` (that would close the group before the async write lands). An
+     * unknown id is a silent no-op; a rejected update is swallowed so it can't
+     * surface as an unhandled rejection. Reads refresh reactively once core emits
+     * 'block changed'. Returns `void`.
+     */
+    update(id: string, data?: BlockToolData, tunes?: {
+        [name: string]: BlockTuneData;
+    }): void;
+    /**
+     * Convert a block to another type ("turn into") by id. Delegates to core's
+     * async `blocks.convert`; both tools must provide a `conversionConfig` or core
+     * rejects — that rejection (and any other) is swallowed so a non-convertible
+     * block is a graceful no-op rather than an unhandled rejection. An unknown id
+     * is a silent no-op. Not wrapped in `transact` (core owns its history step).
+     * Returns `void`.
+     */
+    convert(id: string, newType: string, dataOverrides?: BlockToolData, options?: {
+        caret?: CaretTarget;
+    }): void;
+    transact(fn: () => void): void;
+    /**
+     * Run `fn` as one atomic operation that is NOT captured in the undo history —
+     * the React-surface counterpart of core's `transactWithoutCapture`. Use for
+     * silent auto-repair/normalization that a user's CMD+Z should never step
+     * through. Mutations inside still emit reactively. Pre-ready it just runs `fn`.
+     */
+    transactWithoutCapture(fn: () => void): void;
+    /**
+     * The current block count. Reactive (re-reads on 'block changed'). Pre-ready: 0.
+     */
+    getBlocksCount(): number;
+    /**
+     * The flat index of the block holding the caret, or -1 when none. Pre-ready: -1.
+     */
+    getCurrentBlockIndex(): number;
+    /** The block at a flat index as a snapshot {@link BlockNode}, or null. */
+    getBlockByIndex(index: number): BlockNode | null;
+    /**
+     * The absolute flat index of a block by id, or null when unknown. The
+     * counterpart to {@link getBlockByIndex} — use it to target an off-caret
+     * {@link splitBlock} (whose `insertIndex` is absolute) without the ref. Unknown
+     * ids return null silently (no console warn). Pre-ready: null.
+     */
+    getBlockIndex(id: string): number | null;
+    /**
+     * Read a block's current `data` and `tunes` by id WITHOUT mutating anything —
+     * the synchronous last-extracted view (the same snapshot clipboard ops use).
+     * Makes a client-side duplicate composable from the hook alone: read a node,
+     * then `insert({ type, data, tunes, position })`, no ref escape hatch. Unknown
+     * id returns null. Pre-ready: null.
+     */
+    getBlockData(id: string): {
+        data: BlockToolData;
+        tunes: {
+            [name: string]: BlockTuneData;
+        };
+    } | null;
+    /**
+     * The block whose holder contains/equals `element`, as a snapshot
+     * {@link BlockNode}, or null. Useful for mapping a DOM event target back to a
+     * block.
+     */
+    getBlockByElement(element: HTMLElement): BlockNode | null;
+    /**
+     * Read a tool's default empty data WITHOUT inserting anything — delegates to
+     * core's `composeBlockData`. Async (a tool's data may be composed lazily).
+     * Rejects (via core) for an unknown tool. Pre-ready: resolves to `{}`.
+     */
+    composeBlockData(toolName: string): Promise<BlockToolData>;
+    /**
+     * Replace the WHOLE document with blocks parsed from an HTML string —
+     * delegates to core's `renderFromHTML`. Unlike {@link insertMarkdown} (which is
+     * additive), this CLEARS existing content first, so it's a document-load
+     * primitive, not an insert. Async. Pre-ready: resolves immediately (no-op).
+     */
+    renderFromHTML(html: string): Promise<void>;
+    /**
+     * Insert a flat array of already-serialized {@link OutputBlockData} (the
+     * `save()` shape) directly, honoring each block's `parent`/`content` links —
+     * the raw counterpart of core's `blocks.insertMany`. Use to re-insert a saved
+     * document fragment without reshaping it into {@link TreeInsertSpec}. One
+     * atomic undo step. Returns the created nodes; pre-ready: `[]` (no insert).
+     */
+    insertOutputData(blocks: OutputBlockData[], options?: {
+        index?: number;
+    }): BlockNode[];
+    /**
+     * Atomically split a block: update `currentBlockId` with `currentBlockData`
+     * and insert a new `newBlockType` block at `insertIndex`, as ONE undo step.
+     * Delegates to core's `splitBlock`. Returns the new node, or null pre-ready /
+     * on an unknown id.
+     */
+    splitBlock(currentBlockId: string, currentBlockData: Partial<BlockToolData>, newBlockType: string, newBlockData: BlockToolData, insertIndex: number): BlockNode | null;
+    /**
+     * Insert a single child block under `parentId` at flat `insertIndex`, atomically
+     * (block creation AND parent assignment in ONE undo step) — delegates to core's
+     * `blocks.insertInsideParent`. This is the atomic nested-child creator: prefer it
+     * over `insert()` + `nest()`, which is TWO undo steps. A dangling `parentId` is a
+     * no-op returning `null` (mirrors {@link insert}); an unknown child tool returns
+     * `null`. `childData` defaults to an empty paragraph. Returns the created
+     * {@link BlockNode}, fresh-snapshot volatile — read it now, don't stash it in a
+     * dep array. Pre-ready: `null`.
+     */
+    insertInsideParent(parentId: string, insertIndex: number, childData?: BlockToolData): BlockNode | null;
+    /**
+     * Replace the WHOLE document with blocks parsed from saved {@link OutputData}
+     * (the `save()` shape) — delegates to core's `blocks.render`. Unlike
+     * {@link insertOutputData}/{@link insertMarkdown} (which are ADDITIVE), this
+     * CLEARS existing content first: a document-LOAD primitive, not an insert. The
+     * HTML counterpart is {@link renderFromHTML}. Async. Pre-ready: resolves
+     * immediately (no-op).
+     */
+    render(data: OutputData): Promise<void>;
+    /**
+     * Remove EVERY block from the document — delegates to core's `blocks.clear`. A
+     * document-reset primitive (pairs with {@link render}). Async. Pre-ready:
+     * resolves immediately (no-op).
+     */
+    clear(): Promise<void>;
+    /**
+     * Whether a Yjs sync (undo/redo) is currently in progress — the React mirror of
+     * core's `blocks.isSyncingFromYjs`. A METHOD (not a property) so it reads the
+     * LIVE flag at call time even though the api handle is memoized. Use it to skip
+     * cleanup that would fight Yjs state during an undo/redo. Pre-ready: `false`.
+     */
+    isSyncingFromYjs(): boolean;
+}
+
+/** One field of a block's prop schema. */
+interface PropSchemaEntry {
+    /** Default value, used when the incoming data omits this key. */
+    default: unknown;
+    /** Optional allowed values (advisory; not enforced at runtime in v1). */
+    values?: readonly unknown[];
+}
+/**
+ * Declarative data shape. The keys here are EXACTLY the keys `save()` returns to
+ * Yjs — this closes the per-key-sync key-resurrection gap (a cleared field is
+ * written as its explicit default, never dropped).
+ */
+type PropSchema = Record<string, PropSchemaEntry>;
+
+/** Spec for {@link createAngularBlock}. Authored as a standalone component. */
+interface CreateAngularBlockSpec<Data = BlockToolData> {
+    /** Tool type name (registered key). */
+    type: string;
+    /** Optional toolbox entry. */
+    toolbox?: ToolboxConfig;
+    /** Declarative defaults that also define the exact `save()` key set. */
+    propSchema: PropSchema;
+    /**
+     * The standalone Angular component to render for each block. It injects the
+     * per-block context via `inject(BLOK_BLOCK_CONTEXT)`.
+     */
+    component: Type<unknown>;
+    /** Optional lifecycle callbacks mapped from Blok's block hooks. */
+    onRendered?: (block: BlockAPI) => void;
+    onMoved?: (block: BlockAPI) => void;
+    onRemoved?: (block: BlockAPI) => void;
+}
+/**
+ * Author a first-party Angular block. Returns a `BlockToolConstructable`
+ * registered exactly like a vanilla tool (`tools: { type: { class:
+ * createAngularBlock(...) } }`).
+ *
+ * The factory owns the host element (`data-blok-mutation-free`), a frozen
+ * defaults-filled data mirror, and signals the component reads. It mounts the
+ * component into the host via the editor's shared portal registry (the analog of
+ * Vue's Teleport registry), bridging Blok's block lifecycle to Angular:
+ * - `render()` creates the host and registers the portal entry (mounted sync).
+ * - `setData()` dedups, swaps the reactive snapshot, flushes CD, resolves true.
+ * - `save()` returns the complete frozen mirror (never the DOM, never partial).
+ * - `commit()` merges a patch and fires `dispatchChange` exactly once.
+ * - `setReadOnly()` flips a reactive flag and flushes CD (in-place, no remount).
+ * - `removed()`/`destroy()` unregister the portal (deterministic unmount).
+ */
+declare function createAngularBlock<Data = BlockToolData>(spec: CreateAngularBlockSpec<Data>): (new (options: BlockToolConstructorOptions) => {
+    render(): HTMLElement;
+    save(): BlockToolData;
+    setData(newData: BlockToolData): Promise<boolean>;
+    setReadOnly(state: boolean): void;
+    rendered(): void;
+    moved(): void;
+    removed(): void;
+    destroy(): void;
+}) & {
+    readonly __isBlokAngularBlock: true;
+    readonly toolbox: ToolboxConfig | undefined;
+    readonly isReadOnlySupported: boolean;
+};
+
+/**
+ * Angular factory exposing an id/parentId-relative, reactive view of the block
+ * tree. Reads refresh whenever the editor emits `block changed`; mutators route
+ * through the editor-level `blocks` API (core's chokepoints), so undo/redo and
+ * Yjs sync are inherited rather than re-implemented.
+ *
+ * The block-tree logic is framework-agnostic and lives in the shared
+ * {@link createBlocksApiForEditor} core — the SAME implementation behind React's
+ * and Vue's `useBlocks`, so all three adapters expose the identical 28-method
+ * surface and cannot drift. This wrapper supplies only Angular's reactivity:
+ *
+ * - A private `version` signal is bumped on every `block changed`. The shared API
+ *   is built with an `onRead` seam (`() => { version() }`) that every read method
+ *   calls, so reading inside a `computed`/template tracks `version` and re-runs on
+ *   each structural mutation.
+ * - The bound API is rebuilt (via `bindToEditor`, called eagerly on first call and
+ *   then tracked by an `effect` for subsequent identity changes) when the editor
+ *   IDENTITY changes; the returned facade is stable across that swap.
+ *
+ * Call it in an injection context (component constructor / field initializer),
+ * passing the editor signal (e.g. `BlokEditorComponent.instance` /
+ * `BlokContentDirective.instance`). Pre-ready (editor null) the bound API is the
+ * shared {@link EMPTY_API}: every mutator a no-op, reads empty/null — except
+ * `transact`/`transactWithoutCapture`, which still run their callback.
+ *
+ * Note: Angular 20's `effect()` is scheduled (not eager) — it does not fire
+ * synchronously on first call. The initial binding therefore runs synchronously
+ * in the `injectBlocks` body itself (mirroring Vue's `{ immediate: true }` watch),
+ * and the effect re-binds only on subsequent editor identity changes. When the
+ * effect fires for the first time with the same editor already bound, the guard
+ * `ed === sub.editor` makes it a no-op, so no double-subscription occurs.
+ *
+ * @param editor - a signal of the Blok instance, or null pre-ready
+ */
+declare function injectBlocks(editor: Signal<Blok | null>): UseBlocksApi;
+
+/** How the caller names the DOM scope to observe. */
+type BlokReadyScope = (() => Element | ElementRef<Element> | null | undefined) | ElementRef<Element> | Element | null;
+/** Options accepted by {@link injectBlokReady}. */
+interface InjectBlokReadyOptions {
+    /**
+     * Restrict the wait to editors mounted inside this element. Accepts an
+     * element, an `ElementRef`, or a getter/signal returning either — the getter
+     * form lets you pass `() => this.scopeRef?.nativeElement` from a field
+     * initializer, before the view exists. It is re-read on every readiness
+     * change.
+     *
+     * Omit it to observe every editor on the page. Passing it while it still
+     * resolves to null reports NOT ready — an unresolved scope must never fall
+     * back to the page-global one.
+     */
+    within?: BlokReadyScope;
+    /**
+     * `'ready'` (default) settles when each editor has finished booting.
+     * `'rendered'` also waits for its content to be in the DOM and re-arms on
+     * every post-boot re-render.
+     */
+    settleOn?: 'ready' | 'rendered';
+}
+/**
+ * Angular factory exposing the live readiness of the Blok editors in a DOM
+ * scope as a boolean signal.
+ *
+ * The readiness logic itself is framework-agnostic and lives in core
+ * (`Blok.readyState` / `Blok.subscribeReady`) — the SAME implementation behind
+ * React's and Vue's `useBlokReady`, so the three adapters cannot drift. This
+ * wrapper supplies only Angular's reactivity: a signal re-read on every
+ * registry change, unsubscribed through the injector's `DestroyRef`.
+ *
+ * Call it in an injection context (component constructor / field initializer).
+ * The signal starts `false` and takes its first real reading in
+ * `afterNextRender` — browser-only by contract, and late enough for a
+ * `@ViewChild` scope to exist. Over-waiting is safe; under-waiting is a bug.
+ * @param options - scope and readiness depth
+ */
+declare function injectBlokReady(options?: InjectBlokReadyOptions): Signal<boolean>;
+
+/**
+ * Context handed to a `createAngularBlock` component. Delivered via DI (the
+ * BLOK_BLOCK_CONTEXT token) rather than @Input, because core constructs the tool
+ * outside Angular and the signal-input() form does not compile under the repo's
+ * JIT test harness. The ONLY data write path is `commit`.
+ */
+interface AngularBlockRenderContext<Data> {
+    /** Reactive, FROZEN snapshot of the block data. Read `data()`; never mutate. */
+    data: Signal<Readonly<Data>>;
+    /** The ONLY data write path: merge a partial patch and sync once. */
+    commit: (patch: Partial<Data>) => void;
+    /** This block's per-block API (id, getChildren, dispatchChange…). */
+    block: BlockAPI;
+    /**
+     * Reactive read-only flag. Read `readOnly()` in the template to disable
+     * editing (drop `contenteditable`, hide controls). Toggled IN PLACE by core's
+     * read-only switch — the component reacts without a remount, so ephemeral
+     * state survives. A block that ignores it stays interactive when the editor is
+     * read-only (same contract as a vanilla tool's `setReadOnly`).
+     */
+    readOnly: Signal<boolean>;
+    /**
+     * Container blocks only: append this block's real child holders into `host`
+     * (a `data-blok-nested` element the author owns). Call it once in
+     * `ngAfterViewInit`; the factory re-runs the same mount on every data change
+     * so late-added children appear. Angular must NOT manage these child holders.
+     */
+    mountChildren: (host: HTMLElement) => void;
+}
+/** DI token carrying the per-block render context into the authored component. */
+declare const BLOK_BLOCK_CONTEXT: InjectionToken<AngularBlockRenderContext<unknown>>;
+
+export { BLOK_BLOCK_CONTEXT, BLOK_DEFAULT_CONFIG, BlokContentDirective, BlokEditorComponent, createAngularBlock, injectBlocks, injectBlokReady, provideBlok };
+export type { AngularBlockRenderContext, BlockNode, BlokAngularConfig, BlokReadyScope, CaretTarget, CreateAngularBlockSpec, InjectBlokReadyOptions, InsertPosition, InsertSpec, MoveTarget, PropSchema, PropSchemaEntry, TreeInsertSpec, UseBlocksApi };