# HyperTwist Phase 8B browser-client spec/evidence hardening packet

Created on `2026-06-19`

## Status

- first-party HyperTwist packet
- bounded spec/evidence `Phase 8B` continuation slice
- no implementation widening is granted by this packet

## Purpose

This packet tightens the already-frozen optional full-browser client branch
into a more implementation-ready first-party seam without reopening product
topology.

The granted slice is:

- define the concrete first-party seam families a later browser client would
  use above Unreal backend authority
- ground those seam families in the current first-party browser bridge
  vocabulary where that vocabulary is transport-neutral
- define reconnect, stale-state, offline, and packaging posture explicitly
- add go or no-go criteria that a later implementation packet must satisfy

It is not:

- a replacement for the current embedded browser/CEF shipping posture
- permission to start browser-client runtime implementation
- a browser-first authority inversion over puzzle or training state
- a native `MagicTile` renderer packet
- a renderer-port widening packet of any kind

## Current authority basis

This continuation packet stands on:

- `docs/ops/HYPERTWIST_COMPREHENSIVE_RECONSTRUCTION_ROADMAP_2026-06-10.md`
- `docs/v6_5_deep_manual_pack/HyperTwist/ROADMAP.md`
- `docs/v6_5_deep_manual_pack/HyperTwist/ARCHITECTURE.md`
- `docs/v6_5_deep_manual_pack/HyperTwist/FEATURE_REGISTRY.md`
- `docs/ops/HYPERTWIST_IMPLEMENTATION_PHASE_1_KICKOFF.md`
- `docs/arch/HYPERTWIST_PHASE8B_OPTIONAL_FULL_BROWSER_CLIENT_HTTP_BACKEND_PREPARATION_PACKET_2026-06-19.md`
- `docs/arch/HYPERTWIST_PHASE8A_EMBEDDED_BROWSER_RUNTIME_HARDENING_IMPLEMENTATION_PACKET_2026-06-19.md`
- `docs/arch/HYPERTWIST_PHASE8A_BROWSER_STATUS_SURFACE_HARDENING_IMPLEMENTATION_PACKET_2026-06-19.md`
- `docs/arch/HYPERTWIST_PHASE7D_MAGICTILE_RENDERER_PORT_DECISION_PACKET_2026-06-19.md`

## Current evidence basis

The current lane evidence now supports a tighter spec posture:

- the landed shipping browser posture remains the embedded browser/CEF shell
  through `UHyperTwistBrowserWidget` and `Content/Browser/index.html`
- the embedded browser lane now has deterministic runtime-ready queue
  ownership, shared boot-state ownership, and explicit runtime-status
  surfacing across bundled and fallback shells
- the primary reverse-SSH Windows lane most recently rebuilt the browser slice
  on `2026-06-19` with `Result: Succeeded` and UnrealBuildTool
  `Total execution time: 160.16 seconds`
- the same lane passed all `7` `HyperTwist.Browser.*` tests on `2026-06-19`,
  including the status-surface artifact coverage
- the adjacent `Phase 7D` renderer-port gate still remains explicit `No-Go`,
  so this packet must not blur browser-client branching into native renderer
  widening

## Canonical seam families

If a later optional browser client is separately approved, it must stay inside
these first-party seam families:

| Family | Direction | Minimum first-party responsibility |
| --- | --- | --- |
| Catalog | browser client -> Unreal backend | list puzzles, families, launchable modes, and supported browser-capable surfaces |
| Session | browser client -> Unreal backend | create, resume, end, and inspect authoritative training or puzzle sessions |
| Action submission | browser client -> Unreal backend | submit twists, training actions, or bounded UI-intent commands without moving puzzle authority to the browser |
| State snapshot | Unreal backend -> browser client | deliver authoritative puzzle, training, timer, and view-state snapshots |
| Continuity push | Unreal backend -> browser client | push timer, replay, run-phase, and training continuity updates when push transport is enabled |
| Replay | browser client <-> Unreal backend | query replay metadata, request playback state, and persist owned replay records |
| Persistence status | Unreal backend -> browser client | expose authoritative save, restore, or validation outcomes |
| Runtime health | either direction | report browser readiness, backend reachability, and bounded diagnostic status |

## Transport-neutral vocabulary

Where a later browser client can reuse already-owned vocabulary, it should do
so rather than inventing a parallel contract family.

The currently acceptable transport-neutral message families are:

- `hypertwist-command`
- `hypertwist-shell-state`
- `hypertwist-state`
- `hypertwist-command-result`
- `hypertwist-runtime-ready`
- `browser-runtime-status`

Interpretation rule:

- these names may be reused over HTTP, WebSocket, SSE, or another first-party
  transport only when the meaning remains transport-neutral and first-party
  owned
- they must not be treated as permission to inherit donor/browser-runtime
  internals directly

## Authority boundaries

If later implemented, the browser client may own:

- rendering and presentation
- local layout and interaction composition
- ephemeral UI-only selection or hover state
- bounded client-side buffering for display continuity

It must not own:

- authoritative puzzle legality or mutation
- authoritative training run lifecycle
- authoritative timer continuity
- authoritative replay truth or persistence
- backend save acceptance or recovery decisions

## Failure and reconnect posture

The optional browser-client branch is explicitly not an offline-first branch.

The later implementation posture must therefore remain:

- browser-side queued intent may exist only as a volatile UX aid
- reconnect must rehydrate from an authoritative Unreal snapshot before the
  browser client is treated as current again
- stale or disconnected browser state must be visibly marked as stale
- no browser-side conflict resolution, merge arbitration, or authority
  promotion is granted by default
- offline-first mutation queues remain deferred until separately specified

## Packaging and deployment posture

This branch remains optional and non-default.

A later implementation packet may define:

- a local companion browser package
- a developer-facing browser-hosted validation lane
- a bounded local-network or loopback backend posture

It still may not implicitly define:

- the new default shipping posture
- public-hosted auth or account rollout
- backend multitenancy
- a replacement for the current embedded browser lane

## Go or no-go criteria for future implementation

No later browser-client implementation packet should open unless all of these
are true:

1. the slice stays explicitly above Unreal backend authority
2. the slice names exactly which seam families it is implementing
3. any reused browser vocabulary remains transport-neutral and first-party
   owned
4. timer, replay, and training continuity are not reduced below the current
   embedded browser posture
5. the packet does not try to bundle native renderer widening or `MagicTile`
   host replacement into the browser-client branch
6. validation scope is named in advance for browser, backend, and packaging
   behavior rather than inferred after implementation

Default verdict until a later packet satisfies those criteria:

- `Deferred but valid as an optional first-party branch`

## Explicit deferrals

This packet keeps the following deferred:

- live browser-client runtime code
- backend auth and account posture
- offline-first reconciliation
- public deployment posture
- native renderer widening
- donor-backed browser topology inheritance

## Validation target

Validate this packet through doc-consistency only:

1. the preparation packet, roadmap, architecture, kickoff note, and feature
   registry must agree on the new seam vocabulary and deferred posture
2. no Unreal build claim is required for this spec-only packet
3. no browser-client implementation claim may be inferred from this document

## Queue effect

If this packet lands cleanly:

- the optional browser-client branch becomes more concrete without becoming
  active implementation
- later browser-client work can be scoped against explicit seam families
  instead of restating authority from scratch
- the branch remains cleanly separate from native renderer decisions and the
  landed embedded browser shipping posture
