smoodly 0.0.60 → 0.0.62

package/docs/fields/reference-and-tags.md

@@ -0,0 +1,62 @@
+# Reference and tags
+
+A reference points at an entry in a collection and arrives in the view already loaded. Tags are short labels editors reuse across entries.
+
+## Reference
+
+`f.ref(() => collection)` picks one entry; `f.refList(() => collection)` picks several. The target is a function, so two collections can point at each other without an import cycle:
+
+File: `components/sections/FavouriteArticles.schema.ts`
+
+```ts
+import { articles } from "@/smoodly/collections";
+// …
+  fields: {
+    heading: f.text(),
+    items: f.refList(() => articles).max(6),
+  },
+```
+
+Editors see a search picker over the collection's entries in the language they are editing, each with its status. A list takes each entry once and stops at `.max()`.
+
+## What the view receives
+
+A reference resolves before render, in one batched read per collection, so the view gets the entry as `{ id, path, fields }` rather than an id:
+
+File: `components/sections/FavouriteArticles.tsx`
+
+```tsx
+          {(items ?? []).filter((a) => a !== null).map((a, i) => (
+            <ArticleCard key={i} article={a.fields} url={url(a.path!)} locale={locale} />
+          ))}
+```
+
+An entry that is unpublished, or was deleted after the page went live, resolves to `null`, which is why the view filters before it maps. The value's type follows the target collection's fields.
+
+The same rule holds in every read: sections, `q` lists and single reads, entry pages and globals. How deep a reference goes is the field's decision:
+
+| Declaration | The view gets |
+| --- | --- |
+| `f.ref(() => authors)` | `{ id, path, fields }`; the author's own references stay id strings. |
+| `.resolve("company")` | The named reference of the target resolved one level too. |
+| `.resolve()` | The whole chain resolved. |
+
+Types follow the depth, so `a.fields.company` is an id or a resolved entry as declared. One gap: where the chain meets a cycle it stops at ids, while the type says resolved.
+
+## Where references may go
+
+A reference lives at the top level of a section, element or collection schema. It cannot sit inside a list or an object, in a page field, or in an element that richtext embeds, because the reference index addresses fields by their top-level key. A schema that breaks the rule fails at startup with the path.
+
+## Tags
+
+`f.tags()` stores an array of short strings and shows them as chips. Editors type a tag and press Enter, or paste a comma-separated list, and pick from the tags other entries of the collection already use in that language:
+
+File: `smoodly/collections.ts`
+
+```ts
+    tags: f.tags().localized(),
+```
+
+Tags are trimmed, and two that differ only in case are one tag: typing `design` when `Design` exists reuses it. `.min()` and `.max()` count tags. Each entry keeps its own list; there is no tag collection to manage. The starter shows an article's first tag on its card and all of them on the article page.
+
+Next, [Conditional fields](../fields/conditional.md).

package/docs/fields/richtext.md

