exp-runtime-creator 0.6.0__py3-none-any.whl

exp_runtime/creator/debugger.py

@@ -0,0 +1,123 @@
+"""Source-node stepping and breakpoints using the production VM and services."""
+from dataclasses import asdict
+from pathlib import Path
+from types import SimpleNamespace
+
+from exp_runtime.exp import ExpArchive
+from .compiler import VARIABLE_OWNER, compile_details
+from .model import ProjectError
+
+
+class _Paused(Exception):
+    pass
+
+
+class DebugSession:
+    def __init__(self, project, *, start=None, seed=None, library=None, language=None):
+        from exp_runtime.runtime import Session
+        from exp_runtime.content import digest
+        from exp_runtime.vm import StopKind
+        self.project = project
+        self.context = None
+        self.compilation = compile_details(project, start=start, language=language)
+        self.archive = ExpArchive(self.compilation.data)
+        programs = self.archive.programs()
+        self.resources = SimpleNamespace(library=SimpleNamespace(game_id=project.game, directory=Path('.')),
+            identity={'profile': 'creator-debug', 'episode_sha256': digest(self.compilation.data)},
+            program=programs.__getitem__, exists=lambda key: key in self.archive.entries or
+            any(a.id == key for a in project.assets))
+        if library:
+            from .preview import preview_resources
+            self.context = preview_resources(self.compilation.data, library, project.game)
+            self.resources = self.context.__enter__()
+        try: self.session = Session(self.resources)
+        except Exception:
+            self.close()
+            raise
+        if seed is not None:
+            if type(seed) is not int or not 0 <= seed <= 0xffffffff:
+                self.close()
+                raise ProjectError('Seed must be an unsigned 32-bit integer')
+            self.session.engine.random.state = seed
+            self.session.engine.random48.state = (seed << 16) | 0x330e
+        self.seed = seed
+        self.locations = {script: {pc: node for node, pc in entries.items()}
+                          for script, entries in self.compilation.locations.items()}
+        self.breakpoints = set()
+        self.trace = []
+        self.visited = set()
+        self.overrides = []
+        self.paused = False
+        self._skip = None
+        self._step = True
+        original_run = self.session.vm.run
+        def run(budget=100000):
+            for _ in range(budget):
+                position = (self.session.scene, self.session.vm.pc)
+                node = self.locations.get(position[0], {}).get(position[1])
+                if node and position != self._skip and (self._step or node in self.breakpoints):
+                    self._skip = position
+                    self.paused = True
+                    raise _Paused()
+                self._skip = None
+                result = original_run(1)
+                if node:
+                    self.visited.add(node)
+                    self.trace.append(node)
+                    del self.trace[:-500]
+                if result.kind != StopKind.BUDGET: return result
+            return result
+        self.session.vm.run = run
+        try: self.resume(step=True)
+        except Exception:
+            self.close()
+            raise
+
+    def resume(self, *, step=False, answer=None, provide_answer=False, milliseconds=0):
+        self.paused = False
+        self._step = step
+        try:
+            if milliseconds:
+                self.session.tick(milliseconds)
+            elif provide_answer:
+                self.session.answer(answer)
+            else:
+                self.session.advance()
+        except _Paused:
+            pass
+        return self.state()
+
+    def state(self):
+        session = self.session
+        pc = session.pending.request.pc if session.pending else session.vm.pc
+        entries = self.locations.get(session.scene, {})
+        before = [location for location in entries if location <= pc]
+        node = entries[max(before)] if before else None
+        values = {}
+        for name, address in self.compilation.variables.items():
+            values[name] = (session.engine.numbers.get(session.engine.number_key(VARIABLE_OWNER, address), 0)
+                           if self.compilation.shared_variables else session.vm.data[address])
+        pending = session.pending
+        return {'node': node, 'scene': session.scene, 'pc': pc, 'variables': values,
+                'text_variables': dict(session.engine.strings),
+                'action': pending.name if pending else None,
+                'details': pending.details if pending else {}, 'trace': list(self.trace),
+                'minigames': {name: asdict(value) for name in ('word_game', 'football', 'word_grid')
+                              if (value := getattr(session.engine, name)) is not None},
+                'stack': list(session.vm.stack), 'result': session.vm.result,
+                'pending_arguments': list(session.vm.pending.args) if session.vm.pending else []}
+
+    def set_variable(self, name, value):
+        if name not in self.compilation.variables or type(value) is not int or not -32768 <= value <= 32767:
+            raise ProjectError('Choose an existing numeric variable and signed 16-bit value')
+        address = self.compilation.variables[name]
+        if self.compilation.shared_variables:
+            self.session.engine.numbers[self.session.engine.number_key(VARIABLE_OWNER, address)] = value
+        else:
+            self.session.vm.write_word(address, value)
+        self.overrides.append(dict(variable=name, value=value))
+
+    def close(self):
+        if self.context is not None:
+            self.context.__exit__(None, None, None)
+            self.context = None

