uniweb 0.9.4 → 0.9.6

package/package.json

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

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

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-04-15T22:47:02.926Z",
+  "generatedAt": "2026-04-16T22:34:02.528Z",
   "packages": {
     "@uniweb/build": {
-      "version": "0.9.3",
+      "version": "0.9.4",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -42,24 +42,24 @@
       "deps": []
     },
     "@uniweb/kit": {
-      "version": "0.8.1",
+      "version": "0.8.2",
       "path": "framework/kit",
       "deps": [
         "@uniweb/core"
       ]
     },
     "@uniweb/loom": {
-      "version": "0.2.1",
+      "version": "0.2.2",
       "path": "framework/loom",
       "deps": []
     },
     "@uniweb/press": {
-      "version": "0.2.1",
+      "version": "0.2.4",
       "path": "framework/press",
       "deps": []
     },
     "@uniweb/runtime": {
-      "version": "0.7.3",
+      "version": "0.7.4",
       "path": "framework/runtime",
       "deps": [
         "@uniweb/core",
@@ -82,7 +82,7 @@
       "deps": []
     },
     "@uniweb/templates": {
-      "version": "0.7.23",
+      "version": "0.7.29",
       "path": "framework/templates",
       "deps": []
     },
@@ -175,18 +175,6 @@
         "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.",
@@ -198,6 +186,19 @@
         "dynamic-prose",
         "academic"
       ]
+    },
+    "monograph": {
+      "name": "Monograph (Press showcase)",
+      "description": "A richly illustrated long-form document — numbered chapters with nested subsections, figures with captions, data-driven specimen and measurement tables, and a citestyle bibliography. The same JSX drives the themed web preview and a branded .docx with headers, footers, and page numbers. Ships with Darwin's Galapagos observations as sample content.",
+      "tags": [
+        "monograph",
+        "docusite",
+        "press",
+        "document",
+        "figures",
+        "tables",
+        "bibliography"
+      ]
     }
   }
 }