@port60/template-kit 0.9.0 → 0.11.0

package/src/lib/agentsMd.mjs

@@ -1,13 +1,12 @@
 // The scaffold's AI-agent briefing (T3, user requirement: the kit must let people put an AI
-// engine on template work and be productive immediately). Written for ANY coding agent —
-// AGENTS.md is the cross-tool convention and CLAUDE.md carries the identical content for tools
+// engine on template work and be productive immediately). Written for ANY coding agent, // AGENTS.md is the cross-tool convention and CLAUDE.md carries the identical content for tools
 // that read that name. The briefing is the contract's rules + the iteration loop, so an agent's
 // first move is always the same: read this, edit, validate --json, repeat until clean.
 
 export function agentsMd(name) {
   return `# Working on the "${name}" Port60 template
 
-You are working on a **Port60 site template** — a small, versioned artifact of Liquid renderers
+You are working on a **Port60 site template**, a small, versioned artifact of Liquid renderers
 and CSS that a charity's site is rendered through. It contains **no application code**: no
 JavaScript, no API calls, no payment logic. Templates decide how a site *looks*; the platform
 owns what it *does*.
@@ -22,25 +21,25 @@ npm run package           # validate + produce the uploadable <name>-<version>.z
 \`\`\`
 
 **After every meaningful edit, run \`npm run validate:json\` and fix every error before moving
-on.** The validator is the exact code the platform runs at upload — if it passes here, the
+on.** The validator is the exact code the platform runs at upload, if it passes here, the
 platform accepts it; if it fails here, the upload will fail identically.
 
 ## The file layout (nothing else is accepted)
 
-- \`manifest.json\` — identity + what you support. \`name\` and \`version\` are immutable
+- \`manifest.json\`, identity + what you support. \`name\` and \`version\` are immutable
   identity; bump \`version\` (semver) for every published change.
-- \`layout.liquid\` — the page chrome (header/nav/footer). Must contain **exactly one**
+- \`layout.liquid\`, the page chrome (header/nav/footer). Must contain **exactly one**
   \`{% content %}\` slot. Only needed when \`supports.layout\` is true.
-- \`sections/<type>.liquid\` — one renderer per section type you declare in
+- \`sections/<type>.liquid\`, one renderer per section type you declare in
   \`supports.sections\`. Charities compose pages from a **closed catalogue** of section types
-  (see \`npm run validate\` output or the docs) — you cannot invent new types.
-- \`pages/<page>.liquid\` — optional full-page templates for \`supports.pageTemplates\`.
-- \`assets/theme.css\` — required, your entire look. More \`.css\` files under \`assets/\` are
-  allowed. **No images, no JS** — they are refused at upload.
+  (see \`npm run validate\` output or the docs), you cannot invent new types.
+- \`pages/<page>.liquid\`, optional full-page templates for \`supports.pageTemplates\`.
+- \`assets/theme.css\`, required, your entire look. More \`.css\` files under \`assets/\` are
+  allowed. **No images, no JS**, they are refused at upload.
 
 ## The rules the validator enforces (do not fight them)
 
-1. **Escape-by-default.** Every output is HTML-escaped unless you use \`| raw\` — and the only
+1. **Escape-by-default.** Every output is HTML-escaped unless you use \`| raw\`, and the only
    values you may pass through raw are the contract's sanitised richtext fields.
 2. **The dialect is a whitelist.** \`{% include %}\`, \`{% render %}\`, \`{% layout %}\` and
    several other tags are excluded and fail at parse. Unknown filters throw.
@@ -55,7 +54,7 @@ platform accepts it; if it fails here, the upload will fail identically.
 5. **Render budgets are real.** Runaway loops are killed (~1s per render). Keep renderers simple.
 6. **Context is a whitelist.** Sections see \`{section, brand}\` plus only the collection named by
    that section in the contract; layouts see \`{brand, nav, socials, worship, locale}\`; page
-   templates see their documented fixture + \`brand\`. Nothing else exists — do not invent
+   templates see their documented fixture + \`brand\`. Nothing else exists, do not invent
    variables.
 7. **Capabilities are matching metadata, never entitlements.** Every value in
    \`requiresCapabilities\` must have a declared section, page template or island that presents it.
@@ -77,15 +76,44 @@ platform accepts it; if it fails here, the upload will fail identically.
 - Other platform routes keep their platform body and render inside your layout. Capability flags
   expose documented optional context; they do not transfer transaction or route ownership.
 
+## The content model
+
+Everything you read comes from ONE tree: \`site\`, \`site.brand\`, \`site.nav\`,
+\`site.socials\`, \`site.locale\` and the typed collections under \`site.content.*\`
+(services, events, articles, campaigns, causes, courses, resources, locations,
+schedules, about). Four rules it never breaks, so neither should you:
+
+- Every collection is BOUNDED (a documented cap plus a \`moreHref\`), link onward, never
+  assume you have everything.
+- Enum fields are OPEN, branch on the values you style and fall back for the rest; the
+  validator proves your template survives values it has never seen.
+- Optional fields are explicitly nullable, always branch.
+- The model only grows. The validator computes your content footprint from the paths you read
+  and stamps the minimum model version at publish; you never declare versions, and dynamic
+  indexing into \`site.content\` is refused so that stays decidable.
+
+SEE the model: \`npm run dev\` serves the full reference with live example data at \`/model\`;
+\`npx p60-template-kit model --json\` prints the machine-readable registry; the same reference
+lives at https://developers.port60.com/reference/content-model/.
+
+Bring your own content and imagery: \`npx p60-template-kit content .\` ejects every collection,
+fully populated, as an editable JSON file; replace the copy and the imageUrl values, then
+\`npx p60-template-kit dev . --content my-org.json\` renders YOUR data (the preview admits
+exactly the image hosts your file names, nothing else).
+
+You may replace the preview DATA with your own via \`preview-content.json\` beside the
+manifest ({ collection: [items] }, schema-checked, hot-reloaded). The shape is fixed, packaging
+excludes it, and conformance proofs always run on the canonical fixtures.
+
 ## What to build with
 
 - Theme via CSS custom properties and the settings knobs you declare in
-  \`manifest.settings.schema\` — they surface in the charity's Appearance editor as
+  \`manifest.settings.schema\`, they surface in the charity's Appearance editor as
   \`--p60s-<key>\` variables and \`data-p60s-<key>\` body attributes.
 - Hero photographs (\`homeHero.images\`, when you declare \`supports.heroImagery\`): render one
   photo directly as a TREATED backdrop (a scrim/tint built from your own palette variables via
-  color-mix — never raw), place the \`hero_carousel\` island for two or more (style its
-  \`.hero-slide-scrim\`), and design the no-photo state as a gradient/colour — never a
+  color-mix, never raw), place the \`hero_carousel\` island for two or more (style its
+  \`.hero-slide-scrim\`), and design the no-photo state as a gradient/colour, never a
   placeholder. The starter's \`.lq-homehero\` is the reference; the validator checks all of this
   behaviourally.
 - "Looks" = named one-click bundles of knob values in \`manifest.looks\`.
@@ -93,19 +121,19 @@ platform accepts it; if it fails here, the upload will fail identically.
 - Navigation can contain two levels below a top item. Render every supplied child and branch on
   optional \`group\`, \`description\`, \`imageUrl\` and \`megaMenu\` promo metadata. Never hardcode
   menu groups that are not in \`nav\`.
-- Dynamic sections include appeals (\`causes\`), programmes (\`services\`), resources, locations,
-  volunteering opportunities and structured media. Derive or omit when a collection is empty and
-  use the supplied URLs rather than constructing routes.
-- Submission and behaviour surfaces such as \`newsletter_signup\`, \`volunteer_signup\`, \`form\`,
-  \`search\`, \`language_switch\` and \`next_prayer\` are platform islands. Place and style them;
+- Dynamic sections include appeals (\`causes\`), programmes (\`services\`), resources and
+  locations. Derive or omit when a collection is empty and use the supplied URLs rather than
+  constructing routes.
+- Submission and behaviour surfaces such as \`newsletter_signup\`, \`form\`, \`search\`,
+  \`language_switch\` and \`next_prayer\` are platform islands. Place and style them;
   never reproduce their API calls or consent behaviour.
 - \`manifest.imagery.hero\` (optional but recommended): declare the photo shape YOUR hero
-  composes best with (\`idealAspect\`, \`minWidth\`, a one-line \`note\`) — the charity's editor
+  composes best with (\`idealAspect\`, \`minWidth\`, a one-line \`note\`), the charity's editor
   measures their actual upload against it and advises. Advice, never enforcement.
 
 ## Which contract this is
 
-The section catalogue, islands and fixtures here are the **Charity Platform contract v1** — the
+The section catalogue, islands and fixtures here are the **Charity Platform contract v1**, the
 platform's first product surface. The dialect, the rules above and this toolchain are
 platform-wide; other Port60 products will ship their own contract packs. Do not assume the
 current section list is universal.
@@ -113,7 +141,7 @@ current section list is universal.
 ## Reference
 
 The full generated reference (sections, islands, context variables, tokens, dialect) lives at
-https://developers.port60.com — also available in one file for agents at
+https://developers.port60.com, also available in one file for agents at
 https://developers.port60.com/llms-full.txt
 `;
 }

