uniweb 0.12.56 → 0.12.58

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.12.56",
+  "version": "0.12.58",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,12 +41,12 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/core": "0.7.22",
-    "@uniweb/kit": "0.9.29",
-    "@uniweb/runtime": "0.8.28"
+    "@uniweb/core": "0.7.24",
+    "@uniweb/runtime": "0.8.30",
+    "@uniweb/kit": "0.9.31"
   },
   "peerDependencies": {
-    "@uniweb/build": "0.14.36",
+    "@uniweb/build": "0.14.38",
     "@uniweb/content-reader": "1.1.14",
     "@uniweb/semantic-parser": "1.1.18"
   },

package/partials/agents.md

@@ -217,7 +217,7 @@ The `uniweb` block in `package.json` carries platform-specific configuration tha
 | `namespace` | `uniweb register` | (none — see scope resolution) | Legacy explicit org-namespace override. Equivalent to using a scoped `package.json::name` (`"@myorg/foundation"`). Rarely needed in modern foundations. |
 | `runtimePolicy` | `dist/runtime-pin.json` (foundation build) | `"auto-minor"` | Controls how sites using this foundation receive runtime updates. Three values: `"exact"`, `"auto-patch"`, `"auto-minor"`. See "Foundation runtime policy" below. |
 
-**How a foundation reaches the catalog.** Foundations on Uniweb hosting always live in the catalog as `@org/name@version`. Two ways to get one there, both from the same `dist/foundation.js` artifact:
+**How a foundation reaches the catalog.** Foundations on Uniweb hosting always live in the catalog as `@org/name@version`. Two ways to get one there, both from the same `dist/entry.js` artifact:
 
 - **Brought along by `uniweb publish`.** When a foundation powers a single site, don't run `uniweb register` yourself. Run `uniweb publish` from the site directory — it releases the site's local foundation to the catalog under your `@org` (when its code changed) and then goes live, in one step. No separate register ceremony.
 - **Registered deliberately with `uniweb register --scope @org`.** When the foundation is a product meant for multiple sites — listed in the catalog, consumable by other developers' sites — register it on its own schedule. Consuming sites then pin a versioned ref (`foundation: '@org/name@1.2.3'`).
@@ -845,6 +845,8 @@ seo:
 
 **Localized URLs:** On a multilingual site (`languages:` in site.yml), a page's `slug: { <lang>: <segment> }` gives it a native URL segment per language (`/about` → `/fr/a-propos`); the folder name stays the canonical route. Nested folders compose automatically, and localized URLs flow through navigation, the language switcher, and the sitemap.
 
+**Draft languages:** `publishLanguages: [en, fr]` in site.yml lists which declared languages a published build ships — unlisted ones stay dev-previewable drafts. Absent field = publish all declared; the default language must be listed.
+
 **Content-less containers:** Folders with `page.yml` but no markdown are structural groups. They appear in `getPageHierarchy()` with `hasContent: false` and their own title/label. When visited directly, the runtime auto-redirects to the first descendant with content. This supports hierarchical navigation (courses → modules → lessons) at any depth.
 
 ### Lists as Navigation Menus
@@ -976,6 +978,10 @@ contexts:
   light:
     section: '#fafaf9'        # Override individual tokens per context
 
+appearance:
+  default: light              # 'light' | 'dark' | 'system'; see Light/dark appearance below
+  allowToggle: true           # offer a visitor light/dark switch
+
 fonts:
   import:
     - url: 'https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap'
@@ -1015,6 +1021,60 @@ 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.
 