exp_runtime/creator/diagnostics.py

@@ -0,0 +1,86 @@
+"""Recoverable authoring diagnostics using the same checks as EXP compilation."""
+from collections import deque
+
+from .compiler import compile_details, validate_node
+from .features import text_fields, parameters
+from .graph import edges
+from .model import ProjectError, validate_structure
+
+
+def diagnose(project):
+    issues = []
+    def issue(code, message, *, node=None, field=None, severity='error', suggestion=''):
+        issues.append(dict(code=code, severity=severity, node_id=node, field=field,
+                           message=str(message), suggestion=suggestion))
+    try: validate_structure(project)
+    except ProjectError as error:
+        issue('invalid_structure', error, suggestion='Correct the document types and limits before checking execution.')
+        return dict(valid=False, issues=issues)
+    nodes = {n.id: n for n in project.nodes}
+    assets = {a.id: a for a in project.assets}
+    characters = {c.id: c for c in project.characters}
+    if not project.native:
+        if project.start not in nodes:
+            issue('missing_start', 'Starting node does not exist', field='start', suggestion='Select an existing node ID.')
+        for edge in edges(project):
+            if edge['target'] not in nodes:
+                issue('missing_target', f'Destination {edge["target"]!r} does not exist', node=edge['source'],
+                      field=edge['field'], suggestion='Connect this edge to an existing node.')
+        for character in project.characters:
+            for field, resource in [('portrait', character.portrait), *[(f'expressions.{i}', v) for i, v in enumerate(character.expressions)]]:
+                if resource is not None and resource not in assets:
+                    issue('missing_asset', f'Character {character.id} references image {resource}',
+                          field=f'characters.{character.id}.{field}', suggestion='Import that image or clear the reference.')
+        for node in project.nodes:
+            try: validate_node(project, node, nodes, assets, characters)
+            except (ProjectError, TypeError, ValueError, KeyError) as error:
+                if not any(i['node_id'] == node.id and i['code'] == 'missing_target' for i in issues):
+                    field = ('text' if node.kind in ('dialogue', 'choice') and not node.text.strip() else
+                             'character' if node.character and node.character not in characters else 'params')
+                    issue('invalid_node', error, node=node.id, field=field,
+                          suggestion=f'Consult schema_get for the {node.kind} node requirements.')
+            from .expressions import parse
+            expressions = [(f'options.{i}.condition', o.condition) for i, o in enumerate(node.options)]
+            if node.kind in ('set', 'branch'): expressions.append(('params.expression', parameters(node)['expression']))
+            for field, expression in expressions:
+                if expression:
+                    try: parse(expression)
+                    except (ProjectError, TypeError, ValueError) as error:
+                        issue('invalid_expression', error, node=node.id, field=field,
+                              suggestion='Use integers, variable names, arithmetic, comparisons and and/or/not.')
+            if node.kind == 'choice' and node.options and all(o.condition for o in node.options):
+                issue('conditional_choices', 'Every answer has a condition; some states may offer no enabled answer.',
+                      node=node.id, field='options', severity='warning', suggestion='Add an unconditional answer or test all relevant states.')
+        try:
+            texts = text_fields(project)
+            for key, original in texts.items():
+                value = project.locales.get(project.language, {}).get(key, original)
+                try: value.encode('latin-1')
+                except (AttributeError, UnicodeError):
+                    node_id = next((n.id for n in project.nodes if key.startswith(f'node.{n.id}.')), None)
+                    issue('text_encoding', 'Text cannot be encoded in native Latin-1', node=node_id, field=key,
+                          suggestion='Use Latin-1 characters in the selected export language.')
+            for language, translations in project.locales.items():
+                for key in translations.keys() - texts.keys():
+                    issue('unused_translation', f'{language}: unknown translation key', field=key, severity='warning',
+                          suggestion='Remove or rename this translation to match a current field key.')
+        except (KeyError, TypeError, ValueError):
+            pass  # Invalid structured tables already have a node diagnostic.
+    reached, queue = set(), deque([project.start])
+    while queue:
+        key = queue.popleft()
+        if key not in nodes or key in reached: continue
+        reached.add(key); queue.extend(target for _, target in nodes[key].links())
+    if not project.native:
+        for key in nodes.keys() - reached:
+            issue('unreachable_node', 'No graph path from the starting node', node=key, severity='warning',
+                  suggestion='Connect this node or remove it if it is no longer needed.')
+    compilation = None
+    try: compilation = compile_details(project)
+    except (ProjectError, TypeError, ValueError, KeyError) as error:
+        if not any(i['severity'] == 'error' for i in issues):
+            issue('compile_error', error, suggestion='Correct the compiler error before export; no output was written.')
+    result = dict(valid=not any(i['severity'] == 'error' for i in issues), issues=issues,
+                  coverage=dict(reachable=len(reached), total=len(nodes), analysis='structural'))
+    if compilation: result.update(bytes=len(compilation.data), scripts=sorted(compilation.locations))
+    return result

