Game Bridge v0.2: prompt → spec → playable preview → export

[zedarvates]

Outcome

Close the largest product-UX gap identified after comparing StoryCore with prompt-to-game builders: turn a short prompt into a reviewable public game specification, launch an explicit local playable preview, then create a deterministic source export.

Target flow:

prompt + bounded options -> editable draft spec -> strict validation -> trusted local Godot preview -> deterministic export

This is a separate v0.2 slice. Do not expand or merge draft PR #44 as part of this issue.

Dependency and promotion gate

• Builds on the public contract and original Godot fixture in feat(game-bridge): add deterministic StoryCore-to-Godot contract fixture #44.
• Implementation must wait for feat(game-bridge): add deterministic StoryCore-to-Godot contract fixture #44's remaining human public/private boundary review.
• feat(game-bridge): add deterministic StoryCore-to-Godot contract fixture #44 stays draft; this issue authorizes neither merge nor release.
• Resolve or explicitly adjudicate the repository metadata mismatch (LICENSE: MIT, package.json: ISC) before distributing an export as a release artifact.

Public architecture

Reuse the existing desktop shell instead of creating a second application:

• React workspace under creative-studio-ui/src;
• Electron IPC for local filesystem and process boundaries;
• src/game_bridge remains the validating/compiling authority;
• Godot remains a non-authoritative consumer of the compiled manifest.

The first public drafting adapter is deliberately bounded and honest:

• local-template converts a prompt plus explicit fields (locales, title, world, actor, drop-loop parameters) into contract v0.1;
• it supports the original rune-drop fixture family only;
• identical normalized input produces identical draft/evidence;
• any future model/provider adapter is replaceable and its output is treated as untrusted until strict contract validation passes.

No claim of general text-to-any-game generation is allowed in v0.2.

UX states

1. Describe — prompt, locales and bounded gameplay options.
2. Review — editable structured fields plus JSON view.
3. Validate — exact field-path errors; never silently repair or discard unknown data.
4. Preview — user-triggered launch with a user-selected trusted Godot 4 executable.
5. Export — reproducible source bundle with specification, manifest, evidence and Godot project.

Browser-only mode may validate and export but must clearly explain that local playable preview requires the desktop shell.

Security and authority rules

• no credentials, accounts, billing, hosted inference or network publishing;
• no private commercial server, internal orchestration, reasoning modules, algorithms or provider adapters;
• never pass user input through a shell command;
• spawn the trusted Godot executable with a fixed argument vector, timeout and bounded log capture;
• keep input/output under an explicitly selected workspace; reject traversal and symlink escapes;
• treat the Godot process and all generated/model output as non-authoritative;
• no automatic execution of downloaded projects;
• no public-fork code on self-hosted runners carrying personal, signing, deployment or production credentials;
• production authority may connect later only through the public external-contract boundary.

Deterministic export

Export a source-only bundle containing:

• storycore_game_spec.json;
• storycore_game_manifest.json;
• storycore_game_evidence.json;
• the public Godot template;
• an export manifest with file paths, SHA-256 digests, contract/compiler version and declared license.

Use stable file ordering, normalized line endings and normalized archive timestamps. Do not bundle Godot binaries, model weights, generated private media or third-party assets.

Acceptance criteria

• one bilingual prompt completes Describe -> Review -> Validate -> Preview -> Export;
• the resulting spec passes the strict feat(game-bridge): add deterministic StoryCore-to-Godot contract fixture #44 compiler without coercion;
• invalid/unknown fields produce actionable path-specific errors;
• the same normalized inputs produce byte-identical spec, manifest, evidence and export digest;
• Electron preview uses no shell and rejects untrusted executable/workspace paths;
• the preview verifies the embedded manifest hash before play;
• automated full-quest smoke prints STORYCORE_GAME_SMOKE_PASS;
• exported files contain no credential, private component, provider implementation or third-party asset;
• UI tests cover keyboard flow, validation focus and EN/FR strings;
• IPC/path tests cover absolute paths, .., unexpected characters and symlink escapes;
• an isolated trusted Godot run confirms import, parse and full-quest smoke;
• a human reviewer signs off the public/private boundary;
• MIT/ISC repository metadata is reconciled before release.

Non-goals

• general-purpose AI game generation;
• automatic repair loops, autonomous agents or hidden prompt rewriting;
• embedded web export, hosting, deployment or marketplace publishing;
• multiplayer/MMO/server authority;
• asset generation, 3D reconstruction or provider benchmarking;
• temporal/VLM video validation, which remains tracked separately in StoryCore: preview-time temporal validator and Dhee architecture audit #38.

Exit condition

A new user can enter a bounded game prompt, inspect every generated field, obtain explicit validation evidence, play the local fixture, and export a reproducible source bundle without an account, network call, private backend or proprietary component.

[zedarvates]

Implementation blueprint — prepared without starting code

This plan is intentionally preparatory. It does not complete #44's human boundary review, create a branch/PR, or authorize a merge.

Product audience

This workspace is for StoryCore's direct users — creators, independent developers, studios and production structures. The playable Godot preview is a production proof for those customers, not a player-facing StoryCore product and not an Ultimate Odycer client.

Reuse / isolate decision

Reuse these existing UI primitives:

• WizardStepIndicator, WizardNavigation, ValidationDisplay and LiveRegion;
• the existing React routing shell;
• LanguageContext.currentLanguage as the selected locale;
• the strict Python contract from feat(game-bridge): add deterministic StoryCore-to-Godot contract fixture #44 as the only authoritative validator/compiler.

