exp-runtime-formats 0.5.0__tar.gz

exp_runtime_formats-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Josh Mcdaniel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

exp_runtime_formats-0.5.0/MANIFEST.in

@@ -0,0 +1,4 @@
+# Only authored component source, metadata and license.
+global-exclude *
+include LICENSE README.md pyproject.toml MANIFEST.in
+recursive-include src/exp_runtime *.py

exp_runtime_formats-0.5.0/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: exp-runtime-formats
+Version: 0.5.0
+Summary: EXP containers, KiWi decoding and native resource parsers
+License: MIT License
+        
+        Copyright (c) 2025 Josh Mcdaniel
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: images
+Requires-Dist: Pillow>=10; extra == "images"
+Dynamic: license-file
+
+# EXP Runtime — formats
+
+EXP containers, KiWi decoding and native resource parsers. This is a component of the single
+[EXP Runtime project](https://github.com/joshrmcdaniel/exp-runtime), maintained
+and released together with its other wheels. Python imports use the shared
+`exp_runtime` namespace.
+
+Install `exp-runtime[tools]` for file tools, `exp-runtime[engine,shs]` or
+`exp-runtime[engine,cod]` for a headless game, or `exp-runtime[player]` for
+the desktop player with both games. Individual component wheels also support
+selective installs. See the project's `docs/SDK.md` for APIs and examples.
+
+No original game content is included. Users supply their own game files.
+The inherited MIT license and attribution are included in LICENSE; see
+[provenance](https://github.com/joshrmcdaniel/exp-runtime/blob/main/docs/PROVENANCE.md).

exp_runtime_formats-0.5.0/README.md

@@ -0,0 +1,15 @@
+# EXP Runtime — formats
+
+EXP containers, KiWi decoding and native resource parsers. This is a component of the single
+[EXP Runtime project](https://github.com/joshrmcdaniel/exp-runtime), maintained
+and released together with its other wheels. Python imports use the shared
+`exp_runtime` namespace.
+
+Install `exp-runtime[tools]` for file tools, `exp-runtime[engine,shs]` or
+`exp-runtime[engine,cod]` for a headless game, or `exp-runtime[player]` for
+the desktop player with both games. Individual component wheels also support
+selective installs. See the project's `docs/SDK.md` for APIs and examples.
+
+No original game content is included. Users supply their own game files.
+The inherited MIT license and attribution are included in LICENSE; see
+[provenance](https://github.com/joshrmcdaniel/exp-runtime/blob/main/docs/PROVENANCE.md).

exp_runtime_formats-0.5.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools >= 61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "exp-runtime-formats"
+version = "0.5.0"
+description = "EXP containers, KiWi decoding and native resource parsers"
+readme = "README.md"
+license = {file = "LICENSE"}
+requires-python = ">=3.10"
+dependencies = []
+
+[project.optional-dependencies]
+images = ["Pillow>=10"]
+
+[project.scripts]
+exp-tool = "exp_runtime.cli:main"
+shs-tool = "exp_runtime.cli:main"
+
+[tool.setuptools]
+include-package-data = false
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["exp_runtime", "exp_runtime.*"]
+namespaces = true

exp_runtime_formats-0.5.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

exp_runtime_formats-0.5.0/src/exp_runtime/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running the tools as ``python -m exp_runtime``."""
+
+from .cli import main
+
+main()

exp_runtime_formats-0.5.0/src/exp_runtime/atlas.py

@@ -0,0 +1,203 @@
+"""Packed RGBA sprite atlases used by the native minigame renderer.
+
+This is the CS sprite-atlas path (000507b8 / 000503dc), separate from
+ImagePack's literal-image path. All dimensions and extents are bounded.
+"""
+from dataclasses import dataclass
+
+from .exp import MAX_PAYLOAD
+from .ui_assets import Raster, UIAssetError, _Reader
+
+
+@dataclass(frozen=True)
+class AtlasFrame:
+    x: int
+    y: int
+    width: int
+    height: int
+    stored_width: int
+    stored_height: int
+
+
+@dataclass(frozen=True)
+class SpriteAtlas:
+    flags: int
+    sequences: tuple[tuple[int, ...], ...]
+    parts: tuple[tuple[tuple[int, int, int], ...], ...]
+    transforms: tuple[tuple[int, int], ...]
+    frames: tuple[AtlasFrame, ...]
+    image: Raster
+
+    @classmethod
+    def parse(cls, data):
+        r = _Reader(data)
+        flags, capacity, count = r.integer('B'), r.count(), r.count('b')
+        if flags & ~0x3f:
+            raise UIAssetError('Unsupported sprite-atlas flags')
+        sequences = []
+        if count:
+            base, total = r.integer(), r.count()
+            for _ in range(count):
+                sequences.append(tuple(base + r.integer('h' if flags & 4 else 'b')
+                                       for __ in range(r.count('b'))))
+            if sum(map(len, sequences)) != total:
+                raise UIAssetError('Inconsistent atlas sequences')
+        count, total = r.count(), r.count()
+        parts = []
+        for _ in range(count):
+            parts.append(tuple((r.integer('h' if flags & 1 else 'b'),
+                                r.integer('h' if flags & 2 else 'b'),
+                                r.integer('h' if flags & 2 else 'b'))
+                               for __ in range(r.count('b'))))
+        if sum(map(len, parts)) != total:
+            raise UIAssetError('Inconsistent atlas parts')
+        transforms = tuple(r.unpack('hb') for _ in range(r.count()))
+        scale, size, count = r.integer(), r.count(), r.count()
+        if scale <= 0 or size <= 0 or size * size * 4 > MAX_PAYLOAD or count != capacity:
+            raise UIAssetError('Invalid sprite-atlas dimensions')
+        frames = []
+        for _ in range(count):
+            x, y, w, h, sw, sh = r.unpack('hhhhhh')
+            x, y = x * scale, y * scale
+            if (min(x, y, w, h, sw, sh) < 0 or w * h * 4 > MAX_PAYLOAD
+                    or x + sw > size or y + sh > size):
+                raise UIAssetError('Sprite frame is outside its atlas')
+            frames.append(AtlasFrame(x, y, w, h, sw, sh))
+        data = r.take(size * size * 4)
+        r.finish()
+        # 000503dc reverses each stored A,B,G,R quadruple before upload.
+        rgba = bytearray(len(data))
+        rgba[0::4], rgba[1::4], rgba[2::4], rgba[3::4] = data[3::4], data[2::4], data[1::4], data[0::4]
+        for frame, transform in transforms:
+            if not 0 <= frame < count or not 0 <= transform <= 7:
+                raise UIAssetError('Invalid atlas transform')
+        for group in parts:
+            for index, _, __ in group:
+                if not (-len(parts) <= index < count):
+                    raise UIAssetError('Invalid atlas part reference')
+        return cls(flags, tuple(sequences), tuple(parts), transforms, tuple(frames),
+                   Raster(size, size, bytes(rgba)))
+
+    def raster(self, index):
+        """Decode a positive literal frame; composites retain signed references."""
+        if not 0 <= index < len(self.frames):
+            raise UIAssetError('Absent atlas frame')
+        f = self.frames[index]
+        if f.width != f.stored_width or f.height != f.stored_height:
+            raise UIAssetError('Scaled atlas frame requires renderer resampling')
+        row_size = f.width * 4
+        pixels = b''.join(self.image.pixels[(y * self.image.width + f.x) * 4:
+                                          (y * self.image.width + f.x) * 4 + row_size]
+                          for y in range(f.y, f.y + f.height))
+        result = Raster(f.width, f.height, pixels)
+        for frame, transform in self.transforms:
+            if frame == index:
+                result = result.transformed(transform)
+        return result
+
+    def literals(self, index):
+        """Flatten signed composite references, preserving painter order/origin."""
+        result = []
+
+        def visit(ref, x, y, ancestors):
+            if ref >= 0:
+                if ref >= len(self.frames) or len(result) >= 4096:
+                    raise UIAssetError('Invalid or oversized atlas composite')
+                result.append((ref, x, y))
+                return
+            if ref in ancestors or len(ancestors) >= 64 or ~ref >= len(self.parts):
+                raise UIAssetError('Invalid or cyclic atlas composite')
+            for child, dx, dy in self.parts[~ref]:
+                visit(child, x + dx, y + dy, ancestors + (ref,))
+
+        visit(index, 0, 0, ())
+        return tuple(result)
+
+
+@dataclass(frozen=True)
+class AtlasFont:
+    """000538ac: six-byte header, then (byte, s16 x, s16 y, s8 width)."""
+    space_width: int
+    style: int
+    tracking: int
+    height: int
+    glyphs: dict[int, tuple[int, int, int]]
+
+    @classmethod
+    def parse(cls, data, atlas):
+        r = _Reader(data)
+        space, style, tracking = r.integer('b'), r.integer('B'), r.integer('b')
+        count, height = r.count(), r.integer('b')
+        if height <= 0 or space < 0 or count > 256:
+            raise UIAssetError('Invalid atlas font header')
+        glyphs = {}
+        for _ in range(count):
+            code, x, y, width = r.unpack('Bhhb')
+            if min(x, y, width) < 0 or x + width > atlas.width or y + height > atlas.height:
+                raise UIAssetError('Font glyph is outside its atlas')
+            glyphs[code] = x, y, width
+        r.finish()
+        return cls(space, style, tracking, height, glyphs)
+
+    def glyph(self, char):
+        code = ord(char)
+        code = {0x91: 39, 0x92: 39, 0x93: 34, 0x94: 34, 0x96: 45}.get(code, code)
+        if code not in self.glyphs:
+            if 97 <= code <= 122 or 224 <= code <= 252:
+                code -= 32
+            elif 65 <= code <= 90 or 192 <= code <= 220:
+                code += 32
+        return self.glyphs.get(code)
+
+    @property
+    def line_gap(self):
+        # 000538ac stores header byte 1 at +0x139; 00054490 adds it to
+        # each line's height. The older parser called this byte "style".
+        return self.style if self.style < 128 else self.style - 256
+
+    def char_width(self, char, monospace=None):
+        if monospace is not None:
+            return self.char_width(monospace)
+        glyph = self.glyph(char)
+        return glyph[2] if glyph is not None else self.space_width
+
+    def width(self, text, monospace=None):
+        """000535fc: trim leading spaces, omit the last tracking interval."""
+        return max((max(0, sum(self.char_width(c, monospace) + self.tracking for c in line)
+                        - self.tracking) if line else 0
+                    for line in text.lstrip(' ').split('\n')), default=0)
+
+    def wrap(self, text, width):
+        """00054490: byte glyph advances, space wrapping and explicit newlines."""
+        if width <= 0:
+            raise UIAssetError('Atlas text width must be positive')
+        lines = []
+        while text:
+            text = text.lstrip(' ')
+            if not text:
+                break
+            end, advance = 0, 0
+            while end < len(text) and text[end] != '\n':
+                glyph_width = self.char_width(text[end])
+                if glyph_width > width:
+                    raise UIAssetError('Atlas text column cannot fit a glyph')
+                if advance + glyph_width > width:
+                    break
+                advance += glyph_width + self.tracking
+                end += 1
+            if end == len(text):
+                lines.append(text)
+                break
+            if text[end] == '\n':
+                lines.append(text[:end])
+                text = text[end + 1:]
+            else:
+                space = text.rfind(' ', 0, end + 1)
+                if space > 0:
+                    end = space
+                lines.append(text[:end])
+                text = text[end:]
+        return tuple(lines)
+
+    def text_height(self, lines):
+        return len(lines) * (self.height + self.line_gap) - self.line_gap if lines else 0

exp_runtime_formats-0.5.0/src/exp_runtime/cli.py

@@ -0,0 +1,186 @@
+"""Import, inspect and launch player-supplied EXP game content."""
+
+import argparse
+from dataclasses import asdict
+from importlib.util import find_spec
+import json
+import logging
+import sys
+import tempfile
+
+from pathlib import Path
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    """Build the argument parser with all subcommands."""
+    parser = argparse.ArgumentParser(
+        prog="exp-tool",
+        description="Inspect EXP files and play SHS or Cause of Death with your own game data.",
+    )
+    parser.add_argument(
+        "-v", "--verbose",
+        action="count",
+        default=0,
+        help="Increase verbosity (-v for INFO, -vv for DEBUG).",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    inspect_parser = subparsers.add_parser('inspect', help='Inspect an EXP without installing the engine or games.')
+    inspect_parser.add_argument('archive', type=Path)
+    extract_parser = subparsers.add_parser('extract', help='Extract EXP resources by numeric ID into a new directory.')
+    extract_parser.add_argument('archive', type=Path)
+    extract_parser.add_argument('--output', type=Path, required=True)
+
+    trace_parser = subparsers.add_parser(
+        "trace", help="Execute KiWi to the first pending action and print a JSON trace.",
+    )
+    trace_parser.add_argument("archive", type=Path, help="Path to the .exp archive.")
+    trace_parser.add_argument("--max-steps", type=int, default=100_000)
+    trace_parser.add_argument("--max-events", type=int, default=10_000)
+    trace_parser.add_argument('--game', choices=('shs', 'cod'), default='shs', help='Native host profile (default: shs).')
+
+    import_parser = subparsers.add_parser("import", help="Create a local library from your APK or IPA and episode files.")
+    source = import_parser.add_mutually_exclusive_group(required=True)
+    source.add_argument("--apk", type=Path, help="Your SHS Android 1.0.9 APK.")
+    source.add_argument("--ipa", type=Path, help="Your SHS or Cause of Death IPA with compatible game assets.")
+    import_parser.add_argument('--game', choices=('shs', 'cod'), help='Require assets for this game (otherwise detected).')
+    import_parser.add_argument("--music-apk", type=Path,
+                               help="Optional Android 1.0.9 APK supplying missing IPA music.")
+    import_parser.add_argument("--episodes", type=Path, nargs="+", action="extend", default=[],
+                               help="EXP files, episode ZIPs/RARs or directories; subfolders are scanned recursively.")
+    import_parser.add_argument("--library", type=Path, required=True,
+                               help="New library directory for this game.")
+
+    list_parser = subparsers.add_parser("list", help="List episodes in a local content library.")
+    list_parser.add_argument("--library", type=Path, default=Path(".shs-library"))
+    from .languages import TITLE_LANGUAGES
+    list_parser.add_argument('--title-language', choices=TITLE_LANGUAGES,
+                             help='Episode title language; defaults to the library preference. Does not translate story text.')
+
+    music_parser = subparsers.add_parser("add-music", help="Add missing music to an existing IPA library.")
+    music_parser.add_argument("--apk", type=Path, required=True, help="Your SHS Android 1.0.9 APK.")
+    music_parser.add_argument("--library", type=Path, required=True, help="Existing IPA library.")
+
+    play_parser = subparsers.add_parser("play", help="Open the main menu, or start a selected episode.")
+    play_parser.add_argument("--library", type=Path, help="Content library; defaults to the existing local library or user application data.")
+    play_parser.add_argument("--episode", help="Start directly: unique ID prefix, filename, or title from list.")
+    saves = play_parser.add_mutually_exclusive_group()
+    saves.add_argument("--resume", action="store_true", help="Load this episode's local save slot.")
+    saves.add_argument("--load", type=Path, help="Load a specific runtime JSON save.")
+    play_parser.add_argument("--no-audio", action="store_true")
+    play_parser.add_argument('--game', choices=('shs', 'cod'), help='Open this game directly instead of the chooser.')
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    """CLI entry point."""
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    # Configure logging
+    log_level = logging.WARNING
+    if args.verbose >= 2:
+        log_level = logging.DEBUG
+    elif args.verbose >= 1:
+        log_level = logging.INFO
+    logging.basicConfig(level=log_level, format="%(levelname)s: %(message)s")
+
+    if args.command in ('inspect', 'extract'):
+        from .exp import ContentError, ExpArchive
+        try:
+            archive = ExpArchive(args.archive.read_bytes())
+            if args.command == 'inspect':
+                result = dict(resources=sorted(archive.entries), scripts=sorted(archive.programs()))
+                if 1 in archive.entries:
+                    result['metadata'] = asdict(archive.metadata())
+                print(json.dumps(result, indent=2, ensure_ascii=False))
+            else:
+                destination = args.output
+                if destination.exists():
+                    raise ContentError(f'Output already exists: {destination}; choose a new directory')
+                destination.parent.mkdir(parents=True, exist_ok=True)
+                # A corrupt record must not leave a partial extraction. IDs
+                # are validated integers; original archive paths are not used.
+                with tempfile.TemporaryDirectory(dir=destination.parent, prefix='.exp-extract-') as temporary:
+                    staged = Path(temporary) / 'resources'
+                    staged.mkdir()
+                    for resource in archive.entries:
+                        (staged / f'{resource}.bin').write_bytes(archive.read(resource))
+                    staged.rename(destination)
+                print(f'Extracted {len(archive.entries)} resources into {destination}')
+        except (ContentError, OSError) as error:
+            parser.error(str(error))
+        return
+
+    if args.command in ('import', 'list', 'play', 'add-music', 'trace'):
+        if find_spec('exp_runtime.engine') is None:
+            parser.error('This command needs the engine and a game adapter. '
+                         'Install "exp-runtime[engine,shs]" or "exp-runtime[engine,cod]".')
+    if args.command == 'play' and find_spec('exp_runtime.application') is None:
+        parser.error('The player is not installed. Install "exp-runtime[player]".')
+
+    if args.command in ("import", "list", "play", "add-music"):
+        from .content import ContentError, ContentLibrary, import_game
+        from .runtime import SaveError
+        from .vm import VMError
+
+        try:
+            if args.command == "import":
+                manifest = import_game(args.apk or args.ipa, args.episodes, args.library,
+                                       music_apk=args.music_apk, game=args.game)
+                print(f"Imported {len(manifest['episodes'])} episodes into {args.library}")
+                return
+            if args.command == 'play':
+                if (args.load or args.resume) and not args.episode:
+                    parser.error('--load and --resume require --episode; omit them to use the main menu')
+                try:
+                    from .application import Application
+                except ModuleNotFoundError as error:
+                    if error.name != 'pygame':
+                        raise
+                    parser.error('Desktop support is not installed. Run uv sync --extra desktop '
+                                 'or install the package with its [desktop] extra.')
+                app = Application(args.library, audio=not args.no_audio, game_key=args.game)
+                try:
+                    if args.episode:
+                        if not app.library:
+                            raise ContentError(app.message or 'Import your APK or IPA before selecting an episode')
+                        app.selected = app.library.select(args.episode)['id']
+                        app.start(resume=args.resume, load_path=args.load)
+                except Exception:
+                    app.close()
+                    raise
+                app.run()
+                return
+            with ContentLibrary(args.library) as library:
+                if args.command == 'add-music':
+                    count = library.add_music_apk(args.apk)
+                    print(f'Added {count} missing music tracks.' if count else 'No missing music tracks to add.')
+                    return
+                library.ensure_builtin_episodes()
+                if args.command == "list":
+                    from .menu import MenuState
+                    state = MenuState(library)
+                    if args.title_language is not None:
+                        state.title_language = args.title_language
+                    for record in library.episodes:
+                        print(f"{record['id'][:12]}  {state.title(record)}  ({record['name']})")
+                    return
+        except (ContentError, SaveError, VMError, OSError) as error:
+            parser.error(str(error))
+
+    elif args.command == "trace":
+        from .trace import trace_archive
+
+        try:
+            result = trace_archive(args.archive, max_steps=args.max_steps, max_events=args.max_events, game=args.game)
+        except (ValueError, OSError) as error:
+            parser.error(str(error))
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+        if result["status"] in ("vm_error", "missing_script"):
+            sys.exit(1)
+
+    else:
+        parser.print_help()
+        sys.exit(1)

exp_runtime_formats-0.5.0/src/exp_runtime/decode/__init__.py

@@ -0,0 +1 @@
+"""Lossless KiWi bytecode decoding; EXP archives are handled by content.py."""

exp_runtime_formats-0.5.0/src/exp_runtime/decode/bytecode.py

@@ -0,0 +1,119 @@
+"""Lossless KiWi v2 decoding, verified against libshs09.so FUN_00057068.
+
+This is a binary representation, not a reconstruction of game actions.
+Data words may contain packed text, mutable variables, or other values.
+"""
+from dataclasses import dataclass
+import struct
+
+
+# int32 table at 0x002593a8: only entries equal to 1 consume an operand.
+OPERAND_OPCODES = frozenset({
+    0x01, 0x19, 0x1A, 0x1B, 0x1E, 0x1F, 0x20, 0x23,
+    0x28, 0x29, 0x2A, 0x2B, 0x2C, 0x2D, 0x2E, 0x40, 0x41, 0x5C,
+})
+
+
+class KiwiFormatError(ValueError):
+    """Unsupported or truncated KiWi input, with a file byte offset."""
+
+
+@dataclass(frozen=True)
+class BytecodeInstruction:
+    pc: int
+    byte_offset: int
+    opcode: int
+    operand: int | None
+
+    @property
+    def yield_id(self) -> int | None:
+        if self.opcode == 0x1E:
+            return self.operand
+        if self.opcode == 0x1F:
+            return self.operand >> 8
+        return None
+
+    def branch_target(self) -> int | None:
+        """Statically encoded target in logical instruction indices.
+
+        Native PC arithmetic wraps at 16 bits. Dynamic return opcode 0x43
+        is deliberately not assigned a guessed target.
+        """
+        if self.opcode == 0x29:
+            return self.operand
+        if self.opcode in {0x28, 0x2A, 0x2B, 0x2C, 0x2D, 0x2E}:
+            return (self.pc + self.operand) & 0xFFFF
+        if self.opcode == 0x5C:
+            return (self.pc + (self.operand >> 8)) & 0xFFFF
+        return None
+
+
+@dataclass(frozen=True)
+class KiwiProgram:
+    version: int
+    previous_flag: int
+    previous_data_count: int | None
+    previous_instruction_count: int | None
+    flag: int
+    main_words: tuple[int, ...]
+    gap_count: int
+    extra_words: tuple[int, ...]
+    instructions: tuple[BytecodeInstruction, ...]
+
+    def to_bytes(self) -> bytes:
+        """Re-encode every stored field without interpreting data words."""
+        header = b'kiwi' + bytes((self.version, self.previous_flag))
+        if self.previous_flag:
+            header += struct.pack('>HH', self.previous_data_count,
+                                  self.previous_instruction_count)
+        header += bytes((self.flag,))
+        header += struct.pack('>4H', len(self.main_words), self.gap_count,
+                              len(self.extra_words), len(self.instructions))
+        words = self.main_words + self.extra_words
+        body = struct.pack(f'>{len(words)}H', *words)
+        code = bytearray()
+        for instruction in self.instructions:
+            code.append(instruction.opcode)
+            if instruction.operand is not None:
+                code.extend(struct.pack('>H', instruction.operand))
+        return header + body + code
+
+
+def decode_program(data: bytes) -> KiwiProgram:
+    """Decode v2 strictly; never turn truncated input into invented operands."""
+    pos = 0
+
+    def take(size):
+        nonlocal pos
+        if pos + size > len(data):
+            raise KiwiFormatError(f'truncated KiWi at byte 0x{pos:x}: need {size} bytes')
+        result = data[pos:pos + size]
+        pos += size
+        return result
+
+    def u16():
+        return struct.unpack('>H', take(2))[0]
+
+    if take(4) != b'kiwi':
+        raise KiwiFormatError('invalid KiWi signature at byte 0x0')
+    version = take(1)[0]
+    if version != 2:
+        raise KiwiFormatError(f'unsupported KiWi version {version} at byte 0x4')
+    previous_flag = take(1)[0]
+    previous_data = u16() if previous_flag else None
+    previous_code = u16() if previous_flag else None
+    flag = take(1)[0]
+    main, gap, extra, count = (u16() for _ in range(4))
+    main_words = tuple(u16() for _ in range(main))
+    extra_words = tuple(u16() for _ in range(extra))
+    instructions = []
+    base_pc = previous_code or 0
+    for index in range(count):
+        offset = pos
+        opcode = take(1)[0]
+        operand = u16() if opcode in OPERAND_OPCODES else None
+        instructions.append(BytecodeInstruction(base_pc + index, offset, opcode, operand))
+    if pos != len(data):
+        raise KiwiFormatError(f'{len(data) - pos} trailing bytes at byte 0x{pos:x}')
+    return KiwiProgram(version, previous_flag, previous_data, previous_code,
+                       flag, main_words, gap, extra_words, tuple(instructions))