@bitmagic/cli 0.1.70 → 0.1.71-dev.1

package/assets/roblox-port/port-state.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { parseArgs } from 'node:util';
+import { pathToFileURL } from 'node:url';
+import { VERSION, assert, hash, equal, readJson, writeJson, loadProject, readBase, materialize, assertTarget, reconcile, verifyReadback, validatePlan, withLock } from './lib.mjs';
+
+export function init(sourceRoot, portRoot, environment) {
+  const source = fs.realpathSync(sourceRoot);
+  const parent = fs.realpathSync(path.dirname(path.resolve(portRoot)));
+  const root = path.join(parent, path.basename(portRoot));
+  assert(root !== source && !root.startsWith(`${source}${path.sep}`), 'Port workspace must be outside the source project');
+  assert(!fs.existsSync(root), 'Output already exists; do not overwrite an existing project');
+  const metadata = readJson(path.join(source, 'bitmagic.json'));
+  assert(typeof metadata.gameId === 'string' && typeof metadata.engineVersion === 'string', 'Missing Bitmagic source identity');
+  const env = environment ?? metadata.environment;
+  assert(typeof env === 'string' && env.length > 0, 'Explicit source environment required');
+  assert(!metadata.environment || env === metadata.environment, 'Source environment mismatch');
+  const project = { schemaVersion: VERSION, projectId: randomUUID(), targetId: randomUUID(), source: { root: source, gameId: metadata.gameId, engineVersion: metadata.engineVersion, environment: env }, target: { placeId: null, universeId: null }, runtimeProfile: 'private-single-player' };
+  fs.mkdirSync(root);
+  for (const dir of ['generated/shared', 'generated/client', 'generated/server', 'overrides', 'tests', 'state', '.bitmagic/roblox/runs']) fs.mkdirSync(path.join(root, dir), { recursive: true });
+  writeJson(path.join(root, 'project.json'), project, true);
+  writeJson(path.join(root, 'incoming.json'), { schemaVersion: VERSION, sourceFiles: ['bitmagic.json'], scripts: [] }, true);
+  writeJson(path.join(root, 'port-contract.json'), { schemaVersion: VERSION, features: [], deviations: [] }, true);
+  writeJson(path.join(root, 'assets.lock.json'), { schemaVersion: VERSION, assets: [] }, true);
+  fs.writeFileSync(path.join(root, '.gitignore'), '.bitmagic/\nstate/lock\n', { flag: 'wx' });
+  return { schemaVersion: VERSION, root, projectId: project.projectId, targetId: project.targetId };
+}
+export function prepare(root, live, run, { bind = false, adopt = false } = {}) {
+  return withLock(root, () => {
+    const project = loadProject(root);
+    assertTarget(project, live, bind);
+    assert(live.pendingRun === null, 'PARTIAL_APPLY: resume or roll back the existing run first');
+    const incoming = materialize(root, project), base = readBase(root);
+    assert(!base || live.buildId === base.planHash, 'BUILD_MISMATCH: recover the accepted baseline before planning');
+    const result = reconcile(project, incoming.scripts, base, live, adopt);
+    const body = { schemaVersion: VERSION, runId: randomUUID(), project, baseHash: hash(base), baselineBefore: base, sourceHash: incoming.sourceHash, sourceFiles: incoming.sourceFiles, packageHash: incoming.packageHash, targetBefore: live.target, buildBefore: live.buildId, snapshot: live, generated: incoming.scripts, ...result };
+    const plan = { ...body, planHash: hash(body) };
+    assert(!fs.existsSync(run), 'Run directory already exists; use its plan or choose a new run');
+    fs.mkdirSync(run, { recursive: true, mode: 0o700 });
+    writeJson(path.join(run, 'plan.json'), plan, true);
+    writeJson(path.join(run, 'before.json'), live, true);
+    writeJson(path.join(run, 'journal.json'), { schemaVersion: VERSION, stage: result.conflicts.length ? 'conflict' : 'prepared', planHash: plan.planHash }, true);
+    return plan;
+  });
+}
+export function checkFresh(root, plan) {
+  validatePlan(plan);
+  const project = loadProject(root), incoming = materialize(root, project);
+  assert(equal(project, plan.project), 'Project binding changed; prepare again');
+  assert(incoming.sourceHash === plan.sourceHash && incoming.packageHash === plan.packageHash, 'SOURCE_CHANGED: prepare a new plan');
+  const base = readBase(root);
+  assert(hash(base) === plan.baseHash || base?.planHash === plan.planHash, 'Baseline advanced since planning');
+}
+export function accept(root, run, live) {
+  return withLock(root, () => {
+    const plan = readJson(path.join(run, 'plan.json'));
+    checkFresh(root, plan); verifyReadback(plan, live);
+    writeJson(path.join(run, 'after.json'), live);
+    const base = { schemaVersion: VERSION, planHash: plan.planHash, sourceHash: plan.sourceHash, packageHash: plan.packageHash, generated: plan.generated, applied: plan.desired };
+    // The accepted GENERATED values remain the three-way base. Kept live overrides are recorded
+    // separately; making them the generated base would erase them on the next unchanged export.
+    writeJson(path.join(root, 'state/base.json'), base);
+    writeJson(path.join(run, 'journal.json'), { schemaVersion: VERSION, stage: 'applied', planHash: plan.planHash });
+    return { schemaVersion: VERSION, stage: 'applied', buildId: plan.planHash, verified: false, saveStatus: 'pending' };
+  });
+}
+export function recordSave(root, receipt) {
+  return withLock(root, () => {
+    const base = readBase(root); assert(base, 'No accepted Studio build');
+    assert(receipt.buildId === base.planHash, 'Save receipt is for a different build');
+    assert(['pending', 'saved', 'unsupported', 'failed', 'unconfirmed'].includes(receipt.status), 'Invalid save status');
+    if (receipt.status === 'saved') {
+      assert(typeof receipt.destination === 'string' && receipt.destination.length > 0, 'Saved destination required');
+      assert(typeof receipt.evidence === 'string' && receipt.evidence.length > 0, 'Save evidence required');
+      assert(receipt.published === false, 'Receipt must identify a non-publishing save');
+    }
+    writeJson(path.join(root, 'state/save.json'), { schemaVersion: VERSION, ...receipt });
+    return receipt;
+  });
+}
+export function acceptRollback(root, run, receipt) {
+  return withLock(root, () => {
+    const plan = validatePlan(readJson(path.join(run, 'plan.json')));
+    assert(equal(loadProject(root), plan.project), 'Project binding changed');
+    assert(receipt.stage === 'rolled-back' && receipt.planHash === plan.planHash && receipt.failures.length === 0, 'Rollback incomplete or for another plan');
+    const restored = receipt.snapshot;
+    // Sorting affects order only, not what was preserved. Compare exact editor source and metadata.
+    const sorted = snapshot => ({ ...snapshot, scripts: [...snapshot.scripts].sort((a, b) => JSON.stringify(a.path).localeCompare(JSON.stringify(b.path))) });
+    assert(equal(sorted(restored), sorted(plan.snapshot)), 'Rollback readback differs; reconcile before changing the local baseline');
+    const base = readBase(root);
+    assert(hash(base) === plan.baseHash || base?.planHash === plan.planHash, 'A later baseline must not be rolled back');
+    if (plan.baselineBefore === null) {
+      const file = path.join(root, 'state/base.json');
+      if (fs.existsSync(file)) fs.unlinkSync(file);
+    } else writeJson(path.join(root, 'state/base.json'), plan.baselineBefore);
+    writeJson(path.join(run, 'rollback.json'), receipt);
+    writeJson(path.join(run, 'journal.json'), { schemaVersion: VERSION, stage: 'rolled-back', planHash: plan.planHash });
+    return { schemaVersion: VERSION, stage: 'rolled-back', buildId: plan.buildBefore };
+  });
+}
+export function status(root) {
+  const project = loadProject(root), base = readBase(root);
+  const saveFile = path.join(root, 'state/save.json'), save = fs.existsSync(saveFile) ? readJson(saveFile) : null;
+  const current = base ? materialize(root, project) : null;
+  const stale = base ? current.sourceHash !== base.sourceHash || current.packageHash !== base.packageHash : false;
+  return { schemaVersion: VERSION, projectId: project.projectId, targetId: project.targetId, stage: base ? 'applied' : 'prepared', buildId: base?.planHash ?? null, localChanges: stale, saveStatus: save && save.buildId === base?.planHash && !stale ? save.status : 'pending', studioReadbackRequired: true };
+}
+function main() {
+  const { values: a, positionals } = parseArgs({ allowPositionals: true, options: { source: { type: 'string' }, project: { type: 'string' }, environment: { type: 'string' }, live: { type: 'string' }, run: { type: 'string' }, receipt: { type: 'string' }, 'bind-target': { type: 'boolean' }, adopt: { type: 'boolean' }, help: { type: 'boolean' } } });
+  if (a.help) { console.log('port-state.mjs init --source <source> --project <new-port> [--environment dev]\nprepare --project <port> --live <snapshot.json> --run <new-run-dir> [--bind-target] [--adopt]\naccept --project <port> --run <run-dir> --live <readback.json>\naccept-rollback --project <port> --run <run-dir> --receipt <rollback.json>\nstatus --project <port>\nrecord-save --project <port> --receipt <save.json>'); return; }
+  assert(a.project, '--project required');
+  let result;
+  switch (positionals[0]) {
+    case 'init': assert(a.source, '--source required'); result = init(a.source, a.project, a.environment); break;
+    case 'prepare': assert(a.live && a.run, '--live and --run required'); result = prepare(a.project, readJson(a.live), a.run, { bind: a['bind-target'], adopt: a.adopt }); break;
+    case 'accept': assert(a.live && a.run, '--live and --run required'); result = accept(a.project, a.run, readJson(a.live)); break;
+    case 'accept-rollback': assert(a.receipt && a.run, '--receipt and --run required'); result = acceptRollback(a.project, a.run, readJson(a.receipt)); break;
+    case 'status': result = status(a.project); break;
+    case 'record-save': assert(a.receipt, '--receipt required'); result = recordSave(a.project, readJson(a.receipt)); break;
+    default: throw Error('Unknown command; use --help');
+  }
+  console.log(JSON.stringify(result));
+  if (result.conflicts?.length) process.exitCode = 2;
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(fs.realpathSync(process.argv[1])).href) {
+  try { main(); } catch (error) { console.error(error.message); process.exitCode = 1; }
+}

