uniweb 0.79.2 → 0.80.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.79.2",
+  "version": "0.80.0",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,17 +41,17 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/core": "^0.35.0",
-    "@uniweb/schemas": "^0.9.3",
-    "@uniweb/kit": "^0.19.11",
-    "@uniweb/runtime": "^0.28.3",
+    "@uniweb/runtime": "^0.28.4",
     "@uniweb/content-writer": "^0.3.4",
-    "@uniweb/semantic-parser": "^1.4.1"
+    "@uniweb/core": "^0.35.0",
+    "@uniweb/kit": "^0.19.13",
+    "@uniweb/schemas": "^0.10.0",
+    "@uniweb/semantic-parser": "^1.5.1"
   },
   "peerDependencies": {
-    "@uniweb/build": "^0.73.2",
+    "@uniweb/build": "^0.74.0",
     "@uniweb/content-reader": "^1.2.7",
-    "@uniweb/semantic-parser": "^1.4.1"
+    "@uniweb/semantic-parser": "^1.5.1"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md

@@ -366,6 +366,7 @@ content = {
   images: [],       // { src, alt, role, href }
   icons: [],        // { library, name, role }
   videos: [],       // { src, alt, role, poster, href }
+  documents: [],    // { url, alt, caption, role: 'pdf', preview?, author?, description? } — from {role=pdf}
   insets: [],       // Inline @Component references — { refId }
   lists: [],        // [[{ paragraphs, links, lists, … }]] — each item is an object, not a string
   quotes: [],       // Blockquotes
@@ -524,12 +525,13 @@ Optional attributes: `{size=20}`, `{color=red}`. Custom SVGs: `![Logo](./logo.sv
 ```markdown
 [text](url){target=_blank}              <!-- Open in new tab -->
 [text](./file.pdf){download}            <!-- Download -->
-![alt](./img.jpg){role=banner}          <!-- Role determines array: images, icons, or videos -->
+![alt](./img.jpg){role=banner}          <!-- Role determines array: images, icons, videos or documents -->
 ![alt](./demo.mp4){role=video}          <!-- → content.videos[], not content.images[] -->
+![alt](./report.pdf){role=pdf}          <!-- → content.documents[] — a file, drawn as a link -->
 ![alt](./img.jpg){href=/products}       <!-- Clickable media: href + target ride along -->
 ```
 
-Sizing and loading ride on the image: `{width=800 height=600 loading=lazy fit=cover position=center}`. A video adds `{poster=./thumb.jpg autoplay muted loop controls}`; a `{role=pdf}` document adds `{preview=./cover.jpg author=… description=…}`.
+Sizing and loading ride on the image: `{width=800 height=600 loading=lazy fit=cover position=center}`. A video adds `{poster=./thumb.jpg autoplay muted loop controls}`; a `{role=pdf}` document adds `{preview=./cover.jpg author=… description=…}` and arrives in `content.documents` — `{ url, name, mime, size?, alt, caption, … }` — declare it in `content:` as `documents`.
 
 **Quote values containing spaces:** `{note="Ready to go"}`, not `{note=Ready to go}` — unquoted values end at the first space.
 
@@ -1087,7 +1089,7 @@ Names only — for signatures and props, read the package: it's on disk at `node
 
 **Text:** `H1`–`H6`, `P`, `Span`, `Div`, `Text` (with `as`)
 **Content:** `Section`, `Prose`, `Article`, `Render` (ProseMirror → React), `ChildBlocks`, `splitContent()`
-**Media:** `Visual` (first non-empty: inset/video/image), `Image`, `Media`, `Icon`, `Asset`
+**Media:** `Visual` (a `content.media` item by its kind; or the first of inset/video/image), `Image`, `Media` (video), `Icon`, `Asset`
 **Navigation:** `Link`, `useActiveRoute()`, `useWebsite()`, `useRouting()`
 **Header/layout:** `useScrolled(threshold)`, `useMobileMenu()`, `useAppearance()`
 **Overlays:** `Overlay` (modals, palettes, drawers, toasts — portals out of the layout, contains focus; read the note below before hand-rolling one)
@@ -1098,7 +1100,7 @@ Names only — for signatures and props, read the package: it's on disk at `node
 @import "@uniweb/kit/prose-tokens.css";   /* the plugin, wired to theme.yml */
 ```
 
-Nothing to install — the import brings the plugin with it. **Skip the import and prose is completely unstyled**, silently: the class is there and no rules are behind it. `uniweb doctor` flags that. Use **one** `prose` container per subtree — the `--tw-prose-*` variables are inherited, so a nested one silently resets them and the outer container goes on looking correct. The section that renders the document is usually the better owner; a layout should supply column width and padding.
+Nothing to install — the import brings the plugin with it. **Skip the import and prose is completely unstyled** — lists lose their bullets and numbers, and text its typography — while the markup looks right. The foundation build warns about it, and `uniweb doctor` flags it. Use **one** `prose` container per subtree — the `--tw-prose-*` variables are inherited, so a nested one silently resets them and the outer container goes on looking correct. The section that renders the document is usually the better owner; a layout should supply column width and padding.
 
 **Documentation shells:** `useHeadings()` (the page's headings + the one being read, derived from content so it prerenders), `website.getBranchHierarchy({ route, for })` (the page tree for one branch). Kit ships no ready-made layout — a layout is your foundation's design; write it in `src/layouts/` and use these for the behaviour.
 **Layout helpers:** `useGridLayout(columns, { gap })`, `useAccordion({ multiple, defaultOpen })`
@@ -1160,21 +1162,23 @@ Header.as = 'header'
 export default {
   title: 'Feature Grid',
   description: 'Grid of feature cards with icons',
-  category: 'showcase',     // free-form editor grouping — nothing validates it.
-                            // impact / showcase / structure is a suggested set.
-                            // It names the kind of *component*, not the kind of
-                            // site: a genre like 'marketing' belongs to a template
-  purpose: 'Explain',       // free-form; a single verb reads well
+  family: 'features',       // the standard section type it is — the editor's
+                            // illustration and label (`uniweb families`). Optional;
+                            // a name like `Features` resolves on its own
   // hidden: true,          // Exclude from export entirely (internal helpers)
   // background: 'self',    // Component renders its own background
   // inset: true,           // Available for @ComponentName in markdown
-  // visuals: 1,            // Expects 1 visual
   // children: true,        // Accepts child sections
 
   content: {
     title: 'Section heading',
     paragraphs: 'Introduction [0-1]',
-    items: 'Feature cards with icon, title, description',
+    items: {
+      label: 'Feature cards [3-6]',
+      content: { icon: 'Icon [1]', title: 'Feature', paragraphs: 'Description' },  // one entry
+    },
+    // media: 'Photo, video or diagram [1]',  // an image, a video, or an embedded component
+    // sequence: 'Prose and media',           // renders content.sequence — the section as written
   },
 
   params: {
@@ -1195,6 +1199,13 @@ export default {
 
 **All defaults belong in `meta.js`, not inline in component code.** `meta.js` is also the catalog entry another agent reads to discover your section type (Part 2, step 2) — write `description` and `content:` for that reader.
 
+**`content:` names what the component reads**, each as a label for the author with an optional count (`'Cards [3-6]'`): `title`, `pretitle`, `subtitle`, `paragraphs`, `links`, `lists`, `items`, `media`, `icons`, `documents`, `snippets`, `tables`, `math`, `quotes`, `sequence`.
+
+- **`media` is an image, a video, or an embedded component.** `media: 'Hero media [1]'` takes any of the three; `media: { label, types: ['image'] }` narrows it; `image:`, `videos:` and `insets:` are the same slot narrowed to one type. Read it as `content.media` — the author's order, each item with its `kind` — and render it with `<Visual media={content.media} block={block} />`. Rendering the slot with `<Image>` drops a diagram an author placed there, and kit's `<Media>` is a video player.
+- **`sequence`** says the component renders `content.sequence` — the whole section as written, headline included. `{ label, except: ['table', 'math'] }` names the kinds it leaves out.
+- **`items: { label, content: { … } }`** says what each entry holds, in the same vocabulary.
+- The build warns on what it can't read, and refuses `visuals:` (declare `media`) and the `content:` element `data` (declare the block's tag in `data:`).
+
 > **`meta.js` is a user interface, not just metadata.** When a foundation is published, every `meta.js` is registered as the foundation's schema, and the visual editor builds its controls from it: the build generates a `schema.json` from every `meta.js` in the foundation, and the editor renders it: a `select` param with `options` becomes a dropdown, a `boolean` becomes a toggle, `label` and `description` become the words a non-technical author reads, and each entry in `presets` becomes a one-click choice. That's the real reason param naming matters — `variant: centered` and `renderMode: flex-center` aren't a style preference, they're the difference between a legible control and a baffling one. Write `meta.js` as though someone who will never see your code has to use it, because that's exactly who does.
 
 ### Two worlds: section types and your own components
@@ -1617,7 +1628,7 @@ Back up your database **before** running this. It is not reversible.
 
 That makes one distinction worth holding onto. You **may** declare a schema describing the form *definition's envelope* — `title`, `description`, `fields` as a map — and get build-time validation that an authored form is well-formed. What you can't declare is a schema whose fields are *the form's* fields (`name`, `email`, …); that's describing the visitor's answers, which arrive at runtime and belong to a form you've never seen. Declare the key either way — it is what delivers the block — and give it a schema only if you want it checked, and only of the envelope (`{}` declares the key with none).
 
-**Reading one in a component.** Declare the tag as a key (`data: { faq: {} }`), and `content.data[tag]` gives you both views: `items` for anything row-shaped (an accordion, a step list), `sequence` when you don't recognize the tag and want to render it faithfully in document order. Both are derived, so nothing is stored twice.
+**Reading one in a component.** Declare it the way the author writes the fence — `data: { 'md:faq': 'Questions and answers [3+]' }`. The value is the author's label (its count counts the entries), or `{ label, hint, content: { title: 'Question', paragraphs: 'Answer' } }` to say what each entry holds. The component still reads `content.data.faq`, which gives you both views: `items` for anything row-shaped (an accordion, a step list), `sequence` when you don't recognize the tag and want to render it faithfully in document order. Both are derived, so nothing is stored twice. (`faq: {}` also declares the key, saying nothing about the block.)
 
 ```jsx
 function Faq({ content }) {
@@ -1635,10 +1646,11 @@ function Faq({ content }) {
 ![Architecture overview](@NetworkDiagram){variant=compact}
 ```
 
-The developer builds `NetworkDiagram` as an ordinary React component with `inset: true` in `meta.js`. Kit's `<Visual>` renders the first non-empty candidate, so one section type works whether the author supplies an image, a video, or an interactive component:
+The developer builds `NetworkDiagram` as an ordinary React component with `inset: true` in `meta.js`. The section that hosts it declares a `media` slot, and kit's `<Visual>` renders the author's item by its kind — so one section type works whether the author supplies an image, a video, or an interactive component:
 
 ```jsx
-<Visual inset={block.insets[0]} video={content.videos[0]} image={content.images[0]} className="rounded-2xl" />
+// meta.js: content: { title: 'Headline', media: 'Illustration [1]' }
+<Visual media={content.media} block={block} className="rounded-2xl" />
 ```
 
 **Insets are full section types** — they receive `{ content, params, block }`. The alt text becomes `content.title` and attributes become `params`: `![npm create uniweb](@CommandBlock){note="Ready to go"}` → `content.title = "npm create uniweb"`, `params.note = "Ready to go"`.

package/src/commands/doctor.js

@@ -189,6 +189,24 @@ function loadSiteYml(dir) {
  * `node_modules` — this answers "did the developer write this", so a match
  * inside a dependency is the wrong answer.
  */
+/**
+ * Does this foundation render kit's <Prose> or <Article> — under its own name or an alias?
+ *
+ * The JSX tag alone missed `import { Article as ArticleBody } from '@uniweb/kit'`, which
+ * renders `<ArticleBody>`: two official templates shipped that way with no prose styles
+ * until 2026-09-29. So the import counts too. (The foundation build checks the same thing
+ * from its module graph, which no alias can hide from.)
+ *
+ * @param {string} dir - the foundation's source directory
+ * @returns {boolean}
+ */
+export function rendersKitProse(dir) {
+  return (
+    sourceMatches(dir, /<(Prose|Article)\b/) ||
+    sourceMatches(dir, /import\s*\{[^}]*\b(Prose|Article)\b[^}]*\}\s*from\s*['"]@uniweb\/kit['"]/)
+  )
+}
+
 function sourceMatches(dir, pattern) {
   let found = false
   forEachSourceFile(dir, (text) => {
@@ -1217,8 +1235,8 @@ export async function doctor(args = []) {
 
     // Does anything here actually ask for prose? Either the class in the
     // stylesheet, or kit's components, which render it.
+    const usesProseComponent = rendersKitProse(f.path)
     const usesProseClass = /(^|[\s"'`])prose(\s|["'`]|$)/m.test(styles)
-    const usesProseComponent = sourceMatches(f.path, /<(Prose|Article)\b/)
 
     if (!usesProseClass && !usesProseComponent) continue
 

package/src/commands/starter.js

@@ -90,6 +90,8 @@ export async function generateStarter({ name, sectionDir, preset, json, write })
   const metaPath = join(sectionDir, 'meta.js')
   const meta = existsSync(metaPath) ? await loadMeta(metaPath) : {}
   const result = starterContent({ name, ...meta }, { preset })
+  // What the declaration says that could not be read — the build warns the same way.
+  result.problems = describeContent({ name, ...meta }).problems
 
   const doc = buildDoc(result.content)
   const markdown = doc ? serializeSection(result.params, doc) : ''
@@ -157,11 +159,14 @@ export function reportStarter(result, { write } = {}) {
     console.log('')
     console.log(`  ${c.yellow}!${c.reset} Not filled: ${result.unfilled.join(', ')}`)
     console.log(
-      `    ${c.dim}\`background\` is frontmatter, not content. A video needs an address we cannot invent.${c.reset}`,
-    )
-    console.log(
-      `    ${c.dim}A \`data\` block needs a schema: a @/ ref resolves at build, and an empty {} declares no shape.${c.reset}`,
+      `    ${c.dim}A starter makes up no file, video or embedded component, and writes no table, equation,${c.reset}`,
     )
+    console.log(`    ${c.dim}quote or concept block (md:<tag>) — add those in the section.${c.reset}`)
+  }
+
+  if (result.problems?.length) {
+    console.log('')
+    for (const problem of result.problems) console.log(`  ${c.yellow}!${c.reset} ${problem}`)
   }
 
   if (write) {
@@ -189,7 +194,6 @@ export async function declarationFor(result) {
     icons: 'Icon [1]',
     videos: 'Video [1]',
     snippets: 'Code sample [1]',
-    data: 'The data block the author writes',
   }
   // ⛔ The slot → declaration spelling comes from @uniweb/schemas, not from a
   // copy here. `image` declares and `images` delivers; that mapping is the

package/src/framework-index.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-09-28T23:00:27.056Z",
+  "generatedAt": "2026-09-29T20:02:35.777Z",
   "packages": {
     "@uniweb/api": {
       "version": "0.6.8",
@@ -10,7 +10,7 @@
       ]
     },
     "@uniweb/build": {
-      "version": "0.73.2",
+      "version": "0.74.0",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -55,7 +55,7 @@
       ]
     },
     "@uniweb/kit": {
-      "version": "0.19.11",
+      "version": "0.19.13",
       "path": "framework/kit",
       "deps": [
         "@uniweb/core",
@@ -71,7 +71,7 @@
       "deps": []
     },
     "@uniweb/press": {
-      "version": "0.4.17",
+      "version": "0.4.18",
       "path": "framework/press",
       "deps": []
     },
@@ -84,7 +84,7 @@
       ]
     },
     "@uniweb/runtime": {
-      "version": "0.28.3",
+      "version": "0.28.4",
       "path": "framework/runtime",
       "deps": [
         "@uniweb/core",
@@ -97,7 +97,7 @@
       "deps": []
     },
     "@uniweb/schemas": {
-      "version": "0.9.3",
+      "version": "0.10.0",
       "path": "framework/schemas",
       "deps": []
     },
@@ -107,7 +107,7 @@
       "deps": []
     },
     "@uniweb/semantic-parser": {
-      "version": "1.4.1",
+      "version": "1.5.1",
       "path": "framework/semantic-parser",
       "deps": []
     },
@@ -117,7 +117,7 @@
       "deps": []
     },
     "@uniweb/templates": {
-      "version": "0.17.7",
+      "version": "0.17.9",
       "path": "framework/templates",
       "deps": []
     },
@@ -127,7 +127,7 @@
       "deps": []
     },
     "@uniweb/unipress": {
-      "version": "0.10.16",
+      "version": "0.10.17",
       "path": "framework/unipress",
       "deps": [
         "@uniweb/build",