@seed-hypermedia/client 0.0.43 → 0.0.45

package/dist/blocks-to-markdown.d.ts

@@ -13,7 +13,8 @@
  * Round-trip compatible: output can be piped back through `parseMarkdown()`
  * to recreate the same document with block IDs preserved.
  */
-import type { HMDocument, HMMetadata } from './hm-types';
+import type { SeedClient } from './client';
+import type { HMBlockNode, HMComment, HMDocument, HMMetadata } from './hm-types';
 export type BlocksToMarkdownOptions = {
     /** Format ipfs:// URLs as https gateway URLs. Default: true. */
     ipfsGateway?: boolean;
@@ -58,3 +59,14 @@ export declare function parseDraftFilename(filename: string): {
     id: string;
     ext: string;
 };
+/** Options for Seed-client-backed markdown rendering that resolves embeds and mentions. */
+export type ResolvedMarkdownOptions = {
+    client: Pick<SeedClient, 'request'>;
+    maxDepth?: number;
+};
+/** Convert a document to markdown, resolving inline mentions and block embeds through a Seed client. */
+export declare function documentToResolvedMarkdown(doc: HMDocument, options: ResolvedMarkdownOptions): Promise<string>;
+/** Convert comment content to markdown, resolving inline mentions and block embeds through a Seed client. */
+export declare function commentToResolvedMarkdown(comment: HMComment, options: ResolvedMarkdownOptions): Promise<string>;
+/** Convert Seed block content to markdown, resolving inline mentions and block embeds through a Seed client. */
+export declare function contentToResolvedMarkdown(content: HMBlockNode[], options: ResolvedMarkdownOptions): Promise<string>;

package/dist/change.d.ts

@@ -29,12 +29,12 @@ export type DocumentOperation = {
 export type CreateChangeOpsInput = {
     /** Native CBOR ops */
     ops: DocumentOperation[];
-    /** CID of the genesis change blob */
-    genesisCid: CID;
-    /** CIDs of dependency changes */
-    deps: CID[];
-    /** Depth of the change (max depth of deps + 1) */
-    depth: number;
+    /** CID of the genesis change blob. Omit when creating the first content change for a document. */
+    genesisCid?: CID;
+    /** CIDs of dependency changes. Omit when creating the first content change for a document. */
+    deps?: CID[];
+    /** Depth of the change (max depth of deps + 1). Omit when creating the first content change for a document. */
+    depth?: number;
     /** Timestamp (defaults to Date.now()) */
     ts?: bigint;
 };
@@ -68,7 +68,7 @@ export declare const signPreparedChange: (unsignedBytes: Uint8Array, signer: HMS
 }>;
 /**
  * Create a signed genesis Change blob (empty, ts=0).
- * This is the bootstrap blob for a new document, matching the web pattern.
+ * This deterministic sentinel is only intended for home documents.
  */
 export declare function createGenesisChange(signer: HMSigner): Promise<{
     bytes: Uint8Array;

package/dist/index.d.ts

@@ -24,11 +24,14 @@ export { codePointLength, entityQueryPathToHmIdPath, getHMQueryString, hmIdPathT
 export type { HMRequest, HMSigner, UnpackedHypermediaId } from './hm-types';
 export { resolveHypermediaUrl, resolveId } from './hm-resolver';
 export type { DomainResolverFn, DomainIdChangedCallback, ResolveOptions, ResolvedUrl } from './hm-resolver';
+export { resolveIdWithClient } from './resource-read';
+export type { ResolveIdWithClientOptions, ResolvedIdWithClient } from './resource-read';
 export { fileToIpfsBlobs, filesToIpfsBlobs, resolveFileLinksInBlocks, hasFileLinks } from './file-to-ipfs';
 export type { CollectedBlob } from './file-to-ipfs';
 export { parseMarkdown, flattenToOperations, parseInlineFormatting, parseFrontmatter, markdownBlockNodesToHMBlockNodes, } from './markdown-to-blocks';
 export type { BlockNode, SeedBlock, Annotation } from './markdown-to-blocks';
-export { blocksToMarkdown, emitFrontmatter, slugify, draftFilename, parseDraftFilename } from './blocks-to-markdown';
+export { blocksToMarkdown, emitFrontmatter, slugify, draftFilename, parseDraftFilename, documentToResolvedMarkdown, commentToResolvedMarkdown, contentToResolvedMarkdown, } from './blocks-to-markdown';
+export type { ResolvedMarkdownOptions } from './blocks-to-markdown';
 export type { BlocksToMarkdownOptions } from './blocks-to-markdown';
 export { createBlocksMap, matchBlockIds, computeReplaceOps, hmBlockNodeToBlockNode } from './block-diff';
 export type { APIBlockNode, APIBlock } from './block-diff';

package/dist/index.mjs

@@ -209,11 +209,13 @@ function createChangeOps(input) {
     },
     signer: null,
     ts,
-    sig: null,
-    genesis: input.genesisCid,
-    deps: input.deps,
-    depth: input.depth
+    sig: null
   };
+  if (input.genesisCid) {
+    unsigned.genesis = input.genesisCid;
+    unsigned.deps = input.deps ?? [];
+    unsigned.depth = input.depth ?? 1;
+  }
   return { unsignedBytes: cborEncode4(unsigned), ts };
 }
 async function createChange(unsignedBytes, signer) {
@@ -2349,6 +2351,68 @@ function resolveProfilePath(siteUid, pathSegments) {
   };
 }
 
+// src/resource-read.ts
+async function resolveIdWithClient(rawId, options = {}) {
+  const commentId = extractCommentIdFromReadableUrl(rawId);
+  const parsed = commentId ? commentIdToHmId(commentId) : unpackHmId(rawId);
+  if (parsed) {
+    if (isWebUrl(rawId)) {
+      const origin2 = new URL(rawId).origin;
+      return { id: parsed, client: createSeedClient(origin2), serverUrl: origin2 };
+    }
+    const client = options.client ?? createSeedClient(normalizeServerUrl(options.serverUrl || "https://hyper.media"));
+    return { id: parsed, client, serverUrl: client.baseUrl };
+  }
+  const id = await resolveId(rawId, { domainResolver: options.domainResolver });
+  const origin = new URL(rawId).origin;
+  return { id, client: createSeedClient(origin), serverUrl: origin };
+}
+var COMMENT_VIEW_TERMS = /* @__PURE__ */ new Set([":comments", ":comment", ":discussions"]);
+function extractCommentIdFromReadableUrl(rawId) {
+  if (isWebUrl(rawId)) {
+    const url = new URL(rawId);
+    const panelCommentId = extractCommentIdFromPanel(url.searchParams.get("panel"));
+    if (panelCommentId) return panelCommentId;
+    return extractCommentIdFromPath(url.pathname.split("/").filter(Boolean));
+  }
+  const [withoutHash] = rawId.split("#");
+  const [withoutQuery] = withoutHash.split("?");
+  const parsed = unpackHmId(withoutQuery);
+  return (parsed == null ? void 0 : parsed.path) ? extractCommentIdFromPath(parsed.path) : null;
+}
+function extractCommentIdFromPanel(panel) {
+  if (!panel) return null;
+  const [viewTerm, first, second] = panel.split("/");
+  if (viewTerm !== "comments" && viewTerm !== "comment" && viewTerm !== "discussions") return null;
+  if (first && second) return `${first}/${second}`;
+  return first || null;
+}
+function extractCommentIdFromPath(pathParts) {
+  if (pathParts.length >= 3) {
+    const thirdToLast = pathParts[pathParts.length - 3];
+    if (thirdToLast && COMMENT_VIEW_TERMS.has(thirdToLast)) {
+      return `${pathParts[pathParts.length - 2]}/${pathParts[pathParts.length - 1]}`;
+    }
+  }
+  if (pathParts.length >= 2) {
+    const secondToLast = pathParts[pathParts.length - 2];
+    if (secondToLast && COMMENT_VIEW_TERMS.has(secondToLast)) return pathParts[pathParts.length - 1] || null;
+  }
+  return null;
+}
+function commentIdToHmId(commentId) {
+  const parsed = unpackHmId(`hm://${commentId}`);
+  if (!parsed) throw new Error(`Invalid comment ID: ${commentId}`);
+  return parsed;
+}
+function isWebUrl(rawId) {
+  return rawId.startsWith("http://") || rawId.startsWith("https://");
+}
+function normalizeServerUrl(serverUrl) {
+  const withScheme = serverUrl.startsWith("http://") || serverUrl.startsWith("https://") ? serverUrl : `https://${serverUrl}`;
+  return withScheme.replace(/\/+$/, "");
+}
+
 // src/file-to-ipfs.ts
 import { MemoryBlockstore } from "blockstore-core/memory";
 import { importer as unixFSImporter } from "ipfs-unixfs-importer";
@@ -3235,6 +3299,372 @@ function parseDraftFilename(filename) {
   }
   return { id: base, ext };
 }
+async function documentToResolvedMarkdown(doc, options) {
+  const ctx = {
+    client: options.client,
+    maxDepth: options.maxDepth ?? 2,
+    currentDepth: 0,
+    cache: /* @__PURE__ */ new Map()
+  };
+  return documentToResolvedMarkdownWithContext(doc, ctx);
+}
+async function commentToResolvedMarkdown(comment, options) {
+  return contentToResolvedMarkdown(comment.content || [], options);
+}
+async function contentToResolvedMarkdown(content, options) {
+  const ctx = {
+    client: options.client,
+    maxDepth: options.maxDepth ?? 2,
+    currentDepth: 0,
+    cache: /* @__PURE__ */ new Map()
+  };
+  return blockNodesToResolvedMarkdown(content, ctx);
+}
+async function documentToResolvedMarkdownWithContext(doc, ctx) {
+  const lines = [emitFrontmatter(doc.metadata || {})];
+  const body = await blockNodesToResolvedMarkdown(doc.content || [], ctx);
+  if (body) lines.push(body);
+  return lines.join("\n");
+}
+async function blockNodesToResolvedMarkdown(nodes, ctx) {
+  const lines = [];
+  for (const node of nodes) {
+    const blockMd = await resolvedBlockNodeToMarkdown(node, 0, ctx);
+    if (blockMd) lines.push(blockMd);
+  }
+  return lines.join("\n\n");
+}
+async function resolvedBlockNodeToMarkdown(node, depth, ctx) {
+  var _a;
+  const block = node.block;
+  const children = node.children || [];
+  const childrenType = (_a = block.attributes) == null ? void 0 : _a.childrenType;
+  const isListContainer = block.type === "Paragraph" && !block.text && (childrenType === "Ordered" || childrenType === "Unordered" || childrenType === "Blockquote");
+  let result = isListContainer ? resolvedIdComment(block.id) : await resolvedBlockToMarkdown(block, depth, ctx);
+  for (const child of children) {
+    const childMd = await resolvedBlockNodeToMarkdown(child, depth + 1, ctx);
+    if (!childMd) continue;
+    if (childrenType === "Ordered") result += "\n" + resolvedIndent(depth + 1) + "1. " + childMd.trim();
+    else if (childrenType === "Unordered") result += "\n" + resolvedIndent(depth + 1) + "- " + childMd.trim();
+    else if (childrenType === "Blockquote") result += "\n" + resolvedIndent(depth + 1) + "> " + childMd.trim();
+    else result += "\n\n" + childMd;
+  }
+  return result;
+}
+async function resolvedBlockToMarkdown(block, depth, ctx) {
+  var _a, _b;
+  const ind = resolvedIndent(depth);
+  const b = block;
+  const text = b.text || "";
+  const link = b.link || "";
+  const annotations = b.annotations;
+  const id = b.id;
+  switch (block.type) {
+    case "Paragraph":
+      return appendResolvedIdToFirstLine(ind + await applyResolvedAnnotations(text, annotations, ctx), id);
+    case "Heading": {
+      const hashes = "#".repeat(Math.min(depth + 1, 6));
+      return appendResolvedIdToFirstLine(`${hashes} ${await applyResolvedAnnotations(text, annotations, ctx)}`, id);
+    }
+    case "Code": {
+      const lang = ((_a = b.attributes) == null ? void 0 : _a.language) || "";
+      return ind + "```" + lang + " " + resolvedIdComment(id) + "\n" + ind + text + "\n" + ind + "```";
+    }
+    case "Math":
+      return ind + "$$ " + resolvedIdComment(id) + "\n" + ind + text + "\n" + ind + "$$";
+    case "Image":
+      return ind + `![${text || "image"}](${formatResolvedMediaUrl(link)}) ${resolvedIdComment(id)}`;
+    case "Video":
+      return ind + `[Video](${formatResolvedMediaUrl(link)}) ${resolvedIdComment(id)}`;
+    case "File": {
+      const fileName = ((_b = b.attributes) == null ? void 0 : _b.name) || "file";
+      return ind + `[${fileName}](${formatResolvedMediaUrl(link)}) ${resolvedIdComment(id)}`;
+    }
+    case "Embed":
+      return appendResolvedIdToFirstLine(await resolveBlockEmbed(block, depth, ctx), id);
+    case "WebEmbed":
+      return ind + `[Web Embed](${link}) ${resolvedIdComment(id)}`;
+    case "Button":
+      return ind + `[${text || "Button"}](${link}) ${resolvedIdComment(id)}`;
+    case "Query":
+      return appendResolvedIdToFirstLine(await resolveQuery(block, depth, ctx), id);
+    case "Nostr":
+      return ind + `[Nostr: ${link}](${link}) ${resolvedIdComment(id)}`;
+    default:
+      return text ? appendResolvedIdToFirstLine(ind + text, id) : "";
+  }
+}
+async function resolveBlockEmbed(block, depth, ctx) {
+  var _a;
+  const ind = resolvedIndent(depth);
+  const link = block.link || "";
+  if (ctx.currentDepth >= ctx.maxDepth) return ind + `> [Embed: ${link}](${link})`;
+  const id = unpackHmId(link);
+  if (!id) return ind + `> [Embed: ${link}](${link})`;
+  try {
+    const resolved = await resolveEmbeddedResource(link, ctx);
+    if (!((_a = resolved.content) == null ? void 0 : _a.length)) return ind + `> [Embed: ${resolved.label}](${link})`;
+    const content = selectEmbeddedContent(resolved.content, id);
+    if (!content.length) return ind + `> [Embed: ${resolved.label}](${link})`;
+    const lines = [];
+    const metadata = [`embed: ${link}`, `title: ${resolved.label}`];
+    if (id.version) metadata.push(`version: ${id.version}`);
+    if (id.blockRef) metadata.push(`block: ${id.blockRef}${formatBlockRange(id)}`);
+    lines.push(ind + `<!-- ${metadata.join("; ")} -->`);
+    const nestedCtx = { ...ctx, currentDepth: ctx.currentDepth + 1 };
+    for (const node of content) {
+      const blockMd = await resolvedBlockNodeToMarkdown(node, depth, nestedCtx);
+      if (!blockMd) continue;
+      lines.push(blockMd);
+    }
+    lines.push(ind + `<!-- /embed: ${link} -->`);
+    return lines.join("\n");
+  } catch {
+    return ind + `> [Embed: ${link}](${link})`;
+  }
+}
+async function resolveQuery(block, depth, ctx) {
+  var _a, _b;
+  const ind = resolvedIndent(depth);
+  try {
+    const attrs = block.attributes;
+    const queryConfig = attrs == null ? void 0 : attrs.query;
+    let includes;
+    let sort;
+    let limit;
+    if (queryConfig == null ? void 0 : queryConfig.includes) {
+      includes = queryConfig.includes.map((inc) => ({
+        space: inc.space,
+        path: inc.path,
+        mode: inc.mode || "Children"
+      }));
+      sort = (_a = queryConfig.sort) == null ? void 0 : _a.map((s) => ({ term: s.term, reverse: s.reverse ?? false }));
+      limit = queryConfig.limit;
+    } else {
+      const space = (attrs == null ? void 0 : attrs.space) || "";
+      if (!space) return ind + "<!-- Query: no space specified -->";
+      limit = typeof (attrs == null ? void 0 : attrs.limit) === "number" ? attrs.limit : void 0;
+      includes = [
+        {
+          space,
+          path: attrs == null ? void 0 : attrs.path,
+          mode: (attrs == null ? void 0 : attrs.mode) || "Children"
+        }
+      ];
+    }
+    const results = await ctx.client.request("Query", {
+      includes,
+      sort: sort || [{ term: "UpdateTime", reverse: true }],
+      limit: limit || 10
+    });
+    if (!((_b = results == null ? void 0 : results.results) == null ? void 0 : _b.length)) return ind + "<!-- Query: no results -->";
+    return results.results.map((doc) => {
+      var _a2, _b2;
+      const name = ((_a2 = doc.metadata) == null ? void 0 : _a2.name) || ((_b2 = doc.id.path) == null ? void 0 : _b2.join("/")) || doc.id.uid;
+      return ind + `- [${name}](${doc.id.id})`;
+    }).join("\n");
+  } catch (error) {
+    return ind + `<!-- Query error: ${error instanceof Error ? error.message : String(error)} -->`;
+  }
+}
+function selectEmbeddedContent(content, id) {
+  if (!id.blockRef) return content;
+  const target = findBlockById(content, id.blockRef);
+  if (!target) return [];
+  if (id.blockRange && "start" in id.blockRange && typeof id.blockRange.start === "number") {
+    return [sliceBlockText(target, id.blockRange.start, id.blockRange.end ?? id.blockRange.start)];
+  }
+  if (id.blockRange && "expanded" in id.blockRange && !id.blockRange.expanded) return [{ ...target, children: [] }];
+  return [target];
+}
+function sliceBlockText(node, start, end) {
+  const block = node.block;
+  if (typeof block.text !== "string") return { ...node, children: [] };
+  return { ...node, block: { ...block, text: block.text.slice(start, end) }, children: [] };
+}
+async function applyResolvedAnnotations(text, annotations, ctx) {
+  if (!(annotations == null ? void 0 : annotations.length)) return text;
+  const markers = [];
+  for (const ann of annotations) {
+    const starts = ann.starts || [];
+    const ends = ann.ends || [];
+    for (let i = 0; i < starts.length; i++) {
+      markers.push({ pos: starts[i], type: "open", annotation: ann });
+      if (ends[i] !== void 0) markers.push({ pos: ends[i], type: "close", annotation: ann });
+    }
+  }
+  markers.sort((a, b) => a.pos !== b.pos ? a.pos - b.pos : a.type === "open" ? -1 : 1);
+  let result = "";
+  let lastPos = 0;
+  for (const marker of markers) {
+    result += text.slice(lastPos, marker.pos);
+    lastPos = marker.pos;
+    result += await getResolvedAnnotationMarker(marker.annotation, marker.type, ctx);
+  }
+  result += text.slice(lastPos);
+  return result.replace(/\uFFFC/g, "");
+}
+async function getResolvedAnnotationMarker(ann, type, ctx) {
+  switch (ann.type) {
+    case "Bold":
+      return "**";
+    case "Italic":
+      return "_";
+    case "Strike":
+      return "~~";
+    case "Code":
+      return "`";
+    case "Underline":
+      return type === "open" ? "<u>" : "</u>";
+    case "Link":
+      return type === "open" ? "[" : `](${ann.link || ""})`;
+    case "Embed":
+      return resolveInlineEmbed(ann, type, ctx);
+    default:
+      return "";
+  }
+}
+async function resolveInlineEmbed(ann, type, ctx) {
+  const link = "link" in ann ? ann.link || "" : "";
+  if (type === "close") return `](${link})`;
+  if (!link) return "[\u2197 embed";
+  try {
+    const resolved = await resolveReference(link, ctx);
+    const prefix = resolved.type === "account" ? "@" : "";
+    return `[${prefix}${resolved.label}`;
+  } catch {
+    return `[\u2197 ${fallbackLabel(link)}`;
+  }
+}
+async function resolveEmbeddedResource(link, ctx) {
+  var _a, _b;
+  const cacheKey = `embed:${link}`;
+  const cached = ctx.cache.get(cacheKey);
+  if (cached) return cached;
+  const id = unpackHmId(link);
+  if (!id) throw new Error("Invalid HM link");
+  const resource = await ctx.client.request("Resource", id);
+  let resolved;
+  if (resource.type === "document") {
+    resolved = {
+      label: ((_a = resource.document.metadata) == null ? void 0 : _a.name) || fallbackDocLabel(id),
+      type: "document",
+      content: resource.document.content || [],
+      version: id.version || resource.document.version,
+      latestVersion: resource.document.version
+    };
+  } else if (resource.type === "comment") {
+    let authorName = fallbackUid(resource.comment.author);
+    try {
+      const account = await ctx.client.request("Account", resource.comment.author);
+      if (account.type === "account" && ((_b = account.metadata) == null ? void 0 : _b.name)) authorName = account.metadata.name;
+    } catch {
+    }
+    resolved = {
+      label: `Comment by ${authorName}`,
+      type: "comment",
+      content: resource.comment.content || [],
+      version: id.version || resource.comment.version,
+      latestVersion: resource.comment.version,
+      author: resource.comment.author
+    };
+  } else {
+    resolved = { label: fallbackLabel(link), type: "unknown" };
+  }
+  ctx.cache.set(cacheKey, resolved);
+  return resolved;
+}
+async function resolveReference(link, ctx) {
+  var _a, _b, _c, _d, _e;
+  const cached = ctx.cache.get(link);
+  if (cached) return cached;
+  const id = unpackHmId(link);
+  if (!id) throw new Error("Invalid HM link");
+  let resolved;
+  const profileAccountUid = ((_a = id.path) == null ? void 0 : _a[0]) === ":profile" ? id.path[1] || id.uid : !((_b = id.path) == null ? void 0 : _b.length) ? id.uid : null;
+  if (profileAccountUid) {
+    try {
+      const account = await ctx.client.request("Account", profileAccountUid);
+      if (account.type === "account") {
+        resolved = { label: ((_c = account.metadata) == null ? void 0 : _c.name) || fallbackUid(profileAccountUid), type: "account" };
+        ctx.cache.set(link, resolved);
+        return resolved;
+      }
+    } catch {
+    }
+  }
+  const resource = await ctx.client.request("Resource", id);
+  if (resource.type === "document") {
+    resolved = {
+      label: ((_d = resource.document.metadata) == null ? void 0 : _d.name) || fallbackDocLabel(id),
+      type: "document",
+      content: resource.document.content || [],
+      version: id.version || resource.document.version,
+      latestVersion: resource.document.version
+    };
+  } else if (resource.type === "comment") {
+    let authorName = fallbackUid(resource.comment.author);
+    try {
+      const account = await ctx.client.request("Account", resource.comment.author);
+      if (account.type === "account" && ((_e = account.metadata) == null ? void 0 : _e.name)) authorName = account.metadata.name;
+    } catch {
+    }
+    resolved = {
+      label: `Comment by ${authorName}`,
+      type: "comment",
+      content: resource.comment.content || [],
+      version: id.version || resource.comment.version,
+      latestVersion: resource.comment.version,
+      author: resource.comment.author
+    };
+  } else {
+    resolved = { label: fallbackLabel(link), type: "unknown" };
+  }
+  ctx.cache.set(link, resolved);
+  return resolved;
+}
+function findBlockById(content, blockId) {
+  for (const node of content) {
+    if (node.block.id === blockId) return node;
+    const found = findBlockById(node.children || [], blockId);
+    if (found) return found;
+  }
+  return null;
+}
+function resolvedIdComment(id) {
+  return `<!-- id:${id} -->`;
+}
+function appendResolvedIdToFirstLine(md, id) {
+  const newline = md.indexOf("\n");
+  if (newline === -1) return md ? `${md} ${resolvedIdComment(id)}` : resolvedIdComment(id);
+  return `${md.slice(0, newline)} ${resolvedIdComment(id)}${md.slice(newline)}`;
+}
+function formatResolvedMediaUrl(url) {
+  if (url.startsWith("ipfs://")) return `https://ipfs.io/ipfs/${url.slice(7)}`;
+  return url;
+}
+function formatBlockRange(id) {
+  const range = id.blockRange;
+  if (!range) return "";
+  if ("expanded" in range && range.expanded) return "+";
+  if ("start" in range) return `[${range.start}:${range.end}]`;
+  return "";
+}
+function fallbackDocLabel(id) {
+  var _a;
+  return ((_a = id.path) == null ? void 0 : _a.length) ? id.path.join("/") : fallbackUid(id.uid);
+}
+function fallbackLabel(link) {
+  const id = unpackHmId(link);
+  if (id) return fallbackDocLabel(id);
+  return link;
+}
+function fallbackUid(uid) {
+  return uid.length > 12 ? `${uid.slice(0, 12)}...` : uid;
+}
+function resolvedIndent(depth) {
+  return "  ".repeat(depth);
+}
 
 // src/block-diff.ts
 function createBlocksMap(nodes, parentId = "") {
@@ -4445,8 +4875,10 @@ export {
   blocksToMarkdown,
   codePointLength,
   commentRecordIdFromBlob,
+  commentToResolvedMarkdown,
   computeReplaceOps,
   contactRecordIdFromBlob,
+  contentToResolvedMarkdown,
   createAutoLinkOps,
   createBlocksMap,
   createCapability,
@@ -4465,6 +4897,7 @@ export {
   deleteContact,
   documentContainsLinkToChild,
   documentHasSelfQuery,
+  documentToResolvedMarkdown,
   draftFilename,
   editorBlockToHMBlock,
   editorBlocksToHMBlockNodes,
@@ -4502,6 +4935,7 @@ export {
   resolveFileLinksInBlocks,
   resolveHypermediaUrl,
   resolveId,
+  resolveIdWithClient,
   serializeBlockRange,
   shouldAutoLinkParent,
   signDocumentChange,

package/dist/resource-read.d.ts

@@ -0,0 +1,23 @@
+import { type SeedClient } from './client';
+import { type DomainResolverFn } from './hm-resolver';
+import { type UnpackedHypermediaId } from './hm-types';
+/** Options for resolving a user-supplied hypermedia ID or web URL. */
+export type ResolveIdWithClientOptions = {
+    client?: SeedClient;
+    serverUrl?: string;
+    domainResolver?: DomainResolverFn;
+};
+/** Resolved hypermedia ID with the Seed client that should be used to read it. */
+export type ResolvedIdWithClient = {
+    id: UnpackedHypermediaId;
+    client: SeedClient;
+    serverUrl: string;
+};
+/**
+ * Resolves an hm:// ID, gateway URL, or Seed site URL and returns the matching Seed client.
+ *
+ * This is the shared implementation used by CLI-like document readers:
+ * - hm:// IDs use the caller's configured client/server.
+ * - web URLs resolve through the documented OPTIONS/header flow and then read from that URL's origin.
+ */
+export declare function resolveIdWithClient(rawId: string, options?: ResolveIdWithClientOptions): Promise<ResolvedIdWithClient>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seed-hypermedia/client",
-  "version": "0.0.43",
+  "version": "0.0.45",
   "repository": {
     "type": "git",
     "url": "https://github.com/seed-hypermedia/seed",

package/src/index.ts

@@ -59,6 +59,8 @@ export type {HMRequest, HMSigner, UnpackedHypermediaId} from './hm-types'
 
 export {resolveHypermediaUrl, resolveId} from './hm-resolver'
 export type {DomainResolverFn, DomainIdChangedCallback, ResolveOptions, ResolvedUrl} from './hm-resolver'
+export {resolveIdWithClient} from './resource-read'
+export type {ResolveIdWithClientOptions, ResolvedIdWithClient} from './resource-read'
 
 export {fileToIpfsBlobs, filesToIpfsBlobs, resolveFileLinksInBlocks, hasFileLinks} from './file-to-ipfs'
 export type {CollectedBlob} from './file-to-ipfs'
@@ -71,7 +73,17 @@ export {
   markdownBlockNodesToHMBlockNodes,
 } from './markdown-to-blocks'
 export type {BlockNode, SeedBlock, Annotation} from './markdown-to-blocks'
-export {blocksToMarkdown, emitFrontmatter, slugify, draftFilename, parseDraftFilename} from './blocks-to-markdown'
+export {
+  blocksToMarkdown,
+  emitFrontmatter,
+  slugify,
+  draftFilename,
+  parseDraftFilename,
+  documentToResolvedMarkdown,
+  commentToResolvedMarkdown,
+  contentToResolvedMarkdown,
+} from './blocks-to-markdown'
+export type {ResolvedMarkdownOptions} from './blocks-to-markdown'
 export type {BlocksToMarkdownOptions} from './blocks-to-markdown'
 
 export {createBlocksMap, matchBlockIds, computeReplaceOps, hmBlockNodeToBlockNode} from './block-diff'