@typeroll/mcp-server 0.7.7 → 0.7.8

package/skills/tr-blog.md

@@ -1,103 +1,89 @@
 ---
 name: tr-blog
-description: Use when the user wants to set up a blog, news section, or article feed on a Typeroll site. Triggers on "add a blog", "set up news", "article section", "create posts", "inlägg", "nyheter", or when the user wants to manage a list of dated articles.
+description: Use when the user wants to set up a blog, news section, podcast feed, or any time-ordered article-style content on a Typeroll site. Triggers on "add a blog", "set up news", "article section", "create posts", "podcast", "inlägg", "nyheter", "avsnitt", or any feed-of-dated-entries pattern.
 ---
 
 # Set up a blog / news section
 
-Typeroll doesn't have a built-in blog — instead the AI writes listing HTML
-directly into a page, sourced from a collection. This skill wires the whole
-flow: collection schema → seed items → listing page → individual item URLs
-via `route_template` → deploy.
+A blog in Typeroll is a **collection with `item_template_html` + `route_template`**. Every published item materialises as its own static page at build time — there is **no need to call `create_page` per article**. The detail design lives once in `item_template_html`; the listing lives once in a page with a `<!-- typeroll:listing -->` marker that `regenerate_collection_listing` refreshes.
+
+If you find yourself about to create 20 pages for 20 articles, stop — you're using the old pattern. The recipe below is the right one.
 
 ## Preconditions
 
 - Site exists with working header/footer.
-- You know the desired collection name (e.g. `blog`, `news`, `artiklar`).
+- Collection name picked (`blog`, `news`, `artiklar`, `podcast`, `avsnitt`).
+- URL structure picked: `/blog/{slug}`, `/news/{slug}`, `/podd/{slug}`. Changing later renames every URL.
 
 ## Recipe
 
-### 1. Create the collection
+### 1. Create the collection with detail template baked in
 
 ```
 create_collection {
   "name": "blog",
   "label_singular": "Artikel",
   "label_plural": "Artiklar",
+  "icon": "📝",
   "slug_field": "slug",
   "sort_field": "date",
   "sort_dir": "desc",
   "route_template": "/blog/{slug}",
+  "item_template_html": "<article class=\"post\">\n  <header class=\"post__header\">\n    <time>{{date}}</time>\n    <h1>{{title}}</h1>\n    {{#author}}<p class=\"byline\">av {{author}}</p>{{/author}}\n  </header>\n  {{#image}}<img class=\"post__hero\" src=\"{{image}}\" alt=\"{{title}}\" />{{/image}}\n  <div class=\"post__body\">{{{body}}}</div>\n</article>\n<style>\n.post{max-width:42rem;margin:3rem auto;padding:0 1rem}\n.post__header time{color:var(--color-text-light);font-size:0.85rem}\n.post__header h1{font-family:var(--font-heading);font-size:2.25rem;margin:0.25rem 0}\n.byline{color:var(--color-text-light);font-size:0.9rem}\n.post__hero{width:100%;aspect-ratio:16/9;object-fit:cover;border-radius:0.5rem;margin:2rem 0}\n.post__body{font-size:1.05rem;line-height:1.7}\n.post__body h2{font-family:var(--font-heading);margin-top:2rem}\n.post__body p{margin-bottom:1.25rem}\n</style>",
   "fields": [
-    {"name": "title",    "type": "text",     "label": "Rubrik",    "required": true},
-    {"name": "slug",     "type": "text",     "label": "URL-slug",  "required": true},
-    {"name": "date",     "type": "date",     "label": "Datum",     "required": true},
-    {"name": "author",   "type": "text",     "label": "Författare"},
-    {"name": "excerpt",  "type": "textarea", "label": "Ingress"},
-    {"name": "body",     "type": "richtext", "label": "Brödtext"},
-    {"name": "image",    "type": "image",    "label": "Omslagsbild"},
-    {"name": "tags",     "type": "text",     "label": "Taggar (kommaseparerade)"}
+    {"name": "title",   "type": "text",     "label": "Rubrik",    "required": true},
+    {"name": "slug",    "type": "text",     "label": "URL-slug",  "required": true},
+    {"name": "date",    "type": "date",     "label": "Datum",     "required": true},
+    {"name": "author",  "type": "text",     "label": "Författare"},
+    {"name": "excerpt", "type": "textarea", "label": "Ingress"},
+    {"name": "body",    "type": "richtext", "label": "Brödtext"},
+    {"name": "image",   "type": "image",    "label": "Omslagsbild"}
   ]
 }
 ```
 
