@port60/template-kit 0.1.0

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

@@ -0,0 +1,558 @@
+{
+ "description": "The content-section catalogue — the closed set of section types a page may hold and a template may render. Section type = content KIND (coarse); layout/variant is the template's job. Additive-only: types and fields are added, never removed or re-shaped, within a contract major. Every section is independently omittable — a template must degrade gracefully when any subset is absent.",
+ "sections": [
+  {
+   "type": "hero",
+   "label": "Hero banner",
+   "pages": [
+    "about"
+   ],
+   "description": "The page opener: a headline with an optional kicker and sanitised rich-text intro.",
+   "fields": [
+    {
+     "name": "eyebrow",
+     "kind": "text",
+     "required": false,
+     "description": "Short kicker above the headline."
+    },
+    {
+     "name": "title",
+     "kind": "text",
+     "required": true,
+     "description": "The headline."
+    },
+    {
+     "name": "bodyHtml",
+     "kind": "richtext",
+     "required": false,
+     "description": "Sanitised HTML intro — render with the raw filter."
+    }
+   ],
+   "minimal": {
+    "title": "Our story"
+   },
+   "sample": {
+    "eyebrow": "About us",
+    "title": "Generosity, put to work.",
+    "bodyHtml": "<p>We began in 2019 around a simple belief: small, regular acts of kindness, pooled together, change lives.</p>"
+   }
+  },
+  {
+   "type": "values",
+   "label": "Values / list",
+   "pages": [
+    "about"
+   ],
+   "description": "A set of principles shown as cards or a numbered list, per the template.",
+   "fields": [
+    {
+     "name": "eyebrow",
+     "kind": "text",
+     "required": false,
+     "description": "Short kicker above the heading."
+    },
+    {
+     "name": "heading",
+     "kind": "text",
+     "required": false,
+     "description": "The section heading."
+    },
+    {
+     "name": "items",
+     "kind": "items",
+     "required": true,
+     "description": "The value entries.",
+     "itemFields": [
+      {
+       "name": "title",
+       "kind": "text",
+       "required": true,
+       "description": "The value's name."
+      },
+      {
+       "name": "description",
+       "kind": "text",
+       "required": true,
+       "description": "One sentence describing it."
+      },
+      {
+       "name": "icon",
+       "kind": "icon",
+       "required": false,
+       "description": "Optional emoji/icon."
+      }
+     ]
+    }
+   ],
+   "minimal": {
+    "items": [
+     {
+      "title": "Transparency",
+      "description": "Every pound is tracked and reported."
+     }
+    ]
+   },
+   "sample": {
+    "eyebrow": "What we stand for",
+    "heading": "Our values",
+    "items": [
+     {
+      "title": "Transparency",
+      "description": "Every pound is tracked and reported."
+     },
+     {
+      "title": "Dignity",
+      "description": "We work alongside communities, not for them."
+     },
+     {
+      "title": "Impact",
+      "description": "We fund what works and measure the difference."
+     }
+    ]
+   }
+  },
+  {
+   "type": "cta",
+   "label": "Call to action",
+   "pages": [
+    "home",
+    "about"
+   ],
+   "description": "A closing band: heading, optional line, one button.",
+   "fields": [
+    {
+     "name": "heading",
+     "kind": "text",
+     "required": true,
+     "description": "The band heading."
+    },
+    {
+     "name": "text",
+     "kind": "text",
+     "required": false,
+     "description": "A supporting line."
+    },
+    {
+     "name": "buttonLabel",
+     "kind": "text",
+     "required": true,
+     "description": "The button's label."
+    },
+    {
+     "name": "buttonHref",
+     "kind": "url",
+     "required": true,
+     "description": "The button's destination (scheme-guarded on save)."
+    }
+   ],
+   "minimal": {
+    "heading": "Ready to help?",
+    "buttonLabel": "Donate",
+    "buttonHref": "/donate"
+   },
+   "sample": {
+    "heading": "Ready to help?",
+    "text": "It takes less than a minute.",
+    "buttonLabel": "Donate now",
+    "buttonHref": "/#donate"
+   }
+  },
+  {
+   "type": "homeHero",
+   "label": "Home hero",
+   "pages": [
+    "home"
+   ],
+   "description": "The home opener. EVERY field optional: eyebrow/title derive from branding when absent, the lead OMITS when absent (never a fabricated placeholder), buttons fall back to platform defaults.",
+   "fields": [
+    {
+     "name": "eyebrow",
+     "kind": "text",
+     "required": false,
+     "description": "Defaults to the charity's name."
+    },
+    {
+     "name": "title",
+     "kind": "text",
+     "required": false,
+     "description": "Defaults to the charity's tagline."
+    },
+    {
+     "name": "lead",
+     "kind": "text",
+     "required": false,
+     "description": "A lead paragraph; omitted entirely when blank."
+    },
+    {
+     "name": "primaryLabel",
+     "kind": "text",
+     "required": false,
+     "description": "Main button label (default: Donate now)."
+    },
+    {
+     "name": "primaryHref",
+     "kind": "url",
+     "required": false,
+     "description": "Main button link (default: #donate)."
+    },
+    {
+     "name": "secondaryLabel",
+     "kind": "text",
+     "required": false,
+     "description": "Second button label (default: Our story)."
+    },
+    {
+     "name": "secondaryHref",
+     "kind": "url",
+     "required": false,
+     "description": "Second button link (default: /about)."
+    },
+    {
+     "name": "givingStyle",
+     "kind": "select",
+     "required": false,
+     "options": [
+      "form",
+      "button"
+     ],
+     "description": "How this hero offers giving: 'form' (default) places the donation widget beside the copy; 'button' renders copy only — the primary button becomes the giving path (defaulting to /donate). Templates MUST render both."
+    },
+    {
+     "name": "imageUrl",
+     "kind": "image",
+     "required": false,
+     "description": "Background photograph for the hero (uploaded through the platform pipeline). The template lays a dark overlay under the headline; omit for the flat colour hero."
+    }
+   ],
+   "minimal": {},
+   "sample": {
+    "lead": "We turn everyday generosity into practical help for the families who need it most.",
+    "givingStyle": "button"
+   }
+  },
+  {
+   "type": "impact",
+   "label": "Impact cards",
+   "pages": [
+    "home"
+   ],
+   "description": "What gifts make possible — optional intro plus icon/title/description cards. Claims must be truthful for the tenant.",
+   "fields": [
+    {
+     "name": "eyebrow",
+     "kind": "text",
+     "required": false,
+     "description": "Short kicker."
+    },
+    {
+     "name": "heading",
+     "kind": "text",
+     "required": false,
+     "description": "The section heading."
+    },
+    {
+     "name": "text",
+     "kind": "text",
+     "required": false,
+     "description": "An intro line."
+    },
+    {
+     "name": "items",
+     "kind": "items",
+     "required": true,
+     "description": "The impact cards.",
+     "itemFields": [
+      {
+       "name": "imageUrl",
+       "kind": "image",
+       "required": false,
+       "description": "Card image (uploaded through the platform pipeline). Preferred over icon."
+      },
+      {
+       "name": "icon",
+       "kind": "icon",
+       "required": false,
+       "description": "Legacy emoji/icon — superseded by imageUrl; render it only when imageUrl is absent."
+      },
+      {
+       "name": "title",
+       "kind": "text",
+       "required": true,
+       "description": "The card title."
+      },
+      {
+       "name": "description",
+       "kind": "text",
+       "required": true,
+       "description": "One sentence describing it."
+      }
+     ]
+    }
+   ],
+   "minimal": {
+    "items": [
+     {
+      "title": "Warm meals",
+      "description": "Hot meals served at a community kitchen."
+     }
+    ]
+   },
+   "sample": {
+    "eyebrow": "Where your gift goes",
+    "heading": "Real help, made of small acts",
+    "items": [
+     {
+      "imageUrl": "https://assets.example/impact-water.jpg",
+      "title": "£10 · Clean water",
+      "description": "Safe drinking water for a family for a whole month."
+     },
+     {
+      "icon": "🍲",
+      "title": "£25 · Warm meals",
+      "description": "Fifteen hot meals served at a local community kitchen."
+     },
+     {
+      "title": "£50 · School kit",
+      "description": "Books and supplies for two children for a full term."
+     }
+    ]
+   }
+  },
+  {
+   "type": "whatsOn",
+   "label": "What's-on strip",
+   "pages": [
+    "home"
+   ],
+   "kind": "widget",
+   "island": "whats_on_strip",
+   "description": "Widget section — positions the what's-on strip of info events. No authorable content.",
+   "fields": [],
+   "minimal": {},
+   "sample": {}
+  },
+  {
+   "type": "events",
+   "label": "Events carousel",
+   "pages": [
+    "home"
+   ],
+   "kind": "widget",
+   "island": "events_carousel",
+   "description": "Widget section — positions the ticketed-events carousel. No authorable content.",
+   "fields": [],
+   "minimal": {},
+   "sample": {}
+  },
+  {
+   "type": "articles",
+   "label": "Latest articles",
+   "pages": [
+    "home"
+   ],
+   "kind": "widget",
+   "island": "latest_articles",
+   "description": "Widget section — positions the latest-articles strip. No authorable content.",
+   "fields": [],
+   "minimal": {},
+   "sample": {}
+  },
+  {
+   "type": "emergency",
+   "label": "Emergency appeal strip",
+   "pages": [
+    "home"
+   ],
+   "description": "A high-urgency full-width strip — one headline, an optional line, one action. For live emergencies and time-critical appeals.",
+   "fields": [
+    {
+     "name": "heading",
+     "kind": "text",
+     "required": true,
+     "description": "The urgent headline."
+    },
+    {
+     "name": "text",
+     "kind": "text",
+     "required": false,
+     "description": "One supporting line."
+    },
+    {
+     "name": "buttonLabel",
+     "kind": "text",
+     "required": false,
+     "description": "Action label (default: Donate now)."
+    },
+    {
+     "name": "buttonHref",
+     "kind": "url",
+     "required": false,
+     "description": "Action link (default: /donate). Scheme-guarded on save."
+    }
+   ],
+   "minimal": {
+    "heading": "Emergency appeal"
+   },
+   "sample": {
+    "heading": "Gaza emergency appeal",
+    "text": "Families need food, water and shelter right now.",
+    "buttonLabel": "Give emergency aid",
+    "buttonHref": "/donate"
+   }
+  },
+  {
+   "type": "stats",
+   "label": "Stats band",
+   "pages": [
+    "home"
+   ],
+   "description": "Big headline numbers — the at-a-glance impact band. Values are author-entered text (write them exactly as they should read).",
+   "fields": [
+    {
+     "name": "eyebrow",
+     "kind": "text",
+     "required": false,
+     "description": "Short kicker."
+    },
+    {
+     "name": "heading",
+     "kind": "text",
+     "required": false,
+     "description": "The band heading."
+    },
+    {
+     "name": "items",
+     "kind": "items",
+     "required": true,
+     "description": "The stat entries.",
+     "itemFields": [
+      {
+       "name": "value",
+       "kind": "text",
+       "required": true,
+       "description": "The number, as it should read (e.g. 12,000 or 98%)."
+      },
+      {
+       "name": "label",
+       "kind": "text",
+       "required": true,
+       "description": "What it counts (e.g. meals served)."
+      }
+     ]
+    }
+   ],
+   "minimal": {
+    "items": [
+     {
+      "value": "1,200",
+      "label": "meals served"
+     }
+    ]
+   },
+   "sample": {
+    "eyebrow": "Last year",
+    "heading": "What your giving did",
+    "items": [
+     {
+      "value": "12,400",
+      "label": "hot meals served"
+     },
+     {
+      "value": "3,100",
+      "label": "families supported"
+     },
+     {
+      "value": "98p",
+      "label": "of every pound to the cause"
+     }
+    ]
+   }
+  },
+  {
+   "type": "appealGrid",
+   "label": "Appeal cards",
+   "pages": [
+    "home"
+   ],
+   "description": "A grid of appeal/campaign cards — image, title, a line, and a per-card action.",
+   "fields": [
+    {
+     "name": "eyebrow",
+     "kind": "text",
+     "required": false,
+     "description": "Short kicker."
+    },
+    {
+     "name": "heading",
+     "kind": "text",
+     "required": false,
+     "description": "The section heading."
+    },
+    {
+     "name": "items",
+     "kind": "items",
+     "required": true,
+     "description": "The appeal cards.",
+     "itemFields": [
+      {
+       "name": "imageUrl",
+       "kind": "image",
+       "required": false,
+       "description": "Card photograph (uploaded through the platform pipeline)."
+      },
+      {
+       "name": "title",
+       "kind": "text",
+       "required": true,
+       "description": "The appeal's name."
+      },
+      {
+       "name": "text",
+       "kind": "text",
+       "required": true,
+       "description": "One sentence on what it funds."
+      },
+      {
+       "name": "buttonLabel",
+       "kind": "text",
+       "required": false,
+       "description": "Card action label (default: Donate)."
+      },
+      {
+       "name": "buttonHref",
+       "kind": "url",
+       "required": false,
+       "description": "Card action link (default: /donate). Scheme-guarded on save."
+      }
+     ]
+    }
+   ],
+   "minimal": {
+    "items": [
+     {
+      "title": "Winter appeal",
+      "text": "Warm meals through the coldest months."
+     }
+    ]
+   },
+   "sample": {
+    "eyebrow": "Our appeals",
+    "heading": "Where help is needed most",
+    "items": [
+     {
+      "title": "Winter appeal",
+      "text": "Warm meals and heating grants through the coldest months.",
+      "buttonLabel": "Support winter",
+      "buttonHref": "/donate"
+     },
+     {
+      "title": "Clean water",
+      "text": "Wells and filtration for three villages.",
+      "buttonLabel": "Give water",
+      "buttonHref": "/donate"
+     }
+    ]
+   }
+  }
+ ]
+}

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

