@relyio/sdk 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,89 @@
 # @relyio/sdk
 
+## 0.13.0
+
+### Minor Changes
+
+- e678fb8: **`update()` and `restore()` say which entry links they left pointing nowhere.** `update()` returns the entry with `_metadata.brokenLinks`: each link another entry publishes whose anchor names a heading the revision took away, empty when it took none. `restore()` returns `_metadata.brokenLinks` beside `_metadata.leftOut`, both now in its type. A batch revision (`PATCH`, `PUT`) answers the same list under `data._metadata.brokenLinks`, with `returnData` or without, and a request retried with the same `Idempotency-Key` answers the list the first attempt did.
+- c2fe14d: **Filter by a reference inside blocks and rich text.** A typed client's `where()` and `fetchFirst()` accept a reference inside a list, a page builder or an object (`'sections.features'`) and a rich-text field that links to entries or declares a block holding a reference, each compared with an entry id: "pages that feature X". `$eq`/`$in` match an entry where some block holds it, `$ne`/`$nin` one where no block does, and `$isNull` asks whether any block holds a reference at all. Any other value inside a block, and a `json` field, is refused by name.
+- c2fe14d: **Heading anchors are unique per entry.** Headings are numbered across an entry's top-level rich-text fields in the order its type declares them, so `intro`'s "Overview" is `#overview` and `body`'s is `#overview-1`. `entryHeadingAnchors(entry)` computes an entry's anchors once; hand them to `<RichText anchors={…}>`, `renderRichText` or `richTextToHtml` (`anchors` option) and every field writes the ids an entry link's anchor names. A field rendered without `anchors` numbers its own headings, as before. A publish that takes away a heading other entries link to still lands, and the Content API's update answer lists the links it left pointing nowhere in `_metadata.brokenLinks`.
+- 39ea8c6: **A `json` field holds data nobody models.** `fields.json('chart', { config: { schema } })` declares a field whose value is any JSON value — an object, an array, a string, a number, a boolean or `null` — held to an optional JSON Schema on every write, a draft's included: a value the schema refuses is refused (`JSON_INVALID`), never stored. A read is typed by the schema — `type`, `properties`, `required`, `additionalProperties`, `items`, `enum`, `const`, `anyOf` and `oneOf` — and is `JsonValue` without one, never `any`:
+
+  ```ts
+  fields.json('chart', {
+    config: {
+      schema: {
+        type: 'object',
+        properties: { points: { type: 'array', items: { type: 'number' } } },
+        required: ['points'],
+      } as const,
+    },
+  })
+  // a read of `chart`: { points: number[] }
+  ```
+
+  Write the schema `as const` so `required`, `enum` and `const` keep their literals; `relyio generate-types` writes it so, and its Python target writes the same subset inline. A `json` field takes no `defaultValue`, and is neither searched nor filterable. The schema-modelling skill names the kind and when to reach for it.
+
+- c2d8071: **A preview can take an editor from any block to that block.** `relyioField` binds a value inside a field by its key path — `relyioField(page, 'sections[_key=="f2k6ub9s"].heading')` — the spelling a refused write already names a value by, and continues a binding it returned: `relyioField(binding, 'heading')` binds a field below it, `relyioField(binding, item)` an item of the list it binds. The attributes are the same five, version 1. `formatKeyPath` writes a key path and `parseKeyPath` reads one back, refusing an index, which names another item once a list is reordered.
+
+  `<Blocks>` and `<RichText>` take the field's binding as `field` and stamp each block, and each declared block and inline element, with its key path, on the element its component returns:
+
+  ```tsx
+  <Blocks
+    value={page.sections ?? []}
+    field={relyioField(page, 'sections')}
+    components={{
+      hero: (block, field) => (
+        <header>
+          <h1 {...relyioField(field, 'headline')}>{block.headline}</h1>
+          <RichText
+            value={block.body}
+            field={relyioField(field, 'body')}
+            components={{ callout: Callout }}
+          />
+        </header>
+      ),
+    }}
+  />
+  ```
+
+  Each component is handed its block's binding — a `<Blocks>` component as its second argument, a declared component as `field` — so a block inside a block carries its full path, `sections[_key=="f2k6ub9s"].body[_key=="c1"]`. A component that returns a fragment or an element of a component of its own spreads its binding itself. With no `field`, nothing is stamped and the markup is unchanged. The preview toolbar badges each stamped block and links it to its place in the Studio.
+
+- e0b742d: **`richTextToHtml` stamps each declared block with its key path, as `<RichText>` does.** Handed the field's binding as `field`, each declared Block and Inline element's writer is handed that node's binding as its second argument, and the one element it returns carries it — `data-relyio-field="body[_key==&quot;c1&quot;]"` after the element's own attributes — so a site rendering HTML without React still lets the preview toolbar take an editor from a block to the Studio:
+
+  ```ts
+  richTextToHtml(post.body, {
+    field: relyioField(post, 'body'),
+    declared: {
+      callout: (block, field) =>
+        `<aside>${richTextToHtml(block.body, { field: relyioField(field, 'body') })}</aside>`,
+    },
+  })
+  ```
+
+  A writer that returns text, several elements or an element it bound itself is written as it returns it; it holds the binding to write where it belongs. With no `field`, nothing is stamped and every writer is handed `undefined`.
+
+- 6f0ea50: **Rich text comes in and goes out as RelyIO Markdown: `@relyio/sdk/markdown`.** `richTextFromMarkdown(markdown)` reads a Markdown file into the rich-text tree, every node keyed and ready to write; `richTextToRelyIOMarkdown(value)` writes any rich-text value back as the same Markdown, and importing it again gives the same tree, keys aside. RelyIO Markdown is CommonMark with GitHub's tables, task lists and strikethrough, and directives for what Markdown has no syntax for — declared blocks and inline elements, entry links, code tabs, underline, highlight, sub- and superscript.
+
+  ```ts
+  import { richTextFromMarkdown, richTextToRelyIOMarkdown } from '@relyio/sdk/markdown'
+
+  const body = richTextFromMarkdown(await readFile('getting-started.md', 'utf8'))
+  await relyio.content('docPage').create({ title: 'Getting started', body })
+
+  richTextToRelyIOMarkdown(page.body) // the same Markdown, ready to edit and import again
+  ```
+
+  Markdown the tree cannot hold — HTML, an image, a footnote, a link's title — throws `RichTextMarkdownImportError`, whose `unplaced` names each one with its line and column; `readRichTextMarkdown` returns the tree and that list instead of throwing. A `table` or `code` field takes one block: `richTextFieldBlockFromMarkdown(markdown, 'table')` or `'codeGroup'`. Export throws `RichTextMarkdownExportError` for a node it cannot name. The parser has its own entry point, so a page that only renders rich text never loads it; `richTextToMarkdown` on the root, which writes plain Markdown and drops what it cannot hold, is unchanged.
+
+- 9873ca5: **A typed `where` takes what the API filters by everywhere it is offered, and an expanded singleton is typed as it is served.** `useEntries` and `relyioQueryOptions().entries()` take the `where` `client.content(type).query().where()` takes, so an object's field, a reference inside a block and `$isNull` compile there, and a `json` field or a whole list or object does not. A typed `asset(type)` client's `where()` and `fetchFirst()` are held to the same paths. `WhereOperator` gains `$inTheLast` and `$inTheNext` (`{ amount, unit }`), which a typed read offers on a `date` or `dateTime` field only, as the API asks them of nothing else. `children(id)` no longer takes `depth`: the route lists a parent's direct children, and refused every request that sent one with `400`; a nested tree is a list or entry read's `children()`. A singleton an include expands carries an entry's `_metadata` (`EntryMetadata`), not `SingletonMetadata`, and is typed so — in Python as `Expanded<Name>`, which a reference to the singleton now names.
+- 6c3d471: **A typed `where()` takes exactly what the API filters by.** `where()`, `fetchFirst()` and `fetch({ where })` name a field inside an object by its path — `{ 'pricing.basePrice': { $gte: 100 } }` — and take `$isNull` on any path. A condition the API refuses no longer compiles: a `json` field or a key inside one; a list, an object, a table or code as a whole; rich text that can point at no entry; and a reference or rich text a shared list translates item by item. `$regex`, which the API never read, is gone from `WhereOperator`. `fields.reference`, `fields.richText`, `fields.list` and `fields.object` keep the `localization` they were written with in their type, which is how a typed `where` tells a list translated whole from one translated item by item.
+
+### Patch Changes
+
+- 9ccfff0: **Filter by a reference or rich text a shared list translates item by item.** A typed client's `where()` now accepts these paths (`'sections.logo'` where each section's logo is translated): each item is matched in the read's locale by its own translation, or by that item's fallback, as the read shows it.
+- c2fe14d: **A slug may have segments.** `guide/schema/text-fields` is a valid slug; a leading, trailing or doubled slash is refused, naming which. Read an entry by such a slug with the slug encoded in the path (`guide%2Fschema%2Ftext-fields`), as the SDK already does.
+
 ## 0.12.0
 
 ### Minor Changes

