uniweb 0.9.3 → 0.9.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.9.3",
+  "version": "0.9.5",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -42,11 +42,11 @@
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
     "@uniweb/core": "0.6.1",
-    "@uniweb/runtime": "0.7.3",
-    "@uniweb/kit": "0.8.1"
+    "@uniweb/runtime": "0.7.4",
+    "@uniweb/kit": "0.8.2"
   },
   "peerDependencies": {
-    "@uniweb/build": "0.9.3",
+    "@uniweb/build": "0.9.4",
     "@uniweb/content-reader": "1.1.4",
     "@uniweb/semantic-parser": "1.1.9"
   },

package/partials/agents.md

@@ -529,6 +529,44 @@ For the rare case where children should be independent sections with their own t
 
 **Data and child blocks:** Page-level `data:` is available to all blocks on the page, including children. Each child block resolves data independently through the same page → site hierarchy. If a child component needs data, declare it in the child's `meta.js` or in the child section's frontmatter (`data: articles`).
 
+### Dividers — Content Boundaries
+
+The `---` (horizontal rule) in markdown creates a boundary between content regions. The developer decides what each region means. Two patterns:
+
+**Data-driven iteration (Loom).** Dividers separate header/body/footer in a repeated template. The content handler splits *before* Loom runs because each segment gets a different variable context — the body template contains item-level fields that don't exist on the top-level data. The header and footer are instantiated once against the full data; the body is repeated per data item.
+
+```markdown
+---
+type: CvEntry
+source: education
+---
+# Education
+{COUNT OF education} degrees.
+---
+## {degree}
+{institution} — {field} ({start}–{end})
+```
+
+The `source` frontmatter param names the data array to iterate. The content handler (see "Content Handlers" below) reads it. A second `---` starts a footer, rendered once after all items.
+
+**UI regions (component).** Dividers separate structural areas that the component renders differently — e.g., lesson prose vs challenge content. `splitContent()` from `@uniweb/kit` splits the parsed content at divider elements in the sequence:
+
+```jsx
+import { splitContent } from '@uniweb/kit'
+
+function Lesson({ content, block }) {
+  const [lesson, challenge] = splitContent(content)
+  return (
+    <div>
+      <Prose content={lesson} block={block} />
+      <aside><Prose content={challenge} block={block} /></aside>
+    </div>
+  )
+}
+```
+
+**When to use which:** Different data contexts per region → Loom pre-parse split (handled by the content handler). Same data, different UI treatment → kit post-parse split (`splitContent`). A foundation can use both — Loom splits and iterates to produce final content, then the component splits the result to route regions to different UI.
+
 ### Section Backgrounds
 
 Set `background` in frontmatter — the runtime renders it automatically:
@@ -825,7 +863,7 @@ function MyComponent({ content, params, block }) {
 }
 ```
 
-All non-reserved frontmatter fields become `params`. Reserved: `type`, `preset`, `input`, `data`, `id`, `background`, `theme`. Everything else flows to the component.
+All non-reserved frontmatter fields become `params`. Reserved: `type`, `preset`, `input`, `data`, `id`, `background`, `theme`, `source`, `where`. Everything else flows to the component.
 
 ### block properties
 
@@ -1386,6 +1424,92 @@ Named subdirectories are self-contained — no inheritance. Layout cascade: `pag
 
 ---
 
