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.
"""showcase.py drives capture.py; these tests never launch a browser.
`showcase.capture` is replaced by a stub that writes a file of a chosen size, so the schema, the
resume rule, the budget stop, the quality ladder, the lock and the output-path refusal are all
exercised without a GPU, without Playwright and without touching docs/demos/showcase/.
"""
import contextlib
import importlib.util
import io
import json
from pathlib import Path
import tempfile
import unittest
from unittest import mock
ROOT = Path(__file__).resolve().parents[1]
spec = importlib.util.spec_from_file_location('showcase', ROOT / 'scripts/showcase.py')
showcase = importlib.util.module_from_spec(spec)
spec.loader.exec_module(showcase)
SHOT = {'id': 'a-shot', 'source': 'example:village', 'view': 'overview', 'look': 'knowledge.style-painterly',
'caption': 'a caption'}
MANIFEST = {'schema_version': 1, 'defaults': {'width': 1920, 'height': 1080, 'format': 'jpeg',
'max_bytes': 1000, 'settle_ms': 1400},
'shots': [SHOT]}
CAPTURE_LOG = {'capture_mode': 'gpu', 'webgl_renderer': 'ANGLE (Apple, ANGLE Metal Renderer)',
'views': [{'name': 'overview', 'file': 'overview.jpg', 'requested': 'overview',
'applied': True}]}
def write_manifest(directory, data=MANIFEST):
path = Path(directory) / 'showcase.json'
path.write_text(json.dumps(data), encoding='utf-8')
return path
def fake_capture(sizes):
"""A capture stub: `sizes` maps jpeg quality to the byte count that quality would produce."""
def capture(python, built, cfg, quality, staging):
staging = Path(staging)
staging.mkdir(parents=True, exist_ok=True)
frame = staging / 'overview.jpg'
frame.write_bytes(b'\xff' * sizes[quality])
return frame, dict(CAPTURE_LOG)
return capture
class ManifestTests(unittest.TestCase):
def test_shipped_manifest_is_valid_and_complete(self):
data = json.loads(showcase.HISTORICAL_MANIFEST.read_text(encoding='utf-8'))
ids = [shot['id'] for shot in data['shots']]
self.assertEqual(len(ids), 21) # 20 authored, heart dropped, cargo yard swapped for three village looks
self.assertEqual(len(set(ids)), 21)
for shot in data['shots']:
self.assertTrue(shot['caption'].strip(), shot['id'])
self.assertIn('look_applied', shot, shot['id'])
self.assertTrue(shot['source'], shot['id'])
def test_no_shot_claims_a_tier_the_manifest_did_not_name(self):
data = json.loads(showcase.HISTORICAL_MANIFEST.read_text(encoding='utf-8'))
for shot in data['shots']:
for role, tier in (shot.get('tiers') or {}).items():
self.assertIn(tier, ('T0', 'T1', 'T2', 'T3', 'T4'), f'{shot["id"]}.{role}')
def test_schema_version_must_be_one(self):
with tempfile.TemporaryDirectory() as directory:
path = write_manifest(directory, {**MANIFEST, 'schema_version': 2})
with self.assertRaisesRegex(ValueError, 'schema_version 1'):
showcase.load_manifest(path)
def test_missing_required_key_is_named(self):
with tempfile.TemporaryDirectory() as directory:
broken = {**MANIFEST, 'shots': [{k: v for k, v in SHOT.items() if k != 'look'}]}
with self.assertRaisesRegex(ValueError, 'missing look'):
showcase.load_manifest(write_manifest(directory, broken))
def test_duplicate_id_is_refused(self):
with tempfile.TemporaryDirectory() as directory:
broken = {**MANIFEST, 'shots': [SHOT, SHOT]}
with self.assertRaisesRegex(ValueError, 'duplicate shot id'):
showcase.load_manifest(write_manifest(directory, broken))
def test_unknown_source_is_refused(self):
with tempfile.TemporaryDirectory() as directory:
broken = {**MANIFEST, 'shots': [{**SHOT, 'source': 'somewhere-else'}]}
with self.assertRaisesRegex(ValueError, 'unknown source'):
showcase.load_manifest(write_manifest(directory, broken))
def test_standalone_example_id_requires_kebab_case(self):
for source in ('example:', 'example:Heart', 'example:heart/detail', 'example:heart_space'):
with self.subTest(source=source), self.assertRaisesRegex(ValueError, 'invalid'):
showcase.example_id(source)
self.assertEqual(showcase.example_id('example:muscle-atlas'), 'muscle-atlas')
def test_shot_id_cannot_escape_the_output_directory(self):
with tempfile.TemporaryDirectory() as directory:
broken = {**MANIFEST, 'shots': [{**SHOT, 'id': '../historical-frame'}]}
with self.assertRaisesRegex(ValueError, 'invalid shot id'):
showcase.load_manifest(write_manifest(directory, broken))
def test_harness_source_restricts_record_and_tier(self):
self.assertEqual(showcase.harness_parts('harness:knowledge.blueprint-well@T2'),
('knowledge.blueprint-well', 'T2'))
for source in ('harness:knowledge.blueprint-well@../../escape',
'harness:recipe.well@T2', 'harness:knowledge.blueprint-well@T4',
'harness:knowledge.blueprint-well@T9'):
with self.subTest(source=source), self.assertRaisesRegex(ValueError, 'invalid'):
showcase.harness_parts(source)
def test_malformed_shot_types_are_usage_errors(self):
with tempfile.TemporaryDirectory() as directory:
for shot in ('not-an-object', {**SHOT, 'source': 42}):
with self.subTest(shot=shot), self.assertRaises(ValueError):
showcase.load_manifest(write_manifest(directory, {**MANIFEST, 'shots': [shot]}))
def test_settings_layer_shot_over_defaults(self):
cfg = showcase.settings(MANIFEST, {**SHOT, 'settle_ms': 50, 'motion_ms': 900})
self.assertEqual(cfg['settle_ms'], 50)
self.assertEqual(cfg['motion_ms'], 900)
self.assertEqual(cfg['width'], 1920)
self.assertNotIn('caption', cfg)
class ResumeTests(unittest.TestCase):
def setUp(self):
self.directory = tempfile.TemporaryDirectory()
self.out = Path(self.directory.name)
self.addCleanup(self.directory.cleanup)
self.log = {'shots': [{'id': 'a-shot',
'config_sha256': showcase.shot_fingerprint(MANIFEST, SHOT)}]}
def test_image_and_log_entry_together_mean_done(self):
(self.out / 'a-shot.jpg').write_bytes(b'x')
self.assertEqual(showcase.pending(MANIFEST, self.log, self.out), [])
def test_log_entry_without_image_is_still_pending(self):
self.assertEqual(len(showcase.pending(MANIFEST, self.log, self.out)), 1)
def test_image_without_log_entry_is_still_pending(self):
(self.out / 'a-shot.jpg').write_bytes(b'x')
self.assertEqual(len(showcase.pending(MANIFEST, {'shots': []}, self.out)), 1)
def test_force_re_renders_a_finished_shot(self):
(self.out / 'a-shot.jpg').write_bytes(b'x')
self.assertEqual(len(showcase.pending(MANIFEST, self.log, self.out, force=True)), 1)
def test_changed_shot_configuration_is_not_reused(self):
(self.out / 'a-shot.jpg').write_bytes(b'x')
changed = {**MANIFEST, 'shots': [{**SHOT, 'look': 'knowledge.style-clay'}]}
self.assertEqual(len(showcase.pending(changed, self.log, self.out)), 1)
def test_only_selects_one_shot(self):
many = {**MANIFEST, 'shots': [SHOT, {**SHOT, 'id': 'b-shot'}]}
todo = showcase.pending(many, {'shots': []}, self.out, only='b-shot')
self.assertEqual([shot['id'] for shot in todo], ['b-shot'])
class QualityLadderTests(unittest.TestCase):
def setUp(self):
self.directory = tempfile.TemporaryDirectory()
self.out = Path(self.directory.name)
self.addCleanup(self.directory.cleanup)
self.cfg = showcase.settings(MANIFEST, SHOT)
def render(self, sizes):
with mock.patch.object(showcase, 'capture', fake_capture(sizes)):
return showcase.render('python3', SHOT, self.cfg, Path('built'), self.out,
self.out / 'staging')
def test_first_quality_wins_when_it_fits(self):
entry = self.render({88: 900, 80: 500, 72: 300})
self.assertEqual(entry['quality'], 88)
self.assertEqual(entry['bytes'], 900)
self.assertEqual([attempt['quality'] for attempt in entry['attempts']], [88])
self.assertTrue((self.out / 'a-shot.jpg').is_file())
def test_ladder_steps_down_until_the_frame_fits(self):
entry = self.render({88: 1400, 80: 1100, 72: 700})
self.assertEqual(entry['quality'], 72)
self.assertEqual([attempt['quality'] for attempt in entry['attempts']], [88, 80, 72])
def test_a_frame_over_the_cap_at_the_last_step_fails_loudly(self):
with self.assertRaisesRegex(RuntimeError, 'over the 1000 byte cap'):
self.render({88: 3000, 80: 2000, 72: 1500})
self.assertFalse((self.out / 'a-shot.jpg').exists())
def test_png_does_not_walk_a_jpeg_ladder(self):
self.cfg = showcase.settings(MANIFEST, {**SHOT, 'format': 'png'})
with self.assertRaises(RuntimeError):
self.render({88: 3000, 80: 100, 72: 100})
def test_entry_records_the_evidence_fields(self):
entry = self.render({88: 500})
self.assertEqual(entry['capture_mode'], 'gpu')
self.assertEqual(entry['webgl_renderer'], CAPTURE_LOG['webgl_renderer'])
self.assertEqual(entry['look'], SHOT['look'])
self.assertEqual(entry['view'], 'overview')
self.assertEqual(len(entry['sha256']), 64)
self.assertIn('1920x1080', entry['renderer'])
self.assertIn('q88', entry['renderer'])
self.assertIsInstance(entry['seconds'], float)
class LockTests(unittest.TestCase):
def test_lock_is_written_and_removed(self):
with tempfile.TemporaryDirectory() as directory:
lock = Path(directory) / '.run.lock'
with showcase.run_lock(lock):
self.assertTrue(lock.is_file())
self.assertTrue(lock.read_text(encoding='utf-8').strip().isdigit())
self.assertFalse(lock.exists())
def test_a_second_run_is_refused_while_the_lock_is_held(self):
with tempfile.TemporaryDirectory() as directory:
lock = Path(directory) / '.run.lock'
with showcase.run_lock(lock):
with self.assertRaisesRegex(RuntimeError, 'holds the machine'):
with showcase.run_lock(lock):
pass
self.assertFalse(lock.exists())
def test_the_lock_is_released_when_the_body_raises(self):
with tempfile.TemporaryDirectory() as directory:
lock = Path(directory) / '.run.lock'
with contextlib.suppress(KeyError), showcase.run_lock(lock):
raise KeyError('a shot blew up')
self.assertFalse(lock.exists())
class OutPathTests(unittest.TestCase):
def test_the_historical_showcase_directory_is_refused(self):
with self.assertRaisesRegex(ValueError, 'gallery root is historical'):
showcase.resolve_out(str(showcase.OUT))
def test_a_subdirectory_is_accepted(self):
self.assertEqual(showcase.resolve_out(str(showcase.OUT / 'draft')), showcase.OUT / 'draft')
def test_the_retired_breadth_directory_is_refused(self):
with self.assertRaisesRegex(ValueError, 'reserved for historical artifacts'):
showcase.resolve_out(str(showcase.OUT / 'breadth'))
def test_a_populated_non_run_directory_is_refused(self):
with tempfile.TemporaryDirectory(dir=showcase.OUT) as directory:
(Path(directory) / 'existing.jpg').write_bytes(b'historical')
with self.assertRaisesRegex(ValueError, 'populated but is not a resumable'):
showcase.resolve_out(directory)
def test_anywhere_else_is_refused(self):
with tempfile.TemporaryDirectory() as directory:
with self.assertRaisesRegex(ValueError, 'is outside'):
showcase.resolve_out(directory)
def test_main_refuses_an_outside_out_and_writes_nothing(self):
with tempfile.TemporaryDirectory() as directory:
stderr = io.StringIO()
with contextlib.redirect_stderr(stderr):
status = showcase.main(['--manifest', str(showcase.HISTORICAL_MANIFEST),
'--out', directory])
self.assertEqual(status, 2)
self.assertEqual(list(Path(directory).iterdir()), [])
class RunTests(unittest.TestCase):
"""main() end to end with the capture subprocess and the source build stubbed out."""
def setUp(self):
self.directory = tempfile.TemporaryDirectory()
self.base = Path(self.directory.name).resolve()
self.out = self.base / 'new-run'
self.addCleanup(self.directory.cleanup)
self.manifest = {**MANIFEST, 'shots': [SHOT, {**SHOT, 'id': 'b-shot'}]}
self.path = write_manifest(self.base, self.manifest)
@contextlib.contextmanager
def stubbed(self, capture=None):
with mock.patch.object(showcase, 'OUT', self.base), \
mock.patch.object(showcase, 'SCRATCH', self.out / 'scratch'), \
mock.patch.object(showcase, 'capture', capture or fake_capture({88: 400})), \
mock.patch.object(showcase, 'source_dir', lambda source, cache: Path('built')), \
mock.patch.object(showcase, 'environment', lambda python: ({'os': 'test'},
{'three': '0.180.0'})):
yield
def run_main(self, argv, capture=None):
stdout, stderr = io.StringIO(), io.StringIO()
with self.stubbed(capture), contextlib.redirect_stdout(stdout), \
contextlib.redirect_stderr(stderr):
status = showcase.main(['--manifest', str(self.path), '--out', str(self.out)] + argv)
return status, stdout.getvalue() + stderr.getvalue()
def test_a_full_run_writes_images_a_log_and_no_lock(self):
status, output = self.run_main([])
self.assertEqual(status, 0, output)
log = json.loads((self.out / 'showcase-log.json').read_text(encoding='utf-8'))
self.assertEqual([shot['id'] for shot in log['shots']], ['a-shot', 'b-shot'])
self.assertEqual(log['host'], {'os': 'test'})
self.assertEqual(log['versions'], {'three': '0.180.0'})
self.assertTrue(log['generated'])
self.assertTrue((self.out / 'a-shot.jpg').is_file())
self.assertFalse((self.out / 'scratch/.run.lock').exists())
def test_standalone_source_selects_its_multi_page_build_path(self):
seen = []
delegate = fake_capture({88: 400})
def capture(python, built, cfg, quality, staging):
seen.append(cfg.get('page_path'))
return delegate(python, built, cfg, quality, staging)
status, output = self.run_main(['--only', 'a-shot'], capture=capture)
self.assertEqual(status, 0, output)
self.assertEqual(seen, ['village/'])
def test_re_running_a_complete_showcase_does_no_work(self):
self.run_main([])
status, output = self.run_main([])
self.assertEqual(status, 0)
self.assertIn('nothing to do', output)
def test_an_interrupted_run_resumes_the_rest(self):
self.run_main(['--only', 'a-shot'])
status, output = self.run_main([])
self.assertEqual(status, 0, output)
self.assertIn('b-shot', output)
self.assertNotIn('a-shot:', output)
def test_the_budget_stops_before_a_shot_it_cannot_afford(self):
status, output = self.run_main(['--budget-s', '0'])
self.assertEqual(status, 0, output)
self.assertIn('budget 0 s reached', output)
self.assertIn('2 shot(s) left', output)
self.assertFalse((self.out / 'a-shot.jpg').exists())
def test_a_failing_shot_is_reported_and_the_run_continues(self):
def explode(python, built, cfg, quality, staging):
if cfg.get('view') == 'overview' and quality == 88:
raise RuntimeError('the built page has no view named overview')
raise RuntimeError('unreachable')
status, output = self.run_main([], capture=explode)
self.assertEqual(status, 1, output)
self.assertIn('FAIL a-shot', output)
self.assertIn('FAIL b-shot', output)
def test_dry_run_lists_the_plan_the_builds_and_an_estimate(self):
stdout = io.StringIO()
with self.stubbed(), contextlib.redirect_stdout(stdout):
status = showcase.main(['--manifest', str(self.path), '--out', str(self.out),
'--dry-run'])
output = stdout.getvalue()
self.assertEqual(status, 0)
self.assertIn('2 shot(s) pending of 2', output)
self.assertIn('builds needed (1): example:village', output)
self.assertIn('estimate', output)
self.assertFalse((self.out / 'showcase-log.json').exists())
def test_dry_run_counts_the_shared_examples_build_once(self):
second_source = {**SHOT, 'id': 'b-shot', 'source': 'example:heart'}
manifest = {**MANIFEST, 'shots': [SHOT, second_source]}
path = write_manifest(self.base, manifest)
stdout = io.StringIO()
with self.stubbed(), mock.patch.object(showcase, 'EXAMPLES', self.base / 'examples'), \
contextlib.redirect_stdout(stdout):
status = showcase.main(['--manifest', str(path), '--out', str(self.out), '--dry-run'])
self.assertEqual(status, 0)
self.assertIn('estimate 105 s', stdout.getvalue())
if __name__ == '__main__':
unittest.main()