@uniweb/projections 0.1.5 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/projections",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "Projections of a Uniweb site's content — agent index, per-page markdown, search index. Pure JS, runs anywhere.",
   "type": "module",
   "exports": {
@@ -31,12 +31,12 @@
     "node": ">=20.19"
   },
   "dependencies": {
-    "@uniweb/core": "0.7.33",
-    "@uniweb/content-writer": "0.2.9"
+    "@uniweb/core": "0.8.0",
+    "@uniweb/content-writer": "0.3.0"
   },
   "devDependencies": {
     "vitest": "^4.1.7",
-    "@uniweb/content-reader": "1.1.17"
+    "@uniweb/content-reader": "1.2.0"
   },
   "scripts": {
     "test": "vitest run"

package/src/config.js

@@ -9,8 +9,17 @@
 /** Filename of the agent index within a locale's output root. */
 export const INDEX_FILENAME = 'llms.txt'
 
+/** Default minimum indexable pages before a branch earns its own index. */
+export const DEFAULT_BRANCH_MIN_PAGES = 5
+
 /** Defaults for the `agents:` block. Free capability, on by default.  */
-const DEFAULTS = { index: true, markdown: true, exclude: [] }
+const DEFAULTS = {
+  index: true,
+  markdown: true,
+  exclude: [],
+  branchIndexes: true,
+  branchMinPages: DEFAULT_BRANCH_MIN_PAGES,
+}
 
 /**
  * Read the site's `agents:` block.
@@ -27,16 +36,39 @@ export function resolveAgentsConfig(siteConfig = {}) {
   const agents = siteConfig?.agents
 
   // `agents: false` turns the whole capability off in one word.
-  if (agents === false) return { index: false, markdown: false, exclude: [] }
+  if (agents === false) {
+    return { index: false, markdown: false, exclude: [], branchIndexes: false, branchMinPages: DEFAULT_BRANCH_MIN_PAGES }
+  }
   if (!agents || typeof agents !== 'object') return { ...DEFAULTS }
 
   return {
     index: agents.index !== false,
     markdown: agents.markdown !== false,
     exclude: normalizeExclude(agents.exclude),
+    // On by default, but gated on size — so a small site gets none and a large
+    // one gets them without anyone opting in. An explicit list pins the set.
+    branchIndexes: agents.branchIndexes !== false,
+    branchMinPages: Number.isInteger(agents.branchMinPages)
+      ? agents.branchMinPages
+      : DEFAULT_BRANCH_MIN_PAGES,
   }
 }
 
+/**
+ * Output path of a branch index, relative to the locale root.
+ *
+ * `/docs` → `docs/llms.txt`, sitting beside that branch's pages so the external
+ * convention ("the index lives at the root of what it indexes") holds at every
+ * level a site publishes one.
+ *
+ * @param {string} route
+ * @returns {string}
+ */
+export function branchIndexFilename(route) {
+  const clean = (route || '').replace(/^\/+/, '').replace(/\/+$/, '')
+  return clean ? `${clean}/${INDEX_FILENAME}` : INDEX_FILENAME
+}
+
 /**
  * Normalize `exclude:` to a list of leading-slash route prefixes.
  *

package/src/index.js

@@ -29,12 +29,15 @@ export { resolvePageDescription } from './description.js'
 
 export {
   INDEX_FILENAME,
+  DEFAULT_BRANCH_MIN_PAGES,
   pageMarkdownFilename,
+  branchIndexFilename,
   resolveAgentsConfig,
 } from './config.js'
 
 export {
   selectIndexablePages,
+  selectIndexBranches,
   groupPagesForIndex,
   buildPageUrl,
   applyRouteTranslation,

package/src/pages.js

@@ -111,9 +111,70 @@ function isIndexable(page, branches) {
  * @param {string[]} [options.exclude] - Additional route prefixes
  * @returns {Object[]}
  */
-export function selectIndexablePages(pages = [], { exclude = [] } = {}) {
+export function selectIndexablePages(pages = [], { exclude = [], branch = null } = {}) {
   const branches = excludedBranches(pages, exclude)
-  return pages.filter(page => isIndexable(page, branches) && !isContainer(page))
+  return pages.filter(
+    page =>
+      isIndexable(page, branches) &&
+      !isContainer(page) &&
+      (!branch || isAtOrUnder(page.route, branch))
+  )
+}
+
+/** Route depth: `/docs` → 1, `/docs/authoring` → 2. */
+function routeDepth(route) {
+  return (route || '').split('/').filter(Boolean).length
+}
+
+/**
+ * Branches that warrant an index of their own (`/docs/llms.txt`).
+ *
+ * **A branch index is ADDITIVE, never a delegation.** The root index keeps
+ * enumerating every page: Phase 1's exit criterion is that a cold agent reaches
+ * a leaf in *two hops* (`/llms.txt` → the `.md`), and routing it through a
+ * branch index would make that three. So these are a scoped entry point for an
+ * agent already inside a branch — not a way to shrink the root.
+ *
+ * Consequently this does **not** close the index-size question: the root is
+ * still complete by design, so a large site's root index is still large. A
+ * size-based split is a separate decision, and it has to reckon with the
+ * two-hop criterion the same way.
+ *
+ * **Top-level containers only.** A branch index at every depth multiplies files
+ * without adding reachability — everything under `/docs/authoring` is already
+ * in both `/llms.txt` and `/docs/llms.txt`.
+ *
+ * @param {Object[]} pages - `siteContent.pages` (flat, already ordered)
+ * @param {Object} [options]
+ * @param {string[]} [options.exclude]
+ * @param {number} [options.minPages=5] - Below this, a branch rides the root index alone
+ * @returns {Array<{route: string, title: string, count: number}>}
+ */
+export function selectIndexBranches(pages = [], { exclude = [], minPages = 5 } = {}) {
+  const branchExclusions = excludedBranches(pages, exclude)
+  const out = []
+
+  for (const container of pages) {
+    if (!isContainer(container)) continue
+    if (!isIndexable(container, branchExclusions)) continue
+    if (routeDepth(container.route) !== 1) continue
+
+    const count = pages.filter(
+      page =>
+        isIndexable(page, branchExclusions) &&
+        !isContainer(page) &&
+        isAtOrUnder(page.route, container.route)
+    ).length
+
+    if (count < minPages) continue
+    out.push({
+      route: container.route,
+      title: container.title || container.label || container.route,
+      count,
+    })
+  }
+
+  return out
 }
 
 /**
@@ -127,16 +188,22 @@ export function selectIndexablePages(pages = [], { exclude = [] } = {}) {
  * @param {string[]} [options.exclude]
  * @returns {Array<{heading: string|null, route: string|null, pages: Object[]}>}
  */
-export function groupPagesForIndex(pages = [], { exclude = [] } = {}) {
+export function groupPagesForIndex(pages = [], { exclude = [], branch = null } = {}) {
   const branches = excludedBranches(pages, exclude)
   const containers = pages.filter(p => isContainer(p) && isIndexable(p, branches))
-  const indexable = pages.filter(p => isIndexable(p, branches) && !isContainer(p))
+  const indexable = pages.filter(
+    p => isIndexable(p, branches) && !isContainer(p) && (!branch || isAtOrUnder(p.route, branch))
+  )
 
   // Nearest container ancestor = the longest container route the page sits under.
   const groupFor = page => {
     let best = null
     for (const container of containers) {
       if (container.route === page.route) continue
+      // In a branch index the branch container is the document's own subject —
+      // its title is already the H1 — so it must not also become a `## ` group.
+      // Its direct children belong in the leading unheaded group instead.
+      if (branch && container.route === branch) continue
       if (!isAtOrUnder(page.route, container.route)) continue
       if (!best || container.route.length > best.route.length) best = container
     }

package/src/site-index.js

@@ -30,18 +30,30 @@ const ROOT_GROUP_TITLE = 'Pages'
  * @param {string} [options.description] - Override the site summary
  * @param {string} [options.rootGroupTitle] - Heading for ungrouped pages
  * @param {number} [options.maxDescriptionChars=200]
+ * @param {string} [options.branch] - Scope to one route subtree (a branch index).
+ *   Title and summary then come from that branch's container page. The document
+ *   is otherwise identical, so one renderer serves both — see
+ *   {@link selectIndexBranches} for why a branch index is additive rather than a
+ *   delegation.
  * @returns {string} The index document
  */
 export function renderSiteIndex(siteContent, options = {}) {
   const config = siteContent?.config || {}
+  const { branch = null } = options
+
+  // A branch index is titled by its container, not by the site.
+  const branchPage = branch
+    ? (siteContent?.pages || []).find(page => page.route === branch)
+    : null
+
   const {
     baseUrl = config.seo?.baseUrl || '',
     basePath = '',
     locale = config.activeLocale,
     defaultLocale,
     exclude = [],
-    title = config.title || config.name || 'Site',
-    description = config.description || '',
+    title = branchPage?.title || branchPage?.label || config.title || config.name || 'Site',
+    description = branchPage?.description || (branch ? '' : config.description || ''),
     rootGroupTitle = ROOT_GROUP_TITLE,
     maxDescriptionChars = 200,
   } = options
@@ -60,7 +72,7 @@ export function renderSiteIndex(siteContent, options = {}) {
     lines.push('', ...blockquote(description))
   }
 
-  const groups = groupPagesForIndex(siteContent?.pages, { exclude })
+  const groups = groupPagesForIndex(siteContent?.pages, { exclude, branch })
 
   for (const group of groups) {
     const entries = group.pages