exp_runtime/creator/editing.py

@@ -0,0 +1,80 @@
+"""Shared, UI-independent graph edits and crash-recovery documents."""
+from copy import deepcopy
+from dataclasses import asdict
+import json
+from pathlib import Path
+import uuid
+
+from .model import (Choice, Node, ProjectError, atomic_write, project_from_record,
+                    project_record, validate_structure)
+
+
+def copy_nodes(project, selected):
+    if project.native:
+        raise ProjectError('Native blocks retain fixed PCs and cannot be duplicated')
+    return json.dumps({'format': 'exp-creator-nodes', 'nodes': [asdict(n) for n in project.nodes if n.id in selected]})
+
+
+def paste_nodes(project, text):
+    try:
+        data = json.loads(text)
+        if data['format'] != 'exp-creator-nodes' or not 1 <= len(data['nodes']) <= 2000 or project.native:
+            raise ValueError('unsupported clipboard')
+        candidate = deepcopy(project)
+        ids = {record['id']: uuid.uuid4().hex[:12] for record in data['nodes']}
+        if len(ids) != len(data['nodes']): raise ValueError('duplicate source IDs')
+        for record in data['nodes']:
+            node = Node(**dict(record, options=[Choice(**o) for o in record['options']]))
+            node.id = ids[node.id]
+            node.x += 40; node.y += 40
+            node.next, node.otherwise = ids.get(node.next, node.next), ids.get(node.otherwise, node.otherwise)
+            for option in node.options: option.target = ids.get(option.target, option.target)
+            candidate.nodes.append(node)
+        validate_structure(candidate)
+        project.nodes = candidate.nodes
+        return list(ids.values())
+    except (KeyError, TypeError, ValueError, RecursionError) as error:
+        raise ProjectError(f'Cannot paste nodes: {error}') from error
+
+
+def auto_layout(project):
+    if len(project.nodes) > 20000: raise ProjectError('A graph can contain at most 20000 nodes')
+    remaining = {node.id: node for node in project.nodes}
+    frontier, level = [project.start], 0
+    rows = [0] * 40
+    while remaining:
+        current = list(dict.fromkeys(key for key in frontier if key in remaining))
+        if not current: current = [next(iter(remaining))]
+        frontier = []
+        for row, key in enumerate(current):
+            node = remaining.pop(key)
+            column = level % 40
+            while rows[column] >= 500: column = (column + 1) % 40
+            node.x, node.y = 40 + column * 310, 60 + rows[column] * 180
+            rows[column] += 1
+            frontier.extend(target for _, target in node.links() if target in remaining)
+        level += 1
+
+
+class Recovery:
+    def __init__(self, directory, identity=None):
+        self.path = Path(directory) / ((identity or uuid.uuid4().hex) + '.recovery.json')
+
+    def write(self, project, source=None):
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        record = {'source': str(Path(source).resolve()) if source else None, 'project': project_record(project)}
+        atomic_write(self.path, json.dumps(record, ensure_ascii=True).encode())
+
+    def remove(self):
+        self.path.unlink(missing_ok=True)
+
+    @staticmethod
+    def read(path):
+        from .model import MAX_PROJECT_BYTES
+        path = Path(path)
+        if path.stat().st_size > MAX_PROJECT_BYTES: raise ProjectError('Recovery file exceeds the project limit')
+        try:
+            record = json.loads(path.read_text(encoding='utf-8'))
+            return project_from_record(record['project']), record.get('source')
+        except (KeyError, ValueError, TypeError) as error:
+            raise ProjectError(f'Invalid recovery document: {error}') from error