package/dist/{chunk-3DRDHXLY.js → chunk-3NPPMGB6.js}

@@ -2,20 +2,252 @@ import { __name } from './chunk-XQ4QHWZE.js';
 
 /* RelyIO SDK - Built with ❤️ by the RelyIO Team */
 
+// src/rich-text/anchors.ts
+function richTextHeadingSlug(text) {
+  return text.trim().toLowerCase().replace(/[^\p{L}\p{M}\p{N}\s_-]/gu, "").replace(/\s/gu, "-");
+}
+__name(richTextHeadingSlug, "richTextHeadingSlug");
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+__name(isRecord, "isRecord");
+var BUILT_IN_CONTAINERS = /* @__PURE__ */ new Set([
+  "paragraph",
+  "heading",
+  "quote",
+  "list",
+  "listItem",
+  "codeGroup",
+  "table",
+  "tableRow",
+  "tableCell"
+]);
+function headingText(heading) {
+  if (!Array.isArray(heading.children)) return "";
+  let text = "";
+  for (const child of heading.children) {
+    if (!isRecord(child)) continue;
+    if (child._type === "lineBreak") text += " ";
+    else if (child._type === "text" && typeof child.text === "string") text += child.text;
+  }
+  return text;
+}
+__name(headingText, "headingText");
+function richTextHeadingAnchors(value) {
+  return anchorsAcross([value]);
+}
+__name(richTextHeadingAnchors, "richTextHeadingAnchors");
+function entryHeadingAnchors(entry) {
+  return anchorsAcross(isRecord(entry) ? Object.values(entry) : []);
+}
+__name(entryHeadingAnchors, "entryHeadingAnchors");
+function anchorsAcross(values) {
+  const anchors = /* @__PURE__ */ new Map();
+  const taken = /* @__PURE__ */ new Map();
+  const unique = /* @__PURE__ */ __name((slug) => {
+    let anchor = slug;
+    const seen = taken.get(slug);
+    if (seen !== void 0) {
+      let count = seen;
+      do {
+        count += 1;
+        anchor = `${slug}-${count}`;
+      } while (taken.has(anchor));
+      taken.set(slug, count);
+    }
+    taken.set(anchor, 0);
+    return anchor;
+  }, "unique");
+  const visit = /* @__PURE__ */ __name((nodes) => {
+    for (const node of nodes) {
+      if (!isRecord(node) || typeof node._type !== "string") continue;
+      if (node._type === "heading") {
+        const slug = richTextHeadingSlug(headingText(node));
+        if (slug !== "") anchors.set(node, unique(slug));
+        continue;
+      }
+      if (BUILT_IN_CONTAINERS.has(node._type) && Array.isArray(node.children)) visit(node.children);
+    }
+  }, "visit");
+  for (const value of values) {
+    if (isRecord(value) && value._type === "richText" && Array.isArray(value.children)) {
+      visit(value.children);
+    }
+  }
+  return anchors;
+}
+__name(anchorsAcross, "anchorsAcross");
+
+// src/binding/key-path.ts
+var ITEM_SELECTOR = "[_key==";
+function formatKeyPath(listPath, key, field) {
+  const item = `${listPath}${ITEM_SELECTOR}${JSON.stringify(key)}]`;
+  return field === void 0 ? item : `${item}.${field}`;
+}
+__name(formatKeyPath, "formatKeyPath");
+function parseKeyPath(path) {
+  const segments = [];
+  let at = 0;
+  let expectField = true;
+  while (at < path.length) {
+    if (path.startsWith(ITEM_SELECTOR, at)) {
+      const previous = segments[segments.length - 1];
+      if (expectField || previous === void 0 || !("field" in previous)) return null;
+      const quoted = readQuoted(path, at + ITEM_SELECTOR.length);
+      if (quoted === null || path[quoted.end] !== "]") return null;
+      segments.push({ key: quoted.value });
+      at = quoted.end + 1;
+      if (at < path.length && path[at] !== "." && !path.startsWith(ITEM_SELECTOR, at)) return null;
+      if (path[at] === ".") {
+        at += 1;
+        expectField = true;
+      }
+      continue;
+    }
+    let end = at;
+    while (end < path.length && path[end] !== "." && path[end] !== "[") end += 1;
+    const field = path.slice(at, end);
+    if (field.length === 0) return null;
+    segments.push({ field });
+    expectField = false;
+    at = end;
+    if (path[at] === ".") {
+      at += 1;
+      expectField = true;
+      if (at === path.length) return null;
+    } else if (at < path.length && !path.startsWith(ITEM_SELECTOR, at)) {
+      return null;
+    }
+  }
+  return segments.length === 0 || expectField ? null : segments;
+}
+__name(parseKeyPath, "parseKeyPath");
+function readQuoted(path, start) {
+  if (path[start] !== '"') return null;
+  for (let end = start + 1; end < path.length; end += 1) {
+    if (path[end] === "\\") {
+      end += 1;
+      continue;
+    }
+    if (path[end] !== '"') continue;
+    try {
+      const value = JSON.parse(path.slice(start, end + 1));
+      return typeof value === "string" && value.length > 0 ? { value, end: end + 1 } : null;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+__name(readQuoted, "readQuoted");
+
+// src/binding/relyio-field.ts
+var BINDING_VERSION = "1";
+function relyioField(subject, path) {
+  if (subject === void 0) return void 0;
+  if (isBindingShaped(subject)) return continued(subject, path);
+  const field = typeof path === "string" ? path : String(path);
+  const metadata = subject._metadata;
+  const attributes = {
+    "data-relyio-entry": requireMetadata(metadata, "id", field),
+    "data-relyio-type": requireMetadata(metadata, "type", field),
+    "data-relyio-field": field,
+    "data-relyio-locale": requireMetadata(metadata, "locale", field),
+    "data-relyio-v": BINDING_VERSION
+  };
+  requireKeyPath("entry", field, field);
+  return attributes;
+}
+__name(relyioField, "relyioField");
+function isBindingShaped(value) {
+  return "data-relyio-field" in value;
+}
+__name(isBindingShaped, "isBindingShaped");
+function continued(binding, path) {
+  const spelled = typeof path === "string" ? path : `{ _key: ${JSON.stringify(path._key)} }`;
+  const complete = binding["data-relyio-v"] === BINDING_VERSION && [
+    binding["data-relyio-entry"],
+    binding["data-relyio-type"],
+    binding["data-relyio-field"],
+    binding["data-relyio-locale"]
+  ].every((value) => typeof value === "string" && value.length > 0);
+  if (!complete) {
+    throw new TypeError(
+      `relyioField(binding, '${spelled}'): the binding is not one relyioField returned \u2014 continue the attributes relyioField(entry, field) gave, or a renderer handed you.`
+    );
+  }
+  const field = typeof path === "string" ? `${binding["data-relyio-field"]}.${path}` : formatKeyPath(binding["data-relyio-field"], path._key);
+  requireKeyPath("binding", spelled, field);
+  return {
+    "data-relyio-entry": binding["data-relyio-entry"],
+    "data-relyio-type": binding["data-relyio-type"],
+    "data-relyio-field": field,
+    "data-relyio-locale": binding["data-relyio-locale"],
+    "data-relyio-v": BINDING_VERSION
+  };
+}
+__name(continued, "continued");
+function requireKeyPath(form, given, field) {
+  if (parseKeyPath(field) !== null) return;
+  throw new TypeError(
+    `relyioField(${form}, '${given}'): '${field}' is not a field or a key path. Name a field (\`title\`), or a value inside one by its items\u2019 keys (\`sections[_key=="k1"].heading\`).`
+  );
+}
+__name(requireKeyPath, "requireKeyPath");
+function requireMetadata(metadata, key, field) {
+  const value = metadata?.[key];
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(
+      `relyioField(entry, '${field}'): the entry has no _metadata.${key}, so the field cannot be bound. Pass an entry as the RelyIO API returned it.`
+    );
+  }
+  return value;
+}
+__name(requireMetadata, "requireMetadata");
+
 // src/rich-text/render.ts
 var RICH_TEXT_VOID_TAGS = /* @__PURE__ */ new Set([
   "hr",
   "br",
   "input"
 ]);
+var BUILT_IN_NODES = {
+  paragraph: true,
+  heading: true,
+  quote: true,
+  list: true,
+  listItem: true,
+  codeBlock: true,
+  codeGroup: true,
+  table: true,
+  tableRow: true,
+  tableCell: true,
+  divider: true,
+  text: true,
+  lineBreak: true
+};
+function isDeclaredRichTextNode(node) {
+  if (typeof node !== "object" || node === null) return false;
+  const type = node._type;
+  return typeof type === "string" && type !== "" && !Object.prototype.hasOwnProperty.call(BUILT_IN_NODES, type);
+}
+__name(isDeclaredRichTextNode, "isDeclaredRichTextNode");
 var PLAIN = Object.freeze({ header: false });
 var HEADER = Object.freeze({ header: true });
-function renderRichText(value, target) {
-  if (value._type !== "richText") {
-    const drawn = block(value, target);
+var headingAnchors = /* @__PURE__ */ new Map();
+function renderRichText(value, target, options = {}) {
+  const held = value;
+  if (held._type !== "richText") {
+    const drawn = block(held, target);
     return drawn === void 0 ? [] : [drawn];
   }
-  return Array.isArray(value.children) ? blocks(value.children, target) : [];
+  const outer = headingAnchors;
+  headingAnchors = options.anchors ?? richTextHeadingAnchors(held);
+  try {
+    return Array.isArray(held.children) ? blocks(held.children, target) : [];
+  } finally {
+    headingAnchors = outer;
+  }
 }
 __name(renderRichText, "renderRichText");
 function blocks(nodes, target) {
@@ -36,6 +268,9 @@ var HEADING_TAGS = {
   6: "h6"
 };
 function block(node, target) {
+  if (isDeclaredRichTextNode(node)) {
+    return target.declared(node, "block");
+  }
   switch (node._type) {
     case "paragraph": {
       return target.node(
@@ -47,10 +282,16 @@ function block(node, target) {
     }
     case "heading": {
       const tag = HEADING_TAGS[node.level] ?? "p";
+      const anchor = headingAnchors.get(node);
       return target.node(
         node,
         inline(node.children, target),
-        (contents) => target.element(tag, void 0, contents, node._key),
+        (contents) => target.element(
+          tag,
+          anchor === void 0 ? void 0 : { id: anchor },
+          contents,
+          node._key
+        ),
         PLAIN
       );
     }
@@ -253,6 +494,12 @@ function inline(nodes, target) {
     runs = [];
   }, "flush");
   for (const node of nodes) {
+    if (isDeclaredRichTextNode(node)) {
+      flush();
+      const drawn = target.declared(node, "inline");
+      if (drawn !== void 0) out.push(drawn);
+      continue;
+    }
     switch (node._type) {
       case "text": {
         runs.push({ span: node, drawn: 0 });
@@ -301,9 +548,22 @@ function nextMark(run) {
 __name(nextMark, "nextMark");
 function sameMark(a, b) {
   if (a?._type !== b._type) return false;
-  return a._type !== "link" || b._type !== "link" || a.href === b.href;
+  if (a._type === "link" && b._type === "link") return a.href === b.href;
+  if (a._type === "entryLink" && b._type === "entryLink") {
+    return linkedEntryId(a) === linkedEntryId(b) && a.anchor === b.anchor;
+  }
+  return true;
 }
 __name(sameMark, "sameMark");
+function linkedEntryId(link) {
+  const to = link.to;
+  if (typeof to === "object" && to !== null && "_metadata" in to) {
+    const metadata = to._metadata;
+    return metadata?.id ?? to;
+  }
+  return to;
+}
+__name(linkedEntryId, "linkedEntryId");
 var MARK_TAGS = {
   bold: "strong",
   italic: "em",
@@ -316,6 +576,9 @@ var MARK_TAGS = {
 };
 function applyMark(mark, inner, target) {
   switch (mark._type) {
+    case "entryLink": {
+      return [target.entryLink(mark, inner)];
+    }
     case "link": {
       const href = safeRichTextHref(mark.href);
       if (href === void 0) return inner;
@@ -389,28 +652,168 @@ function attributesOf(attributes) {
   return written;
 }
 __name(attributesOf, "attributesOf");
-var HTML_TARGET = {
-  element(tag, attributes, children) {
-    return RICH_TEXT_VOID_TAGS.has(tag) ? `<${tag}${attributesOf(attributes)}/>` : `<${tag}${attributesOf(attributes)}>${children.join("")}</${tag}>`;
-  },
-  text: escapeHtml,
-  node: /* @__PURE__ */ __name((_node, contents, draw) => draw(contents), "node"),
-  mark: /* @__PURE__ */ __name((_mark, contents, draw) => draw(contents), "mark")
-};
-function richTextToHtml(value) {
+var VOID_ELEMENTS = /* @__PURE__ */ new Set([
+  "area",
+  "base",
+  "br",
+  "col",
+  "embed",
+  "hr",
+  "img",
+  "input",
+  "link",
+  "meta",
+  "source",
+  "track",
+  "wbr"
+]);
+var RAW_TEXT_ELEMENTS = /* @__PURE__ */ new Set(["script", "style", "textarea", "title"]);
+var BOUND = /\sdata-relyio-entry(?:[\s=/>]|$)/i;
+function tagEnd(html, start) {
+  let quote;
+  for (let index = start + 1; index < html.length; index++) {
+    const character = html[index];
+    if (quote !== void 0) {
+      if (character === quote) quote = void 0;
+    } else if (character === '"' || character === "'") {
+      quote = character;
+    } else if (character === ">") {
+      return index + 1;
+    }
+  }
+  return -1;
+}
+__name(tagEnd, "tagEnd");
+var TAG_NAME = /^<\/?([A-Za-z][\w:-]*)/;
+function soleElementStartTag(html) {
+  const from = html.length - html.trimStart().length;
+  const to = html.trimEnd().length;
+  const root = TAG_NAME.exec(html.slice(from));
+  if (root === null || html[from + 1] === "/") return void 0;
+  let depth = 0;
+  let index = from;
+  let startTag;
+  while (index < to) {
+    if (depth === 0 && startTag !== void 0) return void 0;
+    const open = html.indexOf("<", index);
+    if (open !== index) {
+      if (depth === 0) return void 0;
+      if (open === -1 || open >= to) return void 0;
+      index = open;
+      continue;
+    }
+    if (html.startsWith("<!--", index)) {
+      if (depth === 0) return void 0;
+      const close = html.indexOf("-->", index + 4);
+      if (close === -1) return void 0;
+      index = close + 3;
+      continue;
+    }
+    const name = TAG_NAME.exec(html.slice(index));
+    if (name === null) {
+      if (depth === 0) return void 0;
+      index += 1;
+      continue;
+    }
+    const end = tagEnd(html, index);
+    if (end === -1 || end > to) return void 0;
+    const tag = (name[1] ?? "").toLowerCase();
+    if (html[index + 1] === "/") {
+      depth -= 1;
+      if (depth < 0) return void 0;
+      index = end;
+      continue;
+    }
+    const selfClosing = html[end - 2] === "/";
+    if (startTag === void 0) {
+      let insertAt = selfClosing ? end - 2 : end - 1;
+      while (insertAt > index && /\s/.test(html[insertAt - 1] ?? "")) insertAt -= 1;
+      startTag = { insertAt, tag: html.slice(index, end) };
+    }
+    if (selfClosing || VOID_ELEMENTS.has(tag)) {
+      index = end;
+      continue;
+    }
+    if (RAW_TEXT_ELEMENTS.has(tag)) {
+      const close = html.toLowerCase().indexOf(`</${tag}`, end);
+      if (close === -1) return void 0;
+      depth += 1;
+      index = close;
+      continue;
+    }
+    depth += 1;
+    index = end;
+  }
+  return depth === 0 ? startTag : void 0;
+}
+__name(soleElementStartTag, "soleElementStartTag");
+function stamped(html, binding) {
+  if (binding === void 0) return html;
+  const root = soleElementStartTag(html);
+  if (root === void 0) return html;
+  if (BOUND.test(root.tag)) return html;
+  return `${html.slice(0, root.insertAt)}${attributesOf(binding)}${html.slice(root.insertAt)}`;
+}
+__name(stamped, "stamped");
+function htmlTarget(declared2, entryLink, field) {
+  return {
+    element(tag, attributes, children) {
+      return RICH_TEXT_VOID_TAGS.has(tag) ? `<${tag}${attributesOf(attributes)}/>` : `<${tag}${attributesOf(attributes)}>${children.join("")}</${tag}>`;
+    },
+    text: escapeHtml,
+    node: /* @__PURE__ */ __name((_node, contents, draw) => draw(contents), "node"),
+    mark: /* @__PURE__ */ __name((_mark, contents, draw) => draw(contents), "mark"),
+    // A value built by hand holding an entry link no writer draws: its text, with no anchor
+    entryLink: /* @__PURE__ */ __name((link, contents) => entryLink === void 0 ? contents.join("") : entryLink(link, contents.join("")), "entryLink"),
+    // A declared node's writer (REL-1807), handed the node's key path below the field's binding and
+    // stamped with it (REL-2142); no binding asks the core nothing
+    declared(node) {
+      const write = Object.prototype.hasOwnProperty.call(declared2, node._type) ? declared2[node._type] : void 0;
+      if (write === void 0) return void 0;
+      const binding = field === void 0 ? void 0 : relyioField(field, node);
+      return stamped(write(node, binding), binding);
+    }
+  };
+}
+__name(htmlTarget, "htmlTarget");
+function richTextToHtml(value, ...[options]) {
   if (value === void 0) return "";
-  return renderRichText(value, HTML_TARGET).join("");
+  const declared2 = options?.declared ?? {};
+  const entryLink = options?.entryLink;
+  return renderRichText(
+    value,
+    htmlTarget(declared2, entryLink, options?.field),
+    options?.anchors === void 0 ? {} : { anchors: options.anchors }
+  ).join("");
 }
 __name(richTextToHtml, "richTextToHtml");
 
 // src/rich-text/markdown.ts
-function richTextToMarkdown(value) {
+var entryLinkWriter;
+var writers = {};
+function declared(node) {
+  const type = node._type;
+  const write = Object.prototype.hasOwnProperty.call(writers, type) ? writers[type] : void 0;
+  return write === void 0 ? void 0 : write(node);
+}
+__name(declared, "declared");
+function richTextToMarkdown(value, ...[options]) {
   if (value === void 0) return "";
-  const held = value._type === "richText" ? value.children : [value];
+  const tree = value;
+  const held = tree._type === "richText" ? tree.children : [tree];
   if (!Array.isArray(held)) return "";
-  const written = blocks2(held);
-  return written.length === 0 ? "" : `${written.join("\n\n")}
+  const outer = writers;
+  const outerLink = entryLinkWriter;
+  writers = options?.declared ?? {};
+  entryLinkWriter = options?.entryLink;
+  try {
+    const written = blocks2(held);
+    return written.length === 0 ? "" : `${written.join("\n\n")}
 `;
+  } finally {
+    writers = outer;
+    entryLinkWriter = outerLink;
+  }
 }
 __name(richTextToMarkdown, "richTextToMarkdown");
 function blocks2(nodes) {
@@ -423,6 +826,7 @@ function blocks2(nodes) {
 }
 __name(blocks2, "blocks");
 function block2(node) {
+  if (isDeclaredRichTextNode(node)) return declared(node);
   switch (node._type) {
     case "paragraph": {
       return escapeLineStarts(inline2(node.children, "\\\n"));
@@ -566,6 +970,11 @@ function inline2(nodes, lineBreak) {
     runs = [];
   }, "flush");
   for (const node of nodes) {
+    if (isDeclaredRichTextNode(node)) {
+      flush();
+      out += declared(node) ?? "";
+      continue;
+    }
     switch (node._type) {
       case "text": {
         runs.push({ span: node, drawn: 0 });
@@ -616,6 +1025,9 @@ function marked2(runs) {
 __name(marked2, "marked");
 function applyMark2(mark, inner) {
   switch (mark._type) {
+    case "entryLink": {
+      return entryLinkWriter === void 0 || inner === "" ? inner : entryLinkWriter(mark, inner);
+    }
     case "link": {
       const href = safeRichTextHref(mark.href);
       if (href === void 0 || inner === "") return inner;
@@ -675,6 +1087,6 @@ function escapeLineStarts(paragraph) {
 }
 __name(escapeLineStarts, "escapeLineStarts");
 
-export { RICH_TEXT_VOID_TAGS, renderRichText, richTextToHtml, richTextToMarkdown, safeRichTextHref };
-//# sourceMappingURL=chunk-3DRDHXLY.js.map
-//# sourceMappingURL=chunk-3DRDHXLY.js.map
+export { RICH_TEXT_VOID_TAGS, entryHeadingAnchors, escapeHtml, formatKeyPath, isDeclaredRichTextNode, parseKeyPath, relyioField, renderRichText, richTextHeadingAnchors, richTextHeadingSlug, richTextToHtml, richTextToMarkdown, safeRichTextHref };
+//# sourceMappingURL=chunk-3NPPMGB6.js.map
+//# sourceMappingURL=chunk-3NPPMGB6.js.map