+## Content Handlers
+
+Content handlers are a transform layer that runs between data assembly and the component. They're declared in `foundation.js` and apply to every section in the foundation. The standard content shape (title, paragraphs, items, sequence) is the default — handlers can reshape it.
+
+### The three hooks
+
+The foundation declares handlers as an object in its default export:
+
+```js
+// foundation.js
+export default {
+  handlers: {
+    data:    (data, block) => { /* ... */ },
+    content: (data, block) => { /* ... */ },
+    props:   (content, params, block) => { /* ... */ },
+  },
+}
+```
+
+All three are optional. Each runs per block and is error-isolated (a failing handler logs a warning and falls back to the default behavior).
+
+| Handler | When it runs | Receives | Returns | Purpose |
+|---|---|---|---|---|
+| `data` | After data assembly, before content transform | `(data, block)` | New data object, or null | Filter, reshape, or augment the assembled data |
+| `content` | After data handler | `(data, block)` | ProseMirror document, or null | Transform raw content (Loom instantiation, template expansion) |
+| `props` | After parsing, defaults, and guarantees | `(content, params, block)` | `{ content, params }`, or null | Post-process the final shape before the component sees it |
+
+### Loom integration
+
+The most common use of content handlers is Loom-based content instantiation — resolving `{placeholder}` expressions in markdown against live data. `@uniweb/loom` provides a factory that creates the handler for you:
+
+```js
+import { createLoomHandlers } from '@uniweb/loom'
+
+export default {
+  handlers: createLoomHandlers({
+    vars: (data) => data?.profile?.[0],
+  }),
+}
+```
+
+The `vars` function extracts the Loom variable namespace from the assembled data. The factory returns a `content` handler that reads the `source` and `where` frontmatter params — without `source`, the handler does simple substitution; with `source`, the handler splits the markdown at `---` dividers and repeats the body per data item (see "Dividers — Content Boundaries" above). When `where` is also set, the source array is filtered first — only items where the expression evaluates to truthy are iterated:
+
+```yaml
+---
+type: PublicationList
+source: publications
+where: "type = 'book'"
+---
+```
+
+`where` expressions use Loom Plain form: `type = 'book'` (equality), `year > 1870` (comparison), `refereed` (truthy check), `type = 'book' AND refereed` (boolean combination). Aggregate expressions in the header (like `{COUNT OF publications}`) reflect the filtered set.
+
+### Writing a custom handler
+
+When the factory doesn't cover your case, write handlers directly:
+
+```js
+import { Loom, instantiateContent, instantiateRepeated } from '@uniweb/loom'
+
+const loom = new Loom()
+
+export default {
+  handlers: {
+    content: (data, block) => {
+      const profile = data?.profile?.[0]
+      if (!profile) return null
+
+      const doc = block.rawContent?.doc ?? block.rawContent
+      const source = block.properties?.source
+
+      if (!source) return instantiateContent(doc, loom, profile)
+      return instantiateRepeated(doc, loom, profile, source)
+    },
+  },
+}
+```
+
+The content handler receives `block.parsedContent.data` and reads raw ProseMirror from `block.rawContent`. It returns a new ProseMirror document — the framework re-parses it through the semantic parser. Returning `null` or the same reference as `block.rawContent` signals no change.
+
+### Reserved frontmatter fields
+
+`source` and `where` are convention-level reserved fields — they flow through to both `block.properties` (for handler access) and `params` (visible to components). Components can ignore them. This is consistent with how `background` and `theme` work. List them in `meta.js` params with descriptions so the editor and schema recognize them.
+
+---
+
 ## Migrating From Other Frameworks
 
 Don't port line-by-line. Study the source, then rebuild from first principles. Other frameworks produce far more components than Uniweb needs — expect consolidation, not 1:1 correspondence.

package/src/framework-index.json

