uniweb 0.8.9 → 0.8.11

package/README.md

@@ -115,7 +115,7 @@ Frontmatter specifies the component type and configuration. The body contains th
 
 ### Beyond Markdown
 
-For content that doesn't fit markdown patterns—products, team members, events—use tagged code blocks:
+For content that doesn't fit markdown patterns—products, team members, events—use tagged data blocks:
 
 ````markdown
 ```yaml:team-member
@@ -202,7 +202,7 @@ Open `foundation/src/sections/Hero.jsx`. The component receives parsed content:
 
 ```jsx
 export default function Hero({ content }) {
-  const { title, paragraphs, links, imgs, items } = content
+  const { title, paragraphs, links, images, items } = content
   // Edit the JSX below...
 }
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.8.9",
+  "version": "0.8.11",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,11 +41,11 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/build": "0.8.8",
+    "@uniweb/build": "0.8.10",
     "@uniweb/content-reader": "1.1.4",
-    "@uniweb/kit": "0.7.6",
-    "@uniweb/core": "0.5.6",
-    "@uniweb/runtime": "0.6.6",
-    "@uniweb/semantic-parser": "1.1.4"
+    "@uniweb/core": "0.5.7",
+    "@uniweb/runtime": "0.6.7",
+    "@uniweb/kit": "0.7.7",
+    "@uniweb/semantic-parser": "1.1.5"
   }
 }

package/partials/agents.md

