reverseport 0.0.0-stage → 1.2.0

package/port/src/blueprint.mjs

@@ -0,0 +1,225 @@
+// Rebuild blueprint: turns what is known about an existing game or app (a re_lookup dossier and/or genres, tags and a
+// description) into a precise, clean-room rebuild spec: the systems it is made of, the parameters to measure on the
+// original so the rebuild matches it in function and feel, a target engine with its conventions, milestones, a
+// parity table to fill and verify, and a project skeleton with every measured parameter as a tunable.
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { RPError, writeJson, pascalCase, camelCase, snakeCase, kebabCase, statOrNull } from './util.mjs';
+import { workspaceDir, isInside } from './workspace.mjs';
+import { ENGINES, normEngine } from './knowledge.mjs';
+import { scaffold } from './porters.mjs';
+import { loadLookup, footprintFor, FOOTPRINTS } from './lookup.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+export const KNOWLEDGE = JSON.parse(fs.readFileSync(path.join(ROOT, 'knowledge', 'systems.json'), 'utf8'));
+const ENGINE_TARGETS = ['godot', 'godot-csharp', 'unity', 'unreal', 'threejs'];
+const APP_TARGETS = { web: 'Web app (TypeScript + a UI framework)', flutter: 'Flutter (Dart, iOS + Android + web)', 'react-native': 'React Native (TypeScript, iOS + Android)', swift: 'Swift / SwiftUI (iOS)', kotlin: 'Kotlin / Jetpack Compose (Android)', electron: 'Electron (desktop, TypeScript)' };
+const NON_NUMERIC = new Set(['list', 'table', 'notes', 'graph', 'formula', 'samples', 'hex', 'fields', 'curve', 'ms, curve', 'px, s']);
+
+const esc = s => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const wordRe = k => new RegExp(`(^|[^a-z0-9])${esc(k)}(s|es)?([^a-z0-9]|$)`, 'i');
+
+/** Score archetypes against genres/tags (strong) and free text (weak). */
+export function matchArchetypes({ genres = [], tags = [], text = '', kind = null, force = [] } = {}) {
+  const strong = [...genres, ...tags].map(s => String(s).toLowerCase());
+  const weak = String(text).toLowerCase();
+  const out = [];
+  for (const a of KNOWLEDGE.archetypes) {
+    if (kind && a.kind !== kind && !force.includes(a.id)) continue;
+    const hits = [];
+    let score = 0;
+    for (const k of a.match) {
+      const re = wordRe(k);
+      const g = strong.find(s => re.test(s));
+      if (g) { score += 2; hits.push(`genre/tag "${g}"`); } else if (re.test(weak)) { score += 1; hits.push(`description mentions "${k}"`); }
+    }
+    if (force.includes(a.id)) { score += 10; hits.unshift('requested'); }
+    if (score) out.push({ id: a.id, name: a.name, kind: a.kind, score, why: [...new Set(hits)].slice(0, 4) });
+  }
+  out.sort((a, b) => b.score - a.score);
+  const picked = out.filter(a => a.score >= 2);
+  return picked.length ? picked.slice(0, 5) : out.slice(0, 2);
+}
+
+function perspectiveOf(values = [], engineFp) {
+  const v = values.map(s => String(s).toLowerCase()).join(' ');
+  if (/first-person|third-person|free-roaming|\b3d\b|behind view|vr\b/.test(v)) return '3d';
+  if (/side view|side-scroll|scrolling|flip screen|text-based|\b2d\b|pixel/.test(v)) return '2d';
+  if (/isometric|top-down|bird/.test(v)) return engineFp === 'gamemaker' || engineFp === 'rpgmaker' ? '2d' : 'unknown (isometric/top-down: check whether the world is 2D sprites or 3D)';
+  return 'unknown';
+}
+
+function platformFeatures(categories = [], features = []) {
+  const c = [...categories, ...features].map(s => String(s).toLowerCase());
+  const add = [];
+  const has = re => c.some(s => re.test(s));
+  if (has(/achievement/)) add.push({ id: 'achievements', name: 'Achievements', build: 'Achievement list with unlock conditions (write your own names/descriptions).', measure: [{ param: 'achievements', unit: 'list', how: 'public achievement list: conditions and counts' }] });
+  if (has(/controller support/)) add.push({ id: 'gamepad', name: 'Full controller support', build: 'Every screen navigable with a gamepad; button prompts swap with the active device.', measure: [{ param: 'button_layout', unit: 'table', how: 'action per button' }] });
+  if (has(/cloud/)) add.push({ id: 'cloud-save', name: 'Cloud saves', build: 'Save files small and versioned so they sync (platform cloud API).', measure: [] });
+  if (has(/workshop|level editor|mod/)) add.push({ id: 'ugc', name: 'User content / modding', build: 'Level/mod format, editor, sharing.', measure: [{ param: 'ugc_scope', unit: 'notes', how: 'what players can create and share' }] });
+  if (has(/in-app purchase|microtransaction/)) add.push({ id: 'store', name: 'In-app store', build: 'Store screens, currencies, purchase flow (platform billing).', measure: [{ param: 'store_items', unit: 'table', how: 'items, prices, currencies' }] });
+  if (has(/leaderboard/)) add.push({ id: 'leaderboards', name: 'Leaderboards', build: 'Score submission and boards.', measure: [{ param: 'boards', unit: 'list', how: 'which boards exist and their sort' }] });
+  return add;
+}
+
+function chooseTarget({ target, kind, originalFp, perspective, platforms = [], web }) {
+  if (target) {
+    const t = normEngine(target);
+    if (ENGINE_TARGETS.includes(t)) return { target: t, name: ENGINES[t]?.name ?? t, engine: true, why: 'requested' };
+    if (APP_TARGETS[t]) return { target: t, name: APP_TARGETS[t], engine: false, why: 'requested' };
+    return { target: t, name: t, engine: false, why: 'requested (language/framework: no project skeleton is generated)' };
+  }
+  if (kind === 'app') {
+    const p = platforms.map(s => String(s).toLowerCase()).join(' ');
+    if (web || (!/ios|android|iphone|ipad/.test(p) && /web|browser/.test(p))) return { target: 'web', name: APP_TARGETS.web, engine: false, why: 'the original is a web app' };
+    if (/ios|iphone|ipad/.test(p) && /android/.test(p)) return { target: 'flutter', name: APP_TARGETS.flutter, engine: false, why: 'the original ships on iOS and Android: one codebase for both' };
+    if (originalFp === 'flutter' || originalFp === 'react-native' || originalFp === 'electron') return { target: originalFp, name: APP_TARGETS[originalFp], engine: false, why: 'same framework as the original: same widgets, scrolling physics and transitions' };
+    return { target: 'flutter', name: APP_TARGETS.flutter, engine: false, why: 'cross-platform default for app rebuilds' };
+  }
+  const fp = originalFp ? FOOTPRINTS[originalFp] : null;
+  if (fp && ENGINE_TARGETS.includes(fp.rebuildTarget)) return { target: fp.rebuildTarget, name: ENGINES[fp.rebuildTarget].name, engine: true, why: `the original runs on ${fp.name}: the same engine gives the same physics tick, camera conventions and rendering defaults, so measured values carry over 1:1` };
+  if (web) return { target: 'threejs', name: ENGINES.threejs.name, engine: true, why: 'the original is a browser game' };
+  if (/^2d/.test(perspective)) return { target: 'godot', name: ENGINES.godot.name, engine: true, why: '2D game: Godot has pixel-exact 2D, tilemaps and a light runtime' };
+  return { target: 'godot', name: ENGINES.godot.name, engine: true, why: 'default: free, light, good 2D and 3D; choose unity or unreal with target if the original is high-end 3D' };
+}
+
+const ident = p => { const s = snakeCase(p); return /^\d/.test(s) ? `p_${s}` : s; };
+const isNum = m => !NON_NUMERIC.has(m.unit);
+
+function stubFiles(target, systems, name) {
+  const files = {};
+  for (const s of systems) {
+    const nums = s.measure.filter(isNum), other = s.measure.filter(m => !isNum(m));
+    const header = (c) => [`${c} ${s.name} — rebuild of the original's behaviour with your own code and assets.`, `${c} ${s.build}`, `${c} Values come from parity.json (measured on the original); 0 means not measured yet.`, ...other.map(m => `${c} TODO(measure) ${m.param} [${m.unit}]: ${m.how}`)].join('\n');
+    const C = `${pascalCase(s.id)}System`;
+    if (target === 'godot') {
+      files[`systems/${snakeCase(s.id)}.gd`] = `${header('##')}\nextends Node\n\n${nums.map(m => `## ${m.how}\n@export var ${ident(m.param)}: float = 0.0 # ${m.unit}`).join('\n')}\n\nfunc _ready() -> void:\n\tpass\n\nfunc _physics_process(delta: float) -> void:\n\tpass\n`;
+    } else if (target === 'godot-csharp') {
+      files[`Systems/${C}.cs`] = `${header('//')}\nusing Godot;\n\npublic partial class ${C} : Node\n{\n${nums.map(m => `\t/// <summary>${m.how} (${m.unit})</summary>\n\t[Export] public float ${pascalCase(ident(m.param))} { get; set; } = 0f;`).join('\n')}\n\n\tpublic override void _PhysicsProcess(double delta) { }\n}\n`;
+    } else if (target === 'unity') {
+      files[`Assets/Scripts/Systems/${C}.cs`] = `${header('//')}\nusing UnityEngine;\n\npublic class ${C} : MonoBehaviour\n{\n${nums.map(m => `    [Tooltip("${m.how.replace(/"/g, "'")} (${m.unit})")]\n    [SerializeField] float ${camelCase(ident(m.param))} = 0f;`).join('\n')}\n\n    void FixedUpdate() { }\n}\n`;
+    } else if (target === 'threejs') {
+      files[`src/systems/${kebabCase(s.id)}.ts`] = `${header('//')}\nexport const ${camelCase(s.id)}Params = {\n${nums.map(m => `  /** ${m.how} (${m.unit}) */\n  ${camelCase(ident(m.param))}: 0,`).join('\n')}\n};\n\nexport class ${C} {\n  constructor(readonly params = { ...${camelCase(s.id)}Params }) {}\n  fixedUpdate(_dt: number): void {}\n}\n`;
+    } else if (target === 'unreal') {
+      const P = pascalCase(name);
+      files[`Source/${P}/Systems/${C}Component.h`] = `${header('//')}\n#pragma once\n#include "CoreMinimal.h"\n#include "Components/ActorComponent.h"\n#include "${C}Component.generated.h"\n\nUCLASS(ClassGroup=(Rebuild), meta=(BlueprintSpawnableComponent))\nclass U${C}Component : public UActorComponent\n{\n\tGENERATED_BODY()\npublic:\n${nums.map(m => `\t/** ${m.how} (${m.unit}; Unreal uses cm) */\n\tUPROPERTY(EditAnywhere, Category="Measured") float ${pascalCase(ident(m.param))} = 0.f;`).join('\n')}\n};\n`;
+    }
+  }
+  return files;
+}
+
+function markdown(bp) {
+  const L = [];
+  L.push(`# Rebuild blueprint — ${bp.name}`, '', `Working title: **${bp.workingTitle}** — pick your own product name, logo and art before anything is published.`, '');
+  L.push('## What it is', '', `- Kind: ${bp.kind}; perspective: ${bp.perspective}`, `- Archetypes: ${bp.archetypes.map(a => `${a.name} (${a.why.join(', ')})`).join('; ') || 'none matched — add genres/tags or archetypes'}`);
+  if (bp.original.engine) L.push(`- Original engine: ${bp.original.engine}${bp.original.version ? ` ${bp.original.version}` : ''} (${bp.original.confidence ?? 'given'})`);
+  if (bp.original.conventions) L.push(`- Original conventions: ${bp.original.conventions}`);
+  L.push(`- Target: **${bp.target.name}** — ${bp.target.why}`);
+  if (bp.target.conventions) L.push(`- Target conventions: ${bp.target.conventions}`);
+  if (bp.target.note) L.push(`- ${bp.target.note}`);
+  L.push('', '## Clean-room rules', '', `- Rebuild freely: ${KNOWLEDGE.cleanRoom.free.join('; ')}.`, `- Make your own: ${KNOWLEDGE.cleanRoom.own.join('; ')}.`, `- Never: ${KNOWLEDGE.cleanRoom.never.join('; ')}.`, '');
+  L.push('## Capture the original', '', ...KNOWLEDGE.method.capture.map(s => `- ${s}`), '', '### How to measure', '', ...KNOWLEDGE.method.measure.map(s => `- ${s}`), '');
+  if (bp.references.length) L.push('### Public references', '', ...bp.references.map(r => `- ${r}`), '');
+  L.push('## Systems', '');
+  for (const s of bp.systems) {
+    L.push(`### ${s.name}`, '', s.build, '', '| Parameter | Unit | How to measure | Value | ± |', '| --- | --- | --- | --- | --- |');
+    for (const m of s.measure) L.push(`| \`${m.param}\` | ${m.unit} | ${m.how} | | ${isNum(m) ? '5%' : '—'} |`);
+    L.push('');
+  }
+  L.push('## Milestones', '', ...bp.milestones.map((m, i) => `${i}. **${m.name}** — ${m.done}`), '');
+  L.push('## Verify', '', ...KNOWLEDGE.method.verify.map(s => `- ${s}`), '', '`parity.json` holds every parameter: fill `original` from your measurements, `rebuild` from the same measurement on your build; a parameter passes inside its tolerance.', '');
+  if (bp.openSource.length) L.push('## Existing open-source work', '', ...bp.openSource.map(o => `- [${o.repo}](${o.url}) — ${o.kind}${o.license ? `, ${o.license}` : ', no license given'}: ${o.description}`), '', 'Check each license before reusing any of it; "no license" means all rights reserved.', '');
+  return `${L.join('\n')}\n`;
+}
+
+export async function blueprintTool({ lookupId, name, kind, genres = [], tags = [], description = '', engine, target, perspective, archetypes = [], output, scaffold: wantScaffold = true } = {}) {
+  const d = lookupId ? await loadLookup(lookupId) : null;
+  const title = name ?? d?.name;
+  if (!title) throw new RPError('INVALID_ARGUMENT', 'Give a name (or a lookupId from re_lookup).');
+  const theKind = kind ?? (d?.kind === 'app' || d?.kind === 'web' && !(d?.tech?.web?.stack ?? []).some(s => s.group === 'engine') ? 'app' : 'game');
+  for (const a of archetypes) if (!KNOWLEDGE.archetypes.some(x => x.id === a)) throw new RPError('INVALID_ARGUMENT', `Unknown archetype ${a}. Archetypes: ${KNOWLEDGE.archetypes.map(x => x.id).join(', ')}.`);
+  const allGenres = [...genres, ...(d?.identity?.genres ?? []), ...(d?.identity?.modes ?? [])];
+  const allTags = [...tags, ...(d?.identity?.categories ?? [])];
+  const text = [description, d?.identity?.description, title].filter(Boolean).join(' ');
+  const matched = matchArchetypes({ genres: allGenres, tags: allTags, text, kind: theKind, force: archetypes });
+  const origEngine = engine ? { name: engine, confidence: 'given' } : d?.tech?.engines?.[0] ?? null;
+  const originalFp = origEngine ? footprintFor(origEngine.name) : (d?.tech?.web ? 'web' : null);
+  const persp = perspective ?? perspectiveOf([...allGenres, ...allTags, ...(d ? Object.values(d.identity ?? {}).flat().filter(x => typeof x === 'string') : [])], originalFp);
+  const web = !!d?.tech?.web;
+  const tgt = chooseTarget({ target, kind: theKind, originalFp, perspective: persp, platforms: d?.identity?.platforms ?? [], web });
+  const origKey = originalFp && FOOTPRINTS[originalFp]?.engineId;
+  const conv = k => { const e = ENGINES[k]; return e ? `${e.axes.up} up, ${e.axes.forward} forward, ${e.handedness}-handed, ${e.units}, physics ${e.physicsTick}, FOV ${e.fov}` : null; };
+  if (tgt.engine) {
+    tgt.conventions = conv(tgt.target);
+    if (origKey && origKey !== tgt.target && ENGINES[origKey]) tgt.note = `Original (${ENGINES[origKey].name}) and target differ: convert every measured position/rotation/FOV with port_convert {from:"${origKey}", to:"${tgt.target}"}; physics ${ENGINES[origKey].physicsTick} vs ${ENGINES[tgt.target].physicsTick}.`;
+  }
+
+  const core = KNOWLEDGE.core[theKind] ?? KNOWLEDGE.core.game;
+  const fromArch = matched.flatMap(m => KNOWLEDGE.archetypes.find(a => a.id === m.id).systems.map(s => ({ ...s, archetype: m.id })));
+  const extra = platformFeatures(d?.identity?.categories ?? allTags, d?.tech?.app ? d?.identity?.categories ?? [] : []);
+  const seen = new Set();
+  const systems = [...fromArch, ...core.map(s => ({ ...s, archetype: 'core' })), ...extra.map(s => ({ ...s, archetype: 'platform' }))].filter(s => !seen.has(s.id) && seen.add(s.id));
+
+  const slug = kebabCase(title).slice(0, 40) || 'rebuild';
+  const workingTitle = `${title.replace(/[™®©]/g, '').trim()} Rebuild`;
+  const milestones = [
+    { name: 'Reference capture', done: 'recordings and screenshots of the original exist; the feel parameters of the first two systems are measured in parity.json' },
+    { name: 'Graybox vertical slice', done: `${systems[0]?.name ?? 'the core system'}, camera and input work in one level/screen with placeholder shapes, and their parameters pass parity` },
+    { name: 'All systems', done: 'every system in this blueprint works with placeholder content; every numeric parameter is filled' },
+    { name: 'Own content', done: 'own art, audio, text and levels/screens replace the placeholders (nothing taken from the original)' },
+    { name: 'UI and feedback parity', done: 'every screen matches the layout fractions; sounds fire on the same events' },
+    { name: 'Side-by-side verification', done: 'all parity.json parameters within tolerance; blind test remarks resolved' },
+  ];
+  const references = [...(d?.references?.pages ?? []).map(p => `${p.title}: ${p.url}`), ...(d?.references?.videos ?? []).slice(0, 4).map(v => `Video: ${v}`), ...(d?.references?.screenshots ?? []).slice(0, 6).map(s => `Screenshot: ${s}`)];
+  const openSource = (d?.openSource ?? []).filter(o => o.kind !== 'related').slice(0, 8);
+  const bp = {
+    name: title, workingTitle, kind: theKind, perspective: persp, lookupId: lookupId ?? null,
+    archetypes: matched, original: { engine: origEngine?.name ?? null, version: origEngine?.version ?? null, confidence: origEngine?.confidence ?? null, footprint: originalFp, conventions: origKey ? conv(origKey) : null },
+    target: tgt, systems: systems.map(({ id, name: n, build, measure, archetype }) => ({ id, name: n, archetype, build, measure })),
+    milestones, references, openSource, cleanRoom: KNOWLEDGE.cleanRoom, method: KNOWLEDGE.method,
+  };
+
+  // Files: BLUEPRINT.md, parity.json and (for engine targets) a project skeleton with every parameter as a tunable.
+  const dir = path.join(await workspaceDir('blueprints'), slug);
+  await fsp.mkdir(dir, { recursive: true });
+  const parity = { name: title, target: tgt.target, tolerance: { default: '5%', frames: 1 }, parameters: bp.systems.flatMap(s => s.measure.map(m => ({ system: s.id, param: m.param, unit: m.unit, how: m.how, numeric: isNum(m), original: null, rebuild: null, tolerance: isNum(m) ? '5%' : null, status: 'todo' }))) };
+  await fsp.writeFile(path.join(dir, 'BLUEPRINT.md'), markdown(bp));
+  await writeJson(path.join(dir, 'parity.json'), parity);
+  const written = ['BLUEPRINT.md', 'parity.json'].map(f => path.join(dir, f));
+  let projectDir = null;
+  if (wantScaffold && tgt.engine) {
+    const busy = async p => { const st = await statOrNull(p); return !!st && (!st.isDirectory() || (await fsp.readdir(p)).length > 0); };
+    if (output) {
+      projectDir = path.resolve(output);
+      if (await busy(projectDir)) throw new RPError('OUTPUT_NOT_EMPTY', `Output folder must be new or empty: ${projectDir}`);
+    } else {
+      projectDir = path.join(dir, `project-${tgt.target}`);
+      for (let n = 2; await busy(projectDir); n++) projectDir = path.join(dir, `project-${tgt.target}-${n}`);
+    }
+    const files = { ...scaffold(tgt.target, { name: workingTitle }), ...stubFiles(tgt.target, bp.systems, workingTitle) };
+    for (const [rel, content] of Object.entries(files)) {
+      const abs = path.resolve(projectDir, rel);
+      if (!isInside(abs, projectDir)) continue;
+      await fsp.mkdir(path.dirname(abs), { recursive: true });
+      await fsp.writeFile(abs, content);
+      written.push(abs);
+    }
+    await fsp.copyFile(path.join(dir, 'BLUEPRINT.md'), path.join(projectDir, 'BLUEPRINT.md'));
+    await fsp.copyFile(path.join(dir, 'parity.json'), path.join(projectDir, 'parity.json'));
+  }
+  return {
+    ...bp, method: undefined, cleanRoom: { never: KNOWLEDGE.cleanRoom.never, note: KNOWLEDGE.cleanRoom.note },
+    parameters: parity.parameters.length, files: { blueprint: path.join(dir, 'BLUEPRINT.md'), parity: path.join(dir, 'parity.json'), project: projectDir, written: written.length },
+    next: [
+      'Capture the original (BLUEPRINT.md → Capture) and fill parity.json "original" values',
+      projectDir ? `Open ${projectDir} in ${tgt.name}; the systems/ stubs hold every numeric parameter as a tunable` : `Set up a ${tgt.name} project; mirror the systems list as modules`,
+      ...(openSource.length ? ['Open-source work exists (openSource): check licenses; re_lookup {github, mirror:true} + port_plan if you may reuse it'] : []),
+      ...(tgt.note ? ['port_convert for every measured transform/FOV (engines differ)'] : []),
+      'Measure the rebuild the same way, fill "rebuild", and keep going until every parameter is within tolerance',
+    ],
+  };
+}
+
+export const ARCHETYPE_IDS = KNOWLEDGE.archetypes.map(a => a.id);

