feat(events): an event action's progress() on a live run's public page (MODULE_API 1.12.0) #210

wtclaude · 2026-10-06T07:47:27Z

wtclaude commented

2026-10-06 07:47:27 +00:00

What

Core's half of RunicNPC stage 8 (D304, D305; design in docs#321). An event action may declare an optional progress(envelope): how its step stands while the run is live. Core accepts two shapes and interprets neither:

{ label, left, of }, rendered "Bandits: 3 of 8 left";
{ label, percent }, rendered "The Juggernaut: 62%".

How it works:

The new file, server/src/events/progress.js. It asks each step of a live run whose action has progress. The call gets the step's own held ledger rows and the reader as { userId }, so the module applies its own visibility settings.
- Each call has a 2 s deadline.
- A throw, a late answer or any other shape is a line not shown (logged), never an error on the page.
- One answer per run and reader is cached for 5 s.
The public event. The live occurrence (current) carries the lines as progress. GET /public/events/:slug now takes an optional session (optionalAuth).
The page. EventPage.jsx renders the lines under the phase label and re-reads them every 15 s while the event is live, without reloading the page.
The registry. progress is optional and must be a function. It is stripped from the admin catalog with the other callables.

D305, the org lead's condition: core stays game-agnostic and UO must not break.

No game's words are in core.
Module-uo declares ^1.10.0 and registers no action with progress, so its actions and pages are unchanged. The swagger generator loaded the installed UO module (v0.6.0) against this core without complaint.
The bump is minor (1.11.0 → 1.12.0) and additive.
The integration kit's coreApi equality check goes red when its pin moves to this core, by design.

Also regenerated:

engagement-triggers.json: every MODULE_API bump changes its embedded version.
routes.guards.json: optionalAuth on the one route. The URL manifest is unchanged.
The OpenAPI spec: the PublicEventProgressLine schema.

Docs: MODULE_API.md 1.12.0 and EVENTS.md §I will follow in the stage 8 docs PR. They are not in this PR.

Tested

