@acms-subir/core 0.3.3-next.20260929113209 → 0.3.4

package/docs/sections.md

@@ -0,0 +1,203 @@
+# Editable sections: code the look, leave the content editable
+
+This is the guide for agents (and people) building pages for an ACMS site. The rule is simple:
+
+> **Code decides how things look. Section fields decide what the owner can change.**
+
+The owner will update service times, events, prices, people and text long after you're gone, in Design → Pages, without touching code. So anything that might change must be a **field**, never hardcoded in the component.
+
+## The three layers
+
+| Layer | Lives in | Owned by |
+| --- | --- | --- |
+| Code | `src/themes/<theme>/sections/*.astro` | you (the agent). Rewrite freely |
+| Schema | `theme.json → sections.<type>.fields` | the contract between both |
+| Data | the site database (Design → Pages) | the owner. Never overwrite it |
+
+Changing code needs a build and deploy. Changing data never does.
+
+## Workflow
+
+```sh
+acms inspect --json                          # project, themes, capabilities
+acms docs sections                           # this guide
+acms section library                         # ready-made sections to start from
+acms section add service-times --theme church
+acms section add upcoming-events --theme church
+acms section new visit-banner --theme church # blank scaffold
+# edit theme.json fields + the .astro markup
+acms check --build                           # validate, refresh section-types.d.ts, compile
+```
+
+With a mobile app beside the site (`acms add mobile`), library sections render
+natively in the app out of the box; `acms section add <name> --theme <t> --native`
+copies an editable native version into `mobile/sections/`, `acms section new`
+also writes a typed native stub there, and `acms check` lists sections the app
+can only show as a web view. Keep a section's native version in step with its
+fields and variants.
+
+Then give the page starting content in one of two ways:
+
+1. **A preset** in `theme.json` (preferred for code-first work). The owner sees "Start from Church home" in Design → Pages and gets a copy they can edit:
+
+   ```json
+   "presets": {
+     "church-home": {
+       "name": "Church home",
+       "description": "Hero, service times, next events, visit info",
+       "sections": [
+         { "type": "hero-banner", "variant": "cover", "data": { "heading": "A church for the whole city." } },
+         { "type": "service-times", "data": { "services": [ { "title": "Sunday Worship", "day": "Sunday", "time": "10:00" } ] } },
+         { "type": "upcoming-events", "data": { "events": { "calendar": "youth", "limit": 3 } } }
+       ]
+     }
+   }
+   ```
+
+2. **MCP / agent API** when you're connected to a live site: `list_section_types`, `get_page_layout`, `set_page_layout`, `update_section_data`. Everything stages into the design draft. The owner publishes.
+
+## Defining a section
+
+```json
+"sections": {
+  "service-times": {
+    "name": "Service times",
+    "description": "Weekly gatherings with day, time and a short note.",
+    "version": 1,
+    "component": "sections/ServiceTimes.astro",
+    "variants": ["cards", "strip"],
+    "fields": {
+      "heading":  { "label": "Heading", "type": "text", "default": "Join us this week" },
+      "services": { "label": "Services", "type": "list", "itemLabel": "title", "max": 12, "fields": {
+        "title":    { "label": "Name", "type": "text" },
+        "day":      { "label": "Day", "type": "select", "options": ["Sunday", "Wednesday"], "default": "Sunday" },
+        "time":     { "label": "Time", "type": "time", "default": "10:00" },
+        "streamed": { "label": "Streamed online", "type": "toggle" }
+      } }
+    }
+  }
+}
+```
+
+Field keys are camelCase. Every field takes `label`, optional `help` (one line shown under the input) and `default`.
+
+### Field types
+
+| Type | Stored value | Component receives | Use for |
+| --- | --- | --- | --- |
+| `text` | string | string | headings, names, short lines |
+| `textarea` | string | string (keep newlines with `white-space: pre-line`) | paragraphs, addresses |
+| `richtext` | HTML | **sanitized** HTML: render with `set:html` | answers, notes with links/lists |
+| `image` | URL | safe URL or `''` | photos (owner picks from the media library) |
+| `url` | URL | safe URL or `''` | bare links |
+| `link` | `{ label, href, ref? }` | `LinkValue { label, href, external }` | buttons. `ref` follows a page/post/event/booking if its address changes |
+| `select` | string | one of `options` | small fixed choices |
+| `number` | number | number | counts |
+| `toggle` | boolean | boolean | show/hide flags |
+| `date` | `YYYY-MM-DD` | string. Format with `formatDay()` | one-off dates |
+| `time` | `HH:MM` | string. Format with `formatTime()` | times of day |
+| `list` | array of rows | array of rows (sub-fields resolved the same way) | repeating things: services, people, plans, photos |
+| `source` | `{ calendar?, collection?, tag?, resource?, limit }` | fresh `EventItem[]` / `PostItem[]` / `BookingItem[]` | content that must stay current on its own |
+
+`list` options: `fields` (scalar sub-fields only; a list can't contain a list or source), `itemLabel` (the sub-field shown on collapsed rows), `min`, `max` (default 50).
+
+`source` options: `source: "events" | "posts" | "bookings"`. The owner picks which calendar / collection + tag / resource, and how many (1–24).
+
+**When to use `source` instead of `list`:** if the thing already exists elsewhere in ACMS (calendar events, blog posts, booking links), link to it with `source`. Then the homepage updates itself when the calendar changes. Use a `list` only for content that lives nowhere else.
+
+### More schema options
+
+| Where | Option | What it does |
+| --- | --- | --- |
+| section | `category` | Groups it in the "Add a section" picker ("Intro", "Events & times", "People"…) |
+| section | `example` | Sample data: renders the picker thumbnail and fills **empty** fields in the admin preview (never saved, never shown to visitors). Always provide one |
+| section | `limit` | At most this many per page (e.g. `1` for a hero) |
+| section | `presets` | Extra ready-filled picker entries: `[{ "name": "Service times: holiday", "variant": "strip", "data": {…} }]` |
+| field | `visibleIf` | Show only when a sibling matches: `{ "field": "style", "equals": "image" }` (also `notEquals`, `in`, or no operator = "is filled in"). Works inside list rows against the row |
+| field | `required`, `maxLength` | Enforced in the editor (live counter), before publishing, and by `acms check` for examples/presets |
+| field | `aiHint` | Guidance for "Help me write" on that field ("friendly, under 12 words") |
+| field | `locked` | Only owners can change it; editors see it read-only |
+
+Owners can also lock a whole section, and schedule any section with **Show from / until** (site timezone). Image fields get a **focal point**: the component receives `<key>Focus` (e.g. `data.imageFocus`, or `row.photoFocus` in lists) ready for `style={`object-position:${data.imageFocus}`}`, or for `background-position`. Use it on every cropped image.
+
+## Writing the component
+
+```astro
+---
+import type { SectionProps } from '@acms-subir/core/theme';
+import { formatTime } from '@acms-subir/core/theme';
+import type { ServiceTimesData } from '../section-types';   // generated by acms check / acms theme types
+const { data, variant, settings } = Astro.props as SectionProps<ServiceTimesData>;
+---
+<div class:list={['times', `is-${variant}`]}>
+  <h2>{data.heading}</h2>
+  <ul>
+    {data.services.filter((s) => s.title).map((s) => (
+      <li><b>{s.title}</b> {s.day} · {formatTime(s.time, settings.locale)}</li>
+    ))}
+  </ul>
+</div>
+<style>/* scoped; anything goes */</style>
+```
+
+The component receives `data` (resolved values, defaults filled in), `variant`, `settings` and `page`. The core wraps it in `<section class="acms-section section-<type> variant-<variant>">`.
+
+Rules:
+
+- **Render empty values gracefully.** Every field can be empty; lists can have zero rows; sources can return nothing. Skip empty rows (`filter((s) => s.title)`), and show an "empty" line for sources.
+- **Only `richtext` is HTML.** Never `set:html` any other field.
+- Style with theme tokens (`--accent`, `--ink`, `--muted`, `--panel`, `--soft`, `--line`, `--bg`, `--r`, `--r-sm`, `--r-lg`, `--font-heading`, `--font-body`) so the section follows the theme and dark mode. Reuse `.w-btn primary|outline` for buttons.
+- No data fetching in components. Anything dynamic comes through a `source` field.
+- Text the owner might reword (headings, button labels, "See all" links, empty-state lines) is a field with a sensible `default`.
+
+## Responsive: phone *and* desktop, every time
+
+A section that only works at one width is broken. Design for both ends, not "mobile, stretched":
+
+- **The frame is wide.** Section pages break out of the article column to the theme's `--wide-width` (about 1080px, the same frame as the header). Use that room on desktop: multi-column grids, side-by-side copy and media, split layouts. A single narrow column floating on a wide screen is a bug. Cap only *prose* line length (`max-width: 60ch` on paragraphs), never the whole section.
+- **Grids adapt.** Prefer `repeat(auto-fit, minmax(min(100%, 15rem), 1fr))`, which fills desktop and stacks on phones with no media query. Fixed column counts (`repeat(3, …)`) need `@media` steps down to 2 and then 1.
+- **Split layouts stack.** Two-column (text | image, info | hours) collapses to one column below roughly 700px; decide what comes first on phones.
+- **No fixed widths.** No `width: 600px`. Use `%`, `fr`, `min()`, `clamp()` and `max-width`. Nothing may cause sideways scrolling at 360px.
+- **Type and spacing scale.** Headings and padding use `clamp()` so they're big on desktop and sensible on phones.
+- **Touch targets** are at least 44px tall on phones.
+
+Check every section at **390px (phone), 768px (tablet) and 1280–1440px (desktop)**. The Design screen's preview has all three (Mobile · Tablet · Desktop), and `acms theme dev` does too. `acms check` flags common desktop and phone traps (fixed pixel widths, fixed column counts without a breakpoint), but only looking at it proves it.
+
+## Other languages
+
+With `acms({ i18n: { locales: ['en', 'es'] } })`, a page keeps **one** layout. Each section stores its facts once (times, dates, photos, links, linked events) and, per extra language, only its **words**. `/es` renders the same sections with the Spanish words, falling back to English field by field. Owners translate in Design → Pages → Español, and AI drafts the Spanish automatically whenever the English changes (marked "AI draft" until someone reviews it).
+
+What translates by default: `text`, `textarea`, `richtext`, and the label of a `link`. Everything else is shared. Adjust per field:
+
+- `"translatable": false` on a text field that isn't words: phone numbers, emails, prices, street addresses, names of people.
+- `"translatable": true` on a `select` whose options are words (e.g. weekday names).
+
+Components need nothing special: they receive the data already in the visitor's language, and `settings.locale` is set to it, so format dates and times with it (`formatTime(s.time, settings.locale)`) and they come out right (`19:30`, `sáb, 3 oct`). Fixed words written into a component (a "See all" label) stay in the main language. Make them fields if they must translate.
+
+List rows get a hidden `_id` so their translations follow them when reordered. Keep `_id` when you rewrite rows in migrations.
+
+## Changing a section later without losing content
+
+Saved data is keyed by field key. So:
+
+- **Adding a field** is always safe. Give it a `default`.
+- **Removing a field** is safe. Its saved value is kept (the owner sees "kept in case the theme brings it back").
+- **Changing a textarea of `a | b` lines into a list** is automatic: stored strings become rows, cells map to sub-fields in order.
+- **Renaming or reshaping a field:** bump the section's `version` and add `migrations/<type>.mjs`:
+
+  ```js
+  // src/themes/church/migrations/service-times.mjs
+  export default function migrate(data, fromVersion) {
+    if (fromVersion < 2) data.services = (data.services ?? []).map(({ name, ...row }) => ({ ...row, title: name }));
+    return data;
+  }
+  ```
+
+  The site renders old data through the migration immediately. The owner's "Upgrade sections" button saves the upgraded copy. Without a migration, a version bump hides the section until one exists.
+
+## Check before you finish
+
+- `acms check --build` passes. It validates fields, list labels, select defaults, presets and migrations, and compiles.
+- Every piece of changeable content is a field; nothing the owner would edit is hardcoded.
+- Each section looks right with empty fields, one row and many rows, in light and dark, at **phone (390px), tablet (768px) and desktop (1280px+)** widths. On desktop it uses the wide frame (no lonely narrow column); on phones nothing scrolls sideways.
+- In Design → Pages (or the preview's **Edit** chips), every section opens a form that makes sense to a non-developer: clear labels, `help` where needed, `itemLabel` set on lists.

package/docs/theme-authoring.md

@@ -32,9 +32,25 @@ const { page, posts } = Astro.props;
 {posts.map(post => <PostCard href={collectionUrl(post.collection, post.slug)} title={post.title} excerpt={post.excerpt} />)}
 ```
 
-Public types: HomeProps (settings, page, posts, tags), PageProps (settings, page, html), PostProps (settings, post, html, authors, related), EventProps (settings, event, occurrence, calendars, html, upcoming, origin, preview, rsvp), SectionProps (settings, page, variant, data). Public components: PostCard with card/row/feature variants, Pager with base/page/count, TagLabel with name/href/accent. Helpers include collectionUrl, postUrl, postsIndexUrl, tagUrl, formatDate, slugify, authorSlug, localeFromPath, localeHomeUrl and CONTENT. Use collectionUrl for non-default collections; postUrl is the built-in posts alias.
+Public types: ChromeProps (site), HomeProps (settings, page, posts, tags), PageProps (settings, page, html), PostProps (settings, post, html, authors, related), EventProps (settings, event, occurrence, calendars, html, upcoming, origin, preview, rsvp), SectionProps (settings, page, variant, data). Public components: PostCard with card/row/feature variants, Pager with base/page/count, TagLabel with name/href/accent. Helpers include collectionUrl, postUrl, postsIndexUrl, tagUrl, formatDate, slugify, authorSlug, localeFromPath, localeHomeUrl and CONTENT. Use collectionUrl for non-default collections; postUrl is the built-in posts alias.
 
-Template filenames: `home.astro`, `event.astro`, `post-<name>.astro`, `page-<name>.astro`. Post/page variants are selected in the content editor. Core owns routes, auth, SEO and published-content queries. Templates only replace their documented content area. Never query private data from a public section or insert untrusted strings with set:html. The core's rendered `html`/`bodyHtml` is the intended rich-content handoff.
+Template filenames: `home.astro`, `event.astro`, `header.astro`, `footer.astro`, `post-<name>.astro`, `page-<name>.astro`.
+
+`header.astro` and `footer.astro` replace the site header and footer on every public page. They receive `ChromeProps` — one `site` prop (`SiteChrome`) with everything already resolved for the request: `title`, `tagline`, `logo`, `homeUrl`, `links` (header nav, each `{ label, url, current, external }`, already localized), `footerLinks`, `social` (with inline SVG `icon`), `readLinks`, `footerHtml`, `languages` (`{ code, label, url, current }`, where `label` is the language's own name, e.g. "Español"), `search` (`{ url, label }` or null), `schemeToggle`, `liveHeader`, `headerStyle`, `footerStyle`. Core behaviors attach through data hooks, so keep them on your own elements: `data-search-open` (opens search), `data-scheme-toggle` (light/dark), `data-menu-open` (phone menu sheet, built from `site.links`) and a hidden `data-live-header` link (shown during a live stream).
+
+```astro
+---
+import type { ChromeProps } from '@acms-subir/core/theme';
+const { site } = Astro.props as ChromeProps;
+---
+<header class="gh-head">
+  <a href={site.homeUrl}>{site.logo ? <img src={site.logo} alt={site.title} /> : site.title}</a>
+  <nav>{site.links.map((l) => <a href={l.url} aria-current={l.current ? 'page' : undefined}>{l.label}</a>)}</nav>
+  {site.languages.map((l) => <a href={l.url} lang={l.code} aria-current={l.current ? 'true' : undefined}>{l.label}</a>)}
+  {site.search && <a href={site.search.url} data-search-open>{site.search.label}</a>}
+  <button type="button" data-menu-open aria-label="Open menu">Menu</button>
+</header>
+``` Post/page variants are selected in the content editor. Core owns routes, auth, SEO and published-content queries. Templates only replace their documented content area. Never query private data from a public section or insert untrusted strings with set:html. The core's rendered `html`/`bodyHtml` is the intended rich-content handoff.
 
 ## Editable sections
 
@@ -56,7 +72,7 @@ Custom definitions live in `theme.json`:
 }
 ```
 
-The component receives SectionProps. Supported field kinds: text, textarea, image, url, select (options required), number. Instances have stable id/type/version/variant/hidden/data fields. A page layout has mode and sections, persisted by page ID in `settings.sectionPages`. Section values and order have a design draft lifecycle distinct from rich-text/widget page drafts; publishing design does not publish pending page text. Theme switches preserve the map. To migrate a custom schema, transform a pulled draft to the new version, review it, and push it with its revision; incompatible versions never auto-convert silently. Existing widget pages continue using their original renderer.
+The component receives SectionProps<Data>; `acms theme types <slug>` (also run by `acms check`) writes `section-types.d.ts` with one Data interface per section. Field kinds: text, textarea, richtext, image, url, link, select (options required), number, toggle, date, time, list (a repeater of those) and source (live events, posts or booking links). An image field (or its default) may name a file the theme ships, like `assets/hero.jpg`; it resolves to that file's built URL on the website and in the mobile API. Post sources give each item `excerpt` (the post's own, else the first ~160 characters of its text) and `authors` (`{ name, url, avatar }`, public byline fields only). The full guide, including presets, migrations and the starter library (`acms section library` / `acms section add`), is `acms docs sections`. Instances have stable id/type/version/variant/hidden/data fields. A page layout has mode and sections, persisted by page ID in `settings.sectionPages`. Section values and order have a design draft lifecycle distinct from rich-text/widget page drafts; publishing design does not publish pending page text. Theme switches preserve the map. To migrate a custom schema, transform a pulled draft to the new version, review it, and push it with its revision; incompatible versions never auto-convert silently. Existing widget pages continue using their original renderer.
 
 Images in template files should be imported using relative paths so Astro bundles them. Theme CSS can reference `url(assets/name.webp)`; ACMS resolves it through the bundled asset inventory. Brand images and editable section images use the media library. Packaged assets must be local files under assets; declare them in the manifest. Use `theme pack --optimize` to run current img-subir and rewrite references before packing. Original-image backup directories are excluded.
 

package/integration.mjs

@@ -1,3 +1,4 @@
+import { resolveMobile } from './src/lib/mobile/config.mjs';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -32,6 +33,8 @@ const ROUTES = [
   ['/go/[id]', 'go/[id].ts'],
   ['/media/[...key]', 'media/[...key].ts'],
   ['/embed/[pageId]/[blockId]', 'embed/[pageId]/[blockId].ts'],
+  // one published section for mobile apps without a native component for it
+  ['/embed/section/[...path]', 'embed/section/[...path].astro'],
   ['/preview/[type]/[id]', 'preview/[type]/[id].astro'],
   ['/rss.xml', 'rss.xml.ts'],
   ['/sitemap.xml', 'sitemap.xml.ts'],
@@ -40,6 +43,7 @@ const ROUTES = [
   // admin
   ['/admin', 'admin/index.astro'],
   ['/admin/design', 'admin/design.astro'],
+  ['/admin/section-preview', 'admin/section-preview.astro'],
   ['/admin/links', 'admin/links.astro'],
   ['/admin/login', 'admin/login.astro'],
   ['/admin/logout', 'admin/logout.ts'],
@@ -82,6 +86,8 @@ const ROUTES = [
   ['/api/design/keys', 'api/design/keys.ts'],
   ['/api/design/capabilities', 'api/design/capabilities.ts'],
   ['/api/design/media', 'api/design/media.ts'],
+  ['/api/design/ai', 'api/design/ai.ts'],
+  ['/api/design/translate', 'api/design/translate.ts'],
   ['/api/agent', 'api/agent/index.ts'],
   ['/api/agent/docs', 'api/agent/docs.ts'],
   ['/api/mcp', 'api/mcp.ts'],
@@ -251,7 +257,7 @@ function resolveSearch(search) {
 const EVENT_FIELD_TYPES = ['text', 'textarea', 'number', 'url', 'select'];
 function resolveCalendar(calendar, contentBases, locales) {
   const defaults = {
-    enabled: true, base: '/calendar', eventsBase: '/events', bookings: true, bookBase: '/book',
+    enabled: true, base: '/calendar', eventsBase: '/events', bookings: true, bookBase: '/book', bookingApproval: 'auto',
     resourceKinds: ['Room', 'Person', 'Vehicle', 'Equipment'], defaultView: 'month', eventFields: [],
   };
   if (calendar === false) return { ...defaults, enabled: false };
@@ -269,17 +275,31 @@ function resolveCalendar(calendar, contentBases, locales) {
   }
   const enabled = calendar.enabled ?? true;
   if (typeof enabled !== 'boolean') throw new Error('acms: calendar.enabled must be true or false');
+  // bookings: true | false | { approval: 'auto' | 'rules' | 'manual' } — the
+  // object form turns bookings on and sets the starting approval default
+  // (Calendar settings → Bookings can change it later)
+  const bookingsOpt = calendar.bookings ?? true;
+  let bookingApproval = defaults.bookingApproval;
+  if (bookingsOpt && typeof bookingsOpt === 'object' && !Array.isArray(bookingsOpt)) {
+    const extra = Object.keys(bookingsOpt).filter((k) => k !== 'approval');
+    if (extra.length) throw new Error(`acms: unknown calendar.bookings key "${extra[0]}" — the only option is calendar.bookings.approval`);
+    bookingApproval = bookingsOpt.approval ?? defaults.bookingApproval;
+    if (!['auto', 'rules', 'manual'].includes(bookingApproval)) {
+      throw new Error(`acms: calendar.bookings.approval must be "auto", "rules", or "manual" — got "${bookingApproval}"`);
+    }
+  }
   const resolved = {
     enabled,
     base: calendar.base ?? defaults.base,
     eventsBase: calendar.eventsBase ?? defaults.eventsBase,
-    bookings: calendar.bookings ?? true,
+    bookings: typeof bookingsOpt === 'object' && bookingsOpt !== null ? true : bookingsOpt,
+    bookingApproval,
     bookBase: calendar.bookBase ?? defaults.bookBase,
     resourceKinds: calendar.resourceKinds ?? defaults.resourceKinds,
     defaultView: calendar.defaultView ?? defaults.defaultView,
     eventFields: [],
   };
-  if (typeof resolved.bookings !== 'boolean') throw new Error('acms: calendar.bookings must be true or false');
+  if (typeof resolved.bookings !== 'boolean') throw new Error('acms: calendar.bookings must be true, false, or { approval }');
   if (!Array.isArray(resolved.resourceKinds) || !resolved.resourceKinds.length || resolved.resourceKinds.some((k) => typeof k !== 'string' || !k.trim())) {
     throw new Error('acms: calendar.resourceKinds must be a non-empty array of labels, e.g. ["Room", "Person"]');
   }
@@ -379,6 +399,9 @@ export const homes = import.meta.glob('/src/themes/*/templates/home.astro', { ea
 export const postTpls = import.meta.glob('/src/themes/*/templates/post-*.astro', { eager: true });
 export const pageTpls = import.meta.glob('/src/themes/*/templates/page-*.astro', { eager: true });
 export const eventTpls = import.meta.glob('/src/themes/*/templates/event.astro', { eager: true });
+export const headerTpls = import.meta.glob('/src/themes/*/templates/header.astro', { eager: true });
+export const footerTpls = import.meta.glob('/src/themes/*/templates/footer.astro', { eager: true });
+export const migrations = import.meta.glob('/src/themes/*/migrations/*.mjs', { eager: true });
 `;
 
 function acmsVitePlugin(userConfig) {
@@ -418,6 +441,13 @@ function acmsVitePlugin(userConfig) {
  *   Home page content per language is authored in /admin as a normal page
  *   marked "home" with that language selected. Omit for monolingual sites —
  *   nothing changes.
+ * @param {{ios?: {teamId: string, bundleId: string, paths?: string[]}, android?: {package: string, sha256CertFingerprints: string[]}, push?: boolean | {enabled?: boolean, retentionDays?: number}, editor?: {redirectUris: string[], name?: string, accessTokenMinutes?: number, refreshTokenDays?: number}}} [options.mobile]
+ *   Optional iOS Universal Links and Android App Links associations, and push
+ *   notifications for the site's own Expo apps (`push: true`; off by default):
+ *   /api/v1/devices, /api/v1/push/topics and Admin → Mobile app. `editor:
+ *   { redirectUris, name? }` turns on editor apps: staff sign in through the
+ *   browser (/admin/app-auth, OAuth 2.0 + PKCE; only the listed redirect URIs
+ *   receive codes) and edit through the bearer-token /api/v1/admin/* API.
  * @param {{enabled?: boolean}} [options.search]
  *   Public site search: the /search page, the /api/search JSON endpoint, and
  *   the header search modal. On by default — set `enabled: false` to remove
@@ -441,6 +471,7 @@ export default function acms(options = {}) {
   ]);
   const i18n = resolveI18n(options.i18n, contentBases);
   const search = resolveSearch(options.search);
+  const mobile = resolveMobile(options.mobile);
   const calendar = resolveCalendar(options.calendar, contentBases, i18n.locales);
   const legal = { enabled: true, operatorName: '', contactEmail: '', updatedAt: '', ...(options.legal === false ? { enabled: false } : options.legal ?? {}) };
   if (typeof legal.enabled !== 'boolean' || ['operatorName','contactEmail','updatedAt'].some(k => typeof legal[k] !== 'string')) throw new Error('acms: invalid legal configuration');
@@ -453,13 +484,52 @@ export default function acms(options = {}) {
     content,
     i18n,
     search,
+    mobile,
     calendar,
     legal,
   };
   const routes = [...ROUTES,
+    ['/api/v1/site', 'api/v1/site.ts'],
+    ['/api/v1/theme', 'api/v1/theme.ts'],
+    ['/api/v1/pages/home', 'api/v1/pages/home.ts'],
+    ['/api/v1/pages/[...slug]', 'api/v1/pages/[...slug].ts'],
+    ['/api/v1/openapi.json', 'api/v1/openapi.json.ts'],
     ['/api/v1/content', 'api/v1/content/index.ts'],
     ['/api/v1/content/[id]', 'api/v1/content/[id].ts'],
   ];
+  if (mobile.ios) routes.push(['/.well-known/apple-app-site-association', '.well-known/apple-app-site-association.ts']);
+  if (mobile.android) routes.push(['/.well-known/assetlinks.json', '.well-known/assetlinks.json.ts']);
+  if (mobile.push.enabled) {
+    routes.push(
+      ['/api/v1/devices', 'api/v1/devices/index.ts'],
+      ['/api/v1/devices/[token]', 'api/v1/devices/[token].ts'],
+      ['/api/v1/push/topics', 'api/v1/push/topics.ts'],
+      ['/api/push/admin', 'api/push/admin.ts'],
+      ['/admin/mobile', 'admin/mobile.astro'],
+    );
+  }
+  if (mobile.editor.enabled) {
+    // editor apps: browser sign-in (OAuth 2.0 + PKCE) and the bearer-only admin API
+    routes.push(
+      ['/admin/app-auth', 'admin/app-auth.astro'],
+      ['/api/v1/auth/token', 'api/v1/auth/token.ts'],
+      ['/api/v1/auth/revoke', 'api/v1/auth/revoke.ts'],
+      ['/api/v1/admin/me', 'api/v1/admin/me.ts'],
+      ['/api/v1/admin/documents', 'api/v1/admin/documents/index.ts'],
+      ['/api/v1/admin/documents/[kind]/[id]', 'api/v1/admin/documents/[kind]/[id]/index.ts'],
+      ['/api/v1/admin/documents/[kind]/[id]/[action]', 'api/v1/admin/documents/[kind]/[id]/[action].ts'],
+      ['/api/v1/admin/documents/[kind]/[id]/translations/[locale]', 'api/v1/admin/documents/[kind]/[id]/translations/[locale]/index.ts'],
+      ['/api/v1/admin/documents/[kind]/[id]/translations/[locale]/[action]', 'api/v1/admin/documents/[kind]/[id]/translations/[locale]/[action].ts'],
+      ['/api/v1/admin/sections', 'api/v1/admin/sections/index.ts'],
+      ['/api/v1/admin/sections/[pageId]/[sectionId]', 'api/v1/admin/sections/[pageId]/[sectionId]/index.ts'],
+      ['/api/v1/admin/sections/[pageId]/[sectionId]/publish', 'api/v1/admin/sections/[pageId]/[sectionId]/publish.ts'],
+      ['/api/v1/admin/sections/[pageId]/[sectionId]/translations/[locale]', 'api/v1/admin/sections/[pageId]/[sectionId]/translations/[locale]/index.ts'],
+      ['/api/v1/admin/sections/[pageId]/[sectionId]/translations/[locale]/[action]', 'api/v1/admin/sections/[pageId]/[sectionId]/translations/[locale]/[action].ts'],
+      ['/api/v1/admin/media', 'api/v1/admin/media/index.ts'],
+      ['/api/v1/admin/bookings', 'api/v1/admin/bookings/index.ts'],
+      ['/api/v1/admin/bookings/[id]/[action]', 'api/v1/admin/bookings/[id]/[action].ts'],
+    );
+  }
   if (legal.enabled) routes.push(['/privacy', 'legal/privacy.astro'], ['/terms', 'legal/terms.astro']);
   for (const c of Object.values(content.collections)) {
     routes.push([c.base, 'blog/index.astro'], [`${c.base}/[slug]`, 'blog/[slug].astro']);
@@ -490,7 +560,8 @@ export default function acms(options = {}) {
       ['/api/v1/calendars', 'api/v1/calendars.ts'],
       ['/api/calendar/events', 'api/calendar/events/index.ts'],
       ['/api/calendar/calendars', 'api/calendar/calendars.ts'],
-      ['/admin/calendar', 'admin/calendar/index.ts'],
+      ['/admin/calendar', 'admin/calendar/index.astro'],
+      ['/admin/calendar/settings', 'admin/calendar/settings.astro'],
       ['/admin/calendar/events', 'admin/calendar/events/index.astro'],
       ['/admin/calendar/events/[id]', 'admin/calendar/events/[id].astro'],
       ['/admin/calendar/calendars', 'admin/calendar/calendars.astro'],
@@ -529,7 +600,7 @@ export default function acms(options = {}) {
         if (config.root) {
           const discoveryDir = fileURLToPath(new URL('.astro/', config.root));
           mkdirSync(discoveryDir, {recursive:true});
-          writeFileSync(join(discoveryDir,'acms-project.json'), JSON.stringify({ themeApiVersion:1, collections:userConfig.content.collections, calendar:userConfig.calendar }));
+          writeFileSync(join(discoveryDir,'acms-project.json'), JSON.stringify({ themeApiVersion:1, collections:userConfig.content.collections, calendar:userConfig.calendar, mobile:userConfig.mobile ?? {} }));
         }
         updateConfig({ vite: { plugins: [acmsVitePlugin(userConfig)] } });
 

package/mobile-template/client/AGENTS.md

@@ -0,0 +1,97 @@
+# Agent rules for this app
+
+Full guide: run `npx acms docs mobile` from the **site** folder (the folder
+that contains this app; all `acms` commands run there, not in this folder). Finish
+every change with `npx acms mobile doctor` (no failures).
+
+This is the **client app** for the ACMS site at `__ACMS_SITE_URL__`: an Expo
+(React Native) app for iOS, Android and web that shows the site's content. The
+site owner edits everything in the site admin; the app only reads the public
+API. It lives beside the website but is a separate project (its own
+`package.json` and `node_modules`), not part of the site build.
+
+## Rules
+
+1. **Use the ACMS hooks, never raw fetch.** Import from `@acms-subir/native`
+   (`useSite`, `useTheme`, `useLocale`, `usePage`, `usePosts`, `usePost`,
+   `useEvents`, `useEvent`, `useResources`, `useAvailability`, `useBooking`,
+   `<Sections>`, `<RichText>`, `<EventDate>`). For anything else use the typed
+   client from `useAcms()` (`@acms-subir/client`) inside a TanStack Query hook.
+2. **Never hardcode content.** Names, times, text, events, prices, people and
+   images come from the site. If the app needs something the owner should be
+   able to change, it must be a section field or content in the admin, not a
+   string in this code. Only UI chrome ("Try again", "Book") belongs here.
+3. **Public API only.** No admin routes, no database, no agent or integration
+   keys, no admin password. There are no secrets in a mobile app:
+   `EXPO_PUBLIC_*` values are bundled and readable by anyone.
+4. **Style from the site's theme.** Colors, fonts and radius come from
+   `useTheme()` (`t.colors`, `t.styles`). Support light and dark mode. No
+   pill-shaped chips or badges (use 10–12px radius rectangles or plain text),
+   no colored left-edge accent stripes, no gradient-squircle logos.
+5. **Phones and tablets.** Use `useLayout()` / `useWindowDimensions` for
+   columns and gutters; never fixed widths. Content should use the width on a
+   tablet, not a stretched phone column.
+6. **Bookings are sensitive.** `useBooking()` handles idempotency. Never put a
+   booking's manage token, email or idempotency key in a URL, log or analytics
+   event; store the manage token with `expo-secure-store` if you keep it.
+7. **Links:** section links may be root-relative. Open them with
+   `useOpenLink()` (site pages go through `onNavigate`), or resolve with
+   `resolveUrl(href, baseUrl)`. To open your own screens for site pages, pass
+   `onNavigate={(path, url) => …}` to `<AcmsProvider>` in `app/_layout.tsx`
+   (e.g. `router.push` for `/events/<slug>` when the events recipe is in).
+8. **Sections mirror the website.** A native section uses the same fields and
+   variants as the site's `src/themes/<theme>/sections/*.astro` component and
+   renders empty fields the same way.
+
+## Where things are
+
+- `app/_layout.tsx` wires `<AcmsProvider>` (site URL from `EXPO_PUBLIC_ACMS_URL`),
+  theme colors and the language switch.
+- `app/index.tsx` renders the homepage sections with pull to refresh.
+- `sections/index.ts` is this app's section registry, passed to
+  `<Sections registry={sections}>`. Keys are a section type or `type:variant`.
+- Each section renders with the first match of: `sections/index.ts` → the
+  packaged library components (`@acms-subir/native/sections`: hero-banner,
+  service-times, upcoming-events, feature-grid, team, pricing, gallery,
+  questions, cta-band, contact, latest-posts) → the website's rendering in a
+  web view (react-native-webview; an iframe on web) → a generic view.
+- To change a library section, get an editable copy (from the site folder):
+  `npx acms section add team --theme <slug> --native` → `sections/Team.tsx`.
+- New coded sections: `npx acms section new <type> --theme <slug>` writes the
+  web component and a typed native stub here (`sections/<Type>.tsx`, types in
+  `sections/types.ts`). Finish the stub so it matches the web version.
+- `npx acms check` lists sections that only show as a web view; give the ones
+  people use most a native component. Build yours from the exported pieces
+  (`Grid`, `FocalImage`, `SectionHeader`, `ActionButton`, `TextLink`,
+  `useSectionMetrics`) so they stay responsive and themed.
+- Images: pass `<key>Focus` to `FocalImage` so crops keep the owner's focal point.
+
+## Recipes
+
+Add ready-made screens from the site folder instead of writing them from scratch:
+
+```sh
+npx acms mobile recipe list
+npx acms mobile recipe add events    # events list, detail, add to calendar
+npx acms mobile recipe add news      # posts list and article
+npx acms mobile recipe add booking   # resources → slots → form → confirmation
+npx acms mobile recipe add push      # notifications: turn on, topics, taps (site needs push on)
+```
+
+Each recipe prints the extra Expo packages to install (`npx expo install ...`).
+
+## Before you finish
+
+- `npm run typecheck` passes.
+- Check iOS and Android (and `npm run web`), in both light and dark mode, on a
+  phone-sized and a tablet-sized screen. Compare the home screen with the
+  website: same sections, same order, same words.
+- `npx expo export --platform web` bundles without errors.
+- `npx acms mobile dev` (from the site folder) runs the site and this app so a
+  real phone on the same network or Tailscale can reach it.
+- `npx acms mobile doctor` (from the site folder) passes: packages match the
+  site, the site address works, no secrets, sections covered, recipe
+  packages installed. Read its warnings too.
+- If the task needs content the site doesn't have yet (a page, a calendar),
+  read it by slug anyway, show an empty state, and tell the owner what to
+  create in the admin. Don't hardcode it.

package/mobile-template/client/README.md

@@ -0,0 +1,65 @@
+# __ACMS_APP_NAME__
+
+A blank Expo app connected to your ACMS site (`__ACMS_SITE_URL__`). It already
+shows your homepage sections, follows your site's Design colors in light and
+dark mode, and switches language when your site has more than one. Everything
+else is yours to build.
+
+## Run it
+
+From your **site** folder (starts the site too, and points the app at an
+address your phone can reach):
+
+```sh
+cd __ACMS_APP_DIR__ && npm install && cd ..
+npx acms mobile dev
+```
+
+Scan the QR code with Expo Go, or press `i` / `a` / `w` for the iOS simulator,
+Android emulator or a browser. Or run the app on its own:
+
+```sh
+npm start
+```
+
+The site address comes from `EXPO_PUBLIC_ACMS_URL` in `.env` (your production
+site) and `.env.local` (written by `acms mobile dev`, not committed).
+
+## Add screens
+
+```sh
+npx acms mobile recipe add events   # also: news, booking, push
+```
+
+Build your own with the hooks from `@acms-subir/native`. `AGENTS.md` has the
+rules coding agents follow here; `npx acms docs mobile` (from the site folder)
+is the full guide with a cookbook (tabs, events, native sections, booking).
+
+## Check it
+
+From the site folder:
+
+```sh
+npx acms mobile doctor            # --offline skips network checks, --json for tools
+```
+
+It checks the ACMS packages match your site's version, the site address works
+(and isn't localhost for a phone), app ids and deep links, sections the app
+can't show natively, secrets in the code, and recipe packages. It exits 1 when
+something fails.
+
+## Ship it
+
+Builds and store submission use [EAS](https://docs.expo.dev/build/introduction/):
+
+```sh
+npx eas-cli build --profile preview --platform all   # installable test builds
+npx eas-cli build --profile production --platform all
+npx eas-cli submit --platform ios
+```
+
+Before your first store build, run `npx acms mobile doctor` and check
+`app.json`: app name, `ios.bundleIdentifier`
+(`__ACMS_BUNDLE_ID__`) and `android.package` can't change after release. To open
+site links in the app, set `acms({ mobile: { ios, android } })` in the site's
+`astro.config.mjs` (see the site's mobile API docs).

package/mobile-template/client/app/_layout.tsx

@@ -0,0 +1,56 @@
+import { useMemo } from 'react';
+import { Text, View } from 'react-native';
+import { DarkTheme, DefaultTheme, Stack, ThemeProvider } from 'expo-router';
+import { StatusBar } from 'expo-status-bar';
+import { AcmsProvider, useSite, useTheme } from '@acms-subir/native';
+import { LanguageSwitch } from '../components/LanguageSwitch';
+
+// Set in .env (production site) or .env.local (written by `npx acms mobile dev`).
+const baseUrl = process.env.EXPO_PUBLIC_ACMS_URL;
+
+export default function RootLayout() {
+  if (!baseUrl) return <MissingUrl />;
+  return (
+    <AcmsProvider baseUrl={baseUrl}>
+      <ThemedStack />
+    </AcmsProvider>
+  );
+}
+
+// Navigation chrome follows the site's Design tokens in light and dark mode.
+function ThemedStack() {
+  const t = useTheme();
+  const { data: site } = useSite();
+  const navTheme = useMemo(() => {
+    const base = t.scheme === 'dark' ? DarkTheme : DefaultTheme;
+    return { ...base, colors: { ...base.colors, primary: t.colors.accent, background: t.colors.bg, card: t.colors.bg, text: t.colors.ink, border: t.colors.line, notification: t.colors.accent } };
+  }, [t]);
+  return (
+    <ThemeProvider value={navTheme}>
+      <StatusBar style={t.scheme === 'dark' ? 'light' : 'dark'} />
+      <Stack
+        screenOptions={{
+          headerStyle: { backgroundColor: t.colors.bg },
+          headerTintColor: t.colors.ink,
+          headerTitleStyle: { fontFamily: t.styles.fonts.heading },
+          headerShadowVisible: false,
+          contentStyle: { backgroundColor: t.colors.bg },
+          headerRight: () => <LanguageSwitch />,
+        }}
+      >
+        <Stack.Screen name="index" options={{ title: site?.name ?? '' }} />
+      </Stack>
+    </ThemeProvider>
+  );
+}
+
+function MissingUrl() {
+  return (
+    <View style={{ flex: 1, justifyContent: 'center', padding: 24, gap: 8 }}>
+      <Text style={{ fontSize: 18, fontWeight: '600' }}>Connect your site</Text>
+      <Text style={{ fontSize: 15, lineHeight: 22 }}>
+        Set EXPO_PUBLIC_ACMS_URL in .env (for example https://example.com), or run `npx acms mobile dev` from your site folder, then restart Expo.
+      </Text>
+    </View>
+  );
+}