smoodly 0.0.60 → 0.0.62

package/docs/collections/entry-pages.md

@@ -0,0 +1,168 @@
+# Entry pages
+
+Give a collection a path and each entry gets its own URL. The entry page is the component that renders one entry there.
+
+## The path
+
+`path` on a collection is the URL segment its entries live under. The starter's articles sit at `/posts/<slug>` in English and `/artikkelit/<slug>` in Finnish:
+
+File: `smoodly/collections.ts`
+
+```ts
+export const articles = smoodly.collection({
+  name: "articles",
+  title: "Articles",
+  titleField: "title",
+  path: { en: "posts", fi: "artikkelit" },
+  order: { by: "date", direction: "desc" },
+  fields: {
+    title: f.text().localized(),
+    image: f.image({ aspect: "3:2" }),
+    date: f.date(),
+    author: f.ref(() => people),
+    slug: f.slug({ from: "title" }),
+    excerpt: f.text().localized(),
+    // …
+  },
+});
+```
+
+A string applies to every language; an object names the segment per language. The collection needs a field named `slug` for the entry's own part. A collection without a `path` has no URLs: its entries appear only through references and queries.
+
+The path shows in the page tree as a mount, so editors see where the entries live. Pages cannot be created under it.
+
+## A nested path
+
+A path may have several parts. The starter's news sits under the company, at `/company/news/<slug>` and `/yritys/uutiset/<slug>` in Finnish:
+
+File: `smoodly/collections.ts`
+
+```ts
+export const news = smoodly.collection({
+  name: "news",
+  title: "News",
+  titleField: "title",
+  path: { en: "company/news", fi: "yritys/uutiset" },
+  order: { by: "date", direction: "desc" },
+  // …
+});
+```
+
+Your code owns the whole address, not just its last part. The *Company* page at `/company` is an editor's page, or no page at all: renaming or moving it never moves the news, because published URLs should not change with an easy rename in the admin. The page tree lists the collection at the root with its full URL, and editors cannot put a page on `/company/news` or under it.
+
+Each part follows the slug rule. A language the map leaves out takes the default language's address.
+
+Change the path in code and the URLs of the index page and every entry change when the deploy goes live: Smoodly stores only each entry's own part, never the address. The old URLs stop working, so add a redirect in `next.config.ts` for them, as [Paths and slugs](../pages/paths-and-slugs.md#redirects) shows.
+
+## The entry page
+
+**Astro**
+
+A collection with a `path` needs an entry page: `src/entry-pages/<collection>.astro`, named after the collection. It receives `entry` and `head`:
+
+File: `src/entry-pages/articles.astro`
+
+```astro
+---
+// …
+const { entry, head } = Astro.props;
+const { locale, locales } = entry;
+// …
+const a = entry.fields;
+// …
+const { entries: newest = [] } = await getLiveCollection("articles", { locale, limit: 4 });
+// …
+---
+<Layout head={head} locale={locale} locales={locales}>
+  <article class="container article">
+    // …
+      <h1 class="article__title">{a.title}</h1>
+    // …
+    {a.image && <Image image={a.image} aspect="21:9" class="article__image" sizes="(min-width: 900px) 800px, 100vw" priority />}
+    <div class="article__body prose prose--lead"><RichText doc={a.body} sizes="(min-width: 900px) 720px, 100vw" /></div>
+  </article>
+  // …
+</Layout>
+```
+
+The entry's `fields` are resolved: images are ready for `Image`, and a reference such as `author` is `{ id, path, fields }`, the person's fields under `fields`. Beside `fields` the entry carries its `id`, `path`, `locale`, the language rendered, and `locales`, which maps every language to the entry's address there, for a language switcher, and `seo` when the collection turns [SEO](../pages/seo.md#seo-for-entries) on. `head` goes to the layout's `Head`.
+
+There is nothing to register: the file is the entry page. A collection with a `path` and no file is named in the server log at the first request, and its entries answer 404.
+
+**Next.js**
+
+A collection with a `path` needs an entry page, or the site stops at the first render and names the collection. `smoodly.entryPage()` pairs the collection with a component. An entry page has no schema of its own, so it is listed in `pages` in `smoodly/views.ts`, not in the config:
+
+File: `components/pages/Article.tsx`
+
+```tsx
+import { smoodly } from "smoodly/react";
+import { RichText } from "@/smoodly/richtext";
+import { SmoodlyImage } from "smoodly/image";
+import { articles } from "@/smoodly/collections";
+// …
+export const ArticlePage = smoodly.entryPage(articles, async function ArticleView({ entry }) {
+  const { locale, locales } = entry;
+  // …
+  const a = entry.fields;
+  // …
+  return (
+    <PageFrame locale={locale} locales={locales}>
+      <article className="container article">
+        // …
+          <h1 className="article__title">{a.title}</h1>
+        // …
+        {a.image && <SmoodlyImage image={a.image} aspect="21:9" className="article__image" sizes="(min-width: 900px) 800px, 100vw" priority />}
+        <div className="article__body prose prose--lead"><RichText doc={a.body} /></div>
+      </article>
+      // …
+    </PageFrame>
+  );
+});
+```
+
+The view receives `entry`, whose `fields` are resolved: images are ready for `SmoodlyImage`, and a reference such as `author` is `{ id, path, fields }`, the person's fields under `fields`. Beside `fields` the entry carries its `id`, `path`, `locale`, the language rendered, and `locales`, which maps every language to the entry's address there, for a language switcher, and `seo` when the collection turns [SEO](../pages/seo.md#seo-for-entries) on. Register the export in the `pages` list of `smoodly/config.ts`, beside the page types.
+
+An entry page has no zones. It is your own markup over the entry's fields, and editors change the entry in its form rather than in a canvas.
+
+## The index page
+
+The list at `/posts` itself is an ordinary fixed page whose slug matches the collection's path in every language:
+
+File: `components/pages/Articles.schema.ts`
+
+```ts
+export const articlesSchema = smoodly.schema.page({
+  name: "articlesIndex",
+  title: "Articles",
+  slug: { en: "posts", fi: "artikkelit" },
+  zones: {
+    hero: z.locked(pageHeroSchema),
+  },
+  seo: true,
+});
+```
+
+Its view and its registration are any page type's (see [Page types](../content-modeling/page-types.md)), with the schema listed in `pages` in the config.
+
+**Astro**
+
+The view is `src/page-types/articlesIndex.astro`.
+
+**Next.js**
+
+The view is `export const ArticlesPage = smoodly.page(articlesSchema, ArticlesView)`, listed in `pages` in `smoodly/views.ts`.
+
+The list page is live as soon as you deploy it, with an empty hero until an editor fills it. Its row appears in *Pages* the next time someone opens the admin.
+
+Because the slugs match, that page is the mount: the row in the page tree opens its editor, editors own its hero, and its view queries the entries for the grid below. [Queries](../collections/queries.md) shows that part. A nested path works the same way: the News index page's slug is `{ en: "company/news", fi: "yritys/uutiset" }`.
+
+**Astro**
+
+Nothing changes in the routes: the integration's page shell already resolves a URL to a page, a path or an entry, and renders an entry with its collection's entry page.
+
+**Next.js**
+
+Nothing changes in the routes: the catch-all route already resolves a URL to a page, a path or an entry, and renders an entry with its collection's entry page.
+
+Next, [Queries](../collections/queries.md).

package/docs/collections/ordering.md

@@ -0,0 +1,47 @@
+# Ordering
+
+A collection has one order, set in its schema, that the admin's list and your queries share.
+
+## The order option
+
+`order` takes one of two shapes:
+
+| Name | Description |
+| --- | --- |
+| `{ by, direction }` | Sort by a field, or by createdAt or updatedAt, ascending or descending. Without an order, a collection is newest first. On the live site updatedAt is the time of the last publish, so a draft save moves nothing; in draft mode it is the last save. |
+| `"manual"` | Editors drag entries into an order in the admin. Queries return that order. |
+
+The starter uses both: articles by date, people by hand.
+
+File: `smoodly/collections.ts`
+
+```ts
+export const people = smoodly.collection({
+  name: "people",
+  title: "People",
+  titleField: "name",
+  order: "manual",
+  // …
+});
+// …
+export const articles = smoodly.collection({
+  name: "articles",
+  title: "Articles",
+  titleField: "title",
+  path: { en: "posts", fi: "artikkelit" },
+  order: { by: "date", direction: "desc" },
+  // …
+});
+```
+
+## By a field
+
+The field must be shared across languages, because the order is one list for every language. A localized field or the slug is refused at startup, and so is a field the collection does not declare. Numbers order as numbers and dates as dates, since a date field stores an ISO string.
+
+A query may override the order for one read with its own `order` option.
+
+## By hand
+
+With `"manual"`, the collection's list in the admin has a grip on every row, and dragging a row reorders the entries. The new order is immediate and not part of any draft: order belongs to the collection, not to an entry's version, so it needs no publish. On a multilingual site the order is shared by every language unless the config sets [`locales.order`](../languages/locales.md#one-order-or-one-per-language) to `"perLocale"`; then a drag reorders the language selected in the list, and a query returns its own language's order. Dragging works on flat collections; a nested collection, one with `tree`, lists its entries flat and cannot be reordered by drag.
+
+Next, [Globals](../globals/defining.md).

package/docs/collections/queries.md

@@ -0,0 +1,173 @@
+# Queries
+
+Read entries, globals and the page tree from your own views, typed by your registry, cached, and aware of drafts.
+
+## The read API
+
+**Astro**
+
+The reads are Astro live collections. `src/live.config.ts` names one loader per collection, global item, the pages and the page tree, from `smoodly/astro/content`:
+
+File: `src/live.config.ts`
+
+```ts
+export const collections = {
+  pages: defineLiveCollection({ loader: pageLoader() }),
+  pageTree: defineLiveCollection({ loader: pageTreeLoader() }),
+  articles: defineLiveCollection({ loader: entriesLoader(articles) }),
+  // …
+  footer: defineLiveCollection({ loader: globalLoader(footer) }),
+  // …
+};
+```
+
+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 });
+---
+```
+
+| Name | Description |
+| --- | --- |
+| `getLiveCollection("articles", options)` | Published entries of a collection, in the collection's order. Options: locale, where, order, limit, offset, parent. |
+| `getLiveEntry("articles", { path, locale })` | One entry by its URL path, or by id, with its references resolved. |
+| `getLiveEntry("footer", { locale })` | A global item's value in a language, for a layout. |
+| `getLiveEntry("pages", { path, locale })` | A page by URL path or id. |
+| `getLiveCollection("pageTree", { locale })` | The published page tree in a language, each item with its page fields, for a navigation. |
+
+Each result's `data` is the read shape below. Every read tags the response, so a publish expires the page that made it.
+
+**Next.js**
+
+`smoodly/server.ts` exports `q`, a set of read functions typed by the collections and globals you registered:
+
+File: `smoodly/server.ts`
+
+```ts
+export const q = (): Queries =>
+  new Proxy({} as Queries, {
+    get: (_, name) => async (...args: unknown[]) => {
+      await buildGate();
+```
+
+Each call passes the build gate before it reads the keys: while `next build` prerenders it waits for a request, so the build needs no keys; at run time it does nothing, so a page that calls `q()` stays cacheable.
+
+Call it in a server component, a page type's view or a route:
+
+File: `components/pages/Articles.tsx`
+
+```tsx
+import { q } from "@/smoodly/server";
+// …
+  const items = await q().getEntries("articles", { locale });
+```
+
+| Name | Description |
+| --- | --- |
+| `getEntries(collection, options)` | Published entries of a collection, in the collection's order. Options: locale, where, order, limit, offset, parent. |
+| `getEntry(collection, idOrPath, options)` | One entry by id or by its URL path, with its references resolved. |
+| `getGlobal(name, options)` | A global's value in a language, for a layout or a page frame. |
+| `getPage(pathOrId, options)` | A page by URL path or id. |
+| `getPageTree(options)` | The published page tree in a language, each item with its page fields, for a navigation. |
+
+Every read takes `locale`; without it, the default language. Collection and global names are checked against the registry, so a typo is a type error.
+
+## What comes back
+
+Every read returns Smoodly's own keys at the top level and your content under `fields`, so a collection may have a field called `path` without a clash. Nothing else leaves the read: other languages' rows, draft pointers and editors' emails stay inside.
+
+| Read | Shape |
+| --- | --- |
+| `An entry` | `{ id, path, locale, locales, updatedAt, fields, seo? }`. `path` is the entry's URL in that language, or `null` without a collection path; `locales` is its address in every language; `updatedAt` is the last publish on the live site and the last save in draft mode; `seo` is present when the collection turns SEO on. |
+| `A page` | `{ id, title, path, locale, locales, template, fields, seo?, ancestors, children }`. `seo` is present when the page type has `seo: true`. |
+| `A global` | `{ locale, fields, settings?, styles? }`. A visual global adds `settings` and `styles`; an object global has `fields` only. |
+
+A collection read returns a list of these, `fields` typed from the collection, so an item needs no cast:
+
+**Astro**
+
+File: `src/page-types/articlesIndex.astro`
+
+```astro
+      {entries.map(({ data: entry }) => <ArticleCard article={entry.fields} url={href(entry.path!, page.locale)} locale={page.locale} />)}
+```
+
+**Next.js**
+
+File: `components/pages/Articles.tsx`
+
+```tsx
+          {items.map((entry) => (
+            <ArticleCard key={entry.id} article={entry.fields} url={url(entry.path!)} locale={locale} />
+          ))}
+```
+
+A reference arrives resolved, as deep as its own field says: a bare `f.ref` gives `{ id, path, fields }` and its target's references stay ids, `.resolve("author")` follows the named reference one level, and `.resolve()` follows the whole chain. [Reference and tags](../fields/reference-and-tags.md) has the table. In a list, images and references resolve in one batched pass per referenced collection, so a card has its author's fields and its image URL without a second read. A single entry resolves them the same way.
+
+## Filtering and limiting
+
+`where` matches fields by equality, or by any of several values:
+
+**Astro**
+
+File: `src/entry-pages/articles.astro`
+
+```astro
+---
+// …
+const { entries: byAuthor = [] } = authorId ? await getLiveCollection("articles", { locale, where: { author: authorId } }) : { entries: [] };
+// …
+---
+```
+
+**Next.js**
+
+File: `components/RecentNews.tsx`
+
+```ts
+import { q } from "@/smoodly/server";
+
+export async function recentNews(locale: string) {
+  const items = await q().getEntries("articles", { locale, where: { date: "2026-09-02" }, limit: 3 });
+  return items.map((item) => item.fields.title);
+}
+```
+
+`where` sees every field, localized ones included, and filters the version shown: on the public site the published version, in the editor's preview the draft, so an unpublished edit never touches the live list. `slug` is not filterable, so find an entry by its path instead. For an array field such as tags or checkboxes, one value matches entries that contain it. The match is exact, case included. A tag is stored in the spelling the collection already uses, so once one entry has `Dinner`, another that types `dinner` stores `Dinner` too: filter with that spelling. `limit` applies after ordering and after the published-only filter, so it counts entries that are really there, and `order` overrides the collection's default for one query.
+
+The starter's article page reads the four newest articles and drops itself to show three related ones.
+
+## Paging a list
+
+`offset` skips that many entries after the order and the filter, before `limit` counts, so page N of a list is `limit` entries from `(N - 1) * limit`. The read returns the page's entries and no total: ask for one entry more than you show to know whether a next page exists.
+
+**Astro**
+
+Pass the same two options to `getLiveCollection`: `{ locale, limit: perPage + 1, offset: (page - 1) * perPage }`, show the first `perPage` entries, and link to the next page when the read returned one more.
+
+**Next.js**
+
+File: `components/ArticlePage.tsx`
+
+```ts
+import { q } from "@/smoodly/server";
+
+export async function articlePage(locale: string, page: number, perPage = 10) {
+  const items = await q().getEntries("articles", { locale, limit: perPage + 1, offset: (page - 1) * perPage });
+  return { items: items.slice(0, perPage), hasNext: items.length > perPage };
+}
+```
+
+Each page is cached as its own read and expires with the collection, like any other list.
+
+## Draft mode and caching
+
+Inside the editor's canvas every query reads the draft rows: an unpublished article shows in the index grid as it will after publish. On the public site queries read published rows only and are cached; publishing an entry, a global or a page expires the queries that showed it, so the live site updates at once. A list is tagged by its collection and by every collection its references resolved into, so editing an author refreshes the article lists that show that author.
+
+Next, [Ordering](../collections/ordering.md).

package/docs/content-modeling/changing-schemas.md

@@ -0,0 +1,79 @@
+# When the schema changes
+
+Sites change after launch: a section goes, a field is renamed, a zone gets stricter. This page covers what stored content keeps when the code moves on, how the admin shows it, and what Publish refuses until an editor fixes it.
+
+## What a change leaves behind
+
+Smoodly never rewrites stored content when you deploy. A page, an entry or a global keeps what it held, and the admin compares it with the code you deployed. What it finds falls into two kinds: **broken** content blocks the next publish, **left over** content is only reported.
+
+| Change | What stays stored | Publish |
+| --- | --- | --- |
+| `Remove a section` | Every placed copy of it. The canvas shows a placeholder; the site renders nothing for it. | Refused |
+| `Rename or remove a field` | The old key and its value. The admin lists it under No longer in the schema; the new field starts empty. | Allowed, unless the new field is required: then Required until it is filled |
+| `Change a field's type` | The old value. When it doesn't fit the new type, such as text in f.number(), the field shows an error. | Refused when it doesn't fit |
+| `Remove a select option` | The value. It no longer fits the field. | Refused |
+| `Tighten a zone` | Sections the zone no longer allows, and sections over its .max(). | Refused |
+| `Remove a zone from a page type` | The zone's sections, no longer shown. | Allowed |
+| `Remove an element` | Every copy of it inside richtext. Its card in the editor says the code no longer registers it. | Refused |
+| `Drop an element from a toolset` | Every copy of it. It still renders, because a toolset only decides what editors can insert. | Allowed |
+| `Remove a page type` | Its pages. The canvas shows the site's 404 until the page gets another type. | Refused |
+| `Remove a collection` | Its entries. The admin has no editor for them, so register it again or delete them. | No editor |
+| `Toggle .localized()` | Every value. See Localized fields. | Allowed |
+
+An empty value always fits: a new required field on old content is a *Required* error, as it is for new content.
+
+## Content health
+
+*Settings › Content health* lists every page, entry and global that doesn't match the code. Every member can open it, because editors do most of the fixing. It checks when it opens and when you press *Rescan*.
+
+Findings come in two sections, *Blocks publishing* and *Left over*. Each group is one change you made, like "Field `title` no longer in section `hero`", with the documents it touches under it. A row names the document, its languages and where the problem sits:
+
+- *Draft* only: the next publish will be refused until it is fixed.
+- *Live* only: the site runs on content the code no longer describes, and the draft is already fixed. Publishing clears it.
+- Both: fix it in the draft, then publish.
+
+*Open* goes to the document's editor. The page only points; fixes happen in the editors.
+
+## In the editor
+
+A document with findings shows a notice under the top bar: "2 problems block publishing · 1 left over from an older schema". The page editor marks each affected section in the *Page Outline*, red for broken and grey for left over, and the fixes are where the problems are:
+
+- **An unknown section** shows as a placeholder on the canvas. Select it to see its stored values, each with *Copy*, and *Remove section*.
+- **A value that doesn't fit** is an error on its field. Typing a new value replaces it.
+- **Left-over keys** sit in a collapsed *No longer in the schema* group at the foot of the form, each with *Copy* and *Clear*.
+- **A removed zone** is listed after the real zones with *Clear zone*.
+
+Every fix is an ordinary draft edit: it autosaves, and *Discard changes* or the history undoes it.
+
+## What Publish refuses
+
+Publish refuses broken content with the problems listed, the same way it refuses an empty required field. Left-over content never blocks it. The check runs on the server, so an editor can't publish around it.
+
+Live pages are not rewritten. After a deploy the stored live version stays as it was, and a section the code no longer registers renders nothing on the site. The next publish takes the fixed draft live.
+
+## Renaming a field
+
+Rename a field in two steps, so no editor loses a value. First put the new field in the schema where the old one was, and deploy:
+
+File: `components/elements/Callout.schema.ts`
+
+```ts
+import { f, smoodly } from "smoodly";
+
+export const calloutSchema = smoodly.schema.section({
+  name: "callout",
+  title: "Callout",
+  fields: {
+    // was `title`: stored values stay under the old key until an editor moves them
+    heading: f.text(),
+  },
+});
+```
+
+Then, for each page *Content health* lists under "Field `title` no longer in section `callout`": copy the value from the *No longer in the schema* group into *Heading*, *Clear* the old key and publish.
+
+There is no bulk rename in the admin yet. A tool that rewrote every page at once could break every live page with one wrong mapping, so its shape is still an open question. For many pages, a script can do it for your own site: walk `pages.list()`, read each page with `getTree`, move the value, write it back with `setTree` and publish, as [Content from code](../getting-started/content-from-code.md) shows. Until it runs, a required field under the new name renders empty on the live site; nothing warns a visitor.
+
+A rename also fails the type check wherever code writes the old name (`npx tsc --noEmit`; `npx astro check` on Astro, whose `astro build` does not type-check; a dev server or a build pushes the renamed schema to the space when it starts), such as the starter's `scripts/seed.ts`: its `node()` calls are typed from the section. The seed has already run, so update the name there or delete the script.
+
+Next, [Localized fields](../languages/localized-fields.md).

package/docs/content-modeling/custom-section.md

@@ -0,0 +1,94 @@
+# The custom section
+
+The one section editors lay out themselves: rows of richtext columns on a 12-column grid, offered where a zone allows it. You turn it on, pick what its columns may hold, and style the result; Smoodly owns the grid.
+
+To write a section of your own in code, see [Sections](../content-modeling/sections.md).
+
+## Turning it on
+
+A zone offers the custom section when its policy says so. The starter's body zones do:
+
+File: `components/pages/Home.schema.ts`
+
+```ts
+  zones: {
+    hero: z.locked(heroSchema),
+    body: z.freeform({ sections: [imageTextSchema, pointsSchema, favouriteArticlesSchema, peopleSchema, quoteSchema], custom: true }),
+  },
+```
+
+Only `z.freeform()` takes `custom: true`. *Custom section* then appears in *Add section* after the listed sections.
+
+What a column may hold comes from the config's toolset. The starter gives the columns its article toolset, so a column can hold headings, lists, images and the two elements:
+
+File: `smoodly/config.ts`
+
+```ts
+export const config = defineConfig({
+  // …
+  custom: { toolset: article },
+});
+```
+
+**Astro**
+
+The columns render through the package's own richtext view, with images through Astro's image service and your elements by file name. There is nothing to bind.
+
+**Next.js**
+
+`smoodly/views.ts` binds the richtext renderer, so images render through the site's image component:
+
+File: `smoodly/views.ts`
+
+```ts
+export const views = () =>
+  defineViews(config, {
+    // …
+    RichText,
+  });
+```
+
+Without `custom` in the config, the columns take the richtext default plus images. `breakpoint` sets where rows stack; the default is `48rem`.
+
+## What editors get
+
+A new custom section is one row with one column. Each row is a card in the inspector:
+
+| Name | Description |
+| --- | --- |
+| `Columns` | A stepper from one to six. Removing a column folds its content into the last one, so nothing is lost. |
+| `Widths` | A bar dragged in twelfths, with presets such as 1/2 · 1/2 and 1/3 · 2/3. Spans always add up to 12. |
+| `Gap` | S, M or L between the columns. |
+| `Vertical align` | Top, Center, Bottom or Stretch. |
+| `Reverse on mobile` | Flips the column order when the row stacks, so a photo can sit right on desktop and first on a phone. |
+| `Column 1, Column 2, …` | A richtext editor per column, with the toolset from the config. |
+
+Rows move up and down, and a section keeps at least one. In the canvas the section is labeled by its first row, *Custom section · 2 columns*, and clicking a column reveals its editor in the inspector. Like any section it has *Spacing & layout* and, when the config allows, *Custom CSS* on its Settings tab.
+
+## How it renders
+
+The section renders through the same wrapper as yours, so spacing, width, selection and the CSS box come free. Smoodly adds one scoped style per custom section, computed from the stored numbers only:
+
+- Each row is a grid, `.smd-row`, with its spans as `fr` tracks, its gap and its vertical alignment. Rows sit 2rem apart.
+- A row's width is `var(--smd-width, var(--container, none))`, with `var(--smd-gutter, 1rem)` at the sides, so define `--container` and `--smd-gutter` once and rows line up with your other sections.
+- Below the breakpoint every row stacks to one column, and a reversed row stacks bottom-up.
+
+Your stylesheet styles the content. Each column is a `.smd-col`; the starter gives it the same rules as its prose:
+
+File: `app/globals.css`
+
+```css
+/* The custom section's columns (.smd-col) read like prose. */
+.prose, .smd-col { display: flex; flex-direction: column; gap: 20px; font-size: 17px; line-height: 1.65; color: var(--muted); }
+.prose h2, .smd-col h2 { font-size: 32px; margin-top: 8px; }
+```
+
+Nothing else is required: a site with no rules for `.smd-col` still gets working columns.
+
+## What it cannot do
+
+A column holds richtext: text, headings, lists, images and elements. It never holds a section or another row, so the nesting stays one level deep and the canvas, drag and drop and history keep working. A layout that needs more than columns of text is a section you write.
+
+At publish, Smoodly checks that each row has one to six columns and that its spans add up to 12. An empty column is allowed; it is spacing.
+
+Next, [Marks and inline editing](../content-modeling/marks.md) explains how the canvas knows what to make click-to-edit.

package/docs/content-modeling/marks.md

@@ -0,0 +1,97 @@
+# Marks and inline editing
+
+Marks are the attributes a section spreads on the elements that render its fields. They tell the canvas which field an editor clicked, so text edits in place and everything else opens in the inspector.
+
+## What a mark is
+
+`smoodly.marks(heroSchema)` returns typed helpers for one schema. `m.field("heading")` is an object with one `data-` attribute naming the field; spread it on the element that renders the heading. The section root, rendered by Smoodly's section wrapper, carries the section's own id. From a click the canvas walks up from the marked element to that root and knows which field of which section was meant.
+
+Outside the admin the marks are plain data attributes and do nothing. The typed helpers exist so a renamed field is a type error rather than a dead click.
+
+## Marking a field
+
+Put the mark on the element that shows the value as stored:
+
+**Astro**
+
+File: `src/sections/hero.astro`
+
+```astro
+---
+// …
+const m = smoodly.marks(heroSchema);
+---
+// …
+      {kicker && <p class="kicker" {...m.field("kicker")}>{kicker}</p>}
+      <h1 class="hero__heading" {...m.field("heading")}>{heading}</h1>
+      <p class="hero__text" {...m.field("text")}>{text}</p>
+      // …
+    {image && <Image image={image} class="hero__image" sizes="(min-width: 900px) 40vw, 100vw" priority {...m.field("image")} />}
+```
+
+**Next.js**
+
+File: `components/sections/Hero.tsx`
+
+```tsx
+const m = smoodly.marks(heroSchema);
+// …
+          {kicker && <p className="kicker" {...m.field("kicker")}>{kicker}</p>}
+          <h1 className="hero__heading" {...m.field("heading")}>{heading}</h1>
+          <p className="hero__text" {...m.field("text")}>{text}</p>
+// …
+        {image && <SmoodlyImage image={image} className="hero__image" sizes="(min-width: 900px) 40vw, 100vw" priority {...m.field("image")} />}
+```
+
+Hovering a marked element outlines it in the canvas. What a click does depends on the field:
+
+| Field | On click |
+| --- | --- |
+| `f.text()` | Edits in place. The element becomes editable, and each keystroke updates the draft. Escape or a click elsewhere ends it. |
+| `f.richtext()` | Edits in place, with the richtext toolbar floating above the selection. |
+| `Everything else` | Opens the inspector on that field: the media picker for an image, the repeater for a list, the pills for a choice. |
+
+In-place text editing needs an element with nothing but text inside. A mark on an element with child elements, such as a paragraph holding a link, falls through to the inspector. So does a mark on an element that shows the value transformed, in effect: the canvas would write the stored value over the formatted one. Leave a formatted date unmarked, or mark its container.
+
+The image component passes data attributes to its wrapper, so a mark on it selects the image box.
+
+## Lists and objects
+
+A list item or an object field is a scope of its own. `m.item("buttons", i)` returns a helper for one item: spread its `attrs` on the item's root element and use its `field()` for the fields inside. The starter's Hero buttons put both on the same anchor:
+
+**Astro**
+
+File: `src/sections/hero.astro`
+
+```astro
+          {buttons.map((b, i) => {
+            const button = m.item("buttons", i);
+            return <a class={i === 0 ? "button" : "button button--outline"} href={safeHref(b.href)} {...button.attrs} {...button.field("label")}>{b.label}</a>;
+          })}
+```
+
+**Next.js**
+
+File: `components/sections/Hero.tsx`
+
+```tsx
+              {buttons.map((b, i) => {
+                const button = m.item("buttons", i);
+                return (
+                  <a key={i} className={i === 0 ? "button" : "button button--outline"} href={b.href}
+                    {...button.attrs} {...button.field("label")}>{b.label}</a>
+                );
+              })}
+```
+
+`m.object("link")` works the same way for an object field. A scope nests: `m.item("points", i).object("author")` reaches a field inside an object inside a list item.
+
+A mark for the whole list, such as `m.field("people")` on the grid that renders a reference list, opens the list in the inspector.
+
+## What the canvas checks
+
+A click on a mark that names a field the schema does not have logs a warning in development, naming the section and the path, and then does nothing. Check the `data-smd-field` and `data-smd-item` attributes it names.
+
+Globals in the canvas, such as the starter's header, footer and quote, are marked the same way. Selecting one shows its own fields in the inspector, tagged *global*, with its own *Publish*, because publishing a footer to every page is a deliberate click. [Globals](../globals/defining.md) has the details.
+
+Next, the [Fields](../fields/overview.md) group lists every field type and what editors see for each.