@ecsplico/editor 2.1.1 → 3.0.0

package/dist/core/extension-points.d.ts

@@ -1,5 +1,5 @@
 import { Ability, AbilityRuleSource } from "./schema/abilities.js";
-import { MenuItem } from "./toolbar.js";
+import { MenuItem } from "./command-types.js";
 import { Editor } from "@tiptap/core";
 import { Node as Node$1 } from "@tiptap/pm/model";
 //#region src/core/extension-points.d.ts
@@ -19,8 +19,8 @@ interface BlockActionBase {
   label: string;
   /** Iconify name, e.g. `i-lucide-copy`. */
   icon: string;
-  /** Shown only on blocks that have this ability. */
-  ability: Ability;
+  /** Shown only on blocks that have this ability; shown on every block when unset. */
+  ability?: Ability;
   /** Further condition; hidden when it returns false. */
   isVisible?: (ctx: BlockActionContext) => boolean;
   /** Position among the actions (ascending, stable); built-ins use their visual sequence, host actions follow them. */
@@ -37,18 +37,6 @@ export type BlockAction = BlockActionBase & ({
   menu: (ctx: BlockActionContext) => MenuItem[];
   run?: never;
 });
-/** A row of the `/` menu. */
-export interface SlashCommandItem {
-  /** Typed after `/` (`/ai`); the query matches it or the label as prefix, case-insensitively. */
-  id: string;
-  label: string;
-  /** Iconify name, e.g. `i-lucide-sparkles`. */
-  icon: string;
-  /** Runs once the `/query` text is deleted; the caret is then in the (now empty) textblock. */
-  run: (editor: Editor) => void;
-  /** Listed only where the caret has this ability; always listed when unset. */
-  ability?: Ability;
-}
 export interface AbilitiesOptions {
   /** Abilities at document root, before any node rule applies. */
   root: readonly Ability[];

package/dist/core/feature-context.d.ts

@@ -1,9 +1,11 @@
-import { AbilitiesOptions, BlockAction, SlashCommandItem } from "./extension-points.js";
 import { Notifier } from "./notify.js";
 import { EditorContext } from "./context.js";
+import { CommandDef } from "./command-types.js";
+import { AbilitiesOptions, BlockAction } from "./extension-points.js";
 import { EditorUi } from "./editor-ui.js";
 import { MetadataRegistry } from "./metadata.js";
-import { CollaborationSession, EditorPreset, FeatureContext, UploadFn } from "./feature.js";
+import { CollaborationSession, EditorPreset, FeatureContext } from "./feature.js";
+import "./commands.js";
 import { Editor } from "@tiptap/core";
 //#region src/core/feature-context.d.ts
 export interface FeatureContextOptions {
@@ -15,15 +17,14 @@ export interface FeatureContextOptions {
   notify: Notifier;
   getEditor: () => Editor | undefined;
   documentId?: string;
-  upload?: UploadFn;
   collaboration?: CollaborationSession;
   abilities?: Partial<AbilitiesOptions>;
-  /** Host transformer of the `/` menu: receives the features' commands, returns the final list. */
-  slashCommands?: (defaults: SlashCommandItem[]) => SlashCommandItem[];
+  /** Host transformer of the command list (and with it the `/` menu): receives the features' commands, returns the final list. */
+  commands?: (defaults: CommandDef[]) => CommandDef[];
 }
 /**
- * The context of one mounted surface (see `FeatureContext`). Resolves the preset's anchor resolver and builds the `/`
- * menu lazily (features' commands, then the host's transformer), once. Call it during component setup.
+ * The context of one mounted surface (see `FeatureContext`). Resolves the preset's anchor resolver and builds the command
+ * list lazily (features' commands, then the host's transformer), once. Call it during component setup.
  */
 export declare function createFeatureContext(options: FeatureContextOptions): FeatureContext;
 /** The features' block actions in `order` (stable), followed by the host's. */

package/dist/core/feature-context.js

@@ -1,13 +1,14 @@
+import { byOrder } from "./util.js";
 import { contributions } from "./define-editor.js";
+import { assertUniqueCommandIds, commandsOf } from "./commands.js";
 //#region src/core/feature-context.ts
-const byOrder = (a, b) => (a.order ?? 0) - (b.order ?? 0);
 /**
-* The context of one mounted surface (see `FeatureContext`). Resolves the preset's anchor resolver and builds the `/`
-* menu lazily (features' commands, then the host's transformer), once. Call it during component setup.
+* The context of one mounted surface (see `FeatureContext`). Resolves the preset's anchor resolver and builds the command
+* list lazily (features' commands, then the host's transformer), once. Call it during component setup.
 */
 function createFeatureContext(options) {
 	const { app, preset } = options;
-	let slash;
+	let list;
 	const ctx = {
 		app,
 		settings: app.settings,
@@ -16,19 +17,19 @@ function createFeatureContext(options) {
 		notify: options.notify,
 		locale: app.locale,
 		t: app.t,
-		fetch: app.fetch,
+		backend: app.backend,
 		ai: app.ai,
 		documentId: options.documentId,
-		upload: options.upload,
 		collaboration: options.collaboration,
 		anchorResolver: null,
 		abilities: options.abilities ?? {},
-		slashCommands: () => {
-			if (!slash) {
-				const defaults = contributions(preset, "slashCommands").flatMap((factory) => factory(ctx));
-				slash = options.slashCommands ? options.slashCommands(defaults) : defaults;
+		commands: () => {
+			if (!list) {
+				const defaults = commandsOf(preset, ctx);
+				list = options.commands ? options.commands(defaults) : defaults;
+				if (options.commands) assertUniqueCommandIds(list);
 			}
-			return slash;
+			return list;
 		},
 		getEditor: options.getEditor
 	};

package/dist/core/feature-context.js.map

@@ -1 +1 @@
-{"version":3,"file":"feature-context.js","names":[],"sources":["../../src/core/feature-context.ts"],"sourcesContent":["import type { Editor } from '@tiptap/core'\nimport type { EditorContext } from './context'\nimport { contributions } from './define-editor'\nimport type { EditorUi } from './editor-ui'\nimport type { AbilitiesOptions, BlockAction, SlashCommandItem } from './extension-points'\nimport type { CollaborationSession, EditorPreset, FeatureContext, UploadFn } from './feature'\nimport type { MetadataRegistry } from './metadata'\nimport type { Notifier } from './notify'\n\nexport interface FeatureContextOptions {\n  app: EditorContext\n  preset: EditorPreset\n  ui: EditorUi\n  metadata: MetadataRegistry\n  /** The surface's notice renderer (Nuxt UI toast, sonner). */\n  notify: Notifier\n  getEditor: () => Editor | undefined\n  documentId?: string\n  upload?: UploadFn\n  collaboration?: CollaborationSession\n  abilities?: Partial<AbilitiesOptions>\n  /** Host transformer of the `/` menu: receives the features' commands, returns the final list. */\n  slashCommands?: (defaults: SlashCommandItem[]) => SlashCommandItem[]\n}\n\nconst byOrder = <T extends { order?: number }>(a: T, b: T) => (a.order ?? 0) - (b.order ?? 0)\n\n/**\n * The context of one mounted surface (see `FeatureContext`). Resolves the preset's anchor resolver and builds the `/`\n * menu lazily (features' commands, then the host's transformer), once. Call it during component setup.\n */\nexport function createFeatureContext(options: FeatureContextOptions): FeatureContext {\n  const { app, preset } = options\n  let slash: SlashCommandItem[] | undefined\n  const ctx: { -readonly [K in keyof FeatureContext]: FeatureContext[K] } = {\n    app,\n    settings: app.settings,\n    metadata: options.metadata,\n    ui: options.ui,\n    notify: options.notify,\n    locale: app.locale,\n    t: app.t,\n    fetch: app.fetch,\n    ai: app.ai,\n    documentId: options.documentId,\n    upload: options.upload,\n    collaboration: options.collaboration,\n    anchorResolver: null,\n    abilities: options.abilities ?? {},\n    slashCommands: () => {\n      if (!slash) {\n        const defaults = contributions(preset, 'slashCommands').flatMap(factory => factory(ctx))\n        slash = options.slashCommands ? options.slashCommands(defaults) : defaults\n      }\n      return slash\n    },\n    getEditor: options.getEditor,\n  }\n  ctx.anchorResolver = contributions(preset, 'anchorResolver')[0]?.(ctx) ?? null\n  for (const defaults of contributions(preset, 'metadataDefaults')) ctx.metadata.defaults(defaults(ctx))\n  return ctx\n}\n\n/** The features' block actions in `order` (stable), followed by the host's. */\nexport function blockActionsOf(preset: EditorPreset, ctx: FeatureContext, hostActions: readonly BlockAction[] = []): BlockAction[] {\n  return [...contributions(preset, 'blockActions').flatMap(factory => factory(ctx)).sort(byOrder), ...hostActions]\n}\n"],"mappings":";;AAyBA,MAAM,WAAyC,GAAM,OAAU,EAAE,SAAS,MAAM,EAAE,SAAS;;;;;AAM3F,SAAgB,qBAAqB,SAAgD;CACnF,MAAM,EAAE,KAAK,WAAW;CACxB,IAAI;CACJ,MAAM,MAAoE;EACxE;EACA,UAAU,IAAI;EACd,UAAU,QAAQ;EAClB,IAAI,QAAQ;EACZ,QAAQ,QAAQ;EAChB,QAAQ,IAAI;EACZ,GAAG,IAAI;EACP,OAAO,IAAI;EACX,IAAI,IAAI;EACR,YAAY,QAAQ;EACpB,QAAQ,QAAQ;EAChB,eAAe,QAAQ;EACvB,gBAAgB;EAChB,WAAW,QAAQ,aAAa,CAAC;EACjC,qBAAqB;GACnB,IAAI,CAAC,OAAO;IACV,MAAM,WAAW,cAAc,QAAQ,eAAe,CAAC,CAAC,SAAQ,YAAW,QAAQ,GAAG,CAAC;IACvF,QAAQ,QAAQ,gBAAgB,QAAQ,cAAc,QAAQ,IAAI;GACpE;GACA,OAAO;EACT;EACA,WAAW,QAAQ;CACrB;CACA,IAAI,iBAAiB,cAAc,QAAQ,gBAAgB,CAAC,CAAC,EAAE,GAAG,GAAG,KAAK;CAC1E,KAAK,MAAM,YAAY,cAAc,QAAQ,kBAAkB,GAAG,IAAI,SAAS,SAAS,SAAS,GAAG,CAAC;CACrG,OAAO;AACT;;AAGA,SAAgB,eAAe,QAAsB,KAAqB,cAAsC,CAAC,GAAkB;CACjI,OAAO,CAAC,GAAG,cAAc,QAAQ,cAAc,CAAC,CAAC,SAAQ,YAAW,QAAQ,GAAG,CAAC,CAAC,CAAC,KAAK,OAAO,GAAG,GAAG,WAAW;AACjH"}
+{"version":3,"file":"feature-context.js","names":[],"sources":["../../src/core/feature-context.ts"],"sourcesContent":["import type { Editor } from '@tiptap/core'\nimport type { EditorContext } from './context'\nimport { assertUniqueCommandIds, type CommandDef, commandsOf } from './commands'\nimport { contributions } from './define-editor'\nimport type { EditorUi } from './editor-ui'\nimport type { AbilitiesOptions, BlockAction } from './extension-points'\nimport type { CollaborationSession, EditorPreset, FeatureContext } from './feature'\nimport type { MetadataRegistry } from './metadata'\nimport type { Notifier } from './notify'\nimport { byOrder } from './util'\n\nexport interface FeatureContextOptions {\n  app: EditorContext\n  preset: EditorPreset\n  ui: EditorUi\n  metadata: MetadataRegistry\n  /** The surface's notice renderer (Nuxt UI toast, sonner). */\n  notify: Notifier\n  getEditor: () => Editor | undefined\n  documentId?: string\n  collaboration?: CollaborationSession\n  abilities?: Partial<AbilitiesOptions>\n  /** Host transformer of the command list (and with it the `/` menu): receives the features' commands, returns the final list. */\n  commands?: (defaults: CommandDef[]) => CommandDef[]\n}\n\n/**\n * The context of one mounted surface (see `FeatureContext`). Resolves the preset's anchor resolver and builds the command\n * list lazily (features' commands, then the host's transformer), once. Call it during component setup.\n */\nexport function createFeatureContext(options: FeatureContextOptions): FeatureContext {\n  const { app, preset } = options\n  let list: CommandDef[] | undefined\n  const ctx: { -readonly [K in keyof FeatureContext]: FeatureContext[K] } = {\n    app,\n    settings: app.settings,\n    metadata: options.metadata,\n    ui: options.ui,\n    notify: options.notify,\n    locale: app.locale,\n    t: app.t,\n    backend: app.backend,\n    ai: app.ai,\n    documentId: options.documentId,\n    collaboration: options.collaboration,\n    anchorResolver: null,\n    abilities: options.abilities ?? {},\n    commands: () => {\n      if (!list) {\n        const defaults = commandsOf(preset, ctx)\n        list = options.commands ? options.commands(defaults) : defaults\n        if (options.commands) assertUniqueCommandIds(list)\n      }\n      return list\n    },\n    getEditor: options.getEditor,\n  }\n  ctx.anchorResolver = contributions(preset, 'anchorResolver')[0]?.(ctx) ?? null\n  for (const defaults of contributions(preset, 'metadataDefaults')) ctx.metadata.defaults(defaults(ctx))\n  return ctx\n}\n\n/** The features' block actions in `order` (stable), followed by the host's. */\nexport function blockActionsOf(preset: EditorPreset, ctx: FeatureContext, hostActions: readonly BlockAction[] = []): BlockAction[] {\n  return [...contributions(preset, 'blockActions').flatMap(factory => factory(ctx)).sort(byOrder), ...hostActions]\n}\n"],"mappings":";;;;;;;;AA8BA,SAAgB,qBAAqB,SAAgD;CACnF,MAAM,EAAE,KAAK,WAAW;CACxB,IAAI;CACJ,MAAM,MAAoE;EACxE;EACA,UAAU,IAAI;EACd,UAAU,QAAQ;EAClB,IAAI,QAAQ;EACZ,QAAQ,QAAQ;EAChB,QAAQ,IAAI;EACZ,GAAG,IAAI;EACP,SAAS,IAAI;EACb,IAAI,IAAI;EACR,YAAY,QAAQ;EACpB,eAAe,QAAQ;EACvB,gBAAgB;EAChB,WAAW,QAAQ,aAAa,CAAC;EACjC,gBAAgB;GACd,IAAI,CAAC,MAAM;IACT,MAAM,WAAW,WAAW,QAAQ,GAAG;IACvC,OAAO,QAAQ,WAAW,QAAQ,SAAS,QAAQ,IAAI;IACvD,IAAI,QAAQ,UAAU,uBAAuB,IAAI;GACnD;GACA,OAAO;EACT;EACA,WAAW,QAAQ;CACrB;CACA,IAAI,iBAAiB,cAAc,QAAQ,gBAAgB,CAAC,CAAC,EAAE,GAAG,GAAG,KAAK;CAC1E,KAAK,MAAM,YAAY,cAAc,QAAQ,kBAAkB,GAAG,IAAI,SAAS,SAAS,SAAS,GAAG,CAAC;CACrG,OAAO;AACT;;AAGA,SAAgB,eAAe,QAAsB,KAAqB,cAAsC,CAAC,GAAkB;CACjI,OAAO,CAAC,GAAG,cAAc,QAAQ,cAAc,CAAC,CAAC,SAAQ,YAAW,QAAQ,GAAG,CAAC,CAAC,CAAC,KAAK,OAAO,GAAG,GAAG,WAAW;AACjH"}

package/dist/core/feature.d.ts

@@ -1,25 +1,22 @@
-import { ToolbarGroup } from "./toolbar.js";
-import { AbilitiesOptions, BlockAction, SlashCommandItem } from "./extension-points.js";
-import { ConvertTarget } from "./convert.js";
+import { Store } from "./store.js";
 import { Locale, Translate } from "../i18n/index.js";
 import { EditorSettings } from "../settings/index.js";
+import { BackendCapability } from "./backend-capability.js";
+import { EditorBackend } from "./backend.js";
 import { Notifier } from "./notify.js";
-import { Store } from "./store.js";
 import { EditorAiConfig, EditorContext } from "./context.js";
+import { ConvertTarget } from "./convert.js";
+import { CommandDef, InsertGuard, ToolbarGroupDef } from "./command-types.js";
+import { AbilitiesOptions, BlockAction } from "./extension-points.js";
 import { EditorUi } from "./editor-ui.js";
 import { EditorMetadata } from "./metadata-types.js";
 import { MetadataRegistry } from "./metadata.js";
 import { AnyExtension, Editor, JSONContent } from "@tiptap/core";
 import { EditorState, Transaction } from "@tiptap/pm/state";
 import { Node as Node$1, ResolvedPos } from "@tiptap/pm/model";
-import { $Fetch } from "ofetch";
-import * as Y from "yjs";
 import { HocuspocusProvider } from "@hocuspocus/provider";
+import * as Y from "yjs";
 //#region src/core/feature.d.ts
-/** Stores an uploaded file and returns its URL (media feature). */
-export type UploadFn = (file: File) => Promise<{
-  url: string;
-}>;
 /**
  * The user writing in an editor: the collaboration session's `user`, labelled on remote carets, and (authors and comments
  * features) copied into the author mark of every text run and into every comment the user writes.
@@ -35,7 +32,7 @@ export interface CollaborationSession {
   provider?: HocuspocusProvider;
   user?: AuthorIdentity;
   /**
-   * Token the collaboration server's `EditorAdapter.authenticate` receives (`{ headers, token }`), for clients without
+   * Token the collaboration server's `Identity.authenticate` receives (`{ headers, token }`), for clients without
    * the session cookie of the server's origin (scripts, agents, cross-origin hosts). A string, or a function called
    * every time the socket opens (so it can refresh an expired token). Applied to `provider`'s configuration when the
    * surface is set up, which the provider reads when its socket opens: create the provider and mount the surface in the
@@ -79,19 +76,19 @@ export interface FeatureContext {
   readonly locale: Locale;
   /** Renders a catalog message in the app's language; every label a feature contributes goes through it. */
   readonly t: Translate;
-  readonly fetch: $Fetch;
+  /** The data layer of the app (`createEditorContext({ backend })`): uploads, mention lookups, themes, AI. */
+  readonly backend: EditorBackend;
   /** Inert public AI configuration of the app context; absent when none was supplied. */
   readonly ai: EditorAiConfig | undefined;
   /** Document whose package stores uploads (media feature). */
   readonly documentId: string | undefined;
-  readonly upload: UploadFn | undefined;
   readonly collaboration: CollaborationSession | undefined;
   /** The collaboration-aware position mapping of the preset's `anchorResolver` feature; null means local mapping only. */
   readonly anchorResolver: AnchorResolver | null;
   /** Host options for the ability extension (`abilities` prop). */
   readonly abilities: Partial<AbilitiesOptions>;
-  /** The final `/` menu (features' commands run through the host's `slashCommands` transformer). */
-  readonly slashCommands: () => SlashCommandItem[];
+  /** The final command list: the features' commands after the host's `commands` transformer. The `/` menu lists the ones with a `slash` placement. */
+  readonly commands: () => CommandDef[];
   /** Undefined while extensions are constructed; set once the editor exists. Use it in event handlers. */
   getEditor: () => Editor | undefined;
 }
@@ -149,7 +146,7 @@ export interface AiContextKind {
   fields: readonly {
     key: string;
     label: string;
-    type?: 'text' | 'textarea' | 'date' | 'number' | 'select';
+    type?: 'text' | 'textarea' | 'date' | 'number' | 'select' | 'reference' | 'bibliography' | 'derivation';
     options?: readonly {
       value: string;
       label: string;
@@ -187,15 +184,34 @@ export interface AiBlockDataRequest {
 }
 /** Material for one block; `signal` aborts when the editor is destroyed or the run is cancelled. */
 export type AiBlockDataProvider = (request: AiBlockDataRequest) => Promise<readonly AiBlockDatum[]> | readonly AiBlockDatum[];
-/** One independently importable capability. Every member is optional; identity and ordering come from the feature list. */
+/**
+ * The axis a feature belongs to: `content` (nodes, marks and structure rules the document stores: the server schema comes
+ * from here), `interaction` (editing UX, backend-bound UI such as comments and collaboration) or `ai`. A feature
+ * belongs to the dimension without which it makes no sense.
+ */
+export type Dimension = 'content' | 'interaction' | 'ai';
+/** One named contribution to an editor (blocks, toolbar entries, menus, settings, AI knowledge). Every member is optional but `dimension`; identity and ordering come from the feature list. */
 export interface EditorFeature<C = unknown> {
   id: string;
+  /** The feature's primary dimension. */
+  dimension: Dimension;
+  /**
+   * The Vue-free schema-bearing extensions of this feature (no node views, no UI), collected by `schemaExtensionsOf` for
+   * the server schema. Present on every feature whose nodes or marks the stored document can contain.
+   */
+  schemaExtensions?: () => AnyExtension[];
   /** Ids of features that must also be installed (`defineEditor` does not install them). */
   requires?: readonly string[];
+  /** Backend capabilities the feature cannot work without; a surface session over a backend lacking one throws. Optional capabilities (users and tags for mentions) are not listed. */
+  backend?: readonly BackendCapability[];
   extensions?: (ctx: FeatureContext) => AnyExtension[];
-  toolbar?: (ctx: FeatureContext) => ToolbarGroup<C>[];
   blockActions?: (ctx: FeatureContext) => BlockAction[];
-  slashCommands?: (ctx: FeatureContext) => SlashCommandItem[];
+  /** The feature's commands, each declared once with its toolbar and `/` placements (see `CommandDef`). */
+  commands?: (ctx: FeatureContext) => CommandDef<C>[];
+  /** Toolbar groups the feature declares; every command's `toolbar.group` must be declared by some feature. Ids are unique across features. */
+  toolbarGroups?: ToolbarGroupDef[];
+  /** Rules a command's `creates` must pass at the caret besides the schema (e.g. a Baustein's accepted children). */
+  insertGuards?: (ctx: FeatureContext) => InsertGuard[];
   /** Components mounted beside the editor content; they receive `{ editor }`. `C` is the component type of the framework layer that renders them. */
   overlays?: readonly C[];
   /**

package/dist/core/feature.js.map

@@ -1 +1 @@
-{"version":3,"file":"feature.js","names":[],"sources":["../../src/core/feature.ts"],"sourcesContent":["import type { HocuspocusProvider } from '@hocuspocus/provider'\nimport type { AnyExtension, Editor, JSONContent } from '@tiptap/core'\nimport type { Node as PMNode, ResolvedPos } from '@tiptap/pm/model'\nimport type { EditorState, Transaction } from '@tiptap/pm/state'\nimport type { $Fetch } from 'ofetch'\nimport type * as Y from 'yjs'\nimport type { Locale, Translate } from '../i18n'\nimport type { EditorSettings } from '../settings'\nimport type { EditorAiConfig, EditorContext } from './context'\nimport type { ConvertTarget } from './convert'\nimport type { EditorUi } from './editor-ui'\nimport type { AbilitiesOptions, BlockAction, SlashCommandItem } from './extension-points'\nimport type { MetadataRegistry } from './metadata'\nimport type { Notifier } from './notify'\nimport type { EditorMetadata } from './metadata-types'\nimport type { Store } from './store'\nimport type { ToolbarGroup } from './toolbar'\n\n// The composition contracts: an `EditorFeature` contributes extensions and descriptors, `defineEditor` validates a\n// feature list into an immutable `EditorPreset`, and `EditorSurface` mounts one. Everything here is inert data and\n// types; features only differ by which of these seams they fill.\n\n/** Stores an uploaded file and returns its URL (media feature). */\nexport type UploadFn = (file: File) => Promise<{ url: string }>\n\n/**\n * The user writing in an editor: the collaboration session's `user`, labelled on remote carets, and (authors and comments\n * features) copied into the author mark of every text run and into every comment the user writes.\n */\nexport interface AuthorIdentity {\n  id: string\n  name: string\n  color: string\n}\n\n/** A host-owned collaboration session handed to the surface; only the collab feature turns it into extensions. */\nexport interface CollaborationSession {\n  ydoc: Y.Doc\n  provider?: HocuspocusProvider\n  user?: AuthorIdentity\n  /**\n   * Token the collaboration server's `EditorAdapter.authenticate` receives (`{ headers, token }`), for clients without\n   * the session cookie of the server's origin (scripts, agents, cross-origin hosts). A string, or a function called\n   * every time the socket opens (so it can refresh an expired token). Applied to `provider`'s configuration when the\n   * surface is set up, which the provider reads when its socket opens: create the provider and mount the surface in the\n   * same tick, or give the provider its own `token` option instead.\n   */\n  token?: string | (() => string) | (() => Promise<string>)\n}\n\n/**\n * A mapping between document positions and positions that survive collaborative edits. The collab feature supplies\n * the Yjs implementation; without one, `DocAnchors` maps positions through local transactions only.\n */\nexport interface AnchorResolver {\n  /** The transaction applies a Yjs change to the document: remote edits and Yjs undo/redo. */\n  isYSync: (tr: Transaction) => boolean\n  /** The transaction applies an edit of another client (excludes Yjs undo/redo). */\n  isRemoteChange: (tr: Transaction) => boolean\n  /** Opaque token of `range` that `resolve` can turn back into positions after remote changes; null when unavailable. */\n  capture: (state: EditorState, range: { from: number, to: number }, startInside: boolean) => unknown | null\n  resolve: (state: EditorState, token: unknown) => { from: number, to: number } | null\n  /** Stops undo capturing around a programmatic change; true iff a Yjs undo manager exists. */\n  stopUndoCapture: (state: EditorState) => boolean\n}\n\n/** Per-surface dependencies of a feature's factories. Created when a surface is set up; never shared between editors. */\nexport interface FeatureContext {\n  /** The app context the surface belongs to (shared by all editors of the app): app-level models key on it. */\n  readonly app: EditorContext\n  /** The app's shared settings (see `createEditorContext`): read with `get()`, write with `update()`, observe with `subscribe()`. */\n  readonly settings: Store<EditorSettings>\n  readonly metadata: MetadataRegistry\n  /** Chrome of the editor this context belongs to (settings, sidebar). */\n  readonly ui: EditorUi\n  /** Shows a notice through the surface's framework (Nuxt UI toast, sonner). */\n  readonly notify: Notifier\n  /** The app's UI language (`createEditorContext({ locale })`). */\n  readonly locale: Locale\n  /** Renders a catalog message in the app's language; every label a feature contributes goes through it. */\n  readonly t: Translate\n  readonly fetch: $Fetch\n  /** Inert public AI configuration of the app context; absent when none was supplied. */\n  readonly ai: EditorAiConfig | undefined\n  /** Document whose package stores uploads (media feature). */\n  readonly documentId: string | undefined\n  readonly upload: UploadFn | undefined\n  readonly collaboration: CollaborationSession | undefined\n  /** The collaboration-aware position mapping of the preset's `anchorResolver` feature; null means local mapping only. */\n  readonly anchorResolver: AnchorResolver | null\n  /** Host options for the ability extension (`abilities` prop). */\n  readonly abilities: Partial<AbilitiesOptions>\n  /** The final `/` menu (features' commands run through the host's `slashCommands` transformer). */\n  readonly slashCommands: () => SlashCommandItem[]\n  /** Undefined while extensions are constructed; set once the editor exists. Use it in event handlers. */\n  getEditor: () => Editor | undefined\n}\n\n/** A tab of the settings panel/modal, contributed by the feature that owns those settings. */\nexport interface SettingsTab<C = unknown> {\n  id: string\n  /** Already translated (`ctx.t(...)` in the feature's `settingsTabs` factory). */\n  label: string\n  icon?: string\n  component: C\n  /** Props handed to `component`, e.g. the configured composite kinds. */\n  props?: Record<string, unknown>\n}\n\n/** The stages `parseBlocks` and the import/AI insertion paths run; features replace stages, defaults are identity/Markdown. */\nexport interface BlockPipeline {\n  parseMarkdown: (editor: Editor, markdown: string) => JSONContent[]\n  normalize: (editor: Editor, blocks: JSONContent[]) => JSONContent[]\n  segment: (editor: Editor, blocks: JSONContent[]) => JSONContent[]\n  structure: (editor: Editor, blocks: JSONContent[]) => JSONContent[]\n  wrapImport: (editor: Editor, file: File, blocks: JSONContent[]) => JSONContent[]\n  migrateContent: (content: JSONContent) => JSONContent\n}\n\n/** Pipeline hooks that allow a single contributor; `normalize` chains instead. */\nexport const SINGLETON_PIPELINE_HOOKS = ['parseMarkdown', 'segment', 'structure', 'wrapImport', 'migrateContent'] as const satisfies readonly (keyof BlockPipeline)[]\n\n/**\n * A feature's block conversions. Targets keep the inert `ConvertTarget` shapes; the provider that parses a target id\n * owns that target (labels, execution). `handlesSource` claims all conversions of source blocks it understands.\n */\nexport interface ConversionProvider {\n  /** Source blocks this provider converts to any target it can; the first provider claiming a node executes. */\n  handlesSource?: (node: PMNode) => boolean\n  /** Targets offered for `node` in menus (excluding its current type). */\n  targets: (editor: Editor, node: PMNode) => ConvertTarget[]\n  /** The target of `id` when this provider owns it, else null. */\n  parseTarget: (id: string) => ConvertTarget | null\n  /** Menu label (in the language of `t`) and icon of a target this provider owns. */\n  label: (target: ConvertTarget, t: Translate) => { label: string, icon: string } | null\n  /** The conversion of the block after `start` into `target` (absolute range replaced and the converted blocks), or null. */\n  convert: (state: EditorState, start: ResolvedPos, target: ConvertTarget) => { from: number, to: number, blocks: PMNode[] } | null\n}\n\n/**\n * Inert public data AI reads about the editor's document model. A kind's `fields` carry what the model needs to write\n * them (`type`, and the choices of a `select`).\n */\nexport interface AiContextKind {\n  id: string\n  label: string\n  fields: readonly { key: string, label: string, type?: 'text' | 'textarea' | 'date' | 'number' | 'select', options?: readonly { value: string, label: string }[] }[]\n  /** The kind's `ai.purpose`, when configured. */\n  purpose?: string\n}\n\n/** A host block as AI learns it: what it is for, its Markdown form and one example. `id` is the node type name and the `convert` target id. */\nexport interface AiBlock {\n  id: string\n  label: string\n  /** One or two German sentences: purpose and what it may contain. */\n  description: string\n  /** The Markdown form, placeholders in angle brackets, e.g. `!!! <info|warning|success>\\n<Inhalt>`. */\n  syntax: string\n  /** One complete Markdown example of the block. */\n  example: string\n}\n\nexport interface AiContext {\n  kinds?: readonly AiContextKind[]\n  blocks?: readonly AiBlock[]\n  structure?: 'flat' | 'composite'\n}\n\n/** One piece of material a feature fetched for a block before the model fills it (a host's examples, a record). */\nexport interface AiBlockDatum { label: string, text: string }\nexport interface AiBlockDataRequest { editor: Editor, node: PMNode, pos: number, signal: AbortSignal }\n/** Material for one block; `signal` aborts when the editor is destroyed or the run is cancelled. */\nexport type AiBlockDataProvider = (request: AiBlockDataRequest) => Promise<readonly AiBlockDatum[]> | readonly AiBlockDatum[]\n\n/** One independently importable capability. Every member is optional; identity and ordering come from the feature list. */\nexport interface EditorFeature<C = unknown> {\n  id: string\n  /** Ids of features that must also be installed (`defineEditor` does not install them). */\n  requires?: readonly string[]\n  extensions?: (ctx: FeatureContext) => AnyExtension[]\n  toolbar?: (ctx: FeatureContext) => ToolbarGroup<C>[]\n  blockActions?: (ctx: FeatureContext) => BlockAction[]\n  slashCommands?: (ctx: FeatureContext) => SlashCommandItem[]\n  /** Components mounted beside the editor content; they receive `{ editor }`. `C` is the component type of the framework layer that renders them. */\n  overlays?: readonly C[]\n  /**\n   * Runs once when a surface mounts (per-app side effects, e.g. a theme runtime; dedupe inside). Returns the teardown,\n   * called when the surface unmounts; it must be idempotent (React StrictMode mounts twice).\n   */\n  setup?: (ctx: FeatureContext) => void | (() => void)\n  /** The feature's settings tabs. A factory over the app context, so labels render in the context's language. */\n  settingsTabs?: (ctx: EditorContext) => readonly SettingsTab<C>[]\n  /** Built-in metadata lists (`mentions`, `hashtags`, `speakers`, …) used for every list name the host does not supply; searched only when a suggestion uses them. */\n  metadataDefaults?: (ctx: FeatureContext) => EditorMetadata\n  blocks?: Partial<BlockPipeline>\n  conversions?: readonly ConversionProvider[]\n  /** At most one contributor: supplies the collaboration-aware position mapping to `DocAnchors`. */\n  anchorResolver?: (ctx: FeatureContext) => AnchorResolver\n  /** Additive: the contributions of all features are merged (`kinds` and `blocks` concatenated in feature order; `structure` may be set by one feature only). Reads AI's view of the document model. */\n  aiContext?: (editor: Editor) => AiContext\n  /** Additive: every contributor runs for the block (in parallel), their data concatenate in feature order; one rejection fails the whole fill. Read by „Baustein füllen (KI)“. */\n  aiBlockData?: AiBlockDataProvider\n  /** At most one contributor: formats an AI result's markdown before the generic pipeline. */\n  formatAiResult?: (editor: Editor, markdown: string, heading?: string) => string\n}\n\n/** An immutable, validated feature list with its resolved pipeline, conversion providers and AI hooks. */\nexport interface EditorPreset<C = unknown> {\n  readonly features: readonly EditorFeature<C>[]\n  readonly pipeline: BlockPipeline\n  readonly conversions: readonly ConversionProvider[]\n  /** All `aiContext` contributions merged (`aiContextOf`). */\n  readonly aiContext?: EditorFeature['aiContext']\n  /** All `aiBlockData` contributions merged (`aiBlockDataOf`). */\n  readonly aiBlockData?: AiBlockDataProvider\n  /** The single `formatAiResult` contributor, if any. */\n  readonly formatAiResult?: EditorFeature['formatAiResult']\n}\n"],"mappings":";;AAwHA,MAAa,2BAA2B;CAAC;CAAiB;CAAW;CAAa;CAAc;AAAgB"}
+{"version":3,"file":"feature.js","names":[],"sources":["../../src/core/feature.ts"],"sourcesContent":["import type { HocuspocusProvider } from '@hocuspocus/provider'\nimport type { AnyExtension, Editor, JSONContent } from '@tiptap/core'\nimport type { Node as PMNode, ResolvedPos } from '@tiptap/pm/model'\nimport type { EditorState, Transaction } from '@tiptap/pm/state'\nimport type * as Y from 'yjs'\nimport type { Locale, Translate } from '../i18n'\nimport type { EditorSettings } from '../settings'\nimport type { EditorBackend } from './backend'\nimport type { BackendCapability } from './backend-capability'\nimport type { EditorAiConfig, EditorContext } from './context'\nimport type { ConvertTarget } from './convert'\nimport type { EditorUi } from './editor-ui'\nimport type { AbilitiesOptions, BlockAction } from './extension-points'\nimport type { MetadataRegistry } from './metadata'\nimport type { CommandDef, InsertGuard, ToolbarGroupDef } from './command-types'\nimport type { Notifier } from './notify'\nimport type { EditorMetadata } from './metadata-types'\nimport type { Store } from './store'\n\n// The composition contracts: an `EditorFeature` contributes extensions and descriptors, `defineEditor` validates a\n// feature list into an immutable `EditorPreset`, and `EditorSurface` mounts one. Everything here is inert data and\n// types; features only differ by which of these seams they fill.\n\n/**\n * The user writing in an editor: the collaboration session's `user`, labelled on remote carets, and (authors and comments\n * features) copied into the author mark of every text run and into every comment the user writes.\n */\nexport interface AuthorIdentity {\n  id: string\n  name: string\n  color: string\n}\n\n/** A host-owned collaboration session handed to the surface; only the collab feature turns it into extensions. */\nexport interface CollaborationSession {\n  ydoc: Y.Doc\n  provider?: HocuspocusProvider\n  user?: AuthorIdentity\n  /**\n   * Token the collaboration server's `Identity.authenticate` receives (`{ headers, token }`), for clients without\n   * the session cookie of the server's origin (scripts, agents, cross-origin hosts). A string, or a function called\n   * every time the socket opens (so it can refresh an expired token). Applied to `provider`'s configuration when the\n   * surface is set up, which the provider reads when its socket opens: create the provider and mount the surface in the\n   * same tick, or give the provider its own `token` option instead.\n   */\n  token?: string | (() => string) | (() => Promise<string>)\n}\n\n/**\n * A mapping between document positions and positions that survive collaborative edits. The collab feature supplies\n * the Yjs implementation; without one, `DocAnchors` maps positions through local transactions only.\n */\nexport interface AnchorResolver {\n  /** The transaction applies a Yjs change to the document: remote edits and Yjs undo/redo. */\n  isYSync: (tr: Transaction) => boolean\n  /** The transaction applies an edit of another client (excludes Yjs undo/redo). */\n  isRemoteChange: (tr: Transaction) => boolean\n  /** Opaque token of `range` that `resolve` can turn back into positions after remote changes; null when unavailable. */\n  capture: (state: EditorState, range: { from: number, to: number }, startInside: boolean) => unknown | null\n  resolve: (state: EditorState, token: unknown) => { from: number, to: number } | null\n  /** Stops undo capturing around a programmatic change; true iff a Yjs undo manager exists. */\n  stopUndoCapture: (state: EditorState) => boolean\n}\n\n/** Per-surface dependencies of a feature's factories. Created when a surface is set up; never shared between editors. */\nexport interface FeatureContext {\n  /** The app context the surface belongs to (shared by all editors of the app): app-level models key on it. */\n  readonly app: EditorContext\n  /** The app's shared settings (see `createEditorContext`): read with `get()`, write with `update()`, observe with `subscribe()`. */\n  readonly settings: Store<EditorSettings>\n  readonly metadata: MetadataRegistry\n  /** Chrome of the editor this context belongs to (settings, sidebar). */\n  readonly ui: EditorUi\n  /** Shows a notice through the surface's framework (Nuxt UI toast, sonner). */\n  readonly notify: Notifier\n  /** The app's UI language (`createEditorContext({ locale })`). */\n  readonly locale: Locale\n  /** Renders a catalog message in the app's language; every label a feature contributes goes through it. */\n  readonly t: Translate\n  /** The data layer of the app (`createEditorContext({ backend })`): uploads, mention lookups, themes, AI. */\n  readonly backend: EditorBackend\n  /** Inert public AI configuration of the app context; absent when none was supplied. */\n  readonly ai: EditorAiConfig | undefined\n  /** Document whose package stores uploads (media feature). */\n  readonly documentId: string | undefined\n  readonly collaboration: CollaborationSession | undefined\n  /** The collaboration-aware position mapping of the preset's `anchorResolver` feature; null means local mapping only. */\n  readonly anchorResolver: AnchorResolver | null\n  /** Host options for the ability extension (`abilities` prop). */\n  readonly abilities: Partial<AbilitiesOptions>\n  /** The final command list: the features' commands after the host's `commands` transformer. The `/` menu lists the ones with a `slash` placement. */\n  readonly commands: () => CommandDef[]\n  /** Undefined while extensions are constructed; set once the editor exists. Use it in event handlers. */\n  getEditor: () => Editor | undefined\n}\n\n/** A tab of the settings panel/modal, contributed by the feature that owns those settings. */\nexport interface SettingsTab<C = unknown> {\n  id: string\n  /** Already translated (`ctx.t(...)` in the feature's `settingsTabs` factory). */\n  label: string\n  icon?: string\n  component: C\n  /** Props handed to `component`, e.g. the configured composite kinds. */\n  props?: Record<string, unknown>\n}\n\n/** The stages `parseBlocks` and the import/AI insertion paths run; features replace stages, defaults are identity/Markdown. */\nexport interface BlockPipeline {\n  parseMarkdown: (editor: Editor, markdown: string) => JSONContent[]\n  normalize: (editor: Editor, blocks: JSONContent[]) => JSONContent[]\n  segment: (editor: Editor, blocks: JSONContent[]) => JSONContent[]\n  structure: (editor: Editor, blocks: JSONContent[]) => JSONContent[]\n  wrapImport: (editor: Editor, file: File, blocks: JSONContent[]) => JSONContent[]\n  migrateContent: (content: JSONContent) => JSONContent\n}\n\n/** Pipeline hooks that allow a single contributor; `normalize` chains instead. */\nexport const SINGLETON_PIPELINE_HOOKS = ['parseMarkdown', 'segment', 'structure', 'wrapImport', 'migrateContent'] as const satisfies readonly (keyof BlockPipeline)[]\n\n/**\n * A feature's block conversions. Targets keep the inert `ConvertTarget` shapes; the provider that parses a target id\n * owns that target (labels, execution). `handlesSource` claims all conversions of source blocks it understands.\n */\nexport interface ConversionProvider {\n  /** Source blocks this provider converts to any target it can; the first provider claiming a node executes. */\n  handlesSource?: (node: PMNode) => boolean\n  /** Targets offered for `node` in menus (excluding its current type). */\n  targets: (editor: Editor, node: PMNode) => ConvertTarget[]\n  /** The target of `id` when this provider owns it, else null. */\n  parseTarget: (id: string) => ConvertTarget | null\n  /** Menu label (in the language of `t`) and icon of a target this provider owns. */\n  label: (target: ConvertTarget, t: Translate) => { label: string, icon: string } | null\n  /** The conversion of the block after `start` into `target` (absolute range replaced and the converted blocks), or null. */\n  convert: (state: EditorState, start: ResolvedPos, target: ConvertTarget) => { from: number, to: number, blocks: PMNode[] } | null\n}\n\n/**\n * Inert public data AI reads about the editor's document model. A kind's `fields` carry what the model needs to write\n * them (`type`, and the choices of a `select`).\n */\nexport interface AiContextKind {\n  id: string\n  label: string\n  fields: readonly { key: string, label: string, type?: 'text' | 'textarea' | 'date' | 'number' | 'select' | 'reference' | 'bibliography' | 'derivation', options?: readonly { value: string, label: string }[] }[]\n  /** The kind's `ai.purpose`, when configured. */\n  purpose?: string\n}\n\n/** A host block as AI learns it: what it is for, its Markdown form and one example. `id` is the node type name and the `convert` target id. */\nexport interface AiBlock {\n  id: string\n  label: string\n  /** One or two German sentences: purpose and what it may contain. */\n  description: string\n  /** The Markdown form, placeholders in angle brackets, e.g. `!!! <info|warning|success>\\n<Inhalt>`. */\n  syntax: string\n  /** One complete Markdown example of the block. */\n  example: string\n}\n\nexport interface AiContext {\n  kinds?: readonly AiContextKind[]\n  blocks?: readonly AiBlock[]\n  structure?: 'flat' | 'composite'\n}\n\n/** One piece of material a feature fetched for a block before the model fills it (a host's examples, a record). */\nexport interface AiBlockDatum { label: string, text: string }\nexport interface AiBlockDataRequest { editor: Editor, node: PMNode, pos: number, signal: AbortSignal }\n/** Material for one block; `signal` aborts when the editor is destroyed or the run is cancelled. */\nexport type AiBlockDataProvider = (request: AiBlockDataRequest) => Promise<readonly AiBlockDatum[]> | readonly AiBlockDatum[]\n\n/**\n * The axis a feature belongs to: `content` (nodes, marks and structure rules the document stores: the server schema comes\n * from here), `interaction` (editing UX, backend-bound UI such as comments and collaboration) or `ai`. A feature\n * belongs to the dimension without which it makes no sense.\n */\nexport type Dimension = 'content' | 'interaction' | 'ai'\n\n/** One named contribution to an editor (blocks, toolbar entries, menus, settings, AI knowledge). Every member is optional but `dimension`; identity and ordering come from the feature list. */\nexport interface EditorFeature<C = unknown> {\n  id: string\n  /** The feature's primary dimension. */\n  dimension: Dimension\n  /**\n   * The Vue-free schema-bearing extensions of this feature (no node views, no UI), collected by `schemaExtensionsOf` for\n   * the server schema. Present on every feature whose nodes or marks the stored document can contain.\n   */\n  schemaExtensions?: () => AnyExtension[]\n  /** Ids of features that must also be installed (`defineEditor` does not install them). */\n  requires?: readonly string[]\n  /** Backend capabilities the feature cannot work without; a surface session over a backend lacking one throws. Optional capabilities (users and tags for mentions) are not listed. */\n  backend?: readonly BackendCapability[]\n  extensions?: (ctx: FeatureContext) => AnyExtension[]\n  blockActions?: (ctx: FeatureContext) => BlockAction[]\n  /** The feature's commands, each declared once with its toolbar and `/` placements (see `CommandDef`). */\n  commands?: (ctx: FeatureContext) => CommandDef<C>[]\n  /** Toolbar groups the feature declares; every command's `toolbar.group` must be declared by some feature. Ids are unique across features. */\n  toolbarGroups?: ToolbarGroupDef[]\n  /** Rules a command's `creates` must pass at the caret besides the schema (e.g. a Baustein's accepted children). */\n  insertGuards?: (ctx: FeatureContext) => InsertGuard[]\n  /** Components mounted beside the editor content; they receive `{ editor }`. `C` is the component type of the framework layer that renders them. */\n  overlays?: readonly C[]\n  /**\n   * Runs once when a surface mounts (per-app side effects, e.g. a theme runtime; dedupe inside). Returns the teardown,\n   * called when the surface unmounts; it must be idempotent (React StrictMode mounts twice).\n   */\n  setup?: (ctx: FeatureContext) => void | (() => void)\n  /** The feature's settings tabs. A factory over the app context, so labels render in the context's language. */\n  settingsTabs?: (ctx: EditorContext) => readonly SettingsTab<C>[]\n  /** Built-in metadata lists (`mentions`, `hashtags`, `speakers`, …) used for every list name the host does not supply; searched only when a suggestion uses them. */\n  metadataDefaults?: (ctx: FeatureContext) => EditorMetadata\n  blocks?: Partial<BlockPipeline>\n  conversions?: readonly ConversionProvider[]\n  /** At most one contributor: supplies the collaboration-aware position mapping to `DocAnchors`. */\n  anchorResolver?: (ctx: FeatureContext) => AnchorResolver\n  /** Additive: the contributions of all features are merged (`kinds` and `blocks` concatenated in feature order; `structure` may be set by one feature only). Reads AI's view of the document model. */\n  aiContext?: (editor: Editor) => AiContext\n  /** Additive: every contributor runs for the block (in parallel), their data concatenate in feature order; one rejection fails the whole fill. Read by „Baustein füllen (KI)“. */\n  aiBlockData?: AiBlockDataProvider\n  /** At most one contributor: formats an AI result's markdown before the generic pipeline. */\n  formatAiResult?: (editor: Editor, markdown: string, heading?: string) => string\n}\n\n/** An immutable, validated feature list with its resolved pipeline, conversion providers and AI hooks. */\nexport interface EditorPreset<C = unknown> {\n  readonly features: readonly EditorFeature<C>[]\n  readonly pipeline: BlockPipeline\n  readonly conversions: readonly ConversionProvider[]\n  /** All `aiContext` contributions merged (`aiContextOf`). */\n  readonly aiContext?: EditorFeature['aiContext']\n  /** All `aiBlockData` contributions merged (`aiBlockDataOf`). */\n  readonly aiBlockData?: AiBlockDataProvider\n  /** The single `formatAiResult` contributor, if any. */\n  readonly formatAiResult?: EditorFeature['formatAiResult']\n}\n"],"mappings":";;AAsHA,MAAa,2BAA2B;CAAC;CAAiB;CAAW;CAAa;CAAc;AAAgB"}

package/dist/core/fences.d.ts

@@ -1,8 +1,9 @@
 import { JSONContent } from "@tiptap/core";
 //#region src/core/fences.d.ts
-/** A well-formed fence: its kind, JSON meta, inner text and the exact source text, opener line through closer line. */
+/** A well-formed fence: its kind, optional block id (`#id` after the kind), JSON meta, inner text and the exact source text, opener line through closer line. */
 export interface CompositeFence {
   kind: string;
+  id?: string;
   meta: Record<string, unknown>;
   inner: string;
   raw: string;

package/dist/core/fences.js

@@ -1,5 +1,5 @@
 //#region src/core/fences.ts
-const OPENER = /^\s*:::[ \t]*([\p{L}\p{N}_-]+)[ \t]*(\{.*\})?[ \t]*$/u;
+const OPENER = /^\s*:::[ \t]*([\p{L}\p{N}_-]+)(?:[ \t]+#([0-9a-f-]{36}))?[ \t]*(\{.*\})?[ \t]*$/u;
 const CLOSER = /^\s*:::\s*$/;
 const CODE_FENCE = /^ {0,3}(`{3,}|~{3,})/;
 function parseMeta(json) {
@@ -46,7 +46,7 @@ function splitFences(markdown) {
 	while (i < lines.length) {
 		const line = lines[i];
 		const match = code[i] ? null : OPENER.exec(line);
-		const meta = match ? parseMeta(match[2]) : null;
+		const meta = match ? parseMeta(match[3]) : null;
 		if (!match || !meta) {
 			if (match) problems.push({
 				code: "invalid-fence-meta",
@@ -77,6 +77,7 @@ function splitFences(markdown) {
 		flush();
 		segments.push({
 			kind: match[1],
+			...match[2] && { id: match[2] },
 			meta,
 			inner: lines.slice(i + 1, end).join("\n"),
 			raw: lines.slice(i, end + 1).join("\n")

package/dist/core/fences.js.map

@@ -1 +1 @@
-{"version":3,"file":"fences.js","names":[],"sources":["../../src/core/fences.ts"],"sourcesContent":["import type { JSONContent } from '@tiptap/core'\n\n// The `::: kind {meta}` … `:::` fence grammar of Markdown documents, shared by the composite feature (registered kinds\n// become composites) and the Markdown entry (every other kind stays an `opaqueFence`). Nested fences close with the\n// same bare `:::`, so a closer always ends the innermost open fence. Lines inside ``` / ~~~ code fences are never fence\n// syntax.\n\n/** A well-formed fence: its kind, JSON meta, inner text and the exact source text, opener line through closer line. */\nexport interface CompositeFence { kind: string, meta: Record<string, unknown>, inner: string, raw: string }\nexport type FenceSegment = { markdown: string } | CompositeFence\n\n/** A fence-like construct that did not become a fence: `invalid-fence-meta` (the `{…}` after the kind is no JSON object) or `unclosed-fence` (no matching `:::`). `line` is 1-based. */\nexport interface FenceProblem { code: 'invalid-fence-meta' | 'unclosed-fence', line: number, kind: string }\n\nconst OPENER = /^\\s*:::[ \\t]*([\\p{L}\\p{N}_-]+)[ \\t]*(\\{.*\\})?[ \\t]*$/u\nconst CLOSER = /^\\s*:::\\s*$/\nconst CODE_FENCE = /^ {0,3}(`{3,}|~{3,})/\n\nfunction parseMeta(json: string | undefined): Record<string, unknown> | null {\n  if (!json) return {}\n  try {\n    const value: unknown = JSON.parse(json)\n    return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : null\n  }\n  catch {\n    return null\n  }\n}\n\n/** For every line whether it is part of a ``` / ~~~ code fence (the fence lines included). */\nfunction codeLines(lines: readonly string[]): boolean[] {\n  const inside: boolean[] = []\n  let open: { char: string, length: number } | null = null\n  for (const line of lines) {\n    const match = CODE_FENCE.exec(line)\n    if (!open) {\n      if (match) open = { char: match[1]![0]!, length: match[1]!.length }\n      inside.push(open !== null)\n      continue\n    }\n    inside.push(true)\n    const closing = /^ {0,3}(`{3,}|~{3,})\\s*$/.exec(line)\n    if (closing && closing[1]![0] === open.char && closing[1]!.length >= open.length) open = null\n  }\n  return inside\n}\n\n/** Splits `::: kind {json}` … `:::` fences (nestable) into segments; text outside fences stays markdown. `problems` lists the opener lines that stayed plain text. */\nexport function splitFences(markdown: string): { segments: FenceSegment[], problems: FenceProblem[] } {\n  const lines = markdown.split('\\n')\n  const code = codeLines(lines)\n  const segments: FenceSegment[] = []\n  const problems: FenceProblem[] = []\n  let plain: string[] = []\n  const flush = () => {\n    if (plain.join('').trim()) segments.push({ markdown: plain.join('\\n') })\n    plain = []\n  }\n  let i = 0\n  while (i < lines.length) {\n    const line = lines[i]!\n    const match = code[i] ? null : OPENER.exec(line)\n    const meta = match ? parseMeta(match[2]) : null\n    if (!match || !meta) {\n      if (match) problems.push({ code: 'invalid-fence-meta', line: i + 1, kind: match[1]! })\n      plain.push(line)\n      i++\n      continue\n    }\n    // Find the matching closer, counting nested openers; none → the opener line stays plain text.\n    let depth = 1\n    let end = i + 1\n    for (; end < lines.length; end++) {\n      if (code[end]) continue\n      if (OPENER.test(lines[end]!)) depth++\n      else if (CLOSER.test(lines[end]!) && --depth === 0) break\n    }\n    if (depth) {\n      problems.push({ code: 'unclosed-fence', line: i + 1, kind: match[1]! })\n      plain.push(line)\n      i++\n      continue\n    }\n    flush()\n    segments.push({ kind: match[1]!, meta, inner: lines.slice(i + 1, end).join('\\n'), raw: lines.slice(i, end + 1).join('\\n') })\n    i = end + 1\n  }\n  flush()\n  return { segments, problems }\n}\n\n/** The fences of `markdown` (see `splitFences`) without the problem report. */\nexport const splitCompositeFences = (markdown: string): FenceSegment[] => splitFences(markdown).segments\n\n/** An opaque fence node: `raw` is the fence's source text, written back verbatim by the Markdown serializer. */\nexport const opaqueFenceJSON = (fence: CompositeFence): JSONContent => ({ type: 'opaqueFence', attrs: { kind: fence.kind, raw: fence.raw } })\n"],"mappings":";AAcA,MAAM,SAAS;AACf,MAAM,SAAS;AACf,MAAM,aAAa;AAEnB,SAAS,UAAU,MAA0D;CAC3E,IAAI,CAAC,MAAM,OAAO,CAAC;CACnB,IAAI;EACF,MAAM,QAAiB,KAAK,MAAM,IAAI;EACtC,OAAO,SAAS,OAAO,UAAU,YAAY,CAAC,MAAM,QAAQ,KAAK,IAAI,QAAmC;CAC1G,QACM;EACJ,OAAO;CACT;AACF;;AAGA,SAAS,UAAU,OAAqC;CACtD,MAAM,SAAoB,CAAC;CAC3B,IAAI,OAAgD;CACpD,KAAK,MAAM,QAAQ,OAAO;EACxB,MAAM,QAAQ,WAAW,KAAK,IAAI;EAClC,IAAI,CAAC,MAAM;GACT,IAAI,OAAO,OAAO;IAAE,MAAM,MAAM,EAAE,CAAE;IAAK,QAAQ,MAAM,EAAE,CAAE;GAAO;GAClE,OAAO,KAAK,SAAS,IAAI;GACzB;EACF;EACA,OAAO,KAAK,IAAI;EAChB,MAAM,UAAU,2BAA2B,KAAK,IAAI;EACpD,IAAI,WAAW,QAAQ,EAAE,CAAE,OAAO,KAAK,QAAQ,QAAQ,EAAE,CAAE,UAAU,KAAK,QAAQ,OAAO;CAC3F;CACA,OAAO;AACT;;AAGA,SAAgB,YAAY,UAA0E;CACpG,MAAM,QAAQ,SAAS,MAAM,IAAI;CACjC,MAAM,OAAO,UAAU,KAAK;CAC5B,MAAM,WAA2B,CAAC;CAClC,MAAM,WAA2B,CAAC;CAClC,IAAI,QAAkB,CAAC;CACvB,MAAM,cAAc;EAClB,IAAI,MAAM,KAAK,EAAE,CAAC,CAAC,KAAK,GAAG,SAAS,KAAK,EAAE,UAAU,MAAM,KAAK,IAAI,EAAE,CAAC;EACvE,QAAQ,CAAC;CACX;CACA,IAAI,IAAI;CACR,OAAO,IAAI,MAAM,QAAQ;EACvB,MAAM,OAAO,MAAM;EACnB,MAAM,QAAQ,KAAK,KAAK,OAAO,OAAO,KAAK,IAAI;EAC/C,MAAM,OAAO,QAAQ,UAAU,MAAM,EAAE,IAAI;EAC3C,IAAI,CAAC,SAAS,CAAC,MAAM;GACnB,IAAI,OAAO,SAAS,KAAK;IAAE,MAAM;IAAsB,MAAM,IAAI;IAAG,MAAM,MAAM;GAAI,CAAC;GACrF,MAAM,KAAK,IAAI;GACf;GACA;EACF;EAEA,IAAI,QAAQ;EACZ,IAAI,MAAM,IAAI;EACd,OAAO,MAAM,MAAM,QAAQ,OAAO;GAChC,IAAI,KAAK,MAAM;GACf,IAAI,OAAO,KAAK,MAAM,IAAK,GAAG;QACzB,IAAI,OAAO,KAAK,MAAM,IAAK,KAAK,EAAE,UAAU,GAAG;EACtD;EACA,IAAI,OAAO;GACT,SAAS,KAAK;IAAE,MAAM;IAAkB,MAAM,IAAI;IAAG,MAAM,MAAM;GAAI,CAAC;GACtE,MAAM,KAAK,IAAI;GACf;GACA;EACF;EACA,MAAM;EACN,SAAS,KAAK;GAAE,MAAM,MAAM;GAAK;GAAM,OAAO,MAAM,MAAM,IAAI,GAAG,GAAG,CAAC,CAAC,KAAK,IAAI;GAAG,KAAK,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI;EAAE,CAAC;EAC3H,IAAI,MAAM;CACZ;CACA,MAAM;CACN,OAAO;EAAE;EAAU;CAAS;AAC9B;;AAGA,MAAa,wBAAwB,aAAqC,YAAY,QAAQ,CAAC,CAAC;;AAGhG,MAAa,mBAAmB,WAAwC;CAAE,MAAM;CAAe,OAAO;EAAE,MAAM,MAAM;EAAM,KAAK,MAAM;CAAI;AAAE"}
+{"version":3,"file":"fences.js","names":[],"sources":["../../src/core/fences.ts"],"sourcesContent":["import type { JSONContent } from '@tiptap/core'\n\n// The `::: kind #id {meta}` … `:::` fence grammar of Markdown documents, shared by the composite feature (registered kinds\n// become composites) and the Markdown entry (every other kind stays an `opaqueFence`). `#id` (optional, Pandoc-like) is\n// the block id of the fenced composite; `{meta}` is a JSON object. Nested fences close with the\n// same bare `:::`, so a closer always ends the innermost open fence. Lines inside ``` / ~~~ code fences are never fence\n// syntax.\n\n/** A well-formed fence: its kind, optional block id (`#id` after the kind), JSON meta, inner text and the exact source text, opener line through closer line. */\nexport interface CompositeFence { kind: string, id?: string, meta: Record<string, unknown>, inner: string, raw: string }\nexport type FenceSegment = { markdown: string } | CompositeFence\n\n/** A fence-like construct that did not become a fence: `invalid-fence-meta` (the `{…}` after the kind is no JSON object) or `unclosed-fence` (no matching `:::`). `line` is 1-based. */\nexport interface FenceProblem { code: 'invalid-fence-meta' | 'unclosed-fence', line: number, kind: string }\n\nconst OPENER = /^\\s*:::[ \\t]*([\\p{L}\\p{N}_-]+)(?:[ \\t]+#([0-9a-f-]{36}))?[ \\t]*(\\{.*\\})?[ \\t]*$/u\nconst CLOSER = /^\\s*:::\\s*$/\nconst CODE_FENCE = /^ {0,3}(`{3,}|~{3,})/\n\nfunction parseMeta(json: string | undefined): Record<string, unknown> | null {\n  if (!json) return {}\n  try {\n    const value: unknown = JSON.parse(json)\n    return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : null\n  }\n  catch {\n    return null\n  }\n}\n\n/** For every line whether it is part of a ``` / ~~~ code fence (the fence lines included). */\nfunction codeLines(lines: readonly string[]): boolean[] {\n  const inside: boolean[] = []\n  let open: { char: string, length: number } | null = null\n  for (const line of lines) {\n    const match = CODE_FENCE.exec(line)\n    if (!open) {\n      if (match) open = { char: match[1]![0]!, length: match[1]!.length }\n      inside.push(open !== null)\n      continue\n    }\n    inside.push(true)\n    const closing = /^ {0,3}(`{3,}|~{3,})\\s*$/.exec(line)\n    if (closing && closing[1]![0] === open.char && closing[1]!.length >= open.length) open = null\n  }\n  return inside\n}\n\n/** Splits `::: kind {json}` … `:::` fences (nestable) into segments; text outside fences stays markdown. `problems` lists the opener lines that stayed plain text. */\nexport function splitFences(markdown: string): { segments: FenceSegment[], problems: FenceProblem[] } {\n  const lines = markdown.split('\\n')\n  const code = codeLines(lines)\n  const segments: FenceSegment[] = []\n  const problems: FenceProblem[] = []\n  let plain: string[] = []\n  const flush = () => {\n    if (plain.join('').trim()) segments.push({ markdown: plain.join('\\n') })\n    plain = []\n  }\n  let i = 0\n  while (i < lines.length) {\n    const line = lines[i]!\n    const match = code[i] ? null : OPENER.exec(line)\n    const meta = match ? parseMeta(match[3]) : null\n    if (!match || !meta) {\n      if (match) problems.push({ code: 'invalid-fence-meta', line: i + 1, kind: match[1]! })\n      plain.push(line)\n      i++\n      continue\n    }\n    // Find the matching closer, counting nested openers; none → the opener line stays plain text.\n    let depth = 1\n    let end = i + 1\n    for (; end < lines.length; end++) {\n      if (code[end]) continue\n      if (OPENER.test(lines[end]!)) depth++\n      else if (CLOSER.test(lines[end]!) && --depth === 0) break\n    }\n    if (depth) {\n      problems.push({ code: 'unclosed-fence', line: i + 1, kind: match[1]! })\n      plain.push(line)\n      i++\n      continue\n    }\n    flush()\n    segments.push({ kind: match[1]!, ...(match[2] && { id: match[2] }), meta, inner: lines.slice(i + 1, end).join('\\n'), raw: lines.slice(i, end + 1).join('\\n') })\n    i = end + 1\n  }\n  flush()\n  return { segments, problems }\n}\n\n/** The fences of `markdown` (see `splitFences`) without the problem report. */\nexport const splitCompositeFences = (markdown: string): FenceSegment[] => splitFences(markdown).segments\n\n/** An opaque fence node: `raw` is the fence's source text, written back verbatim by the Markdown serializer. */\nexport const opaqueFenceJSON = (fence: CompositeFence): JSONContent => ({ type: 'opaqueFence', attrs: { kind: fence.kind, raw: fence.raw } })\n"],"mappings":";AAeA,MAAM,SAAS;AACf,MAAM,SAAS;AACf,MAAM,aAAa;AAEnB,SAAS,UAAU,MAA0D;CAC3E,IAAI,CAAC,MAAM,OAAO,CAAC;CACnB,IAAI;EACF,MAAM,QAAiB,KAAK,MAAM,IAAI;EACtC,OAAO,SAAS,OAAO,UAAU,YAAY,CAAC,MAAM,QAAQ,KAAK,IAAI,QAAmC;CAC1G,QACM;EACJ,OAAO;CACT;AACF;;AAGA,SAAS,UAAU,OAAqC;CACtD,MAAM,SAAoB,CAAC;CAC3B,IAAI,OAAgD;CACpD,KAAK,MAAM,QAAQ,OAAO;EACxB,MAAM,QAAQ,WAAW,KAAK,IAAI;EAClC,IAAI,CAAC,MAAM;GACT,IAAI,OAAO,OAAO;IAAE,MAAM,MAAM,EAAE,CAAE;IAAK,QAAQ,MAAM,EAAE,CAAE;GAAO;GAClE,OAAO,KAAK,SAAS,IAAI;GACzB;EACF;EACA,OAAO,KAAK,IAAI;EAChB,MAAM,UAAU,2BAA2B,KAAK,IAAI;EACpD,IAAI,WAAW,QAAQ,EAAE,CAAE,OAAO,KAAK,QAAQ,QAAQ,EAAE,CAAE,UAAU,KAAK,QAAQ,OAAO;CAC3F;CACA,OAAO;AACT;;AAGA,SAAgB,YAAY,UAA0E;CACpG,MAAM,QAAQ,SAAS,MAAM,IAAI;CACjC,MAAM,OAAO,UAAU,KAAK;CAC5B,MAAM,WAA2B,CAAC;CAClC,MAAM,WAA2B,CAAC;CAClC,IAAI,QAAkB,CAAC;CACvB,MAAM,cAAc;EAClB,IAAI,MAAM,KAAK,EAAE,CAAC,CAAC,KAAK,GAAG,SAAS,KAAK,EAAE,UAAU,MAAM,KAAK,IAAI,EAAE,CAAC;EACvE,QAAQ,CAAC;CACX;CACA,IAAI,IAAI;CACR,OAAO,IAAI,MAAM,QAAQ;EACvB,MAAM,OAAO,MAAM;EACnB,MAAM,QAAQ,KAAK,KAAK,OAAO,OAAO,KAAK,IAAI;EAC/C,MAAM,OAAO,QAAQ,UAAU,MAAM,EAAE,IAAI;EAC3C,IAAI,CAAC,SAAS,CAAC,MAAM;GACnB,IAAI,OAAO,SAAS,KAAK;IAAE,MAAM;IAAsB,MAAM,IAAI;IAAG,MAAM,MAAM;GAAI,CAAC;GACrF,MAAM,KAAK,IAAI;GACf;GACA;EACF;EAEA,IAAI,QAAQ;EACZ,IAAI,MAAM,IAAI;EACd,OAAO,MAAM,MAAM,QAAQ,OAAO;GAChC,IAAI,KAAK,MAAM;GACf,IAAI,OAAO,KAAK,MAAM,IAAK,GAAG;QACzB,IAAI,OAAO,KAAK,MAAM,IAAK,KAAK,EAAE,UAAU,GAAG;EACtD;EACA,IAAI,OAAO;GACT,SAAS,KAAK;IAAE,MAAM;IAAkB,MAAM,IAAI;IAAG,MAAM,MAAM;GAAI,CAAC;GACtE,MAAM,KAAK,IAAI;GACf;GACA;EACF;EACA,MAAM;EACN,SAAS,KAAK;GAAE,MAAM,MAAM;GAAK,GAAI,MAAM,MAAM,EAAE,IAAI,MAAM,GAAG;GAAI;GAAM,OAAO,MAAM,MAAM,IAAI,GAAG,GAAG,CAAC,CAAC,KAAK,IAAI;GAAG,KAAK,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI;EAAE,CAAC;EAC9J,IAAI,MAAM;CACZ;CACA,MAAM;CACN,OAAO;EAAE;EAAU;CAAS;AAC9B;;AAGA,MAAa,wBAAwB,aAAqC,YAAY,QAAQ,CAAC,CAAC;;AAGhG,MAAa,mBAAmB,WAAwC;CAAE,MAAM;CAAe,OAAO;EAAE,MAAM,MAAM;EAAM,KAAK,MAAM;CAAI;AAAE"}

package/dist/core/fetch-error.d.ts

@@ -1,5 +1,5 @@
 //#region src/core/fetch-error.d.ts
-/** Human-readable message for a failed HTTP request: the server's error message if it sent one. */
+/** Human-readable message for a failed request: a `BackendError`'s message, else the server's error message if it sent one. */
 export declare function fetchErrorMessage(error: unknown): string;
 //#endregion
 //# sourceMappingURL=fetch-error.d.ts.map

package/dist/core/fetch-error.js

@@ -1,6 +1,8 @@
+import { BackendError } from "./backend.js";
 //#region src/core/fetch-error.ts
-/** Human-readable message for a failed HTTP request: the server's error message if it sent one. */
+/** Human-readable message for a failed request: a `BackendError`'s message, else the server's error message if it sent one. */
 function fetchErrorMessage(error) {
+	if (error instanceof BackendError) return error.message;
 	const serverMessage = error?.data?.message;
 	if (typeof serverMessage === "string" && serverMessage) return serverMessage;
 	return error instanceof Error ? error.message : String(error);

package/dist/core/fetch-error.js.map

@@ -1 +1 @@
-{"version":3,"file":"fetch-error.js","names":[],"sources":["../../src/core/fetch-error.ts"],"sourcesContent":["/** Human-readable message for a failed HTTP request: the server's error message if it sent one. */\nexport function fetchErrorMessage(error: unknown): string {\n  const serverMessage = (error as { data?: { message?: unknown } } | null)?.data?.message\n  if (typeof serverMessage === 'string' && serverMessage) return serverMessage\n  return error instanceof Error ? error.message : String(error)\n}\n"],"mappings":";;AACA,SAAgB,kBAAkB,OAAwB;CACxD,MAAM,gBAAiB,OAAmD,MAAM;CAChF,IAAI,OAAO,kBAAkB,YAAY,eAAe,OAAO;CAC/D,OAAO,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AAC9D"}
+{"version":3,"file":"fetch-error.js","names":[],"sources":["../../src/core/fetch-error.ts"],"sourcesContent":["import { BackendError } from './backend'\n\n/** Human-readable message for a failed request: a `BackendError`'s message, else the server's error message if it sent one. */\nexport function fetchErrorMessage(error: unknown): string {\n  if (error instanceof BackendError) return error.message\n  const serverMessage = (error as { data?: { message?: unknown } } | null)?.data?.message\n  if (typeof serverMessage === 'string' && serverMessage) return serverMessage\n  return error instanceof Error ? error.message : String(error)\n}\n"],"mappings":";;;AAGA,SAAgB,kBAAkB,OAAwB;CACxD,IAAI,iBAAiB,cAAc,OAAO,MAAM;CAChD,MAAM,gBAAiB,OAAmD,MAAM;CAChF,IAAI,OAAO,kBAAkB,YAAY,eAAe,OAAO;CAC/D,OAAO,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AAC9D"}

package/dist/core/hash.d.ts

@@ -0,0 +1,5 @@
+//#region src/core/hash.d.ts
+/** SHA-256 of the UTF-8 bytes of `text`, as lowercase hex. */
+export declare function sha256Hex(text: string): string;
+//#endregion
+//# sourceMappingURL=hash.d.ts.map

package/dist/core/hash.js

@@ -0,0 +1,11 @@
+import { sha256 } from "@noble/hashes/sha2.js";
+import { bytesToHex, utf8ToBytes } from "@noble/hashes/utils.js";
+//#region src/core/hash.ts
+/** SHA-256 of the UTF-8 bytes of `text`, as lowercase hex. */
+function sha256Hex(text) {
+	return bytesToHex(sha256(utf8ToBytes(text)));
+}
+//#endregion
+export { sha256Hex };
+
+//# sourceMappingURL=hash.js.map

package/dist/core/hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.js","names":[],"sources":["../../src/core/hash.ts"],"sourcesContent":["import { sha256 } from '@noble/hashes/sha2.js'\nimport { bytesToHex, utf8ToBytes } from '@noble/hashes/utils.js'\n\n// Pure JS on purpose: WebCrypto's `crypto.subtle` is unavailable outside secure contexts (plain-http dev hosts), same\n// reason block ids use `uuid` instead of `crypto.randomUUID`.\n\n/** SHA-256 of the UTF-8 bytes of `text`, as lowercase hex. */\nexport function sha256Hex(text: string): string {\n  return bytesToHex(sha256(utf8ToBytes(text)))\n}\n"],"mappings":";;;;AAOA,SAAgB,UAAU,MAAsB;CAC9C,OAAO,WAAW,OAAO,YAAY,IAAI,CAAC,CAAC;AAC7C"}

package/dist/core/http-backend.d.ts

@@ -0,0 +1,11 @@
+import "./backend.js";
+import { $Fetch } from "ofetch";
+//#region src/core/http-backend.d.ts
+export interface FetchBackendOptions {
+  /** HTTP client (default: the platform `fetch`); Nuxt hosts pass `useNuxtApp().$fetch` (it resolves relative paths while rendering on the server). */
+  fetch?: $Fetch;
+  /** Prefix of every path (`https://api.example.com`); default `''` (same origin). */
+  base?: string;
+}
+//#endregion
+//# sourceMappingURL=http-backend.d.ts.map