@@ -0,0 +1,203 @@
+{
+  "schemaVersion": 1,
+  "generatedAt": "2026-04-16T16:24:12.713Z",
+  "packages": {
+    "@uniweb/build": {
+      "version": "0.9.4",
+      "path": "framework/build",
+      "deps": [
+        "@uniweb/content-reader",
+        "@uniweb/core",
+        "@uniweb/runtime",
+        "@uniweb/schemas",
+        "@uniweb/theming"
+      ]
+    },
+    "@uniweb/content-reader": {
+      "version": "1.1.4",
+      "path": "framework/content-reader",
+      "deps": []
+    },
+    "@uniweb/content-writer": {
+      "version": "0.2.3",
+      "path": "framework/content-writer",
+      "deps": []
+    },
+    "@uniweb/core": {
+      "version": "0.6.1",
+      "path": "framework/core",
+      "deps": [
+        "@uniweb/semantic-parser",
+        "@uniweb/theming"
+      ]
+    },
+    "@uniweb/frame-bridge": {
+      "version": "0.2.3",
+      "path": "framework/frame-bridge",
+      "deps": []
+    },
+    "@uniweb/icons": {
+      "version": "0.1.0",
+      "path": "framework/icons",
+      "deps": []
+    },
+    "@uniweb/kit": {
+      "version": "0.8.2",
+      "path": "framework/kit",
+      "deps": [
+        "@uniweb/core"
+      ]
+    },
+    "@uniweb/loom": {
+      "version": "0.2.2",
+      "path": "framework/loom",
+      "deps": []
+    },
+    "@uniweb/press": {
+      "version": "0.2.3",
+      "path": "framework/press",
+      "deps": []
+    },
+    "@uniweb/runtime": {
+      "version": "0.7.4",
+      "path": "framework/runtime",
+      "deps": [
+        "@uniweb/core",
+        "@uniweb/theming"
+      ]
+    },
+    "@uniweb/schemas": {
+      "version": "0.2.1",
+      "path": "framework/schemas",
+      "deps": []
+    },
+    "@uniweb/scholar": {
+      "version": "0.2.1",
+      "path": "framework/scholar",
+      "deps": []
+    },
+    "@uniweb/semantic-parser": {
+      "version": "1.1.9",
+      "path": "framework/semantic-parser",
+      "deps": []
+    },
+    "@uniweb/templates": {
+      "version": "0.7.26",
+      "path": "framework/templates",
+      "deps": []
+    },
+    "@uniweb/theming": {
+      "version": "0.1.3",
+      "path": "framework/theming",
+      "deps": []
+    }
+  },
+  "templates": {
+    "marketing": {
+      "name": "Marketing Starter",
+      "description": "Landing pages and marketing sites with Tailwind CSS v4",
+      "tags": [
+        "marketing",
+        "landing-page",
+        "tailwind"
+      ]
+    },
+    "academic": {
+      "name": "Academic",
+      "description": "Academic sites for researchers, labs, and departments",
+      "tags": [
+        "academic",
+        "research",
+        "portfolio"
+      ]
+    },
+    "docs": {
+      "name": "Documentation",
+      "description": "Documentation sites with navigation levels",
+      "tags": [
+        "docs",
+        "documentation",
+        "technical"
+      ]
+    },
+    "international": {
+      "name": "International Business",
+      "description": "Multilingual corporate website with English, Spanish, and French",
+      "tags": [
+        "i18n",
+        "multilingual",
+        "corporate",
+        "business",
+        "localization"
+      ]
+    },
+    "dynamic": {
+      "name": "Dynamic Data",
+      "description": "Live API data fetching with loading states, transforms, and the portable data pattern",
+      "tags": [
+        "data",
+        "api",
+        "fetch",
+        "loading-states",
+        "dynamic"
+      ]
+    },
+    "store": {
+      "name": "Solis Artisans - Store",
+      "description": "Artisan e-commerce with product collections, Shopify Buy Button, journal blog, and stone-amber design",
+      "tags": [
+        "store",
+        "e-commerce",
+        "shopify",
+        "artisan",
+        "products"
+      ]
+    },
+    "learning": {
+      "name": "Learning Platform",
+      "description": "Course-based learning site with quizzes, code challenges, and AI grading integration",
+      "tags": [
+        "learning",
+        "course",
+        "education",
+        "quiz",
+        "lms",
+        "tutorial"
+      ]
+    },
+    "extensions": {
+      "name": "Extensions Demo",
+      "description": "Primary foundation with a visual effects extension, demonstrating multi-foundation sites",
+      "tags": [
+        "extensions",
+        "multi-foundation",
+        "visual-effects",
+        "runtime"
+      ]
+    },
+    "cv": {
+      "name": "CV (Docusite)",
+      "description": "An academic CV as a docusite — a URL whose content is also a downloadable Microsoft Word document. Ships with a full Charles Darwin sample CV and demonstrates the one-foundation-many-tenants pattern for download-time theming.",
+      "tags": [
+        "cv",
+        "resume",
+        "docusite",
+        "academic",
+        "document",
+        "press"
+      ]
+    },
+    "cv-loom": {
+      "name": "CV (Loom-instantiated)",
+      "description": "A single-page narrative CV whose prose is written with {placeholder} expressions and instantiated at render time via the foundation content handler and @uniweb/loom. Reference implementation of the handler hook.",
+      "tags": [
+        "cv",
+        "loom",
+        "template-engine",
+        "content-handler",
+        "dynamic-prose",
+        "academic"
+      ]
+    }
+  }
+}

