uniweb 0.14.1 → 0.14.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.14.1",
+  "version": "0.14.3",
   "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.8.0",
-    "@uniweb/kit": "0.10.1",
+    "@uniweb/kit": "0.10.3",
     "@uniweb/runtime": "0.9.0"
   },
   "peerDependencies": {
-    "@uniweb/build": "0.16.0",
+    "@uniweb/build": "0.16.1",
     "@uniweb/content-reader": "1.2.0",
     "@uniweb/semantic-parser": "1.2.0"
   },

package/partials/agents.md

@@ -338,7 +338,9 @@ content = {
   lists: [],        // [[{ paragraphs, links, lists, … }]] — each item is an object, not a string
   quotes: [],       // Blockquotes
   snippets: [],     // Fenced code — [{ language, code }]
-  data: {},         // From tagged data blocks (```yaml:tagname, ```json:tagname)
+  data: {},         // Tagged blocks — ```yaml:tag / ```json:tag give the parsed value,
+                    //   ```md:tag gives { items, sequence } (see Concept blocks)
+  tables: [],       // Only when present — [{ rows: [{ cells: [{ children, header, align }] }] }]
   headings: [],     // Headings after subtitle, in document order
   items: [],        // Each has the same flat structure — from headings after body content
   sequence: [],     // All elements in document order
@@ -503,7 +505,7 @@ Sites can adjust these or add named styles in `theme.yml`'s `inline:` section. O
 
 ### Fenced code: data blocks vs snippets
 
-Fenced code serves two purposes depending on whether it carries a tag.
+Fenced code serves three purposes depending on its info string: `yaml:`/`json:` for data, `md:` for a named kind of prose (see *Concept blocks*), and a bare language for a code sample.
 
 **Tagged data blocks** — structured data parsed into JS objects. The tag is the key in `content.data`; the format (`yaml`/`yml`/`json`) is a serialization format, not a display language.
 
@@ -869,14 +871,13 @@ Names only — for signatures and props, read the package: it's on disk at `node
 **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)
 **Keyboard:** `useShortcut('mod+k', fn)`, `useShortcuts({…})`, `useShortcutLabel('mod+k')` — `mod` is Cmd on Apple platforms and Ctrl elsewhere, and the label renders per-platform so a hint never shows the wrong key
-**Long-form prose:** `<Prose>` and the container you put `<Render>` output in both use Tailwind Typography's `prose` classes, which come from a plugin your *foundation* installs — kit ships no stylesheet. Without it the markup is right and completely unstyled. Add `@tailwindcss/typography` to the foundation's deps, then:
+**Long-form prose:** `<Prose>` and the container you put `<Render>` output in both use Tailwind Typography's `prose` classes. One line in the foundation's `styles.css` supplies them and points them at the site's theme:
 
 ```css
-@plugin "@tailwindcss/typography";
-@import "@uniweb/kit/prose-tokens.css";   /* makes prose answer to theme.yml */
+@import "@uniweb/kit/prose-tokens.css";   /* the plugin, wired to theme.yml */
 ```
 
