@typeroll/mcp-server 0.45.77 → 0.45.80

package/workspace-templates/scripts/typeroll/color_tokens.py

@@ -0,0 +1,81 @@
+"""Review exact colour-to-token replacements; never publish or edit CSS automatically.
+Dry run: python3 scripts/typeroll/color_tokens.py --plan /tmp/design-token-plan.json
+Apply:   python3 scripts/typeroll/color_tokens.py --apply /tmp/design-token-plan.json
+Apply only on a dedicated non-main Version, with no other editors in that Version.
+The plan contains paths and colour values, not page bodies. Keep it out of Git.
+"""
+import argparse
+import hashlib
+import json
+from pathlib import Path
+import trlib
+
+
+def digest(value):
+    return hashlib.sha256(json.dumps(value, sort_keys=True, separators=(',', ':')).encode()).hexdigest()
+
+
+def snapshot():
+    config = trlib.workspace()
+    report = trlib.call('lint_design_tokens')
+    if (report['site_id'], report['organization_id'], report['version_id']) != (
+            config['site_id'], config['organization_id'], config['version']):
+        raise ValueError('Audit scope does not match typeroll.json')
+    settings = trlib.call('read_site_settings')['settings']
+    return {'scope': {k: config[k] for k in ('portal', 'organization_id', 'site_id', 'version')},
+            'palette_hash': digest(settings.get('colors', {})),
+            'counts_before': report['counts'],
+            'replacements': report['exact_replacements']}, report
+
+
+def apply_plan(plan):
+    current, report = snapshot()
+    if plan['scope'] != current['scope'] or plan['palette_hash'] != current['palette_hash']:
+        raise ValueError('Site, Version or palette changed. Run a new dry run; nothing was written.')
+    if current['scope']['version'] == 'main':
+        raise ValueError('Use a dedicated test Version, review it, then promote normally. main is not supported.')
+    available = {digest(row) for row in current['replacements']}
+    if any(digest(row) not in available for row in plan['replacements']):
+        raise ValueError('A replacement is stale or was edited. Run a new dry run; nothing was written.')
+    targets = {(r['target']['kind'], r['target']['id']) for r in plan['replacements']}
+    for kind, id_ in targets:
+        if kind != 'template' and trlib.call('read_working_copy', {'target': {'kind': kind, 'id': id_}}).get('working_copy'):
+            raise ValueError(f'{kind}:{id_} has an unsaved draft; nothing was written.')
+    applied = 0
+    # Ordinary field patches preserve unrelated data. No retries after uncertain writes.
+    # There is no site-wide lock: stop concurrent editing while this command runs.
+    for row in plan['replacements']:
+        tree = trlib.call('get_page_blocks', {'target': row['target']})
+        block = next((b for b in trlib.walk(tree['blocks']) if b['id'] == row['block_id']), None)
+        if block is None or block.get('data', {}).get(row['field']) != row['before']:
+            raise ValueError(f"Source changed after {applied} replacements. Inspect drafts and run a new dry run.")
+        trlib.call('update_block', {'target': row['target'], 'block_id': row['block_id'], 'data': {row['field']: row['after']}})
+        applied += 1
+    for kind, id_ in targets:
+        if kind != 'template':
+            trlib.call('commit_working_copy', {'target': {'kind': kind, 'id': id_}})
+    after = trlib.call('lint_design_tokens')
+    print(json.dumps({'applied': applied, 'before': plan['counts_before'], 'after': after['counts'],
+                      'published': False, 'next': 'Review preview at all breakpoints before promotion.'}, indent=2))
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    mode = parser.add_mutually_exclusive_group(required=True)
+    mode.add_argument('--plan', type=Path)
+    mode.add_argument('--apply', type=Path)
+    args = parser.parse_args()
+    if args.apply:
+        apply_plan(json.loads(args.apply.read_text()))
+    else:
+        plan, report = snapshot()
+        args.plan.write_text(json.dumps(plan, indent=2) + '\n')
+        args.plan.chmod(0o600)
+        print(json.dumps({'counts': report['counts'], 'proposed_replacements': len(plan['replacements']),
+                          'simulated_color_count_after': report['counts']['hardcoded_color'] - len(plan['replacements']),
+                          'written': False, 'plan': str(args.plan),
+                          'note': 'Review and remove deliberate exceptions from the plan. Ambiguous roles, nested values and CSS require manual review.'}, indent=2))
+
+
+if __name__ == '__main__':
+    main()

