Skip to content

Agent skill for creative 3D visualization: turn an idea into a Three.js/Blender scene worth exploring. Claude Code + Codex plugin, 223 recipes, 440 knowledge records, 22 proved kits, 37 runnable studies.

13.7 KB
Raw Blame
#!/usr/bin/env python3
"""Turn one blueprint record into four real captures, a proof log and a check-run event.

It records what headless Chromium drew. It never judges whether the blueprint looks good:
that judgement belongs to a person looking at the four PNGs it writes.
exit codes: 0 ok · 2 usage · 3 playwright or three tree missing · 4 ready-flag timeout
            5 two view captures are byte-identical (the framing collapsed, or with
              --motion-check the blueprint never moved)
"""
import argparse
import hashlib
import importlib.util
import json
from pathlib import Path
import subprocess
import sys
import tempfile

ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(ROOT / 'scripts'))
from blueprint_validation import SKILL, asset_ref, validate_blueprint  # noqa: E402
from kit_proof_harness import (INSTALL_HINT, build_scratch, find_three, node_check,  # noqa: E402
                               surface_settings, three_version)

VIEWS = ('far', 'mid', 'close', 'detail')
CHANGE_ID = 'kits-blueprints'
TIER_CHANGE_ID = 'kits-quality-tiers'
PROOF_TIERS = ('T0', 'T1', 'T2', 'T3')


def load_module(path, name):
    spec = importlib.util.spec_from_file_location(name, path)
    module = importlib.util.module_from_spec(spec)
    spec.loader.exec_module(module)
    return module


capture = load_module(ROOT / SKILL / 'scripts/capture.py', 'scene_capture')


def parse_args(argv=None):
    parser = argparse.ArgumentParser(description=__doc__,
                                     formatter_class=argparse.RawDescriptionHelpFormatter)
    parser.add_argument('--record', help='blueprint record ID')
    parser.add_argument('--root', type=Path, default=ROOT)
    parser.add_argument('--three-dir', help='installed three tree to vendor from')
    parser.add_argument('--scratch', help='scratch directory; temporary by default')
    parser.add_argument('--tier', choices=PROOF_TIERS, default='T1',
                        help='quality tier to build and capture. T1 (default) is the record\'s own '
                             'module and keeps today\'s output directory, check id and change id; '
                             'any other tier writes evidence/kits/<id>/<tier>/ and its own log.')
    parser.add_argument('--change-id', default=None,
                        help=f'evidence change id (default: {CHANGE_ID} at T1, '
                             f'{TIER_CHANGE_ID} otherwise)')
    parser.add_argument('--actor', default='kit-proof')
    parser.add_argument('--width', type=int, default=1280)
    parser.add_argument('--height', type=int, default=720)
    parser.add_argument('--timeout-s', type=int, default=60)
    parser.add_argument('--settle-ms', type=int, default=350)
    parser.add_argument('--motion-check', type=int, default=0, metavar='MS',
                        help='for a blueprint exposing animate(dt): re-shoot the close view '
                             'after advancing MS of simulated time, writing close-motion.png '
                             '(0 = off). The advance is in fixed 1/60 s steps, so it is '
                             'reproducible; a frozen blueprint exits 5.')
    parser.add_argument('--gpu', action='store_true',
                        help="launch chromium on the platform's ANGLE backend (capture.py's "
                             'shared launcher); the observed renderer is logged either way')
    parser.add_argument('--check-tag', default='', metavar='TAG',
                        help='suffix for the check id (lowercase), so a re-proof of an unchanged '
                             'record after a kit fix gets its own event instead of a duplicate id')
    parser.add_argument('--no-evidence', action='store_true', help='skip the check-run event')
    parser.add_argument('--syntax-only', action='store_true', help='node --check the kits')
    return parser.parse_args(argv)


def pick_record(root, record_id):
    """Read the record through the installed-catalog loader, then check its blueprint shape.

    The contract loader would refuse the record until its captures exist, which is exactly the
    state a first proof run starts from; `root=None` runs every structural check but no
    filesystem check, so a malformed asset path still cannot reach the scratch directory.
    """
    sys.path.insert(0, str(root / SKILL / 'scripts'))
    from catalog import load_catalog
    _, records, _ = load_catalog(root / SKILL, collection='knowledge')
    by_id = {row['id']: row for row in records}
    if record_id not in by_id:
        raise ValueError(f'{record_id}: unknown knowledge record')
    record = by_id[record_id]
    if record.get('knowledge_kind') != 'blueprint':
        raise ValueError(f'{record_id}: not a blueprint record')
    validate_blueprint(record, by_id, None)
    return record


