uniweb 1.0.0 → 1.0.2

package/partials/ai-assistance.hbs

@@ -0,0 +1,28 @@
+## Developer Guide
+
+[AGENTS.md](./AGENTS.md) is a comprehensive guide to building with Uniweb — content authoring, component development, theming, configuration, and the kit API. Despite the name, it's written for developers and AI assistants alike. Read it to get productive fast.
+
+### AI Prompts
+
+AI coding assistants (Claude Code, Cursor, Copilot, etc.) read AGENTS.md automatically. Some prompts to try:
+
+**Converting an existing design:**
+```
+I have a landing page design in `homepage.jsx`. Convert it into this Uniweb
+project. Decompose each visual section into a foundation component and extract
+all text content into markdown files in site/pages/home/. The final page
+should render identically to the original. See AGENTS.md for the full guide.
+```
+
+**Adding a new component:**
+```
+Create a Pricing component with 3-column cards. It should support light and
+dark themes. Use content.items for the pricing tiers — each item has a title,
+paragraph (price), and links (CTA button).
+```
+
+**Adding a new page:**
+```
+Add a /contact page with a hero section and a form section. Reuse the Hero
+component from the homepage. Create a new ContactForm component for the form.
+```

package/partials/components-docs.hbs

@@ -0,0 +1,13 @@
+## Component Documentation
+
+Generate up-to-date documentation for all foundation components:
+
+```bash
+# From foundation directory
+uniweb docs
+
+# Or from site directory (auto-detects linked foundation)
+cd site && uniweb docs
+```
+
+This creates `COMPONENTS.md` with details on each component's parameters, presets, and content elements. The documentation is generated from component `meta.js` files, so it's always current.

package/partials/config-reference.hbs

@@ -0,0 +1,66 @@
+## Configuration Reference
+
+### site.yml
+
+Site-wide configuration in `site/site.yml`:
+
+```yaml
+name: My Site                    # Site name
+defaultLanguage: en              # Default locale code
+foundation: foundation           # Foundation package name
+
+# Page ordering (controls top-level navigation)
+pages: [home, about, features]   # First is homepage at /
+# Or just name the homepage:
+index: home
+
+# Internationalization
+i18n:
+  locales: [es, fr]              # Non-default locales to build
+  localesDir: locales            # Translation files directory
+
+# Build options
+build:
+  prerender: true                # Enable static site generation
+```
+
+### page.yml
+
+Page-level configuration in `site/pages/[page]/page.yml`:
+
+```yaml
+title: About Us                  # Page title (used in <title> and nav)
+description: Learn about us      # Meta description
+label: About                     # Short nav label (optional)
+order: 2                         # Navigation sort order
+
+# Child page ordering
+pages: [intro, guide, reference] # First is index for this route
+index: intro                     # Or just name the index
+
+# Navigation visibility
+hidden: true                     # Hide from all navigation
+hideIn: [header]                 # Hide from named nav areas only (header, footer, sidebar, …)
+
+# Layout overrides
+layout:
+  header: false                  # Don't render header
+  footer: false                  # Don't render footer
+
+# Section ordering
+sections:                        # Explicit section order
+  - hero
+  - features:                    # Nested = subsections
+      - logocloud
+      - stats
+  - pricing
+
+# SEO
+seo:
+  noindex: true
+  image: /og-image.png
+  changefreq: monthly
+  priority: 0.8
+```
+
+Run `uniweb docs site` or `uniweb docs page` for complete reference.

package/partials/deployment.hbs

@@ -0,0 +1,13 @@
+## Deployment
+
+Build and deploy the `site/dist` folder:
+
+```bash
+pnpm build
+```
+
+**Supported platforms:**
+- **Vercel**: `cd site && vercel`
+- **Netlify**: Build command `pnpm build`, publish `site/dist`
+- **GitHub Pages**: Use GitHub Actions
+- **Cloudflare Pages**: Connect repo, set `pnpm build` and `site/dist`

package/partials/learn-more.hbs

