@openeditor/custom-block 0.0.46

package/README.md

@@ -0,0 +1,60 @@
+# OpenEditor custom blocks
+
+`@openeditor/custom-block` defines the only public custom-block interface. Every installed block uses the fixed `customBlock` document node. Installation does not change the ProseMirror schema.
+
+Use the headless entry point for the portable definition, registry, validation manifest, migrations, and static export. Import authoring code from `@openeditor/custom-block/editor`. Import published Viewer code from `@openeditor/custom-block/viewer`. The Viewer entry point does not import Tiptap or editor code.
+
+```ts
+import { defineOpenEditorCustomBlock } from "@openeditor/custom-block";
+
+export const card = defineOpenEditorCustomBlock({
+  id: "acme.card",
+  label: "Card",
+  version: 1,
+  dataSchema: {
+    type: "object",
+    properties: { title: { type: "string", minLength: 1 } },
+    required: ["title"],
+    additionalProperties: false,
+  },
+  initialData: () => ({ title: "Untitled" }),
+  toHtml: ({ data }) => ({ tag: "article", children: [data.title] }),
+  toText: ({ data }) => data.title,
+});
+```
+
+Static HTML uses an OpenEditor-owned safe tree. It does not accept raw HTML. Use the general `{ type: "document" }` data schema and the Editor and Viewer `host.fields.document` adapters for nested rich documents. Use `host.resolveUrl`, `host.links`, `host.icons`, and `host.assets` for product-neutral host facilities.
+
+Define authoring and published Viewer adapters in separate files:
+
+```tsx
+// card-editor.tsx
+import { defineOpenEditorCustomBlockEditor } from "@openeditor/custom-block/editor";
+import { card } from "./card";
+
+export const cardEditor = defineOpenEditorCustomBlockEditor({
+  block: card,
+  render: ({ data, updateData }) => (
+    <input value={data.title} onChange={(event) => updateData({ title: event.target.value })} />
+  ),
+});
+```
+
+```tsx
+// card-viewer.tsx
+import { defineOpenEditorCustomBlockViewer } from "@openeditor/custom-block/viewer";
+import { card } from "./card";
+
+export const cardViewer = defineOpenEditorCustomBlockViewer({
+  block: card,
+  render: ({ data }) => <article>{data.title}</article>,
+});
+```
+
+Create one registry from headless definitions. Pass Editor adapters only to authoring surfaces and Viewer adapters only to `@openeditor/react/viewer`. The host provides `fields.document`, safe URL resolution, optional navigation, icon catalog, and managed raster assets. A Viewer adapter cannot update saved data.
+
+Use integer-keyed `migrations` to convert stored data to the current version. Missing, disabled, incompatible, and invalid blocks preserve the original node and return an explicit registry resolution status. Backends validate `registry.manifests` with `validateOpenEditorCustomBlockEnvelope`; manifests contain JSON only and do not execute extension code. Use `conformOpenEditorCustomBlock(definition)` in each block package test to verify initial data, manifest validation, and safe static output.
+
+Use `{ type: "string", format: "asset-id" }` for a host-managed asset reference. Asset IDs are opaque, have a maximum of 128 characters, and cannot contain URLs, paths, whitespace, or control characters. A backend can call `extractOpenEditorCustomBlockAssetReferences(envelope, manifests)` to authorize all asset references, including references in nested OpenEditor document fields, without loading block code.
+
+Portable `constraints` cover primitive and keyed uniqueness, scoped map keys, references, acyclic graphs, and conditional URL policies. For example, `keysIn` can validate each directory row against the column IDs in the same directory. These constraints are JSON data in the manifest and run in backend validation.

package/dist/editor.d.ts

