@port60/template-kit 0.1.1 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@port60/template-kit",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Build Port60 site templates locally: scaffold, live-preview, validate against the platform contract, and package for studio upload. AI-agent ready — every scaffold ships AGENTS.md and validate emits machine-readable JSON.",
   "type": "module",
   "bin": {

package/src/lib/agentsMd.mjs

@@ -62,6 +62,12 @@ platform accepts it; if it fails here, the upload will fail identically.
 - Theme via CSS custom properties and the settings knobs you declare in
   \`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
+  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\`.
 - Fonts: only families from the platform font catalogue, declared with the weights you use.
 

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

@@ -90,6 +90,23 @@
     ".course-pay-panel",
     ".course-soldout-note"
    ]
+  },
+  {
+   "name": "hero_carousel",
+   "label": "Hero image carousel",
+   "status": "available",
+   "description": "Rotation for the home hero's photographs (homeHero.images, 2+): auto-advance every ~6s, pauses on hover/focus, honours prefers-reduced-motion (no auto-advance), swipe on touch, dot navigation. The platform owns the motion; the TEMPLATE owns the look — including the tonal treatment: every slide ships an empty .hero-slide-scrim layer over its image, and the template colours it from its OWN palette variables (a colour wash, a blend, a gradient) so any uploaded photo sits inside the template's tones. Renders nothing with fewer than 2 images — single-image and no-image states are the template's own renderer, not this island's.",
+   "params": [],
+   "stylingApi": [
+    ".hero-carousel",
+    ".hero-slides",
+    ".hero-slide",
+    ".hero-slide-img",
+    ".hero-slide-scrim",
+    ".hero-dots",
+    ".hero-dot",
+    ".hero-dot--active"
+   ]
   }
  ]
-}
+}

package/src/vendor/contract/v1/manifest.schema.json

@@ -70,6 +70,11 @@
           "type": "boolean",
           "default": false,
           "description": "True when the layout renders the `worship` context (the prayer/service-times rail). Declared honesty: the choosers badge worship-enabled tenants toward looks that show their times, and warn on looks that don't. Requires supports.layout; the layout must actually branch on `worship`."
+        },
+        "heroImagery": {
+          "type": "boolean",
+          "default": false,
+          "description": "True when the homeHero renderer displays the tenant's hero photographs (homeHero.images, legacy imageUrl) — always under a TREATMENT built from the template's own palette variables (scrim/tint/blend), never raw. Declared honesty, proven behaviourally at validation: the choosers badge photo-led tenants toward templates that show their images and warn on ones that won't. Requires the homeHero section among supports.sections."
         }
       }
     },

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

@@ -221,13 +221,56 @@
      "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."
+     "description": "Background photograph for the hero (uploaded through the platform pipeline). Superseded by `images` when that carries any entry — render imageUrl only when images is absent/empty. The template must TREAT the photo (scrim/tint from its own palette variables), never place it raw, and omit for its designed no-photo state."
+    },
+    {
+     "name": "images",
+     "kind": "items",
+     "required": false,
+     "description": "Hero photographs (0–6, uploaded through the platform pipeline). One = a main image; several = rotation material — a template with supports.heroImagery renders at least the first and MAY place the hero_carousel island (or a CSS scroll strip) for the rest. Like every field: absent means the template's designed no-photo state, never a placeholder.",
+     "itemFields": [
+      {
+       "name": "imageUrl",
+       "kind": "image",
+       "required": true,
+       "description": "The photograph."
+      },
+      {
+       "name": "alt",
+       "kind": "text",
+       "required": false,
+       "description": "Accessible description; empty renders as decorative (alt=\"\")."
+      },
+      {
+       "name": "focus",
+       "kind": "select",
+       "required": false,
+       "options": [
+        "centre",
+        "top",
+        "bottom",
+        "left",
+        "right"
+       ],
+       "description": "Which part of the photograph survives the fill-crop (templates render photos cover-style, so an aspect mismatch crops — this picks the slice that stays). Maps to background-position/object-position; absent means centre."
+      }
+     ]
     }
    ],
    "minimal": {},
    "sample": {
     "lead": "We turn everyday generosity into practical help for the families who need it most.",
-    "givingStyle": "button"
+    "givingStyle": "button",
+    "images": [
+     {
+      "imageUrl": "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 160 90'%3E%3Cdefs%3E%3ClinearGradient id='g' x1='0' y1='0' x2='1' y2='1'%3E%3Cstop offset='0' stop-color='%23355e4b'/%3E%3Cstop offset='1' stop-color='%23103528'/%3E%3C/linearGradient%3E%3C/defs%3E%3Crect width='160' height='90' fill='url(%23g)'/%3E%3Ccircle cx='118' cy='28' r='14' fill='%23baa769' opacity='.7'/%3E%3Ctext x='10' y='78' font-family='sans-serif' font-size='9' fill='%23ffffff' opacity='.75'%3EHero photo one%3C/text%3E%3C/svg%3E",
+      "alt": "Volunteers serving meals at dusk"
+     },
+     {
+      "imageUrl": "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 160 90'%3E%3Cdefs%3E%3ClinearGradient id='g' x1='0' y1='0' x2='1' y2='1'%3E%3Cstop offset='0' stop-color='%23445a78'/%3E%3Cstop offset='1' stop-color='%23141d2c'/%3E%3C/linearGradient%3E%3C/defs%3E%3Crect width='160' height='90' fill='url(%23g)'/%3E%3Ccircle cx='40' cy='30' r='12' fill='%23e8e2d4' opacity='.5'/%3E%3Ctext x='10' y='78' font-family='sans-serif' font-size='9' fill='%23ffffff' opacity='.75'%3EHero photo two%3C/text%3E%3C/svg%3E",
+      "alt": "The community hall on open day"
+     }
+    ]
    }
   },
   {

package/src/vendor/validator/validate.mjs

@@ -99,6 +99,9 @@ export async function validateArtifact(files) {
   const catalogueByType = new Map(sectionCatalogue.sections.map((s) => [s.type, s]));
   const declaredIslands = new Set(manifest?.supports?.islands ?? []);
   const placedIslands = new Set();
+  // heroImagery proof state (filled by the homeHero renders below).
+  let homeHeroMultiShows = null; // sample (several photos): probe in html OR hero_carousel placed
+  let homeHeroSingleShows = null; // single-photo variant: probe rendered directly
 
   // 2–4. Sections: catalogue membership, parse, fixture renders.
   for (const type of manifest?.supports?.sections ?? []) {
@@ -126,6 +129,21 @@ export async function validateArtifact(files) {
           section: fixture,
           brand: contextContract.fixtures.brand
         });
+        if (type === 'homeHero' && fixtureName === 'sample') {
+          const probe = 'Hero photo one';
+          homeHeroMultiShows = html.includes(probe)
+            || splitIslandParts(html).some((p) => p.island === 'hero_carousel');
+          // The single-photo path proven separately: same fixture, first photo only.
+          try {
+            const single = await liquid.render(parsed, {
+              section: { ...fixture, images: (fixture.images ?? []).slice(0, 1) },
+              brand: contextContract.fixtures.brand
+            });
+            homeHeroSingleShows = single.includes(probe);
+          } catch {
+            homeHeroSingleShows = false;
+          }
+        }
         for (const part of splitIslandParts(html)) {
           if (part.island === CONTENT_SLOT) {
             errors.push(`section '${type}': uses {% content %} — that tag is layout-only`);
@@ -139,6 +157,31 @@ export async function validateArtifact(files) {
     }
   }
 
+  // Hero-imagery honesty, checked BEHAVIOURALLY (the worship pattern). The homeHero sample
+  // fixture carries photographs whose data URIs embed a quote-free marker that survives HTML
+  // escaping, so "does the rendered hero display the tenant's photos?" is a substring check —
+  // and with several photos, placing the hero_carousel island IS displaying them (the island
+  // renders the slides at runtime). The single-photo path is proven separately: images[0] must
+  // appear directly. Declaration and behaviour must agree; the choosers badge photo-led tenants
+  // by supports.heroImagery. Legacy imageUrl-only renderers never match (the fixture's photos
+  // ride `images`), so they pass undeclared — they just don't earn the badge.
+  {
+    const declaresHero = manifest?.supports?.heroImagery === true;
+    if (declaresHero && !(manifest?.supports?.sections ?? []).includes('homeHero')) {
+      errors.push('manifest: supports.heroImagery requires the homeHero section — the photographs live on it');
+    } else if (homeHeroMultiShows !== null) {
+      if (declaresHero && !homeHeroMultiShows) {
+        errors.push('homeHero: manifest declares supports.heroImagery but the rendered section neither displays the images fixture nor places the hero_carousel island');
+      }
+      if (declaresHero && !homeHeroSingleShows) {
+        errors.push('homeHero: supports.heroImagery must render a SINGLE photograph directly (images[0], treated, never raw) — the carousel island only covers 2+');
+      }
+      if (!declaresHero && (homeHeroMultiShows || homeHeroSingleShows)) {
+        errors.push('homeHero: renders the hero photographs but the manifest does not declare supports.heroImagery — declare it so the choosers can badge it');
+      }
+    }
+  }
+
   // 7. Layout (when declared): parse + render the layout fixture + exactly one content slot.
   if (manifest?.supports?.worship && !manifest?.supports?.layout) {
     errors.push('manifest: supports.worship requires supports.layout — the worship rail is layout chrome');

package/starter/assets/theme.css

@@ -41,3 +41,75 @@ strong { color: var(--ink); }
 
 /* The one font slot — headings above already follow it; body text too. */
 body { font-family: ' IBM Plex Sans Arabic', var(--p60s-siteFont, 'Inter'), ui-sans-serif, system-ui, sans-serif; }
+
+/* ── Home hero (supports.heroImagery — the reference treatment) ─────────────────────────────
+   The no-photo state is a DESIGNED gradient (rule: derive or omit, never a placeholder image).
+   Photos get a scrim built from the palette itself via color-mix, so uploads tone into the
+   template — and any palette change re-tones them for free. Never place a hero photo raw. */
+.lq-homehero {
+  position: relative;
+  padding: 4.5rem 0;
+  background:
+    radial-gradient(720px 380px at 85% -10%, var(--primary-soft), transparent 60%),
+    linear-gradient(165deg, var(--bg-tint) 0%, var(--bg) 100%);
+}
+.lq-homehero--photo { background-size: cover; background-position: center; }
+.lq-homehero--photo::before {
+  content: '';
+  position: absolute;
+  inset: 0;
+  background: linear-gradient(
+    180deg,
+    color-mix(in srgb, var(--bg) 68%, transparent) 0%,
+    color-mix(in srgb, var(--bg) 38%, transparent) 50%,
+    color-mix(in srgb, var(--bg-tint) 72%, transparent) 100%
+  );
+}
+.lq-homehero > .container { position: relative; z-index: 1; }
+.lq-homehero-inner { display: grid; gap: 2.5rem; align-items: center; }
+@media (min-width: 900px) {
+  .lq-homehero-inner { grid-template-columns: 1.2fr 1fr; }
+}
+.lq-homehero-lead { color: var(--muted); max-width: 46ch; margin: 0.9rem 0 1.4rem; }
+.lq-homehero-actions { display: flex; gap: 0.8rem; flex-wrap: wrap; }
+
+/* The platform hero_carousel island, styled through its class API — the island owns motion
+   (auto-advance, swipe, reduced-motion), this owns the look. Each slide's .hero-slide-scrim is
+   the same palette treatment as a single photo. */
+.lq-homehero--carousel { overflow: hidden; }
+.lq-homehero--carousel .hero-carousel { position: absolute; inset: 0; z-index: 0; }
+.lq-homehero--carousel .hero-slides,
+.lq-homehero--carousel .hero-slide { position: absolute; inset: 0; }
+.lq-homehero--carousel .hero-slide { opacity: 0; transition: opacity 1s ease; }
+.lq-homehero--carousel .hero-slide--active { opacity: 1; }
+.lq-homehero--carousel .hero-slide-img { width: 100%; height: 100%; object-fit: cover; display: block; }
+.lq-homehero--carousel .hero-slide-scrim {
+  position: absolute;
+  inset: 0;
+  background: linear-gradient(
+    180deg,
+    color-mix(in srgb, var(--bg) 68%, transparent) 0%,
+    color-mix(in srgb, var(--bg) 38%, transparent) 50%,
+    color-mix(in srgb, var(--bg-tint) 72%, transparent) 100%
+  );
+}
+.lq-homehero--carousel .hero-dots {
+  position: absolute;
+  left: 0;
+  right: 0;
+  bottom: 0.8rem;
+  display: flex;
+  justify-content: center;
+  gap: 0.4rem;
+  z-index: 2;
+}
+.lq-homehero--carousel .hero-dot {
+  width: 9px;
+  height: 9px;
+  border-radius: 50%;
+  border: 1px solid var(--accent);
+  background: transparent;
+  padding: 0;
+  cursor: pointer;
+}
+.lq-homehero--carousel .hero-dot--active { background: var(--accent); }

package/starter/manifest.json

@@ -1,23 +1,27 @@
 {
  "name": "starter",
- "version": "1.2.0",
+ "version": "1.4.0",
  "format": "port60-liquid@1",
  "label": "Starter",
- "description": "The reference template for the Port60 dialect \u2014 the developer docs' worked example and the base to copy when building your own. 1.1.0 adds the layout slot: the template owns the header, navigation and footer chrome.",
+ "description": "The reference template for the Port60 dialect — the developer docs' worked example and the base to copy when building your own. 1.1.0 adds the layout slot: the template owns the header, navigation and footer chrome.",
  "supports": {
   "pages": [
+   "home",
    "about"
   ],
   "sections": [
+   "homeHero",
    "hero",
    "values",
    "cta"
   ],
   "islands": [
    "donation_widget",
-   "member_menu"
+   "member_menu",
+   "hero_carousel"
   ],
-  "layout": true
+  "layout": true,
+  "heroImagery": true
  },
  "settings": {
   "schema": [
@@ -36,5 +40,5 @@
    }
   ]
  },
- "changelog": "The reference font slot \u2014 one 'Site font' knob showing the var(--p60s-*) pattern."
+ "changelog": "Per-photo focus: choose which part of a hero photograph survives the fill-crop (centre/top/bottom/left/right) — panoramas and portraits stop cropping blind."
 }

package/starter/sections/homeHero.liquid

@@ -0,0 +1,51 @@
+{% comment %}
+  The home opener — and the REFERENCE IMPLEMENTATION of supports.heroImagery. Three rules worth
+  copying:
+
+  1. EVERY field is optional. Copy derives from brand (| default) or omits; no photos means the
+     designed gradient below — never a placeholder image.
+  2. Photos are NEVER placed raw. The .lq-homehero--photo treatment in theme.css lays a scrim
+     built from the palette variables (color-mix over var(--bg)/var(--primary)), so any uploaded
+     photograph is toned into the template. Tune the treatment, don't remove it.
+  3. Templates ship no JavaScript, so rotation is the PLATFORM's hero_carousel island: with two
+     or more photos, place it and style its documented classes (.hero-slide, .hero-slide-scrim,
+     .hero-dots) — the platform owns the motion, you own the look.
+{% endcomment %}
+{% assign heroCount = section.images | size %}
+{% if heroCount == 1 %}
+  {% assign heroPhoto = section.images.first.imageUrl %}
+{% elsif heroCount == 0 %}
+  {% assign heroPhoto = section.imageUrl %}
+{% endif %}
+{% assign heroFocus = 'center' %}
+{% if heroCount > 0 %}
+  {% case section.images.first.focus %}
+    {% when 'top' %}{% assign heroFocus = 'center top' %}
+    {% when 'bottom' %}{% assign heroFocus = 'center bottom' %}
+    {% when 'left' %}{% assign heroFocus = 'left center' %}
+    {% when 'right' %}{% assign heroFocus = 'right center' %}
+  {% endcase %}
+{% endif %}
+<section class="lq-homehero{% if heroPhoto %} lq-homehero--photo{% endif %}{% if heroCount > 1 %} lq-homehero--carousel{% endif %}"{% if heroPhoto %} style="background-image: url('{{ heroPhoto }}'); background-position: {{ heroFocus }}"{% endif %}>
+  {% if heroCount > 1 %}{% island 'hero_carousel' %}{% endif %}
+  <div class="container lq-homehero-inner">
+    <div>
+      <p class="lq-kicker">{{ section.eyebrow | default: brand.name }}</p>
+      <h1>{{ section.title | default: brand.tagline | default: brand.name }}</h1>
+      {% if section.lead %}<p class="lq-homehero-lead">{{ section.lead }}</p>{% endif %}
+      <div class="lq-homehero-actions">
+        {% if section.givingStyle == 'button' %}
+        <a class="button button-primary" href="{{ section.primaryHref | default: '/donate' }}">{{ section.primaryLabel | default: 'Donate now' }}</a>
+        {% else %}
+        <a class="button button-primary" href="#donate">{{ section.primaryLabel | default: 'Donate now' }}</a>
+        {% endif %}
+        <a class="button" href="{{ section.secondaryHref | default: '/about' }}">{{ section.secondaryLabel | default: 'Our story' }}</a>
+      </div>
+    </div>
+    {% unless section.givingStyle == 'button' %}
+    <aside id="donate">
+      {% island 'donation_widget' %}
+    </aside>
+    {% endunless %}
+  </div>
+</section>