package/workspace-templates/scripts/typeroll/compare_text.py

@@ -0,0 +1,59 @@
+"""Compare saved source HTML (or one WP REST record) to a captured target.
+Template titles are included exactly once by explicit source title/target selector.
+This reports differences, never rewrites content or approves a migration.
+"""
+import argparse
+import difflib
+from html.parser import HTMLParser
+import json
+from pathlib import Path
+import re
+
+
+class Text(HTMLParser):
+    def __init__(self):
+        super().__init__(convert_charrefs=True)
+        self.words, self.skip = [], 0
+    def handle_starttag(self, tag, attrs):
+        if tag in ('script', 'style'):
+            self.skip += 1
+        elif tag in ('p', 'div', 'li', 'br', 'h1', 'h2', 'h3', 'h4'):
+            self.words.append(' ')
+    def handle_endtag(self, tag):
+        if tag in ('script', 'style'):
+            self.skip = max(0, self.skip - 1)
+        elif tag in ('p', 'div', 'li', 'h1', 'h2', 'h3', 'h4'):
+            self.words.append(' ')
+    def handle_data(self, value):
+        if not self.skip:
+            self.words.append(value)
+    # HTMLParser excludes comments. Do not strip tags with a regexp.
+
+
+def tokens(value):
+    parser = Text()
+    parser.feed(value)
+    return re.findall(r'\w+|[^\w\s]', ''.join(parser.words))
+
+
+def main():
+    args = argparse.ArgumentParser(description=__doc__)
+    args.add_argument('source', help='HTML fragment or one saved WP REST record (.json)')
+    args.add_argument('target', help='JSON from capture_text.cjs')
+    args.add_argument('--source-title', default='', help='For an HTML source whose title is template-owned')
+    opts = args.parse_args()
+    source = Path(opts.source).read_text()
+    if opts.source.endswith('.json'):
+        record = json.loads(source)
+        source = record['title']['rendered'] + ' ' + record['content']['rendered']
+    else:
+        source = opts.source_title + ' ' + source
+    target = json.loads(Path(opts.target).read_text())
+    before, after = tokens(source), re.findall(r'\w+|[^\w\s]', target['text'])
+    changes = [line for line in difflib.ndiff(before, after) if line.startswith(('+ ', '- '))]
+    print(json.dumps({'source_tokens': len(before), 'target_tokens': len(after), 'changes': changes}, ensure_ascii=False, indent=2))
+    return int(bool(changes))
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

package/workspace-templates/scripts/typeroll/contact_sheet.py

