uniweb 0.12.41 → 0.12.43

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.12.41",
+  "version": "0.12.43",
   "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/core": "0.7.16",
-    "@uniweb/kit": "0.9.20",
-    "@uniweb/runtime": "0.8.22"
+    "@uniweb/core": "0.7.17",
+    "@uniweb/runtime": "0.8.23",
+    "@uniweb/kit": "0.9.21"
   },
   "peerDependencies": {
-    "@uniweb/build": "0.14.24",
     "@uniweb/content-reader": "1.1.12",
-    "@uniweb/semantic-parser": "1.1.17"
+    "@uniweb/semantic-parser": "1.1.17",
+    "@uniweb/build": "0.14.25"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md

@@ -1005,6 +1005,67 @@ contexts:
 
 > **Contrast warning:** Bright brand colors (orange, yellow, light green) at shade 500 may not meet WCAG contrast (4.5:1) with white foreground text. Test buttons for readability — if contrast is insufficient, keep the default shade 600 mapping.
 
+### Fonts
+
+Font families are a **site** setting, configured in `theme.yml` under `fonts:`. A foundation never installs a font package (no `@fontsource/*`) and never hardcodes a family in its code — if you reach for either, you're off the paved path. The framework provides three roles and wires each onto the standard elements for you:
+
+| Role | Wired onto | Typical use |
+|---|---|---|
+| `body` | `body` (all text by default) | paragraphs, UI |
+| `heading` | `h1, h2, h3` | titles |
+| `mono` | `code, pre, kbd, samp` | code, technical text |
+
+```yaml
+# site/theme.yml
+fonts:
+  body: "Inter, system-ui, sans-serif"
+  heading: "Poppins, system-ui, sans-serif"
+  mono: "'Fira Code', monospace"
+```
+
+Because the site wires the families onto real elements, **components need no font-family classes** — render semantic markup (`<H1>`, `<P>`, `<code>` from the kit) and the roles apply. This is what lets one foundation re-font per site with zero code changes.
+
+**Loading the files** — two site-side options, both config-only, neither adds a dependency:
+
+```yaml
+# Hosted (Google Fonts or any provider). The build auto-adds preconnect
+# hints and drops families no role references.
+fonts:
+  heading: "Poppins, sans-serif"
+  import:
+    - url: "https://fonts.googleapis.com/css2?family=Poppins:wght@600;700"
+
+# Self-hosted (no CDN — privacy / offline). Put the files under
+# site/public/fonts/ and declare @font-face faces; the build emits the
+# @font-face rules + preload hints, and skips any face whose family no
+# role uses.
+fonts:
+  heading: "Söhne, sans-serif"
+  faces:
+    - { family: "Söhne", src: /fonts/soehne-bold.woff2, weight: 700 }
+    - { family: "Söhne", src: /fonts/soehne-regular.woff2, weight: 400 }
+```
+
+**In a component, weight is yours; family is the site's.** Weight / size / style utilities (`font-bold`, `font-black`, `italic`, `text-xl`) are ordinary design vocabulary — use them freely. A font-**family** utility is only safe when the family behind it is site-controlled — and by default `font-sans` / `font-serif` are *not* (they resolve to Tailwind's built-in stacks; only `font-mono` tracks the site's `mono` role, by name-collision). So a bare `font-serif` in a component silently hardcodes a typeface.
+
+**A family beyond the three roles** — an editorial serif, a display face — is a **foundation var**, so the site keeps control. Name it after a Tailwind font slot (`font-serif`) and that utility resolves to it; or give it any name and reference the variable directly:
+
+```js
+// foundation src/main.js
+export const vars = {
+  'font-serif': {
+    default: "Georgia, 'Times New Roman', serif",
+    description: 'Editorial serif for pull-quotes, taglines, quotes',
+  },
+}
+```
+```jsx
+<p className="font-serif">{content.tagline}</p>   {/* now site-controlled */}
+// …or a custom-named var:  <p style={{ fontFamily: 'var(--font-display)' }}>
+```
+
+The site sets the family in `theme.yml` under `vars:` (`font-serif: "Fraunces, Georgia, serif"`) and loads it with `fonts.import` / `fonts.faces` — the file loads even though the family isn't one of the three role slots.
+
 ### Foundation variables
 
 Most customization is handled by component params. Both section components and layout components declare their own params in `meta.js` — layouts are full components with params, not just structural wrappers. A header height, for example, is typically a layout param, not a foundation var.

package/src/framework-index.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-07-13T21:48:20.211Z",
+  "generatedAt": "2026-07-17T21:03:16.675Z",
   "packages": {
     "@uniweb/build": {
-      "version": "0.14.24",
+      "version": "0.14.25",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -25,7 +25,7 @@
       "deps": []
     },
     "@uniweb/core": {
-      "version": "0.7.16",
+      "version": "0.7.17",
       "path": "framework/core",
       "deps": [
         "@uniweb/semantic-parser",
@@ -43,7 +43,7 @@
       "deps": []
     },
     "@uniweb/kit": {
-      "version": "0.9.20",
+      "version": "0.9.21",
       "path": "framework/kit",
       "deps": [
         "@uniweb/core",
@@ -61,7 +61,7 @@
       "deps": []
     },
     "@uniweb/runtime": {
-      "version": "0.8.22",
+      "version": "0.8.23",
       "path": "framework/runtime",
       "deps": [
         "@uniweb/core",
@@ -89,17 +89,17 @@
       "deps": []
     },
     "@uniweb/templates": {
-      "version": "0.7.42",
+      "version": "0.7.44",
       "path": "framework/templates",
       "deps": []
     },
     "@uniweb/theming": {
-      "version": "0.1.5",
+      "version": "0.1.6",
       "path": "framework/theming",
       "deps": []
     },
     "@uniweb/unipress": {
-      "version": "0.4.31",
+      "version": "0.4.32",
       "path": "framework/unipress",
       "deps": [
         "@uniweb/build",
@@ -112,7 +112,7 @@
   },
   "templates": {
     "marketing": {
-      "name": "Marketing Starter",
+      "name": "Marketing",
       "description": "Landing pages and marketing sites with Tailwind CSS v4",
       "tags": [
         "marketing",
@@ -130,7 +130,7 @@
       ]
     },
     "docs": {
-      "name": "Documentation",
+      "name": "Docs",
       "description": "Documentation sites with navigation levels",
       "tags": [
         "docs",
@@ -139,7 +139,7 @@
       ]
     },
     "international": {
-      "name": "International Business",
+      "name": "International",
       "description": "Multilingual corporate website with English, Spanish, and French",
       "tags": [
         "i18n",
@@ -161,7 +161,7 @@
       ]
     },
     "dynamic": {
-      "name": "Dynamic Data",
+      "name": "Dynamic",
       "description": "Live API data fetching with loading states, transforms, and the portable data pattern",
       "tags": [
         "data",
@@ -172,7 +172,7 @@
       ]
     },
     "store": {
-      "name": "Solis Artisans - Store",
+      "name": "Store",
       "description": "Artisan e-commerce with product collections, Shopify Buy Button, journal blog, and stone-amber design",
       "tags": [
         "store",
@@ -183,7 +183,7 @@
       ]
     },
     "learning": {
-      "name": "Learning Platform",
+      "name": "Learning",
       "description": "Course-based learning site with quizzes, code challenges, and AI grading integration",
       "tags": [
         "learning",
@@ -195,7 +195,7 @@
       ]
     },
     "extensions": {
-      "name": "Extensions Demo",
+      "name": "Extensions",
       "description": "Primary foundation with a visual effects extension, demonstrating multi-foundation sites",
       "tags": [
         "extensions",
@@ -205,7 +205,7 @@
       ]
     },
     "cv-loom": {
-      "name": "CV (Loom-instantiated)",
+      "name": "CV (Loom)",
       "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",
@@ -217,7 +217,7 @@
       ]
     },
     "monograph": {
-      "name": "Monograph (Press showcase)",
+      "name": "Monograph",
       "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",
@@ -230,7 +230,7 @@
       ]
     },
     "academic-metrics": {
-      "name": "Academic Metrics (xlsx showcase)",
+      "name": "Academic Metrics",
       "description": "A docusite whose content is also a downloadable Excel workbook. Aggregates academic metrics (publications, funding, supervisions) across multiple members of a university unit. Rich web previews + flat tabular xlsx sheets from the same data. Ships with three 19th-century naturalists as sample members.",
       "tags": [
         "academic-metrics",
@@ -244,7 +244,7 @@
       ]
     },
     "business-docs": {
-      "name": "Business documents",
+      "name": "Business Documents",
       "description": "A complete business-document site: invoice and SOW collections, per-record preview pages, and a filtered engagement report with XLSX export. Built on @uniweb/business-docs and demonstrates the same foundation that ships the unipress invoice template.",
       "tags": [
         "business-docs",
@@ -256,6 +256,17 @@
         "docx",
         "pagedjs"
       ]
+    },
+    "paste": {
+      "name": "Paste a Design (Level 0)",
+      "description": "Bring an existing React design (AI-generated or hand-built) into Uniweb with zero rewiring — replace App.jsx and run. Ships lucide-react preinstalled and SPA-first. The Level 0 conversion starting point.",
+      "tags": [
+        "paste",
+        "level-0",
+        "convert",
+        "ai-generated",
+        "starter"
+      ]
     }
   }
 }

package/src/index.js

@@ -41,6 +41,7 @@ import { template } from './commands/template.js'
 import {
   resolveTemplate,
   parseTemplateId,
+  buildTemplateChoices,
 } from './templates/index.js'
 import { validateTemplate } from './templates/validator.js'
 import { scaffoldWorkspace, scaffoldFoundation, scaffoldSite, applyContent, applyStarter, mergeTemplateDependencies, getWorkspaceTemplateOutputs } from './utils/scaffold.js'
@@ -59,19 +60,11 @@ const colors = {
   red: '\x1b[31m',
 }
 
-// Template choices for interactive prompt
-const TEMPLATE_CHOICES = [
-  { title: 'None', value: 'none', description: 'Foundation + site with no content' },
-  { title: 'Starter', value: 'starter', description: 'Foundation + site + sample content' },
-  { title: 'Marketing', value: 'marketing', description: 'Landing page, features, pricing, testimonials' },
-  { title: 'Docs', value: 'docs', description: 'Documentation with sidebar and search' },
-  { title: 'Academic', value: 'academic', description: 'Research site with publications and team' },
-  { title: 'Dynamic', value: 'dynamic', description: 'Live API data fetching with loading states' },
-  { title: 'International', value: 'international', description: 'Multilingual site with i18n and blog' },
-  { title: 'Store', value: 'store', description: 'E-commerce with product grid' },
-  { title: 'Extensions', value: 'extensions', description: 'Multi-foundation with visual effects extension' },
-  { title: 'Blank workspace', value: 'blank', description: 'Empty workspace — grow with uniweb add' },
-]
+// Template choices for the interactive prompt — built-ins first, then every
+// official template from the shared manifest (so the list never drifts from
+// framework/templates/manifest.json), with "Blank" last. Composed by
+// buildTemplateChoices() in templates/resolver.js.
+const TEMPLATE_CHOICES = buildTemplateChoices()
 
 // Files that may pre-exist in the target dir during `uniweb create .` and
 // will be silently overwritten by the scaffold. Anything else colliding

package/src/templates/index.js

@@ -7,7 +7,7 @@ import { readFile, rm } from 'node:fs/promises'
 import { join, resolve } from 'node:path'
 import { homedir } from 'node:os'
 
-import { parseTemplateId, getTemplateDisplayName, BUILTIN_TEMPLATES, OFFICIAL_TEMPLATES } from './resolver.js'
+import { parseTemplateId, getTemplateDisplayName, BUILTIN_TEMPLATES, OFFICIAL_TEMPLATES, buildTemplateChoices } from './resolver.js'
 import { fetchNpmTemplate } from './fetchers/npm.js'
 import { fetchGitHubTemplate } from './fetchers/github.js'
 import { fetchOfficialTemplate, listOfficialTemplates } from './fetchers/release.js'
@@ -182,4 +182,4 @@ export async function listAvailableTemplates() {
 }
 
 // Re-export for convenience
-export { parseTemplateId, getTemplateDisplayName, BUILTIN_TEMPLATES, OFFICIAL_TEMPLATES }
+export { parseTemplateId, getTemplateDisplayName, BUILTIN_TEMPLATES, OFFICIAL_TEMPLATES, buildTemplateChoices }

package/src/templates/resolver.js

@@ -12,7 +12,8 @@ const __dirname = dirname(fileURLToPath(import.meta.url))
 export const BUILTIN_TEMPLATES = ['blank', 'starter', 'none']
 
 /**
- * Load the list of official template names.
+ * Load the official template metadata map — `{ id: { name, description,
+ * tags } }`, keyed by template id.
  *
  * There are two sources of truth depending on where the CLI is running:
  *
@@ -24,59 +25,93 @@ export const BUILTIN_TEMPLATES = ['blank', 'starter', 'none']
  *
  * 2. **Published CLI (npm-installed)** — the monorepo isn't on disk, so
  *    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.
+ *    which the publish pipeline rewrites just before `pnpm publish` runs,
+ *    copying the manifest's `templates` verbatim. 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
  * without waiting for a CLI republish.
  *
- * 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. 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.
+ * Both files store `templates` as the same `{ id: { name, description,
+ * tags } }` shape, so one map feeds both name-resolution
+ * (OFFICIAL_TEMPLATES) and the interactive picker (buildTemplateChoices) —
+ * neither hardcodes a list. (An earlier version returned only the keys and
+ * left the `create` picker with its own hardcoded array, which silently
+ * drifted out of sync whenever a template was added.)
  */
-function loadOfficialTemplateList() {
+function loadOfficialTemplateMap() {
   // 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 = tryReadTemplateKeys(workspaceManifest)
+  const picked = tryReadTemplateMap(workspaceManifest)
   if (picked) return picked
 
   // 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)
+  const fromIndex = tryReadTemplateMap(indexPath)
   if (fromIndex) return fromIndex
 
-  // If both sources fail, return an empty list rather than a stale
-  // hardcoded array. An unknown template name then falls through to
+  // If both sources fail, return an empty map rather than a stale
+  // hardcoded list. 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 []
+  return {}
 }
 
-function tryReadTemplateKeys(path) {
+function tryReadTemplateMap(path) {
   try {
     if (!statSync(path).isFile()) return null
     const data = JSON.parse(readFileSync(path, 'utf8'))
     if (data && data.templates && typeof data.templates === 'object') {
-      return Object.keys(data.templates)
+      return data.templates
     }
   } catch {}
   return null
 }
 
-// Official templates from the templates repo. Derived from manifest.json
-// (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()
+// Official template metadata keyed by id. Derived from manifest.json (local
+// dev) or framework-index.json (published CLI) at module load time — see
+// loadOfficialTemplateMap() for details. Read once per process; to reflect a
+// just-added template, restart the CLI or rerun the scaffolder.
+export const OFFICIAL_TEMPLATE_MAP = loadOfficialTemplateMap()
+
+// Official template ids, e.g. ['marketing', 'docs', 'academic', …].
+export const OFFICIAL_TEMPLATES = Object.keys(OFFICIAL_TEMPLATE_MAP)
+
+// Built-in (programmatic) picker entries — not in the manifest; the CLI
+// generates these itself. "Blank" trails the official templates.
+const BUILTIN_LEAD_CHOICES = [
+  { title: 'None', value: 'none', description: 'Foundation + site with no content' },
+  { title: 'Starter', value: 'starter', description: 'Foundation + site + sample content' }
+]
+const BLANK_CHOICE = {
+  title: 'Blank workspace',
+  value: 'blank',
+  description: 'Empty workspace — grow with uniweb add'
+}
+
+/**
+ * Build the choices for the interactive `create` template prompt: the
+ * built-in leads (None, Starter), then every official template from the
+ * shared manifest in manifest order, then Blank last. Deriving the official
+ * entries from OFFICIAL_TEMPLATE_MAP keeps the picker in lockstep with
+ * framework/templates/manifest.json — adding a template there (and
+ * republishing the CLI) is all it takes for it to appear here.
+ *
+ * @returns {Array<{title: string, value: string, description: string}>}
+ */
+export function buildTemplateChoices() {
+  const official = Object.entries(OFFICIAL_TEMPLATE_MAP).map(([id, info]) => ({
+    title: info?.name || id,
+    value: id,
+    description: info?.description || ''
+  }))
+  return [...BUILTIN_LEAD_CHOICES, ...official, BLANK_CHOICE]
+}
 
 /**
  * Parse a template identifier and determine its source type