def show(page, name, settle_ms):
    applied = page.evaluate('n => Boolean(window.__viewer && window.__viewer.setView(n))', name)
    if not applied:
        raise ValueError(f'harness has no view named {name}')
    page.wait_for_timeout(settle_ms)


def shoot_views(page, out, settle_ms):
    """Drive the viewer contract through the four named views. Returns the capture entries."""
    entries = {}
    for name in VIEWS:
        show(page, name, settle_ms)
        entries[name] = capture.shoot(page, out, name, False)
    return entries


def shoot_motion(page, out, settle_ms, motion_ms, before):
    """Re-shoot the close view after `motion_ms` of simulated time, the way capture.py does.

    The advance runs through window.__kitAdvance in fixed 1/60 s steps rather than on the wall
    clock, so close-motion.png is as reproducible as the still it is compared against. Returns
    (entry, motion) or (None, None) when the blueprint exposes no animate(dt).
    """
    if not page.evaluate('window.__kitInfo?.animated === true'):
        return None, None
    show(page, 'close', settle_ms)
    moved = page.evaluate('s => Boolean(window.__kitAdvance(s))', motion_ms / 1000)
    page.wait_for_timeout(settle_ms)
    after = capture.shoot(page, out, 'close-motion', False)
    return after, {'interval_ms': motion_ms, 'simulated': True, 'animate_returned': moved,
                   'differs': before['sha256'] != after['sha256'],
                   'sha_before': before['sha256'], 'sha_after': after['sha256']}


def run_browser(args, url, out, log):
    """Open the served harness, wait for the ready flag and capture. Returns an exit code."""
    from playwright.sync_api import sync_playwright
    with sync_playwright() as driver:
        # One launcher with capture.py: a private copy is how the two drifted apart before.
        browser = capture.launch_chromium(driver, gpu=args.gpu)
        page = browser.new_page(viewport={'width': args.width, 'height': args.height})
        page.on('console', lambda m: m.type == 'error' and log['console_errors'].append(m.text))
        page.on('pageerror', lambda e: log['page_errors'].append(str(e)))
        try:
            page.goto(url, timeout=args.timeout_s * 1000)
            log['webgl_renderer'] = capture.read_renderer(page)
            log['capture_mode'] = capture.capture_mode(log['webgl_renderer'])
            try:
                page.wait_for_function('window.__sceneReady === true',
                                       timeout=args.timeout_s * 1000)
            except Exception:
                return 4
            page.wait_for_timeout(args.settle_ms)
            log['kit'] = page.evaluate('window.__kitInfo ?? null')
            entries = shoot_views(page, out, args.settle_ms)
            if args.motion_check:
                moved, log['motion'] = shoot_motion(page, out, args.settle_ms,
                                                    args.motion_check, entries['close'])
                if moved is not None:
                    entries['close-motion'] = moved
            log['captures'] = {entry['file']: entry['sha256'] for entry in entries.values()}
        finally:
            browser.close()
    return 0


def append_check_run(args, record, log_path):
    """One helper builds both artifact strings, so the curated pass can never cite a different one."""
    slug = record['id'].split('.')[-1].replace('blueprint-', '')
    # A per-tier check id, or a second tier's run would silently replace the first tier's event.
    suffix = '' if args.tier == 'T1' else f'.{args.tier.lower()}'   # IDs are lowercase
    if args.check_tag:
        suffix += f'.{args.check_tag.lower()}'
    command = [sys.executable, str(ROOT / 'scripts/evidence-log.py'), 'check-run',
               '--root', str(args.root), '--change-id', args.change_id, '--record', record['id'],
               '--actor', args.actor, '--actor-kind', 'tool',
               '--check-id', f'kit-proof.{slug}{suffix}.r{record["revision"]}',
               '--method', 'visual',
               '--status', 'passed', '--artifact', asset_ref(record),
               '--output', log_path.relative_to(args.root).as_posix(),
               '--observed-by', 'headless chromium via scripts/kit-proof.py',
               '--observed-result', ', '.join(f'{name}.png' for name in VIEWS)
                                    + ' written at four distinct distances from the record footprint',
               '--summary', f'Captured {record["id"]} at four distances at tier {args.tier} '
                            'with the kit harness.']
    return subprocess.run(command, cwd=ROOT).returncode


