@port60/template-kit 1.2.0 → 1.3.0

package/README.md

@@ -50,11 +50,56 @@ See the [AI quickstart](https://developers.port60.com/guides/ai-quickstart/).
 
 ## The contract
 
-Kit 1.2.0 authors **port60-liquid@2**, content model **2.0**, using the contract under
+Kit 1.3.0 authors **port60-liquid@2**, content model **2.0**, using the contract under
 `src/vendor/contract/v2`. Collection envelopes, independent header/footer navigation,
 resolved actions and page-scoped sections are explicit. V1 sources need a deliberate migration,
 not a manifest-only relabel. Historical v1 contracts remain frozen for existing platform pins.
 
+### Editor design flexibility in 1.3.0
+
+The editor offers only controls declared by the exact selected template version. The v2
+presentation registry in `src/vendor/contract/v2/presentation.json` describes the bounded
+choices and reset semantics, not evidence that every template implements each choice.
+
+- `supports.sectionPresentation` can declare per-section heading size, vertical spacing,
+  coordinated colour treatments, photo-only Home hero overlays and About introduction layouts.
+  Keep permanent hooks on the actual heading or natural section root, with token CSS scoped
+  to the control's permitted properties. Preserve inherited defaults, Looks, content and islands.
+  An absent saved key inherits; reset removes the override. Unsupported stored choices stay
+  stored but do not enter the rendering projection.
+- About introductions can independently declare `supports.sectionFields.hero` photograph and
+  alt-text fields, optionally with Fill/Show whole framing. Layout choices require those fields
+  and are logical `image-start`, `image-end` or `stacked` compositions. No photo means the
+  existing no-photo design, never a borrowed Home hero image or empty column. Reset restores
+  the author's framing, which need not match explicit Show whole.
+- The v2 `colour_roles` filter adds bounded semantic paint roles to platform-sanitised rich
+  text. Use `{{ section.bodyHtml | colour_roles | raw }}` consistently; it is not a sanitiser
+  or permission to render untrusted HTML. Colour controls cannot change geometry or content.
+- Existing theme settings may use `group: "header"` or `group: "footer"` when shared layout is
+  supported. These remain website-wide settings, with authored choices and defaults. Add section
+  uses existing exact section/layout declarations, not arbitrary presets or nested blocks.
+- A v2 Impact map placement requires an explicit `section.mapSlug`. Missing, cleared or
+  unavailable selections show no replacement map. Custom preview content must pair that slug
+  with the same `impactMap.slug`; historical v1 behaviour is unchanged.
+
+The scaffold demonstrates its own supported heading, spacing, colour and About-photo/layout
+choices without advertising controls on unsuitable island surfaces. Structural validation is
+not computed browser proof: verify every offered choice and reset across Looks, widths, sparse
+content, keyboard and no-JavaScript states before declaring support.
+
+Deploy the compatible platform first, publish this matching kit, then validate and publish new
+immutable template versions using the registry package. Existing pins do not upgrade themselves.
+See the [section authoring guide](https://developers.port60.com/guides/sections-and-data/) and
+generated AGENTS.md/CLAUDE.md for the detailed markup, CSS and acceptance boundaries.
+
+### Photo-only hero playback in 1.2.1
+
+The compatible host supplies `.hero-playback` on the `hero_carousel` island. Photo-only
+templates may hide the optional dots and reveal playback on hover or keyboard focus,
+while retaining a reachable control on touch devices. The preview supplies inactive
+geometry only. Campaign/content carousel controls are unchanged. Deploy the compatible
+host before publishing templates that depend on this control.
+
 ### Optional editor controls in 1.2.0
 
 The editor only offers controls supported by the exact selected template version. Declare

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@port60/template-kit",
-  "version": "1.2.0",
+  "version": "1.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/commands/create.mjs

@@ -75,6 +75,17 @@ Start with \`npm install\`, then:
 **Working with an AI agent?** Point it at this directory, \`AGENTS.md\` (and \`CLAUDE.md\`)
 brief it on the contract, the rules and the validate loop.
 
+Optional heading sizing and section spacing are independent per section: declare only tested
+choices in \`supports.sectionPresentation\`. Keep \`data-p60-heading-scale\` on the actual
+heading and \`data-p60-section-spacing\` on the natural outer section root, including when
+the heading is hidden. Hooks stay permanently present and empty during inheritance. Define
+responsive font sizes or block-axis root padding in CSS. Never change horizontal gutters,
+card gaps, heights or island internals for spacing. An absent preference inherits;
+reset removes the saved choice. Do not accept arbitrary CSS or numeric sizes. The kit proves
+contract structure, while browser checks must prove visible effects and safe layouts.
+See https://developers.port60.com/guides/sections-and-data/#bounded-heading-size and the
+machine-readable https://developers.port60.com/schemas/template-presentation-v2.json registry.
+
 Docs: https://developers.port60.com
 `);
 

package/src/lib/agentsMd.mjs

@@ -96,11 +96,187 @@ unchanged surrounding content, reset and mobile; computed text-align alone is no
 This capability needs a coordinated host/kit release; keep existing published dependency pins
 until that supporting kit version is available.
 
+## Bounded section presentation
+
+The presentation.json registry defines platform-owned controls, value choices, reset addresses
+and targets. It is published at https://developers.port60.com/schemas/template-presentation-v2.json
+and documented at /reference/presentation/. Read the exact installed kit's registry for authoring;
+the editor and a future agent must also check the exact selected template version's capabilities.
+Do not infer support from a similar template, the catalogue's latest release or visible markup.
+
+hero (About introduction) supports optional imageUrl and imageAlt only with the paired exact
+section declaration supports.sectionFields:{"hero":["imageUrl","imageAlt"]}. This is independent
+of layout choices: fixed compositions can support photographs without sectionLayout. Guard
+missing images and preserve the original no-photo design. Use data-p60-field="imageUrl" only
+on the actual img; escape imageAlt into alt, never an inline text marker. No placeholder,
+invented photograph or borrowed Home hero photo is allowed. Unsafe or unsupported saved image
+addresses stay stored but are omitted from rendering. The host accepts bounded root-relative
+or HTTP(S) addresses, never credentials, whitespace, controls or backslashes.
+
+Optional third field photoFraming in supports.sectionFields.hero offers fill/whole for the
+Introduction photo, saved at section.content.photoFraming, never presentation.photoFraming.
+Absent/reset inherits the author's composition, which may crop. Explicit whole shows the
+uncropped natural image: width100%, heightauto, no blanket heightcap.
+Keep data-p60-photo-framing="{{ section.photoFraming }}" on the actual marked img, empty when
+inherited. Exact img token rules allow only object-fit:cover and aspect-ratio:1/1,4/3,3/2,16/9,2/1
+for fill, or object-fit:contain and aspect-ratio:auto for whole. An optional root tag/classes
+prefix and flat media/container conditions are allowed. Never change width, copy, grid, source,
+alt or wrappers via framing. Prove actual crop vs natural whole in a browser with landscape,
+portrait, square and panorama inputs; verify selector specificity does not mask the control.
+The editor patches the existing image, then reconciles the section without refetching the photo
+or navigating. Home hero framing and its default remain independent and unchanged.
+
+sectionLayout is a per-section capability with image-start, image-end and stacked choices.
+It is not a template-wide switch. Its hero target requires the independent photograph pair
+above. The scaffold declares both; check the exact installed kit before authoring and do not
+infer support from the registry alone. The layout proof preserves the natural root, unchanged
+DOM order and separate frame/media/content roles.
+Token CSS must be gated by data-p60-layout-has-media and may change only bounded grid tracks
+and media/content grid-row/grid-column. No default token rule, arbitrary descendants, extra
+containers, spacing, sizing, paint or platform islands. Start/end follow site direction.
+Author opt-in needs exact default/reset equality, no-image safety and narrow single-column
+browser evidence across every Look, plus long/cleared copy and repeated-section isolation.
+
+headingScale and sectionSpacing are independent optional sectionPresentation controls. For example,
+supports.sectionPresentation:{"homeHero":{"headingScale":{"options":["compact","standard","large"],"default":"standard"},"sectionSpacing":{"options":["compact","standard","spacious"],"default":"standard"}}}.
+Every section key must appear in supports.sections. Declare only the two or three unique tokens
+you have implemented, from compact/standard/large for headingScale, or compact/standard/spacious
+for sectionSpacing; default must be one of those tokens. At least one control is required per
+declared section; a spacing-only section does not need a heading. No raw CSS,
+arbitrary numeric sizes, selectors or conditional expressions belong in this declaration.
+The author defines a safe responsive size for each token in theme.css, not the editor or host.
+
+imageOverlay is optional for homeHero only and requires supports.heroImagery:true. Declare
+two or three choices from subtle/standard/strong and the inherited default. Save it at
+section.content.presentation.imageOverlay; Liquid reads section.presentation.imageOverlay.
+Keep data-p60-image-overlay on the existing first outer hero root, empty when inherited.
+Mark photo-only wrappers data-p60-image-overlay-media and empty decorative overlay elements
+data-p60-image-overlay-layer. Token CSS may change only palette-derived background,
+background-image or background-color on marked layers, marked media ::before/::after, or
+the documented .hero-slide-scrim beneath marked media. Never affect image opacity, filters,
+geometry, copy, widgets or required text-readability scrims. Prove every static and carousel
+branch, Fill and Whole, every Look, zero/one/two/max photos and no JavaScript. Default and reset
+must match the original treatment; unsupported choices stay stored but do not render.
+The inherited default can omit a CSS override; other choices need real matching layer rules.
+Do not opt in a template whose branches cannot honour this. Starter deliberately remains
+unsupported. Read /guides/sections-and-data/#bounded-photo-overlays for the full proof boundary.
+
+colourTreatment is optional on non-island sections, excluding homeHero and impactMap. Declare
+two or three unique standard/soft/contrast choices and an inherited default in sectionPresentation.
+Persist only section.content.presentation.colourTreatment. Keep data-p60-colour-treatment on the
+single natural outer root, empty when inherited. Mark authored descendants with
+data-p60-colour-role="text|muted|accent|surface|border|link|button|secondary-button" (one role).
+Nondefault token CSS must pair root background-color and color, cover every rendered role and
+provide hover/focus-visible paint for link and button roles. Read existing Look palette variables;
+never redefine global or section custom properties. Only color, background-color, border-color,
+outline-color and text-decoration-color declarations are allowed; never use !important.
+Do not alter geometry, images,
+opacity, filters or islands. Never add padding/wrappers merely to make a colour control work.
+Default-token CSS is forbidden so inheritance/default/reset keep the exact original design.
+Use only flat natural root tag/classes + exact token, optionally followed by an owned role selector
+and hover/focus-visible/active. No nested selectors or at-rules inside a token block.
+Prove visible coordinated changes and contrast in every Look,
+width, interaction and no-JavaScript state; structural CSS checks alone cannot prove that.
+Read /guides/sections-and-data/#coordinated-section-colours for the full author contract.
+
+For a colour-capable About introduction, render section.bodyHtml | colour_roles | raw on every
+render, even inherited/default/reset. The v2 colour_roles filter decorates already-sanitised HTML:
+h2/h3/h4=text, p/ul/ol/li=muted, a=link, blockquote=surface, hr=border. Cover every rendered role
+and link hover/focus-visible. Inline emphasis inherits; images and islands are never decorated.
+The filter only adds fixed attributes, preserving text, hrefs, markup and text-align. It is not
+a sanitiser, never makes arbitrary HTML safe and does not bypass output escaping; raw stays explicit.
+Do not conditionally replace or rewrap the body when changing a colour choice.
+
+The saved address is section.content.presentation.headingScale. Inside Liquid the section variable
+is already that content, so read section.presentation.headingScale. An absent key inherits your
+existing CSS; reset removes it. Do not write a default into content or use a Liquid default filter.
+An explicit choice equal to the default remains explicit. Unsupported saved choices stay stored
+but are omitted from the render projection; switching templates must never erase them.
+
+Keep data-p60-heading-scale="{{ section.presentation.headingScale }}" permanently on each actual
+visible h1 to h6 section heading, including inherited headings without a field marker. The default
+hook is empty, not absent. Hidden headings may omit both the heading and hook. Never put this
+hook on a heading group, eyebrow, introduction, card title, action or platform island.
+Write token-specific font-size rules scoped to this hook and the relevant heading family.
+The declared default must have the same computed size as inheritance at each supported width
+and Look. Do not change copy, heading levels or unrelated markup in response to the token.
+
+For spacing, save section.content.presentation.sectionSpacing and read section.presentation.sectionSpacing
+in Liquid. Keep data-p60-section-spacing="{{ section.presentation.sectionSpacing }}" permanently on
+the natural outer section root, with an empty inherited hook, even when its heading is hidden.
+Never add a wrapper or put the hook on an inner container, heading, card or platform island.
+Token-specific CSS must target only that root and change only padding-block, padding-block-start,
+padding-block-end, padding-top or padding-bottom. Never use padding shorthand or change horizontal
+gutters, gaps, height, typography, descendants, pseudo-elements or island internals. Keep asymmetric
+top/bottom authored padding intact in the default. The declared default must compute identically
+to inheritance across widths and Looks. Omit spacing when the existing root has no suitable padding.
+Multiple outer roots, including ancillary behaviour siblings, are unsupported; preserve them and
+omit spacing rather than adding a wrapper. If clearing copy already omits the entire section,
+all spacing choices must preserve that omission, never create a section in response to the token.
+
+Kit preview, live preview and final rendering use the same accepted-value projection. The kit
+checks declarations, heading/root hooks, structural isolation and token-specific CSS declarations;
+it cannot prove computed CSS or visual quality. Check every option and reset in a browser across
+Looks, narrow/wide viewports, long/empty/inherited headings, repeated sections and no JavaScript.
+Prove visible size and spacing changes without overflow or changing unrelated layout. Respect reduced motion.
+Existing headingAlignment and showCollectionLink addresses are unchanged. This is a bounded
+presentation registry, not an arbitrary schema-driven editor or condition language.
+Ship the compatible host and kit before publishing newly versioned template declarations.
+
+The kit scaffold implements both controls on homeHero, hero, values and cta using its existing
+heading families and natural root padding. people, campaigns and impactMap remain excluded:
+their current utility or island roots have no suitable authored spacing surface. Preserve
+the whole-photo hero's zero top padding and the form variant's distinct bottom padding.
+
 Declare supports.fieldMarkers:true when showing authored field markers. A marker such as
 data-p60-field="title" or data-p60-field="items.{{ forloop.index0 }}.label" addresses only that
 section's content. Its node must contain exactly the authored value. Use a span when punctuation
 or generated text surrounds it. Never mark source records, generated labels or resolved actions.
 
+## Shared inspectors and section starting arrangements
+
+An implemented v2 settings.schema entry may use group:"header" or group:"footer" with
+supports.layout:true to appear in the matching shared website inspector. Historical v1 groups
+and artifacts remain unchanged. This is explicit exact-artifact metadata, not a guessed
+meaning of a key or template name. Existing color/select/toggle/font kinds, saved theme keys,
+body data-p60s-<key> attributes and --p60s-<key> variables are unchanged. Implement every option
+in the template's own CSS/markup; grouping alone does not create or prove a visual effect.
+Author bounded artwork sizes per design, not universal ranges; leave unsupported placements
+and choices absent.
+Logo sizing affects artwork, not unrelated type. Keep useful no-logo and empty-social states,
+menu destinations, identity, required legal links, consent and transactions. Verify every Look,
+responsive width, keyboard and no-JavaScript state, plus exact inherited/default/reset equality.
+
+Header/Footer controls share the existing theme working copy. Reset removes only the named
+override; Design bulk reset preserves shared groups and unsupported saved choices. Explicit
+defaults/false/blanks remain resettable. Looks still apply only their declared keys once.
+Brand and menu controls retain their existing source records and website draft/publication flow.
+Social addresses remain in Website settings with their own permissions and save lifecycle;
+presentation choices never create or delete addresses or automatically save their source.
+
+The visual Add section chooser uses exact supports.sections, allowed page types, compositions
+and the existing per-section sectionLayout declarations. Its diagrams are schematic guides,
+never screenshots or tenant content. There is no arbitrary presets schema or nested-container
+model. Add inserts one new stable-key section with empty content or only the chosen layout
+preference. Cancel has no effect; existing sections stay untouched. Template default omits the
+override. Do not seed sample text, images, statistics, action links or source records. A layout
+choice does not add a photograph, create an empty media column or change mobile ownership.
+
+V2 impactMap requires explicit section.mapSlug. Missing/null/blank means no selected map;
+never substitute the first public map. Unavailable, unpublished or archived selected maps have
+no replacement fallback. Historical v1/built-in default-map behaviour is unchanged. The v2 kit
+preview only shows its non-interactive map fixture when the selected slug matches that fixture:
+canonical sample mapSlug:"our-work" matches impactMap.slug:"our-work"; minimal stays empty.
+Custom demos must also explicitly select their matching fixture, never fetch tenant records.
+
+Connected source choices are bounded typed references, not duplicate content or free expressions.
+Map title/description/points stay in Maps; local introduction copy is only for templates that
+actually render it. Cause buttons retain causeId and the public address copied when chosen,
+not a live link expression following future slug changes. Missing sources keep saved choices
+and show a notice; never choose replacements or create source records to fill a layout.
+Use the compatible platform and kit before releasing newly versioned declarations. Source
+tests, browser acceptance, local deployment and remote release are separate gates.
+
 ## Navigation and actions
 
 Optional supports.navigationModes is {options:["simple","mega"],default:"mega"} (either supported

package/src/vendor/contract/v2/dialect.json

@@ -90,7 +90,8 @@
     "url_encode",
     "where",
     "t",
-    "local_date"
+    "local_date",
+    "colour_roles"
   ],
   "excluded": {
     "tags": [

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

@@ -106,7 +106,7 @@
       "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.",
+      "description": "Photo-only rotation for homeHero.images (2+): advances every ~6s, pauses on hover and offers persistent Pause/Resume. Keyboard navigation or focus outside that button stops rotation until explicitly resumed. Reduced motion prevents autoplay, including after a live preference change. Supports horizontal touch swipe and direction-aware arrow keys, Home/End, plus optional dot navigation. Templates may hide dots when the .hero-playback control exists. They may reveal playback on photograph hover and keyboard focus, but must retain keyboard reachability, a visible focus indicator and a control that is available without hover on touch devices. This is separate from campaign/content carousels. The platform owns motion; the template styles the frame and the empty .hero-slide-scrim tonal layer using its palette. Fewer than 2 images render nothing: the template owns single/no-image states.",
       "params": [],
       "stylingApi": [
         ".hero-carousel",
@@ -117,7 +117,8 @@
         ".hero-slide-scrim",
         ".hero-dots",
         ".hero-dot",
-        ".hero-dot--active"
+        ".hero-dot--active",
+        ".hero-playback"
       ]
     },
     {

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

@@ -192,6 +192,75 @@
           "description": "True when the sections mark which node shows which field with data-p60-field, so the editor can put the caret on the page instead of in a side panel. The address is inside that section's own content: data-p60-field=\"title\", or data-p60-field=\"items.{{ forloop.index0 }}.label\" for an entry in a list. Purely additive: the attribute is markup, the contract is untouched, and a template that marks nothing keeps the section-level editor. The validator reads the marks from the source and warns on any that does not name a field of that section. Missing or false leaves this exact template version editing in the panel.",
           "$comment": "Follows the navigationHighlights pattern: declared honesty, proven by the validator."
         },
+        "sectionFields": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "hero": { "type": "array", "minItems": 2, "maxItems": 3, "uniqueItems": true, "items": { "enum": ["imageUrl", "imageAlt", "photoFraming"] }, "allOf": [{ "contains": { "const": "imageUrl" } }, { "contains": { "const": "imageAlt" } }] }
+          },
+          "description": "Per-section opt-in to optional authored fields in this exact template version. The initial capability is the About introduction photograph: hero must also occur in supports.sections, and imageUrl/imageAlt are declared together. Optional photoFraming adds fill/whole on that photo; absent/reset inherits the author's composition while explicit whole shows the uncropped natural ratio. A fixed-layout photograph can be supported without sectionLayout. Missing support keeps saved photo fields but omits them from rendering and offers no new image picker. Validation proves supplied source/alt, no-photo omission, bounded framing and section ownership."
+        },
+        "sectionPresentation": {
+          "type": "object",
+          "maxProperties": 16,
+          "propertyNames": { "enum": ["hero", "values", "cta", "homeHero", "impact", "events", "articles", "campaigns", "emergency", "stats", "appealGrid", "services", "documents", "people", "impactMap", "courses"] },
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "minProperties": 1,
+            "properties": {
+              "sectionLayout": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["options", "default"],
+                "properties": {
+                  "options": { "type": "array", "minItems": 2, "maxItems": 3, "uniqueItems": true, "items": { "enum": ["image-start", "image-end", "stacked"] } },
+                  "default": { "enum": ["image-start", "image-end", "stacked"] }
+                },
+                "description": "Per-section author opt-in for an About introduction with optional authored imagery. Start/end follow site direction. Permanent data-p60-section-layout on the single natural root, with data-p60-layout-has-media only when the photo exists and explicit frame/media/content roles. Token CSS changes only bounded grid tracks and slot placement, never copy, DOM order, imagery, gutters, typography or platform islands. Default/reset keeps inherited styling. Every narrow-screen choice retains authored single-column stacking."
+              },
+              "colourTreatment": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["options", "default"],
+                "properties": {
+                  "options": { "type": "array", "minItems": 2, "maxItems": 3, "uniqueItems": true, "items": { "enum": ["standard", "soft", "contrast"] } },
+                  "default": { "enum": ["standard", "soft", "contrast"] }
+                },
+                "description": "Coordinated section paint within the selected Look. Requires a permanent data-p60-colour-treatment on the single natural section root and bounded data-p60-colour-role descendants. Nondefault treatments coordinate root background/text and every marked role, including link/button hover and focus-visible. No shared palette rebinding, images, layout or platform islands. Home hero and impact maps are unsupported. Missing/reset preserves inherited styling."
+              },
+              "imageOverlay": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["options", "default"],
+                "properties": {
+                  "options": { "type": "array", "minItems": 2, "maxItems": 3, "uniqueItems": true, "items": { "enum": ["subtle", "standard", "strong"] } },
+                  "default": { "enum": ["subtle", "standard", "strong"] }
+                },
+                "description": "Home hero only. Safe palette-derived decorative photo treatment choices, independently proven for static and carousel imagery, Fill and Whole. Preserve required text-readability scrims. Missing/reset preserves inherited treatment; no source editing, image opacity or geometry changes."
+              },
+              "sectionSpacing": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["options", "default"],
+                "properties": {
+                  "options": { "type": "array", "minItems": 2, "maxItems": 3, "uniqueItems": true, "items": { "enum": ["compact", "standard", "spacious"] } },
+                  "default": { "enum": ["compact", "standard", "spacious"] }
+                }
+              },
+              "headingScale": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["options", "default"],
+                "properties": {
+                  "options": { "type": "array", "minItems": 2, "maxItems": 3, "uniqueItems": true, "items": { "enum": ["compact", "standard", "large"] } },
+                  "default": { "enum": ["compact", "standard", "large"] }
+                }
+              }
+            }
+          },
+          "description": "Exact-version opt-in to independent platform-owned section presentation controls. Every key must be in supports.sections and declare at least one known control. Each control's default must occur in its options and describe inherited responsive styling. Saved explicit choices are projected into section.presentation; absence inherits without writing defaults. headingScale requires a permanent data-p60-heading-scale hook on the actual heading and authored font-size CSS. sectionSpacing requires a permanent data-p60-section-spacing hook on the natural outer section root and authored block-axis padding CSS, even without a heading; never alter horizontal gutters, card gaps, heights or island internals. Missing declarations are unsupported. No arbitrary values, conditions or CSS selectors are accepted."
+        },
         "sectionHeadingAlignment": {
           "type": "object",
           "maxProperties": 16,
@@ -413,9 +482,11 @@
                 "type": "string",
                 "enum": [
                   "typography",
-                  "looks"
+                  "looks",
+                  "header",
+                  "footer"
                 ],
-                "description": "Where the admin surfaces this knob: 'typography' → the Typography section beside the font slots; 'looks' → the Looks section with the one-click bundles (colour schemes and accent dials belong there, and ungrouped color knobs plus a knob keyed 'scheme' default there anyway); other ungrouped knobs render under Template options."
+                "description": "Where the admin surfaces this knob: typography, looks, or the shared header/footer inspector. Header and footer groups explicitly declare template-authored global chrome settings, not a new content source. Every option must have template-owned CSS or markup; omitted groups never imply support. Other ungrouped knobs render under Template options."
               },
               "weights": {
                 "type": "array",

package/src/vendor/contract/v2/presentation.json

@@ -0,0 +1,107 @@
+{
+  "version": 1,
+  "description": "Platform-owned presentation meanings. Templates declare supported choices; saved values remain tenant-owned. An absent override inherits the exact artifact's authored default. Hidden or unsupported values remain stored but are not projected into template rendering.",
+  "sectionTypes": ["hero", "values", "cta", "homeHero", "impact", "events", "articles", "campaigns", "emergency", "stats", "appealGrid", "services", "documents", "people", "impactMap", "courses"],
+  "legacySectionAliases": {"programmes": "services", "resources": "documents", "whatsOn": "events"},
+  "controls": {
+    "sectionLayout": {
+      "label": "Section layout",
+      "kind": "choice",
+      "scope": "section",
+      "sectionTypes": ["hero"],
+      "contentFields": {"imageUrl": "image", "imageAlt": "text"},
+      "address": ["presentation", "sectionLayout"],
+      "options": ["image-start", "image-end", "stacked"],
+      "labels": {"image-start": "Image at start", "image-end": "Image at end", "stacked": "Image above"},
+      "minimumOptions": 2,
+      "reset": "remove",
+      "target": "section-layout",
+      "responsive": "author-defined",
+      "attribute": "data-p60-section-layout",
+      "description": "Author-owned image/text layout for an explicitly supported About introduction. Start/end follow the site direction. Mark the single natural outer root and existing frame/media/content slots; token CSS changes only bounded grid tracks and slot placement when a photograph exists. Missing/reset preserves authored styling. Preserve copy, imagery, reading order, links, gutters and narrow-screen stacking; never invent absent media, add arbitrary containers or target platform islands. Every exact section declaration is independent; missing support is unsupported."
+    },
+    "colourTreatment": {
+      "label": "Colour treatment",
+      "kind": "choice",
+      "scope": "section",
+      "sectionTypes": ["hero", "values", "cta", "impact", "events", "articles", "campaigns", "emergency", "stats", "appealGrid", "services", "documents", "people", "courses"],
+      "address": ["presentation", "colourTreatment"],
+      "options": ["standard", "soft", "contrast"],
+      "labels": {"standard": "Standard", "soft": "Soft", "contrast": "Contrast"},
+      "minimumOptions": 2,
+      "reset": "remove",
+      "target": "section-colour-treatment",
+      "responsive": "author-defined",
+      "attribute": "data-p60-colour-treatment",
+      "description": "Coordinated author-owned section surface, copy, links and buttons within the selected Look. Missing/reset retains the original treatment. Mark the natural outer root and explicitly owned colour roles; token CSS changes paint only, never shared palette variables, imagery, layout or island internals. Home hero, impact maps and sections containing platform islands are not supported in this slice."
+    },
+    "headingScale": {
+      "label": "Heading size",
+      "kind": "choice",
+      "scope": "section",
+      "address": ["presentation", "headingScale"],
+      "options": ["compact", "standard", "large"],
+      "labels": {"compact": "Compact", "standard": "Standard", "large": "Large"},
+      "minimumOptions": 2,
+      "reset": "remove",
+      "target": "section-heading",
+      "responsive": "author-defined",
+      "attribute": "data-p60-heading-scale",
+      "description": "Changes only the actual section heading's responsive font size, never its heading level, eyebrow, body, cards, buttons or islands. Templates provide each size in their own CSS. The declared default describes inherited styling; it is not written into tenant content."
+    },
+    "sectionSpacing": {
+      "label": "Section spacing",
+      "kind": "choice",
+      "scope": "section",
+      "address": ["presentation", "sectionSpacing"],
+      "options": ["compact", "standard", "spacious"],
+      "labels": {"compact": "Compact", "standard": "Standard", "spacious": "Spacious"},
+      "minimumOptions": 2,
+      "reset": "remove",
+      "target": "section-root",
+      "responsive": "author-defined",
+      "attribute": "data-p60-section-spacing",
+      "description": "Changes only the natural outer section root's block-axis padding, never horizontal gutters, card gaps, heights or island internals. Templates provide each spacing in their own CSS. The declared default describes inherited styling; it is not written into tenant content. Keep the permanent hook even when the heading is hidden."
+    },
+    "imageOverlay": {
+      "label": "Photo overlay",
+      "kind": "choice",
+      "scope": "section",
+      "sectionTypes": ["homeHero"],
+      "requiresSupport": "heroImagery",
+      "address": ["presentation", "imageOverlay"],
+      "options": ["subtle", "standard", "strong"],
+      "labels": {"subtle": "Subtle", "standard": "Standard", "strong": "Strong"},
+      "minimumOptions": 2,
+      "reset": "remove",
+      "target": "section-image-treatment",
+      "responsive": "author-defined",
+      "attribute": "data-p60-image-overlay",
+      "description": "Changes only authored palette-derived decorative photo treatments in Home hero, never image opacity, source media, geometry, copy, widgets or a required readability scrim. Each exact artifact declares its safe choices and inherited default. Mark the existing photo wrapper with data-p60-image-overlay-media and empty decorative layers with data-p60-image-overlay-layer; token CSS may target those layers, marked wrapper pseudo-elements or the documented hero-slide-scrim. Missing and reset values preserve the authored treatment."
+    },
+    "headingAlignment": {
+      "label": "Desktop heading alignment",
+      "kind": "choice",
+      "scope": "section",
+      "address": ["headingAlignment"],
+      "options": ["start", "center", "end"],
+      "minimumOptions": 1,
+      "reset": "remove",
+      "target": "section-heading-and-eyebrow",
+      "responsive": "desktop-1024",
+      "attribute": "data-p60-heading-align",
+      "declaration": "sectionHeadingAlignment"
+    },
+    "showCollectionLink": {
+      "label": "Show collection link",
+      "kind": "toggle",
+      "scope": "section",
+      "address": ["showCollectionLink"],
+      "reset": "remove",
+      "target": "collection-link",
+      "responsive": "all",
+      "attribute": "data-p60-collection-link",
+      "declaration": "sectionCollectionLinkVisibility"
+    }
+  }
+}