@@ -0,0 +1,49 @@
+import * as react from 'react';
+import { ComponentType, ReactNode } from 'react';
+import { OpenEditorDocument, ProseMirrorNode } from '@openeditor/core';
+import { OpenEditorCustomBlockData, OpenEditorCustomBlockDefinition, OpenEditorCustomBlockHost, OpenEditorCustomBlockRegistry } from './index.js';
+import { Node } from '@tiptap/core';
+
+type OpenEditorCustomBlockDocumentEditorProps = {
+    value: OpenEditorDocument;
+    onChange: (value: OpenEditorDocument) => void;
+    ariaLabel: string;
+};
+type OpenEditorCustomBlockEditorHost = OpenEditorCustomBlockHost & {
+    fields: {
+        document: ComponentType<OpenEditorCustomBlockDocumentEditorProps>;
+    };
+};
+type OpenEditorCustomBlockEditorContext<TData extends OpenEditorCustomBlockData> = {
+    data: Readonly<TData>;
+    instanceId: string;
+    host: OpenEditorCustomBlockEditorHost;
+    updateData: (update: TData | ((current: Readonly<TData>) => TData)) => void;
+    selected: boolean;
+};
+type OpenEditorCustomBlockEditorAdapter<TData extends OpenEditorCustomBlockData = any> = {
+    block: OpenEditorCustomBlockDefinition<TData>;
+    render: ComponentType<OpenEditorCustomBlockEditorContext<TData>>;
+};
+declare const defineOpenEditorCustomBlockEditor: <TData extends OpenEditorCustomBlockData>(adapter: OpenEditorCustomBlockEditorAdapter<TData>) => OpenEditorCustomBlockEditorAdapter<TData>;
+type OpenEditorCustomBlockEditorSurfaceProps = {
+    node: ProseMirrorNode;
+    registry: OpenEditorCustomBlockRegistry;
+    adapters: readonly OpenEditorCustomBlockEditorAdapter[];
+    host: OpenEditorCustomBlockEditorHost;
+    updateNode: (node: ProseMirrorNode) => void;
+    selected?: boolean;
+    fallback?: (input: {
+        node: ProseMirrorNode;
+        status: string;
+    }) => ReactNode;
+};
+declare const OpenEditorCustomBlockEditorSurface: ({ node, registry, adapters, host, updateNode, selected, fallback }: OpenEditorCustomBlockEditorSurfaceProps) => string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | react.ReactPortal | react.ReactElement<unknown, string | react.JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | react.JSX.Element;
+/** Installs the editor lifecycle on the one fixed customBlock schema node. */
+declare const createOpenEditorCustomBlockEditorExtension: (options: {
+    registry: OpenEditorCustomBlockRegistry;
+    adapters: readonly OpenEditorCustomBlockEditorAdapter[];
+    host: OpenEditorCustomBlockEditorHost;
+}) => Node<any, any>;
+
+export { type OpenEditorCustomBlockDocumentEditorProps, type OpenEditorCustomBlockEditorAdapter, type OpenEditorCustomBlockEditorContext, type OpenEditorCustomBlockEditorHost, OpenEditorCustomBlockEditorSurface, type OpenEditorCustomBlockEditorSurfaceProps, createOpenEditorCustomBlockEditorExtension, defineOpenEditorCustomBlockEditor };

package/dist/editor.js