def main(argv=None):
    args = parse_args(argv)
    args.change_id = args.change_id or (CHANGE_ID if args.tier == 'T1' else TIER_CHANGE_ID)
    root = args.root.resolve()
    if args.syntax_only:
        ok, report = node_check(root)
        print(report)
        return 0 if ok is not False else 1
    if not args.record:
        print('Usage: --record is required unless --syntax-only is given', file=sys.stderr)
        return 2
    try:
        record = pick_record(root, args.record)
    except (ValueError, OSError, KeyError) as error:
        print(f'Usage: {error}', file=sys.stderr)
        return 2
    three_dir = find_three(root, args.three_dir)
    if three_dir is None:
        print(f'No installed three tree to vendor from. {INSTALL_HINT}', file=sys.stderr)
        return 3
    try:
        from playwright.sync_api import sync_playwright  # noqa: F401
    except ImportError:
        print(f'Playwright is not available. {capture.INSTALL_HINT}', file=sys.stderr)
        return 3
    params = {p['name']: p['default'] for p in record['params']}
    # T1 keeps today's directory so no existing proof log or evidence event moves; every other
    # tier captures into its own, with its own proof-log.json beside its own PNGs.
    out = root / f'evidence/kits/{record["id"]}'
    if args.tier != 'T1':
        out = out / args.tier
    out.mkdir(parents=True, exist_ok=True)
    asset_file = root / SKILL / record['asset']['path']
    log = {'schema_version': 1, 'blueprint_id': record['id'], 'record_revision': record['revision'],
           'asset': record['asset']['path'],
           'asset_sha256': hashlib.sha256(asset_file.read_bytes()).hexdigest(),
           'params': params, 'tier': args.tier, 'kit': None, 'captures': {}, 'motion': None,
           'gpu_requested': args.gpu, 'capture_mode': 'unknown', 'webgl_renderer': None,
           'versions': {'three': three_version(three_dir), 'postprocessing': 'not used',
                        'playwright': capture.playwright_version()},
           'renderer': (f'headless chromium, {args.width}x{args.height}, sRGB output, '
                        'ACESFilmic tone mapping, exposure 1.0, PCF soft shadows, no post'),
           'console_errors': [], 'page_errors': [],
           'started': capture.now(), 'finished': None}
    # T2 draws its surface at build time, so the settings it drew with are part of the proof.
    surface = surface_settings(record) if args.tier == 'T2' else None
    if surface is not None:
        log['surface'] = surface
    holder = tempfile.TemporaryDirectory() if not args.scratch else None
    scratch = build_scratch(root, args.scratch or holder.name, record,
                            json.dumps(params, separators=(',', ':')), three_dir,
                            args.tier, surface)
    url, server = capture.serve(scratch)
    try:
        status = run_browser(args, url, out, log)
    finally:
        server.shutdown()
        server.server_close()
        if holder is not None:
            holder.cleanup()
    log['finished'] = capture.now()
    log_path = out / 'proof-log.json'
    log_path.write_text(json.dumps(log, indent=2) + '\n', encoding='utf-8')
    if status == 4:
        print('window.__sceneReady never became true; harness errors follow', file=sys.stderr)
        for line in log['console_errors'] + log['page_errors']:
            print(f'  {line}', file=sys.stderr)
        return 4
    if log['console_errors'] or log['page_errors']:
        print(f'{len(log["console_errors"] + log["page_errors"])} browser errors; see {log_path}',
              file=sys.stderr)
        return 1
    if log['motion'] and not log['motion']['differs']:
        print(f'close.png and close-motion.png are identical after {args.motion_check} ms of '
              'simulated time; the blueprint is frozen', file=sys.stderr)
        return 5
    digests = list(log['captures'].values())
    if len(set(digests)) != len(digests):
        print('Two view captures are byte-identical; the framing collapsed', file=sys.stderr)
        return 5
    print(f'{len(digests)} captures and proof-log.json in {out.relative_to(root)}; '
          f'capture_mode {log["capture_mode"]}, '
          f'{log["kit"]["triangles"]} triangles, distances '
          f'{json.dumps(log["kit"]["view_distances_m"])}'
          + (f', motion {json.dumps(log["motion"])}' if log['motion'] else ''))
    return 0 if args.no_evidence else append_check_run(args, record, log_path)


if __name__ == '__main__':
    sys.exit(main())