path = Path(name)

if path.is_absolute() or not path.parts or any(p in ('.', '..', '.git', 'node_modules') for p in path.parts) or '\\' in name:

raise ValueError(f'Unsafe capture path: {name}')

target = root / path

if target.is_symlink() or root not in target.resolve().parents or not target.is_file():

raise ValueError(f'Capture input must be a repository-owned regular file: {name}')

config = json.loads(local_file(root, 'capture/config.json').read_text())

manifest = json.loads(local_file(root, 'port.json').read_text())

paths = ['port.json', 'palette/theme.json', 'scripts/capture.py', 'capture/config.json',

'capture/app.py', 'capture/flake.nix', 'capture/flake.lock', *config.get('fixtures', []), *manifest['files']]

data = path.read_bytes()

if len(data) < 24 or data[:8] != b'\x89PNG\r\n\x1a\n':

raise ValueError(f'Invalid capture PNG: {path}')

manifest = json.loads(local_file(root, 'port.json').read_text())

record = json.loads(local_file(root, 'images/capture.json').read_text())

if record.get('schemaVersion') != 1 or record.get('inputs') != inputs(root):

raise ValueError('Screenshots are stale. Run pnpm screenshots (or pnpm screenshots -- --force).')

declared = {image['flavor']: image['path'] for image in manifest['images']}

if len(declared) != len(manifest['images']) or set(declared) != set(manifest['flavors']) or set(record['images']) != set(declared):

raise ValueError('Every supported flavor needs exactly one real application screenshot')

for flavor, name in declared.items():

image = local_file(root, name)

evidence = record['images'][flavor]

if png_size(image) != (WIDTH, HEIGHT) or digest(image) != evidence['sha256'] or evidence['path'] != name:

raise ValueError(f'Capture is missing, damaged or changed without provenance: {name}')

if not evidence.get('application') or len(evidence.get('paletteColors', [])) < 2:

raise ValueError(f'Incomplete native capture evidence: {flavor}')

destination = root / name

parent = destination.parent.resolve()

if parent != root and root not in parent.parents:

raise ValueError(f'Capture output escapes its repository: {name}')

destination.parent.mkdir(parents=True, exist_ok=True)

with tempfile.NamedTemporaryFile(dir=destination.parent, prefix='.capture-', delete=False) as pending:

temporary = Path(pending.name)

try:

pending.write(content)

pending.flush()

os.fchmod(pending.fileno(), 0o644)

os.replace(temporary, destination) # Replace a link itself; never follow it into user files.

finally:

processes = [process for window in state for tab in window['tabs'] for pane in tab['windows']

for process in pane.get('foreground_processes', [])]

pattern = r'(?:^|[/\s.\-])' + re.escape(application) + r'(?:$|[/\s.\-])'

env = {'LIBGL_ALWAYS_SOFTWARE': '1'}

if mesa := os.environ.get('CAPTURE_MESA'):

# Both Xvfb's GLX server and Kitty's client must use the locked Mesa, not host drivers.

env.update(__EGL_VENDOR_LIBRARY_FILENAMES=f'{mesa}/share/glvnd/egl_vendor.d/50_mesa.json',

__GLX_VENDOR_LIBRARY_NAME='mesa', LD_LIBRARY_PATH=f'{mesa}/lib',

LIBGL_DRIVERS_PATH=f'{mesa}/lib/dri', GALLIUM_DRIVER='llvmpipe')

def __init__(self, root, home, flavor, display):

self.root, self.home, self.flavor = root, home, flavor

self.work = home / 'glyph-field'

self.work.mkdir()

self.slug = f'living-code-{flavor["id"]}'

self.socket = home / 'terminal.sock'

self.children = []

self.terminal_process = None

self.process_log = home / 'capture-process.log'

self.env = {key: os.environ[key] for key in ('PATH', 'FONTCONFIG_FILE', 'FONTCONFIG_PATH', 'TERMINFO_DIRS', 'LOCALE_ARCHIVE', 'SSL_CERT_FILE') if key in os.environ}

self.env.update(HOME=str(home), XDG_CONFIG_HOME=str(home / '.config'), XDG_CACHE_HOME=str(home / '.cache'),

XDG_DATA_HOME=str(home / '.local/share'), XDG_STATE_HOME=str(home / '.local/state'),

XDG_RUNTIME_DIR=str(home / 'runtime'), TMPDIR=str(home / 'tmp'), DISPLAY=display,

LANG='C.UTF-8', LC_ALL='C.UTF-8', TERM='xterm-kitty', COLORTERM='truecolor',

SHELL=shutil.which('bash') or '/bin/sh',

DBUS_SESSION_BUS_ADDRESS='unix:path=' + str(home / 'no-session-bus'))

self.env.update(renderer_env())

for name in ('.config', '.cache', '.local/share', '.local/state', 'runtime', 'tmp'):

(home / name).mkdir(parents=True, exist_ok=True)

(home / 'runtime').chmod(0o700)

self.write('glyph-field/src/FieldRenderer.ts', '''import { clamp, type GlyphField } from "./types";

''')

