@maccesar/titools 5.1.1 → 5.2.0

package/skills/ti-game-assets/references/vector-sources.md

@@ -0,0 +1,21 @@
+# Editable vector and procedural sources
+
+Use an existing SVG/procedural workflow when the project uses it or the user requests editable art generated with code. Integrated `image_gen` remains the default for raster drawing creation/edits; it is not a requirement to replace authored vectors. Rasterizing an SVG is an export step, not image-model generation.
+
+## Source of truth
+
+Keep the editable SVG, generator and parameters as canonical sources; retain individual full-canvas PNG renders as reproducible derivatives. Avoid making a generated PNG the only editable master. Preserve original/legacy source when it has a documented purpose. Name symbols and groups by meaningful parts (hull, cockpit, lights, propulsion, appendages), with explicit `viewBox`, proportions and pivots. Parameterize palette, poses and damage overlays without shifting silhouette or anchor accidentally.
+
+Record deterministic seeds for procedural distributions. Use a maintained SVG rasterizer already in the project, such as `rsvg-convert`/librsvg, and record its version, font dependencies, antialiasing and target dimensions. Rasterizer changes can change bytes: regenerate and review the affected set rather than merely updating hashes. Avoid hidden system-font or external-image dependencies in gameplay graphics.
+
+Reuse a build that emits PNG sheets, runtime catalogs/frame maps, source/generator/output hashes, contact sheets and animation/parallax previews together. The runtime consumes generated PNG/catalog data, not the offline generator. Verify missing/empty cells, frame bounds, dimensions, anchor consistency, stale output hashes and repeat seams. Run it twice in a disposable output directory to check determinism in a fixed environment. Do not infer human authorship from a PNG compression filter or overwrite policy: preserve authored assets through explicit provenance.
+
+Render at the declared logical proportions and preview at actual game sizes, in grayscale and relevant color-vision simulations. Distinguish roles by silhouette/symbol as well as color. Preserve warning readability under reduced-flash settings; do not silently change mechanics, flashes or accessibility preferences while exporting.
+
+## Manifest extension
+
+Keep `source` pointing at the PNG render inspected by the bundled validator; add `vector_source` pointing at its existing SVG master. The validator checks an SVG root and finite positive `viewBox` extents, not vector aesthetics or generation dependencies. Record generator, parameters and render settings in provenance. Optional top-level `build.files` maps source/generator/output paths to SHA-256 hashes; validation detects modified declared files. Include *all* relevant dependencies, not just outputs. Hash agreement does not prove a build was run or that a rasterizer is correct.
+
+## Evidence from Guardian
+
+`docs/art/source/guardian-parts.svg` holds named symbols/editable groups. `docs/scripts/generate-art.js` creates PNGs, runtime catalog and review sheets. `docs/scripts/verify-art.js` checks hashes, cells, animation frames and background edges. `docs/art/README.md` documents the renderer and why its high-resolution antialiased art uses smoothing. These are reusable design choices, not a requirement to copy its cell sizes, frame counts or art.

package/skills/ti-game-assets/scripts/alpha_tools.py