package/port/src/compare.mjs

@@ -0,0 +1,165 @@
+// Diffs (two builds, two versions of a project, two packs or binaries), raw probing of unknown data
+// (hex view, entropy map, embedded files, record strides), carving, and the architecture report.
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { createReadStream, createWriteStream } from 'node:fs';
+import { pipeline } from 'node:stream/promises';
+import crypto from 'node:crypto';
+import { RPError, readAt, requireFile, statOrNull, walk, MiB, sha256File, limit, pascalCase } from './util.mjs';
+import { identify, findSignatures, entropyProfile, strideGuess } from './formats.mjs';
+import { inspectBinary } from './binary.mjs';
+import { openArchive } from './archive.mjs';
+import { workspaceDir } from './workspace.mjs';
+import { scanProject } from './scan.mjs';
+import { buildGraph, graphMermaid } from './graph.mjs';
+import { readScene } from './scene.mjs';
+
+export function hexdump(buf, base = 0) {
+  const lines = [];
+  for (let i = 0; i < buf.length; i += 16) {
+    const row = buf.subarray(i, i + 16);
+    const hex = [...row].map(b => b.toString(16).padStart(2, '0')).join(' ').padEnd(47);
+    const ascii = [...row].map(b => (b >= 0x20 && b < 0x7f ? String.fromCharCode(b) : '.')).join('');
+    lines.push(`${(base + i).toString(16).padStart(8, '0')}  ${hex}  ${ascii}`);
+  }
+  return lines.join('\n');
+}
+
+export async function probe({ file, offset = 0, length = 256, maxMB = 512 } = {}) {
+  const { abs, size } = await requireFile(file);
+  if (offset < 0 || offset >= Math.max(size, 1)) throw new RPError('INVALID_ARGUMENT', `offset must be within the file (0…${size - 1}).`);
+  const head = await readAt(abs, offset, 4096);
+  const view = head.subarray(0, Math.max(16, Math.min(length, 4096)));
+  const strideBuf = await readAt(abs, offset, 65536);
+  const span = Math.min(maxMB, 64 * 1024) * MiB;
+  return {
+    file: abs, size, offset, identified: identify(head),
+    hex: hexdump(view, offset),
+    entropy: await entropyProfile(abs, { start: offset, maxBytes: span }),
+    embedded: await findSignatures(abs, { start: offset, maxBytes: span, max: 150 }),
+    strides: strideGuess(strideBuf),
+    hint: 'embedded[] are candidate files inside this one (carve with re_extract); strides suggest fixed-size records (tables); entropy ≥ 7.5 means compressed or encrypted data.',
+  };
+}
+
+export async function carve({ file, offset, length, name } = {}) {
+  const { abs, size } = await requireFile(file);
+  if (!Number.isInteger(offset) || offset < 0 || offset >= size) throw new RPError('INVALID_ARGUMENT', 'offset must be an integer inside the file.');
+  let len = length;
+  let kind = identify(await readAt(abs, offset, 4096));
+  if (!len) {
+    const sig = (await findSignatures(abs, { start: offset, maxBytes: 64 * MiB, max: 5, includeStart: true })).hits.find(h => h.offset === offset);
+    if (sig?.size) len = sig.size;
+    else throw new RPError('INVALID_ARGUMENT', `Give length: the size of a ${kind.name} at this offset is not stored in its header.`);
+  }
+  len = Math.min(len, size - offset);
+  const ext = { png: 'png', jpeg: 'jpg', gif: 'gif', webp: 'webp', wav: 'wav', ogg: 'ogg', flac: 'flac', mp4: 'mp4', glb: 'glb', zip: 'zip', 'godot-pck': 'pck', pe: 'exe', elf: 'elf', dds: 'dds', fbx: 'fbx', sqlite: 'sqlite', pdf: 'pdf', otf: 'otf', woff: 'woff', woff2: 'woff2', midi: 'mid', 'godot-ctex': 'ctex', 'godot-resource': 'res', unityfs: 'bundle', wasm: 'wasm' }[kind.id] ?? 'bin';
+  const dir = await workspaceDir('extracted', 'carved');
+  const base = (name ? String(name).replace(/[^A-Za-z0-9._-]+/g, '_').slice(0, 80) : `${path.basename(abs).replace(/[^A-Za-z0-9._-]+/g, '_')}@${offset.toString(16)}`) + (name && path.extname(name) ? '' : `.${ext}`);
+  const dest = path.join(dir, base);
+  await pipeline(createReadStream(abs, { start: offset, end: offset + len - 1 }), createWriteStream(dest));
+  kind = identify(await readAt(dest, 0, 4096));
+  return { file: dest, bytes: len, identified: kind, from: { file: abs, offset } };
+}
+
+async function quickHash(file, size) {
+  if (size <= 64 * MiB) return sha256File(file);
+  const h = crypto.createHash('sha256');
+  h.update(await readAt(file, 0, MiB)); h.update(await readAt(file, Math.floor(size / 2), MiB)); h.update(await readAt(file, size - MiB, MiB));
+  return `sampled:${h.digest('hex')}`;
+}
+
+export async function compare({ a, b, limit: max = 300 } = {}) {
+  const sa = await statOrNull(path.resolve(a ?? '')), sb = await statOrNull(path.resolve(b ?? ''));
+  if (!sa || !sb) throw new RPError('NOT_FOUND', 'Both a and b must exist.');
+  const A = path.resolve(a), Bp = path.resolve(b);
+  const cap = Math.max(10, Math.min(5000, max));
+  if (sa.isDirectory() && sb.isDirectory()) {
+    const [wa, wb] = await Promise.all([walk(A, { maxFiles: 200000, ignore: new Set(['.git']) }), walk(Bp, { maxFiles: 200000, ignore: new Set(['.git']) })]);
+    const ma = new Map(wa.files.map(f => [f.rel, f])), mb = new Map(wb.files.map(f => [f.rel, f]));
+    const added = [], removed = [], changed = [];
+    for (const [rel, f] of mb) if (!ma.has(rel)) added.push({ file: rel, size: f.size });
+    for (const [rel, f] of ma) if (!mb.has(rel)) removed.push({ file: rel, size: f.size });
+    for (const [rel, fa] of ma) {
+      const fb = mb.get(rel);
+      if (!fb) continue;
+      if (fa.size !== fb.size) changed.push({ file: rel, sizeA: fa.size, sizeB: fb.size, delta: fb.size - fa.size });
+      else if (fa.size && (await quickHash(fa.abs, fa.size)) !== (await quickHash(fb.abs, fb.size))) changed.push({ file: rel, sizeA: fa.size, sizeB: fb.size, delta: 0 });
+    }
+    changed.sort((x, y) => Math.abs(y.delta) - Math.abs(x.delta));
+    return { kind: 'folders', a: A, b: Bp, summary: { added: added.length, removed: removed.length, changed: changed.length, unchanged: ma.size - removed.length - changed.length }, added: limit(added, cap), removed: limit(removed, cap), changed: limit(changed, cap) };
+  }
+  if (!sa.isFile() || !sb.isFile()) throw new RPError('INVALID_ARGUMENT', 'Compare two folders or two files.');
+  const ka = identify(await readAt(A, 0, 4096)), kb = identify(await readAt(Bp, 0, 4096));
+  // Archives / packs
+  const arcA = await openArchive(A).catch(() => null), arcB = arcA ? await openArchive(Bp).catch(() => null) : null;
+  if (arcA?.entries?.length && arcB?.entries) {
+    const ea = new Map(arcA.entries.map(e => [e.path, e])), eb = new Map(arcB.entries.map(e => [e.path, e]));
+    const added = [...eb.keys()].filter(k => !ea.has(k)).map(k => ({ path: k, size: eb.get(k).size }));
+    const removed = [...ea.keys()].filter(k => !eb.has(k)).map(k => ({ path: k, size: ea.get(k).size }));
+    const changed = [...ea.keys()].filter(k => eb.has(k) && (ea.get(k).size !== eb.get(k).size || (ea.get(k).md5 && eb.get(k).md5 && ea.get(k).md5 !== eb.get(k).md5))).map(k => ({ path: k, sizeA: ea.get(k).size, sizeB: eb.get(k).size, delta: eb.get(k).size - ea.get(k).size }));
+    changed.sort((x, y) => Math.abs(y.delta) - Math.abs(x.delta));
+    return { kind: 'archives', format: [arcA.format, arcB.format], a: A, b: Bp, ...(arcA.godotVersion ? { godotVersion: [arcA.godotVersion, arcB.godotVersion] } : {}), summary: { added: added.length, removed: removed.length, changed: changed.length, entriesA: ea.size, entriesB: eb.size }, added: limit(added, cap), removed: limit(removed, cap), changed: limit(changed, cap) };
+  }
+  // Executables
+  if (ka.category === 'executable' && kb.category === 'executable') {
+    const [ia, ib] = await Promise.all([inspectBinary({ file: A, strings: { limit: 1 } }), inspectBinary({ file: Bp, strings: { limit: 1 } })]);
+    const libs = i => new Set((i.binary?.imports ?? []).flatMap(x => (x.libraries ? x.libraries : [x.library])));
+    const fns = i => new Set((i.binary?.imports ?? []).flatMap(x => (x.functions ?? []).map(f => `${x.library}!${f}`)));
+    const ex = i => new Set(i.binary?.exports?.names ?? []);
+    const diff = (x, y) => ({ added: [...y].filter(v => !x.has(v)).slice(0, cap), removed: [...x].filter(v => !y.has(v)).slice(0, cap) });
+    const secs = i => new Map((i.binary?.sections ?? []).map(s => [s.name, s]));
+    const sA = secs(ia), sB = secs(ib);
+    const sections = [...new Set([...sA.keys(), ...sB.keys()])].map(n => ({ name: n, sizeA: sA.get(n)?.rawSize ?? sA.get(n)?.size ?? null, sizeB: sB.get(n)?.rawSize ?? sB.get(n)?.size ?? null, entropyA: sA.get(n)?.entropy, entropyB: sB.get(n)?.entropy })).filter(s => s.sizeA !== s.sizeB || s.entropyA !== s.entropyB);
+    return { kind: 'binaries', a: A, b: Bp, identical: ia.sha256 === ib.sha256, format: [ia.binary?.format, ib.binary?.format], arch: [ia.binary?.arch, ib.binary?.arch], size: [ia.size, ib.size], timestamp: [ia.binary?.timestamp, ib.binary?.timestamp], libraries: diff(libs(ia), libs(ib)), importedFunctions: diff(fns(ia), fns(ib)), exports: diff(ex(ia), ex(ib)), changedSections: sections.slice(0, 100), hints: [ia.hints, ib.hints] };
+  }
+  // Raw bytes
+  const BLOCK = 4096, sizeA = sa.size, sizeB = sb.size;
+  const scan = Math.min(Math.max(sizeA, sizeB), 512 * MiB);
+  const fa = await fs.open(A, 'r'), fb = await fs.open(Bp, 'r');
+  let first = null, blocks = 0;
+  const regions = [];
+  try {
+    const ba = Buffer.alloc(MiB), bb = Buffer.alloc(MiB);
+    for (let pos = 0; pos < scan; pos += MiB) {
+      const [ra, rb] = await Promise.all([fa.read(ba, 0, MiB, pos), fb.read(bb, 0, MiB, pos)]);
+      const n = Math.max(ra.bytesRead, rb.bytesRead);
+      for (let o = 0; o < n; o += BLOCK) {
+        const x = ba.subarray(o, Math.min(o + BLOCK, ra.bytesRead)), y = bb.subarray(o, Math.min(o + BLOCK, rb.bytesRead));
+        if (x.equals(y)) continue;
+        blocks++;
+        if (first === null) { let k = 0; while (k < Math.min(x.length, y.length) && x[k] === y[k]) k++; first = pos + o + k; }
+        const at = pos + o, last = regions[regions.length - 1];
+        if (last && last.end === at) last.end = at + BLOCK; else if (regions.length < 200) regions.push({ start: at, end: at + BLOCK });
+      }
+    }
+  } finally { await fa.close(); await fb.close(); }
+  return { kind: 'bytes', a: A, b: Bp, formats: [ka.name, kb.name], size: [sizeA, sizeB], identical: blocks === 0 && sizeA === sizeB, firstDifference: first, differingBlocks4K: blocks, regions: regions.map(r => ({ start: r.start, end: r.end, length: r.end - r.start })), scannedBytes: scan, hint: first !== null ? `re_probe {file, offset:${first}} on each file shows the bytes around the first difference.` : undefined };
+}
+
+export async function report({ path: dir, out } = {}) {
+  const scan = await scanProject({ path: dir });
+  const graph = await buildGraph(dir);
+  const name = scan.engines.find(e => e.details?.name)?.details?.name ?? path.basename(scan.root);
+  const lines = [`# Architecture — ${name}`, '', `Generated by [ReversePort](https://github.com/laaielichter/reverseport) on ${new Date().toISOString().slice(0, 10)} from \`${scan.root}\`.`, ''];
+  lines.push('## At a glance', '', `- **Engine / stack:** ${scan.engines.map(e => e.name).join(', ') || 'not detected'}`, `- **Files:** ${scan.files} (${(scan.totalBytes / MiB).toFixed(1)} MiB)`, `- **Languages:** ${Object.entries(scan.languages).map(([l, v]) => `${l} (${v.files} files, ${v.lines} lines)`).join(', ') || '—'}`, `- **Entry points:** ${scan.entryPoints.map(e => `\`${e.file}\``).join(', ') || '—'}`, '');
+  lines.push('## Module graph', '', 'Most connected files (arrows point to what a file depends on):', '', '```mermaid', graphMermaid(graph, 40), '```', '');
+  if (graph.cycles.length) lines.push('## Dependency cycles', '', ...graph.cycles.slice(0, 10).map(c => `- ${c.map(x => `\`${x}\``).join(' ↔ ')}`), '');
+  const hubs = [...graph.nodes.keys()].map(k => ({ k, n: graph.inDegree.get(k) })).sort((x, y) => y.n - x.n).slice(0, 12).filter(x => x.n);
+  if (hubs.length) lines.push('## Most used', '', '| File | Used by |', '|---|---|', ...hubs.map(h => `| \`${h.k}\` | ${h.n} |`), '');
+  const scenes = scan.entryPoints.filter(e => /\.(tscn|unity|prefab)$/.test(e.file)).slice(0, 3);
+  for (const s of scenes) {
+    const sc = await readScene(path.join(scan.root, s.file)).catch(() => null);
+    if (sc?.mermaid) lines.push(`## Scene: ${s.file}`, '', '```mermaid', sc.mermaid, '```', '');
+  }
+  const classes = [];
+  for (const n of graph.nodes.values()) for (const c of n.sym?.classes ?? []) if (c.name) classes.push({ name: c.name, extends: c.extends, file: n.file, functions: n.sym.functions.length });
+  if (classes.length) lines.push('## Classes', '', '| Class | Extends | File | Functions |', '|---|---|---|---|', ...classes.slice(0, 150).map(c => `| ${c.name} | ${c.extends ?? ''} | \`${c.file}\` | ${c.functions} |`), '');
+  if (graph.orphans.length) lines.push('## Possibly unused', '', ...graph.orphans.slice(0, 40).map(o => `- \`${o}\``), '');
+  const ext = [...graph.externals.entries()].sort((x, y) => y[1] - x[1]).slice(0, 25);
+  if (ext.length) lines.push('## External dependencies', '', ...ext.map(([k, v]) => `- ${k} (${v})`), '');
+  const dest = out ? path.resolve(out) : path.join(await workspaceDir('reports'), `${pascalCase(name)}-ARCHITECTURE.md`);
+  await fs.mkdir(path.dirname(dest), { recursive: true });
+  await fs.writeFile(dest, lines.join('\n'));
+  return { file: dest, name, engines: scan.engines.map(e => e.name), files: scan.files, classes: classes.length, cycles: graph.cycles.length, entryPoints: scan.entryPoints, preview: lines.slice(0, 40).join('\n') };
+}