+### Light/dark appearance (scheme vs. context)
+
+Uniweb splits what other frameworks fuse into one "dark mode" into two independent ideas:
+
+- **Section context** — the `theme:` field on a section (`light` / `medium` / `dark`). It sets the color tokens for *that one section*, so a single page can move through light, dark, and colored sections. Per-section, author-controlled, covered above.
+- **Site scheme** — the global light/dark preference, configured under `appearance:` in `theme.yml`. This is the site-wide toggle a visitor flips (or that follows their OS).
+
+They compose rather than fight: a section with **no `theme:`** inherits the site scheme, so it follows the toggle; a section that **pins** `theme: dark` stays dark in either scheme. A dark-scheme site can still carry one bright white CTA; a light-scheme site can carry one dramatic dark hero. You never write `isDark ? … : …` — components built on semantic tokens (`text-heading`, `bg-card`, `border`, …) adapt to whichever scheme and context resolve around them.
+
+Configure the scheme in `theme.yml`:
+
+```yaml
+appearance:
+  default: light                # 'light' | 'dark' | 'system' (start by following the OS)
+  allowToggle: true             # offer a visitor switch (also generates the dark tokens)
+  respectSystemPreference: true # first visit follows the OS; set false to pin `default`
+  schemes: [light, dark]        # optional — declares the available set
+```
+
+Shorthand strings work too: `appearance: light` / `appearance: dark` (fixed, no toggle), `appearance: system` (follow the OS).
+
+A site **has dark mode** whenever it offers a toggle, defaults to `dark`/`system`, or lists `dark` in `schemes:`. Any such site follows the visitor's OS on first visit (unless `respectSystemPreference: false`) and remembers a manual choice. Precedence: a stored choice wins over the OS, which wins over `default:`.
+
+Common intents:
+
+| Goal | `theme.yml` |
+|---|---|
+| Always light, no switch | `appearance: light` |
+| Always dark, no switch | `appearance: dark` |
+| Toggle, follow the OS on first visit | `appearance: { default: system, allowToggle: true }` |
+| Toggle, but always start light | `appearance: { default: light, allowToggle: true, respectSystemPreference: false }` |
+
+Note that `default: light` is a *fallback*, not a guarantee: a dark OS still wins on first visit unless you set `respectSystemPreference: false` (the last row). `default: system` is just the honest way to say "there is no fixed default — use the OS."
+
+**Rendering a toggle (foundation side).** The runtime resolves the scheme and applies it to `<html>` (`scheme-dark` / `scheme-light`) *before the page paints* — you never touch `localStorage` or `document` yourself, and there's no flash of the wrong scheme. A section type only renders the button:
+
+```jsx
+import { useAppearance } from '@uniweb/kit'
+
+function SchemeToggle() {
+  const { scheme, toggle, canToggle } = useAppearance()
+  if (!canToggle) return null            // hidden unless the site enables toggling
+  return <button onClick={toggle}>{scheme === 'dark' ? 'Light' : 'Dark'}</button>
+}
+```
+
+**Tailwind `dark:` variant.** If your foundation uses Tailwind's `dark:` utilities, bind them to the site scheme (not the OS media query) so they track the toggle. In `styles.css`:
+
+```css
+@custom-variant dark (&:where(.scheme-dark, .scheme-dark *));
+```
+
+Without this, `dark:` defaults to `@media (prefers-color-scheme: dark)` and ignores the site's own light/dark setting. Prefer semantic tokens over `dark:` where you can — they adapt to per-section context, which a global `dark:` cannot.
+
 ### 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:
@@ -1201,7 +1261,7 @@ export default {
 export default { '@acme': '../shared/acme-schemas', '@brand': process.env.BRAND_SCHEMAS }
 ```
 
-Plain JS, so paths can be relative, absolute, or read from an env var. A routed scope wins over the package convention; `@/` and `@uniweb` are never routable; an empty value (e.g. an unset env var) falls back to the package convention.
+Plain JS, so paths can be relative, absolute, or read from an env var. A routed scope wins over the package convention; `@/` and `@uniweb` are never routable; an empty value (e.g. an unset env var) falls back to the package convention. A routed scope has no package fallback for a *missing* schema (it errors rather than silently load a different definition). To override a single schema — keeping the rest of the scope routed to the shared folder — add a per-schema key pointing at a file: `'@acme/person': './schemas/acme-person.yml'` (most-specific wins: file › directory › package).
 
 **Validate your data.** `uniweb validate` checks your file-based data against these declared schemas — missing required fields, type/enum/format mismatches, nested fields — before you ship. Warns by default, `--strict` for a non-zero CI exit. It's distinct from `uniweb doctor` (which checks project structure): `validate` checks your *data* against the schemas you *declared*. Remote (`url:`), `ref`/`options`, and rich `sections`-form inputs are reported deferred — validate those against live data.
 
@@ -1340,6 +1400,8 @@ import { Visual } from '@uniweb/kit'
 
 **Utilities:** `cn()` (Tailwind class merge — `cn('px-4', condition && 'bg-primary')` resolves conflicts), `Link`, `Image`, `Asset`, `SafeHtml`, `SocialIcon`, `filterSocialLinks(links)`, `getSocialPlatform(url)`
 
+> **`cn()` gotcha — a later `text-<size>` silently drops an earlier `leading-*`.** Tailwind's size classes set line height too, so `cn()` treats the size as replacing the leading: `cn('leading-[1.1] text-4xl')` → `text-4xl`. Put the size first, or fold the leading into it (`text-[clamp(2rem,5vw,4rem)]/[1.1]`). Most likely to bite when the size comes from a lookup and the leading sits in a shared base string.
+
 **Other styled:** `SidebarLayout`, `Prose`, `Article`, `Code`, `Alert`, `Table`, `Details`, `Divider`, `Disclaimer`
 
 ### Hook Signatures
@@ -1354,7 +1416,7 @@ useThemeData()      → Theme                             // programmatic color
 useColorContext(block) → 'light' | 'medium' | 'dark'   // current section context
 ```
 
-`isActive` and `isActiveOrAncestor` accept a Page object or a route string. `useAppearance` reads `appearance:` from `theme.yml` — `scheme` is `'light'`|`'dark'`, `canToggle` reflects `allowToggle` config. Stores preference in localStorage, respects system preference.
+`isActive` and `isActiveOrAncestor` accept a Page object or a route string. `useAppearance` reflects the site scheme from `appearance:` in `theme.yml` — `scheme` is `'light'`|`'dark'`, `canToggle` reflects `allowToggle`. The runtime applies the scheme to `<html>` before paint; the hook reads it, `toggle`/`setScheme` flip it and persist the choice to localStorage. First visit follows the OS when the site has dark mode. Full model: *Light/dark appearance* above.
 
 ### Icon Component
 
@@ -1622,7 +1684,7 @@ import LessonHeader from '../../components/LessonHeader'
 
 Within the same directory (e.g., one component importing a sibling), use normal relative imports (`./AIFeedbackCard`).
 
-**Foundation entry shape (`main.js`).** A single `export default { … }` whose top-level keys are the capabilities the foundation provides — e.g. `name`, `description`, `defaultLayout`, `defaultSection`, `viewTransitions`, `props`, `defaultInsets`, `xref`, `outputs`, `handlers`. Optionally a named `vars` export for theme-variable metadata (see *Foundation variables*). Everything else (section types, layouts) is auto-discovered from `sections/` and `layouts/` and merged in by `@uniweb/build`. The build wraps your default export under `default.capabilities` in the produced `dist/foundation.js`; you don't write that wrapper yourself, and most foundation code never sees it. The one place it matters: when you import your **own** `main.js` from a foundation component (e.g., a download button calling `compileDocument(website, { foundation })`), you get the bare default object — pass it through directly, Press handles both shapes.
+**Foundation entry shape (`main.js`).** A single `export default { … }` whose top-level keys are the capabilities the foundation provides — e.g. `name`, `description`, `defaultLayout`, `defaultSection`, `viewTransitions`, `props`, `defaultInsets`, `xref`, `outputs`, `handlers`. Optionally a named `vars` export for theme-variable metadata (see *Foundation variables*). Everything else (section types, layouts) is auto-discovered from `sections/` and `layouts/` and merged in by `@uniweb/build`. The build wraps your default export under `default.capabilities` in the produced `dist/entry.js`; you don't write that wrapper yourself, and most foundation code never sees it. The one place it matters: when you import your **own** `main.js` from a foundation component (e.g., a download button calling `compileDocument(website, { foundation })`), you get the bare default object — pass it through directly, Press handles both shapes.
 
 ### Website and Page APIs
 

package/src/commands/build.js

@@ -60,6 +60,7 @@ import {
   classifyPackage,
   isExtensionPackage,
 } from '@uniweb/build'
+import { resolveDefaultLocale, normalizeLanguageList } from '@uniweb/core/locale-config'
 import { readSiteConfig } from '@uniweb/build/site'
 import { readWorkspaceConfig, resolveGlob } from '../utils/config.js'
 
@@ -373,12 +374,26 @@ async function loadI18nConfig(projectDir, siteConfig = null) {
 
   // Resolve locales (undefined/'*' → all available, array → specific)
   const { resolveLocales } = await import('@uniweb/build/i18n')
-  const locales = await resolveLocales(config.languages, localesPath)
+  let locales = await resolveLocales(config.languages, localesPath)
+
+  // Publish filter: build outputs are visitor artifacts. With an explicit
+  // `publishLanguages:`, only listed locales get dist/{locale}/ content,
+  // per-locale HTML, hreflang, and translated collections. Draft locales
+  // stay previewable in dev, which doesn't run this path. Intersecting the
+  // DISK-resolved list here also covers wildcard (`languages: '*'`) sites.
+  if (config.publishLanguages != null) {
+    const publishSet = new Set(normalizeLanguageList(config.publishLanguages))
+    const dropped = locales.filter((l) => !publishSet.has(l))
+    locales = locales.filter((l) => publishSet.has(l))
+    if (dropped.length > 0) {
+      info(`Skipping non-publishable locale(s): ${dropped.join(', ')} (not in publishLanguages)`)
+    }
+  }
 
   if (locales.length === 0) return null
 
   return {
-    defaultLocale: config.defaultLanguage || 'en',
+    defaultLocale: resolveDefaultLocale(config),
     locales,
     localesDir,
   }

package/src/commands/i18n.js

@@ -19,6 +19,7 @@ import { resolve, join, dirname, basename, relative } from 'path'
 import { existsSync } from 'fs'
 import { readFile, writeFile, mkdir, readdir, unlink, rename } from 'fs/promises'
 import yaml from 'js-yaml'
+import { resolveDefaultLocale } from '@uniweb/core/locale-config'
 import {
   isWorkspaceRoot,
   findSites,
@@ -216,7 +217,7 @@ async function loadSiteConfig(siteRoot) {
   const locales = await resolveLocales(config.languages, localesPath)
 
   return {
-    defaultLocale: config.defaultLanguage || 'en',
+    defaultLocale: resolveDefaultLocale(config),
     locales,
     localesDir,
     ...config.i18n,

package/src/commands/publish.js

@@ -48,6 +48,7 @@ import {
   rewriteBallAssets,
 } from '@uniweb/build/site'
 import { emitSyncPackages } from '@uniweb/build/uwx'
+import { resolveDefaultLocale } from '@uniweb/core/locale-config'
 
 import { BackendClient } from '../backend/client.js'
 import { resolveSiteDir, resolveSiteBackend } from './deploy.js'
@@ -117,7 +118,9 @@ function languagesFromContent(siteContent) {
 
 // Languages from site.yml — used only for the dry-run summary (no build yet).
 function languagesFromSiteYml(siteYml) {
-  const def = siteYml.defaultLanguage || siteYml.lang || 'en'
+  // Legacy `lang:` still honored between defaultLanguage and the shared
+  // `defaultLanguage || languages[0] || 'en'` rule.
+  const def = siteYml.defaultLanguage || siteYml.lang || resolveDefaultLocale(siteYml)
   const locales = siteYml.i18n?.locales || siteYml.languages
   if (!Array.isArray(locales) || locales.length === 0) return null
   const norm = locales.map((l) => (typeof l === 'string' ? l : l?.value || l?.code)).filter(Boolean)

package/src/commands/register.js

@@ -454,6 +454,17 @@ async function runRegister(args = []) {
       return { exitCode: 1 }
     }
   }
+  // Registering ≠ delivering the file. A registered schema is a content type
+  // authors use in the app; a FOUNDATION build still resolves '@scope/name' from
+  // disk (a package or a routed folder). This is the moment that belief forms —
+  // you just registered it — so correct it here, not in a doc nobody's reading.
+  if (!jsonMode && defined.length > 0 && scope) {
+    log('')
+    info('Registered schemas are content types authors can use in the Uniweb app.')
+    log(`  ${colors.dim}Delivery is separate: a foundation that binds ${scope}/<name> resolves it from${colors.reset}`)
+    log(`  ${colors.dim}disk — an ${scope}/schemas package, or a folder routed in schemas.config.js.${colors.reset}`)
+  }
+
   if (jsonMode) {
     // Join my authoritative submitted names with the backend's minted ids. Each
     // response entry is `{ registered: { name, version, payload_model_uuid, … },

package/src/framework-index.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-07-23T14:06:14.245Z",
+  "generatedAt": "2026-07-24T20:04:13.283Z",
   "packages": {
     "@uniweb/build": {
-      "version": "0.14.36",
+      "version": "0.14.38",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -25,7 +25,7 @@
       "deps": []
     },
     "@uniweb/core": {
-      "version": "0.7.22",
+      "version": "0.7.24",
       "path": "framework/core",
       "deps": [
         "@uniweb/semantic-parser",
@@ -43,7 +43,7 @@
       "deps": []
     },
     "@uniweb/kit": {
-      "version": "0.9.29",
+      "version": "0.9.31",
       "path": "framework/kit",
       "deps": [
         "@uniweb/core",
@@ -61,7 +61,7 @@
       "deps": []
     },
     "@uniweb/runtime": {
-      "version": "0.8.28",
+      "version": "0.8.30",
       "path": "framework/runtime",
       "deps": [
         "@uniweb/core",
@@ -94,12 +94,12 @@
       "deps": []
     },
     "@uniweb/theming": {
-      "version": "0.1.9",
+      "version": "0.1.10",
       "path": "framework/theming",
       "deps": []
     },
     "@uniweb/unipress": {
-      "version": "0.4.43",
+      "version": "0.4.45",
       "path": "framework/unipress",
       "deps": [
         "@uniweb/build",