@@ -0,0 +1,168 @@
+# Richtext and elements
+
+Formatted text stored as structured data, the toolset that decides what editors may put in it, and the elements they can insert between the paragraphs.
+
+## The field
+
+`f.richtext()` shows a text editor and stores a document, never HTML. Render it with `RichText`.
+
+File: `components/sections/ImageText.schema.ts`
+
+```ts
+    text: f.richtext({ toolset: smoodly.toolset({ marks: ["bold", "italic", "link"] }) }),
+```
+
+**Astro**
+
+`RichText` comes from `smoodly/astro/components`:
+
+File: `src/sections/imageText.astro`
+
+```astro
+---
+import { Image, RichText, Section } from "smoodly/astro/components";
+// …
+---
+// …
+      <div class="prose" {...m.field("text")}><RichText doc={text} /></div>
+```
+
+**Next.js**
+
+`RichText` comes from the site's bound renderer, below:
+
+File: `components/sections/ImageText.tsx`
+
+```tsx
+import { RichText } from "@/smoodly/richtext";
+// …
+      <div className="prose" {...m.field("text")}><RichText doc={text} /></div>
+```
+
+`RichText` renders a fragment with no wrapper, so the element and class around it are yours. An empty document counts as missing, so a required richtext field must hold some text before publish. In the canvas, a marked richtext field edits in place with a floating toolbar.
+
+## Toolsets
+
+A toolset is what a richtext field offers: which formatting, which block types, which elements. Without one, a field gets bold, italic and links, headings two to four, both lists and blockquotes. Heading one is left out because the section or page owns the page's first heading.
+
+`smoodly.toolset()` builds one from three lists:
+
+| Name | Description |
+| --- | --- |
+| `marks` | bold, italic, link. |
+| `nodes` | h1 to h6, bulletList, orderedList, blockquote and image. image adds pictures from the media library, with a caption. |
+| `elements` | Registered elements, by value. |
+
+The starter keeps its toolsets in one file and imports them by value where a field needs them:
+
+File: `smoodly/toolsets.ts`
+
+```ts
+import { smoodly } from "smoodly";
+import { calloutSchema } from "../components/elements/Callout.schema";
+import { ctaSchema } from "../components/elements/Cta.schema";
+
+export const article = smoodly.toolset({
+  marks: ["bold", "italic", "link"],
+  nodes: ["h2", "h3", "h4", "bulletList", "orderedList", "blockquote", "image"],
+  elements: [calloutSchema, ctaSchema],
+});
+```
+
+A toolset limits what editors can create, not what the document may hold. Tightening one later leaves existing content as it is, so nothing is rewritten behind an editor's back.
+
+## Rendering with elements and images
+
+**Astro**
+
+The package's `RichText` knows your elements by file name and renders body images through Astro's image service, so there is nothing to bind. Links keep only safe targets: `http`, `https`, `mailto`, `tel` and site-relative paths.
+
+**Next.js**
+
+The `RichText` from `smoodly/react` renders text alone. A site that embeds elements or images binds its own renderer once, and imports it from there everywhere:
+
+File: `smoodly/richtext.tsx`
+
+```tsx
+import { createRichText } from "smoodly/richtext";
+import { Callout } from "@/components/elements/Callout";
+import { Cta } from "@/components/elements/Cta";
+
+export const RichText = createRichText({ elements: [Callout, Cta], sizes: "(min-width: 900px) 720px, 100vw" });
+```
+
+The bound renderer knows the elements a document may name and renders body images through `SmoodlyImage`, with `sizes` set to the text column's width. Links keep only safe targets: `http`, `https`, `mailto`, `tel` and site-relative paths.
+
+## Elements
+
+An element is a small component editors insert between paragraphs, from the *+* button on the toolbar or by typing `/`. It is defined like a section, with `contexts` saying where it may go:
+
+File: `components/elements/Callout.schema.ts`
+
+```ts
+export const calloutSchema = smoodly.schema.element({
+  name: "callout",
+  title: "Callout",
+  icon: "!",
+  description: "A highlighted note inside the text.",
+  contexts: ["richtext"],
+  fields: {
+    title: f.text().max(80),
+    body: f.richtext({ toolset: smoodly.toolset({ marks: ["bold", "italic", "link"] }) }),
+  },
+  settings: {
+    tone: f.select([{ value: "info", label: "Info" }, { value: "success", label: "Success" }, { value: "warning", label: "Warning" }]).default("info"),
+  },
+  // …
+});
+```
+
+**Astro**
+
+An element's view is `src/elements/<name>.astro`, named after the schema:
+
+File: `src/elements/callout.astro`
+
+```astro
+---
+// …
+const { title, body, settings } = Astro.props;
+---
+<aside class="callout" data-tone={settings.tone}>
+  <strong class="callout__title">{title}</strong>
+  <div class="callout__body"><RichText doc={body} /></div>
+</aside>
+```
+
+A link an editor types in an element goes through `safeHref` from `smoodly`, as in the starter's `cta.astro`.
+
+**Next.js**
+
+File: `components/elements/Callout.tsx`
+
+```tsx
+function CalloutView({ title, body, settings }: Props<typeof calloutSchema>) {
+  return (
+    <aside className="callout" data-tone={settings.tone}>
+      <strong className="callout__title">{title}</strong>
+      <div className="callout__body"><RichText doc={body} /></div>
+    </aside>
+  );
+}
+
+export const Callout = smoodly.element(calloutSchema, CalloutView);
+```
+
+An element renders with no wrapper of Smoodly's and has no styles or CSS box: spacing is the text column's job. It may not hold a reference. In the editor an inserted element is a card with its own fields, and its `sample` fills it on insert.
+
+Register an element's schema in `smoodly/elements.ts` and list it in the toolsets that may insert it. A toolset that names an element the config does not register fails at startup.
+
+**Astro**
+
+The view is the file; there is nothing else to list.
+
+**Next.js**
+
+Add its component to `smoodly/views.ts` and `smoodly/richtext.tsx` as well.
+
+Next, [Link](../fields/link.md).