exp_runtime/creator/expressions.py

@@ -0,0 +1,81 @@
+"""A small numeric expression language compiled to native KiWi instructions.
+
+No Python evaluation, calls, attribute access, indexing or external data.
+Arithmetic uses the VM's signed-word wrapping and truncating division.
+"""
+import ast
+from .model import ProjectError
+
+BINARY = {ast.Add: 0x50, ast.Sub: 0x51, ast.Mult: 0x52, ast.FloorDiv: 0x53, ast.Mod: 0x54}
+COMPARE = {ast.Eq: 0x0a, ast.NotEq: 0x0b, ast.Gt: 0x0c, ast.GtE: 0x0d, ast.Lt: 0x0e, ast.LtE: 0x0f}
+
+
+def parse(expression):
+    if not isinstance(expression, str) or len(expression) > 2000:
+        raise ProjectError('Expression must be at most 2000 characters')
+    try:
+        tree = ast.parse(expression or '0', mode='eval').body
+    except (SyntaxError, RecursionError) as error:
+        raise ProjectError(f'Invalid numeric expression: {expression}') from error
+    if sum(1 for _ in ast.walk(tree)) > 256:
+        raise ProjectError('Expression is too complex')
+    names = set()
+    def check(node):
+        if isinstance(node, ast.Constant) and type(node.value) in (int, bool):
+            if not -32768 <= node.value <= 32767:
+                raise ProjectError('Expression constants must fit a signed 16-bit word')
+        elif isinstance(node, ast.Name):
+            names.add(node.id)
+        elif isinstance(node, ast.BinOp) and type(node.op) in BINARY:
+            check(node.left); check(node.right)
+            if isinstance(node.op, (ast.FloorDiv, ast.Mod)) and isinstance(node.right, ast.Constant) and node.right.value == 0:
+                raise ProjectError('Division by zero in expression')
+        elif isinstance(node, ast.UnaryOp) and isinstance(node.op, (ast.USub, ast.Not, ast.UAdd)):
+            # -32768 is represented as unary minus over the positive literal.
+            if isinstance(node.op, ast.USub) and isinstance(node.operand, ast.Constant) and node.operand.value == 32768:
+                return
+            check(node.operand)
+        elif isinstance(node, ast.BoolOp) and isinstance(node.op, (ast.And, ast.Or)):
+            for value in node.values: check(value)
+        elif isinstance(node, ast.Compare) and all(type(op) in COMPARE for op in node.ops):
+            for value in (node.left, *node.comparators): check(value)
+        else:
+            raise ProjectError('Use integers, variables, arithmetic, comparisons, and/or/not only')
+    check(tree)
+    return tree, names
+
+
+def emit(asm, tree, read_variable):
+    if isinstance(tree, ast.Constant):
+        asm.emit(0x1a, int(tree.value))
+    elif isinstance(tree, ast.Name):
+        read_variable(tree.id)
+    elif isinstance(tree, ast.UnaryOp):
+        if isinstance(tree.op, ast.USub):
+            asm.emit(0x1a, 0)
+            emit(asm, tree.operand, read_variable)
+            asm.emit(0x51)
+        else:
+            emit(asm, tree.operand, read_variable)
+            if isinstance(tree.op, ast.Not):
+                asm.emit(0x1a, 0); asm.emit(0x0a)
+    elif isinstance(tree, ast.BinOp):
+        emit(asm, tree.left, read_variable); emit(asm, tree.right, read_variable)
+        asm.emit(BINARY[type(tree.op)])
+    elif isinstance(tree, ast.BoolOp):
+        stop, end = ('boolean', len(asm.code), 0), ('boolean', len(asm.code), 1)
+        conjunction = isinstance(tree.op, ast.And)
+        for value in tree.values:
+            emit(asm, value, read_variable)
+            if conjunction:
+                asm.emit(0x1a, 0); asm.emit(0x0a)
+            asm.jump_if(stop)
+        asm.emit(0x1a, int(conjunction)); asm.jump(end)
+        asm.labels[stop] = len(asm.code)
+        asm.emit(0x1a, int(not conjunction))
+        asm.labels[end] = len(asm.code)
+    elif isinstance(tree, ast.Compare):
+        for i, (left, op, right) in enumerate(zip((tree.left, *tree.comparators), tree.ops, tree.comparators)):
+            emit(asm, left, read_variable); emit(asm, right, read_variable)
+            asm.emit(COMPARE[type(op)])
+            if i: asm.emit(0x12)