package/src/templates/resolver.js

@@ -23,10 +23,12 @@ export const BUILTIN_TEMPLATES = ['blank', 'starter', 'none']
  *    `node scripts/framework/sandbox.js create`.
  *
  * 2. **Published CLI (npm-installed)** — the monorepo isn't on disk, so
- *    we read a vendored snapshot file (`./official-templates.snapshot.json`)
- *    that the publish script rewrites from the workspace manifest just
- *    before `pnpm publish` runs. The snapshot is committed so every CLI
- *    version in git carries the template list it shipped with.
+ *    we read the vendored framework index at `../framework-index.json`,
+ *    which the publish pipeline's pre-publish hook rewrites just before
+ *    `pnpm publish` runs. The framework index is a single snapshot file
+ *    that also carries `@uniweb/*` package versions (consumed by
+ *    versions.js), so both the template list and the version resolver
+ *    share one source of truth.
  *
  * When both sources are available (local dev with a committed snapshot),
  * the live workspace manifest wins so newly-added templates are visible
@@ -34,43 +36,46 @@ export const BUILTIN_TEMPLATES = ['blank', 'starter', 'none']
  *
  * The previous implementation hardcoded a string array here, which
  * silently duplicated `framework/templates/manifest.json` and required
- * a two-repo edit whenever a template was added.
+ * a two-repo edit whenever a template was added. The one before THAT
+ * (v0.9.3) used a separate `./official-templates.snapshot.json` file;
+ * it has been retired in favor of the shared framework index.
  */
 function loadOfficialTemplateList() {
   // Local dev: framework/templates/manifest.json relative to this file
   // at framework/cli/src/templates/resolver.js
   const workspaceManifest = join(__dirname, '..', '..', '..', 'templates', 'manifest.json')
-  const picked = tryReadManifest(workspaceManifest)
+  const picked = tryReadTemplateKeys(workspaceManifest)
   if (picked) return picked
 
-  // Published CLI fallback: vendored snapshot next to this file
-  const snapshotPath = join(__dirname, 'official-templates.snapshot.json')
-  const snapshot = tryReadManifest(snapshotPath)
-  if (snapshot) return snapshot
+  // Published CLI fallback: the framework index snapshot, one directory
+  // up at framework/cli/src/framework-index.json.
+  const indexPath = join(__dirname, '..', 'framework-index.json')
+  const fromIndex = tryReadTemplateKeys(indexPath)
+  if (fromIndex) return fromIndex
 
-  // If both fail, return an empty list rather than a stale hardcoded
-  // array. An unknown template name then falls through to the npm
-  // `@uniweb/template-<name>` lookup path, which is the intended
-  // behavior for third-party templates.
+  // If both sources fail, return an empty list rather than a stale
+  // hardcoded array. An unknown template name then falls through to
+  // the npm `@uniweb/template-<name>` lookup path, which is the
+  // intended behavior for third-party templates.
   return []
 }
 