self.write('glyph-field/src/types.ts', 'export interface GlyphField { gpu: boolean; cells: { id: string; weight: number }[]; animate(props: object): Promise<void>; }\nexport const clamp = (n: number, min: number, max: number) => Math.min(max, Math.max(min, n));\n')

self.write('glyph-field/README.md', '# Glyph field\n\nA tiny renderer for living, interactive typography.\n')

self.write('glyph-field/package.json', '{"name":"glyph-field","version":"1.0.0","private":true,"type":"module"}\n')

def write(self, name, content):

path = self.home / name

path.parent.mkdir(parents=True, exist_ok=True)

path.write_text(content)

return path

def copy(self, source, target):

path = self.home / target

path.parent.mkdir(parents=True, exist_ok=True)

shutil.copyfile(local_file(self.root, source), path)

return path

def run(self, command, **kwargs):

return subprocess.run([str(x) for x in command], cwd=self.work, env=self.env, check=True,

text=True, capture_output=True, timeout=20, **kwargs).stdout

def spawn(self, command):

with self.process_log.open('ab') as output:

process = subprocess.Popen([str(x) for x in command], cwd=self.work, env=self.env,

stdout=output, stderr=subprocess.STDOUT, start_new_session=True)

self.children.append(process)

return process

def terminal(self, command):

colors = self.flavor['colors']

role = lambda name: colors[self.flavor['roles'][name]]['hex']

options = {'linux_display_server': 'x11', 'hide_window_decorations': 'yes', 'remember_window_size': 'no',

'initial_window_width': str(WIDTH), 'initial_window_height': str(HEIGHT),

'font_family': 'JetBrains Mono', 'font_size': '24', 'window_padding_width': '24',

'cursor_blink_interval': '0', 'enable_audio_bell': 'no', 'allow_remote_control': 'yes',

'background': role('bg'), 'foreground': role('fg'), 'cursor': role('cursor'),

'selection_background': role('selection'), 'selection_foreground': role('fg')}

for i, color in enumerate(self.flavor['ansi']['normal'] + self.flavor['ansi']['bright']):

options[f'color{i}'] = color

args = ['kitty', '--config', 'NONE', '--listen-on', f'unix:{self.socket}', '--title', 'Living Code capture', '--hold']

for key, value in options.items():

args += ['--override', f'{key}={value}']

self.terminal_process = self.spawn(args + [str(x) for x in command])

return self.terminal_process

def remote(self, *args):

return self.run(['kitty', '@', '--to', f'unix:{self.socket}', *args])

def text(self, ansi=False):

return self.remote('get-text', '--extent', 'screen', *(['--ansi'] if ansi else []))

def wait_text(self, pattern, timeout=30):

deadline, last = time.monotonic() + timeout, ''

while time.monotonic() < deadline:

if self.terminal_process is not None and self.terminal_process.poll() is not None:

raise RuntimeError(f'Native terminal exited with status {self.terminal_process.returncode}')

try:

last = self.text()

if re.search(pattern, last, re.I):

return last

except (subprocess.CalledProcessError, FileNotFoundError):

pass

time.sleep(0.25)

raise RuntimeError(f'Application did not reach {pattern!r}:\n{last[-5000:]}')

def type(self, text):

self.remote('send-text', '--bracketed-paste', 'disable', '--', text)

def key(self, key):

self.remote('send-key', key)

def git_fixture(self):

for args in (['init', '-b', 'main'], ['config', 'user.name', 'Living Code'],

['config', 'user.email', '[email protected]'], ['add', '.'],

['commit', '-m', 'feat: render an interactive glyph field']):

self.run(['git', *args])

with (self.work / 'src/FieldRenderer.ts').open('a') as file:

file.write('\nexport const DEFAULT_RADIUS = 0.35;\n')

self.write('glyph-field/src/pointer.ts', 'export const pointer = { x: 0, y: 0 };\n')

def cleanup(self):

for child in reversed(self.children):

try:

os.killpg(child.pid, signal.SIGTERM)

except ProcessLookupError:

pass

time.sleep(0.1)

for child in reversed(self.children):

try:

os.killpg(child.pid, signal.SIGKILL)

except ProcessLookupError:

pass

try:

if not force and not only:

check(root)

print('All application screenshots are current; use --force to recapture.')

return

except (ValueError, KeyError, FileNotFoundError):

pass

if not os.environ.get('CAPTURE_MESA'):

raise RuntimeError('Missing locked software renderer. Set CAPTURE_MESA in capture/flake.nix and run pnpm screenshots.')

for binary in ('Xvfb', 'xdotool', 'kitty', 'magick'):

if not shutil.which(binary):

raise RuntimeError(f'Missing {binary}. Run pnpm screenshots through the pinned capture/flake.nix environment.')

spec = importlib.util.spec_from_file_location('capture_app', local_file(root, 'capture/app.py'))

app = importlib.util.module_from_spec(spec)

spec.loader.exec_module(app)

manifest = json.loads(local_file(root, 'port.json').read_text())