exp_runtime/creator/features.py

@@ -0,0 +1,90 @@
+"""Authoring controls backed by the recovered KiWi host contracts.
+
+Defaults are authored examples, not extracted game content. They are shared
+by the editor and the API; validation never fills in an unknown native call.
+"""
+from copy import deepcopy
+
+NAMES = dict(dialogue='Dialogue', choice='Choice', background='Background', set='Set variable',
+             branch='Condition', music='Music', sound='Sound effect', stop_audio='Stop audio',
+             relationship='Relationship', score='Score / property', input='Text input',
+             text_branch='Text answer condition', title='Title card', message='Message',
+             notice='Dialogue notification', emphasis='Emphasize dialogue', scene_label='Scene label',
+             pan='Background pan', transition='Screen transition', close_dialogue='Close dialogue',
+             random='Random variable', word_game='Timed word choices', football='Football (SHS)',
+             grid='Word / picture grid (SHS)', scene='Scene link',
+             end='End episode', native='Native bytecode block')
+
+DEFAULTS = {
+    'dialogue': {}, 'choice': {'shuffle': False}, 'background': {'variant': 0},
+    'set': {'expression': ''}, 'branch': {'expression': ''},
+    'music': {'resource': 8201, 'loop': True}, 'sound': {'resource': 8001},
+    'stop_audio': {'channel': 0},
+    'relationship': {'operation': 'add', 'value': 1, 'romantic': False, 'hide': False, 'result': 'relationship'},
+    'score': {'owner': 0, 'key': 400, 'operation': 'add', 'value': 1, 'notification': '', 'result': 'score'},
+    'input': {'prompt': 'Enter an answer.', 'default': '', 'result': 'answer'},
+    'text_branch': {'variable': 'answer', 'equals': 'Answer'},
+    'title': {'subtitle': '', 'background': -1, 'flag': 0},
+    'message': {'title': '', 'flag': 0}, 'notice': {}, 'emphasis': {},
+    'scene_label': {'icon': -1}, 'pan': {'automatic': True, 'alignment': 2},
+    'transition': {'selector': 0}, 'close_dialogue': {},
+    'random': {'bound': 2, 'result': 'roll'},
+    'word_game': {'good': ['Clear', 'Calm'], 'bad': ['Late', 'Lost', 'Loud'],
+                  'duration_ms': 10000, 'refresh_ms': 1000, 'result': 'word_score'},
+    'football': {'first_seconds': 30, 'second_seconds': 30,
+                 'plans': [[[1, 5, 2, 1]], [[-1, 5, 2, 1]]] * 3,
+                 'instructions': ['Choose a play.'] * 6, 'start_offense': True,
+                 'home_team': 1, 'away_team': 2, 'home_position': 20, 'away_position': 20,
+                 'home_score': 0, 'away_score': 0, 'allow_block': False,
+                 'pass_bonus': False, 'run_bonus': False, 'coach': False,
+                 'extra_offense': '', 'extra_defense': '', 'result': 'football_margin'},
+    'grid': {'seconds': 30, 'target': 1, 'round_ms': 10000, 'bonus_ms': 1000,
+             'background': -1, 'variant': 0, 'left_character': '', 'right_character': '',
+             'left_expression': 0, 'right_expression': 0, 'shuffle': False,
+             'feedback': True, 'success': 'Well done!', 'failure': 'Try again.',
+             'problems': [{'width': 3, 'height': 3, 'heading': 'Find a word',
+                           'prompt': 'Connect adjacent letters.', 'words': ['CAT'],
+                           'alphabet': 'CAT', 'highlight': True, 'advance_after_one': True,
+                           'minimum_starts': 1, 'id': 1001}],
+             'symbols': [], 'tutorials': [], 'result': 'grid_passed'},
+    'scene': {},
+    'end': {}, 'native': {},
+}
+INPUT_GATES = frozenset(('dialogue', 'choice', 'input', 'title', 'message', 'word_game', 'football', 'grid'))
+
+
+def parameters(node):
+    return dict(deepcopy(DEFAULTS[node.kind]), **node.params)
+
+
+def text_fields(project):
+    """Stable translation keys, including structured minigame text."""
+    result = {'title': project.title}
+    if project.native: return result
+    for character in project.characters:
+        result[f'character.{character.id}.name'] = character.name
+    for node in project.nodes:
+        for field in ('text', 'speaker'):
+            result[f'node.{node.id}.{field}'] = getattr(node, field)
+        for i, option in enumerate(node.options):
+            result[f'node.{node.id}.option.{i}'] = option.text
+        p = parameters(node)
+        for field in ('prompt', 'default', 'equals', 'subtitle', 'title', 'notification', 'success', 'failure',
+                      'extra_offense', 'extra_defense'):
+            if field in p:
+                result[f'node.{node.id}.param.{field}'] = p[field]
+        for field in ('good', 'bad', 'instructions'):
+            for i, value in enumerate(p.get(field, [])):
+                result[f'node.{node.id}.param.{field}.{i}'] = value
+        for field in ('problems', 'tutorials'):
+            for i, record in enumerate(p.get(field, [])):
+                for key in ('title', 'body', 'heading', 'prompt', 'alphabet', 'fixed_board'):
+                    if key in record:
+                        result[f'node.{node.id}.param.{field}.{i}.{key}'] = record[key]
+                for j, word in enumerate(record.get('words', [])):
+                    result[f'node.{node.id}.param.{field}.{i}.words.{j}'] = word
+    return result
+
+
+def translated(project, key, fallback):
+    return project.locales.get(project.language, {}).get(key, fallback)