package/src/vendor/contract/v1/behaviours.json

@@ -64,7 +64,7 @@
       "name": "stickyHeader",
       "status": "available",
       "label": "Sticky header condense",
-      "description": "State classes for scroll-aware headers: past a small threshold the engine adds is-condensed; with the \"auto-hide\" value, scrolling down past 160px adds is-hidden and scrolling up removes it. The engine only ever toggles classes (rAF-throttled) — what condensing or hiding looks like, and whether it animates, is entirely the template's CSS (gate transitions behind prefers-reduced-motion yourself; the classes always apply because a condensed header is layout, not decoration).",
+      "description": "State classes for scroll-aware headers: past a small threshold the engine adds is-condensed; with the \"auto-hide\" value, scrolling down past 160px adds is-hidden and scrolling up removes it. The engine only ever toggles classes (rAF-throttled), what condensing or hiding looks like, and whether it animates, is entirely the template's CSS (gate transitions behind prefers-reduced-motion yourself; the classes always apply because a condensed header is layout, not decoration).",
       "attributes": [
         { "attr": "data-p60-sticky-header", "value": "none for condense-only; \"auto-hide\" adds the hide-on-scroll-down pair" }
       ],
@@ -75,7 +75,7 @@
       "name": "stickyCta",
       "status": "available",
       "label": "Sticky call-to-action bar",