-**Field name rule:** ASCII only, lowercase. `ä→a`, `ö→o`, `å→a`.
+**About `item_template_html`:**
+- `{{field}}` HTML-escapes the value (use for plain text).
+- `{{{field}}}` leaves it raw (use for `body` and any richtext).
+- `{{#field}}...{{/field}}` is a conditional — render the block only if the field is truthy. Useful for optional images, authors, etc.
+- **No loops, no nested conditionals.** If you need either, pre-render the HTML in a field on the item itself (see tr-collection-template for patterns).
 
-### 2. Seed with real content
+**Field name rule:** ASCII only, lowercase, `[a-z][a-z0-9_-]*`. `ä→a`, `ö→o`, `å→a` for the `name`; the `label` can be anything.
 
-Add 2–3 initial articles. Use `create_collection_item`:
+### 2. Seed with real content
 
 ```
-create_collection_item collection="blog" fields={
+create_collection_item collection="blog" status="published" fields={
   "title":   "Vår designfilosofi",
   "slug":    "var-designfilosofi",
   "date":    "2025-05-15",
   "author":  "Anna Lindström",
   "excerpt": "Vi tror på enkelhet med syfte — varje beslut ska kunna motiveras.",
-  "body":    "<p>...</p>",
+  "body":    "<p>Lång brödtext här...</p><h2>En underrubrik</h2><p>Mer text...</p>",
   "image":   "https://cdn.typeroll.com/..."
 }
 ```
 
-If `image` is a URL, upload it first via `upload_media_from_url` and use
-the returned CDN URL.
-
-### 3. List all items for the listing page
-
-```
-list_collection_items collection="blog"
-```
+If `image` is a URL from elsewhere, upload it first via `upload_media_from_url` and use the returned CDN URL.
 
-Use the response to generate the listing HTML. The static site has no
-template engine — the HTML is the listing.
+Each published item with this collection's `route_template` automatically becomes `/blog/{slug}` at deploy time — you do **not** need to call `create_page`.
 
-### 4. Create the listing page
+### 3. Build the listing page (once)
 
-Build HTML manually from the collection items. Include all the data you
-want visible without a detail click. Example structure:
+Create a single page that hosts the listing. The HTML between the `typeroll:listing` markers gets regenerated whenever the collection changes:
 
-```html
-<section class="blog-listing">
-  <div class="container">
-    <h1 class="section-title">Artiklar</h1>
-    <div class="blog-grid">
-      <!-- one .blog-card per item -->
-      <article class="blog-card">
-        <a href="/blog/var-designfilosofi">
-          <img src="https://cdn.typeroll.com/..." alt="Omslagsbild">
-          <div class="blog-card__body">
-            <time class="blog-card__date">15 maj 2025</time>
-            <h2 class="blog-card__title">Vår designfilosofi</h2>
-            <p class="blog-card__excerpt">Vi tror på enkelhet med syfte...</p>
-            <span class="blog-card__cta">Läs mer →</span>
-          </div>
-        </a>
-      </article>
-    </div>
+```
+create_page title="Artiklar" slug="blog" status="published" content_mode="html"
+  html_content="<section class=\"blog-listing\">
+  <div class=\"container\">
+    <h1 class=\"section-title\">Artiklar</h1>
+    <!-- typeroll:listing:blog -->
+    <!-- /typeroll:listing:blog -->
   </div>
 </section>
 <style>