exp_runtime/creator/graph.py

@@ -0,0 +1,124 @@
+"""Bounded story queries and reference-aware edits, independent of MCP and Qt."""
+from collections import Counter, deque
+from dataclasses import asdict
+
+from .model import ProjectError
+
+
+def page(offset, limit):
+    if type(offset) is not int or offset < 0 or type(limit) is not int or not 1 <= limit <= 200:
+        raise ProjectError('Use a nonnegative offset and limit from 1 to 200')
+
+
+def edges(project):
+    result = []
+    for node in project.nodes:
+        for index, (label, target) in enumerate(node.links()):
+            field = (f'options.{index}.target' if node.kind == 'choice' else
+                     'otherwise' if node.kind in ('branch', 'text_branch') and index else 'next')
+            if node.kind == 'native': field = 'params.instructions'
+            result.append(dict(source=node.id, target=target, label=label, field=field))
+    return result
+
+
+def overview(project):
+    return dict(title=project.title, game=project.game, start=project.start, native=bool(project.native),
+                node_count=len(project.nodes), kinds=dict(Counter(n.kind for n in project.nodes)),
+                scenes=dict(Counter(n.scene for n in project.nodes)),
+                characters=[dict(id=c.id, name=c.name) for c in project.characters],
+                asset_count=len(project.assets), language=project.language,
+                languages=sorted({project.language, *project.locales}),
+                endings=[n.id for n in project.nodes if n.kind == 'end'])
+
+
+def search(project, *, text='', character=None, kind=None, scene=None, offset=0, limit=50):
+    page(offset, limit)
+    found = []
+    needle = text.casefold()
+    for node in project.nodes:
+        if character is not None and character not in (node.character, node.params.get('left_character'),
+                                                       node.params.get('right_character')): continue
+        if kind is not None and node.kind != kind: continue
+        if scene is not None and node.scene != scene: continue
+        if needle and needle not in str(asdict(node)).casefold(): continue
+        found.append(node)
+    return dict(total=len(found), nodes=[asdict(n) for n in found[offset:offset + limit]],
+                next_offset=offset + limit if offset + limit < len(found) else None)
+
+
+def subgraph(project, node_id, *, depth=1, direction='both', limit=100):
+    page(0, limit)
+    if type(depth) is not int or not 0 <= depth <= 20 or direction not in ('both', 'incoming', 'outgoing'):
+        raise ProjectError('Use depth 0–20 and direction incoming, outgoing or both')
+    nodes = {n.id: n for n in project.nodes}
+    if node_id not in nodes: raise ProjectError('Unknown node')
+    links = edges(project)
+    adjacent = {key: [] for key in nodes}
+    for edge in links:
+        a, b = edge['source'], edge['target']
+        if b not in nodes: continue
+        if direction != 'incoming': adjacent[a].append(b)
+        if direction != 'outgoing': adjacent[b].append(a)
+    queue, visited, selected = deque([(node_id, 0)]), {node_id}, []
+    while queue and len(selected) < limit:
+        key, level = queue.popleft(); selected.append(key)
+        if level < depth:
+            for target in adjacent[key]:
+                if target not in visited:
+                    visited.add(target); queue.append((target, level + 1))
+    included = set(selected)
+    return dict(nodes=[asdict(nodes[key]) for key in selected], truncated=bool(queue),
+                edges=[e for e in links if e['source'] in included and e['target'] in included],
+                boundary=[e for e in links if (e['source'] in included) != (e['target'] in included)])
+
+
+def paths(project, target, *, source=None, limit=20, max_depth=100, budget=10000):
+    """Enumerate bounded simple structural paths, not claims of runtime reachability."""
+    page(0, limit)
+    if type(max_depth) is not int or not 1 <= max_depth <= 500:
+        raise ProjectError('Path depth must be 1–500')
+    nodes = {n.id: n for n in project.nodes}
+    source = source or project.start
+    if source not in nodes or target not in nodes: raise ProjectError('Unknown source or target node')
+    stack, found, examined, truncated = [(source,)], [], 0, False
+    while stack and len(found) < limit and examined < budget:
+        route = stack.pop(); examined += 1
+        if route[-1] == target:
+            found.append(list(route)); continue
+        if len(route) >= max_depth:
+            truncated |= any(t in nodes and t not in route for _, t in nodes[route[-1]].links())
+            continue
+        for _, next_id in reversed(nodes[route[-1]].links()):
+            if next_id in nodes and next_id not in route: stack.append((*route, next_id))
+    return dict(paths=found, truncated=bool(stack) or truncated, examined=examined,
+                semantics='Simple structural paths. Conditions, timers and native indirect jumps require playtesting.')
+
+
+def rename_node(project, old, new):
+    if project.native: raise ProjectError('Native blocks retain fixed addresses and identities')
+    if not new or any(n.id == new for n in project.nodes): raise ProjectError('Choose a new, nonempty node ID')
+    node = next((n for n in project.nodes if n.id == old), None)
+    if node is None: raise ProjectError('Unknown node')
+    node.id = new
+    if project.start == old: project.start = new
+    for n in project.nodes:
+        if n.next == old: n.next = new
+        if n.otherwise == old: n.otherwise = new
+        for option in n.options:
+            if option.target == old: option.target = new
+    prefix = f'node.{old}.'
+    for language, translations in project.locales.items():
+        project.locales[language] = {(f'node.{new}.' + key[len(prefix):] if key.startswith(prefix) else key): value
+                                    for key, value in translations.items()}
+
+
+def connect(project, source, target, field='next'):
+    if project.native: raise ProjectError('Edit native control flow through its instructions')
+    node = next((n for n in project.nodes if n.id == source), None)
+    if node is None: raise ProjectError('Unknown source node')
+    if field not in {e['field'] for e in edges(project) if e['source'] == source}:
+        raise ProjectError('Choose an existing edge field: next, otherwise or options.N.target')
+    if field.startswith('options.'):
+        node.options[int(field.split('.')[1])].target = target
+    else:
+        setattr(node, field, target)