Add Stagehand stages, fix viewport capture, extend the Chronicle

[ShaalaXIV]

Four changes. All additive to the wire contract, so ApiRoutes.ProtocolVersion is unchanged.

Stagehand stages on beacons

A keeper attaches the Stagehand stage they dressed a place with; guests who run Stagehand can see the camp as it was built rather than an empty field.

Beacon talks to Stagehand over Dalamud IPC by channel name rather than linking its API library. Every call it needs takes and returns primitives, so this costs nothing in capability — and it keeps a licence boundary between the two projects (both Stagehand packages are AGPL-3.0) instead of pulling one into the other.

The guest decides. Nothing loads silently the first time: the beacon page offers the stage and remembers the answer per beacon. Auto-loading everything is a setting, off by default. Every stage is created as a Stagehand temporary stage, so nothing is written into a guest's own library and refusing later leaves nothing behind.

The server treats a stage as an opaque document — it reads only what a guest needs in order to decide, and refuses the two shapes that cannot work for anybody but their author: over the 2 MB cap, and modpacks that load files from the author's own disk.

Stage definitions live beside the images under the data directory, and deploy/backup.sh now captures them.

Photographs

Capture never worked. ImGuiViewportTextureArgs.ViewportId was left at zero, and the main viewport's id is a hash that can only be read inside a draw callback; Uv0/Uv1 were also unset, which describes an empty rectangle. The id is now recorded once a frame and passed at the point of use.

The game's interface is hidden while the shutter is open and given time to finish fading, so a photograph is of the scene rather than the HUD. Both configurable.

The Chronicle

The part of a card that is true today rather than true in general:

• Currently — the live IC line, carrying its own timestamp so the card shows its age. Saving a biography no longer makes a month-old line look freshly written.
• In character / out of character flag.
• Out of character note — the player speaking as themselves.
• At first glance — five label-and-line slots for what a stranger notices before a word is exchanged.

The live line has its own route and its own commands: /beacon currently, /beacon ic, /beacon ooc. A field that takes three clicks to change is written once and never again.

Example content

Removed the placeholder names, epithets, quotes and boundaries from the profile and beacon editors. The hints now describe their field instead of filling it.

Migrations

Two, both additive: AddBeaconStages and AddChronicleMoment. They apply on the next server start.

Verification

• Full solution builds clean in Release; tools/contrast-audit.py passes.
• Stage upload exercised end to end against a local server with a real 21-object stage: metadata parsed, definition round-tripped byte-identical, and empty / malformed / disk-backed stages each refused with a usable message.
• Chronicle endpoints exercised end to end: empty glance slots dropped, over-long lines truncated, clearing the live line clears its timestamp, and a full card save leaves the live line's age untouched.
• Local test database and uploads purged afterwards.

Not verified without the game: whether Stagehand accepts the raw stage JSON as its definition string. ToDefinitionString uses different JsonSerializerOptions than the file format, and there is no base64 or compression wrapper in Stagehand.Definitions.dll — only per-resource compression inside the JSON — so it should parse. If not, the failure surfaces as "Stagehand could not read that stage" rather than anything worse.

🤖 Generated with Claude Code