@@ -0,0 +1,160 @@
+#!/usr/bin/env python3
+"""Inspect alpha; explicitly remove reviewed exterior residue into new files."""
+import argparse
+import json
+import math
+from pathlib import Path
+
+from PIL import Image, ImageDraw
+
+THRESHOLDS = (1, 4, 8, 16, 32)
+
+
+def bbox(alpha, threshold):
+    return alpha.point(lambda value: 255 if value >= threshold else 0).getbbox()
+
+
+def analyze(image):
+    alpha = image.getchannel('A')
+    histogram = alpha.histogram()
+    return {
+        'dimensions': list(image.size),
+        'alpha_range': list(alpha.getextrema()),
+        'translucent_pixels': sum(histogram[1:255]),
+        'visible_pixels': sum(histogram[1:]),
+        'bounding_boxes': {str(t): bbox(alpha, t) for t in THRESHOLDS},
+    }
+
+
+def rectangle(values, size):
+    x0, y0, x1, y1 = values
+    if not (0 <= x0 < x1 <= size[0] and 0 <= y0 < y1 <= size[1]):
+        raise ValueError('rectangle must be nonempty and inside the source canvas')
+    return tuple(values)
+
+
+def clean(image, protected):
+    alpha = image.getchannel('A')
+    retained = Image.new('L', image.size, 0)
+    retained.paste(alpha.crop(protected), protected[:2])
+    result = image.copy()
+    result.putalpha(retained)
+    return result
+
+
+def preview(before, after=None):
+    images = [before] if after is None else [before, after]
+    cell = 280
+    output = Image.new('RGB', (cell * len(images), (cell + 24) * 3), 'white')
+    draw = ImageDraw.Draw(output)
+    for column, source in enumerate(images):
+        scaled = source.copy()
+        scaled.thumbnail((cell, cell), Image.Resampling.NEAREST)
+        for row, background in enumerate(('checker', '#eeeeee', '#181818')):
+            x, y = column * cell, row * (cell + 24) + 24
+            panel = Image.new('RGBA', (cell, cell), background if row else '#cccccc')
+            if row == 0:
+                painter = ImageDraw.Draw(panel)
+                for cy in range(0, cell, 16):
+                    for cx in range(0, cell, 16):
+                        if (cx // 16 + cy // 16) % 2:
+                            painter.rectangle((cx, cy, cx + 15, cy + 15), fill='#999999')
+            panel.alpha_composite(scaled)
+            output.paste(panel.convert('RGB'), (x, y))
+            draw.text((x + 4, y - 20), ('original' if column == 0 else 'candidate') + ' / ' + background, fill='black')
+            for threshold, color in zip(THRESHOLDS, ('red', 'orange', 'lime', 'cyan', 'magenta')):
+                box = bbox(source.getchannel('A'), threshold)
+                if box:
+                    sx, sy = scaled.width / source.width, scaled.height / source.height
+                    draw.rectangle((x + box[0] * sx, y + box[1] * sy,
+                                    x + (box[2] - 1) * sx, y + (box[3] - 1) * sy), outline=color)
+    return output
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('source', type=Path)
+    parser.add_argument('--profile', choices=('pixel-art', 'hard-surface', 'soft-fx'), default='hard-surface')
+    parser.add_argument('--logical-size', nargs=2, type=int, metavar=('W', 'H'))
+    parser.add_argument('--threshold', type=int, default=8)
+    parser.add_argument('--protect', nargs=4, type=int, metavar=('X0', 'Y0', 'X1', 'Y1'))
+    parser.add_argument('--auto-protect', action='store_true')
+    parser.add_argument('--reason', help='reviewed residue and justification for the protected region')
+    parser.add_argument('--clean', type=Path, help='new PNG output; omit for analysis only')
+    crop = parser.add_mutually_exclusive_group()
+    crop.add_argument('--crop', action='store_true')
+    crop.add_argument('--crop-box', nargs=4, type=int, metavar=('X0', 'Y0', 'X1', 'Y1'))
+    parser.add_argument('--report', type=Path)
+    parser.add_argument('--preview', type=Path)
+    args = parser.parse_args()
+    try:
+        if not 1 <= args.threshold <= 255:
+            raise ValueError('threshold must be 1..255')
+        if args.logical_size and min(args.logical_size) <= 0:
+            raise ValueError('logical size must be positive')
+        if args.protect and args.auto_protect:
+            raise ValueError('choose explicit or automatic protection, not both')
+        if not args.clean and (args.crop or args.crop_box or args.protect or args.auto_protect):
+            raise ValueError('protection and crop flags require --clean')
+        outputs = [p.resolve() for p in (args.clean, args.report, args.preview) if p]
+        if len(outputs) != len(set(outputs)) or args.source.resolve() in outputs:
+            raise ValueError('outputs must be distinct from each other and the source')
+        if any(p.exists() for p in outputs):
+            raise ValueError('refusing to overwrite an existing output')
+        with Image.open(args.source) as opened:
+            source = opened.convert('RGBA')
+        report = {'source': str(args.source), 'profile': args.profile, 'analysis': analyze(source)}
+        candidate = None
+        if args.clean:
+            if not args.reason or not args.reason.strip():
+                raise ValueError('cleaning requires --reason documenting the review')
+            if args.profile == 'soft-fx' and (not args.protect or args.auto_protect):
+                raise ValueError('soft-fx requires an explicit protected region')
+            if args.profile == 'pixel-art' and not args.logical_size:
+                raise ValueError('pixel-art cleaning requires --logical-size')
+            padding = [math.ceil(source.size[i] / args.logical_size[i]) for i in (0, 1)] if args.logical_size else [1, 1]
+            if args.protect:
+                protected = rectangle(args.protect, source.size)
+            elif args.auto_protect:
+                detected = bbox(source.getchannel('A'), args.threshold)
+                if not detected:
+                    raise ValueError('no content at threshold; preserve source and inspect lower thresholds')
+                protected = (max(0, detected[0] - padding[0]), max(0, detected[1] - padding[1]),
+                             min(source.width, detected[2] + padding[0]), min(source.height, detected[3] + padding[1]))
+            else:
+                raise ValueError('cleaning requires --protect or reviewed --auto-protect')
+            candidate = clean(source, protected)
+            report['cleanup'] = {
+                'protected_region': protected, 'threshold': args.threshold,
+                'logical_size': args.logical_size, 'logical_pixel_padding': padding,
+                'reason': args.reason, 'region_mode': 'explicit' if args.protect else 'automatic-trial',
+                'removed_pixels': report['analysis']['visible_pixels'] - analyze(candidate)['visible_pixels'],
+                'analysis': analyze(candidate),
+            }
+            trim = args.crop_box or (bbox(candidate.getchannel('A'), 1) if args.crop else None)
+            if (args.crop or args.crop_box) and not bbox(candidate.getchannel('A'), 1):
+                raise ValueError('cannot crop empty content')
+            if trim:
+                trim = rectangle(trim, source.size)
+                visible = bbox(candidate.getchannel('A'), 1)
+                if visible and not (trim[0] <= visible[0] and trim[1] <= visible[1] and trim[2] >= visible[2] and trim[3] >= visible[3]):
+                    raise ValueError('crop box would discard visible content')
+            report['export'] = {'path': str(args.clean), 'offset': list(trim[:2]) if trim else [0, 0],
+                                'source_dimensions': list(source.size),
+                                'dimensions': [trim[2] - trim[0], trim[3] - trim[1]] if trim else list(source.size)}
+        # Build comparison before writing any output. It uses common source canvases.
+        comparison = preview(source, candidate) if args.preview else None
+        if args.clean:
+            (candidate.crop(trim) if trim else candidate).save(args.clean, format='PNG')
+        if args.preview:
+            comparison.save(args.preview, format='PNG')
+        encoded = json.dumps(report, indent=2)
+        if args.report:
+            args.report.write_text(encoded + '\n', encoding='utf-8')
+        print(encoded)
+    except (ValueError, OSError) as error:
+        parser.error(str(error))
+
+
+if __name__ == '__main__':
+    main()

package/skills/ti-game-assets/scripts/requirements.txt

@@ -0,0 +1 @@
+Pillow>=10

package/skills/ti-game-assets/scripts/validate_manifest.py

@@ -0,0 +1,267 @@
+#!/usr/bin/env python3
+"""Validate per-set game art and sound contracts, files, frames and parallax."""
+import argparse
+from collections import Counter, defaultdict
+import json
+import hashlib
+import re
+import wave
+import xml.etree.ElementTree as ET
+import math
+from pathlib import Path
+
+from PIL import Image
+
+FAMILIES = {'players', 'enemies', 'allies', 'obstacles', 'ammunition', 'rewards', 'ambient', 'backgrounds', 'technical'}
+
+
+def numbers(value, length, positive=False):
+    return (isinstance(value, list) and len(value) == length
+            and all(type(n) in (int, float) and math.isfinite(n) and (not positive or n > 0) for n in value))
+
+
+def dimensions(value):
+    return numbers(value, 2, True) and all(type(n) is int for n in value)
+
+
+def validate(data, root):
+    errors = []
+    counts = []
+
+    def require(condition, message):
+        if not condition:
+            errors.append(message)
+
+    def source_path(value, label):
+        if not isinstance(value, str) or not value:
+            errors.append(label + ': missing source')
+            return None
+        path = (root / value).resolve()
+        if not path.is_file():
+            errors.append(label + ': source not found: ' + value)
+            return None
+        return path
+
+    build = data.get('build')
+    if build is not None:
+        files = build.get('files') if isinstance(build, dict) else None
+        require(isinstance(files, dict) and bool(files), 'build.files must be a nonempty path-to-SHA256 object')
+        for filename, digest in files.items() if isinstance(files, dict) else []:
+            valid_hash = isinstance(digest, str) and re.fullmatch(r'[0-9a-f]{64}', digest) is not None
+            require(valid_hash, 'build: invalid SHA256 for ' + filename)
+            path = source_path(filename, 'build')
+            if path and valid_hash:
+                require(hashlib.sha256(path.read_bytes()).hexdigest() == digest, 'build: stale source/output hash: ' + filename)
+
+    require(data.get('schema_version') == 1, 'schema_version must be 1')
+    contracts = data.get('contracts', {})
+    sets = data.get('sets', [])
+    require(isinstance(contracts, dict) and bool(contracts), 'contracts must be a nonempty object')
+    require(isinstance(sets, list) and bool(sets), 'sets must be a nonempty list')
+    if not isinstance(contracts, dict) or not isinstance(sets, list):
+        return errors, counts
+    seen_sets = set()
+    for group in sets:
+        if not isinstance(group, dict):
+            errors.append('set must be an object')
+            continue
+        name = group.get('id')
+        require(isinstance(name, str) and bool(name) and name not in seen_sets, 'set ids must be unique nonempty strings')
+        if not isinstance(name, str):
+            continue
+        seen_sets.add(name)
+        label = name + ': '
+        contract = contracts.get(group.get('contract'))
+        if not isinstance(contract, dict):
+            errors.append(label + 'unknown contract')
+            continue
+        expected = Counter()
+        definitions = contract.get('resources', [])
+        expected_sounds = Counter()
+        require(isinstance(definitions, list), label + 'contract resources must be a list')
+        for definition in definitions if isinstance(definitions, list) else []:
+            resource, family, variant, state = (definition.get(k) for k in ('resource', 'family', 'variant', 'state'))
+            frames = definition.get('frames')
+            if not all(isinstance(v, str) and v for v in (resource, family, variant, state)) or type(frames) is not int or frames < 1:
+                errors.append(label + 'invalid resource definition')
+                continue
+            require(family in FAMILIES, label + 'unknown resource family ' + family)
+            for frame in range(frames):
+                expected[(resource, family, variant, state, frame)] += 1
+        require(all(n == 1 for n in expected.values()), label + 'duplicate contract resource definition')
+        sound_defs = contract.get('sounds', [])
+        require(isinstance(sound_defs, list), label + 'contract sounds must be a list')
+        for definition in sound_defs if isinstance(sound_defs, list) else []:
+            sound, variants = definition.get('sound'), definition.get('variants')
+            if not isinstance(sound, str) or not sound or not isinstance(variants, list) or not variants or not all(isinstance(v, str) and v for v in variants):
+                errors.append(label + 'invalid sound definition')
+                continue
+            expected_sounds.update((sound, variant) for variant in variants)
+        require(all(n == 1 for n in expected_sounds.values()), label + 'duplicate sound contract variant')
+        require(bool(expected or expected_sounds), label + 'contract must require visual or sound assets')
+        assets, sounds = group.get('assets', []), group.get('sounds', [])
+        require(isinstance(assets, list) and isinstance(sounds, list), label + 'assets and sounds must be lists')
+        if not isinstance(assets, list) or not isinstance(sounds, list):
+            continue
+        actual = Counter()
+        ids = set()
+        asset_by_id = {}
+        alignment = defaultdict(list)
+        sequences = defaultdict(list)
+        for asset in assets:
+            identity = asset.get('id')
+            require(isinstance(identity, str) and bool(identity) and identity not in ids, label + 'asset ids must be unique strings')
+            if not isinstance(identity, str):
+                continue
+            ids.add(identity)
+            asset_by_id[identity] = asset
+            fields = [asset.get(k) for k in ('resource', 'family', 'variant', 'state')]
+            frame = asset.get('frame')
+            if not all(isinstance(v, str) and v for v in fields) or type(frame) is not int or frame < 0:
+                errors.append(label + identity + ': invalid identity/frame')
+                continue
+            actual[tuple(fields) + (frame,)] += 1
+            sequences[tuple(fields)].append(frame)
+            size, canvas, pivot = (asset.get(k) for k in ('dimensions', 'canvas', 'pivot'))
+            require(dimensions(size), label + identity + ': dimensions must be positive integers')
+            require(dimensions(canvas), label + identity + ': canvas must be positive integers')
+            require(numbers(pivot, 2), label + identity + ': pivot must be finite coordinates')
+            require(size == canvas, label + identity + ': master must retain its common canvas')
+            if dimensions(canvas) and numbers(pivot, 2):
+                require(all(0 <= pivot[i] <= canvas[i] for i in (0, 1)), label + identity + ': pivot outside canvas')
+            alignment[tuple(fields[:3])].append((canvas, pivot, asset.get('logical_size')))
+            require(type(asset.get('transparency')) is bool, label + identity + ': transparency must be Boolean')
+            style = asset.get('style')
+            require(style in ('pixel-art', 'hard-surface', 'soft-fx', 'hd'), label + identity + ': unknown style')
+            if style == 'pixel-art':
+                require(dimensions(asset.get('logical_size')), label + identity + ': pixel-art requires logical_size')
+            require(isinstance(asset.get('provenance'), dict) and bool(asset['provenance'].get('prompt')),
+                    label + identity + ': provenance.prompt required')
+            if 'vector_source' in asset:
+                vector = source_path(asset['vector_source'], label + identity + ' vector')
+                if vector:
+                    try:
+                        svg = ET.parse(vector).getroot()
+                        require(svg.tag in ('svg', '{http://www.w3.org/2000/svg}svg'), label + identity + ': vector source must have SVG root')
+                        viewbox = [float(n) for n in svg.get('viewBox', '').replace(',', ' ').split()]
+                        require(numbers(viewbox, 4) and viewbox[2] > 0 and viewbox[3] > 0,
+                                label + identity + ': SVG requires finite viewBox with positive extents')
+                    except (ET.ParseError, ValueError, OSError) as error:
+                        errors.append(label + identity + ': unreadable SVG: ' + str(error))
+            path = source_path(asset.get('source'), label + identity)
+            if path:
+                try:
+                    with Image.open(path) as image:
+                        require(image.format == 'PNG', label + identity + ': master must be PNG')
+                        require(list(image.size) == size, label + identity + ': source dimensions mismatch')
+                        alpha = image.convert('RGBA').getchannel('A')
+                        require(alpha.getextrema()[1] > 0, label + identity + ': empty image')
+                        if asset.get('transparency') is True:
+                            require(('A' in image.getbands() or 'transparency' in image.info) and alpha.getextrema()[0] < 255,
+                                    label + identity + ': real transparency required')
+                        elif asset.get('transparency') is False:
+                            require(alpha.getextrema()[0] == 255, label + identity + ': declared opaque source contains transparency')
+                except OSError as error:
+                    errors.append(label + identity + ': unreadable image: ' + str(error))
+        require(actual == expected, label + 'resource/frame contract incomplete or contains unexpected/duplicate entries')
+        for key, frames in sequences.items():
+            require(frames == list(range(len(frames))), label + str(key) + ': frames must appear in contiguous order from zero')
+        for key, values in alignment.items():
+            require(all(value == values[0] for value in values), label + str(key) + ': states/frames must share canvas, pivot and logical size')
+        audio_ids = set()
+        actual_sounds = Counter()
+        for sound in sounds:
+            identity = sound.get('id')
+            require(isinstance(identity, str) and bool(identity) and identity not in audio_ids and identity not in ids,
+                    label + 'sound ids must be unique and distinct from images')
+            if not isinstance(identity, str):
+                continue
+            audio_ids.add(identity)
+            key = (sound.get('sound'), sound.get('variant'))
+            if not all(isinstance(v, str) and v for v in key):
+                errors.append(label + identity + ': invalid sound/variant')
+                continue
+            actual_sounds[key] += 1
+            source_path(sound.get('source'), label + identity)
+            if 'wav' in sound:
+                wav = sound['wav']
+                if not isinstance(wav, dict):
+                    errors.append(label + identity + ': wav must be an object')
+                else:
+                    fields = ('sample_rate', 'channels', 'sample_width', 'frames')
+                    require(all(type(wav.get(k)) is int and wav[k] > 0 for k in fields), label + identity + ': WAV format fields must be positive integers')
+                    require(type(wav.get('loop')) is bool, label + identity + ': WAV loop must be Boolean')
+                    file = source_path(wav.get('file'), label + identity + ' WAV')
+                    if file:
+                        try:
+                            with wave.open(str(file), 'rb') as audio:
+                                actual_format = (audio.getframerate(), audio.getnchannels(), audio.getsampwidth(), audio.getnframes())
+                                require(actual_format == tuple(wav.get(k) for k in fields), label + identity + ': WAV header differs from contract')
+                                require(audio.getcomptype() == 'NONE' and audio.getnframes() > 0, label + identity + ': WAV must be nonempty PCM')
+                                expected_bytes = audio.getnframes() * audio.getnchannels() * audio.getsampwidth()
+                                # Stream the data to avoid loading an entire music file into memory.
+                                actual_bytes = 0
+                                while block := audio.readframes(65536):
+                                    actual_bytes += len(block)
+                                require(actual_bytes == expected_bytes, label + identity + ': truncated WAV payload')
+                        except (wave.Error, EOFError, OSError) as error:
+                            errors.append(label + identity + ': unreadable WAV: ' + str(error))
+            require(isinstance(sound.get('reference'), str) and bool(sound['reference']), label + identity + ': recipe/pattern reference required')
+            require(sound.get('kind') in ('effect', 'sustained', 'music', 'ambient', 'ui'), label + identity + ': unknown sound kind')
+            require(isinstance(sound.get('design'), dict) and bool(sound['design']), label + identity + ': sound design required')
+            require(isinstance(sound.get('provenance'), dict) and bool(sound['provenance']), label + identity + ': sound provenance required')
+        require(actual_sounds == expected_sounds, label + 'sound contract incomplete or contains unexpected/duplicate variants')
+        aliases = group.get('aliases', {})
+        require(isinstance(aliases, dict), label + 'aliases must be an object')
+        if isinstance(aliases, dict):
+            for alias, target in aliases.items():
+                require(alias not in ids | audio_ids and isinstance(target, str) and target in ids | audio_ids,
+                        label + alias + ': alias must directly reference an existing asset or sound without masking an id')
+        layers = group.get('parallax', [])
+        require(isinstance(layers, list), label + 'parallax must be a list')
+        if layers or contract.get('parallax'):
+            require(isinstance(layers, list) and len(layers) == 3 and {layer.get('depth') for layer in layers} == {'far', 'middle', 'near'},
+                    label + 'parallax requires far, middle and near layers')
+            if isinstance(layers, list):
+                layer_assets = [layer.get('asset') for layer in layers]
+                require(len(set(layer_assets)) == 3, label + 'parallax layers must be independent assets')
+                orders = {}
+                for layer in layers:
+                    asset = asset_by_id.get(layer.get('asset'))
+                    require(bool(asset) and asset.get('family') == 'backgrounds', label + 'parallax references unknown/non-background asset')
+                    require(type(layer.get('transparent')) is bool and asset is not None and asset.get('transparency') == layer.get('transparent'),
+                            label + 'parallax transparency must match its asset')
+                    require(layer.get('repeat') in ('none', 'x', 'y', 'xy'), label + 'invalid parallax repeat')
+                    require(numbers(layer.get('displacement'), 2), label + 'parallax displacement must be finite x/y')
+                    order = layer.get('order')
+                    require(type(order) is int, label + 'parallax order must be integer')
+                    orders[layer.get('depth')] = order
+                if all(type(orders.get(k)) is int for k in ('far', 'middle', 'near')):
+                    require(orders['far'] < orders['middle'] < orders['near'], label + 'parallax orders must increase with depth')
+        for event in group.get('events', []):
+            require(isinstance(event.get('event'), str) and bool(event['event']), label + 'semantic event required')
+            require(event.get('visual') in ids and event.get('sound') in audio_ids, label + 'event references unknown visual/sound')
+            require(event.get('timing') in ('discrete', 'sustained', 'music'), label + 'event timing must be discrete, sustained or music (never each frame)')
+        counts.append({'set': name, 'contract': group.get('contract'), 'unique_resources': len({k[0] for k in actual}),
+                       'png_frames': len(assets), 'sound_variants': len(sounds), 'aliases': len(aliases)})
+    return errors, counts
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('manifest', type=Path)
+    parser.add_argument('--root', type=Path, help='source root; defaults to manifest directory')
+    args = parser.parse_args()
+    try:
+        data = json.loads(args.manifest.read_text(encoding='utf-8'))
+        if not isinstance(data, dict):
+            raise ValueError('manifest must be an object')
+        errors, counts = validate(data, args.root or args.manifest.parent)
+    except (ValueError, OSError, TypeError, KeyError, AttributeError) as error:
+        errors, counts = ['malformed manifest: ' + str(error)], []
+    print(json.dumps({'valid': not errors, 'counts': counts, 'errors': errors}, indent=2))
+    raise SystemExit(1 if errors else 0)
+
+
+if __name__ == '__main__':
+    main()

package/skills/ti-synthengine/SKILL.md

@@ -1,26 +1,32 @@
 ---
 name: ti-synthengine
-description: "Use when a Titanium app declares ti.synthengine in tiapp.xml, imports require('ti.synthengine'), or asks for generated tones, chords, patterns, retro/game/UI sounds, alarms, sweeps, vibrato, envelopes, panning, gain staging, or troubleshooting with that native module. Covers Android and iOS contract 1.0.0. Do not use for audio-file playback, streaming music, or unrelated synthesizers."
+description: "Use when a Titanium app declares ti.synthengine in tiapp.xml, imports require('ti.synthengine'), or asks for generated tones, chords, patterns, retro/game/UI sounds, alarms, sweeps, vibrato, envelopes (attack, decay, sustain, release), resonant filters, FM bells and electric-piano tones, detune, panning, binaural headphone positioning (spatialX/spatialY), gain staging, engine statistics, render load, the patternend event, or troubleshooting with that native module. Covers Android and iOS contract 1.0.0. Do not use for audio-file playback, streaming music, or unrelated synthesizers."
 ---
 
 # ti.synthengine — sound synthesis for Titanium SDK
 
 Act as an audio engineer and mobile sound designer for the native `ti.synthengine` module. Translate an aesthetic request into acoustically reasoned JavaScript that uses only the module's public contract.
 
-This skill is verified against TiSynthEngine **1.0.0** at commit **`6685b81` (2026-08-29)**. Android and iOS expose the same eight public methods, option contracts, defaults, limits, waveform constants, and validation behavior.
+This skill follows the reviewed TiSynthEngine **1.0.0 beta working tree based on `95901c98af5353b86d9dc7c60b29ab9186b038cd` (2026-10-14)**, including uncommitted statistics changes. Eight official Markdown references and the raw statistics comparison record source hashes; [source notes](references/source-notes.md) and [snapshot metadata](references/source-snapshot.json) record the reviewed working-tree fingerprint, maintained navigation additions and exclusions. The reviewed Android and iOS source exposes eleven public methods and one event; this is not a claim about published packages. Inspect `getDefaults().limits` for `spatialX` and `spatialY` before offering binaural controls, and detect statistics methods before calling them; `apiVersion` alone does not distinguish installed beta builds.
+
+## Visual and sound asset collaboration
+
+Use `ti-game-assets` to create/edit complete visual and sound asset sets, preserve art/acoustic palettes and provenance, validate alpha/frames/manifests, prepare exports, and coordinate variants and stereo event placement. `ti-game` governs native representation/motion/events; `ti-synthengine` governs synthesis and sound behavior with `ti.synthengine`. Both have equal domain authority. Read their relevant current references rather than duplicating manuals. Art alone does not require installing modules or adding sounds/mechanics.
 
 ## Required workflow
 
-Read the references relevant to the task before proposing code. Do not infer option names from Web Audio, another synthesizer, or general DSP libraries.
+Read the references relevant to the task before proposing code. These are source snapshots, not an independent validation oracle: when reviewing the module or updating its official documentation, compare against the native contract and both renderers, then synchronize the references. Do not infer option names from Web Audio, another synthesizer, or general DSP libraries.
 
 | Task | Read first |
 | --- | --- |
 | Any code using a public method, option, default, limit, or return value | [references/api.md](references/api.md) |
+| Position sounds in a headphone front plane, map spatial controls, or diagnose spatial/pan conflicts | [references/guide.md](references/guide.md#integrate-binaural-in-a-2d-app), [references/api.md](references/api.md), [references/audio-engine.md](references/audio-engine.md) |
 | Design a sound from an aesthetic description | [references/sound-design.md](references/sound-design.md), then [references/recipes.md](references/recipes.md) for a tuned starting point |
 | Build retro/arcade effects, a playable instrument, memory pads, layered chords, timbre comparisons, or cancellable repetition | [references/recipes.md](references/recipes.md), plus [references/api.md](references/api.md) |
 | Learn the official examples for tones, chords, tempo, patterns, noise, validation, startup, and cleanup | [references/examples.md](references/examples.md) |
 | Install the module, start it safely, or manage screen/app cleanup | [references/guide.md](references/guide.md) |
 | Choose a mixing profile, voice count, gain, latency strategy, or understand the signal path | [references/audio-engine.md](references/audio-engine.md), [references/recommendations.md](references/recommendations.md) |
+| Query/reset statistics, enable diagnostics, interpret render load/meters, or compare host performance | [references/api.md](references/api.md#getstats), [references/audio-engine.md](references/audio-engine.md#engine-statistics), [references/stats-performance.md](references/stats-performance.md), [raw trials](references/stats-performance.json) |
 | Diagnose `false`, silence, glitches, distortion, pattern replacement, or route changes | [references/troubleshooting.md](references/troubleshooting.md), [references/api.md](references/api.md) |
 
 Cite factual guidance with `[source: references/<file>.md]`. If a relevant reference cannot be consulted, prefix the claim with `FROM_MEMORY (unverified):` instead of filling the gap silently.
@@ -33,7 +39,7 @@ Answer in the user's language and use this order:
 2. **Safe initialization when needed.** If the surrounding code does not already own a running engine, show `require`, `getDefaults()`, a checked `startEngine()` call, and appropriate cleanup. For a screen startup, follow the post-layout lifecycle in the guide.
 3. **Production JavaScript.** Return a focused, copyable block with short comments, exact option names, valid types and checked Boolean results.
 
-If the request cannot be represented by this synthesizer—audio-file playback, indefinite loops, per-voice control, streaming, or sample-accurate composition—say so and recommend the appropriate kind of audio engine instead of inventing an API.
+If the request cannot be represented by this synthesizer—audio-file playback, indefinite loops, per-voice control, streaming, or sample-accurate composition—say so and recommend the appropriate kind of audio engine instead of inventing an API. The same goes for reverb, delay, chorus and other effects: the module has no effect bus.
 
 ## Contract invariants
 
@@ -45,15 +51,24 @@ var contract = synth.getDefaults()
 var WAVE = contract.waveTypes
 ```
 
-Never hardcode waveform integers when `WAVE.SINE`, `WAVE.SQUARE`, `WAVE.SAWTOOTH`, `WAVE.TRIANGLE`, and `WAVE.NOISE` are available.
+Never hardcode waveform integers when `WAVE.SINE`, `WAVE.SQUARE`, `WAVE.SAWTOOTH`, `WAVE.TRIANGLE`, `WAVE.NOISE`, and `WAVE.WAVETABLE` are available.
 
 - Option dictionaries are closed. Unknown or misspelled keys, wrong types, non-finite numbers, fractional values for integer fields, and out-of-range values make the entire call return `false`.
 - `playTone()` takes at most one pitch source: `note` or `frequency`. If neither is supplied, it defaults to 440 Hz. Never send both.
-- `playChord()` requires exactly one of `notes` or `frequencies`. It accepts `panSpread` or `pans`, but no sweep or LFO fields.
-- Every sounding `playPattern()` step needs exactly one of `note` or `frequency`; a rest uses exactly `rest: true`. Even a `NOISE` step needs a pitch field, although noise ignores its value. Pattern roots do not accept `duration`.
-- `duration` includes attack, the full-level middle, and release. For explicit envelopes, `attack < duration` and `release <= duration - attack`.
-- `pan` and `panEnd` range from -1 to 1. `frequencyEnd` is a linear sweep target. `lfoFreq` is the modulation rate in Hz and `lfoDepth` is absolute pitch deviation in Hz, not cents.
+- `playChord()` requires exactly one of `notes` or `frequencies`. It accepts `panSpread` or `pans`, the fixed shaping fields `noiseRate`, `lowPassHz`, `pulseWidth`, `waveTable`, and `bitDepth`, the fixed expressive fields `decay`, `sustain`, `filterType`, `filterHz`, `filterQ`, `fmRatio`, and `fmDepth`, and `detunes`, but no sweep, LFO, `detune`, or `*End` fields.
+- Every sounding `playPattern()` step needs exactly one of `note` or `frequency`; a rest uses exactly `rest: true`. Even a `NOISE` step needs a pitch field, although noise ignores its value. Pattern roots do not accept `duration`. Step `duration` overrides musical timing and controls both voice length and timeline advance; `stepDuration` is only a fallback. Use explicit rest steps for silence between short notes. [source: references/api.md]
+- `duration` includes attack, decay, the held level, and release. For explicit envelopes, `attack < duration` and `release <= duration - attack`.
+- `decay` (integer ms, 0 to 4000) and `sustain` (0 to 1) complete the ADSR envelope. `sustain` below 1 needs a `decay`. `attack + decay <= duration`, and the default 50 ms attack counts toward that budget. The release overlaps the decay and fades from wherever the level is.
+- `filterType` is `none`, `lowpass`, `highpass` or `bandpass`. `filterHz` (20 Hz up to the frequency limit), `filterQ` (0.5 to 10) and `filterHzEnd` (0 or 20 Hz up, an exponential sweep) are rejected while no filter type is active. This filter is separate from, and runs after, the one-pole `lowPassHz`. A chord has no `filterHzEnd`.
+- FM is `fmDepth` (modulation index, 0 to 10), `fmRatio` (0.1 to 16) and an optional `fmDepthEnd`; unlike the other `*End` keys, 0 is a real target, so omit the key for no sweep. Only `WAVE.SINE` can carry FM, and `fmRatio` without a depth is rejected.
+- `detune` (cents, -1200 to 1200) works on `playTone` and `playPattern`. `playChord()` uses `detunes`, an array aligned with the pitches. The detuned pitch, and any `frequencyEnd` target, must stay inside the frequency limits.
+- `patternend` is an event, not a method: it fires once per accepted `playPattern()` with `{ completed: true }` at the natural end, or `{ completed: false }` when a newer pattern replaces it. `stopAll()` and `shutdown()` fire nothing. Remove the listener when the owner closes.
+- `spatialX` (left/right) and `spatialY` (below/above) are finite numbers from -1 to 1 on `playTone`, `playChord`, and `playPattern` roots/steps. Supplying either enables binaural processing, with 0 for the omitted coordinate; omitting both preserves stereo. A chord shares one fixed position. Never combine coordinates with `pan`, `panEnd`, `pans` or `panSpread`, even through pattern inheritance: the call returns `false` with `conflicting_spatial_fields`. [source: references/api.md]
+- A binaural switch and percentage sliders belong to the app. For direct direction sliders, divide signed percentages from -100 to 100 by 100. For amplitude sliders from 0 to 100%, multiply each source's normalized coordinate by the percentage divided by 100; 100% height does not move every source above. Route every effect that should be spatial through that conversion, preserving its synthesis recipe, then send only the coordinates when enabled. When disabled, omit both coordinates; sending two zeros still enables binaural processing. The module has no separate switch option. Positions stay fixed for each event; later events can use updated coordinates. Test with stereo headphones and broadband sounds; the front plane has no rear sources, distance attenuation, room reflections or head tracking. [source: references/api.md]
+- `pan` and `panEnd` range from -1 to 1. `frequencyEnd` accepts 0 through the frequency maximum; targets below 1 Hz disable the linear sweep. `lfoFreq` is the modulation rate in Hz and `lfoDepth` is absolute pitch deviation in Hz, not cents.
+- `WAVE.WAVETABLE` requires `waveTable`: 2 to 64 finite values from -1 to 1, stepped without interpolation. `bitDepth` is 0 or an integer from 2 to 16; `pulseWidth` is 0.05 to 0.95 and only shapes `SQUARE`; `pulseWidthEnd` is 0 or 0.05 to 0.95. For `noiseRate`, `noiseRateEnd`, and `lowPassHz`, 0 means white noise, no sweep, or no filter.
 - `startEngine()`, `playTone()`, `playChord()`, `playPattern()`, and `setVolume()` return `Boolean`; production code must handle rejection where it matters.
+- `getStats()` returns a snapshot without resetting it; `resetStats()` returns nothing and does not stop playback. `setStatsEnabled(enabled)` accepts a Boolean and returns Boolean acceptance. Detect each method with `typeof synth.<method> === 'function'` when supporting older beta binaries. Basic occupancy/queue/rejection counters remain available with diagnostics off; optional render-load timing and output peak/RMS/limiter measurements default off. Android backend underrun/buffer/latency fields are best-effort and independent of that switch. Preserve `null` for unavailable or unmeasured fields: it is not zero. Poll slowly (for example, 5 Hz), cancel the timer with its owner and disable diagnostics when no owner needs them. Render load is callback elapsed work, not total app CPU; Android host comparisons do not establish iOS/device performance, physical underruns, heat or battery behavior. [source: references/api.md] [source: references/audio-engine.md] [source: references/stats-performance.md]
 - Only one pattern can remain pending. A new pattern replaces future steps from the previous one. `stopAll()` fades active voices but does not cancel scheduled steps; `shutdown()` does both and frees the stream.
 
 ## Acoustic decision guide
@@ -63,21 +78,28 @@ Use these as starting regions, then keep every explicit value inside the API lim
 | Intent | Starting design |
 | --- | --- |
 | Clean UI click or feedback | `SINE` or `TRIANGLE`, roughly 30–120 ms, 1–5 ms attack, short fitted release |
-| Retro pickup or melody | `SQUARE`, short notes or a rising `playPattern()` |
+| Retro pickup or melody | `SQUARE`, short notes or a rising `playPattern()`; a narrow `pulseWidth` or a `pulseWidthEnd` sweep thins it, `bitDepth` adds grit |
 | Retro bass | `TRIANGLE`, lower pitch, short attack and controlled release |
-| Hit, hat, explosion texture | `NOISE`, immediate attack and short-to-medium release; layer only when the overlap budget allows |
+| Hit, hat, explosion texture | `NOISE`, immediate attack and short-to-medium release; lower `noiseRate` or `lowPassHz` darkens it; layer only when the overlap budget allows |
+| Coarse DAC-like or buzzy custom voice | `WAVETABLE` with a short asymmetric `waveTable`, optionally with `bitDepth` |
 | Alarm or urgent cue | `SAWTOOTH`, repeated pitches, a sweep, or vibrato around 4–7 Hz; use larger `lfoDepth` only for an obvious effect |
 | Laser or sci-fi movement | One `frequency` plus `frequencyEnd`, short attack, fitted release, optional `pan` → `panEnd` |
+| Headphone cue above/right or below/left | Use `spatialX`/`spatialY` on a broadband sound, without stereo pan fields; verify perceived direction with headphones |
 | Pad or atmosphere | One `playChord()` with `SINE` or `TRIANGLE`, 2000 ms or longer, 300–600 ms attack, 800–1500 ms release when it fits |
+| Plucked string, marimba or keyboard note | `TRIANGLE` or `SINE`, 2 ms attack, `decay` 120–400 ms, `sustain` 0 to 0.3, release that fits |
+| Electric piano, bell or metallic hit | `SINE` with `fmDepth` that falls to `fmDepthEnd: 0`; `fmRatio` 1, 2 or 3.5 for tine-like tones, a non-integer ratio for bells; add `decay` and a low `sustain` |
+| Wah, wind or filter sweep | `SAWTOOTH` or `NOISE` through `filterType: 'bandpass'` or `'lowpass'`, `filterHz` to `filterHzEnd`, `filterQ` 2 to 6 |
+| Thick unison pad or supersaw | `playChord()` with the same pitch repeated and `detunes` of ±5 to ±12 cents; keep the gain staging in mind |
 
 A4 is 440 Hz under twelve-tone equal temperament; each octave doubles or halves frequency. Upward sweeps tend to read as activation, reward, or energy gain; downward sweeps tend to read as dismissal, power-down, or impact. Treat pan as supporting detail because many phone speakers collapse the stereo image.
 
-For playable controls, trigger one event when the finger enters a new key, not on every `touchmove`. For simultaneous musical voices, prefer one atomic `playChord()` call; use small cent offsets in the generated frequency array when a layered sound needs beating because the module has no chord-detune option. Cancel app-owned timers before stopping voices or shutting down the engine. [source: references/recipes.md]
+For playable controls, trigger one event when the finger enters a new key, not on every `touchmove`. For simultaneous musical voices, prefer one atomic `playChord()` call; use `detunes` (cents per pitch) when a layered sound needs beating. Cancel app-owned timers before stopping voices or shutting down the engine. [source: references/recipes.md]
 
 ## Mixing and lifecycle defaults
 
 - Begin with `mixingProfile: 'conservative'`; use `balanced` mainly for one or two voices, `speakerSafe` for demanding small speakers, and `raw` only when the app owns gain staging.
 - Size `maxVoices` for the largest real overlap, including release tails. Capacity is not loudness.
+- On iOS, the default `audioSession: 'playback'` ignores the silent switch and interrupts other apps' audio. Pass `audioSession: 'ambient'` to `startEngine()` when a game should respect the switch and mix with other apps; Android validates the value and ignores it. Profile, voice count, and session are fixed until `shutdown()`.
 - Use one engine owner. On a Titanium screen, start after layout settles and call `shutdown()` when the owner closes.
 - Test on the actual output path. Headphones expose noise and stereo detail; small phone speakers expose weak bass, resonance, and acoustic distortion that a digital limiter cannot repair.
 
@@ -85,7 +107,9 @@ For playable controls, trigger one event when the finger enters a new key, not o
 
 - Re-read the exact method table in `references/api.md`; remove every unsupported property.
 - Confirm pitch fields are mutually exclusive and numeric values are finite and in range.
-- Compute the envelope intersection explicitly.
+- Compute the envelope intersection explicitly, including `attack + decay <= duration`.
+- Check the cross-field rules: `sustain` below 1 needs a `decay`, filter fields need a `filterType`, FM needs a sine and a depth.
+- Check installed spatial limits before using binaural coordinates; remove conflicting stereo fields at both pattern root and step. Omit coordinates when the app switch is off.
 - Use `WAVE` constants from `getDefaults()`.
 - Use `playChord()` for one simultaneous musical event instead of several hotter independent tones.
 - Include startup and cleanup only at the ownership level relevant to the request.