@port60/template-kit 0.4.2 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@port60/template-kit",
-  "version": "0.4.2",
+  "version": "0.5.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

@@ -70,6 +70,9 @@ platform accepts it; if it fails here, the upload will fail identically.
   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.
+- \`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
+  measures their actual upload against it and advises. Advice, never enforcement.
 
 ## Which contract this is
 

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

@@ -0,0 +1,23 @@
+{
+ "description": "Platform imagery envelopes — ADVICE, never enforcement. Entity images (events, courses, articles) render on SEVERAL surfaces at once (cards, carousel slides, detail banners), including platform-owned components, so their guidance is platform-level: the envelope every surface can live with. Template-composed slots (the home hero) are different — their ideal is the TEMPLATE's own design call, declared per-template in manifest.imagery and surfaced beside the upload. Editors measure the actual upload against the relevant guidance and advise; the charity always decides.",
+ "entityImages": {
+  "eventPromo": {
+   "idealAspect": "3:2",
+   "aspectRange": ["4:3", "16:9"],
+   "minWidth": 1600,
+   "note": "One photo, several surfaces: the events card, the home carousel slide, and the event page banner — each crops differently, so keep the subject centred and avoid text baked into the image."
+  },
+  "courseImage": {
+   "idealAspect": "3:2",
+   "aspectRange": ["4:3", "16:9"],
+   "minWidth": 1600,
+   "note": "Renders as the course card and the course page opener — subject centred, no baked-in text."
+  },
+  "articleCover": {
+   "idealAspect": "16:9",
+   "aspectRange": ["3:2", "2:1"],
+   "minWidth": 1600,
+   "note": "The article card thumbnail and the article page cover — wide editorial shots sit best."
+  }
+ }
+}

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

@@ -78,6 +78,35 @@
         }
       }
     },
+    "imagery": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "The template's OWN image advice, surfaced beside uploads in the charity's editor — a design statement (what shape suits THIS composition), advisory only, never enforced. Entity images (events, courses, articles) are platform-scoped instead: see the contract's imagery.json envelopes.",
+      "properties": {
+        "hero": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["idealAspect", "minWidth"],
+          "properties": {
+            "idealAspect": {
+              "type": "string",
+              "pattern": "^\\d+:\\d+$",
+              "description": "The aspect this hero composes best with, e.g. \"16:9\"."
+            },
+            "minWidth": {
+              "type": "integer",
+              "minimum": 800,
+              "description": "Below this pixel width the photo may look soft full-bleed."
+            },
+            "note": {
+              "type": "string",
+              "maxLength": 240,
+              "description": "One human line of advice, e.g. how panoramas or portraits behave in this hero."
+            }
+          }
+        }
+      }
+    },
     "fonts": {
       "type": "array",
       "items": {

package/starter/manifest.json

@@ -1,6 +1,6 @@
 {
  "name": "starter",
- "version": "1.5.2",
+ "version": "1.5.3",
  "format": "port60-liquid@1",
  "label": "Starter",
  "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.",
@@ -40,5 +40,12 @@
    }
   ]
  },
- "changelog": "Vista + giving form: the donation widget returns to the right-hand column, riding over the photograph and continuing onto the gradient below it — nothing stacks, nothing pushes."
+ "changelog": "Declares image advice: the ideal photo shape for this hero, shown beside the upload in your editor.",
+ "imagery": {
+  "hero": {
+   "idealAspect": "16:9",
+   "minWidth": 1600,
+   "note": "Landscape around 16:9 fills the hero cleanly; panoramas suit the whole-photo framing."
+  }
+ }
 }