@ecsplico/editor 3.5.1 → 4.0.0

package/dist/core/define-editor.js

@@ -1,15 +1,18 @@
+import { fail as fail$1 } from "./util.js";
+import { BUILT_IN_BLOCK_CAPABILITIES, createCapabilityRegistry } from "./capabilities.js";
+import { createDeriveRegistry } from "./derive.js";
 import { SINGLETON_PIPELINE_HOOKS } from "./feature.js";
+import { migratePersistedNames } from "./schema/persisted-names.js";
 import { DEFAULT_BLOCK_PIPELINE } from "./pipeline.js";
-import { fail as fail$1 } from "./util.js";
 //#region src/core/define-editor.ts
 const FEATURE_SINGLETONS = ["anchorResolver", "formatAiResult"];
 const fail = (message) => fail$1(message, "defineEditor");
 /**
 * Validates `features` and resolves their pipeline and conversion providers. Keeps the given order; neither
 * deduplicates nor installs missing dependencies. Throws on duplicate ids, a `requires` entry that is not installed,
-* a toolbar group declared by two features (`toolbarGroups`) and a singleton hook (`parseMarkdown`, `segment`, `structure`, `wrapImport`, `migrateContent`, `anchorResolver`,
+* a toolbar group declared by two features (`toolbarGroups`), a block capability declared twice or with a built-in id (`blockCapabilities`), a derive method declared twice, with neither `run` nor `menu` or requiring an undeclared capability (`deriveMethods`) and a singleton hook (`parseMarkdown`, `segment`, `structure`, `wrapImport`, `migrateContent`, `anchorResolver`,
 * `formatAiResult`) contributed twice. A command naming a toolbar group no feature declares needs the feature context
-* to build the commands: `toolbarOf` throws it. `normalize` hooks chain left to right. `aiContext` contributions merge (`kinds` and `blocks`
+* to build the commands: `toolbarOf` throws it. `normalize` hooks chain left to right. `aiContext` contributions merge (`blockTypes` and `blocks`
 * concatenated in feature order, `structure` from one feature only); their conflicts surface when the merged `aiContext` reads the editor.
 * `aiBlockData` contributions are additive too: they run in parallel per block and their data concatenate in feature order.
 */
@@ -28,6 +31,24 @@ function defineEditor(config) {
 		if (owner) fail(`features "${owner}" and "${feature.id}" both declare toolbar group "${group.id}"`);
 		groups.set(group.id, feature.id);
 	}
+	const capabilities = [...BUILT_IN_BLOCK_CAPABILITIES];
+	const capabilityOwners = new Map(capabilities.map((capability) => [capability.id, "the editor core"]));
+	for (const feature of features) for (const capability of feature.blockCapabilities ?? []) {
+		const owner = capabilityOwners.get(capability.id);
+		if (owner) fail(`the block capability "${capability.id}" is declared by ${owner} and by feature "${feature.id}"`);
+		capabilityOwners.set(capability.id, `feature "${feature.id}"`);
+		capabilities.push(capability);
+	}
+	const deriveMethods = [];
+	const deriveOwners = /* @__PURE__ */ new Map();
+	for (const feature of features) for (const method of feature.deriveMethods ?? []) {
+		const owner = deriveOwners.get(method.id);
+		if (owner) fail(`the derive method "${method.id}" is declared by feature "${owner}" and by feature "${feature.id}"`);
+		deriveOwners.set(method.id, feature.id);
+		if (!method.run === !method.menu) fail(`the derive method "${method.id}" of feature "${feature.id}" needs exactly one of run and menu`);
+		for (const required of method.requires) if (!capabilityOwners.has(required)) fail(`the derive method "${method.id}" of feature "${feature.id}" requires the capability "${required}", which no feature declares`);
+		deriveMethods.push(method);
+	}
 	const owners = /* @__PURE__ */ new Map();
 	const claim = (hook, feature) => {
 		const owner = owners.get(hook);
@@ -49,6 +70,8 @@ function defineEditor(config) {
 		}
 	}
 	if (normalizers.length) pipeline.normalize = (editor, blocks) => normalizers.reduce((current, normalize) => normalize(editor, current), blocks);
