@uniweb/projections 0.3.7 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/projections",
-  "version": "0.3.7",
+  "version": "0.4.1",
   "description": "Projections of a Uniweb site's content — agent index, per-page markdown, search index. Pure JS, runs anywhere.",
   "type": "module",
   "exports": {

package/src/index.js

@@ -57,7 +57,7 @@ export {
   extractSearchContent,
   generateSearchIndex,
   mergeSearchIndexes,
-  generateCollectionIndex,
+  generateRecordSearchIndex,
   isSearchEnabled,
   getSearchConfig,
   getSearchIndexFilename,

package/src/markdown.js

@@ -100,6 +100,71 @@ 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}
@@ -107,5 +172,5 @@ function collectSection(section, blocks, includeChildren, ancestorAnchor) {
 function serializeSectionContent(section) {
   const content = section?.content
   if (!content?.content?.length) return ''
-  return proseMirrorToMarkdown(content).trim()
+  return proseMirrorToMarkdown(resolveInsetCaptions(content, section?.insets)).trim()
 }

package/src/search/generate.js

@@ -85,7 +85,7 @@ export function generateSearchIndex(siteContent, options = {}) {
  * describe *where the index lives* — only whether it serves queries.
  *
  * @param {Object} pagesIndex - Result of {@link generateSearchIndex}
- * @param {Object[]} [collectionIndexes] - Results of `generateCollectionIndex`
+ * @param {Object[]} [collectionIndexes] - Results of `generateRecordSearchIndex`
  * @returns {Object} One index carrying every entry
  */
 export function mergeSearchIndexes(pagesIndex, collectionIndexes = []) {

package/src/search/index.js

@@ -43,4 +43,4 @@ export {
   getSearchIndexFilename
 } from './generate.js'
 
-export { generateCollectionIndex } from './collections.js'
+export { generateRecordSearchIndex } from './records.js'

package/src/search/{collections.js → records.js}

@@ -63,7 +63,29 @@ const isPrimitive = (v) =>
  */
 const DISPLAY_VALUE_MAX = 200
 
-export function generateCollectionIndex(name, config, collectionData, locale) {
+/**
+ * Search-index entries for one named group of records.
+ *
+ * ⛔ RENAMED from `generateCollectionIndex` — 2026-08-27, and the old name was
+ * wrong in two ways that mattered.
+ *
+ * 1. **"Collection" is FRAMEWORK'S build concept** — a named set our build
+ *    compiles to one file. The live lane has no such thing: a host calls this
+ *    with records it fetched from a folder, so the name put our build
+ *    vocabulary into a function whose main caller is a host. `record` is true on
+ *    both lanes and is what the argument actually holds.
+ * 2. **It never said `search`** — every sibling here does (`generateSearchIndex`,
+ *    `mergeSearchIndexes`, `extractSearchContent`), and "collection index" reads
+ *    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.
+ */
+export function generateRecordSearchIndex(name, config, collectionData, locale) {
   // ⛔ NO DEFAULT FIELD LIST. This was `|| ['title']` — a claim about someone
   // else's schema, and wrong for any collection without a `title` (a `people`
   // collection has `name`, a `products` one has `label`). The failure was