-.blog-grid{display:grid;grid-template-columns:repeat(auto-fill,minmax(300px,1fr));gap:2rem}
+.blog-listing{padding:4rem 0}
+.blog-grid{display:grid;grid-template-columns:repeat(auto-fill,minmax(300px,1fr));gap:2rem;margin-top:2rem}
 .blog-card{border:1px solid var(--color-surface);border-radius:0.5rem;overflow:hidden}
 .blog-card a{text-decoration:none;display:block;color:var(--color-text)}
 .blog-card img{width:100%;aspect-ratio:16/9;object-fit:cover}
@@ -106,72 +92,80 @@ want visible without a detail click. Example structure:
 .blog-card__title{font-family:var(--font-heading);font-size:1.25rem;margin-bottom:0.5rem}
 .blog-card__excerpt{color:var(--color-text-light);font-size:0.9rem;margin-bottom:1rem}
 .blog-card__cta{color:var(--color-accent);font-size:0.85rem;font-weight:600}
-</style>
+</style>"
 ```
 
+### 4. Populate the listing (and re-run after every change)
+
 ```
-create_page title="Artiklar" slug="blog"
-            html_content="<listing HTML>"
-            content_mode="html" status="published"
+regenerate_collection_listing
+  collection="blog"
+  page_id="blog"
+  item_template="<article class=\"blog-card\">
+    <a href=\"{{url}}\">
+      {{#image}}<img src=\"{{image}}\" alt=\"{{title}}\">{{/image}}
+      <div class=\"blog-card__body\">
+        <time class=\"blog-card__date\">{{date}}</time>
+        <h2 class=\"blog-card__title\">{{title}}</h2>
+        <p class=\"blog-card__excerpt\">{{excerpt}}</p>
+        <span class=\"blog-card__cta\">Läs mer →</span>
+      </div>
+    </a>
+  </article>"
+  wrap_open="<div class=\"blog-grid\">"
+  wrap_close="</div>"
 ```
 
-### 5. Create individual article pages
+`{{url}}` resolves through the collection's `route_template`. Only the content between the markers is replaced; everything else on the page stays put. Re-run this whenever items are added, edited, or unpublished.
 
-Each collection item with `route_template: "/blog/{slug}"` gets its own
-URL at deploy time IF you create a matching page for each article. Create
-one page per article:
+### 5. Update the header partial to link to the listing
 
 ```
-create_page title="Vår designfilosofi" slug="blog/var-designfilosofi"
-            html_content="<full article HTML>"
-            content_mode="html" kind="article"
-            author="Anna Lindström"
-            seo_title="Vår designfilosofi — Acme Studio"
-            seo_description="Ingress here"
-            status="published"
+read_partial partial_id="header"
+replace_partial partial_id="header" html_content="<updated with /blog link>"
 ```
 
-The slug `blog/var-designfilosofi` maps to URL `/blog/var-designfilosofi`.
-
-**Important:** Typeroll does NOT auto-generate detail pages from collection
-items. You write the detail HTML per article — this gives full control over
-the design but means each article is a separate `create_page` call.
-
-### 6. Update nav to link to the blog
+### 6. Preview a single article
 
-Read the header partial and add a "Blog" or "Artiklar" link:
 ```
-read_partial partial_id="header"
-replace_partial partial_id="header" html_content="<updated with blog link>"
+get_preview_link collection_name="blog" item_id="<id>"
 ```
 
-### 7. Keep listings in sync
+The returned URL renders the item through `item_template_html` exactly as it'll appear in production.
+
+### 7. Deploy
 
-When new articles are added later, the AI must:
-1. `create_collection_item` with the article data
-2. `create_page` for the article's detail URL
-3. Re-read the full collection via `list_collection_items`
-4. Regenerate the listing HTML and `update_page` the listing page
+```
+trigger_deploy
+get_deploy_status job_id=<id>
+```
 
-Or call `regenerate_collection_listing collection="blog"` if the site has
-that route configured — it reruns the listing generation.
+The build produces one HTML file per published article at `/blog/<slug>` plus the listing at `/blog`, and includes them all in `sitemap.xml`.
 
-### 8. Deploy
+## Adding a new article later
 
 ```
+create_collection_item collection="blog" status="published" fields={ ... }
+regenerate_collection_listing collection="blog" page_id="blog" item_template="..." wrap_open="..." wrap_close="..."
 trigger_deploy
-get_deploy_status job_id=<id>
 ```
 
+Three calls. No per-article `create_page`. No HTML diffing by hand.
+
 ## Pitfalls
 
-- **Listing page goes stale.** Every new article needs the listing page
-  regenerated. There's no auto-sync; you must update the HTML.
-- **Don't use non-ASCII field names.** `datum` not `datum`, `rubrik` not
-  `Rubrik` as the field name. The `label` can be anything; the `name` must
-  be `[a-z][a-z0-9_-]*`.
-- **Article slugs must be globally unique.** `/blog/` prefix in the slug
-  avoids collisions with non-blog pages.
-- **`route_template` is decorative without matching pages.** The template
-  declares the URL structure; actual routing depends on pages existing at
-  those paths. Always create the page.
+- **Don't fall back to "one page per article".** That was the pre-`item_template_html` pattern. It works but it's strictly worse: design changes mean editing N pages, you lose `{{url}}` resolution in listings, sitemap doesn't include items, and previews can't surface a per-item URL. If you find yourself writing `create_page` with `slug: "blog/foo"`, stop and reconsider — the only legitimate reason is a one-off "about the editorial team" page that isn't an article.
+- **Slugs must be unique within the collection.** `regenerate_collection_listing` will silently drop items where `slug` is missing; the listing count will be lower than the item count.
+- **Don't use non-ASCII field names.** `datum` not `Datum`; `forfattare` not `författare` in the `name`. The `label` is free-form.
+- **Listing goes stale if you forget step 4.** Every item change needs `regenerate_collection_listing`. Add it to your mental checklist after every `create/update_collection_item`.
+- **`{{#field}}...{{/field}}` only checks truthiness.** Empty string and the field being absent both count as falsy. If you need "render this block when `published_at` is later than today", do it in the data step — set a flag field.
+- **Template too clever.** Mustache substitution has no loops or arithmetic. For an article with chapter timestamps, multiple authors, a guest with nested links — pre-render the HTML into a single field at `create_collection_item` time. See `tr-collection-template` for concrete patterns.
+
+## When you want a page that ISN'T a collection item
+
+A normal `create_page` is still right for:
+- The blog's about/contact pages.
+- Editorial standalone features.
+- Anything that doesn't fit the "list of dated entries" mould.
+
+Just don't use `create_page` *for the entries themselves*.

package/skills/tr-collection-template.md

@@ -0,0 +1,262 @@
+---
+name: tr-collection-template
+description: Use when building a rich per-item detail page for a Typeroll collection — podcast episodes with audio players and chapter timestamps, case studies with guest cards and metric tiles, products with image galleries and spec tables, anything where the detail template would normally want loops or nested data. Covers the "pre-render into a field" pattern that gets you past the template's no-loops-no-conditionals limit.
+---
+
+# Rich detail templates for collections
+
+`item_template_html` uses lightweight Mustache substitution:
+
+- `{{field}}` — HTML-escaped value
+- `{{{field}}}` — raw value (for richtext / pre-rendered HTML)
+- `{{#field}}…{{/field}}` — conditional, render block when field is truthy
+- `{{url}}` — only meaningful in `regenerate_collection_listing`'s `item_template` (resolves through `route_template`)
+
+**No loops, no nested field access, no arithmetic.** `{{chapters[0].title}}` doesn't work. `{{#chapters}}{{title}}{{/chapters}}` doesn't either — the section syntax is truthiness-only, not iteration.
+
+The pattern that gets you everywhere: **pre-render the HTML into a single string field on the item itself.** The agent (you) does the loop in JavaScript/Python during data prep, then writes the resulting HTML into a richtext field like `chapters_html` or `gallery_html`. The template renders it raw with `{{{chapters_html}}}`.
+
+This skill catalogues the patterns we hit most often, with copy-paste recipes.
+
+## Pattern 1 — Audio player + chapter list (podcast episodes)
+
+**Data shape going in:**
+
+```json
+{
+  "title": "Avsnitt 17 — Designsystem på riktigt",
+  "slug": "17-designsystem-pa-riktigt",
+  "date": "2025-05-15",
+  "audio_url": "https://cdn.example.com/avsnitt-17.mp3",
+  "duration_min": 42,
+  "chapters": [
+    { "time_seconds": 0,    "title": "Intro" },
+    { "time_seconds": 132,  "title": "Vad är ett designsystem?" },
+    { "time_seconds": 845,  "title": "Tokens vs. komponenter" },
+    { "time_seconds": 1820, "title": "Vanliga fällor" }
+  ]
+}
+```
+
+**Pre-render `chapters_html` before calling `create_collection_item`:**
+
+```js
+const formatTime = (s) =>
+  s < 3600
+    ? `${Math.floor(s/60)}:${String(s%60).padStart(2,'0')}`
+    : `${Math.floor(s/3600)}:${String(Math.floor(s%3600/60)).padStart(2,'0')}:${String(s%60).padStart(2,'0')}`;
+
+const chaptersHtml = `
+<ol class="chapters">
+  ${item.chapters.map(c => `
+    <li>
+      <button type="button" data-jump-to="${c.time_seconds}">
+        <span class="chapters__time">${formatTime(c.time_seconds)}</span>
+        <span class="chapters__title">${escapeHtml(c.title)}</span>
+      </button>
+    </li>
+  `).join('')}
+</ol>`;
+```
+
+**Schema (note `chapters_html: richtext` — it carries HTML):**
+
+```
+create_collection {
+  "name": "avsnitt",
+  "label_singular": "Avsnitt",
+  "label_plural": "Avsnitt",
+  "slug_field": "slug",
+  "sort_field": "date",
+  "sort_dir": "desc",
+  "route_template": "/podd/{slug}",
+  "fields": [
+    {"name":"title",         "type":"text",     "required":true},
+    {"name":"slug",          "type":"text",     "required":true},
+    {"name":"date",          "type":"date",     "required":true},
+    {"name":"audio_url",     "type":"text",     "required":true},
+    {"name":"duration_min",  "type":"number"},
+    {"name":"excerpt",       "type":"textarea"},
+    {"name":"body",          "type":"richtext"},
+    {"name":"chapters_html", "type":"richtext", "label":"Kapitellista (genereras)"}
+  ],
+  "item_template_html": "<article class=\"episode\">\n  <header class=\"episode__hero\">\n    <p class=\"episode__date\">{{date}} · {{duration_min}} min</p>\n    <h1>{{title}}</h1>\n    <p class=\"episode__excerpt\">{{excerpt}}</p>\n  </header>\n  <div class=\"episode__player\">\n    <audio controls preload=\"metadata\" src=\"{{audio_url}}\"></audio>\n  </div>\n  {{#chapters_html}}<section class=\"episode__chapters\"><h2>Kapitel</h2>{{{chapters_html}}}</section>{{/chapters_html}}\n  <section class=\"episode__notes\">{{{body}}}</section>\n  <script>\n    document.querySelectorAll('[data-jump-to]').forEach(b => {\n      b.addEventListener('click', () => {\n        const a = document.querySelector('audio');\n        if (a) { a.currentTime = Number(b.dataset.jumpTo); a.play(); }\n      });\n    });\n  </script>\n  <style>\n    .episode{max-width:42rem;margin:3rem auto;padding:0 1rem}\n    .episode__hero{background:linear-gradient(135deg,var(--color-primary),var(--color-accent));color:#fff;padding:3rem 2rem;border-radius:1rem;margin-bottom:2rem}\n    .episode__date{opacity:0.85;font-size:0.85rem}\n    .episode__hero h1{font-family:var(--font-heading);font-size:2rem;margin:0.5rem 0}\n    .episode__player audio{width:100%}\n    .chapters{list-style:none;padding:0;margin:1.5rem 0}\n    .chapters li{margin:0.25rem 0}\n    .chapters button{display:flex;gap:1rem;width:100%;background:transparent;border:0;padding:0.5rem 0.75rem;cursor:pointer;text-align:left;border-radius:0.375rem;font:inherit;color:inherit}\n    .chapters button:hover{background:var(--color-surface)}\n    .chapters__time{font-variant-numeric:tabular-nums;color:var(--color-text-light);min-width:4ch}\n  </style>\n</article>"
+}
+```
+
+**Create the item with both raw chapters AND the pre-rendered HTML:**
+
+```
+create_collection_item collection="avsnitt" status="published" fields={
+  "title":         "Avsnitt 17 — Designsystem på riktigt",
+  "slug":          "17-designsystem-pa-riktigt",
+  "date":          "2025-05-15",
+  "audio_url":     "https://cdn.example.com/avsnitt-17.mp3",
+  "duration_min":  42,
+  "excerpt":       "Vi pratar med...",
+  "body":          "<p>...</p>",
+  "chapters_html": "<ol class=\"chapters\">...</ol>"
+}
+```
+
+The raw `chapters` array doesn't need to be stored unless you have a use for it (e.g. regenerating the HTML later from a structured source). If you do want it for round-trip editing, add a `chapters_json: textarea` field and stringify the array into it.
+
+## Pattern 2 — Guest card with nested fields
+
+Each episode features a guest with a name, role, photo, and external links. Mustache can't reach into nested objects, so flatten OR pre-render.
+
+**Option A: Flatten into prefixed fields (preferable when there's ≤1 guest):**
+
+```
+fields: [
+  ...,
+  {"name":"guest_name",  "type":"text"},
+  {"name":"guest_role",  "type":"text"},
+  {"name":"guest_photo", "type":"image"},
+  {"name":"guest_bio",   "type":"textarea"},
+  {"name":"guest_linkedin", "type":"text"},
+  {"name":"guest_website",  "type":"text"}
+]
+```
+
+In the template:
+
+```html
+{{#guest_name}}
+<aside class="guest">
+  {{#guest_photo}}<img src="{{guest_photo}}" alt="{{guest_name}}">{{/guest_photo}}
+  <div>
+    <h3>{{guest_name}}</h3>
+    <p class="guest__role">{{guest_role}}</p>
+    <p>{{guest_bio}}</p>
+    <p class="guest__links">
+      {{#guest_linkedin}}<a href="{{guest_linkedin}}">LinkedIn</a>{{/guest_linkedin}}
+      {{#guest_website}}<a href="{{guest_website}}">Webbplats</a>{{/guest_website}}
+    </p>
+  </div>
+</aside>
+{{/guest_name}}
+```
+
+**Option B: Pre-render `guest_html` (when there are multiple guests or arbitrary depth):**
+
+```js
+const guestHtml = item.guests.map(g => `
+  <article class="guest">
+    ${g.photo ? `<img src="${escapeHtml(g.photo)}" alt="${escapeHtml(g.name)}">` : ''}
+    <div>
+      <h3>${escapeHtml(g.name)}</h3>
+      <p class="guest__role">${escapeHtml(g.role)}</p>
+      ${g.links.map(l => `<a href="${escapeHtml(l.url)}">${escapeHtml(l.label)}</a>`).join(' · ')}
+    </div>
+  </article>
+`).join('');
+```
+
+Then `{{{guests_html}}}` in the template.
+
+## Pattern 3 — Gradient hero with computed colours
+
+The hero needs a colour pair derived from a single brand colour the user picked per item. The template can't compute — pre-compute and pass as fields:
+
+```js
+function shade(hex, amount) { /* lighten/darken */ }
+
+const item = {
+  ...,
+  hero_from: rawColor,
+  hero_to:   shade(rawColor, -0.2),
+};
+```
+
+Template:
+
+```html
+<header class="hero" style="background:linear-gradient(135deg, {{hero_from}}, {{hero_to}})">
+  <h1>{{title}}</h1>
+</header>
+```
+
+Inline style with two substituted hex strings — works because the `{{}}` substitutions sit inside a CSS value, not as a CSS variable name. (Don't do this with user-supplied colours that haven't been validated — a malicious item could break out of the style attribute. For agent-curated colours this is fine.)
+
+## Pattern 4 — Image gallery with thumbnails
+
+Same drill. The agent renders the gallery HTML when shaping the item:
+
+```js
+const galleryHtml = `
+<div class="gallery">
+  ${item.images.map((img, i) => `
+    <a href="${escapeHtml(img.full)}" class="gallery__item">
+      <img src="${escapeHtml(img.thumb)}" alt="${escapeHtml(img.alt || `Bild ${i+1}`)}" loading="lazy">
+    </a>
+  `).join('')}
+</div>`;
+```
+
+Schema gains `gallery_html: richtext`. Template renders `{{{gallery_html}}}`.
+
+For a lightbox you can either inline a tiny vanilla JS handler in the item_template_html (works once per page load) or `tr-images` the gallery into a reusable partial.
+
+## Pattern 5 — Spec table (for products, services, etc.)
+
+For a fixed set of spec fields (price, dimensions, in-stock, lead time), just add the fields explicitly:
+
+```
+fields: [
+  ...,
+  {"name":"price_sek",  "type":"number"},
+  {"name":"weight_g",   "type":"number"},
+  {"name":"in_stock",   "type":"boolean"},
+  {"name":"lead_days",  "type":"number"}
+]
+```
+
+```html
+<dl class="specs">
+  {{#price_sek}}<dt>Pris</dt><dd>{{price_sek}} kr</dd>{{/price_sek}}
+  {{#weight_g}}<dt>Vikt</dt><dd>{{weight_g}} g</dd>{{/weight_g}}
+  <dt>Lagerstatus</dt><dd>{{#in_stock}}I lager{{/in_stock}}{{^in_stock}}Slut{{/in_stock}}</dd>
+  {{#lead_days}}<dt>Leveranstid</dt><dd>{{lead_days}} dagar</dd>{{/lead_days}}
+</dl>
+```
+
+(`{{^field}}…{{/field}}` is the inverse of `{{#field}}` — render when falsy.)
+
+For variable specs (different products have different attributes), fall back to a pre-rendered `specs_html` field.
+
+## Pre-rendering helpers — minimum viable
+
+Every pre-render needs `escapeHtml`. Put this at the top of your data-prep script:
+
+```js
+const escapeHtml = (s) =>
+  String(s ?? '')
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+```
+
+Skip it only when you're certain the value can't carry user-supplied content (your own constants are fine; anything from a scrape, the user, or a model output goes through `escapeHtml`).
+
+## When to flatten vs pre-render
+
+Rough guideline:
+
+| Situation | Approach |
+|---|---|
+| 1–N optional related fields, fixed shape | Flatten into prefixed fields (`guest_name`, `guest_role`, …) and use `{{#field}}` conditionals |
+| List of items with internal structure (chapters, gallery, related-links) | Pre-render to a single `*_html` field |
+| Computed values (formatted dates, derived colours, totals) | Pre-compute as a sibling field, substitute with `{{}}` |
+| Conditional sections based on multiple fields ("show this when status=published AND has_video") | Pre-compute a boolean field; conditional in the template |
+| Genuinely dynamic content that changes per visitor | Doesn't fit — the static template renders once at build. Move to client-side JS in the template body, or rethink the page. |
+
+## Pitfalls
+
+- **Forgetting `{{{ }}}` for pre-rendered HTML.** `{{chapters_html}}` (double braces) HTML-escapes the angle brackets and shows source code. Must be triple braces.
+- **Mutating a published item's schema.** Removing or renaming a field that the template references silently produces empty sections. Keep templates in sync with schema changes.
+- **Pre-rendered HTML drifts when you change the visual design.** The HTML for `chapters_html` was generated against the design as it was on import day. If you redo the look later, you need to re-prep + re-write every item's pre-rendered field, not just the template. Consider keeping the raw data (`chapters_json: textarea` with the original array stringified) so you can regenerate.
+- **Inline `<script>` in `item_template_html` runs once per page.** That's fine for self-contained per-page widgets (the audio chapter-jumper above). If two collections need the same widget, factor it into a partial that both `item_template_html`s `<x-include>`.
+- **Don't put credentials in pre-rendered HTML.** API keys, signed tokens — they go into the build output and end up on the public web. Run any prep step you wouldn't paste into a public Gist with that in mind.