package/assets/roblox-port/references/assets.md

@@ -0,0 +1,100 @@
+# Original assets and packed geometry
+
+For each reachable asset try: permission-valid cached original → supported direct import →
+deterministic conversion → faithful native approximation → licensed/generated replacement.
+Record a valid attempted route or concrete preflight blocker, not blind repeated retries. Missing
+gameplay-critical content blocks completion unless the creator explicitly changes the contract.
+
+Use the source bytes, not screenshots, whenever possible. Packed mesh JSON, articulated components,
+procedural buildings and audio-bank URLs count as original content. Retain source bytes, decoder
+version, conversion recipe and hash, target owner/type/ID/version, upload operation, and evidence.
+Reuse by bytes + recipe + importer version + owner/permission context, not filename.
+
+Studio's importer and Open Cloud asset endpoints have distinct format/settings capabilities.
+Discover the current route. GLB/glTF Model creation is documented; a raw Mesh upload is not a
+general geometry uploader, and content updates are more restricted than asset creation. Tool
+`insert_asset` inserts an existing asset; `store_image` produces a tool reference, not a permanent
+game image. Neither transfers all local models/audio automatically.
+
+## Offline packed-mesh helper
+
+`export-packed-mesh.mjs` supports these explicit, little-endian layouts only:
+
+| Layout | Buffers | Other semantics |
+| --- | --- | --- |
+| `bitmagic-packed-v1`, kit `version: 1` | Unindexed float32 XYZ positions/normals/RGB colors | Optional pivot, height and muzzleHeight. |
+| `bitmagic-packed-v2`, kit `version: 2` | int16 positions × quantum; normalized int8 normals; uint8 colors; uint16 indices | Ordered `[start,count,materialIndex]` groups and articulated pivots. |
+
+Unknown fields/layouts fail. Read the actual source decoder before selecting one. The helper does
+not extract arbitrary procedural code, skin/retarget skeletal animation, bake textures, import
+into Studio, upload assets, or prove visual parity. Those remain explicit conversion tasks.
+
+Save a recipe in the port workspace. This calibration example preserves source axes and scale;
+choose measured values for the actual game:
+
+```json
+{
+  "schemaVersion": 1,
+  "format": "bitmagic-packed-v1",
+  "meshIds": ["townhall"],
+  "basis": [1,0,0, 0,1,0, 0,0,1],
+  "scale": 1,
+  "materials": [{
+    "name": "source-painted",
+    "doubleSided": false,
+    "pbrMetallicRoughness": {
+      "baseColorFactor": [1,1,1,1],
+      "metallicFactor": 0,
+      "roughnessFactor": 0.8
+    }
+  }]
+}
+```
+
+```text
+node "<bundle>/export-packed-mesh.mjs" --input <original-kit.json> --recipe <recipe.json> --out <new-model.glb>
+```
+
+It emits GLB plus `<new-model.glb>.json` with hashes, mesh IDs, triangles, vertices and original
+pivot metadata. It preserves pivot translations, vertex colors and material groups, transforms
+normals, and reverses winding for a reflected basis. Select only reachable mesh IDs; articulated
+components must share the intended hierarchy after native import. Preserve muzzle/footprint
+metadata in native code even if the importer ignores GLB extras.
+
+Verify silhouette, dimensions, pivot articulation, colors/PBR, grounding, sockets, collision roles
+and animation timing after import. Vertex colors surviving a GLB export do not prove the chosen
+Roblox import preserves their appearance. If necessary bake an atlas and record that conversion.
+Gray replacement materials are not an acceptable silent success. Use inexpensive dedicated
+collision geometry, and disable collision/touch/query for decorative content where appropriate.
+
+Zero-area triangles are rejected by default. If inspection confirms that these are degenerate
+source faces, set `"degenerateTriangles": "drop"` in the recipe. The receipt records original,
+retained and dropped triangle counts; the converter removes unused vertices too. It never
+invents normals for retained surfaces. Include the cleanup in the accepted conversion evidence.
+
+## Uploads, permissions and native reconstruction
+
+Use only the selected creator/group owner and declared dependencies. Asset upload, moderation,
+experience permissions, and working playback/rendering are separate states. Private ownership
+does not prove a target experience can play audio. If asset permissions need an existing place,
+ask the creator to establish that in Studio; do not create/publish an experience yourself.
+
+Track operations before polling; after ambiguous timeouts query their actual outcome before
+creating duplicates. Bound retries/concurrency and follow throttling. Preserve previous asset
+mappings when changed content requires a new ID. Avoid auto-updating live package dependencies.
+Never upload secrets, unrelated local files, recovery archives, or signed URL credentials.
+
+Keep original voices, cue timing, subtitles, cooldowns, overlap caps and ducking. Generic growls
+are a replacement, not proof the original voice pack transferred. Source cosmetics/content changes
+are intentional overrides only when requested; do not infer them from platform stereotypes.
+
+Store native construction recipes and per-object identities/property snapshots in the port
+workspace. Recipes must support scoped updates; do not run a full rebuild that erases unrelated
+models. Inspect imported marketplace models for embedded scripts before executing them.
+
+When an image-upload tool needs temporary HTTP hosting, expose only the intended export directory,
+bind narrowly, record the owned PID/port, and stop it and its children after the transfer.
+
+- [Studio importer](https://create.roblox.com/docs/studio/importer).
+- [Assets API guide](https://create.roblox.com/docs/cloud/guides/usage-assets).
+- [Audio assets](https://create.roblox.com/docs/audio/assets).

package/assets/roblox-port/references/source-and-runtime.md

@@ -0,0 +1,68 @@
+# Source contracts and native runtime
+
+Inventory reachable code and data from `Game.ts`, `game.json`, `world.json`, imported JSON,
+asset registries, audio banks, procedural geometry and engine calls. Classify unused experiments
+separately; a cinematic mesh is not automatically the ordinary crowd model. Do not execute
+arbitrary source to discover assets. If runtime extraction is necessary, use an explicitly scoped
+capture with controlled networking/side effects and retain the extraction recipe.
+
+Each feature contract records:
+
+- Stable ID; source files and enclosing symbols; source input hash.
+- Enter/exit state transitions, input gates, pause/cleanup, camera and audio owners.
+- Numeric rules: costs, unlocks, cooldowns, targeting, damage shapes, waves, rewards, loss conditions.
+- Presentation: model variants, animation events, UI behavior, voice/subtitle cues, VFX.
+- Native strategy and dependencies; fidelity category and intentional deviations.
+- A test with explicit inputs and expected outputs/events; independent verification evidence.
+
+Preserve all chapters and tutorial stages, not just an initial playable slice. A result flow that
+returns to the map, selects the next chapter, and waits for the player differs from automatically
+starting the next chapter. Session carry-over differs from account progress after rejoining.
+
+## Translation
+
+Extract tables mechanically. Native Luau is a semantic rewrite for browser/Bitmagic APIs, not
+syntax substitution. Explicitly account for zero/one-based indexes, JavaScript truthiness,
+`undefined`/`null`, Maps/Sets, class initialization, promises, timers and event lifetimes.
+`roblox-ts` cannot provide Three.js, WebGL, DOM/CSS, browser audio or Bitmagic runtime bindings.
+Unknown engine calls become conversion work, not empty stubs or swallowed exceptions.
+
+Use modules with distinct rules, presentation and platform integrations. Stable local events
+such as phase changes, volleys, splash/piercing hits, resource changes and tutorials can connect
+them without becoming network remotes. Preserve event order and single consumption. Keep deliberate
+Roblox extensions in `overrides/` or explicit hooks, with source mappings to the original contract.
+
+## Authority
+
+For a private single-player simulation, local input, placement preview, camera, rules and visuals
+can remain local. Shared world state and consequential multiplayer outcomes need server authority.
+Purchases, ownership and trusted currencies/rewards always need their appropriate server checks.
+Do not grant trusted rewards from client-reported victories. Choose and document a persistence
+trust policy; serializing a client payload does not establish integrity.
+
+Existing target commerce stays intact. Do not add commerce, ads, ownership claims or receipts just
+because a source game is being ported. Preserve coordinated receipt handling and deduplication.
+
+## Coordinates, UI and performance
+
+Use an asymmetric calibration object, floor, forward arrow and known footprint to establish a
+source-to-target basis and scale. Transform normals, winding, negative scales, pivots, animation,
+projectile sockets, ranges, movement and camera distances consistently. Test gameplay facing
+separately from camera facing. One source unit is not automatically one stud.
+
+Map UI intent into native GUI controls, including portraits/icons, safe areas, scrolling,
+controller focus where needed, readable text and touch confirmation. Check the world space left
+visible for placement. Combat should hide construction UI when the contract requires it.
+Use one camera owner per phase and hand over from the rendered pose without snapping/resetting.
+
+Pool transient visuals/audio, bound overlap and allocations, and separate simulation scheduling
+from rendering. Avoid per-enemy scripts, physics bodies and pathfinding for crowds unless required.
+Keep render-step work narrow. Measure before reducing visible density; sampling a small stable
+subset is a disclosed fidelity compromise, not a proven platform limit. Record dropped simulation
+time separately from rendering FPS. Never ship the case study's numeric budgets as universal rules.
+
+Official references, consulted as needed:
+
+- [Client/server runtime](https://create.roblox.com/docs/projects/client-server).
+- [Task scheduler](https://create.roblox.com/docs/performance-optimization/microprofiler/task-scheduler).
+- [Bitmagic coordinate conventions](../../../../engine/agent-docs/coordinate-system.md) when available in the source project; otherwise read its installed engine documentation directly.

package/assets/roblox-port/references/state-contracts.md

@@ -0,0 +1,129 @@
+# Port workspace and helper contracts
+
+The helper bundle is found with `bitmagic tools path roblox-port --json`. Use its returned `path`
+as `<bundle>` below. The normal route executes it in place; `tools install roblox-port` is optional
+and copies helpers into `tools/roblox-port`, never into generated game modules. All helper commands
+are local-only. Inputs/outputs are explicit files; helpers never choose a Studio session.
+
+## Initialize
+
+```text
+node "<bundle>/port-state.mjs" init --source <absolute-bitmagic-project> --project <new-sibling-port>
+```
+
+The source must have a game ID and engine version in `bitmagic.json`. If it lacks an environment,
+provide `--environment` with the confirmed source environment. The output must not exist or nest
+inside the source. Initialization creates stable project/target UUIDs, empty inventories and
+generated/override/test/state directories. Fill the inventories before using them; initialization
+is not a generated or verified game. Existing ports need explicit mapping/adoption, not `init`
+over their files. An empty sibling workspace can hold an adopted port's copied local sources.
+
+Commit `project.json`, `incoming.json`, `port-contract.json`, `assets.lock.json`, generated source,
+overrides, tests and `state/base.json` according to the project's VCS policy. Keep journals and
+recovery snapshots under `.bitmagic/roblox/runs/`; they are ignored for sharing, but retain them
+until recovery is no longer needed. Only conversion cache is disposable. Never store credentials
+in these files, asset recipes, Lua source, tool outputs, or archives.
+
+`project.json` contains schema version 1, immutable managed project/target IDs, source identity,
+runtime profile, and nullable target `placeId`/`universeId` strings. Fill known target IDs before
+applying. A null binding may be used for an explicitly selected unsaved template. Do not store a
+transient Studio session ID as the durable identity. Reconcile later owner-created cloud IDs while
+retaining the managed UUIDs.
+
+## Generated sources
+
+Prepare `incoming.json`:
+
+```json
+{
+  "schemaVersion": 1,
+  "sourceFiles": ["bitmagic.json", "src/work/Game.ts", "src/work/game.json", "src/work/world.json"],
+  "scripts": [
+    {
+      "id": "rules",
+      "path": ["ReplicatedStorage", "BitmagicGame", "Rules"],
+      "className": "ModuleScript",
+      "file": "generated/shared/Rules.luau"
+    },
+    {
+      "id": "client-entry",
+      "path": ["StarterPlayer", "StarterPlayerScripts", "BitmagicGame", "Main"],
+      "className": "LocalScript",
+      "file": "generated/client/Main.client.luau",
+      "enabled": true
+    }
+  ]
+}
+```
+
+Declare **every source file used by conversion**, including imported rules, packed art and audio
+registries, plus relevant engine dependencies. `sourceFiles` is an explicit inventory, not an
+automatic dependency scanner; undeclared changes cannot be detected by the helper. Paths are
+relative to the source root, generated files relative to the port root; escaping symlinks and
+traversal are rejected. Allowed root services are ReplicatedStorage, ServerScriptService,
+ServerStorage, StarterPlayer, StarterGui and Workspace. Use simple generated path segments;
+live creator names, including spaces and Unicode, are preserved by stable ID. Existing
+Folder/Model/StarterPlayerScripts/StarterCharacterScripts containers can hold scripts; missing
+intermediate containers become Folders. Explicitly create special native containers beforehand.
+
+Every Script/LocalScript needs an explicit `enabled`; ModuleScripts omit it. Stable IDs do not
+change when names/paths change. The source helper supports up to 256 scripts, each at most 1 MiB.
+It does not remove omitted scripts, change classes, or reconcile native models/properties.
+Retirement and class migration require a separate backed-up, explicit operation and baseline
+migration. Resolve an unsupported operation instead of hand-editing a prepared plan.
+
+## Feature and asset ledgers
+
+`port-contract.json` has schema version 1 with `features` and `deviations` arrays. Each feature
+needs stable `id`, source files/symbols, `required`, target strategy, fidelity, dependencies,
+test fixture and verification evidence. Accepted differences record the creator's decision and
+affected feature IDs. This is the agent's semantic contract; the source helper does not certify it.
+
+`assets.lock.json` has schema version 1 and `assets`. For each asset record `id`, source path/hash,
+provenance, recipe/version/hash, target owner/type/ID/version, operation ID, moderation, permissions,
+and validation evidence. Store service IDs as strings. Preserve earlier mappings for recovery.
+
+Track native objects/settings outside the script helper in a reviewable scene inventory and
+recipes with expected-value updates and durable before-snapshots. A full game includes this state.
+
+## Plan, apply, accept
+
+See [studio-and-updates.md](studio-and-updates.md) for the exact commands. A run directory contains
+immutable `plan.json` and `before.json` written before Studio mutation, followed by journal and
+readback. The plan binds source/package hashes, target identity, expected live values and baseline.
+Do not edit its hash or values to force a mismatch through. Prepare again after resolving the cause.
+
+`accept` means exact managed source readback passed, **not** gameplay, visuals or performance passed.
+It stores generated values and applied values separately in `state/base.json`; keep both. An
+interrupted forward apply can be replayed from the same plan after inspecting target state, or
+conditionally rolled back. New plans are refused while Studio reports an incomplete run.
+
+Local helper operations use `state/lock`. A stale lock after a killed local process needs inspection:
+verify the owning PID no longer exists and no other task uses the port before removing it. Never
+remove a lock merely because a command is slow. The lock does not prevent human/Team Create edits;
+Studio expected-value checks still apply.
+
+## Save evidence and completion
+
+Record actual tool/manual evidence in a save receipt, never infer it from local source output:
+
+```json
+{
+  "buildId": "the-accepted-plan-hash",
+  "status": "saved",
+  "destination": "confirmed place file or non-published draft destination",
+  "evidence": "actual save operation receipt or verified file evidence",
+  "published": false
+}
+```
+
+```text
+node "<bundle>/port-state.mjs" record-save --project <port> --receipt <save.json>
+node "<bundle>/port-state.mjs" status --project <port>
+```
+
+Statuses are `pending`, `saved`, `unsupported`, `failed`, and `unconfirmed`. The helper validates
+receipt shape/build binding; the agent must obtain genuine evidence. Local `status` reports source
+freshness and recorded save state; it cannot know whether Studio changed since the last readback.
+Reinspect before claiming the current Studio project is unchanged or saved. A new local package
+or accepted build invalidates applicability of older save evidence.

package/assets/roblox-port/references/studio-and-updates.md

@@ -0,0 +1,119 @@
+# Studio connection, source updates, recovery and saving
+
+Discover the connected tools rather than pinning an observed ABI. Typical operations are
+`list_roblox_studios`, `get_studio_state`, hierarchy/source inspection, `multi_edit`, `execute_luau`,
+Play controls, console/input, and captures. Every call targets the selected `studio_id`.
+Studio MCP and Open Cloud authorization are independent. No helper starts its own MCP client.
+
+Use the connected server's schemas and editor-aware reads. Do not assume Script.Source reflects
+an unsaved open buffer. The generated updater requires `ScriptEditorService:GetEditorSource` and
+`UpdateSourceAsync`; unavailable permissions stop it, not trigger a stale-Source fallback.
+Do not paste an entire game into many improvised edits when a reviewed local package is available.
+
+## Inspect and plan
+
+After preparing the local source package:
+
+```text
+node "<bundle>/build-studio-update.mjs" inspect --project <port> --out <new-inspect.luau>
+```
+
+Read that generated code, then execute it through the connected MCP executor in the explicitly
+selected **Edit** context. Save the returned JSON string's contents as `<live.json>`; unwrap the
+tool envelope without editing values. Inspection reads the candidate paths plus managed scripts,
+identity, build and pending-run markers. Duplicate names/IDs and occupied non-script paths fail.
+
+```text
+node "<bundle>/port-state.mjs" prepare --project <port> --live <live.json> --run <new-run-dir>
+```
+
+For the first explicitly selected unbound target add `--bind-target`. This installs the port's
+managed UUIDs on apply, not a cloud identity. It never clears the template. For existing unowned
+scripts, `--adopt` is allowed only after an explicit ownership decision and exact source/class/path/
+enabled matches. First copy their actual editor content into the local package; do not use adoption
+to overwrite a different game. Keep source contract/deviations separate from this ownership baseline.
+
+Review `plan.json`: target/owner, source/package hashes, conflicts, desired values, changed scripts,
+and preserved customizations. No uploads occur. A conflict result exits 2 and produces no applicable
+update. Existing baseline omissions, missing managed objects, foreign path occupants, and divergent
+edits are actionable conflicts. Locate a renamed object by stable ID rather than recreating it.
+
+The plan stores complete affected script text locally. Protect it appropriately. Before altering
+native models, terrain, assets or global settings, prepare separate complete backups and scoped
+expected-value operations; the source helper deliberately does not pretend to cover that content.
+
+## Apply and read back
+
+```text
+node "<bundle>/build-studio-update.mjs" apply --project <port> --run <run-dir> --out <new-apply.luau>
+```
+
+Review and execute that generated Luau in the same selected Edit target. It rechecks target,
+source and hierarchy expectations, stages Script/LocalScript activation, checks editor buffers
+inside update callbacks, and commits the build marker only after all managed sources match.
+Save the returned snapshot as `<after.json>`:
+
+```text
+node "<bundle>/port-state.mjs" accept --project <port> --run <run-dir> --live <after.json>
+```
+
+This advances only the source baseline. It does not run gameplay tests or save the place. Native
+assets/settings must already satisfy the separate scene/asset plan before calling the whole port
+ready. Whole-place atomicity is not provided by Studio MCP or a per-script update callback.
+
+## Interrupted operations
+
+Keep the same run after a timeout. Generate a fresh inspection with `inspect --project <port>
+--run <run-dir> --out <new-inspect.luau>` so recovery reads the durable plan even when local
+conversion inputs are missing or invalid. Inspect its pending marker and
+actual source state, and either replay the existing apply or compensate. A replay accepts only
+expected pre-state or this run's identifiable intermediate writes. An unrelated edit stops it.
+Do not prepare a new baseline from a half-applied game.
+
+Rollback records `rollback:<run-id>` in `BitmagicPendingRun` before restoring anything. While that
+marker remains, new plans and forward replay are blocked; continue the same rollback after resolving
+its conflicts. The marker clears only after successful recovery. Per-script recovery markers let
+that rollback resume a source write interrupted before its ownership/path bookkeeping finished.
+
+```text
+node "<bundle>/build-studio-update.mjs" rollback --project <port> --run <run-dir> --out <new-rollback.luau>
+```
+
+Review and execute the generated recovery only for this run. It restores source/ownership/path/
+enabled state conditionally; later human edits are preserved and reported. New scripts are removed
+only if still attributable to this run, with expected content and no new children. Additional
+attributes, tags, or changes to Archivable, RunContext or LinkedSource preserve the script and
+report a conflict. Empty Folders created by the run also require their recorded original path,
+unchanged attributes/tags and default Archivable state before removal. Missing folder creation
+metadata or unreadable properties require manual recovery. It never deletes imported cloud assets.
+Keep the returned recovery snapshot and resolve any `rollback-incomplete` entries before continuing.
+
+After a successful rollback, restore the matching local accepted baseline from the run's durable
+backup using the returned receipt:
+
+```text
+node "<bundle>/port-state.mjs" accept-rollback --project <port> --run <run-dir> --receipt <rollback.json>
+```
+
+Never leave the local baseline naming the
+reverted build. Cloud versions, purchases and account-data migrations are outside this recovery.
+
+## Saving
+
+After the complete verified game is in Edit state, discover whether a supported MCP operation can
+save the complete place. Confirm its semantics: local file or non-published draft, selected
+destination, no experience publication. Use it when available within the authorized port workflow.
+Reuse an established save destination; ask when one is missing or it would overwrite unrelated work.
+Confirm the result against the installed build and record actual evidence with `record-save`.
+
+Do not infer save privilege from `execute_luau`, invent a save tool, request publishing credentials,
+or call undocumented privileged APIs. If no supported save exists, finish with “ready in Studio;
+save required.” On failure/ambiguous response preserve the project, inspect before retrying, and
+report failed/unconfirmed. Source-only Rojo output and script backups are not complete-place saves.
+
+Leave publishing, visibility and release management to the creator in Studio in every case.
+
+- [Studio MCP](https://create.roblox.com/docs/studio/mcp).
+- [ScriptEditorService](https://create.roblox.com/docs/reference/engine/classes/ScriptEditorService).
+- [Instance attributes, tags and Archivable](https://create.roblox.com/docs/reference/engine/classes/Instance).
+- [BaseScript properties](https://create.roblox.com/docs/reference/engine/classes/BaseScript).

package/assets/roblox-port/references/verification.md

@@ -0,0 +1,63 @@
+# Verify the installed Roblox port
+
+Bind evidence to source/package hashes, live overrides, asset versions, native settings, tool
+versions, and the installed `BitmagicBuildId` attribute. Inspect Edit state before each relevant
+test, then use a fresh Play context. A cached Edit-mode `require` can return old code.
+
+Maintain independent results for:
+
+| Check | Evidence |
+| --- | --- |
+| Source/data | Luau syntax/type checks and complete tables/configurations. |
+| Rules | Fixed inputs and expected outputs/event sequences; defined numeric tolerances. |
+| Native integration | Fresh correct Client/Server contexts, build marker, clean console, working dependencies. |
+| Visual/input | Valid observed views/UI interactions at recorded desktop/touch viewports. |
+| Performance | Named hardware, quality, resolution, foreground state, duration and representative load. |
+| Saved | Confirmed complete-project save receipt/file evidence for this build, if supported. |
+
+An earlier row does not imply later rows passed. Test stubs are not Roblox rendering, input,
+replication, asset moderation or audio. Do not enable unsafe runtime `loadstring` to run tests.
+Explicit owner inspection can provide manual evidence. Missing checks remain unverified, not green.
+
+## Minimum player-journey contract
+
+Derive concrete cases from the source inventory, including later progression:
+
+- Title, briefing, map/level selection, build/play, combat, results, return, defeat/retry and replay.
+- Every tutorial stage, legal/illegal actions, affordability/recovery, unlock and start gating.
+- Rule tables, specialized enemies/abilities, damage boundaries, rewards and single payouts.
+- Repeated full cycles: no duplicate input handlers, stale UI/audio/camera ownership or accumulating instances.
+- Persistence across sessions/rejoining when required; session carry-over alone is not persistence.
+- Required icons, mesh identities/materials, correct scale/grounding, pivots/sockets and animation timing.
+- Feedback that communicates mechanics: splash radius, piercing corridor, attacks and meaningful impact.
+- Desktop, portrait phone and short landscape: safe areas, text, scrolling, touch confirmation,
+  placement visibility, selected controls, pause/music and controller focus where supported.
+- Existing target-only commerce/customization stays intact; inspect cancellation/unknown ownership,
+  receipt deduplication and rejoin behavior if those integrations are part of the port.
+
+Use public UI for a short smoke journey. Test hooks may accelerate long scenarios, but label them
+and exclude temporary cheats/fixtures from the final Edit project. Poll a bounded ready/build marker
+instead of arbitrary sleeps. Stop bounded retries and preserve the last error when evidence fails.
+
+Do not assume JavaScript PRNG streams match Roblox Random. Specify shared deterministic decisions
+or compare exported fixtures. Counts of simulated actors differ from the number actually rendered.
+Report sampling and visible role representation; reducing density requires a disclosed decision.
+
+Profile cold load, mass spawn, collision/contact, peak VFX/audio, boss cases, and repeated returns.
+Record frame-time distributions, simulation and presentation CPU costs, memory/instance/connection
+growth, asset stalls and relevant traffic separately. A headless rules benchmark is not FPS.
+Background-throttled Studio measurements cannot certify foreground or mobile performance.
+
+## Captures and handoff
+
+Check that a screenshot is the intended build/view and includes the GUI under test. Reject blank,
+magenta, locked-screen, wrong-session or missing-overlay evidence. When MCP capture cannot observe
+the UI, give the creator a precise view/action to inspect rather than claiming it passed.
+
+After tests, return task-started Play to Edit and ensure all required content lives there. Remove
+temporary fixtures, disable test hooks, and stop task-owned servers/children/ports. Leave unrelated
+processes and Studio open. Save through a supported MCP operation if available and report its status.
+
+Completion is a complete game ready in Studio with required checks/deviations accounted for.
+Published-client testing, cloud release and public availability are the creator's subsequent
+workflow. Never turn “not published yet” into a reason to add publishing automation.