+	const contributed = pipeline.migrateContent;
+	if (contributed !== DEFAULT_BLOCK_PIPELINE.migrateContent) pipeline.migrateContent = (content) => contributed(migratePersistedNames(content));
 	const conversions = features.flatMap((feature) => [...feature.conversions ?? []]);
 	const contexts = features.flatMap((feature) => feature.aiContext ? [{
 		id: feature.id,
@@ -56,13 +79,13 @@ function defineEditor(config) {
 	}] : []);
 	const aiContext = contexts.length ? (editor) => {
 		const merged = {
-			kinds: [],
+			blockTypes: [],
 			blocks: []
 		};
 		const blockIds = /* @__PURE__ */ new Set();
 		for (const { id, read } of contexts) {
 			const context = read(editor);
-			merged.kinds.push(...context.kinds ?? []);
+			merged.blockTypes.push(...context.blockTypes ?? []);
 			for (const block of context.blocks ?? []) {
 				if (blockIds.has(block.id)) fail(`the AI block "${block.id}" is described by more than one feature`);
 				blockIds.add(block.id);
@@ -74,7 +97,7 @@ function defineEditor(config) {
 			merged.structure = context.structure;
 		}
 		return {
-			kinds: merged.kinds,
+			blockTypes: merged.blockTypes,
 			blocks: merged.blocks,
 			...merged.structure && { structure: merged.structure }
 		};
@@ -82,10 +105,15 @@ function defineEditor(config) {
 	const dataProviders = features.flatMap((feature) => feature.aiBlockData ? [feature.aiBlockData] : []);
 	const aiBlockData = dataProviders.length ? async (request) => (await Promise.all(dataProviders.map((provide) => provide(request)))).flat() : void 0;
 	const formatAiResult = features.find((feature) => feature.formatAiResult)?.formatAiResult;
+	const blockTypeSources = features.flatMap((feature) => feature.blockTypes ? [feature.blockTypes] : []);
+	const blockTypes = blockTypeSources.length ? (editor) => blockTypeSources.length === 1 ? blockTypeSources[0](editor) : blockTypeSources.flatMap((source) => [...source(editor)]) : void 0;
 	return Object.freeze({
 		features,
 		pipeline: Object.freeze(pipeline),
 		conversions: Object.freeze(conversions),
+		capabilities: createCapabilityRegistry(Object.freeze(capabilities)),
+		deriveMethods: createDeriveRegistry(Object.freeze(deriveMethods)),
+		...blockTypes && { blockTypes },
 		...aiContext && { aiContext },
 		...aiBlockData && { aiBlockData },
 		...formatAiResult && { formatAiResult }

package/dist/core/define-editor.js.map

@@ -1 +1 @@
-{"version":3,"file":"define-editor.js","names":["failWith"],"sources":["../../src/core/define-editor.ts"],"sourcesContent":["import type { Editor } from '@tiptap/core'\nimport type { EditorContext } from './context'\nimport { type AiBlock, type AiBlockDataProvider, type AiContext, type AiContextKind, type BlockPipeline, type ConversionProvider, type EditorFeature, type EditorPreset, type SettingsTab, SINGLETON_PIPELINE_HOOKS } from './feature'\nimport { DEFAULT_BLOCK_PIPELINE } from './pipeline'\nimport { fail as failWith } from './util'\n\nconst FEATURE_SINGLETONS = ['anchorResolver', 'formatAiResult'] as const satisfies readonly (keyof EditorFeature)[]\n\nconst fail = (message: string): never => failWith(message, 'defineEditor')\n\n/**\n * Validates `features` and resolves their pipeline and conversion providers. Keeps the given order; neither\n * deduplicates nor installs missing dependencies. Throws on duplicate ids, a `requires` entry that is not installed,\n * a toolbar group declared by two features (`toolbarGroups`) and a singleton hook (`parseMarkdown`, `segment`, `structure`, `wrapImport`, `migrateContent`, `anchorResolver`,\n * `formatAiResult`) contributed twice. A command naming a toolbar group no feature declares needs the feature context\n * to build the commands: `toolbarOf` throws it. `normalize` hooks chain left to right. `aiContext` contributions merge (`kinds` and `blocks`\n * concatenated in feature order, `structure` from one feature only); their conflicts surface when the merged `aiContext` reads the editor.\n * `aiBlockData` contributions are additive too: they run in parallel per block and their data concatenate in feature order.\n */\nexport function defineEditor<C = unknown>(config: { features: readonly EditorFeature<C>[] }): EditorPreset<C> {\n  const features = Object.freeze([...config.features])\n  const ids = new Set<string>()\n  for (const feature of features) {\n    if (!feature.dimension) fail(`feature \"${feature.id}\" declares no dimension`)\n  }\n  for (const feature of features) {\n    if (ids.has(feature.id)) fail(`duplicate feature id \"${feature.id}\"`)\n    ids.add(feature.id)\n  }\n  for (const feature of features) {\n    for (const required of feature.requires ?? []) {\n      if (!ids.has(required)) fail(`feature \"${feature.id}\" requires \"${required}\", which is not installed`)\n    }\n  }\n  const groups = new Map<string, string>()\n  for (const feature of features) {\n    for (const group of feature.toolbarGroups ?? []) {\n      const owner = groups.get(group.id)\n      if (owner) fail(`features \"${owner}\" and \"${feature.id}\" both declare toolbar group \"${group.id}\"`)\n      groups.set(group.id, feature.id)\n    }\n  }\n\n  const owners = new Map<string, string>()\n  const claim = (hook: string, feature: EditorFeature<C>) => {\n    const owner = owners.get(hook)\n    if (owner) fail(`features \"${owner}\" and \"${feature.id}\" both contribute the singleton hook \"${hook}\"`)\n    owners.set(hook, feature.id)\n  }\n  const pipeline: BlockPipeline = { ...DEFAULT_BLOCK_PIPELINE }\n  const normalizers: BlockPipeline['normalize'][] = []\n  for (const feature of features) {\n    for (const hook of FEATURE_SINGLETONS) if (feature[hook]) claim(hook, feature)\n    const blocks = feature.blocks\n    if (!blocks) continue\n    if (blocks.normalize) normalizers.push(blocks.normalize)\n    for (const hook of SINGLETON_PIPELINE_HOOKS) {\n      const fn = blocks[hook]\n      if (!fn) continue\n      claim(hook, feature)\n      Object.assign(pipeline, { [hook]: fn })\n    }\n  }\n  if (normalizers.length) pipeline.normalize = (editor, blocks) => normalizers.reduce((current, normalize) => normalize(editor, current), blocks)\n\n  const conversions: ConversionProvider[] = features.flatMap(feature => [...(feature.conversions ?? [])])\n  const contexts = features.flatMap(feature => feature.aiContext ? [{ id: feature.id, read: feature.aiContext }] : [])\n  const aiContext = contexts.length\n    ? (editor: Editor): AiContext => {\n        const merged: { kinds: AiContextKind[], blocks: AiBlock[], structure?: AiContext['structure'], owner?: string } = { kinds: [], blocks: [] }\n        const blockIds = new Set<string>()\n        for (const { id, read } of contexts) {\n          const context = read(editor)\n          merged.kinds.push(...(context.kinds ?? []))\n          for (const block of context.blocks ?? []) {\n            if (blockIds.has(block.id)) fail(`the AI block \"${block.id}\" is described by more than one feature`)\n            blockIds.add(block.id)\n            merged.blocks.push(block)\n          }\n          if (context.structure === undefined) continue\n          if (merged.owner) fail(`features \"${merged.owner}\" and \"${id}\" both set aiContext.structure`)\n          merged.owner = id\n          merged.structure = context.structure\n        }\n        return { kinds: merged.kinds, blocks: merged.blocks, ...(merged.structure && { structure: merged.structure }) }\n      }\n    : undefined\n  const dataProviders = features.flatMap(feature => feature.aiBlockData ? [feature.aiBlockData] : [])\n  const aiBlockData: AiBlockDataProvider | undefined = dataProviders.length\n    ? async request => (await Promise.all(dataProviders.map(provide => provide(request)))).flat()\n    : undefined\n  const formatAiResult = features.find(feature => feature.formatAiResult)?.formatAiResult\n  return Object.freeze({\n    features,\n    pipeline: Object.freeze(pipeline),\n    conversions: Object.freeze(conversions),\n    ...(aiContext && { aiContext }),\n    ...(aiBlockData && { aiBlockData }),\n    ...(formatAiResult && { formatAiResult }),\n  })\n}\n\n/**\n * The settings tabs the features of `preset` contribute for the app context `ctx` (labels in its language), in feature\n * order; none means there is no settings UI. Throws when two features contribute the same tab id.\n */\nexport function settingsTabsOf<C = unknown>(preset: EditorPreset<C>, ctx: EditorContext): readonly SettingsTab<C>[] {\n  const owners = new Map<string, string>()\n  return preset.features.flatMap((feature) => {\n    const tabs = feature.settingsTabs?.(ctx) ?? []\n    for (const tab of tabs) {\n      const owner = owners.get(tab.id)\n      if (owner) fail(`features \"${owner}\" and \"${feature.id}\" both contribute the settings tab \"${tab.id}\"`)\n      owners.set(tab.id, feature.id)\n    }\n    return tabs\n  })\n}\n\n/** Features of `preset` that fill the contribution `key`, in order. */\nexport function contributions<C, K extends keyof EditorFeature<C>>(preset: EditorPreset<C>, key: K): NonNullable<EditorFeature<C>[K]>[] {\n  return preset.features.flatMap(feature => feature[key] ? [feature[key] as NonNullable<EditorFeature<C>[K]>] : [])\n}\n"],"mappings":"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"}
+{"version":3,"file":"define-editor.js","names":["failWith"],"sources":["../../src/core/define-editor.ts"],"sourcesContent":["import type { Editor } from '@tiptap/core'\nimport { BUILT_IN_BLOCK_CAPABILITIES, type BlockCapability, type BlockTypeData, createCapabilityRegistry } from './capabilities'\nimport { createDeriveRegistry, type DeriveMethod } from './derive'\nimport type { EditorContext } from './context'\nimport { type AiBlock, type AiBlockDataProvider, type AiContext, type AiContextBlockType, type BlockPipeline, type ConversionProvider, type EditorFeature, type EditorPreset, type SettingsTab, SINGLETON_PIPELINE_HOOKS } from './feature'\nimport { DEFAULT_BLOCK_PIPELINE } from './pipeline'\nimport { migratePersistedNames } from './schema/persisted-names'\nimport { fail as failWith } from './util'\n\nconst FEATURE_SINGLETONS = ['anchorResolver', 'formatAiResult'] as const satisfies readonly (keyof EditorFeature)[]\n\nconst fail = (message: string): never => failWith(message, 'defineEditor')\n\n/**\n * Validates `features` and resolves their pipeline and conversion providers. Keeps the given order; neither\n * deduplicates nor installs missing dependencies. Throws on duplicate ids, a `requires` entry that is not installed,\n * a toolbar group declared by two features (`toolbarGroups`), a block capability declared twice or with a built-in id (`blockCapabilities`), a derive method declared twice, with neither `run` nor `menu` or requiring an undeclared capability (`deriveMethods`) and a singleton hook (`parseMarkdown`, `segment`, `structure`, `wrapImport`, `migrateContent`, `anchorResolver`,\n * `formatAiResult`) contributed twice. A command naming a toolbar group no feature declares needs the feature context\n * to build the commands: `toolbarOf` throws it. `normalize` hooks chain left to right. `aiContext` contributions merge (`blockTypes` and `blocks`\n * concatenated in feature order, `structure` from one feature only); their conflicts surface when the merged `aiContext` reads the editor.\n * `aiBlockData` contributions are additive too: they run in parallel per block and their data concatenate in feature order.\n */\nexport function defineEditor<C = unknown>(config: { features: readonly EditorFeature<C>[] }): EditorPreset<C> {\n  const features = Object.freeze([...config.features])\n  const ids = new Set<string>()\n  for (const feature of features) {\n    if (!feature.dimension) fail(`feature \"${feature.id}\" declares no dimension`)\n  }\n  for (const feature of features) {\n    if (ids.has(feature.id)) fail(`duplicate feature id \"${feature.id}\"`)\n    ids.add(feature.id)\n  }\n  for (const feature of features) {\n    for (const required of feature.requires ?? []) {\n      if (!ids.has(required)) fail(`feature \"${feature.id}\" requires \"${required}\", which is not installed`)\n    }\n  }\n  const groups = new Map<string, string>()\n  for (const feature of features) {\n    for (const group of feature.toolbarGroups ?? []) {\n      const owner = groups.get(group.id)\n      if (owner) fail(`features \"${owner}\" and \"${feature.id}\" both declare toolbar group \"${group.id}\"`)\n      groups.set(group.id, feature.id)\n    }\n  }\n\n  const capabilities: BlockCapability[] = [...BUILT_IN_BLOCK_CAPABILITIES]\n  const capabilityOwners = new Map<string, string>(capabilities.map(capability => [capability.id, 'the editor core']))\n  for (const feature of features) {\n    for (const capability of feature.blockCapabilities ?? []) {\n      const owner = capabilityOwners.get(capability.id)\n      if (owner) fail(`the block capability \"${capability.id}\" is declared by ${owner} and by feature \"${feature.id}\"`)\n      capabilityOwners.set(capability.id, `feature \"${feature.id}\"`)\n      capabilities.push(capability)\n    }\n  }\n\n  const deriveMethods: DeriveMethod[] = []\n  const deriveOwners = new Map<string, string>()\n  for (const feature of features) {\n    for (const method of feature.deriveMethods ?? []) {\n      const owner = deriveOwners.get(method.id)\n      if (owner) fail(`the derive method \"${method.id}\" is declared by feature \"${owner}\" and by feature \"${feature.id}\"`)\n      deriveOwners.set(method.id, feature.id)\n      if (!method.run === !method.menu) fail(`the derive method \"${method.id}\" of feature \"${feature.id}\" needs exactly one of run and menu`)\n      for (const required of method.requires) {\n        if (!capabilityOwners.has(required)) fail(`the derive method \"${method.id}\" of feature \"${feature.id}\" requires the capability \"${required}\", which no feature declares`)\n      }\n      deriveMethods.push(method)\n    }\n  }\n\n  const owners = new Map<string, string>()\n  const claim = (hook: string, feature: EditorFeature<C>) => {\n    const owner = owners.get(hook)\n    if (owner) fail(`features \"${owner}\" and \"${feature.id}\" both contribute the singleton hook \"${hook}\"`)\n    owners.set(hook, feature.id)\n  }\n  const pipeline: BlockPipeline = { ...DEFAULT_BLOCK_PIPELINE }\n  const normalizers: BlockPipeline['normalize'][] = []\n  for (const feature of features) {\n    for (const hook of FEATURE_SINGLETONS) if (feature[hook]) claim(hook, feature)\n    const blocks = feature.blocks\n    if (!blocks) continue\n    if (blocks.normalize) normalizers.push(blocks.normalize)\n    for (const hook of SINGLETON_PIPELINE_HOOKS) {\n      const fn = blocks[hook]\n      if (!fn) continue\n      claim(hook, feature)\n      Object.assign(pipeline, { [hook]: fn })\n    }\n  }\n  if (normalizers.length) pipeline.normalize = (editor, blocks) => normalizers.reduce((current, normalize) => normalize(editor, current), blocks)\n  // The rename of the old persisted names always runs first, so a contributed `migrateContent` only ever sees the current names.\n  const contributed = pipeline.migrateContent\n  if (contributed !== DEFAULT_BLOCK_PIPELINE.migrateContent) pipeline.migrateContent = content => contributed(migratePersistedNames(content))\n\n  const conversions: ConversionProvider[] = features.flatMap(feature => [...(feature.conversions ?? [])])\n  const contexts = features.flatMap(feature => feature.aiContext ? [{ id: feature.id, read: feature.aiContext }] : [])\n  const aiContext = contexts.length\n    ? (editor: Editor): AiContext => {\n        const merged: { blockTypes: AiContextBlockType[], blocks: AiBlock[], structure?: AiContext['structure'], owner?: string } = { blockTypes: [], blocks: [] }\n        const blockIds = new Set<string>()\n        for (const { id, read } of contexts) {\n          const context = read(editor)\n          merged.blockTypes.push(...(context.blockTypes ?? []))\n          for (const block of context.blocks ?? []) {\n            if (blockIds.has(block.id)) fail(`the AI block \"${block.id}\" is described by more than one feature`)\n            blockIds.add(block.id)\n            merged.blocks.push(block)\n          }\n          if (context.structure === undefined) continue\n          if (merged.owner) fail(`features \"${merged.owner}\" and \"${id}\" both set aiContext.structure`)\n          merged.owner = id\n          merged.structure = context.structure\n        }\n        return { blockTypes: merged.blockTypes, blocks: merged.blocks, ...(merged.structure && { structure: merged.structure }) }\n      }\n    : undefined\n  const dataProviders = features.flatMap(feature => feature.aiBlockData ? [feature.aiBlockData] : [])\n  const aiBlockData: AiBlockDataProvider | undefined = dataProviders.length\n    ? async request => (await Promise.all(dataProviders.map(provide => provide(request)))).flat()\n    : undefined\n  const formatAiResult = features.find(feature => feature.formatAiResult)?.formatAiResult\n  const blockTypeSources = features.flatMap(feature => feature.blockTypes ? [feature.blockTypes] : [])\n  const blockTypes = blockTypeSources.length\n    ? (editor: Editor): readonly BlockTypeData[] => blockTypeSources.length === 1 ? blockTypeSources[0]!(editor) : blockTypeSources.flatMap(source => [...source(editor)])\n    : undefined\n  return Object.freeze({\n    features,\n    pipeline: Object.freeze(pipeline),\n    conversions: Object.freeze(conversions),\n    capabilities: createCapabilityRegistry(Object.freeze(capabilities)),\n    deriveMethods: createDeriveRegistry(Object.freeze(deriveMethods)),\n    ...(blockTypes && { blockTypes }),\n    ...(aiContext && { aiContext }),\n    ...(aiBlockData && { aiBlockData }),\n    ...(formatAiResult && { formatAiResult }),\n  })\n}\n\n/**\n * The settings tabs the features of `preset` contribute for the app context `ctx` (labels in its language), in feature\n * order; none means there is no settings UI. Throws when two features contribute the same tab id.\n */\nexport function settingsTabsOf<C = unknown>(preset: EditorPreset<C>, ctx: EditorContext): readonly SettingsTab<C>[] {\n  const owners = new Map<string, string>()\n  return preset.features.flatMap((feature) => {\n    const tabs = feature.settingsTabs?.(ctx) ?? []\n    for (const tab of tabs) {\n      const owner = owners.get(tab.id)\n      if (owner) fail(`features \"${owner}\" and \"${feature.id}\" both contribute the settings tab \"${tab.id}\"`)\n      owners.set(tab.id, feature.id)\n    }\n    return tabs\n  })\n}\n\n/** Features of `preset` that fill the contribution `key`, in order. */\nexport function contributions<C, K extends keyof EditorFeature<C>>(preset: EditorPreset<C>, key: K): NonNullable<EditorFeature<C>[K]>[] {\n  return preset.features.flatMap(feature => feature[key] ? [feature[key] as NonNullable<EditorFeature<C>[K]>] : [])\n}\n"],"mappings":";;;;;;;AASA,MAAM,qBAAqB,CAAC,kBAAkB,gBAAgB;AAE9D,MAAM,QAAQ,YAA2BA,OAAS,SAAS,cAAc;;;;;;;;;;AAWzE,SAAgB,aAA0B,QAAoE;CAC5G,MAAM,WAAW,OAAO,OAAO,CAAC,GAAG,OAAO,QAAQ,CAAC;CACnD,MAAM,sBAAM,IAAI,IAAY;CAC5B,KAAK,MAAM,WAAW,UACpB,IAAI,CAAC,QAAQ,WAAW,KAAK,YAAY,QAAQ,GAAG,wBAAwB;CAE9E,KAAK,MAAM,WAAW,UAAU;EAC9B,IAAI,IAAI,IAAI,QAAQ,EAAE,GAAG,KAAK,yBAAyB,QAAQ,GAAG,EAAE;EACpE,IAAI,IAAI,QAAQ,EAAE;CACpB;CACA,KAAK,MAAM,WAAW,UACpB,KAAK,MAAM,YAAY,QAAQ,YAAY,CAAC,GAC1C,IAAI,CAAC,IAAI,IAAI,QAAQ,GAAG,KAAK,YAAY,QAAQ,GAAG,cAAc,SAAS,0BAA0B;CAGzG,MAAM,yBAAS,IAAI,IAAoB;CACvC,KAAK,MAAM,WAAW,UACpB,KAAK,MAAM,SAAS,QAAQ,iBAAiB,CAAC,GAAG;EAC/C,MAAM,QAAQ,OAAO,IAAI,MAAM,EAAE;EACjC,IAAI,OAAO,KAAK,aAAa,MAAM,SAAS,QAAQ,GAAG,gCAAgC,MAAM,GAAG,EAAE;EAClG,OAAO,IAAI,MAAM,IAAI,QAAQ,EAAE;CACjC;CAGF,MAAM,eAAkC,CAAC,GAAG,2BAA2B;CACvE,MAAM,mBAAmB,IAAI,IAAoB,aAAa,KAAI,eAAc,CAAC,WAAW,IAAI,iBAAiB,CAAC,CAAC;CACnH,KAAK,MAAM,WAAW,UACpB,KAAK,MAAM,cAAc,QAAQ,qBAAqB,CAAC,GAAG;EACxD,MAAM,QAAQ,iBAAiB,IAAI,WAAW,EAAE;EAChD,IAAI,OAAO,KAAK,yBAAyB,WAAW,GAAG,mBAAmB,MAAM,mBAAmB,QAAQ,GAAG,EAAE;EAChH,iBAAiB,IAAI,WAAW,IAAI,YAAY,QAAQ,GAAG,EAAE;EAC7D,aAAa,KAAK,UAAU;CAC9B;CAGF,MAAM,gBAAgC,CAAC;CACvC,MAAM,+BAAe,IAAI,IAAoB;CAC7C,KAAK,MAAM,WAAW,UACpB,KAAK,MAAM,UAAU,QAAQ,iBAAiB,CAAC,GAAG;EAChD,MAAM,QAAQ,aAAa,IAAI,OAAO,EAAE;EACxC,IAAI,OAAO,KAAK,sBAAsB,OAAO,GAAG,4BAA4B,MAAM,oBAAoB,QAAQ,GAAG,EAAE;EACnH,aAAa,IAAI,OAAO,IAAI,QAAQ,EAAE;EACtC,IAAI,CAAC,OAAO,QAAQ,CAAC,OAAO,MAAM,KAAK,sBAAsB,OAAO,GAAG,gBAAgB,QAAQ,GAAG,oCAAoC;EACtI,KAAK,MAAM,YAAY,OAAO,UAC5B,IAAI,CAAC,iBAAiB,IAAI,QAAQ,GAAG,KAAK,sBAAsB,OAAO,GAAG,gBAAgB,QAAQ,GAAG,6BAA6B,SAAS,6BAA6B;EAE1K,cAAc,KAAK,MAAM;CAC3B;CAGF,MAAM,yBAAS,IAAI,IAAoB;CACvC,MAAM,SAAS,MAAc,YAA8B;EACzD,MAAM,QAAQ,OAAO,IAAI,IAAI;EAC7B,IAAI,OAAO,KAAK,aAAa,MAAM,SAAS,QAAQ,GAAG,wCAAwC,KAAK,EAAE;EACtG,OAAO,IAAI,MAAM,QAAQ,EAAE;CAC7B;CACA,MAAM,WAA0B,EAAE,GAAG,uBAAuB;CAC5D,MAAM,cAA4C,CAAC;CACnD,KAAK,MAAM,WAAW,UAAU;EAC9B,KAAK,MAAM,QAAQ,oBAAoB,IAAI,QAAQ,OAAO,MAAM,MAAM,OAAO;EAC7E,MAAM,SAAS,QAAQ;EACvB,IAAI,CAAC,QAAQ;EACb,IAAI,OAAO,WAAW,YAAY,KAAK,OAAO,SAAS;EACvD,KAAK,MAAM,QAAQ,0BAA0B;GAC3C,MAAM,KAAK,OAAO;GAClB,IAAI,CAAC,IAAI;GACT,MAAM,MAAM,OAAO;GACnB,OAAO,OAAO,UAAU,GAAG,OAAO,GAAG,CAAC;EACxC;CACF;CACA,IAAI,YAAY,QAAQ,SAAS,aAAa,QAAQ,WAAW,YAAY,QAAQ,SAAS,cAAc,UAAU,QAAQ,OAAO,GAAG,MAAM;CAE9I,MAAM,cAAc,SAAS;CAC7B,IAAI,gBAAgB,uBAAuB,gBAAgB,SAAS,kBAAiB,YAAW,YAAY,sBAAsB,OAAO,CAAC;CAE1I,MAAM,cAAoC,SAAS,SAAQ,YAAW,CAAC,GAAI,QAAQ,eAAe,CAAC,CAAE,CAAC;CACtG,MAAM,WAAW,SAAS,SAAQ,YAAW,QAAQ,YAAY,CAAC;EAAE,IAAI,QAAQ;EAAI,MAAM,QAAQ;CAAU,CAAC,IAAI,CAAC,CAAC;CACnH,MAAM,YAAY,SAAS,UACtB,WAA8B;EAC7B,MAAM,SAAsH;GAAE,YAAY,CAAC;GAAG,QAAQ,CAAC;EAAE;EACzJ,MAAM,2BAAW,IAAI,IAAY;EACjC,KAAK,MAAM,EAAE,IAAI,UAAU,UAAU;GACnC,MAAM,UAAU,KAAK,MAAM;GAC3B,OAAO,WAAW,KAAK,GAAI,QAAQ,cAAc,CAAC,CAAE;GACpD,KAAK,MAAM,SAAS,QAAQ,UAAU,CAAC,GAAG;IACxC,IAAI,SAAS,IAAI,MAAM,EAAE,GAAG,KAAK,iBAAiB,MAAM,GAAG,wCAAwC;IACnG,SAAS,IAAI,MAAM,EAAE;IACrB,OAAO,OAAO,KAAK,KAAK;GAC1B;GACA,IAAI,QAAQ,cAAc,KAAA,GAAW;GACrC,IAAI,OAAO,OAAO,KAAK,aAAa,OAAO,MAAM,SAAS,GAAG,+BAA+B;GAC5F,OAAO,QAAQ;GACf,OAAO,YAAY,QAAQ;EAC7B;EACA,OAAO;GAAE,YAAY,OAAO;GAAY,QAAQ,OAAO;GAAQ,GAAI,OAAO,aAAa,EAAE,WAAW,OAAO,UAAU;EAAG;CAC1H,IACA,KAAA;CACJ,MAAM,gBAAgB,SAAS,SAAQ,YAAW,QAAQ,cAAc,CAAC,QAAQ,WAAW,IAAI,CAAC,CAAC;CAClG,MAAM,cAA+C,cAAc,SAC/D,OAAM,aAAY,MAAM,QAAQ,IAAI,cAAc,KAAI,YAAW,QAAQ,OAAO,CAAC,CAAC,EAAA,CAAG,KAAK,IAC1F,KAAA;CACJ,MAAM,iBAAiB,SAAS,MAAK,YAAW,QAAQ,cAAc,CAAC,EAAE;CACzE,MAAM,mBAAmB,SAAS,SAAQ,YAAW,QAAQ,aAAa,CAAC,QAAQ,UAAU,IAAI,CAAC,CAAC;CACnG,MAAM,aAAa,iBAAiB,UAC/B,WAA6C,iBAAiB,WAAW,IAAI,iBAAiB,EAAE,CAAE,MAAM,IAAI,iBAAiB,SAAQ,WAAU,CAAC,GAAG,OAAO,MAAM,CAAC,CAAC,IACnK,KAAA;CACJ,OAAO,OAAO,OAAO;EACnB;EACA,UAAU,OAAO,OAAO,QAAQ;EAChC,aAAa,OAAO,OAAO,WAAW;EACtC,cAAc,yBAAyB,OAAO,OAAO,YAAY,CAAC;EAClE,eAAe,qBAAqB,OAAO,OAAO,aAAa,CAAC;EAChE,GAAI,cAAc,EAAE,WAAW;EAC/B,GAAI,aAAa,EAAE,UAAU;EAC7B,GAAI,eAAe,EAAE,YAAY;EACjC,GAAI,kBAAkB,EAAE,eAAe;CACzC,CAAC;AACH;;;;;AAMA,SAAgB,eAA4B,QAAyB,KAA+C;CAClH,MAAM,yBAAS,IAAI,IAAoB;CACvC,OAAO,OAAO,SAAS,SAAS,YAAY;EAC1C,MAAM,OAAO,QAAQ,eAAe,GAAG,KAAK,CAAC;EAC7C,KAAK,MAAM,OAAO,MAAM;GACtB,MAAM,QAAQ,OAAO,IAAI,IAAI,EAAE;GAC/B,IAAI,OAAO,KAAK,aAAa,MAAM,SAAS,QAAQ,GAAG,sCAAsC,IAAI,GAAG,EAAE;GACtG,OAAO,IAAI,IAAI,IAAI,QAAQ,EAAE;EAC/B;EACA,OAAO;CACT,CAAC;AACH;;AAGA,SAAgB,cAAmD,QAAyB,KAA4C;CACtI,OAAO,OAAO,SAAS,SAAQ,YAAW,QAAQ,OAAO,CAAC,QAAQ,IAAwC,IAAI,CAAC,CAAC;AAClH"}

package/dist/core/derivation.d.ts

@@ -0,0 +1,119 @@
+import { Node } from "@tiptap/pm/model";
+//#region src/core/derivation.d.ts
+/** `meta` key of a Derivation. */
+export declare const DERIVATION_KEY = "derivation";
+/** How a Derived block was made; `ai:<typeId>` for a block derived from another block by the model. */
+export type DerivationMethod = 'transcription' | 'pdf-text' | 'ocr' | 'description' | 'bibliography' | (string & {});
+/** What a Derived block was made from: an uploaded asset (by asset name) or another block (by block id). */
+export type DerivationSource = {
+  asset: string;
+} | {
+  block: string; /** Document the block lives in; absent = this document. */
+  document?: string;
+};
+/** `meta.derivation` of a Derived block. */
+export interface Derivation {
+  from: DerivationSource;
+  method: DerivationMethod;
+  model?: string;
+  /** ISO timestamp. */
+  createdAt: string;
+  /** SHA-256 hex of the asset bytes / of the source block's Markdown; `''` when unknown. */
+  inputHash: string;
+  /** SHA-256 hex of the produced body's Markdown; `''` when unknown. */
+  outputHash: string;
+  /** Asset name of the stored raw output (text/markdown). */
+  output?: string;
+}
+/** The derivation of a block (`meta.derivation` with a `from` object and a `method`); null when it has none. */
+export declare function derivationOf(node: Node): Derivation | null;
+/** Whether `derivation` points at a block of another document than `documentId` (the open one; null/undefined = unknown, so any named document is another). */
+export declare function isForeignSource(derivation: Derivation, documentId: string | null | undefined): boolean;
+/** The stored asset behind an `/api/editor/assets/<documentId>/<name>` URL; null for any other `src`. */
+export declare function assetRefOf(src: string): {
+  documentId: string;
+  name: string;
+} | null;
+/** The direct children of `parent` that are Derived blocks, with their child index. */
+export declare function derivedChildrenOf(parent: Node): {
+  node: Node;
+  index: number;
+  derivation: Derivation;
+}[];
+/** A Derived block of the document with its position. */
+export interface DerivedEntry {
+  node: Node;
+  pos: number;
+  derivation: Derivation;
+}
+/** A block that holds a stored asset (its `src`), with the block around it (the holder) when there is one. */
+export interface AssetBlock {
+  node: Node;
+  pos: number;
+  /** Position and size of the enclosing block of the asset block; the document itself has none. */
+  holder: {
+    pos: number;
+    size: number;
+  } | null;
+}
+/**
+ * The reverse index of one document version: Derived blocks by what they were made from, and the blocks they can have been
+ * made from by block ID and by asset name. Computed from the document alone and memoised per `doc` node (`derivationIndexOf`),
+ * so it is exactly as current as the document it was read from: a move or delete produces a new `doc` and with it a new index.
+ */
+export interface DerivationIndex {
+  /** Every Derived block, in document order. */
+  readonly derived: readonly DerivedEntry[];
+  /** The block with block ID `id` (any depth) and its position; null when the document has none. */
+  blockById: (id: string) => {
+    node: Node;
+    pos: number;
+  } | null;
+  /** The blocks that hold the stored asset `name`, in document order. */
+  assetBlocks: (name: string) => readonly AssetBlock[];
+  /** The Derived blocks whose Derivation points at block `id`, in this or any document (`isForeignSource` tells them apart). */
+  derivedFromBlock: (id: string) => readonly DerivedEntry[];
+  /** The Derived blocks whose Derivation points at the stored asset `name`. */
+  derivedFromAsset: (name: string) => readonly DerivedEntry[];
+}
+/** The derivation index of `doc`, built once per document version (the `doc` node is immutable, so an edit yields a new index). */
+export declare function derivationIndexOf(doc: Node): DerivationIndex;
+/**
+ * The Derived blocks made from the original at `originalPos` (a Block in `doc`), in document order. They point at its block ID, or
+ * at an asset the original holds as a direct child (its source media); a Derived block moved out of the original still counts. When
+ * several blocks hold the same asset (a duplicated Typed block), a Derived block belongs to the holder that contains it, else to the first
+ * holder. Derivations from another document (`isForeignSource` against `documentId`) are not listed.
+ */
+export declare function derivedOf(doc: Node, originalPos: number, documentId?: string | null): DerivedEntry[];
+/** Where a Derived block's original is: in this document, in another document (not looked up here) or gone. */
+export type DerivationOrigin = {
+  status: 'found';
+  node: Node;
+  pos: number;
+} | {
+  status: 'foreign';
+} | {
+  status: 'missing';
+};
+/**
+ * The original of the Derived block at `derivedPos`: for a block source the block with that ID, for an asset source the block that
+ * holds the asset (the one next to the Derived block when several do). `missing` is the source-missing state: the original was
+ * deleted, so the Derived block stays without it. Null when the node at `derivedPos` is not a Derived block.
+ */
+export declare function derivationOriginOf(doc: Node, derivedPos: number, documentId?: string | null): DerivationOrigin | null;
+/** What is known about a Derived block against its original. */
+export interface DerivationState {
+  /** `missing` is the source-missing state; `foreign` means the original lives in another document and is not looked up. */
+  source: DerivationOrigin['status'];
+  /**
+   * The original changed since the Derived block was made. Only an asset source can be told here (its stored `hash` against
+   * `inputHash`); null otherwise, also for a block source: callers with the editor compare the hash of the source's Markdown.
+   */
+  stale: boolean | null;
+  /** The body's hash (computed lazily, it serialises the body) differs from `outputHash`; null when `outputHash` is unknown. */
+  edited: boolean | null;
+}
+/** The state of the Derived block at `derivedPos` of `doc`; null when the node there is not a Derived block. */
+export declare function derivationState(doc: Node, derivedPos: number, bodyHash: () => string, documentId?: string | null): DerivationState | null;
+//#endregion
+//# sourceMappingURL=derivation.d.ts.map

package/dist/core/derivation.js

@@ -0,0 +1,187 @@
+import { blockIdOf } from "./schema/block-ids.js";
+import { EDITOR_API } from "./api-routes.js";
+//#region src/core/derivation.ts
+/** `meta` key of a Derivation. */
+const DERIVATION_KEY = "derivation";
+/** The derivation of a block (`meta.derivation` with a `from` object and a `method`); null when it has none. */
+function derivationOf(node) {
+	const meta = node.attrs.meta;
+	const value = meta && typeof meta === "object" ? meta[DERIVATION_KEY] : void 0;
+	if (!value || typeof value !== "object") return null;
+	const { from, method } = value;
+	if (!from || typeof from !== "object" || typeof method !== "string") return null;
+	return value;
+}
+/** Whether `derivation` points at a block of another document than `documentId` (the open one; null/undefined = unknown, so any named document is another). */
+function isForeignSource(derivation, documentId) {
+	return "block" in derivation.from && !!derivation.from.document && derivation.from.document !== documentId;
+}
+const ASSET_URL_PREFIX = `${EDITOR_API}/assets/`;
+const ASSET_NAME = /^[0-9a-f-]{36}\.[a-z0-9]{1,8}$/;
+const ASSET_DOCUMENT_ID = /^[A-Za-z0-9_-]{1,64}$/;
+/** The stored asset behind an `/api/editor/assets/<documentId>/<name>` URL; null for any other `src`. */
+function assetRefOf(src) {
+	if (!src.startsWith(ASSET_URL_PREFIX)) return null;
+	const [documentId, name, ...rest] = src.slice(ASSET_URL_PREFIX.length).split("/");
+	if (rest.length || !documentId || !name || !ASSET_DOCUMENT_ID.test(documentId) || !ASSET_NAME.test(name)) return null;
+	return {
+		documentId,
+		name
+	};
+}
+/** The direct children of `parent` that are Derived blocks, with their child index. */
+function derivedChildrenOf(parent) {
+	const found = [];
+	parent.forEach((node, _offset, index) => {
+		const derivation = derivationOf(node);
+		if (derivation) found.push({
+			node,
+			index,
+			derivation
+		});
+	});
+	return found;
+}
+const NONE = [];
+function buildIndex(doc) {
+	const derived = [];
+	const blocks = /* @__PURE__ */ new Map();
+	const assets = /* @__PURE__ */ new Map();
+	const byBlock = /* @__PURE__ */ new Map();
+	const byAsset = /* @__PURE__ */ new Map();
+	const push = (map, key, value) => {
+		const list = map.get(key);
+		if (list) list.push(value);
+		else map.set(key, [value]);
+	};
+	doc.descendants((node, pos) => {
+		if (node.isText) return false;
+		const id = blockIdOf(node);
+		if (id && !blocks.has(id)) blocks.set(id, {
+			node,
+			pos
+		});
+		const derivation = derivationOf(node);
+		if (derivation) {
+			const entry = {
+				node,
+				pos,
+				derivation
+			};
+			derived.push(entry);
+			if ("block" in derivation.from) push(byBlock, derivation.from.block, entry);
+			else push(byAsset, derivation.from.asset, entry);
+		}
+		const src = node.attrs.src;
+		const asset = typeof src === "string" ? assetRefOf(src) : null;
+		if (asset) {
+			const $pos = doc.resolve(pos);
+			push(assets, asset.name, {
+				node,
+				pos,
+				holder: $pos.depth > 0 ? {
+					pos: $pos.before($pos.depth),
+					size: $pos.parent.nodeSize
+				} : null
+			});
+		}
+		return !node.isTextblock;
+	});
+	return {
+		derived,
+		blockById: (id) => blocks.get(id) ?? null,
+		assetBlocks: (name) => assets.get(name) ?? NONE,
+		derivedFromBlock: (id) => byBlock.get(id) ?? NONE,
+		derivedFromAsset: (name) => byAsset.get(name) ?? NONE
+	};
+}
+const INDEXES = /* @__PURE__ */ new WeakMap();
+/** The derivation index of `doc`, built once per document version (the `doc` node is immutable, so an edit yields a new index). */
+function derivationIndexOf(doc) {
+	let index = INDEXES.get(doc);
+	if (!index) INDEXES.set(doc, index = buildIndex(doc));
+	return index;
+}
+const within = (pos, range) => range.pos < pos && pos < range.pos + range.size;
+/**
+* The Derived blocks made from the original at `originalPos` (a Block in `doc`), in document order. They point at its block ID, or
+* at an asset the original holds as a direct child (its source media); a Derived block moved out of the original still counts. When
+* several blocks hold the same asset (a duplicated Typed block), a Derived block belongs to the holder that contains it, else to the first
+* holder. Derivations from another document (`isForeignSource` against `documentId`) are not listed.
+*/
+function derivedOf(doc, originalPos, documentId) {
+	const original = doc.nodeAt(originalPos);
+	if (!original) return [];
+	const index = derivationIndexOf(doc);
+	const found = /* @__PURE__ */ new Map();
+	const id = blockIdOf(original);
+	if (id) {
+		for (const entry of index.derivedFromBlock(id)) if (!isForeignSource(entry.derivation, documentId)) found.set(entry.pos, entry);
+	}
+	const range = {
+		pos: originalPos,
+		size: original.nodeSize
+	};
+	const names = /* @__PURE__ */ new Set();
+	original.forEach((child) => {
+		const src = child.attrs.src;
+		const asset = typeof src === "string" ? assetRefOf(src) : null;
+		if (asset) names.add(asset.name);
+	});
+	for (const name of names) {
+		const holders = index.assetBlocks(name).flatMap((block) => block.holder ? [block.holder] : []);
+		for (const entry of index.derivedFromAsset(name)) {
+			const owner = holders.find((holder) => within(entry.pos, holder)) ?? holders[0];
+			if (owner && owner.pos === range.pos) found.set(entry.pos, entry);
+		}
+	}
+	return [...found.values()].sort((a, b) => a.pos - b.pos);
+}
+/**
+* The original of the Derived block at `derivedPos`: for a block source the block with that ID, for an asset source the block that
+* holds the asset (the one next to the Derived block when several do). `missing` is the source-missing state: the original was
+* deleted, so the Derived block stays without it. Null when the node at `derivedPos` is not a Derived block.
+*/
+function derivationOriginOf(doc, derivedPos, documentId) {
+	const derived = doc.nodeAt(derivedPos);
+	const derivation = derived && derivationOf(derived);
+	if (!derivation) return null;
+	if (isForeignSource(derivation, documentId)) return { status: "foreign" };
+	const index = derivationIndexOf(doc);
+	if ("block" in derivation.from) {
+		const block = index.blockById(derivation.from.block);
+		return block ? {
+			status: "found",
+			...block
+		} : { status: "missing" };
+	}
+	const candidates = index.assetBlocks(derivation.from.asset);
+	const own = candidates.find((candidate) => candidate.holder && within(derivedPos, candidate.holder)) ?? candidates[0];
+	return own ? {
+		status: "found",
+		node: own.node,
+		pos: own.pos
+	} : { status: "missing" };
+}
+/** The state of the Derived block at `derivedPos` of `doc`; null when the node there is not a Derived block. */
+function derivationState(doc, derivedPos, bodyHash, documentId) {
+	const derived = doc.nodeAt(derivedPos);
+	const derivation = derived && derivationOf(derived);
+	const origin = derivationOriginOf(doc, derivedPos, documentId);
+	if (!derivation || !origin) return null;
+	let stale = null;
+	if (origin.status === "found" && "asset" in derivation.from) {
+		const hash = origin.node.attrs.hash;
+		stale = typeof hash === "string" && hash && derivation.inputHash ? hash !== derivation.inputHash : null;
+	}
+	const edited = derivation.outputHash ? bodyHash() !== derivation.outputHash : null;
+	return {
+		source: origin.status,
+		stale,
+		edited
+	};
+}
+//#endregion
+export { DERIVATION_KEY, assetRefOf, derivationIndexOf, derivationOf, derivationOriginOf, derivationState, derivedChildrenOf, derivedOf, isForeignSource };
+
+//# sourceMappingURL=derivation.js.map

package/dist/core/derivation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"derivation.js","names":[],"sources":["../../src/core/derivation.ts"],"sourcesContent":["// Framework-free and server-importable: where a Block's content comes from. A Derived block (transcript, full text, description,\n// AI result, copy) records in `meta.derivation` what it was made from (its Derivation). The link is stored on the Derived block\n// only; the original finds its Derived blocks through an index computed from block IDs and asset names, never through a stored\n// back-pointer, so concurrent edits (Yjs merges, moves, deletes) cannot leave two blocks disagreeing. The `derived` capability\n// (declared by the composites feature, which owns `meta`) reads the record through `derivationOf`.\nimport type { Node as PMNode } from '@tiptap/pm/model'\nimport { EDITOR_API } from './api-routes'\nimport { blockIdOf } from './schema/block-ids'\n\n/** `meta` key of a Derivation. */\nexport const DERIVATION_KEY = 'derivation'\n\n/** How a Derived block was made; `ai:<typeId>` for a block derived from another block by the model. */\nexport type DerivationMethod = 'transcription' | 'pdf-text' | 'ocr' | 'description' | 'bibliography' | (string & {})\n\n/** What a Derived block was made from: an uploaded asset (by asset name) or another block (by block id). */\nexport type DerivationSource = { asset: string } | { block: string, /** Document the block lives in; absent = this document. */ document?: string }\n\n/** `meta.derivation` of a Derived block. */\nexport interface Derivation {\n  from: DerivationSource\n  method: DerivationMethod\n  model?: string\n  /** ISO timestamp. */\n  createdAt: string\n  /** SHA-256 hex of the asset bytes / of the source block's Markdown; `''` when unknown. */\n  inputHash: string\n  /** SHA-256 hex of the produced body's Markdown; `''` when unknown. */\n  outputHash: string\n  /** Asset name of the stored raw output (text/markdown). */\n  output?: string\n}\n\n/** The derivation of a block (`meta.derivation` with a `from` object and a `method`); null when it has none. */\nexport function derivationOf(node: PMNode): Derivation | null {\n  const meta: unknown = node.attrs.meta\n  const value = meta && typeof meta === 'object' ? (meta as Record<string, unknown>)[DERIVATION_KEY] : undefined\n  if (!value || typeof value !== 'object') return null\n  const { from, method } = value as Record<string, unknown>\n  if (!from || typeof from !== 'object' || typeof method !== 'string') return null\n  return value as Derivation\n}\n\n/** Whether `derivation` points at a block of another document than `documentId` (the open one; null/undefined = unknown, so any named document is another). */\nexport function isForeignSource(derivation: Derivation, documentId: string | null | undefined): boolean {\n  return 'block' in derivation.from && !!derivation.from.document && derivation.from.document !== documentId\n}\n\nconst ASSET_URL_PREFIX = `${EDITOR_API}/assets/`\n// Same patterns as `features/media/assets.ts`; copied because core must not import features.\nconst ASSET_NAME = /^[0-9a-f-]{36}\\.[a-z0-9]{1,8}$/\nconst ASSET_DOCUMENT_ID = /^[A-Za-z0-9_-]{1,64}$/\n\n/** The stored asset behind an `/api/editor/assets/<documentId>/<name>` URL; null for any other `src`. */\nexport function assetRefOf(src: string): { documentId: string, name: string } | null {\n  if (!src.startsWith(ASSET_URL_PREFIX)) return null\n  const [documentId, name, ...rest] = src.slice(ASSET_URL_PREFIX.length).split('/')\n  if (rest.length || !documentId || !name || !ASSET_DOCUMENT_ID.test(documentId) || !ASSET_NAME.test(name)) return null\n  return { documentId, name }\n}\n\n/** The direct children of `parent` that are Derived blocks, with their child index. */\nexport function derivedChildrenOf(parent: PMNode): { node: PMNode, index: number, derivation: Derivation }[] {\n  const found: { node: PMNode, index: number, derivation: Derivation }[] = []\n  parent.forEach((node, _offset, index) => {\n    const derivation = derivationOf(node)\n    if (derivation) found.push({ node, index, derivation })\n  })\n  return found\n}\n\n/** A Derived block of the document with its position. */\nexport interface DerivedEntry {\n  node: PMNode\n  pos: number\n  derivation: Derivation\n}\n\n/** A block that holds a stored asset (its `src`), with the block around it (the holder) when there is one. */\nexport interface AssetBlock {\n  node: PMNode\n  pos: number\n  /** Position and size of the enclosing block of the asset block; the document itself has none. */\n  holder: { pos: number, size: number } | null\n}\n\n/**\n * The reverse index of one document version: Derived blocks by what they were made from, and the blocks they can have been\n * made from by block ID and by asset name. Computed from the document alone and memoised per `doc` node (`derivationIndexOf`),\n * so it is exactly as current as the document it was read from: a move or delete produces a new `doc` and with it a new index.\n */\nexport interface DerivationIndex {\n  /** Every Derived block, in document order. */\n  readonly derived: readonly DerivedEntry[]\n  /** The block with block ID `id` (any depth) and its position; null when the document has none. */\n  blockById: (id: string) => { node: PMNode, pos: number } | null\n  /** The blocks that hold the stored asset `name`, in document order. */\n  assetBlocks: (name: string) => readonly AssetBlock[]\n  /** The Derived blocks whose Derivation points at block `id`, in this or any document (`isForeignSource` tells them apart). */\n  derivedFromBlock: (id: string) => readonly DerivedEntry[]\n  /** The Derived blocks whose Derivation points at the stored asset `name`. */\n  derivedFromAsset: (name: string) => readonly DerivedEntry[]\n}\n\nconst NONE: readonly never[] = []\n\nfunction buildIndex(doc: PMNode): DerivationIndex {\n  const derived: DerivedEntry[] = []\n  const blocks = new Map<string, { node: PMNode, pos: number }>()\n  const assets = new Map<string, AssetBlock[]>()\n  const byBlock = new Map<string, DerivedEntry[]>()\n  const byAsset = new Map<string, DerivedEntry[]>()\n  const push = <K, V>(map: Map<K, V[]>, key: K, value: V) => {\n    const list = map.get(key)\n    if (list) list.push(value)\n    else map.set(key, [value])\n  }\n  doc.descendants((node, pos) => {\n    if (node.isText) return false\n    const id = blockIdOf(node)\n    if (id && !blocks.has(id)) blocks.set(id, { node, pos })\n    const derivation = derivationOf(node)\n    if (derivation) {\n      const entry: DerivedEntry = { node, pos, derivation }\n      derived.push(entry)\n      if ('block' in derivation.from) push(byBlock, derivation.from.block, entry)\n      else push(byAsset, derivation.from.asset, entry)\n    }\n    const src: unknown = node.attrs.src\n    const asset = typeof src === 'string' ? assetRefOf(src) : null\n    if (asset) {\n      const $pos = doc.resolve(pos)\n      push(assets, asset.name, { node, pos, holder: $pos.depth > 0 ? { pos: $pos.before($pos.depth), size: $pos.parent.nodeSize } : null })\n    }\n    // Inline content holds neither blocks nor assets.\n    return !node.isTextblock\n  })\n  return {\n    derived,\n    blockById: id => blocks.get(id) ?? null,\n    assetBlocks: name => assets.get(name) ?? NONE,\n    derivedFromBlock: id => byBlock.get(id) ?? NONE,\n    derivedFromAsset: name => byAsset.get(name) ?? NONE,\n  }\n}\n\nconst INDEXES = new WeakMap<PMNode, DerivationIndex>()\n\n/** The derivation index of `doc`, built once per document version (the `doc` node is immutable, so an edit yields a new index). */\nexport function derivationIndexOf(doc: PMNode): DerivationIndex {\n  let index = INDEXES.get(doc)\n  if (!index) INDEXES.set(doc, index = buildIndex(doc))\n  return index\n}\n\nconst within = (pos: number, range: { pos: number, size: number }) => range.pos < pos && pos < range.pos + range.size\n\n/**\n * The Derived blocks made from the original at `originalPos` (a Block in `doc`), in document order. They point at its block ID, or\n * at an asset the original holds as a direct child (its source media); a Derived block moved out of the original still counts. When\n * several blocks hold the same asset (a duplicated Typed block), a Derived block belongs to the holder that contains it, else to the first\n * holder. Derivations from another document (`isForeignSource` against `documentId`) are not listed.\n */\nexport function derivedOf(doc: PMNode, originalPos: number, documentId?: string | null): DerivedEntry[] {\n  const original = doc.nodeAt(originalPos)\n  if (!original) return []\n  const index = derivationIndexOf(doc)\n  const found = new Map<number, DerivedEntry>()\n  const id = blockIdOf(original)\n  if (id) for (const entry of index.derivedFromBlock(id)) if (!isForeignSource(entry.derivation, documentId)) found.set(entry.pos, entry)\n  const range = { pos: originalPos, size: original.nodeSize }\n  const names = new Set<string>()\n  original.forEach((child) => {\n    const src: unknown = child.attrs.src\n    const asset = typeof src === 'string' ? assetRefOf(src) : null\n    if (asset) names.add(asset.name)\n  })\n  for (const name of names) {\n    const holders = index.assetBlocks(name).flatMap(block => block.holder ? [block.holder] : [])\n    for (const entry of index.derivedFromAsset(name)) {\n      const owner = holders.find(holder => within(entry.pos, holder)) ?? holders[0]\n      if (owner && owner.pos === range.pos) found.set(entry.pos, entry)\n    }\n  }\n  return [...found.values()].sort((a, b) => a.pos - b.pos)\n}\n\n/** Where a Derived block's original is: in this document, in another document (not looked up here) or gone. */\nexport type DerivationOrigin\n  = | { status: 'found', node: PMNode, pos: number }\n    | { status: 'foreign' }\n    | { status: 'missing' }\n\n/**\n * The original of the Derived block at `derivedPos`: for a block source the block with that ID, for an asset source the block that\n * holds the asset (the one next to the Derived block when several do). `missing` is the source-missing state: the original was\n * deleted, so the Derived block stays without it. Null when the node at `derivedPos` is not a Derived block.\n */\nexport function derivationOriginOf(doc: PMNode, derivedPos: number, documentId?: string | null): DerivationOrigin | null {\n  const derived = doc.nodeAt(derivedPos)\n  const derivation = derived && derivationOf(derived)\n  if (!derivation) return null\n  if (isForeignSource(derivation, documentId)) return { status: 'foreign' }\n  const index = derivationIndexOf(doc)\n  if ('block' in derivation.from) {\n    const block = index.blockById(derivation.from.block)\n    return block ? { status: 'found', ...block } : { status: 'missing' }\n  }\n  const candidates = index.assetBlocks(derivation.from.asset)\n  const own = candidates.find(candidate => candidate.holder && within(derivedPos, candidate.holder)) ?? candidates[0]\n  return own ? { status: 'found', node: own.node, pos: own.pos } : { status: 'missing' }\n}\n\n/** What is known about a Derived block against its original. */\nexport interface DerivationState {\n  /** `missing` is the source-missing state; `foreign` means the original lives in another document and is not looked up. */\n  source: DerivationOrigin['status']\n  /**\n   * The original changed since the Derived block was made. Only an asset source can be told here (its stored `hash` against\n   * `inputHash`); null otherwise, also for a block source: callers with the editor compare the hash of the source's Markdown.\n   */\n  stale: boolean | null\n  /** The body's hash (computed lazily, it serialises the body) differs from `outputHash`; null when `outputHash` is unknown. */\n  edited: boolean | null\n}\n\n/** The state of the Derived block at `derivedPos` of `doc`; null when the node there is not a Derived block. */\nexport function derivationState(doc: PMNode, derivedPos: number, bodyHash: () => string, documentId?: string | null): DerivationState | null {\n  const derived = doc.nodeAt(derivedPos)\n  const derivation = derived && derivationOf(derived)\n  const origin = derivationOriginOf(doc, derivedPos, documentId)\n  if (!derivation || !origin) return null\n  let stale: boolean | null = null\n  if (origin.status === 'found' && 'asset' in derivation.from) {\n    const hash: unknown = origin.node.attrs.hash\n    stale = typeof hash === 'string' && hash && derivation.inputHash ? hash !== derivation.inputHash : null\n  }\n  const edited = derivation.outputHash ? bodyHash() !== derivation.outputHash : null\n  return { source: origin.status, stale, edited }\n}\n"],"mappings":"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"}

package/dist/core/derive.d.ts

@@ -0,0 +1,61 @@
+import { Ability } from "./schema/abilities.js";
+import { MenuItem } from "./command-types.js";
+import { BlockAction } from "./extension-points.js";
+import { EditorPreset, FeatureContext } from "./feature.js";
+import { Editor } from "@tiptap/core";
+import { Node as Node$1 } from "@tiptap/pm/model";
+//#region src/core/derive.d.ts
+/** What a method reads: the original block (`node` at `pos`), its editor and the surface's context (backend, public AI flags, settings, notices, translations). */
+export interface DeriveContext {
+  editor: Editor;
+  node: Node$1;
+  /** Position right before `node`. */
+  pos: number;
+  ctx: FeatureContext;
+}
+interface DeriveMethodBase {
+  /** Unique across the preset; also the id of the block action generated from the method. */
+  id: string;
+  /** Menu label, in the language of the surface (`ctx.t`). */
+  label: (ctx: FeatureContext) => string;
+  /** Iconify name, e.g. `i-lucide-captions`. */
+  icon: string;
+  /** Shown only on blocks that have this ability (`BlockAction.ability`). */
+  ability?: Ability;
+  /** Position among the block actions (`BlockAction.order`). */
+  order?: number;
+  placement?: BlockAction['placement'];
+  /** Capability ids the original must all have (built-in or declared by a Feature); every id must be declared when the preset is defined. */
+  requires: readonly string[];
+  /** Backend flags and per-block conditions (`backend.ai` or `ai?.transcription` of the feature context `ctx.ctx`, a source that can be read); absent: always available where `requires` holds. */
+  available?: (ctx: DeriveContext) => boolean;
+}
+/**
+ * One way to make a new block or text from a block. Either `run`, or `menu` for a method with sub-choices (derive into one of several
+ * Block types). The method itself writes the result and, where it creates a Derived block, its Derivation (`Derivation.method`).
+ */
+export type DeriveMethod = DeriveMethodBase & ({
+  run: (ctx: DeriveContext) => void;
+  menu?: never;
+} | {
+  menu: (ctx: DeriveContext) => MenuItem[];
+  run?: never;
+});
+/** The merged derive methods of a preset: the declarations, shared by every editor created from it. */
+export interface DeriveRegistry {
+  /** In feature order. */
+  readonly methods: readonly DeriveMethod[];
+  get: (id: string) => DeriveMethod | undefined;
+}
+export declare function createDeriveRegistry(methods: readonly DeriveMethod[]): DeriveRegistry;
+/** The methods that can run on the block at `pos` of `editor`: the block has every capability the method `requires` and its `available` holds. Empty without a block there or without a preset. */
+export declare function deriveMethodsAt(editor: Editor, ctx: FeatureContext, pos: number): readonly DeriveMethod[];
+/**
+ * The block actions of the preset's derive methods, one per method, in the shape the block UI renders: `requires` and the
+ * ability gate them as they gate every action, `available` is the visibility check. The menu a user sees is unchanged by
+ * the consolidation.
+ */
+export declare function deriveActionsOf(preset: EditorPreset, ctx: FeatureContext): BlockAction[];
+//#endregion
+export {};
+//# sourceMappingURL=derive.d.ts.map

package/dist/core/derive.js

@@ -0,0 +1,69 @@
+import { nodeAtPos } from "./util.js";
+import { capabilitiesOf } from "./capabilities.js";
+//#region src/core/derive.ts
+function createDeriveRegistry(methods) {
+	const byId = new Map(methods.map((method) => [method.id, method]));
+	return {
+		methods,
+		get: (id) => byId.get(id)
+	};
+}
+/** The methods that can run on the block at `pos` of `editor`: the block has every capability the method `requires` and its `available` holds. Empty without a block there or without a preset. */
+function deriveMethodsAt(editor, ctx, pos) {
+	const methods = editor.storage.editorPreset?.deriveMethods.methods;
+	const node = methods?.length ? nodeAtPos(editor.state.doc, pos) : null;
+	if (!methods || !node) return [];
+	const capabilities = capabilitiesOf(editor, node);
+	const at = {
+		editor,
+		node,
+		pos,
+		ctx
+	};
+	return methods.filter((method) => method.requires.every((id) => capabilities.has(id)) && (method.available?.(at) ?? true));
+}
+/**
+* The block actions of the preset's derive methods, one per method, in the shape the block UI renders: `requires` and the
+* ability gate them as they gate every action, `available` is the visibility check. The menu a user sees is unchanged by
+* the consolidation.
+*/
+function deriveActionsOf(preset, ctx) {
+	return preset.deriveMethods.methods.map((method) => {
+		const base = {
+			id: method.id,
+			label: method.label(ctx),
+			icon: method.icon,
+			requires: method.requires,
+			...method.ability !== void 0 && { ability: method.ability },
+			...method.order !== void 0 && { order: method.order },
+			...method.placement && { placement: method.placement },
+			...method.available && { isVisible: ({ editor, node, pos }) => method.available({
+				editor,
+				node,
+				pos,
+				ctx
+			}) }
+		};
+		return method.menu ? {
+			...base,
+			menu: ({ editor, node, pos }) => method.menu({
+				editor,
+				node,
+				pos,
+				ctx
+			})
+		} : {
+			...base,
+			run: ({ editor, node, pos }) => method.run({
+				editor,
+				node,
+				pos,
+				ctx
+			})
+		};
+	});
+}
+//#endregion
+export { createDeriveRegistry, deriveActionsOf, deriveMethodsAt };
+
+//# sourceMappingURL=derive.js.map

package/dist/core/derive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive.js","names":[],"sources":["../../src/core/derive.ts"],"sourcesContent":["import type { Editor } from '@tiptap/core'\nimport type { Node as PMNode } from '@tiptap/pm/model'\nimport { capabilitiesOf } from './capabilities'\nimport type { MenuItem } from './command-types'\nimport type { BlockAction } from './extension-points'\nimport type { EditorPreset, FeatureContext } from './feature'\nimport type { Ability } from './schema/abilities'\nimport { nodeAtPos } from './util'\n\n// Framework-free and server-importable. Transcription, text extraction (PDF text, OCR, image description), summary, AI fill, AI\n// derivation into another Block type and bibliography fetch all \"produce something from this block\". Each is one `DeriveMethod`\n// that a Feature contributes through `EditorFeature.deriveMethods`; the preset merges them into one registry, and the block\n// actions the user sees are generated from it (`deriveActionsOf`), so the menu keeps its entries while one registration replaces\n// the separate action, predicate and backend check each used to have.\n\n/** What a method reads: the original block (`node` at `pos`), its editor and the surface's context (backend, public AI flags, settings, notices, translations). */\nexport interface DeriveContext {\n  editor: Editor\n  node: PMNode\n  /** Position right before `node`. */\n  pos: number\n  ctx: FeatureContext\n}\n\ninterface DeriveMethodBase {\n  /** Unique across the preset; also the id of the block action generated from the method. */\n  id: string\n  /** Menu label, in the language of the surface (`ctx.t`). */\n  label: (ctx: FeatureContext) => string\n  /** Iconify name, e.g. `i-lucide-captions`. */\n  icon: string\n  /** Shown only on blocks that have this ability (`BlockAction.ability`). */\n  ability?: Ability\n  /** Position among the block actions (`BlockAction.order`). */\n  order?: number\n  placement?: BlockAction['placement']\n  /** Capability ids the original must all have (built-in or declared by a Feature); every id must be declared when the preset is defined. */\n  requires: readonly string[]\n  /** Backend flags and per-block conditions (`backend.ai` or `ai?.transcription` of the feature context `ctx.ctx`, a source that can be read); absent: always available where `requires` holds. */\n  available?: (ctx: DeriveContext) => boolean\n}\n\n/**\n * One way to make a new block or text from a block. Either `run`, or `menu` for a method with sub-choices (derive into one of several\n * Block types). The method itself writes the result and, where it creates a Derived block, its Derivation (`Derivation.method`).\n */\nexport type DeriveMethod = DeriveMethodBase & (\n  | { run: (ctx: DeriveContext) => void, menu?: never }\n  | { menu: (ctx: DeriveContext) => MenuItem[], run?: never }\n)\n\n/** The merged derive methods of a preset: the declarations, shared by every editor created from it. */\nexport interface DeriveRegistry {\n  /** In feature order. */\n  readonly methods: readonly DeriveMethod[]\n  get: (id: string) => DeriveMethod | undefined\n}\n\nexport function createDeriveRegistry(methods: readonly DeriveMethod[]): DeriveRegistry {\n  const byId = new Map(methods.map(method => [method.id, method]))\n  return { methods, get: id => byId.get(id) }\n}\n\n/** The methods that can run on the block at `pos` of `editor`: the block has every capability the method `requires` and its `available` holds. Empty without a block there or without a preset. */\nexport function deriveMethodsAt(editor: Editor, ctx: FeatureContext, pos: number): readonly DeriveMethod[] {\n  const methods = editor.storage.editorPreset?.deriveMethods.methods\n  const node = methods?.length ? nodeAtPos(editor.state.doc, pos) : null\n  if (!methods || !node) return []\n  const capabilities = capabilitiesOf(editor, node)\n  const at: DeriveContext = { editor, node, pos, ctx }\n  return methods.filter(method => method.requires.every(id => capabilities.has(id)) && (method.available?.(at) ?? true))\n}\n\n/**\n * The block actions of the preset's derive methods, one per method, in the shape the block UI renders: `requires` and the\n * ability gate them as they gate every action, `available` is the visibility check. The menu a user sees is unchanged by\n * the consolidation.\n */\nexport function deriveActionsOf(preset: EditorPreset, ctx: FeatureContext): BlockAction[] {\n  return preset.deriveMethods.methods.map((method): BlockAction => {\n    const base = {\n      id: method.id,\n      label: method.label(ctx),\n      icon: method.icon,\n      requires: method.requires,\n      ...(method.ability !== undefined && { ability: method.ability }),\n      ...(method.order !== undefined && { order: method.order }),\n      ...(method.placement && { placement: method.placement }),\n      ...(method.available && { isVisible: ({ editor, node, pos }: { editor: Editor, node: PMNode, pos: number }) => method.available!({ editor, node, pos, ctx }) }),\n    }\n    return method.menu\n      ? { ...base, menu: ({ editor, node, pos }) => method.menu!({ editor, node, pos, ctx }) }\n      : { ...base, run: ({ editor, node, pos }) => method.run!({ editor, node, pos, ctx }) }\n  })\n}\n"],"mappings":";;;AA0DA,SAAgB,qBAAqB,SAAkD;CACrF,MAAM,OAAO,IAAI,IAAI,QAAQ,KAAI,WAAU,CAAC,OAAO,IAAI,MAAM,CAAC,CAAC;CAC/D,OAAO;EAAE;EAAS,MAAK,OAAM,KAAK,IAAI,EAAE;CAAE;AAC5C;;AAGA,SAAgB,gBAAgB,QAAgB,KAAqB,KAAsC;CACzG,MAAM,UAAU,OAAO,QAAQ,cAAc,cAAc;CAC3D,MAAM,OAAO,SAAS,SAAS,UAAU,OAAO,MAAM,KAAK,GAAG,IAAI;CAClE,IAAI,CAAC,WAAW,CAAC,MAAM,OAAO,CAAC;CAC/B,MAAM,eAAe,eAAe,QAAQ,IAAI;CAChD,MAAM,KAAoB;EAAE;EAAQ;EAAM;EAAK;CAAI;CACnD,OAAO,QAAQ,QAAO,WAAU,OAAO,SAAS,OAAM,OAAM,aAAa,IAAI,EAAE,CAAC,MAAM,OAAO,YAAY,EAAE,KAAK,KAAK;AACvH;;;;;;AAOA,SAAgB,gBAAgB,QAAsB,KAAoC;CACxF,OAAO,OAAO,cAAc,QAAQ,KAAK,WAAwB;EAC/D,MAAM,OAAO;GACX,IAAI,OAAO;GACX,OAAO,OAAO,MAAM,GAAG;GACvB,MAAM,OAAO;GACb,UAAU,OAAO;GACjB,GAAI,OAAO,YAAY,KAAA,KAAa,EAAE,SAAS,OAAO,QAAQ;GAC9D,GAAI,OAAO,UAAU,KAAA,KAAa,EAAE,OAAO,OAAO,MAAM;GACxD,GAAI,OAAO,aAAa,EAAE,WAAW,OAAO,UAAU;GACtD,GAAI,OAAO,aAAa,EAAE,YAAY,EAAE,QAAQ,MAAM,UAAyD,OAAO,UAAW;IAAE;IAAQ;IAAM;IAAK;GAAI,CAAC,EAAE;EAC/J;EACA,OAAO,OAAO,OACV;GAAE,GAAG;GAAM,OAAO,EAAE,QAAQ,MAAM,UAAU,OAAO,KAAM;IAAE;IAAQ;IAAM;IAAK;GAAI,CAAC;EAAE,IACrF;GAAE,GAAG;GAAM,MAAM,EAAE,QAAQ,MAAM,UAAU,OAAO,IAAK;IAAE;IAAQ;IAAM;IAAK;GAAI,CAAC;EAAE;CACzF,CAAC;AACH"}