@hraness/wordcell 0.22.3 → 0.22.4

package/README.md

@@ -42,14 +42,14 @@ Git evidence, and selective publishing. [Compare the tradeoffs](https://github.c
 The CLI and TypeScript SDK run with Bun. Install the versioned GitHub archive:
 
 ```sh
-bun add --global --ignore-scripts https://github.com/hraness/wordcell/releases/download/v0.22.3/hraness-wordcell-0.22.3.tgz
+bun add --global --ignore-scripts https://github.com/hraness/wordcell/releases/download/v0.22.4/hraness-wordcell-0.22.4.tgz
 wordcell --help
 ```
 
 Prefer npm? The same release is [mirrored there](https://www.npmjs.com/package/@hraness/wordcell):
 
 ```sh
-npm install --global --ignore-scripts @hraness/wordcell@0.22.3
+npm install --global --ignore-scripts @hraness/wordcell@0.22.4
 wordcell --help
 ```
 
@@ -91,7 +91,7 @@ After trying the CLI, install the public Agent Skill into a compatible agent,
 such as Claude Code, Codex, Cursor, or GitHub Copilot:
 
 ```sh
-bunx skills add hraness/wordcell#v0.22.3 --skill wordcell
+bunx skills add hraness/wordcell#v0.22.4 --skill wordcell
 ```
 
 Then ask:
@@ -283,7 +283,7 @@ exist. [Graph queries and proof limits](https://github.com/hraness/wordcell/blob
 Add the same immutable release to a Bun project:
 
 ```sh
-bun add --exact --ignore-scripts https://github.com/hraness/wordcell/releases/download/v0.22.3/hraness-wordcell-0.22.3.tgz
+bun add --exact --ignore-scripts https://github.com/hraness/wordcell/releases/download/v0.22.4/hraness-wordcell-0.22.4.tgz
 ```
 
 The SDK provides read-only vault sessions, metadata queries, search, graph

package/dist/cli.js

@@ -5,7 +5,7 @@ import {
   parseArguments,
   runExecutable,
   usage
-} from "./index-yx6p1vzc.js";
+} from "./index-9h7zh0wt.js";
 import"./index-bcknqxrq.js";
 import"./index-054mb7d3.js";
 import"./index-bqtqeak3.js";
@@ -41,14 +41,14 @@ import"./index-tf4wzjew.js";
 import"./index-1gwbassd.js";
 import"./index-vnybgywh.js";
 import"./index-1xxnjn0d.js";
-import"./index-a3j61wz9.js";
+import"./index-pnt9wr59.js";
 import"./index-233z9wmn.js";
 import"./index-d13v9ckt.js";
 import"./index-48pz4jpc.js";
 import"./index-06c9ctr6.js";
 import"./index-4knsp9qj.js";
 import"./index-66pshdtx.js";
-import"./index-3agn8scn.js";
+import"./index-23m6bbjt.js";
 import"./index-hya40gb2.js";
 import"./index-5vwpzb5a.js";
 import"./index-x3fthpsc.js";
@@ -61,7 +61,7 @@ import {
 
 // src/cli.ts
 if (import.meta.main) {
-  const { standaloneSupportEnvironment, isUsefulSupportResult, runProductSupportCommand, showProductSupportInvitation } = await import("./support-vm8fw4yc.js");
+  const { standaloneSupportEnvironment, isUsefulSupportResult, runProductSupportCommand, showProductSupportInvitation } = await import("./support-m3t917ev.js");
   const env = standaloneSupportEnvironment();
   const args = process.argv.slice(2);
   if (args[0] === "support") {

package/dist/{index-3agn8scn.js → index-23m6bbjt.js}

@@ -285,22 +285,58 @@ function comparePublishScores(left, right) {
   return Number(right.identity) - Number(left.identity) || right.score - left.score || left.i - right.i;
 }
 function publishSnippet(text, query, fallback, windowBytes = 160) {
-  const normalized = publishNormalize(text);
-  let offset = query.normalized === "" ? -1 : normalized.indexOf(query.normalized);
-  if (offset < 0) {
+  if (!Number.isSafeInteger(windowBytes) || windowBytes < 0)
+    throw new RangeError("Snippet window must be a nonnegative safe byte count.");
+  const display = text.normalize("NFC");
+  const normalized = publishNormalize(display);
+  let match = query.normalized === "" ? -1 : normalized.indexOf(query.normalized);
+  if (match < 0) {
     for (const term of query.terms) {
-      offset = normalized.indexOf(term);
-      if (offset >= 0)
+      match = normalized.indexOf(term);
+      if (match >= 0)
         break;
     }
   }
-  if (offset < 0)
+  if (match < 0)
     return fallback;
-  const half = Math.floor(windowBytes / 2);
-  const start = Math.max(0, offset - half);
-  const end = Math.min(text.length, offset + half);
-  const snippet = text.slice(start, end).replace(/\s+/gu, " ").trim();
-  return `${start > 0 ? "\u2026" : ""}${snippet}${end < text.length ? "\u2026" : ""}`;
+  let offset = 0, normalizedOffset = 0;
+  for (const character of display) {
+    const width = character.toLocaleLowerCase("en-US").length;
+    if (normalizedOffset + width > match)
+      break;
+    normalizedOffset += width;
+    offset += character.length;
+  }
+  const edge = windowBytes >= 6 ? "\u2026" : "";
+  const budget = windowBytes - 2 * publishUtf8Bytes(edge);
+  const previous = (end2) => {
+    const last = display.charCodeAt(end2 - 1);
+    return end2 > 1 && last >= 56320 && last <= 57343 && display.charCodeAt(end2 - 2) >= 55296 && display.charCodeAt(end2 - 2) <= 56319 ? end2 - 2 : end2 - 1;
+  };
+  let start = offset, end = offset, used = 0;
+  while (start > 0) {
+    const before = previous(start), bytes = publishUtf8Bytes(display.slice(before, start));
+    if (used + bytes > Math.floor(budget / 2))
+      break;
+    start = before;
+    used += bytes;
+  }
+  while (end < display.length) {
+    const character = String.fromCodePoint(display.codePointAt(end) ?? 0), bytes = publishUtf8Bytes(character);
+    if (used + bytes > budget)
+      break;
+    end += character.length;
+    used += bytes;
+  }
+  while (start > 0) {
+    const before = previous(start), bytes = publishUtf8Bytes(display.slice(before, start));
+    if (used + bytes > budget)
+      break;
+    start = before;
+    used += bytes;
+  }
+  const snippet = display.slice(start, end).replace(/\s+/gu, " ").trim();
+  return `${start > 0 ? edge : ""}${snippet}${end < display.length ? edge : ""}`;
 }
 
 export { PUBLISH_FIELD_TITLE, PUBLISH_FIELD_ALIAS, PUBLISH_FIELD_PATH, PUBLISH_FIELD_TAG, PUBLISH_FIELD_METADATA, PUBLISH_FIELD_CONTENT, PUBLISH_SEARCH_WEIGHTS_V1, MAX_PUBLISH_QUERY_BYTES, MAX_PUBLISH_QUERY_TERMS, MAX_PUBLISH_PREFIX_EXPANSIONS, publishUtf8Bytes, publishNormalize, MAX_PUBLISH_QUERY_FILTERS, publishQueryParts, publishDocMatchesFilters, MAX_PUBLISH_MARK_RANGES, publishMarkRanges, publishQuery, publishShardName, publishPrefixTerms, scorePublishDocument, comparePublishScores, publishSnippet };

package/dist/{index-yx6p1vzc.js → index-9h7zh0wt.js}

@@ -100,7 +100,7 @@ import {
   MAX_PUBLISH_LIST_LIMIT,
   publishVault,
   renderPublishReportText
-} from "./index-a3j61wz9.js";
+} from "./index-pnt9wr59.js";
 import {
   refreshVault,
   scanVault

package/dist/{index-a3j61wz9.js → index-pnt9wr59.js}

@@ -31,7 +31,7 @@ import {
 import {
   publishNormalize,
   publishShardName
-} from "./index-3agn8scn.js";
+} from "./index-23m6bbjt.js";
 import {
   parseLocalAttachmentReferences,
   validateMarkdownAttachments
@@ -49,133 +49,6 @@ import { canonicalJson as canonicalJson2, canonicalSha256 } from "@hraness/oh";
 
 // src/publish-index.ts
 import { canonicalJson } from "@hraness/oh";
-var TERM_PATTERN = /[\p{L}\p{N}][\p{L}\p{N}._/-]*/gu;
-function bounded(value, maximumBytes) {
-  if (Buffer.byteLength(value, "utf8") <= maximumBytes)
-    return { text: value, truncated: false };
-  const bytes = Buffer.from(value, "utf8");
-  let end = maximumBytes;
-  while (end > 0 && ((bytes[end] ?? 0) & 192) === 128)
-    end -= 1;
-  return { text: bytes.subarray(0, end).toString("utf8"), truncated: true };
-}
-function previewText(note) {
-  const basis = note.summary !== "" ? note.summary : note.searchableText;
-  const collapsed = basis.replace(/\s+/gu, " ").trim();
-  return bounded(collapsed, WORDCELL_SITE_LIMITS_V1.docPreviewBytes).text;
-}
-function indexableTerms(text) {
-  const terms = new Set;
-  for (const match of text.matchAll(TERM_PATTERN))
-    terms.add(match[0]);
-  return [...terms];
-}
-function buildSiteIndex(notes, slugById, options = {}) {
-  const indexContent = options.indexContent !== false;
-  const fields = [];
-  const inlineTexts = [];
-  let textTruncated = false;
-  let inlineTotal = 0;
-  for (const note of notes) {
-    const title = bounded(publishNormalize(note.title), WORDCELL_SITE_LIMITS_V1.fieldTextBytes);
-    const aliases = bounded(note.aliases.map(publishNormalize).join(`
-`), WORDCELL_SITE_LIMITS_V1.fieldTextBytes);
-    const path = bounded(`${publishNormalize(note.path)}
-${publishNormalize(note.id)}`, WORDCELL_SITE_LIMITS_V1.fieldTextBytes);
-    const tags = bounded(note.tags.map(publishNormalize).join(`
-`), WORDCELL_SITE_LIMITS_V1.fieldTextBytes);
-    const metadata = bounded(publishNormalize(canonicalJson(note.metadata)), WORDCELL_SITE_LIMITS_V1.fieldTextBytes);
-    textTruncated ||= title.truncated || aliases.truncated || path.truncated || tags.truncated || metadata.truncated;
-    fields.push({ t: title.text, a: aliases.text, p: path.text, g: tags.text, m: metadata.text });
-    if (indexContent) {
-      const inline = bounded(publishNormalize(note.searchableText), WORDCELL_SITE_LIMITS_V1.inlineTextBytes);
-      textTruncated ||= inline.truncated;
-      inlineTexts.push(inline.text);
-      inlineTotal += Buffer.byteLength(inline.text, "utf8");
-    }
-  }
-  const mode = !indexContent ? "none" : inlineTotal <= WORDCELL_SITE_LIMITS_V1.inlineTotalBytes ? "inline" : "shards";
-  const allTerms = new Set;
-  const contentPostings = new Map;
-  const docs = [];
-  for (const [index, note] of notes.entries()) {
-    const slug = slugById.get(note.id);
-    if (slug === undefined)
-      throw new Error(`Missing published slug for ${note.id}.`);
-    const field = fields[index];
-    if (field === undefined)
-      throw new Error(`Missing indexed fields for ${note.id}.`);
-    const inline = mode === "inline" ? inlineTexts[index] : undefined;
-    const fieldTerms = indexableTerms(`${field.t}
-${field.a}
-${field.p}
-${field.g}
-${field.m}`);
-    for (const term of fieldTerms)
-      allTerms.add(term);
-    if (mode !== "none") {
-      const content = inlineTexts[index] ?? "";
-      for (const term of indexableTerms(content)) {
-        allTerms.add(term);
-        if (mode === "shards") {
-          const list = contentPostings.get(term) ?? [];
-          list.push(index);
-          contentPostings.set(term, list);
-        }
-      }
-    }
-    docs.push({
-      i: index,
-      s: slug,
-      t: note.title,
-      p: previewText(note),
-      f: field,
-      ...inline === undefined ? {} : { x: inline }
-    });
-  }
-  let termsTruncated = false;
-  let sortedTerms = [...allTerms].toSorted((left, right) => left.localeCompare(right));
-  if (sortedTerms.length > WORDCELL_SITE_LIMITS_V1.indexTerms) {
-    sortedTerms = sortedTerms.slice(0, WORDCELL_SITE_LIMITS_V1.indexTerms);
-    termsTruncated = true;
-  }
-  const admitted = new Set(sortedTerms);
-  const postings = new Map;
-  if (mode === "shards") {
-    const grouped = new Map;
-    for (const [term, docIds] of [...contentPostings.entries()].toSorted(([a], [b]) => a.localeCompare(b))) {
-      if (!admitted.has(term))
-        continue;
-      const shard = publishShardName(term);
-      const bucket = grouped.get(shard) ?? Object.create(null);
-      bucket[term] = docIds;
-      grouped.set(shard, bucket);
-    }
-    for (const [shard, bucket] of [...grouped.entries()].toSorted(([a], [b]) => a.localeCompare(b))) {
-      postings.set(shard, {
-        format: WORDCELL_SITE_POSTINGS_FORMAT_V1,
-        shard,
-        postings: Object.freeze(bucket)
-      });
-    }
-  }
-  return {
-    docs: {
-      format: WORDCELL_SITE_DOCS_FORMAT_V1,
-      content: mode,
-      docs
-    },
-    terms: {
-      format: WORDCELL_SITE_TERMS_FORMAT_V1,
-      terms: sortedTerms
-    },
-    postings,
-    termsCount: sortedTerms.length,
-    termsTruncated,
-    textTruncated,
-    mode
-  };
-}
 
 // src/publish-markdown.ts
 var VOID_SLUG = /[^\p{L}\p{N}._~-]+/gu;
@@ -257,6 +130,8 @@ function renderFootnoteReference(raw, label, footnotes) {
   const id = `wordcell:footnote-ref:${number}:${note.references.length + 1}`;
   note.references.push(id);
   footnotes.references += 1;
+  if (footnotes.plain)
+    return "";
   return `<sup><a id="${id}" href="#wordcell:footnote:${number}" role="doc-noteref" aria-label="Footnote ${number}">${number}</a></sup>`;
 }
 function renderInline(text, ctx, footnotes) {
@@ -904,6 +779,72 @@ function renderMarkdownToHtml(content, ctx) {
 ${notes}
 </ol></section>`;
 }
+function projectMarkdownText(content, description) {
+  const footnotes = { byLabel: new Map, numbered: [], definitions: 0, references: 0, disabled: false, plain: true };
+  const blocks = parseMarkdownBlocks(content, footnotes, true);
+  const context = {
+    source: "",
+    resolveNote: () => {
+      return;
+    },
+    resolveAsset: () => {
+      return;
+    },
+    noteHref: () => ""
+  };
+  const inline = (text2, state) => stripMarkup(renderInline(text2, context, state));
+  const parts = (items, state) => items.map((block) => {
+    switch (block.type) {
+      case "paragraph":
+      case "heading":
+        return inline(block.text, state);
+      case "literal":
+      case "code":
+        return block.text;
+      case "break":
+        return "";
+      case "quote":
+        return parts(block.blocks, state).join(`
+
+`);
+      case "table":
+        return [block.header, ...block.rows].map((row) => row.map((cell) => inline(cell, state)).join(" ")).join(`
+`);
+      case "list":
+        return block.parts.map((part) => part.type === "item" || part.type === "continuation" ? inline(part.text, state) : "").filter(Boolean).join(`
+`);
+      case "footnote":
+        return state.disabled || block.note.invalid ? block.note.authored : "";
+    }
+  });
+  const rendered = parts(blocks, footnotes);
+  if (!footnotes.disabled)
+    for (const note of footnotes.byLabel.values()) {
+      if (note !== null && !note.invalid)
+        footnoteNumber(note, footnotes);
+    }
+  const text = [...rendered, ...footnotes.numbered.map((note) => inline(note.body.replaceAll(`
+`, " ")))].filter(Boolean).join(`
+
+`);
+  let preview = rendered.find((value, index) => blocks[index]?.type === "paragraph" && value.trim() !== "") ?? text;
+  if (description !== undefined && description.trim() !== "") {
+    const state = {
+      byLabel: new Map([...footnotes.byLabel].map(([label, note]) => [label, note === null ? null : { body: note.body, authored: note.authored, invalid: note.invalid, references: [] }])),
+      numbered: [],
+      definitions: footnotes.definitions,
+      references: 0,
+      disabled: footnotes.disabled,
+      plain: true
+    };
+    const authored = parts(parseMarkdownBlocks(description, state, false), state).filter(Boolean).join(`
+
+`);
+    if (authored.trim() !== "")
+      preview = authored;
+  }
+  return { text, preview };
+}
 function stripMarkup(html) {
   let stripped = "";
   let inTag = false;
@@ -918,6 +859,135 @@ function stripMarkup(html) {
   return stripped.replaceAll("&lt;", "<").replaceAll("&gt;", ">").replaceAll("&quot;", '"').replaceAll("&#39;", "'").replaceAll("&amp;", "&");
 }
 
+// src/publish-index.ts
+var TERM_PATTERN = /[\p{L}\p{N}][\p{L}\p{N}._/-]*/gu;
+function bounded(value, maximumBytes) {
+  if (Buffer.byteLength(value, "utf8") <= maximumBytes)
+    return { text: value, truncated: false };
+  const bytes = Buffer.from(value, "utf8");
+  let end = maximumBytes;
+  while (end > 0 && ((bytes[end] ?? 0) & 192) === 128)
+    end -= 1;
+  return { text: bytes.subarray(0, end).toString("utf8"), truncated: true };
+}
+function previewText(note) {
+  const display = projectMarkdownText(note.content, note.properties["description"]);
+  const collapsed = display.preview.replace(/\s+/gu, " ").trim();
+  return bounded(collapsed, WORDCELL_SITE_LIMITS_V1.docPreviewBytes).text;
+}
+function indexableTerms(text) {
+  const terms = new Set;
+  for (const match of text.matchAll(TERM_PATTERN))
+    terms.add(match[0]);
+  return [...terms];
+}
+function buildSiteIndex(notes, slugById, options = {}) {
+  const indexContent = options.indexContent !== false;
+  const fields = [];
+  const inlineTexts = [];
+  let textTruncated = false;
+  let inlineTotal = 0;
+  for (const note of notes) {
+    const title = bounded(publishNormalize(note.title), WORDCELL_SITE_LIMITS_V1.fieldTextBytes);
+    const aliases = bounded(note.aliases.map(publishNormalize).join(`
+`), WORDCELL_SITE_LIMITS_V1.fieldTextBytes);
+    const path = bounded(`${publishNormalize(note.path)}
+${publishNormalize(note.id)}`, WORDCELL_SITE_LIMITS_V1.fieldTextBytes);
+    const tags = bounded(note.tags.map(publishNormalize).join(`
+`), WORDCELL_SITE_LIMITS_V1.fieldTextBytes);
+    const metadata = bounded(publishNormalize(canonicalJson(note.metadata)), WORDCELL_SITE_LIMITS_V1.fieldTextBytes);
+    textTruncated ||= title.truncated || aliases.truncated || path.truncated || tags.truncated || metadata.truncated;
+    fields.push({ t: title.text, a: aliases.text, p: path.text, g: tags.text, m: metadata.text });
+    if (indexContent) {
+      const inline = bounded(publishNormalize(note.searchableText), WORDCELL_SITE_LIMITS_V1.inlineTextBytes);
+      textTruncated ||= inline.truncated;
+      inlineTexts.push(inline.text);
+      inlineTotal += Buffer.byteLength(inline.text, "utf8");
+    }
+  }
+  const mode = !indexContent ? "none" : inlineTotal <= WORDCELL_SITE_LIMITS_V1.inlineTotalBytes ? "inline" : "shards";
+  const allTerms = new Set;
+  const contentPostings = new Map;
+  const docs = [];
+  for (const [index, note] of notes.entries()) {
+    const slug = slugById.get(note.id);
+    if (slug === undefined)
+      throw new Error(`Missing published slug for ${note.id}.`);
+    const field = fields[index];
+    if (field === undefined)
+      throw new Error(`Missing indexed fields for ${note.id}.`);
+    const inline = mode === "inline" ? inlineTexts[index] : undefined;
+    const fieldTerms = indexableTerms(`${field.t}
+${field.a}
+${field.p}
+${field.g}
+${field.m}`);
+    for (const term of fieldTerms)
+      allTerms.add(term);
+    if (mode !== "none") {
+      const content = inlineTexts[index] ?? "";
+      for (const term of indexableTerms(content)) {
+        allTerms.add(term);
+        if (mode === "shards") {
+          const list = contentPostings.get(term) ?? [];
+          list.push(index);
+          contentPostings.set(term, list);
+        }
+      }
+    }
+    docs.push({
+      i: index,
+      s: slug,
+      t: note.title,
+      p: previewText(note),
+      f: field,
+      ...inline === undefined ? {} : { x: inline }
+    });
+  }
+  let termsTruncated = false;
+  let sortedTerms = [...allTerms].toSorted((left, right) => left.localeCompare(right));
+  if (sortedTerms.length > WORDCELL_SITE_LIMITS_V1.indexTerms) {
+    sortedTerms = sortedTerms.slice(0, WORDCELL_SITE_LIMITS_V1.indexTerms);
+    termsTruncated = true;
+  }
+  const admitted = new Set(sortedTerms);
+  const postings = new Map;
+  if (mode === "shards") {
+    const grouped = new Map;
+    for (const [term, docIds] of [...contentPostings.entries()].toSorted(([a], [b]) => a.localeCompare(b))) {
+      if (!admitted.has(term))
+        continue;
+      const shard = publishShardName(term);
+      const bucket = grouped.get(shard) ?? Object.create(null);
+      bucket[term] = docIds;
+      grouped.set(shard, bucket);
+    }
+    for (const [shard, bucket] of [...grouped.entries()].toSorted(([a], [b]) => a.localeCompare(b))) {
+      postings.set(shard, {
+        format: WORDCELL_SITE_POSTINGS_FORMAT_V1,
+        shard,
+        postings: Object.freeze(bucket)
+      });
+    }
+  }
+  return {
+    docs: {
+      format: WORDCELL_SITE_DOCS_FORMAT_V1,
+      content: mode,
+      docs
+    },
+    terms: {
+      format: WORDCELL_SITE_TERMS_FORMAT_V1,
+      terms: sortedTerms
+    },
+    postings,
+    termsCount: sortedTerms.length,
+    termsTruncated,
+    textTruncated,
+    mode
+  };
+}
+
 // src/publish-nav.ts
 var SITE_NAV_GROUP_LIMIT = 96;
 var SITE_NAV_NODE_BUDGET = 768;
@@ -1709,7 +1779,7 @@ async function projectVault(snapshot, options, io) {
   let anyTextTruncated = false;
   for (const note of selection.notes) {
     const slug = slugFor(note.id);
-    const text = boundedNormalized(note.searchableText, WORDCELL_SITE_LIMITS_V1.noteTextBytes);
+    const text = boundedNormalized(projectMarkdownText(note.content).text, WORDCELL_SITE_LIMITS_V1.noteTextBytes);
     anyTextTruncated ||= text.truncated;
     const payload = {
       format: WORDCELL_SITE_NOTE_FORMAT_V1,

package/dist/index.js

@@ -167,7 +167,7 @@ import {
   publishVault,
   renderPublishReportText,
   serializeSiteFile
-} from "./index-a3j61wz9.js";
+} from "./index-pnt9wr59.js";
 import {
   MAX_NOTE_UTF8_BYTES,
   MAX_SCANNED_NOTES,
@@ -245,7 +245,7 @@ import {
   parseSitePostingsV1,
   parseSiteTermsV1
 } from "./index-66pshdtx.js";
-import"./index-3agn8scn.js";
+import"./index-23m6bbjt.js";
 import {
   auditAgentGuideRepository,
   auditAgentGuideSource,

package/dist/publish-reader/reader.js

@@ -757,22 +757,58 @@ function comparePublishScores(left, right) {
   return Number(right.identity) - Number(left.identity) || right.score - left.score || left.i - right.i;
 }
 function publishSnippet(text, query, fallback, windowBytes = 160) {
-  const normalized = publishNormalize(text);
-  let offset = query.normalized === "" ? -1 : normalized.indexOf(query.normalized);
-  if (offset < 0) {
+  if (!Number.isSafeInteger(windowBytes) || windowBytes < 0)
+    throw new RangeError("Snippet window must be a nonnegative safe byte count.");
+  const display = text.normalize("NFC");
+  const normalized = publishNormalize(display);
+  let match = query.normalized === "" ? -1 : normalized.indexOf(query.normalized);
+  if (match < 0) {
     for (const term of query.terms) {
-      offset = normalized.indexOf(term);
-      if (offset >= 0)
+      match = normalized.indexOf(term);
+      if (match >= 0)
         break;
     }
   }
-  if (offset < 0)
+  if (match < 0)
     return fallback;
-  const half = Math.floor(windowBytes / 2);
-  const start = Math.max(0, offset - half);
-  const end = Math.min(text.length, offset + half);
-  const snippet = text.slice(start, end).replace(/\s+/gu, " ").trim();
-  return `${start > 0 ? "…" : ""}${snippet}${end < text.length ? "…" : ""}`;
+  let offset = 0, normalizedOffset = 0;
+  for (const character of display) {
+    const width = character.toLocaleLowerCase("en-US").length;
+    if (normalizedOffset + width > match)
+      break;
+    normalizedOffset += width;
+    offset += character.length;
+  }
+  const edge = windowBytes >= 6 ? "…" : "";
+  const budget = windowBytes - 2 * publishUtf8Bytes(edge);
+  const previous = (end2) => {
+    const last = display.charCodeAt(end2 - 1);
+    return end2 > 1 && last >= 56320 && last <= 57343 && display.charCodeAt(end2 - 2) >= 55296 && display.charCodeAt(end2 - 2) <= 56319 ? end2 - 2 : end2 - 1;
+  };
+  let start = offset, end = offset, used = 0;
+  while (start > 0) {
+    const before = previous(start), bytes = publishUtf8Bytes(display.slice(before, start));
+    if (used + bytes > Math.floor(budget / 2))
+      break;
+    start = before;
+    used += bytes;
+  }
+  while (end < display.length) {
+    const character = String.fromCodePoint(display.codePointAt(end) ?? 0), bytes = publishUtf8Bytes(character);
+    if (used + bytes > budget)
+      break;
+    end += character.length;
+    used += bytes;
+  }
+  while (start > 0) {
+    const before = previous(start), bytes = publishUtf8Bytes(display.slice(before, start));
+    if (used + bytes > budget)
+      break;
+    start = before;
+    used += bytes;
+  }
+  const snippet = display.slice(start, end).replace(/\s+/gu, " ").trim();
+  return `${start > 0 ? edge : ""}${snippet}${end < display.length ? edge : ""}`;
 }
 
 // src/publish-theme.ts
@@ -924,7 +960,7 @@ function resultHref(base, slug) {
 }
 function snippetFor(index, doc, query) {
   const hydrated = index.notes.get(doc.s);
-  const text = hydrated?.text ?? doc.x;
+  const text = hydrated?.text;
   return text === undefined ? doc.p : publishSnippet(text, query, doc.p);
 }
 function appendMarked(parent, text, terms) {

package/dist/publish-search.js

@@ -23,7 +23,7 @@ import {
   publishSnippet,
   publishUtf8Bytes,
   scorePublishDocument
-} from "./index-3agn8scn.js";
+} from "./index-23m6bbjt.js";
 import"./index-z1w83f81.js";
 export {
   scorePublishDocument,

package/dist/publish.js

@@ -10,14 +10,14 @@ import {
   publishVault,
   renderPublishReportText,
   serializeSiteFile
-} from "./index-a3j61wz9.js";
+} from "./index-pnt9wr59.js";
 import"./index-233z9wmn.js";
 import"./index-d13v9ckt.js";
 import"./index-48pz4jpc.js";
 import"./index-06c9ctr6.js";
 import"./index-4knsp9qj.js";
 import"./index-66pshdtx.js";
-import"./index-3agn8scn.js";
+import"./index-23m6bbjt.js";
 import"./index-5vwpzb5a.js";
 import"./index-x3fthpsc.js";
 import"./index-qbssx940.js";

package/dist/{support-vm8fw4yc.js → support-m3t917ev.js}

@@ -2,7 +2,7 @@
 import {
   parseArguments as parseArguments2,
   parseUrlMetadataArguments
-} from "./index-yx6p1vzc.js";
+} from "./index-9h7zh0wt.js";
 import"./index-bcknqxrq.js";
 import {
   parsePdfArguments
@@ -42,14 +42,14 @@ import"./index-tf4wzjew.js";
 import"./index-1gwbassd.js";
 import"./index-vnybgywh.js";
 import"./index-1xxnjn0d.js";
-import"./index-a3j61wz9.js";
+import"./index-pnt9wr59.js";
 import"./index-233z9wmn.js";
 import"./index-d13v9ckt.js";
 import"./index-48pz4jpc.js";
 import"./index-06c9ctr6.js";
 import"./index-4knsp9qj.js";
 import"./index-66pshdtx.js";
-import"./index-3agn8scn.js";
+import"./index-23m6bbjt.js";
 import"./index-hya40gb2.js";
 import"./index-5vwpzb5a.js";
 import"./index-x3fthpsc.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hraness/wordcell",
-  "version": "0.22.3",
+  "version": "0.22.4",
   "description": "A local Markdown knowledge base with superpowers. Save decisions, sources, and plans as files you own, then recover them through exact and semantic search, typed relationships, backlinks, and Git history.",
   "license": "MIT",
   "type": "module",
@@ -479,8 +479,8 @@
     "check": "bun run check:worker && bun run check:effect && bun run check:workflows && bun run check:portfolio-inventory && bun run check:installed-command-docs && bun run typecheck && bun run build && bun run test:package && bun run test && bun run url-metadata:tool:check",
     "prepack": "bun run check",
     "check:effect": "bun run scripts/check-effect-policy.ts",
-    "kb:search": "bunx --bun --package https://github.com/hraness/wordcell/releases/download/v0.22.2/hraness-wordcell-0.22.2.tgz wordcell search --root kb --mode exact --rerank typesafe --rerank-limit 25",
-    "kb:search:local": "bunx --bun --package https://github.com/hraness/wordcell/releases/download/v0.22.2/hraness-wordcell-0.22.2.tgz wordcell search --root kb --mode exact",
+    "kb:search": "bunx --bun --package https://github.com/hraness/wordcell/releases/download/v0.22.3/hraness-wordcell-0.22.3.tgz wordcell search --root kb --mode exact --rerank typesafe --rerank-limit 25",
+    "kb:search:local": "bunx --bun --package https://github.com/hraness/wordcell/releases/download/v0.22.3/hraness-wordcell-0.22.3.tgz wordcell search --root kb --mode exact",
     "check:worker": "tsc -p worker/tsconfig.json --noEmit"
   },
   "dependencies": {

package/skills/wordcell/SKILL.md

@@ -56,7 +56,7 @@ missing:
 ```sh
 command -v wordcell >/dev/null 2>&1 || {
   command -v bun >/dev/null 2>&1 || exit 1
-  bun add --global --ignore-scripts https://github.com/hraness/wordcell/releases/download/v0.22.3/hraness-wordcell-0.22.3.tgz
+  bun add --global --ignore-scripts https://github.com/hraness/wordcell/releases/download/v0.22.4/hraness-wordcell-0.22.4.tgz
 }
 wordcell --help
 ```

package/src/publish-index.ts

@@ -1,6 +1,7 @@
 import { canonicalJson } from "@hraness/oh";
 
 import type { Note } from "./graph.js";
+import { projectMarkdownText } from "./publish-markdown.js";
 import {
   WORDCELL_SITE_DOCS_FORMAT_V1,
   WORDCELL_SITE_LIMITS_V1,
@@ -38,8 +39,8 @@ function bounded(value: string, maximumBytes: number): { text: string; truncated
 }
 
 function previewText(note: Note): string {
-  const basis = note.summary !== "" ? note.summary : note.searchableText;
-  const collapsed = basis.replace(/\s+/gu, " ").trim();
+  const display = projectMarkdownText(note.content, note.properties["description"]);
+  const collapsed = display.preview.replace(/\s+/gu, " ").trim();
   return bounded(collapsed, WORDCELL_SITE_LIMITS_V1.docPreviewBytes).text;
 }
 

package/src/publish-markdown.ts

@@ -108,6 +108,8 @@ type Footnotes = {
   definitions: number;
   references: number;
   disabled: boolean;
+  /** Plain display projections omit admitted citation navigation only. */
+  readonly plain?: true;
 };
 
 function footnoteLabel(raw: string): string | undefined {
@@ -136,6 +138,7 @@ function renderFootnoteReference(raw: string, label: string, footnotes: Footnote
   const id = `wordcell:footnote-ref:${number}:${note.references.length + 1}`;
   note.references.push(id);
   footnotes.references += 1;
+  if (footnotes.plain) return "";
   return `<sup><a id="${id}" href="#wordcell:footnote:${number}" role="doc-noteref" aria-label="Footnote ${number}">${number}</a></sup>`;
 }
 
@@ -820,6 +823,58 @@ export function renderMarkdownToHtml(content: string, ctx: PublishRenderContext)
   return `${body}${body === "" ? "" : "\n"}<section class="footnotes" aria-label="Footnotes"><ol>\n${notes}\n</ol></section>`;
 }
 
+export type PublishMarkdownText = {
+  readonly text: string;
+  readonly preview: string;
+};
+
+/**
+ * Readable display text, derived before truncation or case normalization.
+ * Shares the article grammar and footnote admission rules; it is not an index
+ * or a replacement for authored Markdown. Valid citation navigation disappears,
+ * while unresolved definitions/references, escaped text, and code stay literal.
+ */
+export function projectMarkdownText(content: string, description?: string): PublishMarkdownText {
+  const footnotes: Footnotes = { byLabel: new Map(), numbered: [], definitions: 0, references: 0, disabled: false, plain: true };
+  const blocks = parseMarkdownBlocks(content, footnotes, true);
+  // Display labels need no filesystem, URL fetch, or selected-note resolution.
+  // Unresolved local assets retain their authored alt text through renderInline.
+  const context: PublishRenderContext = {
+    source: "", resolveNote: () => undefined, resolveAsset: () => undefined, noteHref: () => "",
+  };
+  const inline = (text: string, state?: Footnotes): string => stripMarkup(renderInline(text, context, state));
+  const parts = (items: readonly MarkdownBlock[], state: Footnotes): string[] => items.map((block): string => {
+    switch (block.type) {
+      case "paragraph": case "heading": return inline(block.text, state);
+      case "literal": case "code": return block.text;
+      case "break": return "";
+      case "quote": return parts(block.blocks, state).join("\n\n");
+      case "table": return [block.header, ...block.rows].map((row) => row.map((cell) => inline(cell, state)).join(" ")).join("\n");
+      case "list": return block.parts.map((part) => part.type === "item" || part.type === "continuation" ? inline(part.text, state) : "").filter(Boolean).join("\n");
+      case "footnote": return state.disabled || block.note.invalid ? block.note.authored : "";
+    }
+  });
+  const rendered = parts(blocks, footnotes);
+  // The article orders valid definitions by first reference, then unreferenced
+  // definitions. Nested references in their bodies deliberately remain literal.
+  if (!footnotes.disabled) for (const note of footnotes.byLabel.values()) {
+    if (note !== null && !note.invalid) footnoteNumber(note, footnotes);
+  }
+  const text = [...rendered, ...footnotes.numbered.map((note) => inline(note.body.replaceAll("\n", " ")))].filter(Boolean).join("\n\n");
+  let preview = rendered.find((value, index) => blocks[index]?.type === "paragraph" && value.trim() !== "") ?? text;
+  if (description !== undefined && description.trim() !== "") {
+    // Resolve description citations against the same authored definitions, but
+    // never let preview rendering consume the article's citation allowance.
+    const state: Footnotes = {
+      byLabel: new Map([...footnotes.byLabel].map(([label, note]) => [label, note === null ? null : { body: note.body, authored: note.authored, invalid: note.invalid, references: [] }])),
+      numbered: [], definitions: footnotes.definitions, references: 0, disabled: footnotes.disabled, plain: true,
+    };
+    const authored = parts(parseMarkdownBlocks(description, state, false), state).filter(Boolean).join("\n\n");
+    if (authored.trim() !== "") preview = authored;
+  }
+  return { text, preview };
+}
+
 export function stripMarkup(html: string): string {
   // Scan literal tags first — escaped angle brackets (&lt;) decode to text,
   // never tag boundaries. The character scanner (not a regex) keeps CodeQL's

package/src/publish-model.ts

@@ -47,7 +47,7 @@ export const WORDCELL_SITE_LIMITS_V1 = Object.freeze({
    * exact lane's substring semantics; larger corpora use postings shards.
    */
   inlineTotalBytes: 2 * 1_024 * 1_024,
-  /** Normalized content text retained per note payload for hydration. */
+  /** Normalized readable content retained per note payload for snippet hydration. */
   noteTextBytes: 32 * 1_024,
   /** Site title and description. */
   titleBytes: 512,
@@ -185,7 +185,7 @@ export type WordcellSiteNoteV1 = {
   readonly type?: string;
   readonly tags: readonly string[];
   readonly summary: string;
-  /** Bounded normalized content text for search hydration. */
+  /** Bounded normalized readable content for snippet hydration, not ranking. */
   readonly text: string;
   readonly textTruncated: boolean;
   readonly links: readonly WordcellSiteNoteLinkV1[];

package/src/publish-reader/reader.ts

@@ -321,7 +321,9 @@ function resultHref(base: string, slug: string): string {
 
 function snippetFor(index: SiteIndex, doc: WordcellSiteDocV1, query: PublishQuery): string {
   const hydrated = index.notes.get(doc.s);
-  const text = hydrated?.text ?? doc.x;
+  // doc.x is a normalized ranking basis, not display text. The eager preview
+  // remains readable while the existing bounded hydration fetch is pending.
+  const text = hydrated?.text;
   return text === undefined ? doc.p : publishSnippet(text, query, doc.p);
 }
 

package/src/publish-search.ts

@@ -392,8 +392,10 @@ export function comparePublishScores(
 }
 
 /**
- * Bounded context window around the first query match in normalized text.
- * Mirrors `exactSnippet`: collapse whitespace, ellipsize edges.
+ * Bounded display context around the first normalized query match. Match
+ * offsets are mapped back to NFC display text before taking a UTF-8 byte
+ * window, so case expansion and supplementary characters cannot split it.
+ * The fallback retains the separate document-preview byte contract.
  */
 export function publishSnippet(
   text: string,
@@ -401,18 +403,47 @@ export function publishSnippet(
   fallback: string,
   windowBytes = 160,
 ): string {
-  const normalized = publishNormalize(text);
-  let offset = query.normalized === "" ? -1 : normalized.indexOf(query.normalized);
-  if (offset < 0) {
+  if (!Number.isSafeInteger(windowBytes) || windowBytes < 0) throw new RangeError("Snippet window must be a nonnegative safe byte count.");
+  const display = text.normalize("NFC");
+  const normalized = publishNormalize(display);
+  let match = query.normalized === "" ? -1 : normalized.indexOf(query.normalized);
+  if (match < 0) {
     for (const term of query.terms) {
-      offset = normalized.indexOf(term);
-      if (offset >= 0) break;
+      match = normalized.indexOf(term);
+      if (match >= 0) break;
     }
   }
-  if (offset < 0) return fallback;
-  const half = Math.floor(windowBytes / 2);
-  const start = Math.max(0, offset - half);
-  const end = Math.min(text.length, offset + half);
-  const snippet = text.slice(start, end).replace(/\s+/gu, " ").trim();
-  return `${start > 0 ? "…" : ""}${snippet}${end < text.length ? "…" : ""}`;
+  if (match < 0) return fallback;
+  let offset = 0, normalizedOffset = 0;
+  for (const character of display) {
+    const width = character.toLocaleLowerCase("en-US").length;
+    if (normalizedOffset + width > match) break;
+    normalizedOffset += width;
+    offset += character.length;
+  }
+  const edge = windowBytes >= 6 ? "…" : "";
+  const budget = windowBytes - 2 * publishUtf8Bytes(edge);
+  const previous = (end: number): number => {
+    const last = display.charCodeAt(end - 1);
+    return end > 1 && last >= 0xdc00 && last <= 0xdfff && display.charCodeAt(end - 2) >= 0xd800 && display.charCodeAt(end - 2) <= 0xdbff ? end - 2 : end - 1;
+  };
+  let start = offset, end = offset, used = 0;
+  while (start > 0) {
+    const before = previous(start), bytes = publishUtf8Bytes(display.slice(before, start));
+    if (used + bytes > Math.floor(budget / 2)) break;
+    start = before; used += bytes;
+  }
+  while (end < display.length) {
+    const character = String.fromCodePoint(display.codePointAt(end) ?? 0), bytes = publishUtf8Bytes(character);
+    if (used + bytes > budget) break;
+    end += character.length; used += bytes;
+  }
+  // Near the end, spend the remaining budget on earlier whole characters.
+  while (start > 0) {
+    const before = previous(start), bytes = publishUtf8Bytes(display.slice(before, start));
+    if (used + bytes > budget) break;
+    start = before; used += bytes;
+  }
+  const snippet = display.slice(start, end).replace(/\s+/gu, " ").trim();
+  return `${start > 0 ? edge : ""}${snippet}${end < display.length ? edge : ""}`;
 }

package/src/publish.ts

@@ -16,6 +16,7 @@ import {
 } from "./graph.js";
 import { buildSiteIndex } from "./publish-index.js";
 import {
+  projectMarkdownText,
   renderMarkdownToHtml,
   type PublishRenderContext,
 } from "./publish-markdown.js";
@@ -307,7 +308,9 @@ export async function projectVault(
   let anyTextTruncated = false;
   for (const note of selection.notes) {
     const slug = slugFor(note.id);
-    const text = boundedNormalized(note.searchableText, WORDCELL_SITE_LIMITS_V1.noteTextBytes);
+    // Display grammar owns citations before normalization can fold distinct
+    // labels together. Ranking continues to use untouched searchableText.
+    const text = boundedNormalized(projectMarkdownText(note.content).text, WORDCELL_SITE_LIMITS_V1.noteTextBytes);
     anyTextTruncated ||= text.truncated;
     const payload: WordcellSiteNoteV1 = {
       format: WORDCELL_SITE_NOTE_FORMAT_V1,