@@ -0,0 +1,85 @@
+import { useRef, useEffect, Component } from 'react';
+import { Node } from '@tiptap/core';
+import { ReactNodeViewRenderer, NodeViewWrapper } from '@tiptap/react';
+import { jsxs, jsx } from 'react/jsx-runtime';
+
+// src/editor.tsx
+var defineOpenEditorCustomBlockEditor = (adapter) => adapter;
+var EditorAdapterErrorBoundary = class extends Component {
+  state = { failed: false };
+  static getDerivedStateFromError() {
+    return { failed: true };
+  }
+  componentDidCatch() {
+  }
+  render() {
+    return this.state.failed ? /* @__PURE__ */ jsx("div", { "data-openeditor-custom-block-error": "editor-error", role: "status", children: "Custom block editor unavailable." }) : this.props.children;
+  }
+};
+var ReadyEditorSurface = ({ resolved, adapter, host, updateNode, selected }) => {
+  const persistedMigration = useRef(null);
+  useEffect(() => {
+    if (!resolved.migrated) {
+      persistedMigration.current = null;
+      return;
+    }
+    const migrationKey = `${String(resolved.node.attrs?.["openeditor-id"])}:${String(resolved.node.attrs?.version)}`;
+    if (persistedMigration.current === migrationKey) return;
+    persistedMigration.current = migrationKey;
+    updateNode(resolved.node);
+  }, [resolved.migrated, resolved.node, updateNode]);
+  const Render = adapter.render;
+  const instanceId = String(resolved.node.attrs?.["openeditor-id"]);
+  const updateData = (update) => {
+    const data = typeof update === "function" ? update(resolved.data) : update;
+    updateNode({ ...resolved.node, attrs: { ...resolved.node.attrs, data } });
+  };
+  return /* @__PURE__ */ jsx(EditorAdapterErrorBoundary, { children: /* @__PURE__ */ jsx(Render, { data: resolved.data, host, instanceId, selected, updateData }) }, `${String(resolved.node.attrs?.["openeditor-id"])}:${resolved.definition.id}`);
+};
+var OpenEditorCustomBlockEditorSurface = ({ node, registry, adapters, host, updateNode, selected = false, fallback }) => {
+  const ids = /* @__PURE__ */ new Set();
+  for (const adapter2 of adapters) {
+    if (ids.has(adapter2.block.id)) throw new Error(`Duplicate custom block editor adapter "${adapter2.block.id}".`);
+    ids.add(adapter2.block.id);
+  }
+  const resolved = registry.resolve(node);
+  if (resolved.status !== "ready") return fallback?.({ node, status: resolved.status }) ?? /* @__PURE__ */ jsxs("div", { "data-openeditor-custom-block-error": resolved.status, role: "status", children: [
+    "Custom block unavailable: ",
+    resolved.status,
+    "."
+  ] });
+  const adapter = adapters.find((item) => item.block.id === resolved.definition.id);
+  if (!adapter) return fallback?.({ node, status: "missing-editor" }) ?? /* @__PURE__ */ jsx("div", { "data-openeditor-custom-block-error": "missing-editor", role: "status", children: "Custom block editor unavailable." });
+  if (adapter.block !== resolved.definition) return fallback?.({ node, status: "incompatible-editor" }) ?? /* @__PURE__ */ jsx("div", { "data-openeditor-custom-block-error": "incompatible-editor", role: "status", children: "Custom block editor unavailable." });
+  return /* @__PURE__ */ jsx(ReadyEditorSurface, { adapter, host, resolved, selected, updateNode: (next) => {
+    const checked = registry.resolve(next);
+    if (checked.status !== "ready") throw new Error(`Invalid data for custom block "${resolved.definition.id}".`);
+    updateNode(checked.node);
+  } });
+};
+var createOpenEditorCustomBlockEditorExtension = (options) => Node.create({
+  name: "customBlock",
+  group: "block",
+  atom: true,
+  isolating: true,
+  draggable: true,
+  addAttributes: () => ({ "openeditor-id": { default: null }, blockId: { default: null }, version: { default: null }, data: { default: {} } }),
+  renderHTML: ({ node }) => ["div", { "data-openeditor-custom-block": node.attrs.blockId ?? "unknown" }],
+  addNodeView() {
+    return ReactNodeViewRenderer((props) => /* @__PURE__ */ jsx(NodeViewWrapper, { "data-openeditor-custom-block": props.node.attrs.blockId ?? "unknown", children: /* @__PURE__ */ jsx(
+      OpenEditorCustomBlockEditorSurface,
+      {
+        adapters: options.adapters,
+        host: options.host,
+        node: props.node.toJSON(),
+        registry: options.registry,
+        selected: props.selected,
+        updateNode: (next) => props.updateAttributes(next.attrs ?? {})
+      }
+    ) }));
+  }
+});
+
+export { OpenEditorCustomBlockEditorSurface, createOpenEditorCustomBlockEditorExtension, defineOpenEditorCustomBlockEditor };
+//# sourceMappingURL=editor.js.map
+//# sourceMappingURL=editor.js.map