package/port/src/connect.mjs

@@ -0,0 +1,58 @@
+// `reverseport connect [client]`: the exact snippet to connect ReversePort to any agent, with no setup wizard and no
+// dependencies. MCP clients get their own config format; everything else gets HTTP, OpenAPI or function definitions.
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { RPError } from './util.mjs';
+import { closest } from './agent.mjs';
+
+const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+function launch(mode) {
+  // On Windows, clients cannot start the npx .cmd shim directly; cmd /c does it.
+  if (mode === 'npx') return process.platform === 'win32' ? { command: 'cmd', args: ['/c', 'npx', '-y', 'reverseport@latest', 'mcp'] } : { command: 'npx', args: ['-y', 'reverseport@latest', 'mcp'] };
+  return { command: 'node', args: [path.join(REPO, 'bin', 'reverseport.mjs'), 'mcp'] };
+}
+
+const json = v => JSON.stringify(v, null, 2);
+
+export const CLIENTS = {
+  'claude-code': { file: 'shell', snippet: l => `claude mcp add rea -- ${l.command} ${l.args.join(' ')}\n# or instead (not both), the plugin with skills and the porting agent:\n/plugin marketplace add laaielichter/reverseport\n/plugin install reverseport@reverseport` },
+  'claude-desktop': { file: 'claude_desktop_config.json', snippet: l => json({ mcpServers: { rea: l } }) },
+  cursor: { file: '~/.cursor/mcp.json', snippet: l => json({ mcpServers: { rea: l } }) },
+  windsurf: { file: '~/.codeium/windsurf/mcp_config.json', snippet: l => json({ mcpServers: { rea: l } }) },
+  cline: { file: 'cline_mcp_settings.json', snippet: l => json({ mcpServers: { rea: { ...l, disabled: false } } }) },
+  'roo-code': { file: 'mcp_settings.json', snippet: l => json({ mcpServers: { rea: l } }) },
+  vscode: { file: '.vscode/mcp.json (GitHub Copilot agent mode)', snippet: l => json({ servers: { rea: { type: 'stdio', ...l } } }) },
+  codex: { file: '~/.codex/config.toml', snippet: l => `[mcp_servers.rea]\ncommand = ${JSON.stringify(l.command)}\nargs = ${JSON.stringify(l.args)}\nstartup_timeout_sec = 60\ntool_timeout_sec = 600` },
+  'gemini-cli': { file: '~/.gemini/settings.json', snippet: l => json({ mcpServers: { rea: { ...l, env: { REVERSEPORT_SCHEMA: 'portable' }, timeout: 600000 } } }) },
+  opencode: { file: 'opencode.json', snippet: l => json({ mcp: { rea: { type: 'local', command: [l.command, ...l.args], enabled: true } } }) },
+  zed: { file: 'Zed settings.json', snippet: l => json({ context_servers: { rea: { source: 'custom', command: l.command, args: l.args } } }) },
+  continue: { file: '.continue/mcpServers/reverseport.yaml', snippet: l => `name: ReversePort\nversion: 1.0.0\nschema: v1\nmcpServers:\n  - name: rea\n    command: ${l.command}\n    args:\n${l.args.map(a => `      - ${JSON.stringify(a)}`).join('\n')}` },
+  goose: { file: '~/.config/goose/config.yaml', snippet: l => `extensions:\n  rea:\n    type: stdio\n    name: rea\n    cmd: ${l.command}\n    args: ${JSON.stringify(l.args)}\n    enabled: true\n    timeout: 600` },
+  'lm-studio': { file: 'LM Studio mcp.json', snippet: l => json({ mcpServers: { rea: l } }) },
+  'mcp-http': { file: 'any client that takes an MCP URL (n8n, LangChain MultiServerMCPClient, Vercel AI SDK, Open WebUI via mcpo…)', snippet: () => 'reverseport serve\n# then connect to: http://127.0.0.1:32147/mcp   (set REVERSEPORT_TOKEN to require a bearer token)' },
+  openai: { file: 'OpenAI Chat Completions / Responses, and OpenAI-compatible servers (vLLM, Ollama, LM Studio, llama.cpp)', snippet: () => 'reverseport serve\ncurl -s "http://127.0.0.1:32147/api/agent/tools?format=openai-strict"   # tools=…   (format=responses for the Responses API)\n# run a call: POST http://127.0.0.1:32147/api/agent/call {"name": "...", "arguments": {...}}' },
+  anthropic: { file: 'Anthropic Messages API tool use', snippet: () => 'reverseport serve\ncurl -s "http://127.0.0.1:32147/api/agent/tools?format=anthropic"   # tools=…\n# run a call: POST http://127.0.0.1:32147/api/agent/call {"name": "...", "arguments": {...}}' },
+  gemini: { file: 'Gemini API function calling', snippet: () => 'reverseport serve\ncurl -s "http://127.0.0.1:32147/api/agent/tools?format=gemini"   # tools=…\n# run a call: POST http://127.0.0.1:32147/api/agent/call {"name": "...", "arguments": {...}}' },
+  openapi: { file: 'LangChain/LlamaIndex OpenAPI tools, Semantic Kernel, CrewAI, AutoGen, n8n HTTP; GPT Actions via a tunnel', snippet: () => 'reverseport serve\n# OpenAPI 3.1: http://127.0.0.1:32147/api/openapi.json   (each tool is POST /api/agent/tools/<name>)\n# GPT Actions and other hosted agents need a public HTTPS URL: set REVERSEPORT_TOKEN, REVERSEPORT_HOST=0.0.0.0 and\n# REVERSEPORT_ALLOWED_HOSTS=<tunnel host>, then expose the port with a tunnel of your choice.' },
+  shell: { file: 'agents that can only run commands', snippet: () => 'reverseport help                      # what exists\nreverseport describe re_scan          # one tool\'s schema\nreverseport scan ./Game --compact     # JSON on stdout, errors as JSON on stderr\nreverseport re_scan --args \'{"path":"./Game"}\'\necho \'{"path":"./Game"}\' | reverseport re_scan --request -' },
+};
+
+export function connect({ client, mode } = {}) {
+  const how = mode === 'npx' || mode === 'local' ? mode : 'npx';
+  const l = launch(how);
+  if (!client) {
+    return {
+      clients: Object.fromEntries(Object.entries(CLIENTS).map(([k, v]) => [k, v.file])),
+      easiest: 'npx -y reverseport@latest setup   (finds and configures installed agents for you)',
+      next: 'reverseport connect <client>   (add --mode local to point at this copy instead of npx)',
+    };
+  }
+  const key = String(client).toLowerCase().replace(/_/g, '-');
+  const c = CLIENTS[key];
+  if (!c) {
+    const near = closest(key, Object.keys(CLIENTS), 3);
+    throw new RPError('INVALID_ARGUMENT', `Unknown client "${client}".${near ? ` Did you mean "${near}"?` : ''} Clients: ${Object.keys(CLIENTS).join(', ')}.`);
+  }
+  return { client: key, where: c.file, snippet: c.snippet(how === 'local' ? launch('local') : l), serverName: 'rea — the same name setup uses, so running both never registers the server twice', tools: 'ReversePort lists its own tools plus the engine core; REVERSEPORT_TOOLS=all lists every engine tool, REVERSEPORT_TOOLS=port only ReversePort\'s.' };
+}