package/docs/fields/text.md

@@ -0,0 +1,152 @@
+# Text, number, date and time
+
+The plain values: a line of text, a number, a date, a date with a time, and the slug that becomes part of an entry's URL.
+
+## Text
+
+`f.text()` is a single line. `.max(n)` limits it in characters, and publish enforces the limit. There is no multi-line text field: paragraphs are [richtext](../fields/richtext.md), which keeps formatting as data rather than as line breaks.
+
+File: `components/elements/Cta.schema.ts`
+
+```ts
+  fields: {
+    heading: f.text().max(80),
+    text: f.text().max(200).optional(),
+    label: f.text().max(40),
+    href: f.link(),
+  },
+```
+
+Text is the one field editors can change in place in the canvas, when its element carries a [mark](../content-modeling/marks.md).
+
+## Number
+
+`f.number()` shows a number box and stores a number. An empty box stores nothing, so an optional number is `undefined` in the view, not `0`.
+
+## Date and time
+
+`f.date()` is a calendar: a text box the editor may type into, and a calendar button that opens a month grid. It stores the day as `2026-09-02`, and publish refuses anything else — `2.9.2026` or a February 30th never reach the site. The view formats it for the reader; the starter formats in the page's language:
+
+File: `components/articles.ts`
+
+```ts
+export const formatDate = (iso: string, locale: string) =>
+  new Intl.DateTimeFormat(locale, { dateStyle: "medium", timeZone: "UTC" }).format(new Date(iso));
+```
+
+`f.datetime()` is the same calendar with an hour and a minute beside it. It stores a moment in time as a UTC instant, `2026-09-02T14:30:00Z`, so an event start or a publish-at means the same thing in every zone and sorts as a string. The editor picks in the site's time zone, and a hint under the field names it.
+
+The site's zone is one line of config, an IANA name:
+
+File: `smoodly/config.ts`
+
+```ts
+export const config = defineConfig({
+  // …
+  locales: { default: routing.defaultLocale, supported: [...routing.locales] },
+  // Editors pick dates and times in this zone; the views format with it (an IANA name, never an offset).
+  timeZone: "Europe/Helsinki",
+  // …
+});
+```
+
+Name a city, never an offset. `"+3"` is wrong half the year; `Europe/Helsinki` carries the daylight-saving rules, and the browser and Node apply them from their own zone database. `defineConfig` refuses a name the runtime does not know. Without `timeZone`, editors pick in their own browser's zone, and the hint says so.
+
+A view formats a datetime with the same zone:
+
+File: `components/articles.ts`
+
+```ts
+export const formatDateTime = (iso: string, locale: string, timeZone: string) =>
+  new Intl.DateTimeFormat(locale, { dateStyle: "medium", timeStyle: "short", timeZone }).format(new Date(iso));
+```
+
+Pass `config.timeZone` from your config file. A collection can order its entries by either field, as the starter's articles do with `order: { by: "date", direction: "desc" }`.
+
+### Time zones in Europe
+
+The value to put in `timeZone`, country by country. A country with several zones has its capital first.
+
+| Country | timeZone |
+| --- | --- |
+| `Albania` | Europe/Tirane |
+| `Andorra` | Europe/Andorra |
+| `Austria` | Europe/Vienna |
+| `Belarus` | Europe/Minsk |
+| `Belgium` | Europe/Brussels |
+| `Bosnia and Herzegovina` | Europe/Sarajevo |
+| `Bulgaria` | Europe/Sofia |
+| `Croatia` | Europe/Zagreb |
+| `Cyprus` | Asia/Nicosia |
+| `Czechia` | Europe/Prague |
+| `Denmark` | Europe/Copenhagen |
+| `Estonia` | Europe/Tallinn |
+| `Faroe Islands` | Atlantic/Faroe |
+| `Finland` | Europe/Helsinki |
+| `Åland` | Europe/Mariehamn |
+| `France` | Europe/Paris |
+| `Germany` | Europe/Berlin (Büsingen: Europe/Busingen) |
+| `Gibraltar` | Europe/Gibraltar |
+| `Greece` | Europe/Athens |
+| `Guernsey` | Europe/Guernsey |
+| `Hungary` | Europe/Budapest |
+| `Iceland` | Atlantic/Reykjavik |
+| `Ireland` | Europe/Dublin |
+| `Isle of Man` | Europe/Isle_of_Man |
+| `Italy` | Europe/Rome |
+| `Jersey` | Europe/Jersey |
+| `Kosovo` | Europe/Belgrade |
+| `Latvia` | Europe/Riga |
+| `Liechtenstein` | Europe/Vaduz |
+| `Lithuania` | Europe/Vilnius |
+| `Luxembourg` | Europe/Luxembourg |
+| `Malta` | Europe/Malta |
+| `Moldova` | Europe/Chisinau |
+| `Monaco` | Europe/Monaco |
+| `Montenegro` | Europe/Podgorica |
+| `Netherlands` | Europe/Amsterdam |
+| `North Macedonia` | Europe/Skopje |
+| `Norway` | Europe/Oslo (Svalbard: Arctic/Longyearbyen) |
+| `Poland` | Europe/Warsaw |
+| `Portugal` | Europe/Lisbon (Azores: Atlantic/Azores, Madeira: Atlantic/Madeira) |
+| `Romania` | Europe/Bucharest |
+| `Russia` | Europe/Moscow (also Europe/Kaliningrad, Europe/Samara, Europe/Astrakhan, Europe/Saratov, Europe/Ulyanovsk, Europe/Volgograd, Europe/Kirov) |
+| `San Marino` | Europe/San_Marino |
+| `Serbia` | Europe/Belgrade |
+| `Slovakia` | Europe/Bratislava |
+| `Slovenia` | Europe/Ljubljana |
+| `Spain` | Europe/Madrid (Canary Islands: Atlantic/Canary) |
+| `Sweden` | Europe/Stockholm |
+| `Switzerland` | Europe/Zurich |
+| `Turkey` | Europe/Istanbul |
+| `Ukraine` | Europe/Kyiv (Crimea: Europe/Simferopol) |
+| `United Kingdom` | Europe/London |
+| `Vatican City` | Europe/Vatican |
+
+Outside Europe the same rule holds — a city name from the IANA database, such as `America/New_York` or `Asia/Tokyo`. The full list is `Intl.supportedValuesOf("timeZone")` in any modern runtime.
+
+## Slug
+
+`f.slug()` is a text box shown with the entry's URL prefix in front, such as `/posts/`. It belongs on a collection, and the field must be named `slug`: that is the name the URL is built from, so `collection()` refuses `f.slug()` under any other name.
+
+File: `smoodly/collections.ts`
+
+```ts
+export const articles = smoodly.collection({
+  name: "articles",
+  title: "Articles",
+  titleField: "title",
+  path: { en: "posts", fi: "artikkelit" },
+  // …
+  fields: {
+    title: f.text().localized(),
+    // …
+    slug: f.slug({ from: "title" }),
+    // …
+  },
+});
+```
+
+The starter passes `from: "title"`: the admin fills the slug from the title as the editor types it, until they type a slug of their own. It stops at the first publish, so a live URL never changes by itself. A slug is tidied when the box loses focus, so `Hello World` becomes `hello-world`, and publish refuses anything that is still not a valid slug. A slug is per language without `.localized()`, because each language has its own URL. Two entries under the same parent cannot share one. Pages have no slug field: a page's slug is set in the admin when it is created and renamed under *Settings*.
+
+Next, [Richtext and elements](../fields/richtext.md).

