uniweb 1.25.3 → 1.25.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,52 @@
1
+ [
2
+ {
3
+ "name": "content",
4
+ "title": "Writing content",
5
+ "description": "write or restructure content, nav, layout files, SEO, math, icons, doc versions"
6
+ },
7
+ {
8
+ "name": "foundation",
9
+ "title": "Building a foundation",
10
+ "description": "build a section type, layout or inset"
11
+ },
12
+ {
13
+ "name": "theme",
14
+ "title": "Theming",
15
+ "description": "change colors, fonts, light/dark, tokens, styles.css"
16
+ },
17
+ {
18
+ "name": "start",
19
+ "title": "Starting a project",
20
+ "description": "start a project, grow the workspace, learn from a template"
21
+ },
22
+ {
23
+ "name": "data",
24
+ "title": "Data",
25
+ "description": "work with records, queries, [slug] pages, external APIs, schemas, Loom"
26
+ },
27
+ {
28
+ "name": "services",
29
+ "title": "Services",
30
+ "description": "add search, forms, tracking, an assistant"
31
+ },
32
+ {
33
+ "name": "backend",
34
+ "title": "Backend",
35
+ "description": "the site has accounts or member data (services.backend, @uniweb/api)"
36
+ },
37
+ {
38
+ "name": "i18n",
39
+ "title": "Localization",
40
+ "description": "add a language"
41
+ },
42
+ {
43
+ "name": "ship",
44
+ "title": "Shipping",
45
+ "description": "publish, deploy, push/pull, register, CI, workspaces, updates"
46
+ },
47
+ {
48
+ "name": "migrate",
49
+ "title": "Migrating",
50
+ "description": "port a React / Next / generated design"
51
+ }
52
+ ]
@@ -0,0 +1,27 @@
1
+ # Migrating from another framework
2
+
3
+ On-demand guide (`uniweb guide migrate`); AGENTS.md is assumed read. Full guide: `development/converting-existing.md`.
4
+
5
+ Don't port line-by-line. Study the source, then rebuild from first principles. Other frameworks produce far more components than Uniweb needs — expect consolidation, not 1:1 correspondence. A React site with 30+ components typically maps to 8–15 section types.
6
+
7
+ | React / conventional | Uniweb equivalent |
8
+ |---|---|
9
+ | Props with typed data | frontmatter params + `meta.js` |
10
+ | Component variants via props | `variant` param; Front Desk pattern for complex routing |
11
+ | Context / ThemeProvider | `theme:` frontmatter + semantic tokens |
12
+ | Wrapper / layout components | section nesting or custom layouts |
13
+ | Prop-drilling visuals into containers | insets — `![](@Component)` rendered via `<Visual>` |
14
+ | Content in JSX or `.js` data files | markdown → parser → `content` |
15
+ | CSS color tokens / design systems | `theme.yml` → palette shades + semantic tokens |
16
+ | `isDark ? … : …` | `text-heading` — context classes handle it |
17
+ | Per-component backgrounds | `background:` in frontmatter |
18
+ | Multiple near-identical components | one section type + `variant` param, or Front Desk |
19
+ | i18n wrapping (`t()`, `<Trans>`) | `locales/` beside `pages/` |
20
+
21
+ **Approach:** scaffold with `--template none` → named layouts for different page groups → dump legacy components under `components/` (not section types; import them from section types during transition) → create section types one at a time.
22
+
23
+ **Incremental, not a rewrite.** Level **0** — paste the original as one section type; routing and dev tooling work immediately. Level **1** — decompose into section types, consolidating duplicates via `variant` params or Front Desk. Level **2** — move content from JSX to markdown so authors can edit without code. Level **3** — replace hardcoded colors with semantic tokens so components work in any context. Each level is shippable; stopping at 1 is legitimate.
24
+
25
+ **The most common mistake** is recreating source colors as CSS custom properties — that bypasses the token system. Primary color → `colors.primary`; neutral tone → `colors.neutral`; context needs → `theme:` frontmatter. Map a source design's subtle surface variations (`--surface-base` vs `--surface-sunken`) to `background:` or token overrides in frontmatter, not to component code.
26
+
27
+ Name by purpose, not content (`TheModel` → `SplitContent`, `WorkModes` → `FeatureColumns`); UI helpers (buttons, badges, cards) go in `components/` with no `meta.js`. The four styles a ported design brings that break something — global smooth scroll, `filter: blur()` glows, `-webkit-font-smoothing` on `html`, JS entrance animations — are in the theme guide.
@@ -0,0 +1,174 @@
1
+ # Services: search, forms, tracking, assistant
2
+
3
+ On-demand guide (`uniweb guide services`); AGENTS.md is assumed read. References: `authoring/search.md`, `development/receiving-form-submissions.md`, `reference/site-configuration.md`.
4
+
5
+ ## The arrangement
6
+
7
+ A host states what it offers in the served payload's `config.services`, keyed by name. Every service resolves by one rule: **the host's offer, then the site's own address, then neither.** Drawing the UI is the foundation's job; where requests go comes from the site or its host — never a section type.
8
+
9
+ **Ask before you draw**, one predicate per service, no arguments: `isSearchEnabled()`, `isSubmitEnabled()`, `isBackendEnabled()`, `isAssistantEnabled()`, `isTrackingEnabled()`. `false` always means draw nothing. The hooks that draw a feature return the same answer (`useSearch().isEnabled`, `useFormSubmit().canSubmit`). For the address itself:
10
+
11
+ ```jsx
12
+ const { url, source } = resolveService(website, 'assistant') // or 'search', or your own name
13
+ ```
14
+
15
+ A synchronous read, not a request — the answer was settled at publish and travels in the site's metadata. Absent is the answer, not a lookup that failed. `source` (`'site'`, `'host'`, `null`) is a diagnostic for you while wiring a site up; `'host'` with a null `url` means the host answered and offered no address. The name is open: a foundation can define a service the framework never heard of (`website.isServiceEnabled('booking')`) and a host can fill it.
16
+
17
+ Absence is a rendering decision, not a message. No assistant → no Ask-AI affordance; no submit endpoint → no form, or degrade to a `mailto:` the site already carries. Text a visitor reads is site content, authored and localized.
18
+
19
+ ### `services:` in `site.yml`
20
+
21
+ ```yaml
22
+ services:
23
+ search: true # on — the host's, or the built-in index
24
+ submit: false # off
25
+ tracking: https://collector.example.com/events # an address of your own
26
+ backend: { grade: pro } # on, with the service's own settings
27
+ records: true # deliver records with a data schema to published pages
28
+ google: { id: G-XXXXXXXXXX } # Uniweb Cloud loads Google's tag; a static build ignores it (Tracking)
29
+ ```
30
+
31
+ An entry is `true`, `false`, an address (a string, or `endpoint:` in a map), or a map of options (`records` and `google` take no address); anything else stops the build and the push. `yes`/`no`/`on`/`off` are text in YAML — write `true`/`false`. On a site you push or publish it is also what you ask the host for: `true` asks for its service, `false` turns it off, an address asks the host to leave its own off so yours answers. **A hosted site's services are off unless `services:` asks** — list the ones the site uses. Turn `records: true` on before publishing a page that shows schema records (a static build ignores it; `publish` warns). An entry says everything about its service: removing a setting removes it on the next push; removing the entry switches it off. `push`/`publish` send each service listed; one turned on in the app since your last pull is left alone; one changed on both sides stops the push — `uniweb pull`, then push. `uniweb pull` writes what the site has into `services:`. A change that needs payment is settled in the app (`publish` opens it). Everything in an entry is public except `backend`'s settings; a key or token is set in the app.
32
+
33
+ ### Declaring what your foundation supports
34
+
35
+ ```json
36
+ { "uniweb": { "supports": ["search", "submit"] } }
37
+ ```
38
+
39
+ A service only does something if the foundation renders against it, and a host can't otherwise know. The build derives the set from what the bundle reaches (`resolveService(website, 'search')`, `isSearchEnabled()`), so an undeclared foundation still publishes an accurate set; what you write is a supplement (union), and only needed for a service reached through a computed name (`resolveService(website, name)` — the build warns). `[]` means none, proven by the build; absent means unknown. Never list `tracking`: the runtime reports for every foundation, so the build drops the name with a warning. `uniweb doctor` compares declared with found.
40
+
41
+ ## Search
42
+
43
+ ```yaml
44
+ services:
45
+ search:
46
+ provider: index # default
47
+ ```
48
+
49
+ | Provider | Answers with | Trade-off |
50
+ |---|---|---|
51
+ | `index` | `search-index.json`, ranked in the browser | free, any host, typo-tolerant; only what existed at build time |
52
+ | `endpoint` | a server-side search API | covers API-fetched records, re-indexable without rebuild; needs a host that serves one |
53
+ | any other name | a foundation-supplied search transport | Typesense, Meilisearch, Pagefind, a vendor API |
54
+
55
+ With `provider: endpoint`, `endpoint:` is **required** (no default): `_search` resolves against the base path (`/` → `/_search`); an absolute URL points elsewhere. `search: true` asks a host for its own search; an endpoint of your own asks it to leave its off.
56
+
57
+ **Results have one shape.** Always: `id`, `type` (`page` | `section` | `record`), `route`, `href`, `title`, `pageTitle`, `excerpt`, `snippetHtml`. Provider-optional (`null` when absent): `sectionId`, `anchor`, `description`, `component`, `snippetText`, `matches`, `group`, `item` (a record's fields). Guard optionals (`result.item?.image`). `snippetHtml` is HTML with `<mark>` — render through `SafeHtml`. A failing provider falls back to the local index when one exists, else returns no results with a console warning.
58
+
59
+ ```jsx
60
+ const { results, isLoading, query, isEnabled } = useSearch(website) // `query` is a debounced function
61
+ ```
62
+
63
+ Never hardcode a search endpoint in a component.
64
+
65
+ ## Forms
66
+
67
+ A form's destination, in order: (1) one the host supplies — `submit: true` under `services:` asks for it, naming no address; (2) `submit: <url>` of the site's own (static site, or a host without form handling — on a host that handles forms, it asks the host to turn its off); (3) neither → render no form, or fall back to contact details the site carries. In `uniweb dev` the dev server answers `submit: true`; each submission prints in the terminal and lands in `.uniweb/dev-submissions/`.
68
+
69
+ ```jsx
70
+ const { submit, status, error, canSubmit } = useFormSubmit({
71
+ block, context: { formId: 'contact' },
72
+ summary: (v) => ({ title: v.name, subtitle: v.email }),
73
+ })
74
+ if (!canSubmit) return null // check at render, not on the button press
75
+ ```
76
+
77
+ `status`: `idle → submitting → success | error`; a non-2xx becomes a thrown `Error` carrying the endpoint's `error` message. File fields: pass `files`; the endpoint replies with `uploadUrls`, and bytes never ride inside the JSON. `submitForm()` / `resolveSubmitTarget(website)` are the same without React. A failed read leaves its key `null`, with the message on `block.dataError[key]`; a write that 404s loses what a person typed, so it gets no silent fallback.
78
+
79
+ **Rendering an author-designed form** (`yaml:form` at `content.data.form`): you don't declare the fields, you receive them. `useFormValues` owns what's identical in every such component:
80
+
81
+ ```jsx
82
+ const { controls, values, setValue, missing, formData, files } = useFormValues(content.data.form)
83
+ const { submit, canSubmit, status } = useFormSubmit({ block })
84
+ {controls.map((c) => (
85
+ <MyControl key={c.path} control={c} value={valueAt(values, c.path)} onChange={(v) => setValue(c.path, v)} />
86
+ ))}
87
+ <button disabled={!canSubmit || missing.length > 0} onClick={() => submit(formData, { files })}>
88
+ ```
89
+
90
+ Use `valueAt(values, path)`, never `values[c.path]`: `values` is nested, so a control at `address.street` lives at `values.address.street` and indexing by path yields `undefined` — a form that renders blank and submits empty. `missing` is the `required` controls still empty, unenforced. **Submit `formData`, not `values`:** a `File` in `formData` would serialize to `{}`, so file controls ride in `files`, each tagged with its control; `values` keeps the `File` for display.
91
+
92
+ ## Tracking
93
+
94
+ One **tracking destination** per site; everything worth counting is an event on a single stream.
95
+
96
+ ```yaml
97
+ services:
98
+ tracking: https://collector.example.com/events # your own collector
99
+ # or
100
+ tracking: { endpoint: /collect, consent: required }
101
+ # or, on a published site
102
+ tracking: true # the host's
103
+ ```
104
+
105
+ The endpoint must accept the framework's batched `{ "events": [ … ] }` POST (`reference/site-configuration.md`) — not a vendor's own API. A vendor script goes under `services.tracking.scripts`, loaded once, after consent when gated, never in a frame or during prerender — a separate path; nothing you `track()` reaches it. On a site you publish, an entry with no endpoint also asks the host for its collector; `enabled: false` beside `scripts` loads the script alone.
106
+
107
+ ### Google Analytics, Tag Manager, Meta's pixel
108
+
109
+ **A `scripts` entry is a URL and nothing else, so these can't be installed that way.** Each one's install runs inline lines; from a URL alone GA sends nothing and Tag Manager never gets its page-load event. A tag carrying an attribute the vendor reads (`data-domain`, `data-website-id`) has the same problem. What works depends on who builds the pages:
110
+
111
+ - **The framework builds them** (`uniweb export`, `uniweb deploy --host=<adapter>`): the vendor's snippet goes in `head.html` next to `site.yml`, and the build adds it to every page's `<head>`. A `services.google` entry does nothing here.
112
+ - **Uniweb Cloud builds them** (`uniweb publish`): `head.html` is kept and synced but **not applied**. For Google's two, name the ID and the host loads the tag from the next publish, with no code, on any foundation:
113
+
114
+ ```yaml
115
+ services:
116
+ google:
117
+ id: G-XXXXXXXXXX # or GTM-XXXXXXX, or a list of both
118
+ ```
119
+
120
+ The app's site settings edit the same entry; a pull or push carries a change across. Leave `services.tracking.scripts` unset beside it — a site's own list replaces what the host states, so Google's tag would not load. `tracking: { enabled: false, consent: required }` beside it holds the tag until a visitor answers, and needs a component using `useTrackingConsent()`, or it never loads. Gate that component on the hook's `status`: `isTrackingEnabled()` is false here. Any other such vendor has to run from the foundation's code, so a site whose foundation you can't change can't add one — say so rather than writing a `head.html` that does nothing.
121
+
122
+ Either way, tell the person to check Realtime from a browser that doesn't block trackers: a visit from Brave, say, never reaches Google, which looks like a failed install. Google Analytics counts each page a visitor moves to through the browser-history setting, under Enhanced measurement in the data stream's settings, which a new stream has on.
123
+
124
+ A Tag Manager container needs nothing more, so don't present what follows as limits; use it if it comes up. A tag that doesn't follow page changes on its own, unlike Google Analytics or Meta's pixel, uses Tag Manager's *History Change* trigger, as on any site that changes pages without reloading. Tag Assistant shows the tags that fired, and Google doesn't report a mistyped ID as an error. If a container already sends to a Measurement ID, list only the container, so pages aren't counted twice. Foundation code sends a container its own events with `(window.dataLayer = window.dataLayer || []).push({ event: 'name' })`; `track()` doesn't reach Google.
125
+
126
+ ### Events
127
+
128
+ **Free events** — reported for you, however the foundation renders, when `emit` includes them:
129
+
130
+ | Event | When |
131
+ |---|---|
132
+ | `page_view` | every route change, including the first |
133
+ | `outbound_click` | a link off the site — the destination **host** only |
134
+ | `section_view` | a section first half-visible, unless `emit` or the page's `trackSections` says no |
135
+ | `conversion` | a phone or email tap (`name: phone`, `email`); a link or page listed in `services.tracking.conversions`; a form accepted by a provider of the site's own through `useFormSubmit`; a sign-up through `@uniweb/api` |
136
+ | `engagement` | a sign-in through `@uniweb/api` (`name: sign_in`) |
137
+
138
+ A `services.tracking.conversions` list is public (it is in every page's data), so a listed link must not carry a token. **Don't write your own listener for any of these, and don't report a sign-up, sign-in or accepted form that goes through kit or `@uniweb/api`** — a second report double-counts.
139
+
140
+ ```jsx
141
+ block.track('video_milestone', { milestone: 50 }) // in a section type — attaches page path and section type
142
+ block.track('conversion', { name: 'quote_requested' }) // what only your foundation can see that a site counts
143
+ const { track } = useTracker() // elsewhere
144
+ track('brochure_download', { file: 'specs.pdf' })
145
+ ```
146
+
147
+ Event names are yours; nine are already in use — the five above, `video_milestone` (kit's `<Media>`), `read_depth` (below), and `section_click` and `time_on_page` under `emit: all`. Put the varying part in a field, never in the name. Never guard a `track()` call: with no destination it does nothing and never throws.
148
+
149
+ **`emit`** chooses what the site sends: `minimal` (`page_view`), `standard` (the default with your own endpoint: `page_view`, `outbound_click`, `section_view`), `all` (a standing yes, future events included), or a list of names. So with your own endpoint, `conversion` and `engagement` take `emit: all` or a list naming them; a `conversions` list turns on what it lists by itself. Needs no endpoint of its own — on a host-supplied collector, saying nothing sends whatever the host declares it collects, and naming `emit` pins it. `emit` never limits your own `track()` calls. **`flushIntervalMs`** widens the batching window (default 5000; `30` is thirty milliseconds).
150
+
151
+ **`trackSections`** in `page.yml` overrides the site for `section_view` in both directions — the one event with a per-page control, because its cost scales with page length.
152
+
153
+ **Reading depth** in a long-form section: `useReadingDepth({ ref, block })` reports `read_depth` at 25/50/75/100% of that element, once each. A hook rather than automatic because only you know a section is long-form reading.
154
+
155
+ **Consent:** with `consent: required`, tracking buffers until the visitor answers — granting sends, denying discards:
156
+
157
+ ```jsx
158
+ const { status, grant, deny } = useTrackingConsent()
159
+ if (status !== 'pending') return null
160
+ return <CookieBanner onAccept={grant} onReject={deny} />
161
+ ```
162
+
163
+ Every event carries an opaque `visit` key, generated at page load, in memory only. **Never sent:** visitor id, fingerprint, cross-tab or multi-day session, anything written to the device. A `page_view` carries the path, two booleans about the load (`first_of_load`, `continues`), and the external referrer and `utm_*` captured once at first load.
164
+
165
+ ## Assistant
166
+
167
+ The service name is `assistant`; a host that runs an agent typically serves it at `/_agent`. Never write that path:
168
+
169
+ ```jsx
170
+ const { url } = resolveService(website, 'assistant')
171
+ if (!url) return null // no agent on this site — render nothing or a static fallback
172
+ ```
173
+
174
+ No `url` means the site has no agent — never enabled, or this host runs none. Don't retry it, don't hardcode `/_agent/chat` (on a static host that's a 404 indistinguishable from a broken endpoint), and don't tell the visitor. A live agent that errors mid-conversation is ordinary request failure, handled where you make the request. Knowledge pages that feed an assistant: content guide.
@@ -0,0 +1,116 @@
1
+ # Shipping: hosting, Uniweb Cloud, sync, registering, staying current
2
+
3
+ On-demand guide (`uniweb guide ship`); AGENTS.md is assumed read — in particular §3 step 1: `uniweb status` first, never `--force` past a refusal, going live and spending are the person's decisions. For flags, `uniweb <command> --help` is always current.
4
+
5
+ ## Commands
6
+
7
+ ```bash
8
+ uniweb deploy # its default target; with none, a wizard (terminal only) picks one, or sets up CI
9
+ uniweb deploy --host=<adapter> # build + upload now, from this machine
10
+ uniweb add ci --host=<adapter> # CI so every push deploys — usually best for a free host
11
+ uniweb export # build dist/ for any static host (no account)
12
+ uniweb publish # ship to Uniweb hosting, foundation included (needs login)
13
+ uniweb add ci --target foundation # publish a foundation at permanent versioned URLs (GitHub Pages)
14
+
15
+ uniweb status # what changed in the app, in git and in Uniweb — and what to run (--json)
16
+ uniweb push / pull / clone # git-style content sync with the backend
17
+ uniweb refresh / sync # catch up (git + backend, never pushes) / catch up, then push
18
+ uniweb login [--server <url>] [--org @acme | --personal] [--token <bearer>] / logout
19
+ uniweb org list / create <handle>
20
+ uniweb register [--scope @scope] # register a foundation + its schemas
21
+ uniweb forget --all | --server <url>
22
+ uniweb content export [dir] # package a site (or a built foundation's schema) as .uwx
23
+ uniweb snapshot [--compare | --share] # public/preview.webp (--share: public/share-card.png); needs @uniweb/snapshot + Chrome/Edge
24
+ uniweb -v # CLI version (a global install also says whether newer exists)
25
+ npx uniweb@latest update --yes # align @uniweb/* deps + AGENTS.md; --yes answers the prompt (no tty), --dry-run previews
26
+ ```
27
+
28
+ ## Where a site can live
29
+
30
+ No lock-in and no default you're pushed toward:
31
+
32
+ | Path | Command | Good for |
33
+ |---|---|---|
34
+ | Free static host, via CI | `uniweb add ci --host=<adapter>` | most self-hosted sites — one command, then every push deploys |
35
+ | Free static host, from this machine | `uniweb deploy --host=<adapter>` | one-off or manual deploys |
36
+ | Any static host | `uniweb export` | full control; no account |
37
+ | Uniweb Cloud | `uniweb publish` | non-technical content authors, client work |
38
+
39
+ Adapters: `github-pages`, `cloudflare-pages`, `netlify`, `vercel`, plus `s3-cloudfront` for `deploy`. On Cloudflare Pages / Netlify / Vercel, `add ci` also adds per-PR previews. With nothing configured, `deploy` opens a picker and records the choice in `deploy.yml` beside `site.yml` — **the CLI writes it**; later deploys rewrite only `deploys:`; edit `targets:` to change where a site ships. A bare `deploy` goes to the default target, and when that's the `host: uniweb` target a publish recorded, it runs `publish`. Host credentials come from the environment. GitHub runs workflows only from the top of a repository: in a project that is a folder of a larger repo, its own `.github/` never runs — `status` says so and `add ci` refuses to write one there.
40
+
41
+ **Three independent facts** `status` opens with:
42
+
43
+ - **Synced** — the project has a site on a backend (`sync.json` names it per backend: `https://uniweb.app` by default, or `uniweb login --server <url>`), so authors can edit in the Uniweb app.
44
+ - **Published** — that backend serves it live (Uniweb Cloud). A publish is recorded in `deploy.yml` under a `host: uniweb` target; where visitors go now (a custom domain) is the backend's answer.
45
+ - **Deployed** — a build is on another host, by CI or by hand.
46
+
47
+ A site can be in more than one place. `publish` makes a change live on Cloud, `git push` on a CI-deployed host, `uniweb deploy --target <name>` on a hand-deployed one — each the person's to decide. `status` also lists the services the live site has (`services:` in `site.yml` is the request, not proof).
48
+
49
+ ## Uniweb Cloud and the two-sided workflow
50
+
51
+ **Authors work visually in the Uniweb app** — same extended markdown, same params, through a visual editor, never touching git or the CLI. Every `meta.js` is registered as the foundation's schema when you publish; `meta.js` is the app's UI.
52
+
53
+ **One Uniweb workspace at a time.** The app's workspaces — not the pnpm one — are where sites and entities live: personal, an organization's, or a project space inside one (`@studio:acme`) for a customer or a purpose. Every push, pull and publish works in the workspace chosen at `uniweb login`. A site a push or publish *creates* is owned and billed there; moving it to another workspace, or transferring it to a new owner, is done in the app, not from the CLI. A site the backend keeps in another workspace stops the command. Already logged in, `uniweb login --org @other` / `--personal` switches without logging in again; `uniweb push --org @acme` for one command. **Without a terminal, a login with organizations and no workspace named signs you in but exits 2** — `uniweb login --org @acme` finishes it. A process using `UNIWEB_TOKEN` names its workspace with `UNIWEB_WORKSPACE=@acme` (or `personal`). Backend commands and `dev` reject unknown flags (`Unknown flag` — read the suggestion); `update`, `deploy` and `export` ignore them, so check the spelling.
54
+
55
+ **Sync is developer-only and one-sided.** The app is the live source of truth for content; git is the reviewed, durable record. Authors never push or pull.
56
+
57
+ **Nobody's work is overwritten without asking.** `push` is refused if the site changed on the backend since your last pull, and reports what changed. In a git repository `pull` merges like `git pull`: it commits the backend's content (*"The site's content on …"*) and merges into your branch against the last shared state. Your work and a teammate's are kept; a file the backend never had is never deleted; only a genuine overlap leaves conflict markers and a non-zero exit — settle it as in any merge, then `git commit` (where your uncommitted changes overlap, settle, `git add`, then `git stash drop`). A push or publish is refused while a file is in conflict. **In a repository a push sends what you have committed**: uncommitted site content is refused before anything is sent — commit, or `uniweb push --commit -m "…"` (commits the site's content only; `publish` and `sync` take `--commit` too). The ids the backend assigns are committed by the push itself, as `uniweb`. A push is also refused when your branch doesn't hold what this copy last took from the backend (after `git merge --abort`, or a fresh clone) — pull, then push. Outside git (including a folder the surrounding repo ignores), `pull` takes the backend's version over your files, asking first. `--force` is the deliberate overwrite in either direction. `sync` is `refresh` then `push`; neither publishes.
58
+
59
+ **Working on a site others edit:** `status` when you begin, when you come back, before push/publish/deploy, after any refusal. It reads the backend without taking anything: what changed file by file, what you hold that it lacks, who has a page open in the app right now, what in the project is uncommitted (an update, foundation source — a push neither sends nor waits for that, but a push or publish releases a changed foundation from the files). Take what changed (`pull` or `refresh`) before you edit; when someone has a page open in the app, tell the person before changing that page.
60
+
61
+ **Moving a synced project to another repository.** Where the copy last met the backend lives in git history and `.uniweb/` (not in git); `sync.json` comes along. `uniweb sync` in the old copy, copy the project without `.git/`, commit, sign in to the site's Uniweb workspace, `uniweb pull` once. If the old copy hadn't synced, `status` says the copy shares no history and lists the files that differ; the first pull makes each a conflict — settle by what you know (an app edit since the last push is the backend's side), never `--force`.
62
+
63
+ **`sync.json`** says which site this is, on each backend; the first push records the ids the backend assigned and commits it. Never edit it. **A copy of a project carries the original's `sync.json`** — `uniweb forget --all` before the copy's first push, or the push updates the original's site. It also deletes `deploy.yml`, whose targets are the original's. A copy inside the same pnpm workspace is refused until then; one outside it isn't noticed. `forget --server <url>` removes one backend's records. A record file's `$uuid` is its own and stays. Backend commands go to the backend you're logged in to (`login --server <url>` switches; a bare `login` is uniweb.app).
64
+
65
+ **`services:` in `site.yml`** is both the site's declaration and, on a pushed/published site, what you ask the host for — see the services guide for the format. A change that needs payment is settled in the app (`publish` opens it).
66
+
67
+ **The Cloud also provides a real backend for structured data**: a database per registered schema, and a CMS that edits page content and typed data entities. Either side can publish; the same foundation and site run under `dev`, `export`, or CI with no account.
68
+
69
+ ## Publishing vs registering
70
+
71
+ Foundations on Cloud live in the catalog as `@org/name@version` (`name` from `main.js`). When a foundation powers one site, **don't run `uniweb register` yourself** — `uniweb publish` from the site releases the local foundation (when its code changed) and goes live in one step. A registered version is immutable, so a changed foundation is released under the next **patch** version, written into its `package.json` and committed by the push in a git repository (`--no-release` sends content only). For a change that isn't backwards compatible, set a higher minor/major yourself first. They stop when the registry holds a newer version released from another copy: pull it, or `--bump` to release above it. Register deliberately only when the foundation is a product for multiple sites; consuming sites pin `foundation: '@org/name@1.2.3'`. **The catalog is private and access-segregated** — people see only foundations licensed to sites they own or edit; the site carries the license. Schemas can be registered on their own from a schemas-only package (`@org/schemas`, or a bare `schemas/*.{yml,json,js}` folder). Auth via `uniweb login` or `UNIWEB_TOKEN`; preview with `--dry-run`.
72
+
73
+ **Extensions.** An extension is a foundation: register it (`uniweb register` in its directory) and reference it like one. A site-relative URL (`/effects/entry.js`) works only where the site serves its own files (`export`, `deploy --host`); a site published to Uniweb hosting ships no JS, so `publish` rejects it and points to the catalog-ref form. A workspace-local extension is brought along by `publish` exactly as the primary is — released if its code changed, pinned on the published site.
74
+
75
+ **Scope.** A foundation's name is `name` in `main.js`; the scope is part of it (`'@acme/marketing'`). A name with no scope is unregistered: the first `register` takes `--scope`, else the scope of the Uniweb workspace you're logged in to (an org's, or your personal `@<handle>`), asks at a terminal when you belong to orgs and chose none, refuses without one, and writes it into the name. Its own schemas register under the same scope. Once registered the scope is fixed — and it is independent of the workspace any site using the foundation lives in; sites move, scopes don't.
76
+
77
+ ## Staying current
78
+
79
+ ```bash
80
+ uniweb status # names a newer Uniweb release than this project runs
81
+ uniweb doctor # report drift, change nothing
82
+ npx uniweb@latest update --dry-run # preview
83
+ npx uniweb@latest update --yes # align @uniweb/* deps AND refresh AGENTS.md together; --yes because no tty answers the prompt
84
+ ```
85
+
86
+ When `status` names a newer release, take it: update, restart any running dev server, build, look at the pages, commit what changed. A foundation is a federated ES module that links to the runtime at load time, like a shared library: the contract between them is stable across releases, and the runtime version a foundation was built against is a floor, not a pin. A hosted site moves forward when it is republished, to a runtime at or above its foundation's floor. The docs describe the latest release; a project that is behind should move, not be documented as it is. A **patch** brings fixes and features; a **minor** is where breaking changes go (`update` lists each package crossing one — build and check before shipping); a **major** is for something big. Dependencies are tilde ranges (`~1.0.1`), so `pnpm install` never crosses a minor on its own.
87
+
88
+ **Write `@latest`.** In a project, `uniweb` resolves to the copy in your own `node_modules`, pinned by your own `package.json`; it reconciles against the matrix it already has and correctly reports nothing to do. `pnpm uniweb update` and a stale global install are the same. `@latest` makes it a question about the newest release and bumps the pin. Don't `npm update` / `pnpm update` the `@uniweb/*` packages — a matched set, and it won't refresh AGENTS.md, so the guide silently drifts from the code. `update` won't refresh AGENTS.md while declared deps lag the CLI or edited deps aren't installed. Updating the CLI itself is your package manager's job (`npm i -g uniweb@latest`).
89
+
90
+ `uniweb update` rewrites AGENTS.md each version and keeps only blocks between a `<!-- project-notes:start -->` line and a `<!-- project-notes:end -->` line, which it moves to the end (markers that don't pair leave the file as it is) — keep project conventions in a file of your own (`NOTES.md`) and point to it from that block.
91
+
92
+ ### Retired forms — most stop the build or a push; write the right-hand column
93
+
94
+ | Retired | Now |
95
+ |---|---|
96
+ | `data:` in a section's frontmatter (old name for `query:`) | `query:` / `fetch:` |
97
+ | `route:` on a query | the record's `$route` |
98
+ | `refine: true`, `detail: false` on a fetch | `current: only / exclude / include` |
99
+ | `filter:` on a query or fetch | `where:`, a where-object |
100
+ | `under`, `like` in a `where:` | `scope:`; `starts_with`, `ends_with`, `contains` |
101
+ | `merge:` on a fetch; `sync:` on a query | a fetch fills the key it names; every file in `records/` is pushed, unless its name starts with `_` |
102
+ | `deferred:` on a query; `'@std/article/*'` | the schema's brief decides what a list holds; `whole: true` on the data key |
103
+ | `path`, `url`, `method`, `body`, `transform`, `detail`, `scope` on a `fetch:`; `detailUrl:` | on the query (`url:`, `record:`, `scope:`) |
104
+ | `fetcher.baseUrl / headers / envelope / supports / request.*` | a transport under `fetcher.transports` |
105
+ | top-level `search:`, `submit:`, `assistant:`, `tracking:`, `api:`; `services.api`; `$devApi` | `services.<name>`; `services.backend`; `$devBackend` |
106
+ | `published: false` on a record | `draft: true` |
107
+ | `slug:` key in a record file; a file holding a list | the file name is the record's name; one record per file |
108
+ | `[dir]` / `[path]` as parametric folder names; a folder inside `[...path]/` | `[slug]`, `[uuid]`, `[<field>]`, `[...path]` |
109
+ | `fonts.mono` | `fonts.code` |
110
+ | `seo.baseUrl`; `seo.defaultImage`; `seo.locales`; `url:`, `trailingSlash:` in `site.yml` | `seo.origin` (scheme + host, no path); `seo.image`; `languages:`; `seo.origin` again |
111
+ | `creatable_by` in a schema | models are open; protect with `append_only`, `readable_with`, `grantable` |
112
+ | `uniweb.id`, `uniweb.scope` in a foundation's `package.json` | `name: '@scope/name'` in `main.js` |
113
+ | `main.jsx`, `foundation.js`; JSX in a `.js` component | `main.js` (plain JS); `.jsx` |
114
+ | `visuals:` in `meta.js`; `data` as a `content:` element | a `media:` element in `content:`; declare the tag in `data:` |
115
+ | `versions:` in a folder | a folder named `v1` (`uniweb add version`) |
116
+ | `runtimePolicy: auto-patch / auto-minor` | omit; the framework doesn't read it |
@@ -0,0 +1,73 @@
1
+ # Starting a project
2
+
3
+ On-demand guide (`uniweb guide start`); AGENTS.md is assumed read.
4
+
5
+ ## Scaffold with the CLI — never by hand
6
+
7
+ ```bash
8
+ npx uniweb@latest create my-project --template marketing
9
+ cd my-project && pnpm install
10
+ npx uniweb dev
11
+ ```
12
+
13
+ Never hand-write `package.json`, `vite.config.js`, `entry.js`, or `index.html`. The CLI resolves correct versions and structure; hand-written config is the most common way to end up with a project that can't build.
14
+
15
+ `@latest` matters: a project starts on the packages and templates of the CLI that creates it, and a bare `npx uniweb` runs a globally installed `uniweb` when there is one, however old.
16
+
17
+ **Templates.** `--template <name>` gives a working site plus a foundation to study and edit. `--template none` gives the same two packages with no content — right for building a foundation from scratch or porting a design. `--blank` gives an empty workspace and assumes you'll add packages with `uniweb add`; use it only if you already know the framework.
18
+
19
+ Official templates (`uniweb template list` shows all): `marketing` (tokens, insets, grids, multi-line headings), `docs` (sidebar nav, code highlighting), `blog` (records of `@std/article`, a query, a parametric `[slug]` page), `dynamic` (live API data, loading states), `international` (i18n, records, multi-locale routing), `store` (product grids, e-commerce), `academic` (publications, timeline, math), `extensions` (multi-foundation, runtime loading), `conference` (a worked example of the `backend` service).
20
+
21
+ **npm or pnpm.** Projects include both `pnpm-workspace.yaml` and npm workspaces. Replace `pnpm` with `npm` in any command (`npm run build`, `npm run dev`).
22
+
23
+ ## What you get
24
+
25
+ ```
26
+ my-project/
27
+ ├── src/ # the foundation — component developer's domain
28
+ ├── site/ # the site — content author's domain
29
+ └── pnpm-workspace.yaml
30
+ ```
31
+
32
+ A site is pure content. A foundation is the site's source code, which is why it lives in `src/`. The foundation's `package.json::name` is `src`, symmetric with `site` — a **workspace** name, how the site depends on it. What the foundation **registers as** (`@org/<name>`, the name sites pin) is `name` in its `main.js`, which `uniweb create` sets to the project's name. `uniweb register` refuses `src`, `foundation` and anything under `@uniweb`.
33
+
34
+ - **Foundation** (`src/`): React components. Those in `sections/` and `layouts/` are section types — selectable by authors via `type:`, or used for layout areas. Everything in `components/` and `utils/` is ordinary React and JS, not visible to authors.
35
+ - **Site** (`site/`): sections written in markdown, which parse into the content object a section type receives, and configuration, plus optional records and the queries that reach them or an external data source.
36
+
37
+ ## Growing the workspace
38
+
39
+ ```bash
40
+ uniweb add project docs # co-located pair → docs/src + docs/site
41
+ uniweb add foundation [name|path] [--path parent] # no name → ./src/, bare name → ./name/, slash → that path
42
+ uniweb add site [name|path]
43
+ uniweb add extension <name> [--site <name>] # secondary foundation; wired to the site named, or the only one
44
+ uniweb add section Hero [--foundation ui] # sections/Hero/{index.jsx,meta.js}
45
+ uniweb rename <foundation|site|extension> <old> <new> # rename across the whole workspace
46
+ ```
47
+
48
+ The CLI creates exactly the folder you ask for — no silent nesting under `foundations/` or `sites/`. If the target folder exists or another package of the same kind has the name, it stops with a precise error and suggests alternatives; a name held by the other kind gets a suffix (`add site marketing` beside a foundation named `marketing` makes `marketing-site`). `uniweb add section` scaffolds a starter the dev server picks up with no build or install.
49
+
50
+ Workspace layouts and their wiring (single, segregated, co-located, projects with several sites): `development/project-structures.md`. The same `@scope/name` shape means different things by position: a `foundation:` value is a catalog ref; a data-schema ref in `meta.js` resolves from an npm package (`@uniweb/schemas`, `@org/schemas`); `@uniweb/kit` in `dependencies` is an ordinary npm package.
51
+
52
+ ## Learn from a working template
53
+
54
+ When unsure how to implement a pattern — data fetching, i18n, layouts, insets, theming — read a real one instead of guessing:
55
+
56
+ ```bash
57
+ uniweb add project marketing --from marketing
58
+ pnpm install
59
+ ```
60
+
61
+ That creates `marketing/src/` + `marketing/site/` alongside your project. No need to build or run it. Read `marketing/src/sections/` (components with `meta.js`), `marketing/site/pages/` (real content → component mapping), and `marketing/site/theme.yml` + `site.yml`. It downloads the template, and the install needs the network too; reading it afterwards doesn't. Install several if you like. To run one: `cd marketing/site && pnpm dev`.
62
+
63
+ ## The loop
64
+
65
+ ```bash
66
+ uniweb dev # the site you are in; from the workspace root, it picks one for you
67
+ pnpm build # production build (SSG + SPA)
68
+ pnpm preview # preview the production build
69
+ ```
70
+
71
+ Markdown, `theme.yml`, and component edits hot-reload. New section types are picked up without a restart.
72
+
73
+ `uniweb dev` takes a free port and prints `Serving <site> at <url>` once the server listens — read it, never assume a port; the usual port may be another project's server. Run it in the background when you need your shell back: `uniweb dev --status` prints the address later, a second `uniweb dev` points at the running server instead of starting another, and `uniweb dev --stop` stops it. These know the server `uniweb dev` started, not one started with `vite` or `npm run dev` inside the site. Pass `--port <n>` only when a port is required: you get that one or an error, never another.
@@ -0,0 +1,123 @@
1
+ # Theming: tokens, light and dark, `theme.yml`, fonts, `styles.css`
2
+
3
+ On-demand guide (`uniweb guide theme`); AGENTS.md is assumed read. Author's view: `reference/site-theming.md`.
4
+
5
+ ## Semantic tokens
6
+
7
+ | Token | Purpose |
8
+ |---|---|
9
+ | `heading`, `body`, `subtle` | text |
10
+ | `section`, `card`, `muted` | section background, panel background, hover/zebra |
11
+ | `border`, `ring` | lines, focus |
12
+ | `link` / `link-hover` | links |
13
+ | `primary` / `-foreground` / `-hover` / `-border`, `secondary` / … | actions |
14
+ | `success` / `warning` / `error` / `info`, `+ -subtle` | status, status backgrounds |
15
+
16
+ Palette shades: `text-primary-600`, `bg-neutral-100`, `border-accent-300` — 50–950 for primary, secondary, accent, neutral. Full mapping in `theme-tokens.css`.
17
+
18
+ **Debugging a token that "does nothing" — don't probe in the browser.** Tailwind v4 is JIT and emits only classes found in scanned source, so a class assigned from the console can never resolve. Ask the build: `grep -o '\.text-link{[^}]*}' dist/assets/*.css`. A rule prints → the utility exists and something overrides it at runtime. Nothing prints → `styles.css` doesn't import `theme-tokens.css` (or declares its own `@theme inline` omitting it), or `@source` doesn't cover the file.
19
+
20
+ **Per-section theme maps.** A section's `theme:` is `theme.yml` for that section — tokens beside `mode`, plus `colors`, `contexts`, `vars` scoped to it (`theme: { mode: light, section: neutral-100, card: neutral-50, primary: neutral-900, colors: { accent: '#e65100' }, contexts: { dark: { link: accent-300 } } }`). `background:` accepts CSS variables and hex too, so authors alternate surfaces with no component code. Map a source design's surface variations to backgrounds or token overrides in frontmatter — not to component code.
21
+
22
+ ## Section context vs site scheme
23
+
24
+ - **Section context** — `theme:` on one section. Per-section, author-controlled.
25
+ - **Site scheme** — the global preference under `appearance:` in `theme.yml`; the visitor's toggle.
26
+
27
+ A section with no `theme:` follows the scheme; one that pins `theme: dark` stays dark in either.
28
+
29
+ ```yaml
30
+ appearance:
31
+ default: light # light | dark | system
32
+ allowToggle: true # offer a switch (also generates dark tokens)
33
+ respectSystemPreference: true # first visit follows the OS; false pins `default`
34
+ schemes: [light, dark]
35
+ ```
36
+
37
+ Shorthands: `appearance: light` / `dark` (fixed), `appearance: system`. A site has dark mode when it offers a toggle, defaults to `dark`/`system`, or lists `dark`. Precedence: stored choice > a dark OS > `default:` — the OS can only choose dark, so `default: light` is a fallback, not a guarantee, unless `respectSystemPreference: false`, and `default: dark` stays dark on a light OS.
38
+
39
+ | Goal | `theme.yml` |
40
+ |---|---|
41
+ | Always light / dark, no switch | `appearance: light` / `dark` |
42
+ | Toggle, follow OS on first visit | `{ default: system, allowToggle: true }` |
43
+ | Toggle, always start light | `{ default: light, allowToggle: true, respectSystemPreference: false }` |
44
+
45
+ ```jsx
46
+ const { scheme, toggle, canToggle } = useAppearance()
47
+ if (!canToggle) return null
48
+ ```
49
+
50
+ The runtime applies `scheme-dark`/`scheme-light` to `<html>` before paint. For Tailwind `dark:` utilities: `@custom-variant dark (&:where(.scheme-dark, .scheme-dark *));` in `styles.css`; prefer tokens, which adapt per section.
51
+
52
+ ## theme.yml
53
+
54
+ ```yaml
55
+ colors:
56
+ primary: '#3b82f6' # your hex at shade 500
57
+ secondary: '#64748b'
58
+ accent: '#8b5cf6'
59
+ neutral: stone # named preset: stone, zinc, gray, slate, neutral
60
+ contexts:
61
+ light: { section: '#fafaf9' }
62
+ appearance: { default: light, allowToggle: true }
63
+ fonts: { heading: "'Inter', system-ui, sans-serif", body: "'Inter', system-ui, sans-serif" }
64
+ inline: { callout: { color: var(--accent), font-weight: '600' } }
65
+ vars: { radius: 0.75rem }
66
+ code: dracula # or { light: github-light, dark: github-dark }, or { theme: github-dark, background: '#0D0D0D' }
67
+ ```
68
+
69
+ Context override keys match token names (`section:` not `bg:`). In light/medium `--primary` uses shade 600, `--link` 600, `--ring` 500; in dark `--primary` 500, `--link` 400. Buttons use 600 for contrast with white text; for brand-exact buttons set `contexts.light.primary: primary-500` and `primary-hover: primary-600`, and test contrast — bright brands at 500 may fail WCAG 4.5:1. A code block paints its theme's background and foreground before the highlighter loads when both are known.
70
+
71
+ ## Fonts
72
+
73
+ | Role | Wired onto | Use |
74
+ |---|---|---|
75
+ | `body` | `body` | paragraphs, UI |
76
+ | `heading` | `h1, h2, h3` | titles |
77
+ | `code` | `code, pre, kbd, samp` | monospace |
78
+
79
+ The site wires families onto elements, so a foundation normally sets none — render semantic markup and the roles apply. Weight/size/style utilities are yours; a font-**family** utility (`font-sans`, `font-serif`) resolves to Tailwind's stacks unless the foundation declares it as a font var. For typefaces the three roles can't express, declare each as a **font var** in `main.js` — a `font-*` name is recognised as a typeface (a bare name takes `type: 'font'`):
80
+
81
+ ```js
82
+ export const vars = {
83
+ 'font-serif': { default: 'ui-serif, Georgia, serif', applyTo: ['blockquote', '.tagline'] }, // framework emits the rule
84
+ 'font-display': { default: 'ui-sans-serif, system-ui, sans-serif' }, // component wires it
85
+ }
86
+ ```
87
+
88
+ `fonts:` in `theme.yml` takes any role name; redeclaring a built-in role's var with a new `applyTo` retargets it. `serif` and `font-serif` are the same var (the site sets it by the bare role name).
89
+
90
+ ```yaml
91
+ fonts:
92
+ heading: "Poppins, sans-serif"
93
+ serif: '"Fraunces", Georgia, serif'
94
+ import: [{ url: "https://fonts.googleapis.com/css2?family=Poppins:wght@600;700" }]
95
+ faces: [{ family: "Fraunces", src: /fonts/fraunces.woff2, weight: "100 900" }]
96
+ ```
97
+
98
+ The build adds preconnect hints, emits `@font-face` + preload, drops unreferenced families; `uniweb push` uploads face files under `public/`. The `code` role owns `--font-code`; Tailwind's `font-mono` reads `--font-mono`, a separate var you declare yourself. A role's face on an element it isn't wired onto — a wordmark in the heading face, say — is `font-family: var(--font-heading)`, or a utility of your own: `@theme inline { --font-display: var(--font-heading); }` in `styles.css`, then `font-display`.
99
+
100
+ ## styles.css
101
+
102
+ ```css
103
+ @import "tailwindcss";
104
+ @import "@uniweb/kit/theme-tokens.css";
105
+ @import "@uniweb/kit/prose-tokens.css";
106
+ @source "./sections/**/*.{js,jsx}";
107
+ @source "./components/**/*.{js,jsx}";
108
+ @source "./layouts/**/*.{js,jsx}";
109
+ @theme { --breakpoint-xs: 30rem; }
110
+ ```
111
+
112
+ Two more imports are opt-in: `@uniweb/kit/math-tokens.css` lays out equations, and `@uniweb/kit/callout-tokens.css` draws concept blocks such as `md:warning`, which are otherwise plain prose.
113
+
114
+ **Name every folder that writes classes.** The foundation's own build finds them all, but a site build and `uniweb dev` read only what these lines name, so a class in a folder left out is in one CSS and missing from the other. `uniweb dev`, a site build and `uniweb doctor` (`unread-folder`) give the line to add. `theme-tokens.css` also tells Tailwind to read kit's source, so kit's own classes reach your CSS wherever your package manager put kit; a foundation that skips that import names kit itself, by where kit is (`./node_modules/@uniweb/kit/src/**` under pnpm, `../node_modules/@uniweb/kit/src/**` under npm).
115
+
116
+ Custom CSS is expected alongside Tailwind — shadow systems, border hierarchies, gradients, glass. Tokens are a floor; add vocabulary that references them so it adapts per context:
117
+
118
+ ```css
119
+ .border-subtle { border-color: color-mix(in oklch, var(--border), transparent 50%); }
120
+ .text-tertiary { color: color-mix(in oklch, var(--body), var(--subtle) 50%); }
121
+ ```
122
+
123
+ Priority: design quality > portability > configurability. Four things a ported design brings that break something: global `scroll-behavior: smooth` (the runtime's `scrollTo(x, y)` inherits it and route changes animate/interrupt — scope it to an element); `filter: blur()` glows (Safari repaints them on the main thread during view transitions — use a radial `mask-image` instead); `-webkit-font-smoothing: antialiased` on `html` (scope it to `.scheme-dark`); JS-started entrance animations (write them in CSS so they start at first paint on a prerendered page).