package/dist/editor.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/editor.tsx"],"names":["adapter"],"mappings":"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","file":"editor.js","sourcesContent":["import type { OpenEditorDocument, ProseMirrorNode } from \"@openeditor/core\";\nimport {\n  type OpenEditorCustomBlockData,\n  type OpenEditorCustomBlockDefinition,\n  type OpenEditorCustomBlockHost,\n  type OpenEditorCustomBlockRegistry,\n} from \"./index\";\nimport { Component, useEffect, useRef, type ComponentType, type ReactNode } from \"react\";\nimport { Node } from \"@tiptap/core\";\nimport { NodeViewWrapper, ReactNodeViewRenderer, type ReactNodeViewProps } from \"@tiptap/react\";\n\nexport type OpenEditorCustomBlockDocumentEditorProps = {\n  value: OpenEditorDocument;\n  onChange: (value: OpenEditorDocument) => void;\n  ariaLabel: string;\n};\nexport type OpenEditorCustomBlockEditorHost = OpenEditorCustomBlockHost & {\n  fields: { document: ComponentType<OpenEditorCustomBlockDocumentEditorProps> };\n};\nexport type OpenEditorCustomBlockEditorContext<TData extends OpenEditorCustomBlockData> = {\n  data: Readonly<TData>;\n  instanceId: string;\n  host: OpenEditorCustomBlockEditorHost;\n  updateData: (update: TData | ((current: Readonly<TData>) => TData)) => void;\n  selected: boolean;\n};\nexport type OpenEditorCustomBlockEditorAdapter<TData extends OpenEditorCustomBlockData = any> = {\n  block: OpenEditorCustomBlockDefinition<TData>;\n  render: ComponentType<OpenEditorCustomBlockEditorContext<TData>>;\n};\nexport const defineOpenEditorCustomBlockEditor = <TData extends OpenEditorCustomBlockData>(adapter: OpenEditorCustomBlockEditorAdapter<TData>) => adapter;\n\nexport type OpenEditorCustomBlockEditorSurfaceProps = {\n  node: ProseMirrorNode;\n  registry: OpenEditorCustomBlockRegistry;\n  adapters: readonly OpenEditorCustomBlockEditorAdapter[];\n  host: OpenEditorCustomBlockEditorHost;\n  updateNode: (node: ProseMirrorNode) => void;\n  selected?: boolean;\n  fallback?: (input: { node: ProseMirrorNode; status: string }) => ReactNode;\n};\n\nclass EditorAdapterErrorBoundary extends Component<{ children: ReactNode }, { failed: boolean }> {\n  state = { failed: false };\n  static getDerivedStateFromError() { return { failed: true }; }\n  componentDidCatch() {}\n  render() {\n    return this.state.failed\n      ? <div data-openeditor-custom-block-error=\"editor-error\" role=\"status\">Custom block editor unavailable.</div>\n      : this.props.children;\n  }\n}\n\nconst ReadyEditorSurface = ({ resolved, adapter, host, updateNode, selected }: { resolved: Extract<ReturnType<OpenEditorCustomBlockRegistry[\"resolve\"]>, { status: \"ready\" }>; adapter: OpenEditorCustomBlockEditorAdapter; host: OpenEditorCustomBlockEditorHost; updateNode: (node: ProseMirrorNode) => void; selected: boolean }) => {\n  const persistedMigration = useRef<string | null>(null);\n  useEffect(() => {\n    if (!resolved.migrated) { persistedMigration.current = null; return; }\n    const migrationKey = `${String(resolved.node.attrs?.[\"openeditor-id\"])}:${String(resolved.node.attrs?.version)}`;\n    if (persistedMigration.current === migrationKey) return;\n    persistedMigration.current = migrationKey;\n    updateNode(resolved.node);\n  }, [resolved.migrated, resolved.node, updateNode]);\n  const Render = adapter.render;\n  const instanceId = String(resolved.node.attrs?.[\"openeditor-id\"]);\n  const updateData = (update: OpenEditorCustomBlockData | ((current: Readonly<OpenEditorCustomBlockData>) => OpenEditorCustomBlockData)) => {\n    const data = typeof update === \"function\" ? update(resolved.data) : update;\n    updateNode({ ...resolved.node, attrs: { ...resolved.node.attrs, data } });\n  };\n  return (\n    <EditorAdapterErrorBoundary key={`${String(resolved.node.attrs?.[\"openeditor-id\"])}:${resolved.definition.id}`}>\n      <Render data={resolved.data} host={host} instanceId={instanceId} selected={selected} updateData={updateData} />\n    </EditorAdapterErrorBoundary>\n  );\n};\n\nexport const OpenEditorCustomBlockEditorSurface = ({ node, registry, adapters, host, updateNode, selected = false, fallback }: OpenEditorCustomBlockEditorSurfaceProps) => {\n  const ids = new Set<string>();\n  for (const adapter of adapters) {\n    if (ids.has(adapter.block.id)) throw new Error(`Duplicate custom block editor adapter \"${adapter.block.id}\".`);\n    ids.add(adapter.block.id);\n  }\n  const resolved = registry.resolve(node);\n  if (resolved.status !== \"ready\") return fallback?.({ node, status: resolved.status }) ?? <div data-openeditor-custom-block-error={resolved.status} role=\"status\">Custom block unavailable: {resolved.status}.</div>;\n  const adapter = adapters.find((item) => item.block.id === resolved.definition.id);\n  if (!adapter) return fallback?.({ node, status: \"missing-editor\" }) ?? <div data-openeditor-custom-block-error=\"missing-editor\" role=\"status\">Custom block editor unavailable.</div>;\n  if (adapter.block !== resolved.definition) return fallback?.({ node, status: \"incompatible-editor\" }) ?? <div data-openeditor-custom-block-error=\"incompatible-editor\" role=\"status\">Custom block editor unavailable.</div>;\n  return <ReadyEditorSurface adapter={adapter} host={host} resolved={resolved} selected={selected} updateNode={(next) => { const checked = registry.resolve(next); if (checked.status !== \"ready\") throw new Error(`Invalid data for custom block \"${resolved.definition.id}\".`); updateNode(checked.node); }} />;\n};\n\n/** Installs the editor lifecycle on the one fixed customBlock schema node. */\nexport const createOpenEditorCustomBlockEditorExtension = (options: {\n  registry: OpenEditorCustomBlockRegistry;\n  adapters: readonly OpenEditorCustomBlockEditorAdapter[];\n  host: OpenEditorCustomBlockEditorHost;\n}) => Node.create({\n  name: \"customBlock\",\n  group: \"block\",\n  atom: true,\n  isolating: true,\n  draggable: true,\n  addAttributes: () => ({ \"openeditor-id\": { default: null }, blockId: { default: null }, version: { default: null }, data: { default: {} } }),\n  renderHTML: ({ node }) => [\"div\", { \"data-openeditor-custom-block\": node.attrs.blockId ?? \"unknown\" }],\n  addNodeView() {\n    return ReactNodeViewRenderer((props: ReactNodeViewProps) => (\n      <NodeViewWrapper data-openeditor-custom-block={props.node.attrs.blockId ?? \"unknown\"}>\n        <OpenEditorCustomBlockEditorSurface\n          adapters={options.adapters}\n          host={options.host}\n          node={props.node.toJSON()}\n          registry={options.registry}\n          selected={props.selected}\n          updateNode={(next) => props.updateAttributes(next.attrs ?? {})}\n        />\n      </NodeViewWrapper>\n    ));\n  },\n});\n"]}