-function tryReadManifest(path) {
+function tryReadTemplateKeys(path) {
   try {
     if (!statSync(path).isFile()) return null
-    const manifest = JSON.parse(readFileSync(path, 'utf8'))
-    if (manifest && manifest.templates && typeof manifest.templates === 'object') {
-      return Object.keys(manifest.templates)
+    const data = JSON.parse(readFileSync(path, 'utf8'))
+    if (data && data.templates && typeof data.templates === 'object') {
+      return Object.keys(data.templates)
     }
   } catch {}
   return null
 }
 
 // Official templates from the templates repo. Derived from manifest.json
-// at module load time — see loadOfficialTemplateList() for the two source
-// paths (local workspace vs. vendored snapshot). If the list needs to
-// reflect a just-added template, restart the CLI process or rerun the
-// scaffolder; this constant is read once per process.
+// (local dev) or framework-index.json (published CLI) at module load
+// time — see loadOfficialTemplateList() for details. If the list needs
+// to reflect a just-added template, restart the CLI process or rerun
+// the scaffolder; this constant is read once per process.
 export const OFFICIAL_TEMPLATES = loadOfficialTemplateList()
 
 /**

package/src/versions.js

@@ -96,12 +96,61 @@ function readWorkspaceVersion(packageName) {
   return null
 }
 
+/**
+ * Load the vendored framework index file (see
+ * `./framework-index.json`). The index is a snapshot of the framework
+ * state taken at CLI publish time — every `@uniweb/*` package name,
+ * version, path, and inter-package dep edges, plus the template list.
+ *
+ * The snapshot is the only way a published CLI (running from
+ * `node_modules/uniweb/…`, with no workspace on disk) can resolve
+ * versions for packages it doesn't directly import (press, loom,
+ * scholar, etc.). Without it, Handlebars helpers like
+ * `{{version "@uniweb/press"}}` fall through to a bogus default.
+ *
+ * Returns null if the file doesn't exist, is unparseable, or has a
+ * schema version we don't understand. Callers treat null as "no
+ * snapshot available" and fall back to their next source.
+ */
+function loadFrameworkIndex() {
+  const indexPath = join(__dirname, 'framework-index.json')
+  try {
+    const raw = readFileSync(indexPath, 'utf8')
+    const parsed = JSON.parse(raw)
+    if (parsed && parsed.schemaVersion === 1 && parsed.packages) {
+      return parsed
+    }
+  } catch {}
+  return null
+}
+
+/**
+ * Pull `@uniweb/*` package versions out of the framework index's
+ * `packages` field and format them as caret ranges. Used as the
+ * published-CLI fallback source after the CLI's own deps and the live
+ * workspace walk both come up empty.
+ */
+function readIndexPackages() {
+  const index = loadFrameworkIndex()
+  if (!index) return {}
+  const result = {}
+  for (const [name, entry] of Object.entries(index.packages)) {
+    if (entry && entry.version) {
+      result[name] = `^${entry.version}`
+    }
+  }
+  return result
+}
+
 /**
  * Enumerate every `@uniweb/*` package under `framework/*` and return a
  * map of `{ name: '^version' }`. Used to seed the resolved-versions
  * cache so that packages not explicitly listed in the CLI's own deps
  * (press, loom, scholar, schemas, etc.) still have a version available
  * to templates that reference them.
+ *
+ * Works only in the monorepo. Published CLIs fall through to the
+ * framework-index snapshot via readIndexPackages() instead.
  */
 function discoverWorkspacePackages() {
   const root = getFrameworkRoot()
@@ -145,17 +194,23 @@ function resolveVersionSpec(spec, packageName) {
  * Get resolved versions for @uniweb/* packages.
  *
  * Priority (highest first):
+ *
  *   1. A concrete version spec already in the CLI's own `package.json`
- *      (the state after an npm publish: `workspace:*` is resolved to a
- *      real version).
- *   2. The on-disk version of the matching workspace package (the state
- *      during local development).
- *   3. Discovery fallback — every `@uniweb/*` package found under
- *      `framework/*`, for packages that aren't in the CLI's own deps.
+ *      (the state after an npm publish: `workspace:*` is resolved by
+ *      pnpm to a real version).
+ *   2. Live workspace walk — every `@uniweb/*` package found under
+ *      `framework/*` at CLI invocation time. This is the path that
+ *      matters for local dev: a freshly-added package becomes
+ *      reachable from every locally-run CLI without republishing.
+ *   3. Framework index snapshot — `./framework-index.json`, written by
+ *      the publish pipeline's pre-publish hook. This is the path that
+ *      matters for published CLIs: the monorepo isn't on disk, so the
+ *      snapshot is how the CLI knows about packages it doesn't import
+ *      directly (press, loom, scholar, schemas, …).
  *
- * The return shape is stable across both paths: a map of package names to
- * npm-compatible version specs, plus the CLI's own version under the key
- * `uniweb`.
+ * The return shape is stable across all paths: a map of package names
+ * to npm-compatible version specs, plus the CLI's own version under
+ * the key `uniweb`.
  *
  * @returns {Object} Map of package names to version specs
  */
@@ -173,14 +228,24 @@ export function getResolvedVersions() {
     if (resolved) result[name] = resolved
   }
 
-  // Merge in anything under framework/* that the CLI didn't list explicitly.
-  // A newly-added package (e.g. @uniweb/press) becomes reachable via
-  // {{version "@uniweb/press"}} without touching the CLI's package.json.
+  // Layer in the live workspace walk. Overrides nothing (dev versions
+  // are fresher than anything in the CLI's own deps), but fills in
+  // packages the CLI doesn't reference directly.
   const discovered = discoverWorkspacePackages()
   for (const [name, version] of Object.entries(discovered)) {
     if (!result[name]) result[name] = version
   }
 
+  // Final fallback: the vendored framework index snapshot. Only hits
+  // when the workspace walk came up empty for a package (published
+  // CLI running outside the monorepo). The snapshot is refreshed at
+  // publish time, so its view of the world is current as of the CLI's
+  // own publish.
+  const indexed = readIndexPackages()
+  for (const [name, version] of Object.entries(indexed)) {
+    if (!result[name]) result[name] = version
+  }
+
   // CLI itself. Caret on the current version — templates referencing
   // `{{version "uniweb"}}` pick up whatever patch/minor ships in the
   // same publish cycle as the template.

package/src/templates/official-templates.snapshot.json

@@ -1,50 +0,0 @@
-{
-  "version": "1.0.0",
-  "templates": {
-    "marketing": {
-      "name": "Marketing Starter",
-      "description": "Landing pages and marketing sites with Tailwind CSS v4",
-      "tags": ["marketing", "landing-page", "tailwind"]
-    },
-    "academic": {
-      "name": "Academic",
-      "description": "Academic sites for researchers, labs, and departments",
-      "tags": ["academic", "research", "portfolio"]
-    },
-    "docs": {
-      "name": "Documentation",
-      "description": "Documentation sites with navigation levels",
-      "tags": ["docs", "documentation", "technical"]
-    },
-    "international": {
-      "name": "International Business",
-      "description": "Multilingual corporate website with English, Spanish, and French",
-      "tags": ["i18n", "multilingual", "corporate", "business", "localization"]
-    },
-    "dynamic": {
-      "name": "Dynamic Data",
-      "description": "Live API data fetching with loading states, transforms, and the portable data pattern",
-      "tags": ["data", "api", "fetch", "loading-states", "dynamic"]
-    },
-    "store": {
-      "name": "Solis Artisans - Store",
-      "description": "Artisan e-commerce with product collections, Shopify Buy Button, journal blog, and stone-amber design",
-      "tags": ["store", "e-commerce", "shopify", "artisan", "products"]
-    },
-    "learning": {
-      "name": "Learning Platform",
-      "description": "Course-based learning site with quizzes, code challenges, and AI grading integration",
-      "tags": ["learning", "course", "education", "quiz", "lms", "tutorial"]
-    },
-    "extensions": {
-      "name": "Extensions Demo",
-      "description": "Primary foundation with a visual effects extension, demonstrating multi-foundation sites",
-      "tags": ["extensions", "multi-foundation", "visual-effects", "runtime"]
-    },
-    "cv": {
-      "name": "CV (Docusite)",
-      "description": "An academic CV as a docusite — a URL whose content is also a downloadable Microsoft Word document. Ships with a full Charles Darwin sample CV and demonstrates the one-foundation-many-tenants pattern for download-time theming.",
-      "tags": ["cv", "resume", "docusite", "academic", "document", "press"]
-    }
-  }
-}