@@ -0,0 +1,20 @@
+"""Tile screenshots into contact sheets for fast visual review of many pages.
+usage: python3 contact_sheet.py <out-prefix> <cols> <tile-width> <png> [<png> ...]
+Each tile shows the top of a screenshot (height = 3.2 x width) labelled with its file name."""
+import sys, os
+from PIL import Image, ImageDraw
+out, cols, tw, files = sys.argv[1], int(sys.argv[2]), int(sys.argv[3]), sys.argv[4:]
+th = int(tw * 3.2)
+per = cols * 2
+for n, start in enumerate(range(0, len(files), per)):
+    chunk = files[start:start + per]
+    sheet = Image.new("RGB", (cols * tw, 2 * (th + 20)), "white")
+    d = ImageDraw.Draw(sheet)
+    for i, f in enumerate(chunk):
+        im = Image.open(f).convert("RGB")
+        im = im.resize((tw, int(im.height * tw / im.width))).crop((0, 0, tw, th))
+        x, y = (i % cols) * tw, (i // cols) * (th + 20)
+        sheet.paste(im, (x, y + 20))
+        d.text((x + 3, y + 3), os.path.basename(f)[:40], fill="red")
+    sheet.save(f"{out}-{n}.png")
+    print(f"{out}-{n}.png")

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

@@ -0,0 +1,33 @@
+// Explain vertical spacing: computed margin/padding/gap of every ancestor of a selector and of the next
+// section down to its first heading. Works on a signed preview link (reads the inner frame) or a public URL.
+// usage: node layout_trace.js <url> [width=390] [selector=h1]
+const qa = require('./browser.cjs');
+const { chromium } = qa;
+(async () => {
+  const [,, url, width = '390', sel = 'h1'] = process.argv;
+  const b = await chromium.launch();
+  const p = await b.newPage({viewport: {width: +width, height: 900}});
+  await qa.open(p, url);
+  const f = p.mainFrame();
+  try { console.log(await f.evaluate((sel) => {
+    const out = [];
+    const show = (lab, el) => {
+      if (!el) return;
+      const c = getComputedStyle(el), r = el.getBoundingClientRect();
+      out.push(`${lab} <${el.tagName.toLowerCase()} ${el.getAttribute('data-block') || String(el.className).slice(0, 40)}> top=${Math.round(r.top)} h=${Math.round(r.height)} margin=${c.marginTop}/${c.marginBottom} padding=${c.paddingTop}/${c.paddingBottom} gap=${c.rowGap} radius=${c.borderRadius}`);
+    };
+    const target = document.querySelector(sel);
+    if (!target) throw Error('Selector not found');
+    const sec = target.closest('[data-block="section"]') || target;
+    const chain = []; for (let a = target; a && a !== document.body; a = a.parentElement) chain.push(a);
+    chain.reverse().forEach((x, i) => show('ancestor' + i, x));
+    for (let s = sec.nextElementSibling; s; s = s.nextElementSibling) {
+      show('next', s);
+      const h = s.querySelector('h1,h2,h3');
+      if (h) { const ch = []; for (let q = h; q && q !== s; q = q.parentElement) ch.push(q); ch.reverse().forEach((x, i) => show('inside' + i, x)); break; }
+    }
+    show('header', document.querySelector('header'));
+    return out.join('\n');
+  }, sel));
+  } finally { await b.close(); }
+})().catch(qa.fail);

package/workspace-templates/scripts/typeroll/prepare_image.py

@@ -0,0 +1,64 @@
+"""Convert a reviewed local original to an sRGB JPEG; never upload or change CMS content.
+Requires Pillow with ImageCms. Preserve the untouched original in the source archive.
+CMYK needs its actual embedded or supplied ICC profile. Never guess a CMYK profile.
+Unprofiled RGB/gray requires --assume-srgb after review. Output must not exist.
+"""
+import argparse
+import hashlib
+import io
+import json
+from pathlib import Path
+
+
+def prepare(source, output, source_profile=None, assume_srgb=False, quality=95):
+    from PIL import Image, ImageCms, ImageOps
+    source, output = Path(source), Path(output)
+    if output.exists() or source.resolve() == output.resolve():
+        raise ValueError('Output already exists; choose a new derivative path.')
+    if output.suffix.lower() not in ('.jpg', '.jpeg'):
+        raise ValueError('Choose a .jpg or .jpeg output.')
+    if not 1 <= quality <= 100:
+        raise ValueError('JPEG quality must be from 1 to 100.')
+    with Image.open(source) as original:
+        if getattr(original, 'n_frames', 1) != 1:
+            raise ValueError('Multi-page/animated originals require an explicit frame decision.')
+        if 'A' in original.getbands() or 'transparency' in original.info:
+            raise ValueError('Transparent originals need a reviewed background or a PNG workflow.')
+        profile_bytes = Path(source_profile).read_bytes() if source_profile else original.info.get('icc_profile')
+        image = ImageOps.exif_transpose(original)
+        target = ImageCms.ImageCmsProfile(ImageCms.createProfile('sRGB'))
+        if profile_bytes:
+            profile = ImageCms.ImageCmsProfile(io.BytesIO(profile_bytes))
+            converted = ImageCms.profileToProfile(image, profile, target, outputMode='RGB')
+        elif image.mode in ('RGB', 'L') and assume_srgb:
+            converted = image.convert('RGB')
+        else:
+            raise ValueError('Missing source ICC profile. CMYK cannot be safely guessed; supply the correct --source-profile. For reviewed unprofiled RGB/gray only, use --assume-srgb.')
+        # No source EXIF/GPS/caption metadata is copied into the public derivative.
+        with output.open('xb') as destination:
+            converted.save(destination, format='JPEG', quality=quality, subsampling=0, icc_profile=target.tobytes())
+    with Image.open(output) as check:
+        check.load()
+        if check.mode != 'RGB' or not check.info.get('icc_profile'):
+            raise ValueError('Output verification failed; do not upload the derivative.')
+        dimensions = list(check.size)
+    return {'source_sha256': hashlib.sha256(source.read_bytes()).hexdigest(),
+            'output_sha256': hashlib.sha256(output.read_bytes()).hexdigest(),
+            'width': dimensions[0], 'height': dimensions[1], 'colour_space': 'sRGB',
+            'source_profile': 'supplied' if source_profile else 'embedded' if profile_bytes else 'assumed sRGB',
+            'uploaded': False}
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('source', type=Path)
+    parser.add_argument('output', type=Path)
+    parser.add_argument('--source-profile', type=Path)
+    parser.add_argument('--assume-srgb', action='store_true')
+    parser.add_argument('--quality', type=int, default=95)
+    args = parser.parse_args()
+    print(json.dumps(prepare(args.source, args.output, args.source_profile, args.assume_srgb, args.quality), indent=2))
+
+
+if __name__ == '__main__':
+    main()

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

@@ -0,0 +1,26 @@
+const qa = require('./browser.cjs');
+const [origin, out, paths, ...args] = process.argv.slice(2);
+(async () => {
+  const browser = await qa.chromium.launch();
+  const report = [];
+  try {
+    for (const route of paths.split(',')) {
+      const url = new URL(route, origin);
+      if (url.origin !== new URL(origin).origin) throw Error('Paths must stay on the selected origin');
+      for (const width of qa.widths(args)) {
+        const page = await browser.newPage({ viewport: { width, height: 900 } });
+        const failed = [];
+        page.on('requestfailed', r => failed.push({ host: new URL(r.url()).hostname, kind: 'network' }));
+        page.on('response', r => { if (r.status() >= 400) failed.push({ host: new URL(r.url()).hostname, status: r.status() }); });
+        await qa.open(page, url.href); await qa.settle(page);
+        const result = { path: route, width, ...await qa.inspect(page), failed };
+        const name = require('node:crypto').createHash('sha256').update(route).digest('hex').slice(0, 12);
+        await qa.screenshot(page, `${out}/${name}-${width}.png`);
+        report.push(result);
+        await page.close();
+      }
+    }
+    console.log(JSON.stringify(report, null, 2));
+    if (report.some(r => r.overflow || r.incompleteImages.length || r.h1 !== 1 || r.failed.length || !r.scrollCoverageComplete)) process.exitCode = 1;
+  } finally { await browser.close(); }
+})().catch(qa.fail);

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

@@ -0,0 +1,16 @@
+const qa = require('./browser.cjs');
+const [out, url, ...args] = process.argv.slice(2);
+(async () => {
+  const browser = await qa.chromium.launch();
+  try {
+    for (const width of qa.widths(args)) {
+      const page = await browser.newPage({ viewport: { width, height: 900 } });
+      const hosts = new Set();
+      page.on('request', r => { try { hosts.add(new URL(r.url()).hostname); } catch {} });
+      await qa.open(page, url); await qa.settle(page);
+      await qa.screenshot(page, `${out}-${width}.png`);
+      console.log(JSON.stringify({ width, ...await qa.inspect(page), hosts: [...hosts] }));
+      await page.close();
+    }
+  } finally { await browser.close(); }
+})().catch(qa.fail);

package/workspace-templates/scripts/typeroll/sweep_blocks.example.py

@@ -0,0 +1,23 @@
+"""Pattern: change one kind of block on every Page, Page template and partial, then save.
+Example: set last_row "start" on every core/grid that centers its last row. Dry run lists; --apply writes.
+Copy and edit MATCH/PATCH for other sweeps. Templates save immediately; Pages and partials must be committed. Refuses existing unsaved work."""
+import os, sys
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import trlib
+SITE = trlib.site_id()
+MATCH = lambda b: b.get("type") == "core/grid" and (b.get("data") or {}).get("last_row") == "center"
+PATCH = {"last_row": "start"}
+apply = "--apply" in sys.argv
+for tgt in trlib.containers():
+    tree = trlib.call("get_page_blocks", {"site_id": SITE, "target": tgt})
+    hits = [b for b in trlib.walk(tree.get("blocks", tree) if isinstance(tree, dict) else tree) if MATCH(b)]
+    if not hits:
+        continue
+    print(tgt["kind"], tgt["id"], len(hits))
+    if apply:
+        if tgt['kind'] != 'template' and trlib.call('read_working_copy', {'target': tgt}).get('working_copy'):
+            raise RuntimeError('Unsaved work exists; review it before this sweep')
+        for b in hits:
+            trlib.call("update_block", {"site_id": SITE, "target": tgt, "block_id": b["id"], "data": PATCH})
+        if tgt["kind"] in ("page", "partial"):
+            trlib.call("commit_working_copy", {"site_id": SITE, "target": tgt})

package/workspace-templates/scripts/typeroll/trlib.py

@@ -0,0 +1,212 @@
+"""Small, version-bound MCP helper. Credentials are injected, never persisted.
+No automatic retries for mutations. Run from the workspace root.
+"""
+import hashlib
+import json
+import os
+from pathlib import Path
+import urllib.error
+import urllib.parse
+import urllib.request
+
+
+class NoRedirect(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, *args, **kwargs):
+        return None  # Never forward Authorization or signed PUTs to another URL.
+
+
+def workspace():
+    for directory in (Path.cwd(), *Path.cwd().parents):
+        file = directory / 'typeroll.json'
+        if file.is_file():
+            value = json.loads(file.read_text())
+            if not all(value.get(k) for k in ('portal', 'organization_id', 'site_id', 'version')):
+                raise ValueError('Complete portal, organization_id, site_id and version in typeroll.json first')
+            origin = urllib.parse.urlsplit(value['portal'])
+            if origin.username or origin.password or origin.query or origin.fragment or origin.path not in ('', '/'):
+                raise ValueError('portal must be a plain origin')
+            if origin.scheme != 'https' and not (origin.scheme == 'http' and origin.hostname in ('localhost', '127.0.0.1', '::1')):
+                raise ValueError('portal requires HTTPS (HTTP is allowed only on loopback)')
+            return value
+    raise ValueError('Run from a workspace containing typeroll.json')
+
+
+class Client:
+    def __init__(self, config=None):
+        self.config = config or workspace()
+        self.url = self.config['portal'].rstrip('/') + '/api/mcp?tools=full'
+        self.session = None
+        self.sequence = 0
+        self.tools = None
+        self.verified = False
+        self.opener = urllib.request.build_opener(NoRedirect)
+
+    def rpc(self, method, params=None, notify=False):
+        self.sequence += 1
+        body = {'jsonrpc': '2.0', 'method': method}
+        if params is not None:
+            body['params'] = params
+        if not notify:
+            body['id'] = self.sequence
+        key = os.environ.get('TYPEROLL_API_KEY')
+        if not key:
+            raise ValueError('Inject TYPEROLL_API_KEY privately before running')
+        headers = {'Authorization': 'Bearer ' + key, 'Content-Type': 'application/json',
+                   'Accept': 'application/json, text/event-stream'}
+        if self.session:
+            headers['Mcp-Session-Id'] = self.session
+        request = urllib.request.Request(self.url, data=json.dumps(body).encode(), headers=headers)
+        try:
+            with self.opener.open(request, timeout=180) as response:
+                self.session = response.headers.get('Mcp-Session-Id') or self.session
+                raw = response.read().decode()
+        except urllib.error.HTTPError as error:
+            raise RuntimeError(f'MCP HTTP {error.code}; no mutation was retried') from None
+        if notify:
+            return None
+        result = decode_rpc(raw, self.sequence)
+        if 'error' in result:
+            raise RuntimeError(f"MCP RPC error {result['error'].get('code')}")
+        return result['result']
+
+    def initialize(self):
+        self.rpc('initialize', {'protocolVersion': '2025-03-26', 'capabilities': {},
+                              'clientInfo': {'name': 'typeroll-workspace', 'version': '1'}})
+        self.rpc('notifications/initialized', notify=True)
+        self.tools = {}
+        cursor = None
+        seen = set()
+        while True:
+            result = self.rpc('tools/list', {'cursor': cursor} if cursor else {})
+            self.tools.update({t['name']: t for t in result['tools']})
+            cursor = result.get('nextCursor')
+            if not cursor:
+                break
+            if cursor in seen:
+                raise RuntimeError('tools/list repeated its cursor')
+            seen.add(cursor)
+
+    def call(self, tool, args=None):
+        if self.tools is None:
+            self.initialize()
+        if tool not in self.tools:
+            raise ValueError(f'Tool unavailable: {tool}')
+        if not self.verified:
+            info = self.invoke('get_site', {})
+            if info.get('organization_id') != self.config['organization_id'] or info.get('id') != self.config['site_id']:
+                raise ValueError('Connected Organization/Site does not match typeroll.json; nothing was written')
+            self.verified = True
+        return self.invoke(tool, args or {})
+
+    def invoke(self, tool, args):
+        props = self.tools[tool]['inputSchema'].get('properties', {})
+        data = dict(args)
+        for key, wanted in [('site_id', self.config['site_id']), ('version', self.config['version'])]:
+            if key in data and data[key] != wanted:
+                raise ValueError(f'{key} differs from typeroll.json; change the binding explicitly')
+            if key in props:
+                data[key] = wanted
+        if 'version' not in props and self.config['version'] != 'main' and tool != 'get_site':
+            raise ValueError(f'{tool} has no version parameter; refusing an implicit main-version operation')
+        result = self.rpc('tools/call', {'name': tool, 'arguments': data})
+        if result.get('isError'):
+            raise RuntimeError(f'{tool} failed; inspect through your authenticated MCP client (no retry)')
+        if 'structuredContent' in result:
+            return result['structuredContent']
+        text = ''.join(c.get('text', '') for c in result.get('content', []) if c.get('type') == 'text')
+        return json.loads(text)
+
+
+def decode_rpc(raw, request_id):
+    if raw.lstrip().startswith('{'):
+        value = json.loads(raw)
+        if value.get('id') != request_id:
+            raise ValueError('MCP response did not contain the matching request ID')
+        return value
+    # Streamable HTTP may include notifications, multiline data, and keepalives.
+    for event in raw.replace('\r\n', '\n').split('\n\n'):
+        data = '\n'.join(line[5:].lstrip() for line in event.splitlines() if line.startswith('data:'))
+        if data:
+            value = json.loads(data)
+            if value.get('id') == request_id:
+                return value
+    raise ValueError('MCP response did not contain the matching request ID')
+
+
+_client = None
+
+
+def call(tool, args=None):
+    global _client
+    if _client is None:
+        _client = Client()
+    return _client.call(tool, args)
+
+
+def site_id():
+    return workspace()['site_id']
+
+
+def walk(blocks):
+    for block in blocks or []:
+        yield block
+        yield from walk(block.get('children'))
+        for slot in block.get('slots') or []:
+            yield from walk(slot)
+
+
+def all_pages():
+    cursor, seen = None, set()
+    while True:
+        args = {'limit': 200, **({'cursor': cursor} if cursor else {})}
+        result = call('list_pages', args)
+        yield from result['pages']
+        cursor = result.get('next_cursor')
+        if not cursor:
+            return
+        if cursor in seen:
+            raise RuntimeError('list_pages repeated its cursor')
+        seen.add(cursor)
+
+
+def all_migration_urls():
+    offset = 0
+    while True:
+        result = call('list_migration_urls', {'limit': 1000, 'offset': offset})
+        rows = result['urls']
+        yield from rows
+        offset += len(rows)
+        if not rows or offset >= result.get('total_matching', float('inf')):
+            return
+
+
+def containers():
+    for page in all_pages():
+        yield {'kind': 'page', 'id': page['id']}
+    for kind, tool, key in [('template', 'list_page_templates', 'templates'), ('partial', 'list_partials', 'partials')]:
+        result = call(tool)
+        rows = result if isinstance(result, list) else result.get(key, result.get('page_templates'))
+        if not isinstance(rows, list):
+            raise ValueError(f'Unexpected response from {tool}')
+        for row in rows:
+            yield {'kind': kind, 'id': row['id']}
+
+
+def upload(file, content_type, alt=''):
+    content = Path(file).read_bytes()
+    sha = hashlib.sha256(content).hexdigest()
+    mint = call('create_upload_url', {'filename': Path(file).name, 'content_type': content_type,
+                                    'size': len(content), 'alt_text': alt})
+    if urllib.parse.urlsplit(mint['upload_url']).scheme != 'https':
+        raise ValueError('Signed upload must use HTTPS')
+    request = urllib.request.Request(mint['upload_url'], data=content, method='PUT', headers={'Content-Type': content_type})
+    try:
+        with urllib.request.build_opener(NoRedirect).open(request, timeout=120) as response:
+            response.read()
+    except Exception:
+        raise RuntimeError('Signed upload failed; URL withheld; no automatic retry') from None
+    result = call('finalize_media', {'media_id': mint['media_id'], 'expected_sha256': sha})
+    evidence = result.get('result', result)
+    if evidence.get('sha256') != sha:
+        raise ValueError('Finalize did not confirm the source SHA-256; do not reference this asset')
+    return {'media_id': mint['media_id'], 'cdn_url': mint['cdn_url'], 'sha256': sha}

package/workspace-templates/workflows/design.md

@@ -0,0 +1,65 @@
+# Layout defaults and owner decisions
+
+Use current native composition starters and block schemas. These defaults are
+starting points, not permission to overwrite an approved design.
+
+- Keep incomplete grid rows left-aligned (`last_row: start`). Never enlarge one
+  peer card just to fill the gap. Center only on an explicit owner request.
+- Prefer `core/navigation_menu` with `core/navigation_links` desktop/mobile slots
+  for a header drawer (below 1024 px). Read tr-header-footer; test 1023/1024 px.
+- Separate dense footer about text from the link grid. Give it a readable width
+  and a larger gap; inspect 390/1024/1280/1536 px. Equal columns need equal density.
+- Sections own gutters. Do not erase side padding with `padding: 3rem 0` when
+  only vertical spacing is intended. Wrap column-slot contents in a flow
+  container with article rhythm when they need vertical block spacing.
+- Give cards one clear destination. Use whole_card_link without action_label
+  or download actions. Check excerpt, image, whitespace and keyboard activation.
+- Do not fade body text with opacity. Verify actual text/background contrast,
+  current links on light/dark navigation, and all states.
+- Preserve image subjects across widths. Choose contain/original sizing when
+  cropping or upscaling is not intended. Hero crop, text placement, plates,
+  corner treatment and category-page composition are project decisions in
+  brief/brand.md, not a universal design.
+- After migration, check heading hierarchy, unchanged preserved text, HTML
+  comments, links with ../, and the home SEO title/suffix. Shared headings and
+  titles must not be duplicated in body content.
+
+Record deliberate departures in decisions.md with scope and owner approval.
+Use a QA round per review: method, pages/viewports, expected differences, results,
+unverified items and remaining defects. Record platform findings in
+qa/typeroll-platform-feedback.md; do not bury them in workaround CSS.
+
+## Site tokens before block overrides
+
+Core 0.2.106 / template capabilities 0.54.0 adds palette names in all colour
+fields and named typography/spacing steps. Check the connected capability
+version; on older renderers use `var(--color-surface)` rather than a bare name.
+
+Set colours and font families in site settings, then use named styles and
+palette names in blocks. Do not write hex, rgb or font-family literals in block
+content. Prefer `primary`, `secondary`, `accent`, `background`, `surface`, `text`,
+`text_light`, and `on_primary`/`on_secondary`/`on_accent` for text on brand colours.
+Use `surface_hover` for a darker interactive surface (derived automatically
+unless explicitly configured). Existing semantic roles should be reused; a
+new visual shade is not automatically a new semantic role. For a derived shade
+use `color-mix(in srgb, var(--color-surface) 92%, var(--color-primary))`.
+For an additional role not in the native palette, define a named site style
+or a site CSS variable derived from existing palette variables, and document it.
+
+Choose `heading`, `body` or `mono` for fonts. Font families belong only in the
+site's `fonts` settings. Use type-size steps `xs`, `sm`, `md`, `lg`, `xl`, `2xl`,
+`3xl`; spacing `none`, `xs`, `sm`, `md`, `lg`, `xl`; line height `tight`, `snug`,
+`normal`, `relaxed`, `loose`. Presentation fields accept responsive maps of these
+names, for example `font_size_px: {mobile: "md", desktop: "lg"}`. Read the field
+schema: counts, widths and breakpoints are not spacing steps. Pixel values are
+explicit exceptions, not the default authoring method. Configure scales in
+`design_scales`, then reuse them in role styles and blocks.
+
+Record deliberate exceptions in `decisions.md`, with source/block, reason and
+review criteria (for example white text on a photograph). Run `lint_design_tokens`
+before launch and after major design changes. It warns, never blocks launch.
+Use the starter's `scripts/typeroll/color_tokens.py` for an exact-match dry run;
+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.