-      "description": "Adds is-stuck once the visitor scrolls past the threshold (the attribute value in px, default 480) and removes it above. The bar should DUPLICATE an action that already exists in the page (a donate button, a ticket link) — because of that, this is the one behaviour whose element may be hidden unconditionally in CSS rather than .p60-js-scoped: a no-JS visitor loses nothing, the original action is still on the page.",
+      "description": "Adds is-stuck once the visitor scrolls past the threshold (the attribute value in px, default 480) and removes it above. The bar should DUPLICATE an action that already exists in the page (a donate button, a ticket link); because of that, this is the one behaviour whose element may be hidden unconditionally in CSS rather than .p60-js-scoped: a no-JS visitor loses nothing; the original action is still on the page.",
       "attributes": [
         { "attr": "data-p60-sticky-cta", "value": "optional scroll threshold in px (default 480)" }
       ],
@@ -86,7 +86,7 @@
       "name": "lightbox",
       "status": "available",
       "label": "Lightbox",
-      "description": "On a group container: each data-p60-lightbox-item is an anchor whose href is the full image (the no-JS render simply navigates to it — already functional). The engine intercepts the click and opens an injected overlay (.p60-lightbox) with the image, a caption from data-p60-caption or the thumbnail's alt, a close button, backdrop and Escape close, arrow-key prev/next within the group, and a focus trap. Reduced motion: no transition on the overlay (the engine sets none; style the steady state).",
+      "description": "On a group container: each data-p60-lightbox-item is an anchor whose href is the full image (the no-JS render simply navigates to it, already functional). The engine intercepts the click and opens an injected overlay (.p60-lightbox) with the image, a caption from data-p60-caption or the thumbnail's alt, a close button, backdrop and Escape close, arrow-key prev/next within the group, and a focus trap. Reduced motion: no transition on the overlay (the engine sets none; style the steady state).",
       "attributes": [
         { "attr": "data-p60-lightbox", "value": "none; the group container" },
         { "attr": "data-p60-lightbox-item", "value": "none; on each anchor to a full image" },
@@ -100,7 +100,7 @@
       "name": "tabs",
       "status": "available",
       "label": "Tabs",
-      "description": "data-p60-tab=\"key\" on each tab control and data-p60-panel=\"key\" on each panel, inside a data-p60-tabs container. The engine wires the tablist/tab/tabpanel roles, aria-selected, roving tabindex, arrow/Home/End keys, toggles is-active on the active pair and hides inactive panels with the hidden attribute — so the no-JS render shows every panel stacked and complete, with no CSS scoping needed. The first tab (or the one authored with is-active) starts active.",
+      "description": "data-p60-tab=\"key\" on each tab control and data-p60-panel=\"key\" on each panel, inside a data-p60-tabs container. The engine wires the tablist/tab/tabpanel roles, aria-selected, roving tabindex, arrow/Home/End keys, toggles is-active on the active pair and hides inactive panels with the hidden attribute, so the no-JS render shows every panel stacked and complete, with no CSS scoping needed. The first tab (or the one authored with is-active) starts active.",
       "attributes": [
         { "attr": "data-p60-tabs", "value": "none; the container" },
         { "attr": "data-p60-tab", "value": "the key of the panel this control activates" },

package/src/vendor/contract/v1/content-bounds.json

@@ -1,5 +1,5 @@
 {
-  "description": "The maximum lengths of every admin-entered display field a template renders. The admin screens stop input at these caps and the API rejects anything longer, so a template can design cards, headings and captions against known worst cases. Additive-only within a contract major: a bound may loosen, never tighten. Long-form bodies (article bodies, course About pages, service pages) are deliberately outside this table — they are sanitised HTML rendered in dedicated full-width regions, never inside cards.",
+  "description": "The maximum lengths of every admin-entered display field a template renders. The admin screens stop input at these caps and the API rejects anything longer, so a template can design cards, headings and captions against known worst cases. Additive-only within a contract major: a bound may loosen, never tighten. Long-form bodies (article bodies, course About pages, service pages) are deliberately outside this table; they are sanitised HTML rendered in dedicated full-width regions, never inside cards.",
   "groups": [
     {
       "name": "Brand (layout chrome)",
@@ -68,7 +68,7 @@
         {
           "field": "Tag",
           "max": 40,
-          "note": "Each — rendered as chips."
+          "note": "Each, rendered as chips."
         }
       ]
     },
@@ -109,7 +109,7 @@
         {
           "field": "Page name",
           "max": 200,
-          "note": "The body is sanitised HTML rendered full-width — not card content."
+          "note": "The body is sanitised HTML rendered full-width, not card content."
         }
       ]
     }

package/src/vendor/contract/v1/content-model.json

@@ -0,0 +1,165 @@
+{
+  "description": "The CONTENT MODEL REGISTRY (docs/template-content-model.md, v1): the typed `site.content.*` tree every template reads. One realistic organisation, one shape. Four disciplines are baked in from birth because they cannot be retrofitted: every collection is BOUNDED (a documented cap and an explicit moreHref, so a big tenant can never break a render budget); every enum field is OPEN (values grow; templates must survive unknown values, proven behaviourally); every optional field is EXPLICITLY nullable (branch-on-it is the norm); and the model is ADD-ONLY (fields and collections gain `deprecated: true` markers, they are never removed within a major, deprecated means it stops being documented, never that it stops being served). Versioning is COMPUTED, never author-declared: every collection and field carries `since`, the validator derives a template's required minimum from its content footprint at publish, and authors never think about versions. New list or field = minor. Fixture or doc clarification = patch.",
+  "version": "1.0",
+  "root": "site",
+  "siblings": {
+    "description": "site.brand, site.nav, site.socials and site.locale carry the SAME shapes documented in context.json for the flat era; the tree re-addresses them, it does not reshape them.",
+    "keys": ["brand", "nav", "socials", "locale"]
+  },
+  "collections": {
+    "services": {
+      "since": "1.0",
+      "cap": 24,
+      "moreHref": "/services",
+      "description": "The organisation's published content pages (the services CMS), newest curation order first.",
+      "item": {
+        "id": { "type": "string", "since": "1.0" },
+        "title": { "type": "string", "since": "1.0", "max": 200 },
+        "slug": { "type": "string", "since": "1.0" },
+        "summary": { "type": "string", "since": "1.0", "nullable": true, "max": 500 },
+        "imageUrl": { "type": "string", "since": "1.0", "nullable": true },
+        "href": { "type": "string", "since": "1.0" }
+      }
+    },
+    "events": {
+      "since": "1.0",
+      "cap": 12,
+      "moreHref": "/events",
+      "description": "Published events, soonest first. `registrationMode` is an OPEN enum: INFO, RSVP and TICKETED exist today and new modes will arrive; branch on the ones you style and fall back for the rest.",
+      "item": {
+        "id": { "type": "string", "since": "1.0" },
+        "name": { "type": "string", "since": "1.0", "max": 200 },
+        "description": { "type": "string", "since": "1.0", "nullable": true, "max": 200 },
+        "registrationMode": { "type": "string", "since": "1.0", "enumOpen": ["INFO", "RSVP", "TICKETED"] },
+        "startsAt": { "type": "string", "since": "1.0" },
+        "endsAt": { "type": "string", "since": "1.0", "nullable": true },
+        "venueName": { "type": "string", "since": "1.0", "nullable": true, "max": 200 },
+        "online": { "type": "boolean", "since": "1.0" },
+        "imageUrl": { "type": "string", "since": "1.0", "nullable": true },
+        "onSale": { "type": "boolean", "since": "1.0" },
+        "soldOut": { "type": "boolean", "since": "1.0" },
+        "priceFrom": { "type": "number", "since": "1.0", "nullable": true },
+        "currency": { "type": "string", "since": "1.0", "nullable": true },
+        "detailHref": { "type": "string", "since": "1.0" }
+      }
+    },
+    "articles": {
+      "since": "1.0",
+      "cap": 12,
+      "moreHref": "/articles/all",
+      "description": "Published articles, newest first. Detail bodies stay editor-owned sanitised richtext on the article page BY DESIGN; the card model carries everything a listing needs.",
+      "item": {
+        "id": { "type": "string", "since": "1.0" },
+        "title": { "type": "string", "since": "1.0", "max": 200 },
+        "slug": { "type": "string", "since": "1.0" },
+        "excerpt": { "type": "string", "since": "1.0", "nullable": true, "max": 500 },
+        "imageUrl": { "type": "string", "since": "1.0", "nullable": true },
+        "authorName": { "type": "string", "since": "1.0", "nullable": true, "max": 120 },
+        "authorRole": { "type": "string", "since": "1.0", "nullable": true, "max": 120 },
+        "categories": { "type": "string[]", "since": "1.0" },
+        "publishedAt": { "type": "string", "since": "1.0" },
+        "readingMinutes": { "type": "number", "since": "1.0", "nullable": true },
+        "href": { "type": "string", "since": "1.0" }
+      }
+    },
+    "campaigns": {
+      "since": "1.0",
+      "cap": 12,
+      "moreHref": "/campaigns",
+      "description": "Live campaigns, curation order.",
+      "item": {
+        "id": { "type": "string", "since": "1.0" },
+        "title": { "type": "string", "since": "1.0", "max": 200 },
+        "href": { "type": "string", "since": "1.0" },
+        "summary": { "type": "string", "since": "1.0", "nullable": true, "max": 500 },
+        "imageUrl": { "type": "string", "since": "1.0", "nullable": true }
+      }
+    },
+    "causes": {
+      "since": "1.0",
+      "cap": 12,
+      "moreHref": "/donate",
+      "description": "Causes currently accepting donations, quick-give first. `paymentOptions` mirrors the public cause contract.",
+      "item": {
+        "id": { "type": "string", "since": "1.0" },
+        "title": { "type": "string", "since": "1.0", "max": 200 },
+        "slug": { "type": "string", "since": "1.0" },
+        "description": { "type": "string", "since": "1.0", "nullable": true, "max": 500 },
+        "imageUrl": { "type": "string", "since": "1.0", "nullable": true },
+        "targetAmount": { "type": "number", "since": "1.0", "nullable": true },
+        "raisedAmount": { "type": "number", "since": "1.0", "nullable": true },
+        "progressPercentage": { "type": "number", "since": "1.0", "nullable": true },
+        "href": { "type": "string", "since": "1.0" },
+        "paymentOptions": { "type": "object", "since": "1.0", "nullable": true }
+      }
+    },
+    "courses": {
+      "since": "1.0",
+      "cap": 12,
+      "moreHref": "/courses",
+      "description": "Enrollable courses. The long-form About body is sanitised richtext on the course page, never in cards.",
+      "item": {
+        "id": { "type": "string", "since": "1.0" },
+        "title": { "type": "string", "since": "1.0", "max": 200 },
+        "description": { "type": "string", "since": "1.0", "nullable": true, "max": 500 },
+        "imageUrl": { "type": "string", "since": "1.0", "nullable": true },
+        "venue": { "type": "string", "since": "1.0", "nullable": true, "max": 200 },
+        "audience": { "type": "string", "since": "1.0", "enumOpen": ["ADULT", "CHILD", "FAMILY"] },
+        "priceFrom": { "type": "number", "since": "1.0", "nullable": true },
+        "currency": { "type": "string", "since": "1.0", "nullable": true },
+        "soldOut": { "type": "boolean", "since": "1.0" },
+        "href": { "type": "string", "since": "1.0" }
+      }
+    },
+    "resources": {
+      "since": "1.0",
+      "cap": 24,
+      "moreHref": "/resources",
+      "description": "Published documents, grouped by folder.",
+      "item": {
+        "id": { "type": "string", "since": "1.0" },
+        "title": { "type": "string", "since": "1.0", "max": 200 },
+        "folder": { "type": "string", "since": "1.0", "nullable": true },
+        "url": { "type": "string", "since": "1.0" },
+        "contentType": { "type": "string", "since": "1.0", "nullable": true },
+        "bytes": { "type": "number", "since": "1.0", "nullable": true },
+        "publishedAt": { "type": "string", "since": "1.0", "nullable": true }
+      }
+    },
+    "locations": {
+      "since": "1.0",
+      "cap": 12,
+      "moreHref": "/locations",
+      "description": "The organisation's physical places, primary first.",
+      "item": {
+        "id": { "type": "string", "since": "1.0" },
+        "name": { "type": "string", "since": "1.0", "max": 200 },
+        "address": { "type": "string", "since": "1.0", "nullable": true, "max": 500 },
+        "latitude": { "type": "number", "since": "1.0", "nullable": true },
+        "longitude": { "type": "number", "since": "1.0", "nullable": true },
+        "primary": { "type": "boolean", "since": "1.0" },
+        "directionsHref": { "type": "string", "since": "1.0", "nullable": true }
+      }
+    },
+    "schedules": {
+      "since": "1.0",
+      "cap": 4,
+      "moreHref": null,
+      "description": "TYPE-DERIVED recurring schedules. `type` is an OPEN enum; 'worship' is the first (its shape is the layout worship contract: times, labels, today, next). Other institutions arrive as new types; render the types you know, ignore the rest.",
+      "item": {
+        "type": { "type": "string", "since": "1.0", "enumOpen": ["worship"] },
+        "content": { "type": "object", "since": "1.0" }
+      }
+    },
+    "about": {
+      "since": "1.0",
+      "cap": 24,
+      "moreHref": null,
+      "description": "The admin-authored page composition: the ordered sections of the home/about surface. `type` is the section catalogue's OPEN enum; `content` is that section type's fields. This is what `section.*` re-addresses; a mega-page template can walk it directly.",
+      "item": {
+        "type": { "type": "string", "since": "1.0", "enumOpen": [] },
+        "content": { "type": "object", "since": "1.0" }
+      }
+    }
+  }
+}