flavors = json.loads(local_file(root, 'palette/theme.json').read_text())['flavors']

config = json.loads(local_file(root, 'capture/config.json').read_text())

if (root / 'images').is_symlink() or {image['flavor']: image['path'] for image in manifest['images']} != {

flavor: f'images/{flavor}.png' for flavor in manifest['flavors']}:

raise ValueError('Capture outputs must be images/<supported-flavor>.png inside this repository')

before = inputs(root)

evidence = {}

# Keep native Unix-domain socket paths below the OS's 108-byte limit, even inside nix develop.

with tempfile.TemporaryDirectory(prefix='lc-shot-', dir='/tmp', ignore_cleanup_errors=True) as temporary:

temporary = Path(temporary)

display_file = temporary / 'display'

with display_file.open('w+') as output, (temporary / 'xvfb.log').open('w+') as xvfb_log:

xvfb = subprocess.Popen(['Xvfb', '-displayfd', str(output.fileno()), '-screen', '0', f'{WIDTH}x{HEIGHT}x24',

'-nolisten', 'tcp', '-ac'], pass_fds=(output.fileno(),), stderr=xvfb_log,

env={'PATH': os.environ['PATH'], 'HOME': str(temporary),

'TMPDIR': str(temporary), **renderer_env()})

try:

for _ in range(100):

if display_file.read_text().strip():

break

if xvfb.poll() is not None:

raise RuntimeError('Xvfb failed to start')

time.sleep(0.05)

display = ':' + display_file.read_text().strip()

for flavor in flavors:

id = flavor['id']

if id not in manifest['flavors'] or (only and id != only):

continue

home = temporary / id

home.mkdir()

context = Context(root, home, flavor, display)

try:

command = app.prepare(context)

version = context.run(config['versionCommand']).strip().splitlines()[0]

process = context.spawn(command) if getattr(app, 'GRAPHICAL', False) else context.terminal(command)

app.drive(context)

time.sleep(0.4)

if process.poll() is not None:

raise RuntimeError(f'Application window exited: {process.returncode}')

if not getattr(app, 'GRAPHICAL', False):

state = json.loads(context.remote('ls'))

application = Path(str(command[0])).name

if not has_application(state, application):

raise RuntimeError('Native application is not running in the terminal; refusing a shell/error-screen capture:\n' + context.text()[-3000:])

image = temporary / f'{id}.png'

context.run(['magick', 'import', '-window', 'root', '-depth', '8', '-strip', f'PNG:{image}'])

if os.environ.get('CAPTURE_DEBUG'):

replace_output(root, f'dist/capture-debug/{id}.png', image.read_bytes())

if png_size(image) != (WIDTH, HEIGHT):

raise RuntimeError('Unexpected screenshot dimensions')

histogram = context.run(['magick', image, '-format', '%c', 'histogram:info:-']).lower()

colors = sorted({color['hex'].lower() for color in flavor['colors'].values()

if color['hex'].lower() in histogram})

if len(colors) < 2:

raise RuntimeError('The screenshot does not contain the selected Living Code palette')

if not getattr(app, 'GRAPHICAL', False):

screen = context.text()

if re.search(r'(?i)(failed to (?:parse|deserialize|load config)|invalid (?:color|theme)|error loading theme|panicked at|server did not become ready|exited with (?:status|error)|error: nu::|Docker event stream returned error)', screen):

raise RuntimeError('Application reported a theme/configuration error:\n' + screen[-3000:])

name = next(image['path'] for image in manifest['images'] if image['flavor'] == id)

evidence[id] = {'path': name, 'sha256': digest(image), 'application': version, 'paletteColors': colors}

print(f'{manifest["name"]} {id}: captured the real application ({len(colors)} palette colors)', flush=True)

except Exception:

if context.process_log.exists():

print('Native process diagnostics:\n' + context.process_log.read_text(errors='replace')[-5000:], file=sys.stderr)

xvfb_log.seek(0)

print('Native display diagnostics:\n' + xvfb_log.read()[-3000:], file=sys.stderr)

raise

finally:

try:

if hasattr(app, 'cleanup'):

app.cleanup(context)

finally:

context.cleanup()

if only:

destination = root / 'dist/capture-preview'

replace_output(root, f'dist/capture-preview/{only}.png', (temporary / f'{only}.png').read_bytes())

print(f'Preview only: {destination / (only + ".png")}; committed captures were not changed.')

return

if before != inputs(root):

raise RuntimeError('Capture inputs changed while applications were running; images were not replaced')

if set(evidence) != set(manifest['flavors']):

raise RuntimeError('Not all supported flavors were captured; images were not replaced')

for id, item in evidence.items():

replace_output(root, item['path'], (temporary / f'{id}.png').read_bytes())

replace_output(root, 'images/capture.json', (json.dumps({'schemaVersion': 1, 'scene': config['scene'],

'inputs': before, 'images': evidence}, indent=2) + '\n').encode())

finally:

xvfb.terminate()

xvfb.wait(timeout=5)