package/dist/index.d.ts

@@ -0,0 +1,257 @@
+import { JsonValue, OpenEditorDocument, ProseMirrorNode } from '@openeditor/core';
+export { JsonObject as OpenEditorCustomBlockJsonObject, JsonValue as OpenEditorCustomBlockJsonValue, OpenEditorDocument } from '@openeditor/core';
+
+declare const OPENEDITOR_CUSTOM_BLOCK_NODE: "customBlock";
+
+type OpenEditorCustomBlockId = `${string}.${string}`;
+/**
+ * A block-owned data record. The portable schema and bounded JSON validator
+ * enforce JSON at runtime. `unknown` values at this type boundary also allow
+ * the structurally wider `OpenEditorDocument` type in declared document fields.
+ */
+type OpenEditorCustomBlockData = Record<string, unknown>;
+/** Preserves a block's precise field types, including nested document fields. */
+type OpenEditorCustomBlockDataShape<TData extends object> = TData;
+type OpenEditorCustomBlockEnvelope<TData extends OpenEditorCustomBlockData = OpenEditorCustomBlockData> = {
+    blockId: OpenEditorCustomBlockId;
+    version: number;
+    data: TData;
+};
+type OpenEditorCustomBlockNode<TData extends OpenEditorCustomBlockData = OpenEditorCustomBlockData> = ProseMirrorNode & {
+    type: typeof OPENEDITOR_CUSTOM_BLOCK_NODE;
+    attrs: OpenEditorCustomBlockEnvelope<TData> & Record<string, unknown>;
+};
+type OpenEditorCustomBlockDiagnostic = {
+    path: string;
+    message: string;
+};
+type PortableSchemaBase = {
+    nullable?: boolean;
+    enum?: readonly JsonValue[];
+};
+type OpenEditorCustomBlockDataSchema = PortableSchemaBase & ({
+    type: "any";
+} | {
+    type: "string";
+    minLength?: number;
+    maxLength?: number;
+    format?: "asset-id";
+} | {
+    type: "number";
+    integer?: boolean;
+    minimum?: number;
+    maximum?: number;
+} | {
+    type: "boolean";
+} | {
+    type: "null";
+} | {
+    type: "oneOf";
+    variants: readonly OpenEditorCustomBlockDataSchema[];
+} | {
+    type: "document";
+} | {
+    type: "array";
+    items?: OpenEditorCustomBlockDataSchema;
+    minItems?: number;
+    maxItems?: number;
+} | {
+    type: "object";
+    properties?: Readonly<Record<string, OpenEditorCustomBlockDataSchema>>;
+    required?: readonly string[];
+    additionalProperties?: boolean | OpenEditorCustomBlockDataSchema;
+});
+type OpenEditorCustomBlockManifest = {
+    id: OpenEditorCustomBlockId;
+    label: string;
+    version: number;
+    dataSchema: OpenEditorCustomBlockDataSchema;
+    constraints?: readonly OpenEditorCustomBlockConstraint[];
+};
+type OpenEditorCustomBlockConstraint = {
+    kind: "unique";
+    array: string;
+} | {
+    kind: "uniqueBy";
+    array: string;
+    keys: readonly string[];
+} | {
+    kind: "keysIn";
+    scope?: string;
+    objects: string;
+    keys: string;
+    requireAll?: boolean;
+} | {
+    kind: "reference";
+    array: string;
+    field: string;
+    targetArray: string;
+    targetField: string;
+    nullable?: boolean;
+} | {
+    kind: "acyclic";
+    array: string;
+    id: string;
+    parent: string;
+} | {
+    kind: "graph";
+    array: string;
+    id: string;
+    parent: string;
+    siblingKeys?: readonly string[];
+} | {
+    kind: "url";
+    path: string;
+    allowRelative?: boolean;
+    requireSchemeSeparator?: boolean;
+    schemes?: readonly string[];
+    denySchemes?: readonly string[];
+    when?: {
+        field: string;
+        equals: JsonValue;
+    };
+};
+type OpenEditorCustomBlockMigration = (data: Readonly<OpenEditorCustomBlockData>) => OpenEditorCustomBlockData;
+type OpenEditorCustomBlockStaticContext<TData extends OpenEditorCustomBlockData> = {
+    data: Readonly<TData>;
+    renderDocument: (document: OpenEditorDocument) => OpenEditorCustomBlockSafeHtml;
+    documentToText: (document: OpenEditorDocument) => string;
+};
+type OpenEditorCustomBlockSafeHtml = string | number | null | false | {
+    tag: "div" | "span" | "p" | "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "article" | "section" | "aside" | "blockquote" | "figure" | "figcaption" | "ul" | "ol" | "li" | "dl" | "dt" | "dd" | "table" | "caption" | "thead" | "tbody" | "tr" | "th" | "td" | "strong" | "em" | "u" | "s" | "code" | "pre" | "a" | "img" | "br" | "hr";
+    attrs?: Readonly<Partial<Record<"aria-label" | "aria-current" | "role" | "title" | "href" | "src" | "alt" | "width" | "height" | "start" | "colspan" | "rowspan" | "scope", string | number | undefined>>>;
+    children?: readonly OpenEditorCustomBlockSafeHtml[];
+};
+type OpenEditorCustomBlockDefinition<TData extends OpenEditorCustomBlockData = any> = {
+    id: OpenEditorCustomBlockId;
+    label: string;
+    version: number;
+    dataSchema: OpenEditorCustomBlockDataSchema;
+    initialData: () => TData;
+    /** Optional in-process refinement. This function is not included in the portable manifest. */
+    validateData?: (data: Readonly<TData>) => string | readonly string[] | null | undefined;
+    constraints?: readonly OpenEditorCustomBlockConstraint[];
+    migrations?: Readonly<Record<number, OpenEditorCustomBlockMigration>>;
+    toHtml: (context: OpenEditorCustomBlockStaticContext<TData>) => OpenEditorCustomBlockSafeHtml;
+    toText: (context: OpenEditorCustomBlockStaticContext<TData>) => string;
+    manifest: OpenEditorCustomBlockManifest;
+};
+/** Opaque host asset IDs. URLs, paths, whitespace, and control characters are not valid. */
+declare const OPENEDITOR_CUSTOM_BLOCK_ASSET_ID_PATTERN: RegExp;
+/** Validates one value against a portable JSON-only custom-block schema. */
+declare const validateOpenEditorCustomBlockDataValue: (value: unknown, schema: OpenEditorCustomBlockDataSchema) => {
+    valid: true;
+    diagnostics: readonly [];
+} | {
+    valid: false;
+    diagnostics: readonly OpenEditorCustomBlockDiagnostic[];
+};
+declare const defineOpenEditorCustomBlock: <TData extends OpenEditorCustomBlockData>(input: Omit<OpenEditorCustomBlockDefinition<TData>, "manifest">) => OpenEditorCustomBlockDefinition<TData>;
+type UnavailableStatus = "missing" | "disabled" | "incompatible" | "invalid";
+type OpenEditorResolvedCustomBlock<TData extends OpenEditorCustomBlockData = OpenEditorCustomBlockData> = {
+    status: "ready";
+    definition: OpenEditorCustomBlockDefinition<TData>;
+    node: OpenEditorCustomBlockNode<TData>;
+    data: TData;
+    migrated: boolean;
+} | {
+    status: UnavailableStatus;
+    node: ProseMirrorNode;
+    blockId?: string;
+    diagnostics: readonly OpenEditorCustomBlockDiagnostic[];
+};
+type OpenEditorCustomBlockRegistry = {
+    definitions: readonly OpenEditorCustomBlockDefinition[];
+    manifests: readonly OpenEditorCustomBlockManifest[];
+    get: (id: string) => OpenEditorCustomBlockDefinition | undefined;
+    isEnabled: (id: string) => boolean;
+    resolve: (node: ProseMirrorNode) => OpenEditorResolvedCustomBlock;
+    toHtml: (node: ProseMirrorNode) => string;
+    toText: (node: ProseMirrorNode) => string;
+};
+declare const escapeOpenEditorCustomBlockHtml: (value: unknown) => string;
+declare const renderOpenEditorCustomBlockSafeHtml: (value: OpenEditorCustomBlockSafeHtml) => string;
+declare const createOpenEditorCustomBlockRegistry: (definitions: readonly OpenEditorCustomBlockDefinition[], options?: {
+    disabled?: readonly string[];
+    renderDocument?: (document: OpenEditorDocument) => OpenEditorCustomBlockSafeHtml;
+    documentToText?: (document: OpenEditorDocument) => string;
+}) => OpenEditorCustomBlockRegistry;
+declare const createOpenEditorCustomBlockNode: <TData extends OpenEditorCustomBlockData>(registry: OpenEditorCustomBlockRegistry, id: string, data?: TData, options?: {
+    instanceId?: string;
+    createInstanceId?: () => string;
+}) => OpenEditorCustomBlockNode<TData>;
+declare const resolveOpenEditorCustomBlockNode: (registry: OpenEditorCustomBlockRegistry, node: ProseMirrorNode) => OpenEditorResolvedCustomBlock<OpenEditorCustomBlockData>;
+declare const validateOpenEditorCustomBlockEnvelope: (value: unknown, manifests: readonly OpenEditorCustomBlockManifest[], options?: {
+    mode?: "strict" | "preserve";
+    disabled?: readonly string[];
+}) => {
+    valid: false;
+    diagnostics: {
+        path: string;
+        message: string;
+    }[];
+    status?: undefined;
+} | {
+    valid: true;
+    diagnostics: readonly [];
+    status: "preserved";
+} | {
+    valid: true;
+    diagnostics: OpenEditorCustomBlockDiagnostic[];
+    status: "preserved-invalid";
+} | {
+    valid: true;
+    diagnostics: readonly [];
+    status?: undefined;
+};
+type OpenEditorCustomBlockAssetReference = {
+    id: string;
+    path: string;
+};
+/** Extracts host asset IDs from a portable manifest without loading extension code. */
+declare const extractOpenEditorCustomBlockAssetReferences: (value: unknown, manifests: readonly OpenEditorCustomBlockManifest[]) => readonly OpenEditorCustomBlockAssetReference[];
+type OpenEditorCustomBlockIcon = {
+    id: string;
+    label: string;
+};
+type OpenEditorCustomBlockAsset = {
+    id: string;
+    kind: "raster";
+    alt: string;
+    width?: number;
+    height?: number;
+};
+type OpenEditorCustomBlockHost = {
+    resolveUrl: (value: string, context: "navigation" | "asset") => string | null;
+    links?: {
+        resolve: (destination: {
+            href: string;
+            kind?: string;
+        }) => {
+            href: string;
+            external: boolean;
+            label?: string;
+        } | null;
+    };
+    navigate?: (url: string) => void | Promise<void>;
+    icons?: {
+        list: () => readonly OpenEditorCustomBlockIcon[];
+        render: (id: string) => unknown;
+    };
+    assets?: {
+        pick?: () => Promise<OpenEditorCustomBlockAsset | null>;
+        resolve: (id: string) => Promise<{
+            src: string;
+            alt: string;
+        } | null>;
+    };
+};
+type OpenEditorCustomBlockDocumentField = {
+    value: OpenEditorDocument;
+    onChange?: (value: OpenEditorDocument) => void;
+    readOnly: boolean;
+};
+/** Runs portable checks that custom-block packages can include in their test suites. */
+declare const conformOpenEditorCustomBlock: (definition: OpenEditorCustomBlockDefinition) => readonly OpenEditorCustomBlockDiagnostic[];
+
+export { OPENEDITOR_CUSTOM_BLOCK_ASSET_ID_PATTERN, OPENEDITOR_CUSTOM_BLOCK_NODE, type OpenEditorCustomBlockAsset, type OpenEditorCustomBlockAssetReference, type OpenEditorCustomBlockConstraint, type OpenEditorCustomBlockData, type OpenEditorCustomBlockDataSchema, type OpenEditorCustomBlockDataShape, type OpenEditorCustomBlockDefinition, type OpenEditorCustomBlockDiagnostic, type OpenEditorCustomBlockDocumentField, type OpenEditorCustomBlockEnvelope, type OpenEditorCustomBlockHost, type OpenEditorCustomBlockIcon, type OpenEditorCustomBlockId, type OpenEditorCustomBlockManifest, type OpenEditorCustomBlockMigration, type OpenEditorCustomBlockNode, type OpenEditorCustomBlockRegistry, type OpenEditorCustomBlockSafeHtml, type OpenEditorCustomBlockStaticContext, type OpenEditorResolvedCustomBlock, conformOpenEditorCustomBlock, createOpenEditorCustomBlockNode, createOpenEditorCustomBlockRegistry, defineOpenEditorCustomBlock, escapeOpenEditorCustomBlockHtml, extractOpenEditorCustomBlockAssetReferences, renderOpenEditorCustomBlockSafeHtml, resolveOpenEditorCustomBlockNode, validateOpenEditorCustomBlockDataValue, validateOpenEditorCustomBlockEnvelope };