package/docs/frameworks/astro.md

@@ -0,0 +1,110 @@
+# Astro
+
+How Smoodly plugs into an Astro project: one integration in astro.config, views by file name, reads as live collections, pages cached whole and expired by tag, and what happens on a request. The installer writes all of it; this page is for reading it.
+
+## The integration
+
+One line in `astro.config.ts` mounts Smoodly:
+
+File: `astro.config.ts`
+
+```ts
+import { defineConfig, memoryCache } from "astro/config";
+import node from "@astrojs/node";
+import smoodly from "smoodly/astro";
+// …
+  cache: { provider: memoryCache() },
+// …
+  site: process.env.SITE_URL,
+  integrations: [smoodly({ config: "src/smoodly/config.ts" })],
+```
+
+`smoodly()` adds three routes and one middleware, so the project has no route file for any of them:
+
+- **The admin**, at `/admin`. To move it, pass `adminPath: "/studio"` here and set `admin: { path: "/studio" }` in the config; the admin says so when the two disagree.
+- **The preview address**, `/_smoodly/preview/<path>`, where the admin's canvas shows drafts.
+- **The pages**, at every address a page file of your own does not take.
+
+`config` names the Smoodly config file. `site` is the site's own address: canonical and hreflang links are absolute on it. Astro reads `astro.config.ts` before `.env`, so `process.env.SITE_URL` there sees only a value set in the shell or on the host; when it is empty, `smoodly()` sets `site` from `SITE_URL` in `.env`, and the build warns when nothing names one. The integration reads `.env` at `astro dev` and `astro build`, the `SMOODLY_` keys and `SITE_URL`; `npm start` reads it when it is there, and a deployed server takes the variables from its host.
+
+## Views by file name
+
+A view is an `.astro` file named after its schema's `name`. There is no list of views to keep:
+
+| Folder | What it renders, and its props |
+| --- | --- |
+| `src/page-types/<name>.astro` | A page type. It receives `page` (where the page sits: title, path, ancestors, children, locales), `zones` and `head`. |
+| `src/sections/<name>.astro` | A section. Its fields arrive flat, with `settings` and `styles`. |
+| `src/elements/<name>.astro` | An element inside richtext. Its fields and `settings`. |
+| `src/entry-pages/<collection>.astro` | The entry page of a collection with a `path`. It receives `entry` and `head`. |
+
+A schema with no view, and a view with no schema, are named once in the server log at the first request. A section is the same file in every framework apart from its view; [Sections](../content-modeling/sections.md) shows one.
+
+## Reads
+
+Smoodly's content reaches your views as Astro live collections. `src/live.config.ts` names one loader per collection, global item, the pages and the page tree:
+
+File: `src/live.config.ts`
+
+```ts
+import { defineLiveCollection } from "astro:content";
+import { entriesLoader, globalLoader, pageLoader, pageTreeLoader } from "smoodly/astro/content";
+// …
+export const collections = {
+  pages: defineLiveCollection({ loader: pageLoader() }),
+  pageTree: defineLiveCollection({ loader: pageTreeLoader() }),
+  articles: defineLiveCollection({ loader: entriesLoader(articles) }),
+  // …
+  header: defineLiveCollection({ loader: globalLoader(header) }),
+  // …
+};
+```
+
+A view reads with `getLiveCollection` and `getLiveEntry` from `astro:content`:
+
+File: `src/page-types/articlesIndex.astro`
+
+```astro
+---
+import { getLiveCollection } from "astro:content";
+// …
+const { entries = [] } = await getLiveCollection("articles", { locale: page.locale });
+// …
+---
+```
+
+A collection takes `locale`, `where`, `order` and `limit`; `getLiveEntry("footer", { locale })` reads a global item, and `getLiveEntry("pages", { path, locale })` one page. In a preview the same reads return drafts. A global flagged `layout: true` is answered from the page's own read, so a layout's `getLiveEntry` calls cost no call ([Defining a global](../globals/defining.md#layout-globals)).
+
+## The cache
+
+Every read tags the response with what it read. Once the page is rendered, the response is stored whole, and a publish expires exactly the tags it touched. The first request after a publish reads from the service again; the rest are served from the cache. A 404, a draft and anything under the preview address are never stored.
+
+`memoryCache()` keeps pages in the server process's memory: one process, one cache. On Vercel, `cacheVercel()` stores them on the CDN instead; [Deploying](../getting-started/deploying.md) shows the swap.
+
+That is live mode, the default: pages render on demand and a publish is live at once. The other mode is static: with `output: "static"` in `astro.config`, every published page is built as a file, visitors need no function and no service, and editors press **Deploy** in the admin when their publishes should go live. Sections, schemas, the admin and the preview address are the same in both; [Deploying › Static](../getting-started/deploying.md#static) has the switch and the Deploy tile.
+
+## Preview
+
+The admin's canvas loads a page at the preview address. A signed cookie, set for the admin's session, opens it; without the cookie the address is closed. Reads there return drafts, and the editor's bridge is added to the response. A live address never shows a draft and carries no Smoodly script. There is no pill: drafts are seen in the admin only.
+
+## Images
+
+`Image` from `smoodly/astro/components` renders an `f.image()` value as plain HTML, an `<img>` or a `<picture>`:
+
+File: `src/sections/hero.astro`
+
+```astro
+{image && <Image image={image} class="hero__image" sizes="(min-width: 900px) 40vw, 100vw" priority {...m.field("image")} />}
+```
+
+The box keeps the crop's aspect and the `srcset` lists the cut's widths on Smoodly's media host, in AVIF or WebP, so Astro's image service, `/_image` and `image.remotePatterns` are not involved and no image setting is needed. `Head` opens a connection to the media host when the page shows an image. In static output the build writes every image its pages show into the output instead, so a static page loads its images from your own host. [Images and crops](../media/images-and-crops.md) has named crops and the `media` prop.
+
+## Languages
+
+`i18n` in `astro.config.ts` and `locales` in the config name the same set; the site refuses to start when they disagree, and the installer writes both. Smoodly follows Astro's rule for the default locale: no prefix unless `routing.prefixDefaultLocale` says so. `Head` writes one hreflang link per language the page is published in. [Locales and routing](../languages/locales.md) has the rest.
+
+## A page of your own
+
+A file under `src/pages/`, such as `src/pages/pricing.astro`, wins its address. A page an editor creates at `/pricing` saves and publishes, but visitors see your file, and the page editor says so. `src/pages/404.astro` is the site's "not found" page.
+
+To write content from a script, see [Content from code](../getting-started/content-from-code.md).

package/docs/frameworks/nextjs.md

@@ -0,0 +1,147 @@
+# Next.js
+
+How Smoodly plugs into a Next.js app: the one route file, the server seam, the admin route group, and what happens on a request. The installer writes all of it; this page is for reading it.
+
+## The route file
+
+One file under `app/(site)` serves every CMS URL, and it needs no editing:
+
+File: `app/(site)/[[...path]]/page.tsx`
+
+```tsx
+import { renderSmoodlyPath, smoodlyMetadata } from "@/smoodly/server";
+// …
+export function generateStaticParams() {
+  return [];
+}
+// …
+export default async function Page({ params, searchParams }: { params: Params; searchParams: SearchParams }) {
+  return renderSmoodlyPath((await params).path ?? [], { searchParams });
+}
+```
+
+`renderSmoodlyPath` resolves the URL path to a page, a path in the tree or an entry, and renders it with its page type or entry page; no segments is the home. A page or entry that does not exist, or is not published, is a 404. A multilingual site has the same file under `app/[locale]` and passes the language along.
+
+`generateStaticParams` returning nothing is what makes the page cacheable: Next builds no page ahead, renders each address on its first visit and keeps the result until a publish expires it ([What happens on a request](#what-happens-on-a-request)). Keep the export; without it Next renders the route on every request.
+
+A route file of your own beside this one, `app/(site)/pricing/page.tsx`, wins for that exact URL by Next's precedence; deeper URLs still reach the catch-all. A page an editor creates at `/pricing` saves and publishes, but visitors see your route instead. The page editor says so: when its canvas cannot show the page, a warning names the cause, with a line starting "For your developer:" that says what to change. A home of your own is the same file: return your component when `path` is empty.
+
+A page under this route may not read cookies, headers or search params, and neither may a section or the layout above it: Next decided the page is static, so a dynamic API inside the render answers a 500 in production, and `next dev` does not show it. A page that needs them is its own route file, which renders on every request. The same goes for `connection()`: a snippet from before 0.0.50 that awaits it in `smoodly/server.ts` turns every page into that 500. The file passes `searchParams` on to `renderSmoodlyPath`, which reads them inside draft mode only: the canvas asks for the page with a `smoodly-editor` parameter, and without it the page renders with no editor bridge, so nothing in the canvas can be selected. The page editor names that case too.
+
+## The server seam
+
+`smoodly/server.ts` builds everything the routes and the admin share, once per server, and only when first used, so a build with no environment still succeeds:
+
+File: `smoodly/server.ts`
+
+```ts
+  const site = createSmoodlyApi({ ...apiEnv(), config });
+  // …
+  const renderer = createPageRenderer({ site, ...views(), href });
+  // …
+  const q = createSmoodlyQueries({ site, collections, globals });
+```
+
+`createSmoodlyApi` reads your content over Smoodly's API, one call per read, and computes everything else the renderer needs from the config, so the two cannot disagree. Your site opens no database. `views()` hands the renderer your components from `smoodly/views.ts`, checked against the config's schemas the first time the site renders.
+
+The live site reads two variables: `SMOODLY_SPACE_ID`, the space your content lives in, and `SMOODLY_SECRET_KEY`. The admin needs the same two: it learns where editors sign in from Smoodly's API. `SITE_URL` is the address the build pushes to the space with the schema (`prebuild: "smoodly push"` in `package.json`). [Keys](../getting-started/keys.md) explains them. It exports the two functions the routes call, `q` for [queries](../collections/queries.md), and `href`, the one seam that turns a language-relative path into a site URL.
+
+The file also builds `content()`, which scripts write content through ([Content from code](../getting-started/content-from-code.md)). It takes it from `smoodly/admin` and posts to the same API with the secret key:
+
+File: `smoodly/server.ts`
+
+```ts
+  return createSmoodlyContent({ config, href, transport: apiTransport(apiEnv()) });
+```
+
+## The admin
+
+The admin is one route. The `smoodly` package ships it prebuilt, so your app compiles none of it:
+
+File: `app/(smoodly)/admin/[[...segments]]/route.ts`
+
+```ts
+import { createAdminRoute } from "smoodly/next";
+import { config } from "@/smoodly/config";
+import { adminDeps, presence } from "@/smoodly/server";
+
+export const { GET, POST } = createAdminRoute(() => ({ config, ...adminDeps(), presence }));
+```
+
+`GET` serves the admin's page and the script and fonts it loads. The admin's operations run in Smoodly's API, which accepts them from the addresses your builds pushed and checks the editor's session against the space's members; the browser never holds a write key. `POST` takes two calls only: the API's call after a publish naming the cache tags to expire, which must be signed with the API's own key and less than a minute old, and the editor's browser turning on draft mode with a grant the API signed, accepted from the site's own address only.
+
+`presence` is where the browser opens the editing-presence connection (Smoodly's API and your space), public values read from `smoodly/server.ts` per request; where editors sign in, the page asks Smoodly's API. Leave `presence` out and the admin works the same, minus [who is editing what](../getting-started/working-together.md).
+
+The route folder under `app/(smoodly)` must match `admin.path` in the config; [The admin](https://smoodly.io/docs/getting-started/admin) covers moving it. The admin's page has no layout, so the site's layout never wraps it.
+
+## Content in the browser
+
+The publishable key is public and reads published content only, so a component that runs in the browser could read with it. The starter's way is a route in your own app that reads through `q` on the server: the browser holds no key, and the route decides what leaves. A component that needs entries, a search box or a "load more" button, asks that route:
+
+File: `app/api/articles/route.ts`
+
+```ts
+import { q } from "@/smoodly/server";
+
+export async function GET(request: Request) {
+  const locale = new URL(request.url).searchParams.get("locale") ?? undefined;
+  const items = await q().getEntries("articles", { locale, limit: 12 });
+  return Response.json(items.map((item) => ({ id: item.id, path: item.path, title: item.fields.title })));
+}
+```
+
+Return only what the browser should see: the route decides, not the service. Published content only leaves the route, because a request outside the editor's draft mode reads published rows.
+
+## What happens on a request
+
+A CMS route is never built ahead: `next build` reads nothing from the service and needs no keys. Each address renders on its first visit, outside draft mode, and Next keeps the page in its route cache, which Vercel serves from its CDN without running your function. The render reads under tags that name the page or entry by id, the layout's global items by name, and, for a 404, a redirect or a code-owned page, one tag for every address. Publishing, unpublishing, renaming or deleting expires exactly those tags at once; the next visit renders fresh. Nothing expires on a timer. One consequence: a renamed page's old address answers its permanent redirect without the request's query string, since the cached answer cannot read it.
+
+Draft mode is Next's way of rendering unpublished content for one browser. The editor turns it on for the editor's browser by posting a grant from Smoodly's API to the admin route, then loads the site's real URL in the canvas with `/~editor` after it, which mounts the bridge the canvas talks to. In draft mode every read returns the live draft rows, and *History* renders an old version at the page's URL followed by `/~version~` and the version's id. The flags ride the path, not the query, because Vercel passes a cached route only its own parameters, even in draft mode. The public site honors neither: outside draft mode such an address is not found.
+
+## Preview mode
+
+Opening the page editor turns on draft mode for that browser. Every page Smoodly renders then shows a floating pill, outside the editor's canvas: *Preview · unpublished changes*, with *Exit preview*. Editors can drag it to the left, center or right, move it with the arrow keys, or hide it until the next reload. Outside draft mode the page's HTML has no trace of it, and no page loads Smoodly's editor code.
+
+Exit goes to `/api/preview?disable`, the route every starter ships:
+
+File: `app/api/preview/route.ts`
+
+```ts
+export { previewRoute as GET } from "smoodly/next";
+```
+
+If you moved that route, tell the renderer with the `previewRoute` option of `createPageRenderer`, like `previewRoute: "/my/preview"`.
+
+A page you render yourself, without `renderSmoodlyPath`, can show the pill too:
+
+File: `app/pricing/page.tsx`
+
+```tsx
+import { draftMode } from "next/headers";
+import { previewPill } from "smoodly/next";
+
+export default async function Pricing() {
+  const { isEnabled } = await draftMode();
+  return <main>{isEnabled && previewPill()}</main>;
+}
+```
+
+The pill loads as a small script of its own, in preview only.
+
+## Cache Components
+
+Leave `cacheComponents` off in `next.config.ts`. Next 16's Cache Components mode brings the `"use cache"` directive and partial prerendering for every route: a static shell goes out first and the rest streams in. Smoodly's catch-all serves paths that are unknown at build time, so under that mode it is always sent from a shell that has already committed status 200. A page that doesn't exist then answers 200 with a `noindex` tag instead of 404, and a redirect answers 200 instead of 308, both of which search engines treat worse. No route can opt out of the mode, so Smoodly does not support it.
+
+You keep `unstable_cache` and `revalidateTag`, and every page and entry is already cached under its own tag. What you give up is `"use cache"` in your own code.
+
+If the mode is on, the server log says so once, at the first page render:
+
+```text
+smoodly: Next's cacheComponents is on, and Smoodly does not support it — …
+```
+
+## Images
+
+`SmoodlyImage` from `smoodly/image` renders an `f.image()` value as a plain `<img>`, or a `<picture>` for named crops, over cuts from Smoodly's media host in AVIF or WebP. It does not use `next/image`, so `next.config.ts` holds no `images` setting and Vercel's image optimization is never billed. The component calls React's `preconnect` for the media host, which React places in the head. [Images and crops](../media/images-and-crops.md) has the rest.
+
+Next, [Upgrading](../reference/upgrading.md) says what a new version asks of your code.