@@ -0,0 +1,26 @@
+{
+  "description": "The CSS custom-property contract — the theming tokens the platform base declares and every island/page consumes. A template overrides them via :root:root in its theme.css. Additive-only: tokens are never removed or repurposed within a contract major.",
+  "tokens": [
+    { "name": "--bg", "description": "Page background." },
+    { "name": "--bg-tint", "description": "Subtle tinted background (footer, wells)." },
+    { "name": "--surface", "description": "Card/panel surface." },
+    { "name": "--ink", "description": "Primary text colour." },
+    { "name": "--muted", "description": "Secondary text colour." },
+    { "name": "--primary", "description": "Brand primary (progress, links, selected states)." },
+    { "name": "--primary-strong", "description": "Darker primary (hover/emphasis)." },
+    { "name": "--primary-soft", "description": "Translucent primary wash (selected fills, chips)." },
+    { "name": "--accent", "description": "Action accent (the donate CTA family)." },
+    { "name": "--accent-strong", "description": "Darker accent." },
+    { "name": "--gold", "description": "Highlight tint (marks, ratings)." },
+    { "name": "--line", "description": "Hairline borders." },
+    { "name": "--line-strong", "description": "Emphasised borders (selected, focus)." },
+    { "name": "--danger", "description": "Errors and destructive affordances." },
+    { "name": "--cta-hover", "description": "The donate-button hover 'go' colour." },
+    { "name": "--cta-hover-strong", "description": "Darker CTA hover." },
+    { "name": "--shadow-sm", "description": "Small elevation shadow." },
+    { "name": "--shadow", "description": "Large elevation shadow." },
+    { "name": "--radius", "description": "Large corner radius (cards, bands)." },
+    { "name": "--radius-sm", "description": "Small corner radius (inputs, chips)." },
+    { "name": "--container", "description": "Max content width." }
+  ]
+}