Server: the new eventProgress.test.js covers the two shapes, the deadline, a throw, a dead database, per-step rows, the reader, and the cache. Also added: a registry test (optional, stripped from the catalog) and a public-model test (only the live occurrence carries progress, asked for the reader). The pinned version moved to 1.12.0.
Full server suite: 2077 pass, 0 fail after the fix below.
- The only failures were the two route-manifest checks, plus the engagement manifest until it was regenerated.
- The route checks fail on pristine main on this machine, because website/modules/ holds the installed rust and uo modules.
- With MODULES_DIR pointed at an empty directory (CI's view), the manifest, engagement and event tests pass 97/97.
Client: builds; 401 tests pass, including progressText.

Checklist

I have read CONTRIBUTING.md.
OpenAPI spec regenerated.
AI tools were used. Tool(s): Claude Code (Claude Opus 5.5). The commit carries the Co-Authored-By trailer.
I agree that my contribution is licensed under GPL-3.0-or-later.

🤖 Generated with Claude Code

https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY

## What Core's half of RunicNPC stage 8 (D304, D305; design in docs#321). An event action may declare an optional **`progress(envelope)`**: how its step stands while the run is live. Core accepts two shapes and interprets neither: - `{ label, left, of }`, rendered "Bandits: 3 of 8 left"; - `{ label, percent }`, rendered "The Juggernaut: 62%". **How it works:** - **The new file, `server/src/events/progress.js`.** It asks each step of a live run whose action has `progress`. The call gets the step's own held ledger rows and the reader as `{ userId }`, so the module applies its own visibility settings. - Each call has a 2 s deadline. - A throw, a late answer or any other shape is a line not shown (logged), never an error on the page. - One answer per run and reader is cached for 5 s. - **The public event.** The live occurrence (`current`) carries the lines as `progress`. `GET /public/events/:slug` now takes an optional session (`optionalAuth`). - **The page.** `EventPage.jsx` renders the lines under the phase label and re-reads them every 15 s while the event is live, without reloading the page. - **The registry.** `progress` is optional and must be a function. It is stripped from the admin catalog with the other callables. **D305, the org lead's condition:** core stays game-agnostic and UO must not break. - No game's words are in core. - **Module-uo** declares `^1.10.0` and registers no action with `progress`, so its actions and pages are unchanged. The swagger generator loaded the installed UO module (v0.6.0) against this core without complaint. - The bump is minor (1.11.0 → 1.12.0) and additive. - The integration kit's `coreApi` equality check goes red when its pin moves to this core, by design. Also regenerated: - `engagement-triggers.json`: every MODULE_API bump changes its embedded version. - `routes.guards.json`: `optionalAuth` on the one route. The URL manifest is unchanged. - The OpenAPI spec: the `PublicEventProgressLine` schema. **Docs:** `MODULE_API.md` 1.12.0 and `EVENTS.md` §I will follow in the stage 8 docs PR. They are not in this PR. ## Tested - **Server:** the new `eventProgress.test.js` covers the two shapes, the deadline, a throw, a dead database, per-step rows, the reader, and the cache. Also added: a registry test (optional, stripped from the catalog) and a public-model test (only the live occurrence carries `progress`, asked for the reader). The pinned version moved to 1.12.0. - **Full server suite:** 2077 pass, 0 fail after the fix below. - The only failures were the two route-manifest checks, plus the engagement manifest until it was regenerated. - The route checks fail on pristine `main` on this machine, because `website/modules/` holds the installed rust and uo modules. - With `MODULES_DIR` pointed at an empty directory (CI's view), the manifest, engagement and event tests pass 97/97. - **Client:** builds; 401 tests pass, including `progressText`. ## Checklist - [x] I have read CONTRIBUTING.md. - [x] OpenAPI spec regenerated. - [x] AI tools were used. Tool(s): `Claude Code (Claude Opus 5.5)`. The commit carries the `Co-Authored-By` trailer. - [x] I agree that my contribution is licensed under GPL-3.0-or-later. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY

wtclaude added 1 commit 2026-10-06 07:47:29 +00:00

feat(events): an event action's progress() on a live run's public page (MODULE_API 1.12.0)

PR Checks / bot-tests (pull_request) Successful in 38s

Details

PR Checks / client-build (pull_request) Successful in 49s

Details

PR Checks / server-tests (pull_request) Successful in 20m42s

Details

9ddb59a326

An event action may declare an optional `progress(envelope)`: how its
step stands while the run is live. Core accepts two shapes and
interprets neither:

- a count: { label, left, of }, rendered "Bandits: 3 of 8 left";
- a percentage: { label, percent }, rendered "The Juggernaut: 62%".

How core asks:

- `events/progress.js` asks each step of a live run whose action has
  one. It passes the step's own held ledger rows and the reader's
  account id, so the module applies its own visibility.
- Each call has a 2 s deadline. A throw, a late answer or any other
  shape is a line not shown, never an error on the page.
- One answer per run and reader is cached for 5 s.
- The public event's live occurrence carries the lines as `progress`.
  The route takes an optional session for the reader.
- The page renders them under the phase label and re-reads them every
  15 s while the event is live.

Core stays game-agnostic: no game's words are in it. Additive, so a
minor bump. Module-uo declares ^1.10.0, registers no action with
progress(), and its actions and pages are unchanged.

From RunicNPC stage 8 (D304, D305).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY

whitlocktech approved these changes 2026-10-06 12:58:45 +00:00

whitlocktech merged commit 0a37a44164 into main

2026-10-06 12:59:01 +00:00

whitlocktech deleted branch feat/events-action-progress

2026-10-06 12:59:02 +00:00

whitlocktech referenced this issue from a commit

2026-10-06 12:59:03 +00:00

Merge pull request 'feat(events): an event action's progress() on a live run's public page (MODULE_API 1.12.0)' (#210) from feat/events-action-progress into main

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: RunicGateway/website#210