@typeroll/mcp-server 0.45.83 → 0.45.85

package/dist/tools/deploy.js

@@ -41,7 +41,7 @@ export const deployTools = [
     },
     {
         name: 'get_deploy_status',
-        description: "Status of a single deploy job. Optional top-level build_progress reports the exact task status, attempt, step and completed/total files; not an overall percentage or ETA. Returns { job, queued_for_seconds, queue_timeout_seconds }. job.status is one of queued | running | succeeded | failed. On a failed build, job.error names the failed step and the cause the step printed, job.failure.code is the reported code (e.g. media_build_process_exit_1) and job.failure.diagnostic holds { cause, lines } (the last 40 lines that step printed, credentials removed). On the Cloudflare build engine job.failure.provider_log also holds { step, build_id, summary, lines } from the provider's build log (last 60 lines). Read them before retrying; retrying does not fix a cause that is in the content or the build engine. Polling cadence: ~5s for queued/running. job.render_report, when present, reports actual HTML mode (full/partial), rendered, reused, total and removed route counts plus a fallback reason. From Core 0.2.17, custom blocks and consumed image metadata are tracked per route; older caches require one full build. It does not measure media or provider startup savings. job.coordinator, when present, reports the last completed CMS phase and duration_ms for that attempt; external build waiting is excluded. Keep observing the same job across checkpoints; do not trigger duplicate deploys. A job stuck in 'queued' for longer than queue_timeout_seconds (default 300s) auto-flips to failed with phase='queue_timeout' — so a single poll past that timestamp returns the terminal state and you can stop polling.",
+        description: "Status of a single deploy job. Optional top-level build_progress reports the exact task status, attempt, step and completed/total files; not an overall percentage or ETA. Returns { job, queued_for_seconds, queue_timeout_seconds }. job.status is one of queued | running | succeeded | failed. On a failed build, job.error names the failed step and the cause the step printed, job.failure.code is the reported code (e.g. media_build_process_exit_1) and job.failure.diagnostic holds { cause, lines } (the last 40 lines that step printed, credentials removed). On the Cloudflare build engine job.failure.provider_log also holds { step, build_id, summary, lines } from the provider's build log (last 60 lines). Read them before retrying; retrying does not fix a cause that is in the content or the build engine. job.warnings, when present, lists non-blocking findings of a deploy that still ran, for example a media file left out of the publication because it could not be published safely (an SVG that could not be sanitized); report them to the user. Polling cadence: ~5s for queued/running. job.render_report, when present, reports actual HTML mode (full/partial), rendered, reused, total and removed route counts plus a fallback reason. From Core 0.2.17, custom blocks and consumed image metadata are tracked per route; older caches require one full build. It does not measure media or provider startup savings. job.coordinator, when present, reports the last completed CMS phase and duration_ms for that attempt; external build waiting is excluded. Keep observing the same job across checkpoints; do not trigger duplicate deploys. A job stuck in 'queued' for longer than queue_timeout_seconds (default 300s) auto-flips to failed with phase='queue_timeout' — so a single poll past that timestamp returns the terminal state and you can stop polling.",
         inputSchema: { job_id: z.string(), include_provider: z.boolean().optional().describe('Also read the exact Git commit and Cloudflare build stages for a customer Git publication. Does not return build secrets.') },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
             const res = await client.get(siteId, `deploys/${encodeURIComponent(args.job_id)}`);

package/dist/tools/extensions.js

@@ -142,7 +142,7 @@ export const developerExtensionTools = [
     },
     {
         name: 'read_developer_extension', noSite: true,
-        description: 'Read one of your organization\'s Extensions with all saved releases and their status (draft, review, published, deprecated, revoked). Requires an organization API key.',
+        description: 'Read one of your organization\'s Extensions with all saved releases and their status (draft, review, published, deprecated, revoked). extension.developer_org_id is the value of the developer_org_id claim in every token Typeroll issues for its installations: provider backends must require it in addition to aud. id_reservation is reserved, unreserved (a registration that predates reservations; any update claims it) or held_by_other (another developer organization holds this id). Requires an organization API key.',
         inputSchema: { extension_id: z.string().min(1) },
         handler: withErrorBoundary(async (args, { client }) => ok(await client.developer('GET', ext(args.extension_id)))),
     },

package/dist/tools/forms.js

@@ -149,7 +149,7 @@ export const formTools = [
     },
     {
         name: 'list_form_submissions',
-        description: 'List submissions received for a form, newest first, cursor-paginated (cap 200 per page). Admins also see each submission\'s webhook delivery status. Use this to help a customer triage inbound contact / lead submissions; read_form_submission reads one.',
+        description: 'List submissions received for a form, newest first, cursor-paginated (cap 200 per page). Admins also see each submission\'s webhook delivery status. Visitor IP addresses are not stored or returned; completed submissions past the site\'s form_submission_retention_days (read_site_settings) are deleted and never listed. Use this to help a customer triage inbound contact / lead submissions; read_form_submission reads one.',
         inputSchema: {
             form_id: z.string(),
             limit: z.number().int().min(1).max(200).optional(),
@@ -163,7 +163,7 @@ export const formTools = [
     },
     {
         name: 'read_form_submission',
-        description: 'Read one submission of a form by id (from list_form_submissions): the submitted values, status (partial or complete), step and timestamps. Admins also see its webhook delivery status, as in the portal.',
+        description: 'Read one submission of a form by id (from list_form_submissions): the submitted values, status (partial or complete), step and timestamps, with expires_at when the submission is due for deletion. Admins also see its webhook delivery status, as in the portal.',
         inputSchema: {
             form_id: z.string(),
             submission_id: z.string(),

package/dist/tools/media.js

@@ -67,8 +67,8 @@ export const mediaTools = [
         name: 'create_upload_url',
         description: 'Mint a 5-min signed PUT URL for direct-to-R2 upload. After the upload completes, the CDN url is what you reference in <img src="…">. REQUIRED follow-up: call `finalize_media` after the PUT succeeds — without it the original ships with no Cache-Control (Lighthouse will flag it) and no responsive variants get generated. The response carries `finalize_url` as a reminder. This signed-PUT path is the INTEGRITY-SAFE way to upload bytes from disk or a generated asset — a direct `curl --data-binary @file` sends the bytes straight to R2 without transcribing them through the model, so it can\'t be corrupted the way a large `upload_media_inline` base64 blob can (ESPECIALLY use this, not inline, for SVG/logos). For a public source URL, `upload_media_from_url` is the one-call equivalent; reserve `upload_media_inline` for tiny payloads only.',
         inputSchema: {
-            filename: z.string().min(1),
-            content_type: z.string().min(1).describe('e.g. "image/png", "image/jpeg", "application/pdf"'),
+            filename: z.string().min(1).describe('Should end in an extension of content_type (e.g. logo.png with image/png). When the extension is missing or belongs to another type, the type\'s extension is appended (logo → logo.png, photo.html → photo.html.png); the response returns the stored filename. Unsupported types answer 415.'),
+            content_type: z.string().min(1).describe('e.g. "image/png", "image/jpeg", "application/pdf". SVGs are sanitized at finalize; an SVG that cannot be sanitized is refused.'),
             size: z.number().int().nonnegative().optional(),
             alt_text: z.string().optional(),
         },
@@ -82,7 +82,7 @@ export const mediaTools = [
         description: 'Fetch an image (or PDF) from any public URL and push it to the site\'s media library in one call. The MCP server downloads the source from verified public HTTP(S) destinations; private addresses and unsafe redirects are refused. Integrity-safe: the bytes are streamed, never transcribed as base64 through the model, so (unlike a large `upload_media_inline` payload) they can\'t be silently corrupted in transit. Returns { media_id, cdn_url, filename }.',
         inputSchema: {
             source_url: z.string().url().describe('Public URL to download the image from.'),
-            filename: z.string().optional().describe('Override the filename used on R2. Defaults to the last path segment of source_url.'),
+            filename: z.string().optional().describe('Override the filename used on R2. Defaults to the last path segment of source_url. When its extension does not match the content type, the type\'s extension is appended; the response returns the stored filename.'),
             content_type: z.string().optional().describe('Override the inferred content type (e.g. when source_url has no extension).'),
             alt_text: z.string().optional(),
         },
@@ -131,7 +131,7 @@ export const mediaTools = [
         name: 'upload_media_inline',
         description: 'Upload an image (or PDF) from base64-encoded bytes. ⚠️ Use ONLY for tiny payloads (a few KB). The base64 string crosses the model/tool boundary as text, where a larger blob can be SILENTLY CORRUPTED in transit — a few mutated chars yield a broken-but-valid-looking file that uploads with no error and the right size, and only fails when rendered (this has bitten a ~12KB logo SVG: half the wordmark vanished). For anything non-trivial, and ALWAYS for SVG/logos or assets you generated, prefer create_upload_url + a direct curl --data-binary PUT of the file bytes (bytes never transcribed → verified byte-identical), or upload_media_from_url (bytes fetched from a URL). After uploading any generated asset, VERIFY it (render it, or byte-diff against the source) before referencing it. Returns { media_id, cdn_url, filename }.',
         inputSchema: {
-            filename: z.string().min(1),
+            filename: z.string().min(1).describe('When its extension does not match content_type, the type\'s extension is appended; the response returns the stored filename.'),
             content_type: z.string().min(1).describe('e.g. "image/png", "image/jpeg", "application/pdf"'),
             data_base64: z.string().min(1).describe('The file bytes, base64-encoded (without a data: URL prefix).'),
             alt_text: z.string().optional(),
@@ -172,7 +172,7 @@ export const mediaTools = [
             return ok({
                 media_id: mint.media_id,
                 cdn_url: mint.cdn_url,
-                filename: args.filename,
+                filename: mint.filename ?? args.filename,
                 content_type: args.content_type,
                 size_bytes: buf.byteLength,
                 finalize: finalizeResult,
@@ -182,7 +182,7 @@ export const mediaTools = [
     },
     {
         name: 'update_media',
-        description: 'Patch a media item\'s alt text, filename or public path. A public path change is applied at the next publication.',
+        description: 'Patch a media item\'s alt text, filename or public path. A rename must be correct: a new filename or public path must end in an extension matching the file\'s type, and nothing is appended (400 media_extension_mismatch otherwise). A public path change is applied at the next publication.',
         inputSchema: {
             media_id: z.string(),
             alt_text: z.string().optional(),

package/dist/tools/settings.js

@@ -28,7 +28,7 @@ export const settingsTools = [
     },
     {
         name: 'read_site_settings',
-        description: "Read every site setting: name, tagline, logo, favicon/app icons, colors, fonts, contact info, social links, URL trailing-slash policy, iframe host allowlist, default SEO suffix/description, default_og_image, twitter_handle, organization (JSON-LD), language, robots_txt, image_sizes_default, cookie_consent, plus the scriptable surfaces scripts_head, scripts_body_end, and custom_css, `urls` (including `urls.staging`, the site's staging_url) and `render` (the site's platform render version, the latest version and what upgrading would change). Pass `version` to read a branch's settings (with copy-on-write chain-fallback to main for fields the branch hasn't overridden).",
+        description: "Read every site setting: name, tagline, logo, favicon/app icons, colors, fonts, contact info, social links, URL trailing-slash policy, iframe host allowlist, default SEO suffix/description, default_og_image, twitter_handle, organization (JSON-LD), language, robots_txt, image_sizes_default, cookie_consent, plus the scriptable surfaces scripts_head, scripts_body_end, and custom_css, form_submission_retention_days (days completed form submissions are kept before deletion; null = kept until deleted; site-wide, not per version), `urls` (including `urls.staging`, the site's staging_url) and `render` (the site's platform render version, the latest version and what upgrading would change). Pass `version` to read a branch's settings (with copy-on-write chain-fallback to main for fields the branch hasn't overridden).",
         inputSchema: {
             version: versionParam,
         },
@@ -47,6 +47,7 @@ export const settingsTools = [
             'scripts_head / scripts_body_end / custom_css and cookie_consent scripts ARE writable here — useful for a global stylesheet or analytics tag across all pages. ' +
             'Social sharing and structured data: default_og_image, twitter_handle, organization ({name, logo, same_as[]}, replaced as a whole; null clears). ' +
             'staging_url is stored on the Site (not per version), so it applies whichever `version` you pass. ' +
+            'form_submission_retention_days is also site-wide and deletes data: set it only when the user asks for a retention period. ' +
             'Pass `version` to scope the write to a branch (copy-on-write) instead of main — the right way to brand/recolor a site inside a redesign branch (colors, fonts, logo, custom_css) without touching the live settings. Omit it to write main.',
         inputSchema: {
             version: versionParam,
@@ -81,8 +82,10 @@ export const settingsTools = [
                 same_as: z.array(z.string()).max(50).optional().describe('Profile URLs (LinkedIn, X, Facebook, …) emitted as sameAs.'),
             }).strict().nullable().optional().describe('Organization schema.org JSON-LD emitted on every page. Replaces the stored value as a whole; null (or all-empty) clears it.'),
             staging_url: z.string().nullable().optional().describe('URL of a staging environment for this site, reported as urls.staging. Stored on the Site, not per version. Trailing slashes are dropped; empty string or null clears.'),
+            form_submission_retention_days: z.number().int().min(30).max(3650).nullable().optional().describe('Opt-in deletion of completed form submissions this many days (30–3650) after they were completed, on every form of the site, including existing submissions: those already older are deleted immediately and cannot be restored. null (the default) keeps submissions until someone deletes them. Site administrators only (never an Extension credential); stored on the Site, not per version. The response reports form_submission_retention { updated, deleted }. Partial submissions keep their form\'s partial_ttl_days.'),
             render_version: z.number().int().min(1).optional().describe('Platform render version. Platform output changes ship as new versions so existing sites never change look on their own. Upgrade only after previewing (get_preview_link render_version) and with the user\'s approval; the tr-upgrade-rendering skill compares every page. Lowering it returns to an earlier version.'),
-            design_scales: z.record(z.string(), z.record(z.string(), z.string())).optional().describe('Site token scales (replaced as a whole): type_size xs/sm/md/lg/xl/2xl/3xl; space none/xs/sm/md/lg/xl in px/rem/em; leading tight/snug/normal/relaxed/loose as unitless 1–2. Omitted steps use platform defaults.'),
+            typography: z.object({ ratio_mobile: z.number().min(1.1).max(1.5).optional(), ratio_desktop: z.number().min(1.1).max(1.5).optional(), rhythm: z.number().min(0.5).max(2).optional(), line_length: z.number().min(40).max(90).optional() }).strict().optional().describe('Fluid design controls (render version 10+). Base size is fonts.size_base. Replaces typography as a whole; omitted controls use defaults.'),
+            design_scales: z.record(z.string(), z.record(z.string(), z.union([z.string(), z.object({ mobile: z.string().optional(), tablet: z.string().optional(), laptop: z.string().optional(), desktop: z.string().optional(), wide: z.string().optional() }).strict()]))).optional().describe('Site token scales (replaced as a whole): type_size xs/sm/md/lg/xl/2xl/3xl; space none/xs/sm/md/lg/xl in px/rem/em or clamp(min, length + vw, max), or responsive maps; leading tight/snug/normal/relaxed/loose as unitless 1–2. Omitted steps use platform defaults.'),
             colors: z.record(z.string(), z.string().nullable()).optional().describe('Palette: primary, secondary, accent, background, surface, surface_hover, text, text_light (shallow-merged). Optional on_primary, on_secondary, on_accent set the text colour on that theme colour (buttons, badges, tabs, call-to-action sections, styles using the on_* tokens) as a hex colour such as "#ffffff"; null returns to the automatic black or white (chosen by APCA from render version 8, by the WCAG 2 ratio before). A chosen on_* colour applies on every render version. The response lists `on_colors` with each one\'s APCA Lc and WCAG 2 ratio; a choice below APCA Lc 60 (button text, 16px/600) is kept and returned as a warning. Prefer the automatic choice unless the brand specifies a colour.'),
             fonts: z.record(z.string(), z.unknown()).optional().describe('heading, body, mono (Google Fonts family or "system"), size_base (px) and smoothing: "auto" (browser default) or "antialiased" (thinner text on macOS, for light text on dark backgrounds); null clears smoothing. Unset smoothing is auto from render version 6.'),
             contact: z

package/dist/version.js

@@ -8,4 +8,4 @@
 //
 // Keep it in lockstep with package.json: tests/version.test.ts asserts
 // VERSION === package.json.version, so a bump that forgets this line fails CI.
-export const VERSION = '0.45.83';
+export const VERSION = '0.45.85';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typeroll/mcp-server",
-  "version": "0.45.83",
+  "version": "0.45.85",
   "description": "Typeroll CMS MCP server \u2013 connect AI agents to the REST API to manage content and publish static websites.",
   "license": "MIT",
   "repository": {

package/skills/tr-brand.md

@@ -367,3 +367,26 @@ Open in browser. Check:
   phantom margins inside the wrapper — visible as white bands above and
   below the photo. Zero it explicitly in your figure CSS:
   `.my-figure img { margin: 0; border-radius: 0 }`.
+
+## Fluid typography and component rhythm
+
+Core 0.2.114 / MCP 0.45.85 / capabilities 0.55.0 adds responsive scales.
+Check the connected versions before using this contract. New sites use render
+version 10. For an existing site, test a Version first; upgrading rendering
+and replacing existing roles are separate, deliberate choices.
+
+Use `fonts.size_base` (default 16), `typography.ratio_mobile` (1.2),
+`typography.ratio_desktop` (1.25), `typography.rhythm` (1), and
+`typography.line_length` (65 ch). Set the controls once, then use named type,
+spacing and line-height steps. `apply_standard_styles` uses those steps;
+`overwrite: true` resets existing roles, so review their current values first.
+Explicit sizes and breakpoint overrides still win and are not silently migrated.
+
+Heading role margins belong to editorial flow. Component titles use their own
+padding/gap, and opening headings in containers/sections add no top margin.
+Use role-linked `core/heading` size `auto` or `theme`; explicit hero sizes remain
+deliberate exceptions. Do not compensate with per-card negative margins.
+Compare 375, 768 and 1280px in Site settings → Design and in a full site preview.
+After a rendering upgrade/rebuild, recheck cards, boxed headings, leading text
+and webfonts. Boxes should get their outer air from padding. Keep exceptions
+in decisions.md, and run lint_design_tokens before launch.

package/skills/tr-migrate-wp.md

@@ -429,3 +429,26 @@ DNS, explicitly prepare the last published snapshot for the future hosts with
 traffic separately. If newer content is published while the candidate waits,
 prepare again before cutover; do not overwrite it with an outdated snapshot. Respect preserve/renew choices for owner-supplied facts;
 "timeless" wording must not invent recurring events or erase preserved copy.
+
+## Fluid typography and component rhythm
+
+Core 0.2.114 / MCP 0.45.85 / capabilities 0.55.0 adds responsive scales.
+Check the connected versions before using this contract. New sites use render
+version 10. For an existing site, test a Version first; upgrading rendering
+and replacing existing roles are separate, deliberate choices.
+
+Use `fonts.size_base` (default 16), `typography.ratio_mobile` (1.2),
+`typography.ratio_desktop` (1.25), `typography.rhythm` (1), and
+`typography.line_length` (65 ch). Set the controls once, then use named type,
+spacing and line-height steps. `apply_standard_styles` uses those steps;
+`overwrite: true` resets existing roles, so review their current values first.
+Explicit sizes and breakpoint overrides still win and are not silently migrated.
+
+Heading role margins belong to editorial flow. Component titles use their own
+padding/gap, and opening headings in containers/sections add no top margin.
+Use role-linked `core/heading` size `auto` or `theme`; explicit hero sizes remain
+deliberate exceptions. Do not compensate with per-card negative margins.
+Compare 375, 768 and 1280px in Site settings → Design and in a full site preview.
+After a rendering upgrade/rebuild, recheck cards, boxed headings, leading text
+and webfonts. Boxes should get their outer air from padding. Keep exceptions
+in decisions.md, and run lint_design_tokens before launch.

package/skills/tr-new-site.md

@@ -437,3 +437,26 @@ For migrated legacy pages or a hand-crafted one-off, `content_mode:
 ## Organization access
 
 When a Cloud write reports `organization_trial_ended` or `organization_access_ended`, use `read_organization_access` on the selected Site. Explain the deadline and recovery URL; keep reads and export available when permitted. Do not repeatedly retry or create another organization to bypass the lock. Self-hosted installations are unrestricted by default. A trial does not limit AI credits: the organization supplies its own provider key.
+
+## Fluid typography and component rhythm
+
+Core 0.2.114 / MCP 0.45.85 / capabilities 0.55.0 adds responsive scales.
+Check the connected versions before using this contract. New sites use render
+version 10. For an existing site, test a Version first; upgrading rendering
+and replacing existing roles are separate, deliberate choices.
+
+Use `fonts.size_base` (default 16), `typography.ratio_mobile` (1.2),
+`typography.ratio_desktop` (1.25), `typography.rhythm` (1), and
+`typography.line_length` (65 ch). Set the controls once, then use named type,
+spacing and line-height steps. `apply_standard_styles` uses those steps;
+`overwrite: true` resets existing roles, so review their current values first.
+Explicit sizes and breakpoint overrides still win and are not silently migrated.
+
+Heading role margins belong to editorial flow. Component titles use their own
+padding/gap, and opening headings in containers/sections add no top margin.
+Use role-linked `core/heading` size `auto` or `theme`; explicit hero sizes remain
+deliberate exceptions. Do not compensate with per-card negative margins.
+Compare 375, 768 and 1280px in Site settings → Design and in a full site preview.
+After a rendering upgrade/rebuild, recheck cards, boxed headings, leading text
+and webfonts. Boxes should get their outer air from padding. Keep exceptions
+in decisions.md, and run lint_design_tokens before launch.

package/skills/tr-starter-design.md

@@ -113,3 +113,26 @@ uses the same color-mix() recipe as the header.
   match what's already there.
 - Choosing a new palette or fonts is brand work (the MCP recipe `tr-brand`),
   not this reference.
+
+## Fluid typography and component rhythm
+
+Core 0.2.114 / MCP 0.45.85 / capabilities 0.55.0 adds responsive scales.
+Check the connected versions before using this contract. New sites use render
+version 10. For an existing site, test a Version first; upgrading rendering
+and replacing existing roles are separate, deliberate choices.
+
+Use `fonts.size_base` (default 16), `typography.ratio_mobile` (1.2),
+`typography.ratio_desktop` (1.25), `typography.rhythm` (1), and
+`typography.line_length` (65 ch). Set the controls once, then use named type,
+spacing and line-height steps. `apply_standard_styles` uses those steps;
+`overwrite: true` resets existing roles, so review their current values first.
+Explicit sizes and breakpoint overrides still win and are not silently migrated.
+
+Heading role margins belong to editorial flow. Component titles use their own
+padding/gap, and opening headings in containers/sections add no top margin.
+Use role-linked `core/heading` size `auto` or `theme`; explicit hero sizes remain
+deliberate exceptions. Do not compensate with per-card negative margins.
+Compare 375, 768 and 1280px in Site settings → Design and in a full site preview.
+After a rendering upgrade/rebuild, recheck cards, boxed headings, leading text
+and webfonts. Boxes should get their outer air from padding. Keep exceptions
+in decisions.md, and run lint_design_tokens before launch.

package/workspace-templates/qa/checklist.md

@@ -57,3 +57,9 @@ Follow workflows/page-notes.md and pages/README.md. Create notes during migratio
 read before edits, update afterward, check external links at each editorial review,
 and archive notes for confirmed removed Pages under pages/archived/. Refreshing
 generated facts never counts as a completed review. Keep notes out of public output.
+
+- After a Core rendering upgrade, compare typography and spacing at 375, 768
+  and 1280px. Opening headings in cards, boxes and sections must not add the
+  editorial heading's top margin. Check actual fonts as well as the Site settings
+  scale preview. Run `node scripts/typeroll/check_heading_spacing.cjs <origin>`
+  and review deliberate exceptions in decisions.md.

package/workspace-templates/scripts/README.md

@@ -117,3 +117,12 @@ See workflows/source-media.md for archive verification and original preservation
 Omit --dry-run to write local files; --migration-inventory adds recorded redirect
 sources. It never writes to the CMS, marks a Page reviewed or deletes notes. Read
 pages/README.md and workflows/page-notes.md before first use.
+
+### Heading rhythm after a rebuild
+
+`node scripts/typeroll/check_heading_spacing.cjs https://example.com [paths.json]`
+checks opening component headings and card spacing at 375, 768 and 1280px.
+`paths.json` is an array of same-origin page paths; otherwise it reads a flat
+sitemap. Requires Playwright and its Chromium browser. Findings need visual
+review: deliberate asymmetric cards belong in decisions.md. It is a read-only
+QA helper, not a publication gate or a CSS repair tool.

package/workspace-templates/scripts/typeroll/check_heading_spacing.cjs

@@ -0,0 +1,49 @@
+// Read-only component rhythm QA. Deliberate exceptions require visual review.
+const { chromium } = require('playwright');
+const fs = require('node:fs');
+async function main() {
+  const origin = new URL(process.argv[2]);
+  if (!['http:', 'https:'].includes(origin.protocol) || origin.username || origin.password) throw Error('Use an http(s) origin without credentials.');
+  const browser = await chromium.launch();
+  try {
+    const page = await browser.newPage();
+    let paths;
+    if (process.argv[3]) paths = JSON.parse(fs.readFileSync(process.argv[3], 'utf8'));
+    else {
+      const response = await page.request.get(new URL('/sitemap.xml', origin).href);
+      if (!response.ok()) throw Error(`Sitemap returned ${response.status()}`);
+      const xml = await response.text();
+      if (xml.includes('<sitemapindex')) throw Error('Provide paths.json for a sitemap index.');
+      paths = [...xml.matchAll(/<loc>([^<]+)<\/loc>/g)].map(m => m[1].replace(/&amp;/g,'&'));
+    }
+    if (!Array.isArray(paths) || !paths.length || paths.some(p => typeof p !== 'string' || new URL(p,origin).origin !== origin.origin)) throw Error('Provide a nonempty array of same-origin paths.');
+    let count = 0;
+    for (const width of [375,768,1280]) {
+      await page.setViewportSize({width,height:900});
+      for (const path of [...new Set(paths)]) {
+        await page.goto(new URL(path,origin).href,{waitUntil:'domcontentloaded'});
+        await page.evaluate(()=>document.fonts.ready);
+        const findings=await page.evaluate(()=>{
+          const found=[];
+          const roots=document.querySelectorAll('[data-block="container"], .block-section-inner, [data-block="post_card"] [class*="postcard-body"], [data-block="icon_box"]');
+          for(const root of roots) {
+            const visible=[...root.children].filter(e=>e.getBoundingClientRect().height>0);
+            const first=visible[0];
+            const heading=first?.matches('h1,h2,h3,h4,h5,h6')?first:first?.matches('[data-block="heading"],hgroup')?first.querySelector('h1,h2,h3,h4,h5,h6'):null;
+            if(heading && parseFloat(getComputedStyle(heading).marginBlockStart)>1) found.push({kind:'opening_heading_margin',block:root.closest('[data-block]')?.getAttribute('data-block'),text:heading.textContent.slice(0,80),px:parseFloat(getComputedStyle(heading).marginBlockStart)});
+            if(root.closest('[data-block="post_card"]') && visible.length) {
+              const rect=root.getBoundingClientRect(),top=visible[0].getBoundingClientRect().top-rect.top,bottom=rect.bottom-visible.at(-1).getBoundingClientRect().bottom;
+              if(top>bottom+4) found.push({kind:'asymmetric_card',top:Math.round(top),bottom:Math.round(bottom)});
+            }
+          }
+          return found;
+        });
+        count+=findings.length;
+        if(findings.length) console.log(JSON.stringify({path:new URL(path,origin).pathname,width,findings}));
+      }
+    }
+    console.log(JSON.stringify({pages:paths.length,widths:[375,768,1280],findings:count}));
+    process.exitCode=count?1:0;
+  } finally {await browser.close();}
+}
+main().catch(error=>{console.error(error.message);process.exitCode=2;});

package/workspace-templates/workflows/design.md

@@ -63,3 +63,26 @@ review the plan before applying it in a dedicated Version. Equal hex values can
 mean different roles: never automatically choose between background and text.
 Verify a primary/surface change in a test Version across header, footer, cards,
 menus and buttons, then restore the test settings. Do not republish automatically.
+
+## Fluid typography and component rhythm
+
+Core 0.2.114 / MCP 0.45.85 / capabilities 0.55.0 adds responsive scales.
+Check the connected versions before using this contract. New sites use render
+version 10. For an existing site, test a Version first; upgrading rendering
+and replacing existing roles are separate, deliberate choices.
+
+Use `fonts.size_base` (default 16), `typography.ratio_mobile` (1.2),
+`typography.ratio_desktop` (1.25), `typography.rhythm` (1), and
+`typography.line_length` (65 ch). Set the controls once, then use named type,
+spacing and line-height steps. `apply_standard_styles` uses those steps;
+`overwrite: true` resets existing roles, so review their current values first.
+Explicit sizes and breakpoint overrides still win and are not silently migrated.
+
+Heading role margins belong to editorial flow. Component titles use their own
+padding/gap, and opening headings in containers/sections add no top margin.
+Use role-linked `core/heading` size `auto` or `theme`; explicit hero sizes remain
+deliberate exceptions. Do not compensate with per-card negative margins.
+Compare 375, 768 and 1280px in Site settings → Design and in a full site preview.
+After a rendering upgrade/rebuild, recheck cards, boxed headings, leading text
+and webfonts. Boxes should get their outer air from padding. Keep exceptions
+in decisions.md, and run lint_design_tokens before launch.

package/workspace-templates/workflows/migration.md

@@ -134,3 +134,26 @@ Follow workflows/page-notes.md and pages/README.md. Create notes during migratio
 read before edits, update afterward, check external links at each editorial review,
 and archive notes for confirmed removed Pages under pages/archived/. Refreshing
 generated facts never counts as a completed review. Keep notes out of public output.
+
+## Fluid typography and component rhythm
+
+Core 0.2.114 / MCP 0.45.85 / capabilities 0.55.0 adds responsive scales.
+Check the connected versions before using this contract. New sites use render
+version 10. For an existing site, test a Version first; upgrading rendering
+and replacing existing roles are separate, deliberate choices.
+
+Use `fonts.size_base` (default 16), `typography.ratio_mobile` (1.2),
+`typography.ratio_desktop` (1.25), `typography.rhythm` (1), and
+`typography.line_length` (65 ch). Set the controls once, then use named type,
+spacing and line-height steps. `apply_standard_styles` uses those steps;
+`overwrite: true` resets existing roles, so review their current values first.
+Explicit sizes and breakpoint overrides still win and are not silently migrated.
+
+Heading role margins belong to editorial flow. Component titles use their own
+padding/gap, and opening headings in containers/sections add no top margin.
+Use role-linked `core/heading` size `auto` or `theme`; explicit hero sizes remain
+deliberate exceptions. Do not compensate with per-card negative margins.
+Compare 375, 768 and 1280px in Site settings → Design and in a full site preview.
+After a rendering upgrade/rebuild, recheck cards, boxed headings, leading text
+and webfonts. Boxes should get their outer air from padding. Keep exceptions
+in decisions.md, and run lint_design_tokens before launch.