@@ -50,10 +50,10 @@ This project was created with [Uniweb CLI](https://github.com/uniweb/cli). Full
 | Component metadata (meta.js) | `reference/component-metadata.md` |
 | Migrating existing designs | `development/converting-existing.md` |
 
-> **npm registry:** Use `https://registry.npmjs.org/uniweb` for package metadata — the npmjs.com website blocks automated requests.
-
 ## Project Structure
 
+Most projects start as a workspace with two packages:
+
 ```
 project/
 ├── foundation/     # Component developer's domain
@@ -61,23 +61,24 @@ project/
 └── pnpm-workspace.yaml
 ```
 
-Multi-site variant uses `foundations/` and `sites/` (plural) folders.
+- **Foundation** (developer): React components. Those in `src/sections` and `src/layouts` are *section types* — selectable by content authors via `type:` in frontmatter, or used for site-level layout areas (header, footer, panel). Most have an a `meta.js` with metadata in them. Everything in `src/components` (or elsewhere) is ordinary React.
+- **Site** (content author): Markdown content + configuration. Each section file references a section type. Authors work here without touching foundation code. It may also contain collections of structured content and/or references to external data sources.
 
-- **Foundation** (developer): React components. Those with `meta.js` are *section types* — selectable by content authors via `type:` in frontmatter. Everything else is ordinary React.
-- **Site** (content author): Markdown content + configuration. Each section file references a section type. Authors work here without touching foundation code.
+> Multi-site projects use sub-folders with site/foundation pairs in them, or segregate foundations and sites into separate folders (`foundations/`, `sites/`).
 
 ## Project Setup
 
 Always use the CLI to scaffold projects — never write `package.json`, `vite.config.js`, `main.js`, or `index.html` manually. The CLI resolves correct versions and structure.
 
+**npm or pnpm.** Projects include both `pnpm-workspace.yaml` and npm workspaces. Replace `pnpm` with `npm` in any command below.
+
 ### New workspace
 
 ```bash
-pnpm create uniweb my-project
+pnpm create uniweb my-project --template <n>
 cd my-project && pnpm install
 ```
-
-This creates a workspace with foundation + site + starter content — two commands to a dev server. Use `--template <n>` for an official template (`marketing`, `docs`, `academic`, etc.), `--template none` for foundation + site with no content, or `--blank` for an empty workspace.
+Use `--template <n>` for an official template (`none`, `starter`, `marketing`, `docs`, `academic`, etc.), `--template none` for foundation + site with no content, or `--blank` for an empty workspace.
 
 ### Adding a co-located project
 
@@ -129,8 +130,6 @@ pnpm build      # Build for production
 pnpm preview    # Preview production build (SSG + SPA)
 ```
 
-> **npm works too.** Projects include both `pnpm-workspace.yaml` and npm workspaces. Replace `pnpm` with `npm` in any command above.
-
 ---
 
 ## Content Authoring
@@ -176,13 +175,14 @@ content = {
   subtitle2: '',    // Third-level heading
   paragraphs: [],   // Text blocks
   links: [],        // { href, label, role } — standalone links become buttons
-  imgs: [],         // { src, alt, role }
+  images: [],       // { src, alt, role, href }
   icons: [],        // { library, name, role }
-  videos: [],       // Video embeds
+  videos: [],       // { src, alt, role, poster, href }
   insets: [],       // Inline @Component references — { refId }
   lists: [],        // [[{ paragraphs, links, lists, ... }]] — each list item is an object, not a string
   quotes: [],       // Blockquotes
-  data: {},         // From tagged code blocks (```yaml:tagname) and (```js:tagname)
+  snippets: [],     // Fenced code — [{ language, code }]
+  data: {},         // From tagged data blocks (```yaml:tagname, ```json:tagname)
   headings: [],     // Overflow headings after subtitle2
   items: [],        // Each has the same flat structure — from headings after body content
   sequence: [],     // All elements in document order
@@ -205,7 +205,7 @@ Lightning quick.        ← items[0].paragraphs[0]
 Enterprise-grade.       ← items[1].paragraphs[0]
 ```
 
-**Items have the full content shape** — this is the most commonly overlooked feature. Each item has `title`, `pretitle`, `subtitle`, `paragraphs`, `links`, `icons`, `lists`, and even `data` (tagged blocks). You don't need workarounds for structured content within items:
+**Items have the full content shape** — this is the most commonly overlooked feature. Each item has `title`, `pretitle`, `subtitle`, `paragraphs`, `links`, `icons`, `lists`, `snippets`, and even `data` (tagged data blocks). You don't need workarounds for structured content within items:
 
 ```markdown
 ### The Problem                ← items[0].pretitle
@@ -258,7 +258,7 @@ You have three layers. Most of the design skill is choosing between them:
 
 **Frontmatter params** — `columns: 3`, `variant: centered`, `theme: dark`. Configuration that an author might change but that isn't *content*. Would changing this value change the section's *meaning*, or just its *presentation*? Presentation → param. Meaning → content.
 
-**Tagged data blocks** — for content that doesn't fit markdown patterns. Products with SKUs, team members with roles, event schedules, pricing metadata, form definitions. When the information is genuinely structured data that a content author still owns, a well-named tagged block (`yaml:pricing`, `yaml:speakers`, `yaml:config`) is clearer than contorting markdown into a data format.
+**Tagged data blocks** — for content that doesn't fit markdown patterns. Products with SKUs, team members with roles, event schedules, pricing metadata, form definitions. When the information is genuinely structured data that a content author still owns, a well-named tagged block (`yaml:pricing`, `yaml:speakers`, `yaml:config`) is clearer than contorting markdown into a data format. Supported formats: `yaml` and `json`. The format is a serialization format (how to parse the data), not a language for display. Tagged blocks are parsed at build time into JS objects and delivered as `content.data.tagName`.
 
 Read the markdown out loud. If a content author would understand what every line does and how to edit it, you've chosen the right layer. The moment markdown feels like it's encoding data rather than expressing content, step up to a tagged block — that's fine. A well-documented `yaml:pricing` block is better than a markdown structure that puzzles the author.
 
@@ -321,7 +321,7 @@ Custom SVGs: `![Logo](./logo.svg){role=icon}`
 ```markdown
 [text](url){target=_blank}              <!-- Open in new tab -->
 [text](./file.pdf){download}            <!-- Download -->
-![alt](./img.jpg){role=banner}          <!-- Role determines array: imgs, icons, or videos -->
+![alt](./img.jpg){role=banner}          <!-- Role determines array: images, icons, or videos -->
 ```
 
 **Quote values that contain spaces:** `{note="Ready to go"}` not `{note=Ready to go}`. Unquoted values end at the first space.
@@ -345,9 +345,11 @@ This is [less important]{muted} context.
 
 Sites can define additional named styles in `theme.yml`'s `inline:` section.
 
-### Structured Data
+### Fenced Code in Content
+
+Fenced code in markdown serves two distinct purposes depending on whether it has a tag:
 
-Tagged code blocks pass structured data via `content.data`:
+**Tagged data blocks** — structured data parsed into JS objects. The format (`yaml`/`json`) is a serialization format, not a display language. The tag is the key in `content.data`:
 
 ````markdown
 ```yaml:form
@@ -358,9 +360,21 @@ submitLabel: Send
 ```
 ````
 
-Access: `content.data?.form` → `{ fields: [...], submitLabel: "Send" }`
+Access: `content.data?.form` → `{ fields: [...], submitLabel: "Send" }`. Supported formats: `yaml` (or `yml`) and `json`.
+
+**Code snippets** — display content with a language for syntax highlighting. Available in `content.snippets` as `[{ language, code }]`:
+
+````markdown
+```jsx
+function Hello() {
+  return <h1>Hello world</h1>
+}
+```
+````
+
+Access: `content.snippets[0]` → `{ language: 'jsx', code: 'function Hello() {...}' }`. The `language` attribute is a display hint for syntax highlighting, not a parsing format. Filter by language: `content.snippets.filter(s => s.language === 'css')`.
 
-**Untagged code blocks** (plain ``` js) are only visible to sequential-rendering components. If a component needs to access code blocks by name, tag them (`jsx:before`, `jsx:after` → `content.data?.before`, `content.data?.after`).
+Both appear in `content.sequence` for document-order rendering. The difference: tagged data blocks are parsed and extracted to `content.data`; code snippets are preserved and collected in `content.snippets`.
 
 ### Composition: Nesting and Embedding
 