package/port/src/convert.mjs

@@ -0,0 +1,134 @@
+// Coordinate-system conversion between engines: positions, rotations (quaternions), scales, Euler angles
+// in each engine's own convention, and camera field of view. Every system is an orthonormal axis map to
+// Godot's frame (right-handed, Y up, -Z forward, meters) plus a unit scale.
+import { RPError } from './util.mjs';
+import { matToQuat } from './scene.mjs';
+
+const I = [[1, 0, 0], [0, 1, 0], [0, 0, 1]];
+/** Rows map Godot coordinates into the system: p_sys = M · p_godot × scale. */
+export const SYSTEMS = {
+  godot: { M: I, scale: 1, label: 'Godot (right-handed, Y up, -Z forward, m)' },
+  'godot-csharp': { M: I, scale: 1, label: 'Godot C# (same as Godot)' },
+  threejs: { M: I, scale: 1, label: 'three.js (right-handed, Y up, -Z camera forward, m)' },
+  gltf: { M: I, scale: 1, label: 'glTF 2.0 (right-handed, Y up, m; assets face +Z)' },
+  bevy: { M: I, scale: 1, label: 'Bevy (right-handed, Y up, -Z forward, m)' },
+  unity: { M: [[1, 0, 0], [0, 1, 0], [0, 0, -1]], scale: 1, label: 'Unity (left-handed, Y up, +Z forward, m) — Z mirrored' },
+  'unity-xmirror': { M: [[-1, 0, 0], [0, 1, 0], [0, 0, 1]], scale: 1, label: 'Unity, X mirrored (glTF-importer style: model fronts stay on +Z)' },
+  unreal: { M: [[0, 0, -1], [1, 0, 0], [0, 1, 0]], scale: 100, label: 'Unreal (left-handed, Z up, X forward, Y right, cm)' },
+  blender: { M: [[1, 0, 0], [0, 0, -1], [0, 1, 0]], scale: 1, label: 'Blender (right-handed, Z up, m) via the glTF axis rule' },
+};
+
+const T = m => m[0].map((_, c) => m.map(r => r[c]));
+const mul = (a, b) => a.map(r => b[0].map((_, c) => r.reduce((s, v, k) => s + v * b[k][c], 0)));
+const mulVec = (m, v) => m.map(r => r[0] * v[0] + r[1] * v[1] + r[2] * v[2]);
+const clean = x => { const r = Math.round(x * 1e6) / 1e6; return Object.is(r, -0) ? 0 : r; };
+
+export function quatToMat([x, y, z, w]) {
+  const n = Math.hypot(x, y, z, w) || 1;
+  x /= n; y /= n; z /= n; w /= n;
+  return [
+    [1 - 2 * (y * y + z * z), 2 * (x * y - z * w), 2 * (x * z + y * w)],
+    [2 * (x * y + z * w), 1 - 2 * (x * x + z * z), 2 * (y * z - x * w)],
+    [2 * (x * z - y * w), 2 * (y * z + x * w), 1 - 2 * (x * x + y * y)],
+  ];
+}
+
+const rad = d => (d * Math.PI) / 180, deg = r => (r * 180) / Math.PI;
+const clamp1 = v => Math.max(-1, Math.min(1, v));
+const Rx = a => [[1, 0, 0], [0, Math.cos(a), -Math.sin(a)], [0, Math.sin(a), Math.cos(a)]];
+const Ry = a => [[Math.cos(a), 0, Math.sin(a)], [0, 1, 0], [-Math.sin(a), 0, Math.cos(a)]];
+const Rz = a => [[Math.cos(a), -Math.sin(a), 0], [Math.sin(a), Math.cos(a), 0], [0, 0, 1]];
+
+/** R = Ry·Rx·Rz (Godot EULER_ORDER_YXZ; Unity applies Z, X, Y) → [x, y, z] radians. */
+export function matToEulerYXZ(m) {
+  const b = Math.asin(clamp1(-m[1][2]));
+  if (Math.abs(m[1][2]) < 0.9999999) return [b, Math.atan2(m[0][2], m[2][2]), Math.atan2(m[1][0], m[1][1])];
+  return [b, Math.atan2(-m[2][0], m[0][0]), 0];
+}
+/** R = Rx·Ry·Rz (three.js 'XYZ') → [x, y, z] radians. */
+export function matToEulerXYZ(m) {
+  const y = Math.asin(clamp1(m[0][2]));
+  if (Math.abs(m[0][2]) < 0.9999999) return [Math.atan2(-m[1][2], m[2][2]), y, Math.atan2(-m[0][1], m[0][0])];
+  return [Math.atan2(m[2][1], m[1][1]), y, 0];
+}
+export const eulerYXZToMat = ([x, y, z]) => mul(mul(Ry(y), Rx(x)), Rz(z));
+export const eulerXYZToMat = ([x, y, z]) => mul(mul(Rx(x), Ry(y)), Rz(z));
+
+function system(name) {
+  const s = SYSTEMS[String(name ?? '').toLowerCase()];
+  if (!s) throw new RPError('INVALID_ARGUMENT', `Unknown coordinate system "${name}". Use one of: ${Object.keys(SYSTEMS).join(', ')}.`);
+  return s;
+}
+
+/** Axis transform from system A to system B (orthonormal) and unit factor. */
+export function transformBetween(from, to) {
+  const a = system(from), b = system(to);
+  return { T: mul(b.M, T(a.M)), factor: b.scale / a.scale };
+}
+
+function eulerFor(sys, R) {
+  if (['godot', 'godot-csharp', 'bevy'].includes(sys)) { const e = matToEulerYXZ(R); return { order: 'YXZ', unit: 'degrees (rotation_degrees); rotation uses radians', degrees: e.map(deg).map(clean), radians: e.map(clean) }; }
+  if (sys.startsWith('unity')) { const e = matToEulerYXZ(R); return { order: 'Z, X, Y (Unity)', unit: 'degrees (localEulerAngles)', degrees: e.map(deg).map(clean) }; }
+  if (sys === 'threejs') { const e = matToEulerXYZ(R); return { order: "XYZ (three.js default; for YXZ set rotation.order = 'YXZ')", unit: 'radians', radians: e.map(clean), yxz: matToEulerYXZ(R).map(clean) }; }
+  return null;
+}
+
+/**
+ * Convert transforms between engines. Inputs in the source system: position [x,y,z], rotation as a
+ * quaternion [x,y,z,w] or euler degrees in the source engine's convention, scale [x,y,z], fov in degrees.
+ */
+export function convert({ from, to, position, rotation, euler, scale, fov, aspect = 16 / 9 } = {}) {
+  const { T: M, factor } = transformBetween(from, to);
+  const out = { from: system(from).label, to: system(to).label, axisMatrix: M.map(r => r.map(clean)), unitFactor: factor };
+  const vec3 = (v, what) => { if (!Array.isArray(v) || v.length !== 3 || v.some(n => typeof n !== 'number' || !Number.isFinite(n))) throw new RPError('INVALID_ARGUMENT', `${what} must be [x, y, z] numbers.`); return v; };
+  if (position) out.position = mulVec(M, vec3(position, 'position')).map(v => clean(v * factor));
+  let R = null;
+  const src = String(from).toLowerCase();
+  if (rotation) {
+    if (!Array.isArray(rotation) || rotation.length !== 4) throw new RPError('INVALID_ARGUMENT', 'rotation must be a quaternion [x, y, z, w].');
+    R = quatToMat(rotation);
+  } else if (euler) {
+    const e = vec3(euler, 'euler').map(rad);
+    if (['godot', 'godot-csharp', 'bevy'].includes(src) || src.startsWith('unity')) R = eulerYXZToMat(e);
+    else if (src === 'threejs') R = eulerXYZToMat(e);
+    else throw new RPError('INVALID_ARGUMENT', `Give a quaternion for ${from}; euler input is supported for godot, unity and threejs.`);
+  }
+  if (R) {
+    const R2 = mul(mul(M, R), T(M));
+    out.rotation = { quaternion: matToQuat(R2).map(clean), ...(eulerFor(String(to).toLowerCase(), R2) ? { euler: eulerFor(String(to).toLowerCase(), R2) } : {}) };
+  }
+  if (scale) out.scale = M.map(r => clean(r.reduce((s, v, k) => s + Math.abs(v) * vec3(scale, 'scale')[k], 0)));
+  if (fov != null) {
+    const verticalIn = !String(from).toLowerCase().startsWith('unreal');
+    const verticalOut = !String(to).toLowerCase().startsWith('unreal');
+    const v = verticalIn ? fov : deg(2 * Math.atan(Math.tan(rad(fov) / 2) / aspect));
+    out.fov = { degrees: clean(verticalOut ? v : deg(2 * Math.atan(Math.tan(rad(v) / 2) * aspect))), axis: verticalOut ? 'vertical' : 'horizontal', aspect };
+  }
+  out.notes = [
+    'Positions and rotations stay visually identical; the axis matrix shows where each source axis goes.',
+    ...(Math.abs(det(M) + 1) < 1e-9 ? ['Handedness changes (mirror): meshes imported separately keep their own importer orientation — if a model looks backwards, rotate that node 180° about the up axis.'] : []),
+    ...(factor !== 1 ? [`Distances scale ×${factor} (speeds, forces and ranges in code too).`] : []),
+  ];
+  return out;
+}
+
+const det = m => m[0][0] * (m[1][1] * m[2][2] - m[1][2] * m[2][1]) - m[0][1] * (m[1][0] * m[2][2] - m[1][2] * m[2][0]) + m[0][2] * (m[1][0] * m[2][1] - m[1][1] * m[2][0]);
+
+/** Convert a neutral scene tree (from re_scene) into another system, in place on a copy. */
+export function convertTree(node, from, to) {
+  const { T: M, factor } = transformBetween(from, to);
+  const visit = n => {
+    const copy = { ...n };
+    if (n.transform) {
+      const R = quatToMat(n.transform.rotation ?? [0, 0, 0, 1]);
+      copy.transform = {
+        position: mulVec(M, n.transform.position ?? [0, 0, 0]).map(v => clean(v * factor)),
+        rotation: matToQuat(mul(mul(M, R), T(M))).map(clean),
+        scale: M.map(r => clean(r.reduce((s, v, k) => s + Math.abs(v) * (n.transform.scale ?? [1, 1, 1])[k], 0))),
+      };
+    }
+    copy.children = (n.children ?? []).map(visit);
+    return copy;
+  };
+  return visit(node);
+}