Do not make #45 depend on the application's broad, generic process or filesystem IPC surfaces. Add a narrow, feature-specific boundary instead. Any review of pre-existing generic IPC belongs in a separate non-public security workflow.

BaseWizard can inform step behavior, but should not be used unchanged: its review is a raw <pre>, several labels are hard-coded in English, and its completion/autosave model does not match authoritative spec validation. Existing media export is also unsuitable because it includes wall-clock values and placeholder behavior rather than reproducible Game Bridge evidence.

For v0.2, keep the creative prompt in memory and persist it only after an explicit user action. Do not inherit mixed legacy draft-storage behavior implicitly.

Narrow runtime surface

Expose only a dedicated preload API:

gameBridge.draft(request)
gameBridge.validate(spec)
gameBridge.preview({ workspacePath, godotExecutablePath })
gameBridge.export({ spec, workspacePath, destinationPath })
gameBridge.stopPreview()

The renderer must never select executable operations, process arguments, working directories or environments.

Add a separate Electron service/registration module:

• electron/services/GameBridgeService.ts
• electron/gameBridgeIpc.ts
• small registration/disposal calls in electron/main.ts
• narrow declarations in electron/preload.ts, electron/electronAPI.d.ts and creative-studio-ui/src/types/electron.ts

Python authority

After #44 is human-approved and integrated, add:

• src/game_bridge/draft.py — deterministic local-template adapter;
• src/game_bridge/export.py — source-only deterministic bundle;
• src/game_bridge/desktop_cli.py — one-shot, bounded JSON request/response over stdin/stdout;
• focused tests under tests/game_bridge/.

The Electron service chooses from fixed actions. Prompt/spec data travels over stdin, never process arguments or logs. Suggested limits:

• request <= 128 KiB;
• response/log capture <= 1 MiB;
• draft/validate timeout 10 s;
• export timeout 30 s;
• Godot version probe timeout 5 s;
• interactive preview has an explicit Stop control and an upper lifetime bound.

The public local-template is not an LLM and must not pretend to understand arbitrary prose. It combines a short creative brief with explicit localized fields and the rune-drop preset. Any unsupported meaning remains visible for user editing. It performs no translation and no silent repair. Future provider output remains untrusted input to the same strict contract.

Store only prompt_sha256 in generation evidence by default; do not copy the prompt into logs or provenance unless the user explicitly exports it.

Deterministic export

Generate the archive in Python with standard-library zipfile, using:

• ZIP_STORED to avoid compression-library drift;
• lexicographically sorted paths;
• UTF-8 and LF normalization for generated text;
• fixed ZIP timestamps and fixed file mode;
• an allowlisted public template only;
• SHA-256, byte size, contract/compiler version and declared license for every file;
• no symlinks, binaries, model weights, generated private media or third-party assets.

The browser fallback may perform advisory form validation and export a clearly labelled draft JSON. It must not claim authoritative compilation, runnable preview or verified deterministic bundle; those require the desktop/Python boundary.

UI file plan

Create an isolated feature folder:

• creative-studio-ui/src/pages/GameBridgePage.tsx
• creative-studio-ui/src/components/game-bridge/GameBridgeWizard.tsx
• DescribeStep.tsx, ReviewStep.tsx, ValidateStep.tsx, PreviewStep.tsx, ExportStep.tsx
• creative-studio-ui/src/services/gameBridgeService.ts
• creative-studio-ui/src/types/gameBridge.ts
• creative-studio-ui/src/components/game-bridge/gameBridgeI18n.ts
• focused component/service tests.

Add one route, /game-bridge. Keep game-specific EN/FR strings in a pure tested dictionary for v0.2; do not claim French support until switching is proven by tests.

Process and path controls

• no shell mediation; fixed executable operations and arguments only;
• lstat + realpath + root containment before every read/write;
• reject absolute user-supplied subpaths, .., unexpected characters and every symlink component;
• fixed output filenames and atomic temp-file replacement;
• user explicitly selects the Godot executable;
• probe --version, require Godot 4.x, hash the executable and show the digest before first launch;
• preview only an export created inside the selected workspace;
• scan bounded logs for SCRIPT ERROR / ERROR: and require the smoke marker for acceptance evidence;
• never run this public code on a secrets-bearing self-hosted runner.

Test matrix

1. Python: deterministic draft/spec/evidence/export; malformed JSON; oversize input; locale completeness; unknown fields; path and symlink negatives.
2. Electron: fixed-operation boundary; executable/workspace validation; timeout/stop; output caps; path race regressions.
3. React: keyboard-only five-step flow; validation focus; EN/FR; browser capability messaging; no silent repair; explicit prompt persistence/export.
4. Synthetic process fixture: exercise timeout/log/error IPC only and label it synthetic.
5. Real runtime gate: official trusted Godot import, parse and full-quest smoke; mocks never count as compatibility proof.
6. Reproducibility: two clean runs produce byte-identical spec, manifest, evidence and archive digest.
7. Boundary: secret/private-component scan plus human review.

PR decomposition after the gate

1. Python local-template + deterministic export.
2. Dedicated Electron IPC/service boundary.
3. React five-step workspace + EN/FR + end-to-end evidence.

Each should be a separate draft PR with no implicit merge. Do not stack them onto #44 by default.

Additional blocker

Repository license metadata consistency is now isolated in #46. It blocks release packaging but should not broaden #44 or the first implementation PR.