@@ -0,0 +1,6 @@
+## Learn More
+
+- [AGENTS.md](./AGENTS.md) — comprehensive guide to building with Uniweb
+- [Uniweb Documentation](https://github.com/uniweb/docs) — full reference docs
+- [Uniweb CLI](https://github.com/uniweb/cli) — project scaffolding and build tools
+- [Tailwind CSS v4](https://tailwindcss.com)

package/partials/quick-start.hbs

@@ -0,0 +1,8 @@
+## Quick Start
+
+```bash
+pnpm install    # Install dependencies
+pnpm dev        # Start development server
+```
+
+Visit `http://localhost:5173` to see your site.

package/partials/search-docs.hbs

@@ -0,0 +1,110 @@
+## Search Functionality
+
+Uniweb sites support full-text search out of the box. Search indexes are generated automatically at build time.
+
+### Enabling Search in Your Foundation
+
+To add search to your site, your foundation needs the **Fuse.js** library:
+
+```bash
+cd foundation
+pnpm add fuse.js
+```
+
+Then use the search helpers from `@uniweb/kit`:
+
+```jsx
+import { useSearch } from '@uniweb/kit'
+
+function SearchComponent({ website }) {
+  const { query, results, isLoading, clear } = useSearch(website)
+
+  return (
+    <div>
+      <input
+        type="search"
+        placeholder="Search..."
+        onChange={e => query(e.target.value)}
+      />
+      {isLoading && <span>Searching...</span>}
+      <ul>
+        {results.map(result => (
+          <li key={result.id}>
+            <a href={result.href}>{result.title}</a>
+            <p dangerouslySetInnerHTML=\{{ __html: result.snippetHtml }} />
+          </li>
+        ))}
+      </ul>
+    </div>
+  )
+}
+```
+
+### Search Configuration
+
+Search is enabled by default. To customize, add to `site/site.yml`:
+
+```yaml
+search:
+  enabled: true
+  exclude:
+    routes: [/admin, /private]    # Don't index these routes
+    components: [Debug]            # Don't index these component types
+```
+
+### How It Works
+
+1. **Build time**: Uniweb extracts text from all pages and sections
+2. **Output**: A `search-index.json` file is generated in `dist/`
+3. **Runtime**: Components fetch and search the index client-side
+4. **Multi-locale**: Each locale gets its own search index
+
+### Search API
+
+The `website` object provides these methods:
+
+```javascript
+// Check if search is available
+website.isSearchEnabled()      // Returns boolean
+
+// Get the URL for the search index
+website.getSearchIndexUrl()    // "/search-index.json" or "/es/search-index.json"
+
+// Get full search configuration
+website.getSearchConfig()      // { enabled, indexUrl, locale, include, exclude }
+```
+
+### Search Result Format
+
+Results from `useSearch()` include:
+
+| Field | Description |
+|-------|-------------|
+| `id` | Unique result identifier |
+| `type` | `"page"` or `"section"` |
+| `route` | Page route |
+| `href` | Full link including anchor |
+| `title` | Result title |
+| `pageTitle` | Parent page title (for sections) |
+| `snippetHtml` | Excerpt with `<mark>` highlighted matches |
+| `snippetText` | Plain text excerpt |
+
+### Without @uniweb/kit
+
+If you prefer not to use the kit helpers, you can fetch the index directly:
+
+```javascript
+// Fetch the search index
+const response = await fetch(website.getSearchIndexUrl())
+const index = await response.json()
+
+// Use with Fuse.js directly
+import Fuse from 'fuse.js'
+const fuse = new Fuse(index.entries, {
+  keys: ['title', 'content'],
+  threshold: 0.35,
+  includeMatches: true
+})
+
+const results = fuse.search('your query')
+```

package/src/backend/asset-download.js

@@ -0,0 +1,222 @@
+/**
+ * Fetch the asset bytes a site project does not have locally.
+ *
+ * `pull` and `clone` bring content down; this brings the media with it, so a
+ * teammate who clones gets a project that renders instead of one full of images
+ * pointing at a host they may not even be able to reach.
+ *
+ * ## Where an asset lands, and why there are two answers
+ *
+ * - **The map knows it** (this backend's `assets` in `sync.json`) — the file goes
+ *   back to the path its author wrote. That is the whole reason the map is
+ *   committed: a fresh clone restores `public/images/hero.png`, not a hash.
+ * - **The map does not know it** — this project has never held these bytes:
+ *   authored in the app, or pushed from a machine whose map entry has not
+ *   arrived. There is no local path to guess, so it lands at a **generic,
+ *   content-addressed** one (`/assets/{id}.{ext}`) and the map gains the entry.
+ *   From then on it is a known asset like any other.
+ *
+ * ## ⛔ The URL is READ from the content, never composed
+ *
+ * Identity rides beside the reference (`sync-package.js` stamps `assetId` next
+ * to the serve URL), so the address is already on the node. Composing one would
+ * mean holding the host's route layout — the coupling deleting `buildAssetUrl`
+ * removed from this CLI, and the reason the asset map stores no URL either (only a
+ * fingerprint of one). An id with no URL beside it is skipped, not guessed at.
+ *
+ * ## ⛔ A failed download is a WARNING, never a failed pull
+ *
+ * The content still carries the URL, so a site whose bytes did not arrive still
+ * renders — from the host, as it did before. Making the pull fail would turn a
+ * degraded outcome into no outcome, and the degraded one is genuinely usable.
+ */
+
+import { mkdirSync, existsSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { ASSET_SLOTS } from '@uniweb/semantic-parser'
+import {
+  readBackendState,
+  updateBackendMap,
+  carryServed,
+  servedFingerprint
+} from '@uniweb/build/uwx'
+
+/**
+ * Collect every `{ id, ext, url }` an entity document references.
+ *
+ * Reads the same shape `rewriteEntityAssets` writes — identity on the object
+ * carrying the reference — so a ProseMirror image node's attrs and a section
+ * background's media object are both found by one walk.
+ */
+export function collectAssetRefs(document, map = {}) {
+  const found = new Map() // id → { id, ext, url }
+  const visit = (node) => {
+    if (Array.isArray(node)) return node.forEach(visit)
+    if (!node || typeof node !== 'object') return
+    for (const slot of ASSET_SLOTS) {
+      const id = typeof node[slot.id] === 'string' ? node[slot.id] : null
+      if (!id || found.has(id)) continue
+      const url = slot.urls
+        .map((k) => (typeof node[k] === 'string' ? node[k] : null))
+        .find(Boolean)
+      found.set(id, { id, ext: node[slot.ext] || '', url })
+    }
+    for (const v of Object.values(node)) visit(v)
+  }
+  visit(document)
+  // A BARE-STRING reference (`info.preview`, `seo.image`, a section param) has no
+  // object to carry identity beside it. The map recognizes it by the fingerprint the
+  // push recorded for its serve URL — see `servedFingerprint` in @uniweb/build/uwx.
+  const byServed = new Map()
+  for (const v of Object.values(map || {})) {
+    if (v?.served && v.id && !byServed.has(v.served)) byServed.set(v.served, v)
+  }
+  if (byServed.size) {
+    const visitStrings = (node) => {
+      if (typeof node === 'string') {
+        if (!node.startsWith('/') && !/^https?:\/\//i.test(node)) return
+        const entry = byServed.get(servedFingerprint(node))
+        if (entry && !found.has(entry.id))
+          found.set(entry.id, { id: entry.id, ext: entry.ext || '', url: node })
+        return
+      }
+      if (Array.isArray(node)) return node.forEach(visitStrings)
+      if (node && typeof node === 'object')
+        for (const v of Object.values(node)) visitStrings(v)
+    }
+    visitStrings(document)
+  }
+  return [...found.values()]
+}
+
+/** Where a site-root ref lives on disk. `resolveAssetPath` looks in public/ first. */
+const diskPathFor = (siteDir, ref) => join(siteDir, 'public', ref)
+
+/** The generic landing path for an asset this project has never held. */
+export const genericRefFor = (id, ext) => `/assets/${id}${ext ? `.${ext}` : ''}`
+
+/**
+ * Download the assets `document` references that are not already on disk.
+ *
+ * @param {object} opts
+ * @param {object} opts.document  - the site-content document (not mutated)
+ * @param {string} opts.siteDir   - the site root
+ * @param {string} opts.origin    - backend origin, to resolve an origin-relative URL
+ * @param {typeof fetch} [opts.fetchImpl]
+ * @param {(m: string) => void} [opts.onProgress]
+ * @param {(m: string) => void} [opts.warn]
+ * @returns {Promise<{ downloaded: string[], present: string[], failed: string[], skipped: string[] }>}
+ */
+export async function downloadMissingAssets({
+  document,
+  siteDir,
+  origin,
+  fetchImpl,
+  onProgress = () => {},
+  warn = () => {}
+}) {
+  const doFetch = fetchImpl || ((u) => globalThis.fetch(u))
+  // Read first: a bare-string reference is only recognizable through the map.
+  const map = readBackendState(siteDir, origin).assets || {}
+  const refs = collectAssetRefs(document, map)
+  const out = { downloaded: [], present: [], failed: [], skipped: [] }
+  if (!refs.length) return out
+
+  const byId = new Map()
+  for (const [ref, v] of Object.entries(map)) if (v?.id) byId.set(v.id, ref)
+
+  const learned = {}
+
+  for (const { id, ext, url } of refs) {
+    const known = byId.get(id)
+    const ref = known || genericRefFor(id, ext)
+    const disk = diskPathFor(siteDir, ref)
+
+    if (existsSync(disk)) {
+      out.present.push(ref)
+      // Still record identity for a generic ref we already hold but never mapped.
+      if (!known) learned[ref] = { id, ext }
+      continue
+    }
+    if (!url) {
+      // Identity with no address beside it. Composing one would mean holding the
+      // host's route layout; skipping is the honest answer.
+      warn(`asset ${id}: no URL in content to fetch from (skipped)`)
+      out.skipped.push(ref)
+      continue
+    }
+
+    try {
+      const res = await doFetch(new URL(url, origin).href)
+      if (!res.ok) {
+        warn(`asset ${id}: HTTP ${res.status} (kept the URL in content)`)
+        out.failed.push(ref)
+        continue
+      }
+      const bytes = Buffer.from(await res.arrayBuffer())
+      mkdirSync(dirname(disk), { recursive: true })
+      writeFileSync(disk, bytes)
+      onProgress(`↓ ${ref}`)
+      out.downloaded.push(ref)
+      if (!known) learned[ref] = { id, ext }
+    } catch (err) {
+      warn(`asset ${id}: ${err.message} (kept the URL in content)`)
+      out.failed.push(ref)
+    }
+  }
+
+  // Newly-landed assets become known ones, so the next pull restores them to
+  // this path rather than fetching them again to a second location.
+  if (Object.keys(learned).length)
+    updateBackendMap(siteDir, origin, 'assets', learned, carryServed)
+  return out
+}
+
+/**
+ * Fetch the files a pull's file records name (`@uniweb/file`) to where each lands in
+ * `records/uniweb/file/` — the list `recordsToProject` returns as `fileDownloads` — and record each
+ * one's asset under its key (`sync.json` `assets`), as a push records the upload, so the next pull
+ * knows the bytes on disk are that asset and fetches nothing.
+ *
+ * @param {object} opts
+ * @param {Array<{ url: string, path: string, ref: string, assetId?: string, assetExt?: string }>} opts.downloads
+ * @param {string} opts.siteDir
+ * @param {string} opts.origin - backend origin, to resolve an origin-relative URL
+ * @param {typeof fetch} [opts.fetchImpl]
+ * @param {(m: string) => void} [opts.onProgress]
+ * @param {(m: string) => void} [opts.warn]
+ * @returns {Promise<{ downloaded: string[], failed: string[] }>} paths
+ */
+export async function downloadFileRecords({
+  downloads = [],
+  siteDir,
+  origin,
+  fetchImpl,
+  onProgress = () => {},
+  warn = () => {}
+}) {
+  const doFetch = fetchImpl || ((u) => globalThis.fetch(u))
+  const out = { downloaded: [], failed: [] }
+  const learned = {}
+  for (const d of downloads) {
+    try {
+      const res = await doFetch(new URL(d.url, origin).href)
+      if (!res.ok) {
+        warn(`file ${d.ref}: HTTP ${res.status} — not fetched`)
+        out.failed.push(d.path)
+        continue
+      }
+      const bytes = Buffer.from(await res.arrayBuffer())
+      mkdirSync(dirname(d.path), { recursive: true })
+      writeFileSync(d.path, bytes)
+      onProgress(`↓ ${d.ref}`)
+      out.downloaded.push(d.path)
+      if (d.assetId) learned[d.ref] = { id: d.assetId, ext: d.assetExt || '' }
+    } catch (err) {
+      warn(`file ${d.ref}: ${err.message} — not fetched`)
+      out.failed.push(d.path)
+    }
+  }
+  if (Object.keys(learned).length) updateBackendMap(siteDir, origin, 'assets', learned, carryServed)
+  return out
+}