caracms 0.1.0 → 0.2.0

package/skills/caracms-tina/SKILL.md

@@ -0,0 +1,427 @@
+---
+name: caracms-tina
+description: Port a site built on self-hosted Tina (a Caracode Tina template site, with `tina/`, `server.mjs` and pages as JSON read through `src/lib/sections.ts`) onto caracms — strip Tina, run the reference conversion script (`tina-to-caracms.mjs`, re-runnable on newer content), rewrite each block onto `Block`, `Text`, `RichText` and `Media` so text is typed on the page, carry page-wide rules and cards into the page component, deploy to a branch environment that can't publish to the live site, and prove visitors' pages look the same. Use when porting a Tina site, re-running its conversion, or adapting the script.
+---
+
+# Porting a Tina site onto caracms
+
+**The bar: visitors' pages look the same.** The port changes what editors see, not what
+visitors see. Any redesign is separate work, after the switch.
+
+**The port is real, and the live site keeps moving.** The client keeps editing in Tina
+while the port's branch is open. So content is never converted by hand: the site's own
+copy of the conversion script writes `content/`, and at the switch Tina is frozen, the
+script is re-run on the latest `main`, and the branch is merged. Anything you'd fix in a
+converted file, fix in the script (or the site's adapt table) and re-run.
+
+Read with this skill:
+
+- `caracms-blocks`: blocks, fields, collections, the page component, forms.
+- `caracms-adopt`: `init` in detail, the look-same script (section 9), motion under the
+  preview (section 8). This skill is the Tina-specific order; adopt's page-by-page
+  method doesn't apply, since the script converts every page at once.
+- `caracms-content`: the content files the script writes.
+- Beside this file: **`tina-to-caracms.mjs`**, the reference script (its header is its
+  manual), and **`field-kinds.md`**, the mapping table: how each Tina field kind becomes a
+  caracms field and value.
+
+Commands run from the site's root: `npx caracms …` (or `pnpm caracms …`).
+
+**Swapping in a new packed tarball** at the same `file:` path (`vendor/caracms.tgz`):
+`pnpm install`, even with `--force`, keeps the old copy, since the lockfile holds the old
+file's integrity. Remove and add it again:
+`pnpm remove caracms && pnpm add caracms@file:vendor/caracms.tgz`.
+
+## 0. Before anything moves: the block table
+
+A template site has its own block templates (`_template` names, camelCase). Propose the
+**old-to-new block table** to Rich and get it approved before content moves: each Tina
+template, the caracms block key it becomes, and whether it maps one to one, splits or
+is flattened. Keys are kebab case (`textMedia` → `text-media`, the script's default);
+rename where the editor's label reads better (`features` → `steps`, `fullMedia` →
+`wide-media`). The approved renames go into the script's adapt table (`blockRenames`).
+
+Also list, for the same approval: the fields that will be **edited in the sidebar only**
+(display text fitted to its box, split-letter headings, a word drawn as artwork), and
+anything the template does that caracms has no place for yet.
+
+## 1. The order
+
+Work on a branch (`caracms-port`, say) in a worktree of the site. Commit after each step.
+
+1. **Bump Astro on its own commit** to the version caracms needs (its peer dependency:
+   `npm view caracms peerDependencies`, or the tarball's `package.json` while the package
+   is unpublished or the port runs on a packed tarball). Build and check the site still looks the same
+   before anything else changes. If the site pins its own `vite`, bump it with Astro:
+   left behind, it leaves a second Vite in the tree and `astro check` fails in the Astro
+   config. **Bump `.nvmrc` and `engines.node` in `package.json` with Astro** (Astro 7.4
+   needs Node 22.23.4 or later, and so does caracms): Railway builds on the older Node
+   and fails with exit 1 and no error text in the build log.
+2. **Strip Tina** (section 3): `tina/`, `server.mjs`, `server/`, Tina's routes and admin,
+   **including the untracked `tina/__generated__/` and `public/admin/`** (they're in
+   `.gitignore`; delete them from disk too, or `init` and the build trip on them).
+3. **Delete `content/`** (git keeps it). `init` refuses a `content/` that isn't caracms's.
+4. **Switch the adapter to standalone:** `@astrojs/node` with `mode: 'standalone'`.
+   `caracms start` serves `dist/server/entry.mjs` and refuses any other mode.
+5. **`npx caracms init`**, read the dry run, then **`npx caracms init --write`** and install
+   again (caracms-adopt → section 1). It links the four skills, writes the config, the
+   CLAUDE.md block, the health route and, on a site without one, `.railway/railway.ts`.
+   **A template site already has a `.railway/railway.ts` that describes production: leave
+   it alone and never apply it** (applying it can switch production's CDN off). `init`
+   leaves an existing one untouched, which is the expected outcome. Set the branch
+   environment up with the Railway CLI or MCP, scoped to that environment (section 9).
+6. **Copy the script and run it** (section 2) against a **built** checkout of `main`.
+   First run with `--scaffold-config` for a starting `caracms.config.ts`. It names a
+   component per block before any is written, so nothing builds until they exist: point
+   every block's `component` at one stub first, then swap each in as it's rewritten.
+7. **Rewrite the blocks** onto caracms's components (section 4), the page component
+   (section 5), the routes (section 6), forms (section 8).
+8. **`npx caracms validate`**: no errors and no warnings, the missing-`w`/`h` warning
+   included (section 7 fills sizes in).
+9. **Look-same** every public page against `main` at the commit the script last ran on
+   (section 11), then the branch environment (section 9).
+
+## 2. The conversion script
+
+Copy `node_modules/caracms/skills/caracms-tina/tina-to-caracms.mjs` into the site's own
+`scripts/`. The site's copy is the one that runs; it's committed with the site.
+
+**Adapt only the table under `ADAPT HERE`** (the script's header says what each entry is):
+the approved `blockRenames`, `fieldDefaults` (values Tina's files leave out but the
+template's mapper code read as set: a toggle that defaulted on, a per-block background
+default that isn't the first option), `addressFields`, `headingFields`, `docTitleAlt`,
+the file-link pattern, and Tina's home file. **`addressFields` matters:** Tina's schema has
+no marker for a link field (a custom component serialises to `ui: {}`), so only strings
+named `href` are known to be addresses; list every other one. Everything below the table is generic and
+driven by Tina's generated schema; never add per-block code. If a block needs something
+the table can't say, that's a gap in the script: change the generic part, and say so in
+your report so it reaches the package's copy.
+
+Run it from the site's root:
+
+```bash
+node scripts/tina-to-caracms.mjs --from ../share-web-main --scaffold-config
+```
+
+- `--from` is a checkout of the Tina site's `main` that has been **built** (`pnpm build`,
+  or the template's `build:local`), so `tina/__generated__/_schema.json` exists. Only that
+  schema is needed: the site's own build may fail there for lack of env, and that's fine.
+  If `build:local` stops on a busy port 9000 (Tina's datalayer), pass
+  `--datalayer-port <another>` to the Tina site's own `build:local` / `tinacms build`, not
+  to this script (it rejects unknown arguments).
+- Run it after `caracms init --write` and an install: it borrows the installed package's
+  image sniffer and S3 signer.
+- `--scaffold-config` writes a starting `caracms.config.ts` from Tina's schema, with
+  Tina's labels and help. **Once.** After that the config and the block components are
+  the site's own, hand-maintained, and a normal run never touches them (section 4 says
+  which options only you can add).
+- `--recipients <address>` replaces every form's recipients in Site Settings with one
+  address. **Always pass it for a branch environment**: the converted Site Settings name
+  the client, and a test submission would email them. The run at the switch leaves it out.
+
+**What it owns: `content/`, nothing else.** Each run deletes `content/` and writes it again,
+laid out the way the editor saves it, so the same Tina content gives byte-identical files
+and `validate` finds nothing to reformat. **A re-run deletes `content/` whole**, so anything
+published from the branch environment's editor is replaced by it. That is by design: Tina
+stays the source until the switch. Beside it, it only adds to
+`scripts/tina-media-sizes.json` (images' `w`/`h`, commit it) and copies file-link objects
+in the bucket to caracms file keys (skipped when the key exists; it never deletes).
+Without `S3_*` set, it still writes `content/` and lists the copies still to make (a
+rulebook PDF, say): run it again with the environment's bucket credentials to make them.
+
+To pick up newer Tina content: pull `main` in the `--from` checkout, build it, re-run,
+commit `content/` and the size cache, and look-same again against that commit.
+
+What the script converts (the full table is `field-kinds.md`): `_template` → `type`,
+the section list → `blocks`, the home file → `index.json`, Tina's Markdown rich text →
+caracms's (Tina's escapes such as `A\&M` and `mailto\:` undone), an image and its `…Alt`
+sibling → one media value, a Mux clip → a video value, `linkLabel` + `href` → one
+`link()`, references → document paths, Site Settings (`formNotifications` →
+`formRecipients`, `adminBranding` → `brand`, `adminAccess` → `editors`, `defaultSeo` →
+`seo`), file links → caracms file addresses, and Tina's `hidden` → `"hidden": true`
+(section 6).
+
+## 3. Tina's pieces and what replaces each
+
+| The template's | Goes | Replaced by |
+|---|---|---|
+| `tina/`, `tina/__generated__/`, Tina's dependencies | yes | `caracms.config.ts` |
+| `public/admin/`, `public/admin-previews/` | yes | `/admin` (caracms's editor) |
+| `server.mjs`, `server/` (Express: forms, downloads, the admin, previews) | yes | `caracms start`; forms → `/_caracms/form` (section 8); downloads → caracms file addresses `/files/<12 hex>/<name>` |
+| `src/pages/[...slug].astro` and other collection routes reading Tina | yes | caracms routes (section 6) |
+| `src/lib/sections.ts` (the mappers: Tina document → component props) | yes, except page-wide logic | blocks draw from their own data; page-wide rules → the page component (section 5) |
+| `Sections.astro` / `PageView` | yes | the page component and `<Blocks>` |
+| `data-tina-field` on every element | yes | caracms's markers, added by `Block`, `Text`, `RichText`, `Media` in a preview only |
+| `islandPreview.ts`, Tina's preview islands | yes | caracms's preview; site scripts listen for `caracms:rendered` (section 4) |
+| `@astrojs/sitemap` | yes | caracms's `/sitemap.xml` (needs `SITE_URL`) |
+| `.template-sync`, engine-sync scripts, the deploy-gate workflow, `@caracode/pins` | yes | nothing (`.carapin/` can stay as history) |
+| The header, footer, motion, fonts, analytics tags, design-system routes, the site's own `src/lib/` logic | **stays** | |
+
+**Tests:** delete tests of Tina's machinery, of the mappers, of deleted files, and of
+`data-tina-field`. A test that guards site behaviour that still exists is rewritten
+against caracms's content format; the template's helper that reads committed content is
+usually the one to rewrite first. **Docs:** the engine and Tina docs go (Tina behaviour,
+publishing, admin login, the media pipeline, downloads). The site's own half of
+`docs/decisions.md` stays, rewritten where it describes Tina. CLAUDE.md loses the
+engine/site split; `init` added its caracms block.
+
+## 4. Rewriting a block onto caracms's components
+
+**The default: every block draws through caracms's components**, keeping the template's
+markup and classes exactly. That's what makes its text typed on the page in `/admin`.
+(Keeping the template's components behind a reverse adapter, feeding them props from
+caracms's data, is faster to look-same but leaves every field sidebar-only. Use it only
+as a stepping stone, a block at a time.)
+
+```astro
+---
+import Block from 'caracms/components/Block.astro';
+import Media from 'caracms/components/Media.astro';
+import RichText from 'caracms/components/RichText.astro';
+import Text from 'caracms/components/Text.astro';
+import type { BlockProps } from 'caracms/document';
+import type { TextMediaData } from './text-media.ts';
+
+type Props = BlockProps<TextMediaData>;
+const { block, cms } = Astro.props;
+---
+
+<Block cms={cms} class={`section bg-${block.background}`} id={block.anchor || undefined}>
+	<Text cms={cms} field="heading" value={block.heading} class="heading text-balance" lineClass="block text-balance" />
+	<RichText cms={cms} field="body" value={block.body} class="prose" />
+	<Media cms={cms} field="media" value={block.media} sizes="(min-width: 1024px) 50vw, 100vw" class="media" />
+</Block>
+```
+
+- **`Block`** is the block's root (`as="section"` by default; `as` and every attribute
+  pass through). Drop the template's `data-tina-field`.
+- **`Text`** for a plain text field: `as` sets the tag; a field declared
+  `text({ heading: true })` is the page's `h1` when it's the first heading, else `h2`.
+- **Lines** (`text({ lines: true })` in the config, `lineClass` on `Text`): for a heading
+  the template drew one element per typed line (its `typography.ts`/`Heading.astro`).
+  Two lines or more draw a `<span class={lineClass}>` each, blank lines draw nothing,
+  and a single line is drawn bare, as the template's `ui/Heading.astro` does. Typed on
+  the page, Shift+Enter still stores `\n`.
+- **`RichText`** for rich text: semantic HTML with no classes, inside one wrapper (`as`,
+  default `div`). Style it from the wrapper's class (`.prose p`, `.prose strong`).
+- **A rich-text heading** (`richText({ heading: true })`): for a heading the template
+  drew from rich text with bold as a highlight colour and each paragraph a line
+  (`ui/RichLine.astro`). It draws inline runs joined by `<br>` inside its own heading
+  tag (`h1` when it's the page's first heading), never `<p>`. It takes bold and line
+  breaks only, typed on the page. The template's highlight class becomes site CSS on
+  `strong` inside it: `.statement strong { color: var(--highlight); }`.
+- **`Media`** for an image or a Mux clip: one `<img>` with a srcset (or the clip's
+  video). Fluid: `sizes` (and `ratio` to crop); fixed: `width`/`height`. For flat
+  artwork the template served as PNG (WebP smears it), declare the field
+  `media({ format: 'png' })`: every width is then `@png`.
+- **YouTube**: a `link({ addressOnly: true })`; the block parses the id from the address.
+- **Sidebar-only fields** (fitted display text, split letters, a word drawn as artwork):
+  draw the value yourself (`{block.word}`) instead of through `Text`, so it isn't typed
+  on the page. Text the template splits into letters for motion can be drawn unsplit in
+  the preview (`cms.preview`), where motion is off, and then typed on the page.
+- **Help:** Tina's long block descriptions go into the block's `help` (one or two
+  sentences, shown at the top of the block in the sidebar). Field `help` stays short.
+- **Site scripts and the preview:** the preview re-renders a block in place after each
+  edit (a morph, no reload). A script that measures or fits text (`fitText.ts`) re-runs
+  on it: `document.addEventListener('caracms:rendered', run)` (fired on the frame's
+  `document` after each morph, never on public pages). Motion follows caracms-adopt →
+  section 8.
+
+The options only you can add (`--scaffold-config` doesn't know them): `heading: true` on
+the block's heading field, `lines: true`, `richText({ heading: true })`,
+`media({ format: 'png' })`, `media({ play: 'loop' })` for a hero's loop, `allowNoLink: true`
+on buttons that may be a label alone ("Coming soon": `validate` warns on one until it's
+set), select defaults from mapper code, and trimmed `help`.
+
+## 5. The page component: page-wide rules and cards
+
+The template's page-wide logic (`pageRules.ts`, `pageParts()`) moves into the page
+component (`page:` in the config). It gets `document`, `collection`, `path` (the page's
+path in its collection, `null` for none), `preview`, `data`, `settings` (Site
+Settings), `listPage` and `read`.
+
+- **A block sees only its own data.** Page-wide rules the Tina mappers applied across
+  blocks (dropping an anchor already used higher up the page, say) belong here, through
+  `<Blocks>`'s context or its `wrap` rule. Check whether today's content needs each one
+  before carrying it over.
+- **Titles.** Tina template sites show Site Settings' title on every page without its own
+  `seo.title`, not `<page> · <brand>`: set `titleFallback: 'site'` in the config
+  (caracms-adopt → Keep the old title format). Check the `<title>` lines in look-same's
+  HTML diff.
+- **Time zone.** A Tina template site keeps its zone in the `SITE_TIMEZONE` variable;
+  caracms reads `timeZone` in the config (default UTC) for the editor's and the inbox's
+  times. Copy production's value into the config.
+- **The h1 and eager loading** are caracms's own: the first block with a heading holds
+  the `h1`, and the first two blocks' images load eagerly (`cms.first`, `cms.eager`). Drop
+  the template's versions.
+- **Cards** (a run of neighbouring blocks drawn inside a band, each card holding several
+  blocks, the anchor `id` on the card): give `<Blocks>` a `wrap` rule. It gets the blocks
+  that render (`{ index, type, data }`, `data` as the block gets it) and returns runs:
+  `{ from, to, component, props, runs }`, document indices inclusive, with `runs` nested
+  inside (the cards inside a band). Each block inside keeps its own index, context and
+  preview markers, so it's selected, typed into and morphed as anywhere else.
+
+```astro
+---
+import Blocks from 'caracms/components/Blocks.astro';
+import type { BlockRun, PageProps, WrapBlocks } from 'caracms/document';
+import CardBand from './CardBand.astro';
+import Card from '../components/ui/Card.astro';
+
+type Props = PageProps;
+const { document, collection, preview = false, listPage } = Astro.props;
+
+/** The template's pageParts(), on the blocks' `card` field: "start" opens a card, "continue" joins the one above. */
+const cards: WrapBlocks = (blocks) => {
+	const bands: { from: number; to: number; cards: BlockRun[] }[] = [];
+	for (const b of blocks) {
+		const spot = b.data.card as string | undefined;
+		if (!spot || spot === 'none') continue;
+		let band = bands.at(-1);
+		// A band is a run of neighbouring carded blocks: a gap (an uncarded block) starts a new one.
+		if (!band || band.to !== b.index - 1) bands.push((band = { from: b.index, to: b.index, cards: [] }));
+		const card = band.cards.at(-1);
+		if (spot === 'start' || !card) band.cards.push({ from: b.index, to: b.index, component: Card, props: { id: (b.data.anchor as string) || undefined } });
+		else band.cards[band.cards.length - 1] = { ...card, to: b.index };
+		band.to = b.index;
+	}
+	return bands.map((band) => ({ from: band.from, to: band.to, component: CardBand, runs: band.cards }));
+};
+---
+
+<Blocks document={document} collection={collection} preview={preview} listPage={listPage} wrap={cards} />
+```
+
+A wrapper component renders `<slot />` where the blocks go. Rules that break the runs'
+order (overlapping, out of order, a card outside its band) stop the render with a
+sentence: that's a bug in the rule. The block's anchor `id` goes on the card, not the
+block, when the template put it there: section links jump to those ids.
+
+## 6. Routes, hidden pages and the 404
+
+`init` writes the pages' catch-all (`src/pages/[...path].astro`) once Tina's
+`[...slug].astro` is gone (it refuses while another route catches the top of the site).
+Write one route per other collection with an address (`src/pages/games/[slug].astro`) the
+same way: `listDocuments` + `readDocument` + `RenderDocument`. Every `getStaticPaths`
+leaves out **`e.warning`** (a file that can't be opened) and **`e.hidden`** (a hidden page,
+or one under it):
+
+```ts
+const entries = (await listDocuments(site, 'pages')).filter((e) => !e.warning && !e.hidden);
+```
+
+**Hidden pages:** Tina's `hidden` becomes `"hidden": true` at the top of the document,
+after its title. A hidden page isn't served (visitors get the site's own `404.astro`),
+isn't in the sitemap, isn't offered by the link picker, and isn't in a block's
+`cms.read.documents(…)`; pages nested under it are hidden with it. It stays editable,
+previewable and publishable in `/admin`, marked "Hidden" in the pages list, with a
+"Hidden from the site" switch in its page settings. The home page can't be hidden (the
+script warns and leaves it shown). A link to a hidden page is a warning, not an error,
+in the editor and in `validate`, naming the page.
+
+## 7. Images
+
+- **Keep the bucket keys.** The template's images are imgproxy URLs over the media bucket
+  (`…/unsafe/plain/s3://<bucket>/uploads/…`); the script keeps each `uploads/…` key, so no
+  image is copied and the bucket only grows.
+- **`w`/`h` are found once** and cached in `scripts/tina-media-sizes.json` (commit it). The
+  first run needs the images reachable (their Tina URLs) or the bucket (`S3_*`); after
+  that the cache answers. `validate` warns on any image still missing its size.
+- **imgproxy:** caracms signs every URL (`CARACMS_MEDIA_URL`, `IMGPROXY_KEY`,
+  `IMGPROXY_SALT`, `S3_BUCKET`). The template's production imgproxy is unsigned and its
+  URLs are cached by the CDN, so **never give it a key while Tina runs**: stand up a new,
+  signed imgproxy beside it, reading the same bucket. Without the media variables the
+  preview draws no images, and a build stops with a sentence naming them.
+
+## 8. Forms
+
+Both of a template's usual forms fit caracms's own: define them in the site's forms
+(caracms-blocks → forms), and their submissions go to the inbox in `/admin`, with a
+notification to Site Settings' `formRecipients`. A form drawn with `<Form>` is styled from
+the site's CSS to the template's markup; its hooks (caracms-blocks → Forms: `submitClass`,
+`thanks`, `errors`, `actions`, `labelPlaceholders`, attributes on the form, a textarea's
+`rows`) carry the template's button classes, its wording and its layout, so no wrapper or
+copied CSS is needed for them.
+
+A form that keeps its own markup (a footer's newsletter signup) posts to caracms's
+endpoint by its **wire contract**:
+
+- `POST /_caracms/form`, urlencoded (or `multipart/form-data` when the form has a files
+  field; JSON is accepted too).
+- `form`: the form's id. `return`: the page's path, where a no-script post comes back to.
+- Each field by its name. `fax`: the honeypot, an empty text input hidden from people
+  (`tabindex="-1"`, off-screen); filled in, the post is dropped and answered as sent.
+- `cf-turnstile-response`: Turnstile's token, added by Cloudflare's widget when the site
+  has `TURNSTILE_SITE_KEY` (at build) and `TURNSTILE_SECRET_KEY` (at run time). Without
+  the secret the endpoint accepts and logs it.
+- Answers: with `Accept: application/json`, `200 {"ok":true}` or the status with
+  `{"error":"…"}` (400 a field, 403 the bot check, 429 too many, 502 storing failed);
+  without, a `303` to `<return>?sent=1`, or the error as plain text.
+
+Not `/api/forms` with `source`/`redirectTo` (the template's): nothing stays a site
+endpoint. The template's existing submissions stay in its own bucket and need no
+conversion: caracms's inbox reads the template's records as they are (`<id>.json` with
+`v: 1`, files at `<id>/<n>-<name>`).
+
+## 9. The branch environment
+
+The port is deployed from its branch to its own environment, **never production**:
+
+- A new environment in the site's Railway project (`caracms`), with its own `web`, Redis, a
+  signed imgproxy and its own submissions bucket. It reads the live media bucket (caracms
+  only ever adds to a bucket). Its variables copy production's where they carry over
+  (`RESEND_API_KEY`, `FORMS_FROM`, the site's `MUX_TOKEN_*`, `CARACMS_ALLOW` from the
+  template's admin allow list), and it deploys from the port branch.
+- **`CARACMS_MAIN_BRANCH` and `CARACMS_DRAFTS_BRANCH`** name caracms's two branches
+  (default `main` and `drafts`). Set them to the port branch and its own drafts branch
+  (`caracms-port`, `caracms-drafts`) **before anyone signs in**: a Publish there then
+  commits to the port branch and redeploys the environment, and the live site's `main`
+  never moves. With the defaults, the first Publish would land caracms's content on the
+  live site's `main`.
+- A GitHub App with Contents read/write on the site's repo, its variables on the
+  environment (as for any caracms site).
+- Convert with `--recipients <agency address>`, so test submissions never reach the client.
+- **Never `railway config apply` against production**: production's variables are set
+  with `railway variables --set` (a template's Railway file can switch its CDN off).
+
+**The switch** (its own task, later): Tina is frozen, the script is re-run on the latest
+`main` without `--recipients`, the branch is merged, production's variables move to
+caracms's (the branch variables unset), and Tina's imgproxy and variables retire.
+
+## 10. Before calling it done
+
+- `npx caracms validate`: no errors, no warnings.
+- `astro check` and `astro build` pass; the site's remaining tests pass.
+- In `/admin`: every heading, intro, body, caption and button label the template marked
+  with `data-tina-field` can be typed on the page, except the sidebar-only fields you
+  listed; rich headings keep bold as the highlight after an edit; blocks inside cards
+  select and morph; a hidden page 404s publicly and edits in `/admin`.
+
+## 11. Look-same
+
+Run caracms-adopt's look-same script (section 9) on every public page, the 404 included,
+at 1440 and 390, against `main` at the commit the script last ran on (never production
+as it is now: the content keeps moving). Build that baseline with **production's** media
+base URL: a local build takes it from `.dev.env`, which may point at the template's
+imgproxy, and then images render unresized and nothing compares. Pass the template's
+attributes and random ids:
+
+```bash
+node .claude/skills/caracms-adopt/look-same.mjs --playwright /tmp/look-same --old <main's build> --new <the port's build> --pages <list> --out <dir> --ignore-attr data-tina-field,data-tina-island --mask-ids auto
+```
+
+If an element varies from run to run on the old site itself (a wordmark fitted to its box
+while the display font loads), add `--css '<rules>'` to hide it or pin its size on both
+sides (caracms-adopt → section 9).
+
+**A 1px crop difference on a responsive image** is a known cause of a small pixel share.
+caracms rounds each srcset width's crop height from the ratio, while an Astro `getImage()`
+site scaled every width from the top width's rounded height (1280 × 875 where caracms
+draws 1280 × 876 at 962:658). Match it in the site, not in caracms: the Share port reads
+the image's ratio in `ladderRatio()` (`src/lib/media.ts`) and keeps the design ratio in
+the frame's CSS.
+
+Passing means a pixel share of 0.00% and no height change at both widths, and the same
+status on both sides (a hidden page answers 404 on both). Review the HTML diff: every
+difference should be one the rewrite explains (caracms's wrappers, Tina's attributes
+gone).

package/skills/caracms-tina/field-kinds.md

@@ -0,0 +1,88 @@
+# Tina field kinds → caracms
+
+How `tina-to-caracms.mjs` maps each kind of Tina field. The script reads Tina's own generated schema (`tina/__generated__/_schema.json`) and applies this table to every field it finds, so nothing is written per block. The same table drives the content it writes and the starting config `--scaffold-config` writes.
+
+"Schema path" below is how the script's adapt table names a field: `blocks.<template>.<field>` for a block's, `<collection>.<field>` for a collection's, `siteSettings.<field>` for Site Settings', with dots for nesting (`blocks.columns.items.media`).
+
+## Fields
+
+| Tina field | caracms field | Stored value |
+|---|---|---|
+| `string` | `text()` | copied as it is |
+| `string`, `ui.component: 'textarea'` | `text({ multiline: true })` | copied (`\n` between lines) |
+| `string` whose name is in the adapt table's `headingFields` (in a block) | `text({ heading: true, … })` | copied |
+| `string` with `options` | `select({ options })` (Tina's labels kept) | copied. A blank or unknown value is left out, so caracms's default applies (the first option, as Tina's "blank reads as the first option"), or the adapt table's `fieldDefaults` value |
+| `string`, `list`, with `options` | `list(select({ options }))` | copied |
+| `string`, `list` | `list(text())` | copied |
+| `string` named `href`, or listed in `addressFields` | `link({ addressOnly: true })` | `{ "href": "…" }` |
+| `number` | `number()` | copied |
+| `boolean` | `toggle()` | copied; `fieldDefaults` fills a missing one (a default that lived in the mapper's code) |
+| `datetime` | `date()` | copied |
+| `image` with a sibling `<name>Alt` string | `media({ only: 'image' })` | `{ key, alt, w, h }`: the pair becomes one value, the `…Alt` field goes |
+| `image` with no alt sibling | `media({ only: 'image' })` | `{ key, alt: "", decorative: true, w, h }`, or the document's title as alt when listed in `docTitleAlt` |
+| `object` with `kind` and an image `src` (the template's `media()`) | `media()`, or `media({ only: 'image' })` when it has no `playbackId` | an image: `{ key, alt, focal, w, h }` (Tina's whole-percent `focusX`/`focusY` become `focal` 0–1). A Mux clip: `{ video, play, poster, name, duration }` (`playAs` → `play`, `posterTime` → `poster`) |
+| `linkLabel` + `href` side by side | one `link()` named `link`, where `linkLabel` stood | `{ label, href }` |
+| `object` list of `{ label, href, style }` | `buttons({ styles })` | `[{ label, href, style }]` |
+| `object` list of `{ label, href }` | `list(link())` | `[{ label, href }]` |
+| `object` list of one field (after the pairs merge) that is text, a reference or an image | a list of that field | flattened: `[{ line: "a" }]` → `["a"]`, `[{ game: "content/games/x.json" }]` → `["x"]`, `[{ image, imageAlt }]` → `[{ key, alt, w, h }]` |
+| `object` list (anything else) | `list({ … })`, `itemLabel` the first text field | a list of objects, keys in schema order |
+| `object` | `group({ … })` | an object, keys in schema order |
+| `reference` | `reference({ to })` | the document's path in its collection: `content/games/x.json` → `x` (Tina's home file → `index`) |
+| `rich-text` | `richText({ headings, links })`: headings from Tina's `overrides.headingLevels` (h2 and h3 only), links on when the toolbar has `link`; Tina's default (no overrides) is h2, h3 and links | caracms's rich text (below) |
+| `displayOnly` | — | dropped |
+| a collection's `isTitle` field | the document's own `title` | copied |
+
+Every label and help (`description`) is carried into the scaffolded config. A template's own description (`ui.description`) becomes its block's `help`, cut to a sentence or two; where the site also put it in front of a field's help ("About this block: …"), the field keeps only its own.
+
+## Rich text
+
+Tina stores Markdown in a JSON string. Each blank-line-separated chunk becomes caracms blocks:
+
+- a line starting `## ` or `### ` → `{ "h2": … }` / `{ "h3": … }`; any other heading level becomes a paragraph, with a warning (caracms never holds an `h1`);
+- runs of `* `, `- ` or `+ ` lines → `{ "ul": [ … ] }`, runs of `1. ` lines → `{ "ol": [ … ] }`; an indented item is flattened into its list, with a warning (caracms has no nested lists);
+- everything else → `{ "p": … }`.
+
+Inline, `**bold**`, `*italic*` and `[text](href)` carry over (Tina's `__bold__` and `_italic_` become `**`/`*`). Tina's two forms of a line break, a trailing `\` or two spaces before a newline, become `\n`, and so does a bare newline inside a paragraph. **Tina's escapes are undone** (`A\&M` → `A&M`, `mailto\:` → `mailto:`) except before `*`, `[`, `]` and `\`, the only characters caracms escapes. Units are trimmed, so a rich heading's trailing `\n` goes, and an empty value becomes `[]`.
+
+## Documents and collections
+
+- A Tina collection with a list of templates (a section builder) → `kind: 'sections'`: `_template` → `type`, the templates list (`sections`) → `blocks`, its other fields are page fields (stored after `title`, before `blocks`). Any other collection → `kind: 'fields'`.
+- The collection's key and folder are its Tina folder in kebab case (`content/clientLogos` → `client-logos`).
+- Tina's `home.json` (the adapt table's `homeFile`) → `index.json`. Folders under a collection are kept.
+- **Block types** take the adapt table's `blockRenames`, and otherwise go from camelCase to kebab case (`textMedia` → `text-media`).
+- `seo { metaTitle, metaDescription, ogImage, ogImageAlt }` → caracms's `seo { title, description, image }`.
+- **Hidden:** a section builder's boolean `hidden` → `"hidden": true` at the top level of the document, beside `title` and `blocks` (absent means shown). The home page can't be hidden: it's left shown, with a warning.
+- Every file starts with its `$schema` (`../../schemas/<collection>.schema.json`), as `caracms schemas` stamps it.
+- A key in a Tina file that its schema no longer has is left out, with a warning.
+
+## Site Settings
+
+| Tina (`siteSettings`) | caracms (`content/site-settings.json`) |
+|---|---|
+| `adminAccess.allow[].entry` | `editors` |
+| `adminBranding { name, accent }` | `brand { name, accent }`. The logo and favicon aren't carried (a warning says so): upload them in the editor |
+| `defaultSeo` | `seo` |
+| `googleTag` | `googleTag` |
+| `formNotifications.<form>[].address` | `formRecipients.<form>`; `--recipients <address>` makes every form's list that one address |
+| `submissionsLink` | dropped (caracms's inbox is in the editor) |
+| everything else | Site Settings' own fields, by the table above |
+
+## Images and files
+
+- **Images keep their bucket objects.** The key is the URL's part after `s3://<bucket>/` (`https://img…/unsafe/plain/s3://share-media-…/uploads/photos/a.jpg` → `uploads/photos/a.jpg`). An image URL that isn't in the bucket is left out, with a warning.
+- **`w` and `h`** come from `scripts/tina-media-sizes.json`, read first. A key it lacks is fetched once (its Tina URL, else the bucket with the site's `S3_*` settings), sized by caracms's own sniffer (EXIF orientation included), and added to the file. Commit the file: re-runs then need no network for images.
+- **File links** the Tina site served itself (`/files/<name>`, from `uploads/<name>`; the adapt table's `fileLinks`) become caracms file addresses, `/files/<hex>/<name>`, wherever an address can be: links, buttons, address fields and rich text. `<hex>` is the first 12 hex of the SHA-256 of the source key, so the address is the same on every run. The object is copied in the bucket to `uploads/<hex>/<name>` (the name slugified as caracms's upload names are), and the copy is skipped when that key exists.
+
+## The adapt table
+
+At the top of the script, under "ADAPT HERE". Everything else is generic.
+
+| Entry | What it's for |
+|---|---|
+| `blockRenames` | the approved block table: a Tina template's caracms key where it isn't the kebab-case rule |
+| `fieldDefaults` | a value Tina's files leave out but the site's mapper code reads as set: a per-block background default that isn't the first option, a toggle that reads as on |
+| `addressFields` | strings that are addresses but aren't named `href` (social links, a privacy link, a YouTube link). Tina's schema doesn't say which strings are links |
+| `headingFields` | text field names that are headings (scaffold only) |
+| `docTitleAlt` | bare images whose alt is the document's title (a client's logo) |
+| `fileLinks` | the Tina site's own file route and the bucket key behind it |
+| `homeFile` | Tina's home page file |