@uniweb/projections 0.1.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,181 @@
+# @uniweb/projections
+
+Artifacts derived from a Uniweb site's **content alone** — no foundation, no
+runtime, nothing rendered.
+
+A Uniweb site is content; a foundation is code; the runtime orchestrates them.
+Producing HTML needs all three. The artifacts in this package need only the
+first, which is what makes them identical in every context — browser SPA,
+prerender, edge SSR, desktop, `unipress` — and stable when the foundation or
+the runtime changes.
+
+```bash
+npm install @uniweb/projections
+```
+
+> **Most projects never import this directly.** `uniweb build` and `uniweb dev`
+> emit these artifacts for you. Reach for the package when you are building a
+> tool that consumes a site's content outside the normal build — a custom
+> publisher, an analysis pass, an alternate host.
+
+## What it produces
+
+| Artifact | For | Built from |
+|---|---|---|
+| `llms.txt` | agents — discovery | the page graph + each page's first paragraph |
+| `/{route}.md` | agents — retrieval | `section.content` via `@uniweb/content-writer` |
+| search index | site search | the same page graph |
+
+### The index
+
+Follows the [`llms.txt`](https://llmstxt.org) convention — an H1 title, a
+blockquote summary, and `##` groups of annotated links:
+
+```markdown
+# Uniweb
+
+> Component content architecture — a framework where content authors and
+> component developers can't break each other's work.
+
+## Getting Started
+
+- [Quickstart](https://example.com/docs/getting-started/quickstart.md): Create your first Uniweb site in 5 minutes.
+
+## Authoring
+
+- [Working with Collections](https://example.com/docs/authoring/collections.md): Collections let you manage repeating content — blog posts, team members, products — as a set of files.
+```
+
+Two properties are what make this worth having over a sitemap:
+
+- **Links point at the `.md` projection**, not the HTML page, so following an
+  entry is one hop rather than fetch-then-strip.
+- **Descriptions never require an author to have written anything.** The chain
+  is `page.yml::description` → `seo.ogDescription` → the first paragraph of the
+  first section that has prose, as clean plain text. Grouping is taken from the
+  page graph: content-less container folders become the `##` headings.
+
+### The per-page markdown
+
+Section bodies in page order, serialized from the stored ProseMirror document.
+No frontmatter, no section `type`, no params — `type` names which component
+renders a section, which is a *rendering* assignment and foundation-specific.
+Emitting it would break the property this package exists for: the output is a
+projection of the **site**, identical under a swapped foundation.
+
+The output carries Uniweb dialect (`![](lu-house)` icons,
+`![desc](@Component){params}` insets). That is what the author wrote, and it is
+more informative to an agent working on a Uniweb site than a lossy translation
+to plain CommonMark would be.
+
+## Configuration
+
+Sites configure this under `agents:` in `site.yml`. Free, and on by default:
+
+```yaml
+agents:
+  index: true          # emit llms.txt              (default true)
+  markdown: true       # emit per-page .md          (default true)
+  exclude: [/internal] # additional route exclusions
+```
+
+`agents: false` turns the whole capability off in one word.
+
+Pages are excluded when they set `seo.noindex` or `hidden`, when a route
+segment starts with `_`, when the route is a dynamic template (`/blog/:slug`),
+or when an `exclude` prefix covers them. `noindex`/`hidden` on a *content-less
+container* hides its whole branch, since a container is pure structure and
+suppressing only the heading would orphan its children.
+
+These exclusions are load-bearing rather than tidy-up. An index is *more*
+revealing than a sitemap because it describes pages rather than listing them:
+an unlinked page becomes discoverable **and** summarized. Weakening them turns
+the on-by-default into a leak.
+
+## Usage
+
+```js
+import { renderSiteIndex, renderPageMarkdown } from '@uniweb/projections'
+
+const index = renderSiteIndex(siteContent, { baseUrl: 'https://example.com' })
+const markdown = renderPageMarkdown(siteContent.pages[0])
+```
+
+### API
+
+**Rendering**
+
+| Export | Signature |
+|---|---|
+| `renderSiteIndex` | `(siteContent, options?) → string` |
+| `renderPageMarkdown` | `(page, { includeChildren = true }?) → string` |
+| `resolvePageDescription` | `(page, { maxChars = 200 }?) → string` |
+
+`renderSiteIndex` options: `baseUrl`, `basePath`, `locale`, `defaultLocale`,
+`exclude`, `title`, `description`, `rootGroupTitle`, `maxDescriptionChars`.
+Links are absolute when `baseUrl` is known and root-relative otherwise — a
+root-relative link still resolves for an agent that arrived via the index.
+
+**Page graph** — `selectIndexablePages`, `groupPagesForIndex`, `buildPageUrl`,
+`applyRouteTranslation`, `isContainer`, `isDynamicTemplate`.
+
+**Config and filenames** — `resolveAgentsConfig`, `pageMarkdownFilename`,
+`INDEX_FILENAME`.
+
+The internal vocabulary is *projections*. `llms.txt` is one emitter's filename —
+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`.
+
+```js
+import { generateSearchIndex, isSearchEnabled } from '@uniweb/projections/search'
+
+if (isSearchEnabled(siteContent)) {
+  const index = generateSearchIndex(siteContent, { locale: 'en' })
+}
+```
+
+Search extraction lives here rather than in `@uniweb/build` so that one
+implementation serves every publisher. `@uniweb/build` re-exports this module,
+so existing call sites are unchanged.
+
+## Localization
+
+The default locale's artifacts sit at the output root; other locales go under
+`/{locale}/`, mirroring the search index's established pattern. Pass `locale`
+and `defaultLocale` to `renderSiteIndex` and it builds locale-correct URLs,
+including translated route segments from `config.i18n.routeTranslations` — the
+same rule the sitemap uses, so the two can never disagree about where a
+localized page lives.
+
+## Environment contract
+
+**Runs anywhere JS runs.** No `node:*`, no bundler, no DOM, no filesystem —
+enforced by `tests/environment.test.js`, which walks the real import graph.
+
+This is the package's reason to exist rather than a nicety. A Uniweb project is
+dual-published: the CLI and the app are both JavaScript clients of one backend,
+and either may be the publisher. An artifact derived from site content has to
+come out identical whichever side published, or a deployed site's artifacts
+oscillate — and an index that exists after one publish and vanishes after
+another is worse than none, because agents are told to rely on it. One
+implementation, imported by both publishers; the backend stores and serves
+opaque bytes and generates nothing.
+
+The same contract is why `search/generate.js` imports the leaf subpath
+`@uniweb/core/locale-config` rather than the bare `@uniweb/core` entry, whose
+package root pulls in heavier dependencies. The environment test forbids the
+bare entry, so the trap cannot be re-entered.
+
+## Development
+
+```bash
+pnpm test    # vitest
+```
+
+## License
+
+Apache-2.0

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@uniweb/projections",
+  "version": "0.1.1",
+  "description": "Projections of a Uniweb site's content — agent index, per-page markdown, search index. Pure JS, runs anywhere.",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js",
+    "./search": "./src/search/index.js"
+  },
+  "files": [
+    "src"
+  ],
+  "keywords": [
+    "uniweb",
+    "projections",
+    "llms-txt",
+    "markdown",
+    "search"
+  ],
+  "author": "Proximify",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/uniweb/projections.git"
+  },
+  "homepage": "https://github.com/uniweb/projections#readme",
+  "bugs": {
+    "url": "https://github.com/uniweb/projections/issues"
+  },
+  "engines": {
+    "node": ">=20.19"
+  },
+  "dependencies": {
+    "@uniweb/core": "0.7.30",
+    "@uniweb/content-writer": "0.2.8"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.7",
+    "@uniweb/content-reader": "1.1.16"
+  },
+  "scripts": {
+    "test": "vitest run"
+  }
+}

package/src/config.js

@@ -0,0 +1,77 @@
+/**
+ * @fileoverview Config surface and output filenames.
+ *
+ * The internal vocabulary is *projections*. `llms.txt` is one emitter's
+ * filename — a third-party convention that may not survive — so it appears
+ * exactly once, here, at the edge. A change of convention costs a constant.
+ */
+
+/** Filename of the agent index within a locale's output root. */
+export const INDEX_FILENAME = 'llms.txt'
+
+/** Defaults for the `agents:` block. Free capability, on by default.  */
+const DEFAULTS = { index: true, markdown: true, exclude: [] }
+
+/**
+ * Read the site's `agents:` block.
+ *
+ * Deliberately NOT `features:` — that list is the billing-intent declaration
+ * paired with a server-side entitlement gate, and projections are free. A
+ * free capability in that list would blur what `features:` means for
+ * everything else in it.
+ *
+ * @param {Object} [siteConfig] - `siteContent.config`
+ * @returns {{index: boolean, markdown: boolean, exclude: string[]}}
+ */
+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 || typeof agents !== 'object') return { ...DEFAULTS }
+
+  return {
+    index: agents.index !== false,
+    markdown: agents.markdown !== false,
+    exclude: normalizeExclude(agents.exclude),
+  }
+}
+
+/**
+ * Normalize `exclude:` to a list of leading-slash route prefixes.
+ *
+ * Exported because exclusions arrive two ways — from `site.yml`'s `agents:`
+ * block and as a direct option — and both have to be normalized or one path
+ * silently stops excluding.
+ *
+ * @param {*} value
+ * @returns {string[]}
+ */
+export function normalizeExclude(value) {
+  if (!value) return []
+  const list = Array.isArray(value) ? value : [value]
+  return list
+    .filter(v => typeof v === 'string' && v.trim())
+    .map(v => {
+      const trimmed = v.trim()
+      const withSlash = trimmed.startsWith('/') ? trimmed : `/${trimmed}`
+      // Strip a trailing slash so `/internal/` and `/internal` behave alike.
+      return withSlash.length > 1 ? withSlash.replace(/\/+$/, '') : withSlash
+    })
+}
+
+/**
+ * Output path of a page's markdown projection, relative to the locale root.
+ *
+ * 1:1 with the route, matching how `agents.md` names pages: the page at
+ * `/docs/authoring/collections` projects to `docs/authoring/collections.md`.
+ * The site root is `index.md` — `dist/index.html` is the page, `index.md` is
+ * free beside it.
+ *
+ * @param {string} route
+ * @returns {string}
+ */
+export function pageMarkdownFilename(route) {
+  if (!route || route === '/') return 'index.md'
+  return `${route.replace(/^\/+/, '').replace(/\/+$/, '')}.md`
+}

package/src/description.js

@@ -0,0 +1,57 @@
+/**
+ * @fileoverview One line describing a page, for the agent index.
+ *
+ * Discovery needs *meaning*, not just a URL — a bare list of links is what an
+ * agent could already get from a sitemap. The whole value of the index is
+ * that each entry says what the page is for.
+ *
+ * Never requires an author to have written anything: the docs corpus this was
+ * measured against has no frontmatter at all, so every description there comes
+ * from the derived path.
+ */
+
+import { docSummaryText } from '@uniweb/content-writer'
+
+/**
+ * Resolve a page's one-line description.
+ *
+ * Order: authored `page.yml::description` › authored SEO description ›
+ * the first paragraph of the page's first section.
+ *
+ * Note on the second step: the collected page carries `seo.ogDescription`
+ * (the Open Graph override), not a bare `seo.description` — `page.description`
+ * *is* the meta description, and it is already step one.
+ *
+ * @param {Object} page - A collected page
+ * @param {Object} [options]
+ * @param {number} [options.maxChars=200] - Soft bound on the derived summary
+ * @returns {string} A plain-text description, or '' when there is nothing
+ */
+export function resolvePageDescription(page, { maxChars = 200 } = {}) {
+  const authored = page?.description?.trim()
+  if (authored) return authored
+
+  const seoDescription = page?.seo?.ogDescription?.trim()
+  if (seoDescription) return seoDescription
+
+  return deriveDescription(page, { maxChars })
+}
+
+/**
+ * First paragraph of the first section that has one.
+ *
+ * Walks sections rather than reading only the first, so a page opening with a
+ * bare Hero (a title and nothing else) still gets a description from the
+ * section below it.
+ *
+ * @param {Object} page
+ * @param {Object} options
+ * @returns {string}
+ */
+function deriveDescription(page, { maxChars }) {
+  for (const section of page?.sections || []) {
+    const summary = docSummaryText(section?.content, { maxChars })
+    if (summary) return summary
+  }
+  return ''
+}

package/src/index.js

@@ -0,0 +1,53 @@
+/**
+ * @uniweb/projections — everything derived from the *site* ingredient alone.
+ *
+ * A Uniweb site is content; a foundation is code; the runtime orchestrates
+ * them. Rendering HTML needs all three. These artifacts need only the first,
+ * which is what makes them identical in every context — SPA, prerender,
+ * JIT-SSR isolate, desktop, `unipress` — and stable across foundation and
+ * runtime changes.
+ *
+ * **Environment contract: runs anywhere JS runs.** No `node:*`, no Vite, no
+ * DOM, no filesystem. That is not incidental; it is the package's reason to
+ * exist. A Uniweb project is dual-published — the CLI and the app are both
+ * JavaScript clients of one backend, and either may be the publisher. An
+ * artifact derived from site content must therefore be produced *identically*
+ * by whichever side publishes, or a deployed site's artifacts oscillate with
+ * the publisher. One implementation, imported by both; the backend stores and
+ * serves opaque bytes and generates nothing.
+ *
+ * The contract is enforced by a test (`tests/environment.test.js`), because a
+ * subpath export of a Node-flavored package is one careless import away from
+ * breaking a consumer it never sees.
+ *
+ * @module @uniweb/projections
+ */
+
+export { renderSiteIndex } from './site-index.js'
+export { renderPageMarkdown } from './markdown.js'
+export { resolvePageDescription } from './description.js'
+
+export {
+  INDEX_FILENAME,
+  pageMarkdownFilename,
+  resolveAgentsConfig,
+} from './config.js'
+
+export {
+  selectIndexablePages,
+  groupPagesForIndex,
+  buildPageUrl,
+  applyRouteTranslation,
+  isContainer,
+  isDynamicTemplate,
+} from './pages.js'
+
+export {
+  extractSearchContent,
+  generateSearchIndex,
+  mergeSearchIndexes,
+  generateCollectionIndex,
+  isSearchEnabled,
+  getSearchConfig,
+  getSearchIndexFilename,
+} from './search/index.js'

package/src/markdown.js

@@ -0,0 +1,69 @@
+/**
+ * @fileoverview The retrieval projection: one page as markdown.
+ *
+ * Retrieval needs *fidelity*, so this reads `section.content` — the stored
+ * ProseMirror document — through `content-writer`, rather than reconstructing
+ * prose from the semantic parser's flattened groups.
+ *
+ * What is deliberately absent: no frontmatter, no section `type`, no params.
+ * `type` names which component renders a section — a rendering assignment,
+ * and foundation-specific. Emitting it would break the property that makes
+ * this projection worth having: it is a projection of the *site* ingredient
+ * alone, identical under a swapped foundation.
+ *
+ * The output carries Uniweb dialect (`![](lu-house)` icons,
+ * `![desc](@Component){params}` insets). That is what the author wrote, and
+ * it is more informative for an agent working on a Uniweb site than a
+ * lossy translation to plain CommonMark would be.
+ */
+
+import { proseMirrorToMarkdown } from '@uniweb/content-writer'
+
+/**
+ * Render one page as markdown.
+ *
+ * @param {Object} page - A collected page (`siteContent.pages[n]`)
+ * @param {Object} [options]
+ * @param {boolean} [options.includeChildren=true] - Include nested sections
+ * @returns {string} Markdown, or '' when the page has no projectable content
+ */
+export function renderPageMarkdown(page, { includeChildren = true } = {}) {
+  const blocks = []
+
+  for (const section of page?.sections || []) {
+    collectSection(section, blocks, includeChildren)
+  }
+
+  return blocks.join('\n\n').trim()
+}
+
+/**
+ * Serialize one section, then its children in declared order.
+ *
+ * Child sections (`@`-prefixed files attached via `nest:`) are real authored
+ * content that happens to render inside a parent. Skipping them would drop
+ * body text an author wrote, which is exactly what retrieval is for.
+ *
+ * @param {Object} section
+ * @param {string[]} blocks
+ * @param {boolean} includeChildren
+ */
+function collectSection(section, blocks, includeChildren) {
+  const markdown = serializeSectionContent(section)
+  if (markdown) blocks.push(markdown)
+
+  if (!includeChildren) return
+  for (const child of section?.subsections || []) {
+    collectSection(child, blocks, includeChildren)
+  }
+}
+
+/**
+ * @param {Object} section
+ * @returns {string}
+ */
+function serializeSectionContent(section) {
+  const content = section?.content
+  if (!content?.content?.length) return ''
+  return proseMirrorToMarkdown(content).trim()
+}