package/src/vendor/engine/budgets.mjs

@@ -0,0 +1,14 @@
+// LiquidJS DoS budgets — ONE definition for the production engine, the validator and the studio
+// preview, so "validated ⇒ renders in production" includes the resource ceiling. Third-party
+// templates run in the shared SSR process (developer program T1.3): without these, an untrusted
+// `{% for %}`/`{% capture %}` burns CPU/memory for every tenant on the box. The numbers are far
+// above anything a legitimate template needs (the largest internal artifact parses ~80KB and
+// renders in single-digit ms) and far below what hurts the process.
+export const LIQUID_BUDGETS = {
+  /** Max characters parsed per parse() call (dialect docs: a typical PC handles 1e8). */
+  parseLimit: 1e6,
+  /** Max wall-clock ms per render() call. */
+  renderLimit: 1000,
+  /** Max object creations per render (arrays, concats, strftime …). */
+  memoryLimit: 5e7
+};

package/src/vendor/engine/dialect.mjs

@@ -0,0 +1,77 @@
+// Applies the Port60 dialect (contract/v1/dialect.json) to a LiquidJS instance. Plain JS on purpose:
+// this exact module is imported by BOTH the rendering engine (Vite-bundled into charity-site) and the
+// Node conformance validator (scripts/validate-template.mjs) — one enforcement implementation, so the
+// validator can never disagree with production rendering. The dialect object is passed IN (parsed
+// JSON); this module does no file loading.
+
+/** Marker protocol for island placement: the island tag emits these; the renderer splits on them. */
+export const ISLAND_MARK_START = '\u0000P60_ISLAND:';
+export const ISLAND_MARK_END = '\u0000';
+
+/** The layout's {% content %} slot rides the island marker protocol under a reserved name — the
+ *  slash makes collision with registry island names (snake_case words) impossible. */
+export const CONTENT_SLOT = 'P60/content';
+
+/**
+ * Restrict a Liquid instance to the dialect: excluded tags become parse-time errors, excluded
+ * filters become render-time errors (unknown filters already throw via strictFilters), and the
+ * {% island %} tag is registered. `islandNames` is the platform island registry (a Set of names);
+ * an unknown island renders to nothing (the validator rejects it at publish time).
+ */
+export function configureDialect(liquid, dialect, islandNames) {
+  for (const tag of dialect.excluded?.tags ?? []) {
+    liquid.registerTag(tag, {
+      parse() {
+        throw new Error(`The '${tag}' tag is not part of the Port60 dialect (${dialect.format}).`);
+      },
+      render() {
+        return '';
+      }
+    });
+  }
+  // Filters LiquidJS ships beyond our whitelist (e.g. its non-standard json/inspect debug filters).
+  const allowed = new Set(dialect.filters);
+  for (const name of ['json', 'inspect', 'to_integer', 'normalize_whitespace', 'find', 'find_exp', 'group_by', 'group_by_exp', 'where_exp', 'sum']) {
+    if (!allowed.has(name)) {
+      liquid.registerFilter(name, () => {
+        throw new Error(`The '${name}' filter is not part of the Port60 dialect (${dialect.format}).`);
+      });
+    }
+  }
+  liquid.registerTag('island', {
+    parse(token) {
+      this.args = token.args;
+    },
+    async render(ctx) {
+      const name = String(await this.liquid.evalValue(this.args, ctx));
+      if (!islandNames.has(name)) {
+        return ''; // unknown island — omitted at render; rejected at publish by the validator
+      }
+      return `${ISLAND_MARK_START}${name}${ISLAND_MARK_END}`;
+    }
+  });
+  // {% content %} — the layout's page slot (contract v1, roadmap 8.2). Registered everywhere; a
+  // section that emits it is rejected by the validator and stripped by the section renderer.
+  liquid.registerTag('content', {
+    parse() {},
+    render() {
+      return `${ISLAND_MARK_START}${CONTENT_SLOT}${ISLAND_MARK_END}`;
+    }
+  });
+}
+
+/** Split rendered output into HTML fragments and island mount points. */
+export function splitIslandParts(html) {
+  const parts = [];
+  const pieces = html.split(ISLAND_MARK_START);
+  parts.push({ html: pieces[0] ?? '' });
+  for (const piece of pieces.slice(1)) {
+    const end = piece.indexOf(ISLAND_MARK_END);
+    if (end === -1) {
+      parts.push({ html: piece });
+      continue;
+    }
+    parts.push({ island: piece.slice(0, end) }, { html: piece.slice(end + ISLAND_MARK_END.length) });
+  }
+  return parts;
+}