@uniweb/projections 0.4.1 → 0.5.1

package/README.md

@@ -127,8 +127,14 @@ a third-party convention that may not survive — so it appears exactly once, in
 `config.js`, at the edge. A change of convention costs a constant.
 
 **Search** — also available from the `@uniweb/projections/search` subpath:
-`generateSearchIndex`, `extractSearchContent`, `generateCollectionIndex`,
-`isSearchEnabled`, `getSearchConfig`, `getSearchIndexFilename`.
+`generateSearchIndex`, `extractSearchContent`, `generateRecordSearchIndex`,
+`mergeSearchIndexes`, `isSearchEnabled`, `getSearchConfig`, `getSearchIndexFilename`.
+
+> **Renamed in 0.5.0** — `generateCollectionIndex` is now `generateRecordSearchIndex`, and a
+> search entry carries `type: 'record'` / `group` / `id: "record:<group>:<slug>"` where it
+> carried `type: 'collection'` / `collection` / `id: "collection:…"`. *"Collection" is a
+> build-side concept — a named set compiled to one file — and this function is called with
+> records that may never have been one.*
 
 ```js
 import { generateSearchIndex, isSearchEnabled } from '@uniweb/projections/search'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/projections",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "description": "Projections of a Uniweb site's content — agent index, per-page markdown, search index. Pure JS, runs anywhere.",
   "type": "module",
   "exports": {
@@ -31,8 +31,8 @@
     "node": ">=20.19"
   },
   "dependencies": {
-    "@uniweb/core": "^0.13.0",
-    "@uniweb/content-writer": "^0.3.4"
+    "@uniweb/content-writer": "^0.3.4",
+    "@uniweb/core": "^0.13.1"
   },
   "devDependencies": {
     "vitest": "^4.1.7",

package/src/insets.js

@@ -0,0 +1,73 @@
+/**
+ * Inset captions — the one place that decides what an inset contributes.
+ *
+ * Shared by BOTH projections on purpose. The markdown page and the search index
+ * are two views of ONE site, so "what words did the author write here" has to be
+ * answered once. It was answered twice — markdown resolved captions and search
+ * did not — and the two artifacts disagreed about the same page.
+ */
+
+/**
+ * Replace `inset_placeholder` nodes with the author's own words.
+ *
+ * ## Why this is not "restore the inset"
+ *
+ * An inset is `![Platform overview](@Diagram)` — an author's caption plus a
+ * FOUNDATION COMPONENT to render it with. The build splits them: the caption and
+ * params go to the section's `insets[]`, and the body keeps an
+ * `inset_placeholder` carrying only `{ refId, embedKind }`.
+ *
+ * ⛔ **`@Diagram` must never reach this output.** A component name is a rendering
+ * assignment, and this package's whole property is that a projection is of the
+ * SITE — identical under a swapped foundation. Emitting it here would break the
+ * same rule that keeps `type:` and params out (see the package's README/notes on
+ * why the exclusions are load-bearing rather than tidy-up).
+ *
+ * ⭐ **But the caption IS site content** — the author wrote it, and an agent
+ * retrieving this page should read it. So the placeholder becomes its title, as
+ * plain text, and nothing else.
+ *
+ * ⚠️ Before this, `proseMirrorToMarkdown` had no serializer for the node and
+ * dropped it with a warning per build — *"this is a tracked capability gap"*. It
+ * was: every inset caption was missing from every agent-facing page.
+ *
+ * @param {Object} content - the section's ProseMirror document
+ * @param {Array} insets - the section's `insets[]` (`{ refId, title }`)
+ * @returns {Object} content with placeholders resolved to text
+ */
+export function resolveInsetCaptions(content, insets) {
+  if (!content?.content?.length) return content
+  // No insets array → nothing to resolve against. Dropping is then still the only
+  // option, but it is silent: the caption is genuinely not reachable from here.
+  const titleByRef = new Map(
+    (Array.isArray(insets) ? insets : [])
+      .filter((i) => i && typeof i.refId === 'string' && i.title)
+      .map((i) => [i.refId, String(i.title)])
+  )
+
+  // ⛔ THE REPLACEMENT'S SHAPE DEPENDS ON WHERE IT SITS, and getting this wrong
+  // fails SILENTLY IN THE WORSE DIRECTION: a bare text node at block level is not
+  // serializable, so the caption vanishes exactly as before — but the warning that
+  // used to announce it is gone. Measured while writing this: the first version
+  // emitted text unconditionally, removed the warning, and restored nothing.
+  const TEXTBLOCKS = new Set(['paragraph', 'heading'])
+
+  const visit = (nodes, inline) =>
+    nodes.flatMap((node) => {
+      if (!node) return []
+      if (node.type === 'inset_placeholder') {
+        const title = titleByRef.get(node.attrs?.refId)
+        // An inset with no caption contributes no author text — drop it, and do
+        // so quietly: there is nothing a reader is missing.
+        if (!title) return []
+        const text = { type: 'text', text: title }
+        return inline ? [text] : [{ type: 'paragraph', content: [text] }]
+      }
+      if (Array.isArray(node.content)) {
+        return [{ ...node, content: visit(node.content, TEXTBLOCKS.has(node.type)) }]
+      }
+      return [node]
+    })
+
+  return { ...content, content: visit(content.content, false) }
+}

package/src/markdown.js

@@ -19,6 +19,7 @@
 
 import { proseMirrorToMarkdown } from '@uniweb/content-writer'
 import { sectionDomId } from '@uniweb/core/section-id'
+import { resolveInsetCaptions } from './insets.js'
 
 /**
  * How blocks are joined into a page. Exported because the corpus projection
@@ -100,71 +101,6 @@ function collectSection(section, blocks, includeChildren, ancestorAnchor) {
   }
 }
 
-/**
- * Replace `inset_placeholder` nodes with the author's own words.
- *
- * ## Why this is not "restore the inset"
- *
- * An inset is `![Platform overview](@Diagram)` — an author's caption plus a
- * FOUNDATION COMPONENT to render it with. The build splits them: the caption and
- * params go to the section's `insets[]`, and the body keeps an
- * `inset_placeholder` carrying only `{ refId, embedKind }`.
- *
- * ⛔ **`@Diagram` must never reach this output.** A component name is a rendering
- * assignment, and this package's whole property is that a projection is of the
- * SITE — identical under a swapped foundation. Emitting it here would break the
- * same rule that keeps `type:` and params out (see the package's README/notes on
- * why the exclusions are load-bearing rather than tidy-up).
- *
- * ⭐ **But the caption IS site content** — the author wrote it, and an agent
- * retrieving this page should read it. So the placeholder becomes its title, as
- * plain text, and nothing else.
- *
- * ⚠️ Before this, `proseMirrorToMarkdown` had no serializer for the node and
- * dropped it with a warning per build — *"this is a tracked capability gap"*. It
- * was: every inset caption was missing from every agent-facing page.
- *
- * @param {Object} content - the section's ProseMirror document
- * @param {Array} insets - the section's `insets[]` (`{ refId, title }`)
- * @returns {Object} content with placeholders resolved to text
- */
-function resolveInsetCaptions(content, insets) {
-  if (!content?.content?.length) return content
-  // No insets array → nothing to resolve against. Dropping is then still the only
-  // option, but it is silent: the caption is genuinely not reachable from here.
-  const titleByRef = new Map(
-    (Array.isArray(insets) ? insets : [])
-      .filter((i) => i && typeof i.refId === 'string' && i.title)
-      .map((i) => [i.refId, String(i.title)])
-  )
-
-  // ⛔ THE REPLACEMENT'S SHAPE DEPENDS ON WHERE IT SITS, and getting this wrong
-  // fails SILENTLY IN THE WORSE DIRECTION: a bare text node at block level is not
-  // serializable, so the caption vanishes exactly as before — but the warning that
-  // used to announce it is gone. Measured while writing this: the first version
-  // emitted text unconditionally, removed the warning, and restored nothing.
-  const TEXTBLOCKS = new Set(['paragraph', 'heading'])
-
-  const visit = (nodes, inline) =>
-    nodes.flatMap((node) => {
-      if (!node) return []
-      if (node.type === 'inset_placeholder') {
-        const title = titleByRef.get(node.attrs?.refId)
-        // An inset with no caption contributes no author text — drop it, and do
-        // so quietly: there is nothing a reader is missing.
-        if (!title) return []
-        const text = { type: 'text', text: title }
-        return inline ? [text] : [{ type: 'paragraph', content: [text] }]
-      }
-      if (Array.isArray(node.content)) {
-        return [{ ...node, content: visit(node.content, TEXTBLOCKS.has(node.type)) }]
-      }
-      return [node]
-    })
-
-  return { ...content, content: visit(content.content, false) }
-}
-
 /**
  * @param {Object} section
  * @returns {string}

package/src/search/extract.js

@@ -10,6 +10,7 @@
 // Enforced by tests/environment.test.js.
 import { sectionDomId } from '@uniweb/core/section-id'
 import { selectIndexablePages } from '../pages.js'
+import { resolveInsetCaptions } from '../insets.js'
 
 /**
  * Extract all searchable content from site
@@ -165,7 +166,25 @@ function extractFromSection(section, page, options, ancestorAnchor) {
   let sectionTitle = ''
 
   if (section.content?.type === 'doc') {
-    const extracted = extractFromProseMirrorDoc(section.content, {
+    // ⭐ RESOLVE INSET CAPTIONS FIRST, with the SAME function the markdown
+    // projection uses. An inset is `![Platform overview](@Diagram)`: the build
+    // moves the author's caption into `insets[]` and leaves an
+    // `inset_placeholder` behind, so a walk of the body alone never sees it.
+    //
+    // ⛔ Both positions were losing text, and the INLINE one was losing it in the
+    // worse direction: a placeholder mid-sentence contributed nothing, so
+    // "See <inset> for detail." was indexed as "See  for detail." — mangled
+    // prose rather than an obvious hole, and a search for the caption's words
+    // found a page whose markdown projection plainly contained them.
+    //
+    // Resolving up front rather than teaching the walkers about the node keeps
+    // ONE implementation of "a caption is content, a component name is not" —
+    // the property this whole package rests on. It also makes both positions
+    // work for free: a block placeholder becomes a paragraph, an inline one a
+    // text node, and the existing walk already handles both.
+    const content = resolveInsetCaptions(section.content, section.insets)
+
+    const extracted = extractFromProseMirrorDoc(content, {
       includeHeadings,
       includeParagraphs,
       includeLinks,
@@ -235,10 +254,32 @@ function extractFromProseMirrorDoc(doc, options) {
     return { title, textParts }
   }
 
-  for (const node of doc.content) {
+  // ⛔ CONTAINERS WHOSE CHILDREN ARE ORDINARY AUTHOR PROSE. Until 2026-08-27 this
+  // walk was FLAT over `doc.content`, so anything nested one level down was
+  // invisible to search — measured: a blockquote's prose and every table cell were
+  // lost outright, on a site that looked perfectly indexed.
+  //
+  // ⭐ An ALLOWLIST rather than a blind recursion, deliberately: descending into
+  // everything would pull in `codeBlock` and `math_display`, which are not prose —
+  // they inflate the index and match on tokens nobody searches for. Adding a
+  // container here is a decision, not a default.
+  const DESCEND = new Set(['blockquote', 'table', 'tableRow', 'tableCell'])
+
+  const walk = (nodes) => {
+    for (const node of nodes || []) {
+      if (!node) continue
+      if (DESCEND.has(node.type)) {
+        walk(node.content)
+        continue
+      }
+      visit(node)
+    }
+  }
+
+  const visit = (node) => {
     if (node.type === 'heading') {
       const text = extractTextFromNode(node)
-      if (!text) continue
+      if (!text) return
 
       // First H1 becomes the title
       if (!foundFirstHeading && node.attrs?.level === 1) {
@@ -269,9 +310,16 @@ function extractFromProseMirrorDoc(doc, options) {
     } else if ((node.type === 'bulletList' || node.type === 'orderedList') && includeLists) {
       const listTexts = extractFromList(node)
       textParts.push(...listTexts)
+    } else if (node.type === 'image') {
+      // ⭐ `alt` is the author describing their own image — the only words an
+      // image contributes, and what a reader searching for it would type.
+      const alt = typeof node.attrs?.alt === 'string' ? node.attrs.alt.trim() : ''
+      if (alt) textParts.push(alt)
     }
   }
 
+  walk(doc.content)
+
   return { title, textParts }
 }
 

package/src/search/records.js

@@ -79,11 +79,12 @@ const DISPLAY_VALUE_MAX = 200
  *    as an index OF collections or a collection's own listing. It is neither: it
  *    is a search index derived FROM records.
  *
- * ⚠️ The RESULT still carries the old vocabulary — `type: 'collection'`,
- * `collection: name`, and `id: "collection:<name>:<slug>"`. That is a data shape
- * with live consumers (`kit`'s endpoint search provider and hosting's search both
- * read `entry.collection`), so it is a separate, larger decision than this rename
- * and is deliberately NOT bundled into it.
+ * ✅ The RESULT was renamed to match, 2026-08-27 — `type: 'record'`, `group: name`,
+ * `id: "record:<group>:<slug>"`. That was a real data break against two live
+ * consumers (kit's endpoint search provider and hosting's search), taken
+ * deliberately rather than left to rot: doing it while the shape was already
+ * being discussed cost one coordinated change; leaving it would have made the
+ * entry the last place `collection` survived as a lane-crossing word.
  */
 export function generateRecordSearchIndex(name, config, collectionData, locale) {
   // ⛔ NO DEFAULT FIELD LIST. This was `|| ['title']` — a claim about someone
@@ -113,9 +114,18 @@ export function generateRecordSearchIndex(name, config, collectionData, locale)
     // correctly, looks plausible, and 404s on click.
     const route = item.route || composeRoute(config.route, slug)
     return {
-      id: `collection:${name}:${slug}`,
-      type: 'collection',
-      collection: name,
+      // ⛔ RENAMED 2026-08-27 — `collection` is FRAMEWORK'S build concept (a named
+      // set our build compiles to one file) and the live lane has no such thing:
+      // a host calls this with records fetched from a folder. Same category error
+      // the function name carried until it became `generateRecordSearchIndex`.
+      //
+      // ⭐ `record` is symmetric with the page entry's `type: 'page'` / `id:
+      // "page:<route>"`, and true on both lanes. `group` names what a result UI
+      // actually does with it — label or group results by the set they came from —
+      // without borrowing either lane's word for that set.
+      id: `record:${name}:${slug}`,
+      type: 'record',
+      group: name,
       ...(route ? { route } : {}),
       title: item.title || item.name || slug,
       content,
@@ -130,8 +140,8 @@ export function generateRecordSearchIndex(name, config, collectionData, locale)
   // No `generated` timestamp — see the note in `generate.js`. A clock defeats
   // content-addressing and byte-parity between publishers.
   return {
-    type: 'collection',
-    collection: name,
+    type: 'record',
+    group: name,
     locale,
     entries,
   }