@@ -377,7 +391,7 @@ In other frameworks, this is where you'd reach for MDX, or prop-drill a componen
 Standard markdown image syntax — `![alt](@Component){attributes}`. The content author placed a full React component with content and params, and it looks like an image reference. The developer builds `NetworkDiagram` as an ordinary React component with `inset: true` in its `meta.js`. The kit's `<Visual>` component renders the first non-empty candidate — so the same section type works whether the author provides a static image, a video, or an interactive component:
 
 ```jsx
-<Visual inset={block.insets[0]} video={content.videos[0]} image={content.imgs[0]} className="rounded-2xl" />
+<Visual inset={block.insets[0]} video={content.videos[0]} image={content.images[0]} className="rounded-2xl" />
 ```
 
 The content author controls what goes in the visual slot. The developer's component doesn't need to know or care whether it's rendering an image or a ThreeJS scene.
@@ -461,6 +475,8 @@ export default function Grid({ block, params }) {
 
 Set `background` in frontmatter — the runtime renders it automatically:
 
+> **FIXME:** var(--primary-900) should be primary-900, right?
+
 ```yaml
 background: /images/hero.jpg                             # Image
 background: /videos/hero.mp4                             # Video
@@ -796,7 +812,7 @@ import { Section, Render } from '@uniweb/kit'
 ```jsx
 import { Visual } from '@uniweb/kit'
 
-<Visual inset={block.insets[0]} video={content.videos[0]} image={content.imgs[0]} className="rounded-2xl" />
+<Visual inset={block.insets[0]} video={content.videos[0]} image={content.images[0]} className="rounded-2xl" />
 ```
 
 ### Kit API by Use Case
@@ -916,8 +932,20 @@ export default {
     compact: { label: 'Compact', params: { columns: 4 } },
   },
 
+  // context and initialState: keys are developer-defined, not framework fields.
+  // Design your own names for your foundation's cross-block communication.
+
+  // Static — neighbors read via getNextBlockInfo().context
   context: {
-    allowTranslucentTop: true,
+    // Example: a Hero might declare this so a Header knows it can float.
+    // allowTranslucentTop: true,
+  },
+
+  // Dynamic — neighbors read via getNextBlockInfo().state
+  // Component can update with useBlockState()
+  initialState: {
+    // Example: Hero starts translucent-ready, but component logic may disable it.
+    // allowTranslucentTop: true,
   },
 }
 ```
@@ -928,46 +956,52 @@ All defaults belong in `meta.js`, not inline in component code.
 
 Section types naturally use params to adjust their own rendering — `variant: flipped` reverses a flex direction, `columns: 3` sets a grid. That's not a pattern, that's the baseline.
 
-The **Front Desk pattern** is when a section type does virtually no rendering itself. It reads the author's params, picks the right helper component from `src/components/`, and translates author-friendly vocabulary into developer-oriented props. The section type is a front desk — it greets the request and routes it to the right specialist:
+The **Front Desk pattern** is when a section type does virtually no rendering itself. It reads the author's params, picks the right helper component, and translates author-friendly vocabulary into developer-oriented props. The section type is a front desk — it greets the request and routes it to the right specialist.
+
+The workers behind the front desk don't need to share the same interface. A `Hero` might delegate to a `SliderHero` that renders an image carousel and a `ContactHero` that renders a quote request form. They expect different content and different props — that's fine. The front desk declares the **union** of all content its workers might need. Some content won't be used for a given variant, and that's perfectly normal in CCA — params change behavior, and that includes not rendering some content:
+
+```js
+// meta.js — the union of all variants' needs
+export default {
+  params: {
+    variant: { type: 'select', options: ['slider', 'contact'], default: 'slider' },
+    slideInterval: { type: 'number', default: 5 },
+    density: { type: 'select', options: ['default', 'compact'], default: 'default' },
+    style: { type: 'select', options: ['default', 'dramatic'], default: 'default' },
+  }
+}
+```
 
 ```jsx
-// sections/Features/index.jsx — the front desk
-import { CardGrid } from '../../components/CardGrid'
-import { CardList } from '../../components/CardList'
-import { ComparisonTable } from '../../components/ComparisonTable'
+// sections/Hero/index.jsx — the front desk
+import { SliderHero } from '../../components/SliderHero'
+import { ContactHero } from '../../components/ContactHero'
 
-const variants = { grid: CardGrid, list: CardList, comparison: ComparisonTable }
+const variants = { slider: SliderHero, contact: ContactHero }
 
-export default function Features({ content, block, params }) {
-  const Layout = variants[params.variant] || CardGrid
+export default function Hero({ content, block, params }) {
+  const Variant = variants[params.variant] || SliderHero
 
   return (
-    <Layout
+    <Variant
+      // Shared — every variant gets these
       title={content.title}
       subtitle={content.paragraphs[0]}
-      items={content.items}
+      links={content.links}
       block={block}
-      columns={params.columns}
-      showIcons={params.showIcon !== false}
+      // Content that only some variants use
+      images={content.images}
+      formData={content.data?.quote}
+      // Translated params — author vocabulary → developer props
+      interval={params.slideInterval}
       compact={params.density === 'compact'}
+      transition={params.style === 'dramatic' ? 'zoom' : 'fade'}
     />
   )
 }
 ```
 
-```js
-// meta.js — author-friendly language
-export default {
-  params: {
-    variant: { type: 'select', options: ['grid', 'list', 'comparison'], default: 'grid' },
-    columns: { type: 'number', default: 3 },
-    showIcon: { type: 'boolean', default: true },
-    density: { type: 'select', options: ['default', 'compact'], default: 'default' },
-  }
-}
-```
-
-The content author writes `variant: comparison` — they don't know or care about `ComparisonTable`. The section type translates `density: compact` into a `compact={true}` prop. `CardGrid`, `CardList`, `ComparisonTable` live in `src/components/` — ordinary React, reusable across multiple section types, testable independently.
+`SliderHero` uses `images`, `interval`, and `transition`; it ignores `formData` and `compact`. `ContactHero` uses `formData` and `compact`; it ignores `images` and `interval`. Each worker takes what it needs. Some params only matter for certain variants (`slideInterval` for slider, `density` for contact). Some are high-level names that the front desk translates into developer-oriented values (`style: dramatic` → `transition="zoom"`). The content author writes `variant: contact` — they don't know or care about `ContactHero`.
 
 This is the system-building pattern at its clearest: **section types are the public interface** to your content system (author-friendly names, documented in `meta.js`). **Helper components are the implementation** (developer-friendly APIs, ordinary React props). The section type is the thin translation layer that connects the two worlds.
 
@@ -1027,11 +1061,65 @@ page.hasChildren(), page.children
 
 ### Cross-Block Communication
 
+Section types sometimes need to coordinate. The typical case: a Header needs to know whether the section below it supports a floating translucent overlay — a Hero with a full-bleed background does, a plain text section doesn't. The section that **owns the capability declares it**; the section that **needs to adapt reads it**.
+
+`getBlockInfo()` exposes two channels:
+
+- **`context`** — Static capabilities from `meta.js`. Never changes. The declaring section type always has this capability.
+- **`state`** — Dynamic runtime state via `useBlockState()`. Can change based on component logic. Initial value comes from `initialState` in `meta.js`.
+
+```jsx
+// Header reads the next section's info to decide how to render
+const nextBlockInfo = block.getNextBlockInfo()
+// nextBlockInfo.context  → static (meta.js)
+// nextBlockInfo.state    → dynamic (useBlockState)
+```
+
+**Static context** — Hero declares a permanent capability, Header reads it:
+
+```js
+// Hero/meta.js — "I always support a translucent header over me"
+export default {
+  context: { allowTranslucentTop: true },
+}
+```
+
+```jsx
+// Header/index.jsx — adapts based on what's below
+const nextBlockInfo = block.getNextBlockInfo()
+const isFloating = nextBlockInfo?.context?.allowTranslucentTop || false
+```
+
+**Dynamic state** — Hero declares an initial value but can change it at runtime:
+
+```js
+// Hero/meta.js — starts as true, but component logic may change it
+export default {
+  initialState: { allowTranslucentTop: true },
+}
+```
+
+```jsx
+// Hero/index.jsx — conditionally updates
+function Hero({ content, block }) {
+  const [state, setState] = block.useBlockState(useState)
+  // state.allowTranslucentTop is true initially (from meta.js)
+  // Component logic can change it: setState({ allowTranslucentTop: false })
+}
+```
+
 ```jsx
-const firstBody = block.page.getFirstBodyBlockInfo()
-// → { type, theme, context: { allowTranslucentTop }, state }
+// Header/index.jsx — reads dynamic state, falls back to static context
+const nextBlockInfo = block.getNextBlockInfo()
+const isFloating = nextBlockInfo?.state?.allowTranslucentTop
+  ?? nextBlockInfo?.context?.allowTranslucentTop
+  ?? false
 ```
 
+The key names (`allowTranslucentTop`, `expanded`, etc.) are yours to design — they're not framework fields. Define whatever protocol your foundation's sections need.
+
+Other navigation methods: `block.getPrevBlockInfo()`, `block.page.getFirstBodyBlockInfo()`.
+
 ### Custom Layouts
 
 Layouts live in `foundation/src/layouts/` and are auto-discovered:
@@ -1154,9 +1242,9 @@ Semantic tokens come from `theme-tokens.css` (populated from `theme.yml`). Use `
 
 **Content not appearing as expected?**
 ```bash
-uniweb inspect pages/home/hero.md         # Single section
-uniweb inspect pages/home/                 # Whole page
-uniweb inspect pages/home/hero.md --raw    # ProseMirror AST
+pnpm uniweb inspect pages/home/hero.md         # Single section
+pnpm uniweb inspect pages/home/                 # Whole page
+pnpm uniweb inspect pages/home/hero.md --raw    # ProseMirror AST
 ```
 
 ## Learning from Official Templates
@@ -1164,7 +1252,7 @@ uniweb inspect pages/home/hero.md --raw    # ProseMirror AST
 When you're unsure how to implement a pattern — data fetching, i18n, layouts, insets, theming — install an official template as a reference project in your workspace:
 
 ```bash
-uniweb add project marketing --from marketing
+pnpm uniweb add project marketing --from marketing
 pnpm install
 ```
 

package/src/commands/inspect.js

@@ -149,7 +149,7 @@ function guaranteeItemStructure(item) {
     subtitle: item.subtitle || '',
     paragraphs: item.paragraphs || [],
     links: item.links || [],
-    imgs: item.imgs || [],
+    images: item.images || [],
     lists: item.lists || [],
     icons: item.icons || [],
     videos: item.videos || [],
@@ -178,7 +178,7 @@ function guaranteeContentStructure(parsedContent) {
     alignment: content.alignment || null,
     paragraphs: content.paragraphs || [],
     links: content.links || [],
-    imgs: content.imgs || [],
+    images: content.images || [],
     lists: content.lists || [],
     icons: content.icons || [],
     videos: content.videos || [],

package/starter/foundation/src/sections/Section/index.jsx

@@ -7,7 +7,7 @@ import { H1, H2, P, Link, cn } from '@uniweb/kit'
  * Uses semantic tokens so it adapts to any theme context automatically.
  */
 export default function Section({ content, params }) {
-  const { title, pretitle, subtitle, paragraphs = [], links = [], imgs = [] } = content || {}
+  const { title, pretitle, subtitle, paragraphs = [], links = [], images = [] } = content || {}
 
   const {
     align = 'center',
@@ -77,9 +77,9 @@ export default function Section({ content, params }) {
           </div>
         )}
 
-        {imgs.length > 0 && (
+        {images.length > 0 && (
           <div className="mt-8">
-            {imgs.map((img, index) => (
+            {images.map((img, index) => (
               <img
                 key={index}
                 src={img.url || img.src}

package/starter/foundation/src/sections/Section/meta.js

@@ -10,7 +10,7 @@ export default {
     subtitle: 'Secondary heading',
     paragraphs: 'Body text',
     links: 'Call-to-action buttons',
-    imgs: 'Section images',
+    images: 'Section images',
   },
 
   params: {