@port60/template-kit 0.11.0 → 0.13.0

package/bin/cli.mjs

@@ -10,6 +10,8 @@ import { model } from '../src/commands/model.mjs';
 import { content } from '../src/commands/content.mjs';
 import { upgrade } from '../src/commands/upgrade.mjs';
 import { refresh } from '../src/commands/refresh.mjs';
+import { login, logout, whoami } from '../src/commands/auth.mjs';
+import { publish } from '../src/commands/publish.mjs';
 
 function parseArgs(argv) {
   const args = { _: [] };
@@ -59,6 +61,18 @@ switch (command) {
   case 'package':
     await packageCmd(args);
     break;
+  case 'login':
+    await login(args);
+    break;
+  case 'logout':
+    await logout(args);
+    break;
+  case 'whoami':
+    await whoami(args);
+    break;
+  case 'publish':
+    await publish(args);
+    break;
   default:
     console.log(`@port60/template-kit, build Port60 site templates locally
 
@@ -73,6 +87,12 @@ usage:
   p60-template-kit package [dir]               validate + build the uploadable zip
   p60-template-kit upgrade [dir]               move an existing template to the latest kit
                                                and contract, re-brief, re-validate
+  p60-template-kit login                       sign in from the terminal (the browser does the
+                                               actual sign-in; the code appears here)
+  p60-template-kit whoami                      who is signed in, and which studio workspace
+  p60-template-kit logout                      sign this machine out and revoke its token
+  p60-template-kit publish [dir] [--no-submit] validate, package, upload to your studio and
+                                               submit for review, in one command
 
 AI agents: the scaffold's AGENTS.md is your briefing; iterate with \`validate --json\`.
 Docs: https://developers.port60.com (agents: /llms-full.txt)`);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@port60/template-kit",
-  "version": "0.11.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.",
+  "version": "0.13.0",
+  "description": "Build Port60 site templates locally: scaffold, live-preview, validate against the platform contract, and package for studio upload. AI-agent ready \u2014 every scaffold ships AGENTS.md and validate emits machine-readable JSON.",
   "type": "module",
   "bin": {
     "p60-template-kit": "bin/cli.mjs"
@@ -12,6 +12,7 @@
     "starter"
   ],
   "scripts": {
+    "sync-vendor": "node scripts/sync-vendor.mjs",
     "test": "node --test 'tests/*.test.mjs'"
   },
   "dependencies": {
@@ -22,12 +23,5 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Port60Labs/template-kit.git"
-  },
-  "homepage": "https://developers.port60.com",
-  "bugs": {
-    "url": "https://github.com/Port60Labs/template-kit/issues"
-  },
-  "publishConfig": {
-    "access": "public"
   }
 }

package/src/commands/auth.mjs

@@ -0,0 +1,102 @@
+import { createInterface } from 'node:readline/promises';
+import {
+  accessToken, api, apiBase, authBase, authRealm, clearCredentials, decodeJwtPayload,
+  deviceLogin, loadCredentials, oauthClientId, requireCredentials, revoke, saveCredentials
+} from '../lib/auth.mjs';
+
+/**
+ * `login` / `logout` / `whoami` (developer CLI stream A). Login runs the device flow, then finds
+ * the developer's STUDIO workspace: memberships are product-blind, so the studio is discovered by
+ * probing the studio surface itself (the gateway's entitlement gate refuses non-studio workspaces,
+ * which is exactly the discriminator). One membership skips the ceremony; ambiguity asks once and
+ * the choice is remembered.
+ */
+
+async function studioProbe(creds, token, tenantId) {
+  try {
+    const res = await api(creds, token, `/api/admin/studio/tenants/${tenantId}/studio/status`);
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+export async function login() {
+  const { accessToken: access, refreshToken } = await deviceLogin();
+  if (!refreshToken) {
+    console.error('✗ The sign-in completed but returned no offline token. Is offline_access enabled on the CLI client?');
+    process.exit(1);
+  }
+  const claims = decodeJwtPayload(access);
+  const creds = {
+    authBase: authBase(),
+    realm: authRealm(),
+    clientId: oauthClientId(),
+    apiBase: apiBase(),
+    refreshToken,
+    email: claims.email ?? null
+  };
+
+  const res = await api(creds, access, '/api/me/memberships');
+  if (!res.ok) {
+    console.error(`✗ Signed in, but the workspace list could not be read (${res.status}).`);
+    process.exit(1);
+  }
+  const memberships = await res.json();
+  if (memberships.length === 0) {
+    console.error('✗ This account has no workspaces. Create a developer account at https://port60.com/developers/ first.');
+    process.exit(1);
+  }
+
+  let workspace = null;
+  if (memberships.length === 1) {
+    workspace = memberships[0];
+  } else {
+    const probes = await Promise.all(
+      memberships.map(async (m) => ((await studioProbe(creds, access, m.tenantId)) ? m : null))
+    );
+    const studios = probes.filter(Boolean);
+    if (studios.length === 1) {
+      workspace = studios[0];
+    } else {
+      const candidates = studios.length > 0 ? studios : memberships;
+      console.log('\n  Your workspaces:');
+      candidates.forEach((m, i) => console.log(`    ${i + 1}. ${m.workspaceName}`));
+      const rl = createInterface({ input: process.stdin, output: process.stdout });
+      const answer = await rl.question('  Which one is your template studio? ');
+      rl.close();
+      workspace = candidates[Number(answer) - 1];
+      if (!workspace) {
+        console.error('✗ No such option. Run login again.');
+        process.exit(1);
+      }
+    }
+  }
+
+  saveCredentials({ ...creds, workspace: { tenantId: workspace.tenantId, name: workspace.workspaceName } });
+  console.log('');
+  console.log(`✓ Signed in${creds.email ? ` as ${creds.email}` : ''}.`);
+  console.log(`  Studio workspace: ${workspace.workspaceName}`);
+  console.log('  Not the account you meant? Run: p60-template-kit logout, then login again.');
+  console.log('  Publish from a template directory with: p60-template-kit publish');
+}
+
+export async function whoami() {
+  const creds = requireCredentials();
+  const token = await accessToken(creds);
+  const claims = decodeJwtPayload(token);
+  console.log(`Signed in as ${claims.email ?? creds.email ?? claims.sub}`);
+  console.log(`Studio workspace: ${creds.workspace?.name ?? '(none chosen)'}`);
+  console.log(`Platform API: ${creds.apiBase}`);
+}
+
+export async function logout() {
+  const creds = loadCredentials();
+  if (!creds) {
+    console.log('Not signed in.');
+    return;
+  }
+  await revoke(creds);
+  clearCredentials();
+  console.log('✓ Signed out; this machine\'s token has been revoked.');
+}

package/src/commands/publish.mjs

@@ -0,0 +1,94 @@
+import { resolve } from 'node:path';
+import { validateArtifact } from '../vendor/validator/validate.mjs';
+import { loadArtifactDir } from '../lib/artifactFiles.mjs';
+import { buildZip } from '../lib/zip.mjs';
+import { accessToken, api, requireCredentials } from '../lib/auth.mjs';
+
+/**
+ * `publish [dir]` (developer CLI stream A): validate, package and upload in one breath, then
+ * submit the version for review. The upload lane is manifest-routed, so an unclaimed name CREATES
+ * the template and a claimed one gains a version — the server runs the identical validation
+ * again, and a human reviews before anything can reach a charity's site. `--no-submit` stops at
+ * validated (submit later from the studio).
+ */
+export async function publish(args) {
+  const creds = requireCredentials();
+  if (!creds.workspace?.tenantId) {
+    console.error('✗ No studio workspace on record. Run: p60-template-kit login');
+    process.exit(1);
+  }
+  const dir = resolve(args._[0] ?? '.');
+  const files = loadArtifactDir(dir);
+  const { errors, manifest } = await validateArtifact(files);
+  if (errors.length > 0) {
+    console.error(`✗ not publishing, ${errors.length} validation error${errors.length === 1 ? '' : 's'}:`);
+    for (const e of errors) console.error(`  - ${e}`);
+    process.exit(1);
+  }
+  const zip = buildZip(Object.entries(files).map(([path, content]) => ({ path, content })));
+  console.log(`✓ ${manifest.name} ${manifest.version} validated, uploading…`);
+
+  const token = await accessToken(creds);
+  const studio = `/api/admin/studio/tenants/${creds.workspace.tenantId}/studio`;
+  const res = await api(creds, token, `${studio}/uploads`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/zip' },
+    body: zip
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    let message = text;
+    try {
+      const body = JSON.parse(text);
+      message = body.message ?? body.detail ?? text;
+    } catch {
+      // plain-text error, shown as-is
+    }
+    console.error(`✗ Upload refused (${res.status}): ${message}`);
+    if (res.status === 403) {
+      // The CLI holds the developer's OWN token; the server's permission model decides, exactly
+      // as in the studio UI. A role below the studio's minimum publishes nowhere.
+      console.error('  This account doesn\'t have permission to publish in that workspace.');
+      console.error('  Sign in with an account that administers the developer studio.');
+    }
+    process.exit(1);
+  }
+  const outcome = await res.json();
+  const upload = outcome.upload ?? {};
+  if (outcome.templateCreated) {
+    console.log(`✓ ${outcome.templateLabel} created from its manifest.`);
+  }
+  if (!upload.accepted) {
+    console.error('✗ The platform rejected the version:');
+    for (const e of upload.errors ?? []) console.error(`  - ${e}`);
+    process.exit(1);
+  }
+  for (const w of upload.warnings ?? []) console.log(`  ⚠ ${w}`);
+  console.log(`✓ Version ${upload.version} uploaded and validated.`);
+
+  if (args['no-submit']) {
+    console.log('  Left unsubmitted (--no-submit). Submit it for review from your studio.');
+    return;
+  }
+
+  // Submission needs the version row's id; the detail read supplies it.
+  const detailRes = await api(creds, token, `${studio}/templates/${outcome.templateId}`);
+  if (!detailRes.ok) {
+    console.error(`⚠ Uploaded, but the submit step could not read the template (${detailRes.status}). Submit from your studio.`);
+    process.exit(1);
+  }
+  const detail = await detailRes.json();
+  const row = (detail.versions ?? []).find((v) => v.version === upload.version && v.status === 'VALIDATED');
+  if (!row) {
+    console.error('⚠ Uploaded, but the new version was not found in a submittable state. Submit from your studio.');
+    process.exit(1);
+  }
+  const submitRes = await api(creds, token, `${studio}/templates/${outcome.templateId}/versions/${row.id}/submit`, {
+    method: 'POST'
+  });
+  if (!submitRes.ok) {
+    console.error(`⚠ Uploaded, but submitting for review failed (${submitRes.status}). Submit from your studio.`);
+    process.exit(1);
+  }
+  console.log('✓ Submitted for review. You\'ll get an email when a reviewer decides.');
+}

package/src/lib/auth.mjs

@@ -0,0 +1,195 @@
+import { chmodSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { spawn } from 'node:child_process';
+
+/**
+ * The kit's sign-in plumbing (developer CLI stream A, docs/developer-cli-and-ci-publishing.md).
+ * The OAuth Device Authorization Grant against the platform's customer realm: the BROWSER does
+ * the actual sign-in (so passwordless email codes and Google both work unchanged), the terminal
+ * only ever holds the resulting tokens. The refresh token is an offline token, stored 0600 in
+ * ~/.port60/credentials.json and revocable from the account's sessions at any time.
+ */
+
+const STORE_DIR = join(homedir(), '.port60');
+const STORE_FILE = join(STORE_DIR, 'credentials.json');
+
+export const authBase = () => (process.env.P60_AUTH_BASE || 'https://auth.port60.com').replace(/\/+$/, '');
+export const authRealm = () => process.env.P60_REALM || 'port60-customers';
+export const apiBase = () => (process.env.P60_API_BASE || 'https://api.port60.com').replace(/\/+$/, '');
+export const oauthClientId = () => process.env.P60_CLIENT_ID || 'port60-kit';
+
+const tokenUrl = (base, realm) => `${base}/realms/${realm}/protocol/openid-connect/token`;
+
+export function loadCredentials() {
+  try {
+    return JSON.parse(readFileSync(STORE_FILE, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function saveCredentials(creds) {
+  mkdirSync(STORE_DIR, { recursive: true, mode: 0o700 });
+  writeFileSync(STORE_FILE, JSON.stringify(creds, null, 2) + '\n', { mode: 0o600 });
+  chmodSync(STORE_FILE, 0o600); // writeFileSync mode is ignored when the file already exists
+}
+
+export function clearCredentials() {
+  rmSync(STORE_FILE, { force: true });
+}
+
+export function requireCredentials() {
+  const creds = loadCredentials();
+  if (!creds?.refreshToken) {
+    console.error('✗ Not signed in. Run: p60-template-kit login');
+    process.exit(1);
+  }
+  return creds;
+}
+
+/** The JWT payload, unverified — display only (email, subject). The server verifies for real. */
+export function decodeJwtPayload(token) {
+  try {
+    return JSON.parse(Buffer.from(token.split('.')[1], 'base64url').toString('utf8'));
+  } catch {
+    return {};
+  }
+}
+
+async function form(url, params) {
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: { 'content-type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams(params)
+  });
+  const text = await res.text();
+  let body = {};
+  try {
+    body = JSON.parse(text);
+  } catch {
+    // non-JSON error page; the status carries the story
+  }
+  return { ok: res.ok, status: res.status, body };
+}
+
+/** A fresh access token from the stored offline token; rotates the stored refresh token when the
+ *  server hands a new one back. */
+export async function accessToken(creds) {
+  const { ok, status, body } = await form(tokenUrl(creds.authBase, creds.realm), {
+    grant_type: 'refresh_token',
+    client_id: creds.clientId,
+    refresh_token: creds.refreshToken
+  });
+  if (!ok) {
+    console.error(`✗ Your sign-in is no longer valid (${body.error ?? status}). Run: p60-template-kit login`);
+    process.exit(1);
+  }
+  if (body.refresh_token && body.refresh_token !== creds.refreshToken) {
+    saveCredentials({ ...creds, refreshToken: body.refresh_token });
+  }
+  return body.access_token;
+}
+
+function tryOpenBrowser(url) {
+  const opener = process.platform === 'darwin' ? 'open'
+    : process.platform === 'win32' ? 'start' : 'xdg-open';
+  try {
+    spawn(opener, [url], { stdio: 'ignore', detached: true, shell: process.platform === 'win32' }).unref();
+  } catch {
+    // no browser to open; the printed URL is the path
+  }
+}
+
+const sleep = (s) => new Promise((r) => setTimeout(r, s * 1000));
+
+/**
+ * The device flow itself: ask for a code, hand the human to the browser, poll until the sign-in
+ * completes. Returns {accessToken, refreshToken}.
+ */
+export async function deviceLogin() {
+  const base = authBase();
+  const realm = authRealm();
+  const clientId = oauthClientId();
+  // prompt=login forces a fresh, intentional sign-in at the verification page even when the
+  // browser already holds an SSO session — so a developer who is also signed in as (say) a charity
+  // editor can never silently authorise the CLI as the wrong account. Login is rare (the offline
+  // token lasts), so paying for intentionality every time is the right trade.
+  const start = await form(`${base}/realms/${realm}/protocol/openid-connect/auth/device`, {
+    client_id: clientId,
+    scope: 'openid offline_access',
+    prompt: 'login'
+  });
+  if (!start.ok) {
+    console.error(`✗ Could not start the sign-in (${start.body.error_description ?? start.body.error ?? start.status}).`);
+    if (start.status === 404 || start.body.error === 'invalid_client') {
+      console.error('  The sign-in service may not have the CLI client enabled yet.');
+    }
+    process.exit(1);
+  }
+  const { device_code: deviceCode, user_code: userCode, verification_uri: uri,
+    verification_uri_complete: uriComplete, interval = 5, expires_in: expiresIn = 600 } = start.body;
+
+  console.log('');
+  console.log(`  Visit:  ${uri}`);
+  console.log(`  Code:   ${userCode}`);
+  console.log('');
+  console.log('  Sign in there with the account you want to PUBLISH AS — you will be asked to sign in');
+  console.log('  even if your browser is already logged in, so pick the right one. This terminal will notice.');
+  if (uriComplete) tryOpenBrowser(uriComplete);
+
+  const deadline = Date.now() + expiresIn * 1000;
+  let waitSeconds = interval;
+  while (Date.now() < deadline) {
+    await sleep(waitSeconds);
+    const poll = await form(tokenUrl(base, realm), {
+      grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+      client_id: clientId,
+      device_code: deviceCode
+    });
+    if (poll.ok) {
+      return { accessToken: poll.body.access_token, refreshToken: poll.body.refresh_token };
+    }
+    switch (poll.body.error) {
+      case 'authorization_pending':
+        break;
+      case 'slow_down':
+        waitSeconds += 5;
+        break;
+      case 'access_denied':
+        console.error('✗ The sign-in was declined in the browser.');
+        process.exit(1);
+        break;
+      case 'expired_token':
+        console.error('✗ The code expired before the sign-in completed. Run login again.');
+        process.exit(1);
+        break;
+      default:
+        console.error(`✗ Sign-in failed (${poll.body.error_description ?? poll.body.error ?? poll.status}).`);
+        process.exit(1);
+    }
+  }
+  console.error('✗ The code expired before the sign-in completed. Run login again.');
+  process.exit(1);
+}
+
+/** Best-effort server-side revocation of the offline token; local removal always follows. */
+export async function revoke(creds) {
+  try {
+    await form(`${creds.authBase}/realms/${creds.realm}/protocol/openid-connect/logout`, {
+      client_id: creds.clientId,
+      refresh_token: creds.refreshToken
+    });
+  } catch {
+    // unreachable server; the local removal still signs this machine out
+  }
+}
+
+/** An authenticated platform-API call. */
+export async function api(creds, token, path, init = {}) {
+  const res = await fetch(`${creds.apiBase}${path}`, {
+    ...init,
+    headers: { authorization: `Bearer ${token}`, ...(init.headers ?? {}) }
+  });
+  return res;
+}

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

@@ -892,6 +892,12 @@
           "kind": "text",
           "required": false,
           "description": "Optional introduction."
+        },
+        {
+          "name": "mapSlug",
+          "kind": "text",
+          "required": false,
+          "description": "WHICH map renders here, by its address (the Pages editor's placement picker writes it; the Maps area is where maps exist). Absent = the tenant's first published map."
         }
       ],
       "minimal": {},

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

@@ -12,6 +12,9 @@
     { "name": "--accent", "description": "Action accent (the donate CTA family)." },
     { "name": "--accent-strong", "description": "Darker accent." },
     { "name": "--gold", "description": "Highlight tint (marks, ratings)." },
+    { "name": "--marker", "description": "Impact-map pin colour (the live-map markers are a zoom-scaling circle layer that take this colour). Defaults to --accent." },
+    { "name": "--map-mode", "description": "Impact-map basemap colour mode read by the map island: auto (derive the map's paper/ink from the theme), light, dark, or muted. Default auto." },
+    { "name": "--map-projection", "description": "Impact-map projection: flat (default) or globe — the planet as a rotatable sphere with atmosphere." },
     { "name": "--line", "description": "Hairline borders." },
     { "name": "--line-strong", "description": "Emphasised borders (selected, focus)." },
     { "name": "--danger", "description": "Errors and destructive affordances." },

package/src/vendor/validator/platform-base.css

@@ -20,6 +20,15 @@
   --accent: #ef6044;
   --accent-strong: #d94d33;
   --gold: #f3b13b;
+  /* Impact map. --marker = the map pin colour (a deliberate brand accent by default; the live-map
+     markers are a zoom-scaling MapLibre circle layer that takes this colour). --map-mode = the
+     basemap colour mode read by the map island: `auto` derives the map's paper/ink from the theme
+     neutrals below, `light`/`dark`/`muted` force a base. Template-owned — set in theme.css or exposed
+     as Appearance knobs; the tenant never edits map colour directly. */
+  --marker: var(--accent);
+  --map-mode: auto;
+  /* flat (default) or globe — MapLibre's own globe projection, a rotatable sphere. */
+  --map-projection: flat;
   --line: rgba(31, 42, 51, 0.1);
   --line-strong: rgba(18, 135, 122, 0.28);
   --danger: #c0392b;
@@ -953,6 +962,22 @@ textarea.p60-form-control {
   gap: 1rem;
 }
 
+/* MOBILE BREAKOUT (owner, 2026-08-17): on phones the nesting stack squashes the card badly —
+   measured on Sanctuary: 390px viewport → 346 container → 294 aside → 249px card → ~195px of
+   actual controls. A donate form is a working control surface; it gets the full screen width
+   (edge to edge, side borders/radius dropped, its own padding kept). The negative-margin trick
+   escapes ANY wrapper depth; layouts here are symmetric, so the sheet lands exactly 0..100vw. */
+@media (max-width: 640px) {
+  .donate-card {
+    width: 100vw;
+    margin-left: calc(50% - 50vw);
+    border-radius: 0;
+    border-left: 0;
+    border-right: 0;
+    padding: 1.4rem 1.1rem;
+  }
+}
+
 /* Optional cause image banner at the top of the widget (set per-cause in tenant-admin). */
 .donate-cause-img {
   width: 100%;
@@ -1966,6 +1991,30 @@ textarea.p60-form-control {
   grid-template-columns: repeat(auto-fill, minmax(260px, 1fr));
   gap: 1.5rem;
 }
+/* MOBILE: the stacked grid becomes an edge-to-edge SWIPE ROW with a peek (owner, 2026-08-17) —
+   the scroller bleeds to the screen edges, each card keeps its padding, the first card aligns to
+   the text gutter, and the cut-off next card IS the "swipe me" affordance (the reference maps'
+   card idiom). Snap keeps cards settling cleanly; the scrollbar is hidden, the peek replaces it. */
+@media (max-width: 640px) {
+  .article-grid {
+    display: flex;
+    width: 100vw;
+    margin-left: calc(50% - 50vw);
+    overflow-x: auto;
+    -webkit-overflow-scrolling: touch;
+    scroll-snap-type: x proximity;
+    gap: 0.9rem;
+    padding: 0.2rem 22px 0.6rem;
+    scroll-padding-left: 22px;
+    scrollbar-width: none;
+  }
+  .article-grid::-webkit-scrollbar { display: none; }
+  .article-grid > .article-card {
+    flex: 0 0 78%;
+    max-width: 330px;
+    scroll-snap-align: start;
+  }
+}
 .article-card {
   display: flex;
   flex-direction: column;
@@ -2355,6 +2404,26 @@ textarea.p60-form-control {
   align-items: center;
   gap: 0.5rem;
 }
+/* MOBILE: the rotator is MEDIA — it bleeds edge to edge like the hero and the map, with the
+   arrows overlaid on the image instead of eating width beside it. */
+@media (max-width: 640px) {
+  .events-carousel {
+    position: relative;
+    width: 100vw;
+    margin-left: calc(50% - 50vw);
+    gap: 0;
+  }
+  .events-carousel .carousel-slide { border-radius: 0; }
+  .events-carousel > .carousel-arrow {
+    position: absolute;
+    top: 50%;
+    transform: translateY(-50%);
+    z-index: 2;
+    opacity: 0.9;
+  }
+  .events-carousel > .carousel-arrow:first-of-type { left: 10px; }
+  .events-carousel > .carousel-arrow:last-of-type { right: 10px; }
+}
 .carousel-slide {
   position: relative;
   flex: 1;
@@ -4228,23 +4297,98 @@ textarea.p60-form-control {
   .people-grid { grid-template-columns: 1fr; }
 }
 
-/* ── Impact map island (WP4) — baseline look; templates restyle via the styling API. Colours ride
-   currentColor and the theme's tokens so the island wears the template's clothes. */
+/* ── Impact map island (WP4) — the OVERLAY borrows the theme: pins wear --marker (a brand accent by
+   default), the card is a themed --surface. The BASEMAP colour is derived by the map island from the
+   theme + --map-mode (see lib/mapTheme.ts). Brand on the overlay, neutrals on the map — the recipe
+   that stays legible on any theme. Templates restyle any of this via the tokens or these classes. */
 .impact-map { margin: 24px 0; }
 .impact-map-head h2 { margin: 0 0 6px; }
 .impact-map-intro { margin: 0 0 14px; opacity: 0.85; }
-.impact-map-canvas { position: relative; min-height: 340px; border-radius: 14px; overflow: hidden;
-  background: linear-gradient(160deg, rgba(0, 0, 0, 0.28), rgba(0, 0, 0, 0.55)), currentColor; }
+.impact-map-stats { margin: 0 0 14px; color: var(--muted); font-weight: 600; letter-spacing: 0.01em; }
+/* The stable stage, shaped like THE WORLD BAND ITSELF: the island's planet view is all 360° of
+   longitude by 84°N–58°S (whole Greenland in, only the polar void and Antarctica trimmed), which in
+   Web Mercator is a 1.497:1 box — so a frame with that exact ratio holds the full planet edge to
+   edge, full width AND full height, at any screen size. A ratio wider than the band (a max-height
+   clamp once made it so on large screens) turns the fit height-constrained and the world renders
+   NARROWER than the frame — dead bars at the sides; a narrower ratio (min-height on phones) just
+   adds benign vertical margin. Relative + clipped so MapLibre always has a real box and can never
+   escape it. Keep this ratio in step with the island's planet bounds. */
+.impact-map-stage { position: relative; width: 100%; aspect-ratio: 1.497; min-height: 300px;
+  border-radius: 14px; overflow: hidden; }
+  /* width:100% is LOAD-BEARING: with height pinned by min-height and width left auto, CSS derives
+     width FROM the aspect-ratio (300 x 1.497 = 449px) — on phones the stage overflowed the page
+     sideways, shoving every other section into a lopsided "left with a right gutter" layout. Width
+     pinned, the ratio yields height and min-height only ever makes the stage TALLER. */
+/* MOBILE BREAKOUT: a map is a canvas — every pixel is information, nothing needs a margin — so on
+   phones it bleeds edge to edge (media bleeds, prose gutters: the hero already sets the rhythm).
+   Cooperative gestures keep page-scrolling safe over the full-width canvas. */
+@media (max-width: 640px) {
+  .impact-map-stage {
+    width: 100vw;
+    margin-left: calc(50% - 50vw);
+    border-radius: 0;
+  }
+}
+.impact-map-canvas { position: absolute; inset: 0;
+  background: linear-gradient(160deg, rgba(0, 0, 0, 0.28), rgba(0, 0, 0, 0.55)), var(--muted); }
 .impact-map-pin { position: absolute; width: 16px; height: 16px; border-radius: 50%;
-  transform: translate(-50%, -50%); border: 2px solid #fff; background: currentColor;
+  transform: translate(-50%, -50%); border: 2px solid var(--surface); background: var(--marker);
   cursor: pointer; padding: 0; transition: transform 120ms ease; }
 .impact-map-pin:hover, .impact-map-pin:focus-visible { transform: translate(-50%, -50%) scale(1.35); }
-.impact-map-pin--active { box-shadow: 0 0 0 5px rgb(255 255 255 / 28%); }
-.impact-map-card { margin-top: 14px; border: 1px solid rgb(127 127 127 / 30%); border-radius: 12px;
+.impact-map-pin--active { box-shadow: 0 0 0 5px var(--primary-soft); }
+.impact-map-card { margin-top: 14px; background: var(--surface); color: var(--ink);
+  border: 1px solid var(--line); border-radius: var(--radius-sm); box-shadow: var(--shadow-sm);
   padding: 16px 18px; max-width: 34rem; }
+/* On the LIVE map the below-map card is a SMALL-SCREEN device: the anchored popup is taller than a
+   phone-height stage, so the marker selection drives this card instead (Google-Maps-mobile idiom).
+   Desktop keeps the inline popup and hides this. The pin-canvas fallback (no modifier) shows the
+   card on every screen size, as it always has. */
+.impact-map-card--small-screens { display: none; }
+@media (max-width: 640px) {
+  /* Full width, flush under the full-bleed map — the two read as one attached sheet (the same
+     breakout as the donate card; the hairline top border is the seam between map and card). */
+  .impact-map-card--small-screens {
+    display: block;
+    width: 100vw;
+    margin: 0 0 0 calc(50% - 50vw);
+    max-width: none;
+    border-radius: 0;
+    border-left: 0;
+    border-right: 0;
+  }
+}
 .impact-map-card-kind { display: inline-block; font-size: 11px; font-weight: 700;
-  letter-spacing: 0.06em; text-transform: uppercase; opacity: 0.65; margin-bottom: 4px; }
+  letter-spacing: 0.06em; text-transform: uppercase; color: var(--muted); margin-bottom: 4px; }
 .impact-map-card-title { margin: 0 0 6px; }
 .impact-map-card-summary { margin: 0 0 10px; opacity: 0.9; }
-.impact-map-card-cta { font-weight: 600; }
+.impact-map-card-cta { font-weight: 600; color: var(--primary); }
 .impact-map-empty { opacity: 0.7; }
+/* The live tile layer (slice 2): fills the stage from first render so MapLibre measures a real box;
+   the pin canvas overlays it until (unless) the map is ready, then unmounts to reveal the map.
+   Sized with width/height (NOT inset) because MapLibre forces position:relative on this element,
+   which would defeat absolute insets and collapse the box to zero height. */
+.impact-map-gl { width: 100%; height: 100%; }
+/* Live-map markers are a MapLibre circle layer (WebGL) — they scale with zoom and take their colour
+   from --marker (circle-color) — so there is no DOM marker element to style here. The pin canvas
+   fallback above keeps its own .impact-map-pin dots for the no-tiles case. */
+/* The INLINE marker card (a MapLibre popup anchored at the clicked marker — where "See more"
+   lives): the shell takes the theme's surface; the tip is recoloured per anchor side to match. */
+.impact-map-popup .maplibregl-popup-content { background: var(--surface); color: var(--ink);
+  border: 1px solid var(--line); border-radius: var(--radius-sm); box-shadow: var(--shadow);
+  padding: 14px 16px; }
+.impact-map-popup.maplibregl-popup-anchor-bottom .maplibregl-popup-tip,
+.impact-map-popup.maplibregl-popup-anchor-bottom-left .maplibregl-popup-tip,
+.impact-map-popup.maplibregl-popup-anchor-bottom-right .maplibregl-popup-tip { border-top-color: var(--surface); }
+.impact-map-popup.maplibregl-popup-anchor-top .maplibregl-popup-tip,
+.impact-map-popup.maplibregl-popup-anchor-top-left .maplibregl-popup-tip,
+.impact-map-popup.maplibregl-popup-anchor-top-right .maplibregl-popup-tip { border-bottom-color: var(--surface); }
+.impact-map-popup.maplibregl-popup-anchor-left .maplibregl-popup-tip { border-right-color: var(--surface); }
+.impact-map-popup.maplibregl-popup-anchor-right .maplibregl-popup-tip { border-left-color: var(--surface); }
+.impact-map-popup-card .impact-map-card-title { margin: 4px 0 6px; font-size: 1.02rem; }
+.impact-map-popup-card .impact-map-card-summary { margin: 0 0 8px; }
+/* The point's image (when it has one): bleeds to the popup's top edge; plain rounded in the
+   fallback card. Absent image = the card simply starts at the kind line. */
+.impact-map-card-image { display: block; width: 100%; aspect-ratio: 16 / 9; object-fit: cover;
+  border-radius: 10px; margin: 0 0 10px; }
+.impact-map-popup-card .impact-map-card-image { width: calc(100% + 32px); margin: -14px -16px 10px;
+  border-radius: calc(var(--radius-sm) - 1px) calc(var(--radius-sm) - 1px) 0 0; }

package/starter/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "starter",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "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.",
@@ -15,12 +15,14 @@
       "values",
       "cta",
       "people",
-      "campaigns"
+      "campaigns",
+      "impactMap"
     ],
     "islands": [
       "donation_widget",
       "member_menu",
-      "hero_carousel"
+      "hero_carousel",
+      "map"
     ],
     "layout": true,
     "heroImagery": true,
@@ -46,7 +48,7 @@
       }
     ]
   },
-  "changelog": "Demonstrates the behaviour catalogue: the values rail reveals with a stagger and a multi-photo standard hero becomes an engine-wired carousel.",
+  "changelog": "Adds the impact map section: pin your located work on a themed map of where you work.",
   "imagery": {
     "hero": {
       "idealAspect": "16:9",

package/starter/sections/impactMap.liquid

@@ -0,0 +1,5 @@
+<section class="section">
+  <div class="container">
+    {% island 'map' %}
+  </div>
+</section>