-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**, 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.
 
 **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 })`
@@ -1335,12 +1336,58 @@ Pages are sequences of sections — the obvious layer. The framework also suppor
 | Pattern | How authored | Use when |
 |---|---|---|
 | **Items** (`content.items`) | Heading groups within one `.md` | Repeating content in one section: cards, features, FAQ entries |
+| **Concept blocks** (`content.data[tag]`) | ` ```md:<tag> ` fence around markdown | A named *kind* of content — an FAQ, a callout, a set of steps |
 | **Child sections** (`block.childBlocks`) | `@`-prefixed `.md` files + `nest:` | Children needing their own section type, rich content, or independent editing |
 | **Insets** (`block.insets`) | `![](@Component)` in markdown | Self-contained visuals/widgets: charts, diagrams, code demos |
 | **Block insets** (`block.insets`) | ` ```@Component ` fence around markdown | A component that *wraps* authored prose: callouts, disclosures, admonitions |
 
 Does the author write content *inside* the nested element? **Yes** → child sections, or a block inset when the wrapper is presentational and lives mid-page. **No** (self-contained, param-driven) → inset. Repeating same-structure groups → items. These compose: a child section can contain insets; items work inside children; a block inset can contain both.
 
+### Concept blocks — naming *what* content is
+
+A ` ```md:<tag> ` fence marks a run of prose as a named kind of thing. The author writes ordinary markdown; the tag says what it is:
+
+````markdown
+```md:faq
+# What plans do you have?
+Three — Starter, Team and Enterprise.
+
+# Can I change later?
+Any time, and we prorate the difference.
+```
+````
+
+Every `#` heading starts an item, so this arrives as `content.data.faq`:
+
+```js
+{
+  items:    [ { title, paragraphs, links, … }, … ],  // one per heading
+  sequence: [ … ]                                    // the same content, in document order
+}
+```
+
+**The shape is fixed by the fence, not by the tag.** Any tag works and none is special — the framework never learns what `faq` means. A body with **no** headings is the same block with a single titleless item, which is what a callout is:
+
+````markdown
+```md:warning
+Back up your database **before** running this. It is not reversible.
+```
+````
+
+**Why this instead of a component reference.** ` ```@Alert ` names *which component renders this*, which is a rendering decision sitting in content. `md:warning` names *what the content is* and leaves rendering to the foundation — so the same content works under a different foundation, and an editor can recognize the concept and offer a surface built for it.
+
+**Reading one in a component.** `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.
+
+```jsx
+function Faq({ content }) {
+  const faq = content.data?.faq
+  if (!faq) return null
+  return faq.items.map((item, i) => <Disclosure key={i} q={item.title} a={item.paragraphs} />)
+}
+```
+
+**Two tags, not a tag plus a variant.** A warning and a note are different concepts, so they are `md:warning` and `md:note`. The fence takes no params.
+
 **Insets — embedding components in content.** Many section types need a "visual" — a hero's illustration, a split-content section's media. Classically an image or video. But what if it's a JSX + SVG diagram, a ThreeJS animation, an interactive playground? Elsewhere you'd reach for MDX or prop-drilling. Here the author writes standard image syntax:
 
 ```markdown

package/src/commands/doctor.js

@@ -169,6 +169,41 @@ function loadSiteYml(dir) {
  *    committed, and then looks like something you may edit. That is how
  *    hand-authored files ended up there in the first place.
  */
+/**
+ * Whether any component source under `dir` matches `pattern`.
+ *
+ * Only the directories a foundation puts components in, and never
+ * `node_modules` — this answers "did the developer write this", so a match
+ * inside a dependency is the wrong answer.
+ */
+function sourceMatches(dir, pattern) {
+  const roots = ['sections', 'layouts', 'components']
+  const walk = (d, depth = 0) => {
+    if (depth > 6) return false
+    let entries
+    try {
+      entries = readdirSync(d, { withFileTypes: true })
+    } catch {
+      return false
+    }
+    for (const entry of entries) {
+      if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue
+      const p = join(d, entry.name)
+      if (entry.isDirectory()) {
+        if (walk(p, depth + 1)) return true
+      } else if (/\.(jsx?|tsx?)$/.test(entry.name)) {
+        try {
+          if (pattern.test(readFileSync(p, 'utf8'))) return true
+        } catch {
+          // unreadable file — not this check's problem to report
+        }
+      }
+    }
+    return false
+  }
+  return roots.some((r) => walk(join(dir, r)))
+}
+
 function checkGeneratedDataDir({ sitePath, siteName, siteYml, issues, shouldFix, fixed }) {
   const dataDir = join(sitePath, 'public', DATA_DIR)
   const declared = new Set(Object.keys(siteYml.collections || {}))
@@ -380,6 +415,52 @@ export async function doctor(args = []) {
     }
   }
 
+  // Prose without the tokens — a silent, total loss of styling.
+  //
+  // `@uniweb/kit/prose-tokens.css` brings Tailwind Typography with it and then
+  // points it at the site's theme.yml. A foundation that writes `prose` (or
+  // renders <Prose>/<Article>, which emit it) and does NOT import that file
+  // gets the class and no rules behind it: correct markup, zero styling, and
+  // nothing reported anywhere. Measured 2026-07-30 on a foundation missing only
+  // the plugin — every paragraph `margin-top: 0px`, no warning from Vite,
+  // Tailwind or the browser.
+  //
+  // kit closes this for anyone who imports the file; this closes it for anyone
+  // who does not, which is the case kit cannot reach.
+  for (const f of foundations) {
+    // `f.path` is already absolute (built above with join(workspaceDir, …)).
+    const stylesPath = join(f.path, 'styles.css')
+    if (!existsSync(stylesPath)) continue
+
+    const styles = readFileSync(stylesPath, 'utf8')
+    if (styles.includes('@uniweb/kit/prose-tokens.css')) continue
+
+    // Does anything here actually ask for prose? Either the class in the
+    // stylesheet, or kit's components, which render it.
+    const usesProseClass = /(^|[\s"'`])prose(\s|["'`]|$)/m.test(styles)
+    const usesProseComponent = sourceMatches(f.path, /<(Prose|Article)\b/)
+
+    if (!usesProseClass && !usesProseComponent) continue
+
+    const id = 'prose-without-tokens'
+    const reason = usesProseComponent
+      ? 'renders <Prose> or <Article>'
+      : 'uses the `prose` class'
+    issues.push({
+      id,
+      type: 'warning',
+      foundation: f.name,
+      message: `${f.name} ${reason} but does not import prose-tokens.css`
+    })
+    warn(`[${id}] ${f.name} ${reason}, with no prose styling behind it`)
+    log(
+      `    Tailwind Typography supplies the rules and it is not loaded, so the ` +
+      `markup is correct and completely unstyled — silently.`
+    )
+    log(`    Add to ${f.folderName}/styles.css:`)
+    log(`      ${colors.dim}@import "@uniweb/kit/prose-tokens.css";${colors.reset}`)
+  }
+
   if (extensions.length > 0) {
     log('')
     success(`Found ${extensions.length} extension(s):`)

package/src/framework-index.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-07-30T19:35:25.684Z",
+  "generatedAt": "2026-07-30T22:59:53.314Z",
   "packages": {
     "@uniweb/build": {
-      "version": "0.16.0",
+      "version": "0.16.1",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -22,7 +22,7 @@
       "deps": []
     },
     "@uniweb/content-writer": {
-      "version": "0.3.0",
+      "version": "0.3.1",
       "path": "framework/content-writer",
       "deps": []
     },
@@ -45,7 +45,7 @@
       "deps": []
     },
     "@uniweb/kit": {
-      "version": "0.10.1",
+      "version": "0.10.3",
       "path": "framework/kit",
       "deps": [
         "@uniweb/core",
@@ -64,7 +64,7 @@
       "deps": []
     },
     "@uniweb/projections": {
-      "version": "0.2.0",
+      "version": "0.2.1",
       "path": "framework/projections",
       "deps": [
         "@uniweb/content-writer",
@@ -100,7 +100,7 @@
       "deps": []
     },
     "@uniweb/templates": {
-      "version": "0.7.46",
+      "version": "0.8.0",
       "path": "framework/templates",
       "deps": []
     },