kaizen-agent 1.70.0 → 1.71.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2 -2
- package/cli/annotate-proxy.ts +5 -0
- package/cli/automations.ts +10 -3
- package/cli/browser.ts +1 -1
- package/cli/chat.ts +9 -1
- package/cli/chatgpt.ts +2 -1
- package/cli/docs.ts +1 -1
- package/cli/google.ts +2 -1
- package/cli/handoff.ts +1 -1
- package/cli/install.ts +28 -8
- package/cli/knowledge.ts +1 -1
- package/cli/notes.ts +10 -1
- package/cli/settings.ts +5 -1
- package/cli/sources.ts +3 -2
- package/cli/state.ts +43 -5
- package/cli/versions.ts +1 -1
- package/cli/video.ts +1 -1
- package/cli/web.ts +43 -27
- package/cli/workers.ts +20 -7
- package/cli/worktree.ts +55 -15
- package/package.json +1 -1
- package/skills/kaizen/SKILL.md +12 -8
- package/skills/kaizen/config.default.yml +18 -2
- package/skills/kaizen/settings.md +3 -1
- package/skills/kaizen/spec-build.md +13 -2
- package/skills/kaizen/spec-main.md +2 -0
- package/skills/kaizen-help/SKILL.md +1 -0
- package/skills/media/kaizen-game/SKILL.md +96 -0
- package/skills/media/kaizen-game/assets/gdd.css +12 -0
- package/skills/media/kaizen-game/references/build.md +81 -0
- package/skills/media/kaizen-game/references/content.md +32 -0
- package/skills/media/kaizen-game/references/design.md +81 -0
- package/skills/media/kaizen-game/references/ship.md +34 -0
- package/skills/media/kaizen-game/references/verify.md +33 -0
- package/skills/media/kaizen-game/scripts/check.sh +13 -0
- package/skills/media/kaizen-game/scripts/frames.mjs +34 -0
- package/skills/media/kaizen-game/scripts/gdd-pdf.mjs +19 -0
- package/skills/media/kaizen-game/scripts/pw.mjs +18 -0
- package/skills/media/kaizen-game/scripts/serve.mjs +53 -0
- package/skills/media/kaizen-game/scripts/serve.test.mjs +18 -0
- package/skills/media/kaizen-game/scripts/setup.sh +9 -0
- package/skills/media/kaizen-game/scripts/smoke.mjs +40 -0
- package/skills/media/kaizen-game/skill.json +1 -0
- package/web/board/icebox.ts +6 -3
- package/web/board/markdown.ts +7 -2
- package/web/board/run-view.ts +1 -1
- package/web/board/settings-orchestration.ts +1 -1
- package/web/board/settings-pages.ts +1 -0
- package/web/board/settings-skills.ts +1 -0
- package/web/board/settings.ts +2 -2
- package/web/board.js +70 -70
- package/web/notebook.js +1 -1
- package/web/term.js +48 -48
- package/web/term.ts +16 -4
- package/web/video.js +1 -1
|
@@ -30,8 +30,10 @@ nearest first, so a change lands globally unless this project keeps its own conf
|
|
|
30
30
|
| `git.rebuild_on_land` | text | Command that remakes generated files after they were resolved |
|
|
31
31
|
| `git.land_check` | `auto`, `off`, or a command | Runs after a rebase that pulled commits; a failure stops the land |
|
|
32
32
|
| `ui.mouse` | `false`, `true` | Click to select, click again to act; while on, the terminal cannot select text |
|
|
33
|
-
| `agent.model.<tool>` | the tool's own model name, or empty | Launch model
|
|
33
|
+
| `agent.model.<tool>` | the tool's own model name, or empty | Launch model per tool. agy, codex, gemini, opencode run every stage on it; for claude it is the main session, which stage subagents on `inherit` follow |
|
|
34
|
+
| `agent.handoff_model.<tool>` | the tool's own model name, or empty | Model of the second agent a worktree run hands build, review and the fix loop to; empty is the run's own model |
|
|
34
35
|
| `subagents.model` | `inherit`, `opus`, `sonnet`, `haiku` | Model the stage subagents run on (Claude Code only) |
|
|
36
|
+
| `subagents.planner`, `subagents.builder`, `subagents.reviewer` | `default`, `opus`, `sonnet`, `haiku` | One stage on its own model, ahead of `subagents.model`; the builder also runs the fix rounds, the reviewer the rechecks (Claude Code only) |
|
|
35
37
|
| `subagents.effort` | `inherit`, `low`, `medium`, `high` | Reasoning effort for the stage subagents (Claude Code only) |
|
|
36
38
|
| `sources.every` | `off`, `1h`, `6h`, `24h` | How often the web board checks request sources for new requests, into the icebox, while it runs |
|
|
37
39
|
| `sources.agent` | `ask`, `chatgpt`, `agent` | Who picks the posts that fit from social sources when Gather is pressed: the ChatGPT plan signed in from the Icebox, or your agent on `/kaizen gather` |
|
|
@@ -55,7 +55,8 @@ code in the same folder. If `kaizen worktree start` fails, say why and stop; do
|
|
|
55
55
|
back to the project folder unasked. A run whose `state.json` has no `worktree` builds in
|
|
56
56
|
place, exactly as before.
|
|
57
57
|
|
|
58
|
-
**Hand the build to a second agent, when the run gets a worktree.**
|
|
58
|
+
**Hand the build to a second agent, when the run gets a worktree.** This applies under every
|
|
59
|
+
runner, `lite` included: the second agent is a board terminal, not a subagent. The agent the user is
|
|
59
60
|
talking to stays with them. Before `kaizen worktree start`, it writes into `02-approval.md`
|
|
60
61
|
every decision made in chat that the plan lacks: the second agent never sees the chat. After
|
|
61
62
|
it, it runs `kaizen handoff start <id>`. Exit 0: say the worktree agent is building, and end
|
|
@@ -66,7 +67,17 @@ same rules (it is the coordinator if the plan has approved workers), and ends wi
|
|
|
66
67
|
`kaizen handoff done` or `kaizen handoff blocked "<reason>"`. It never runs `kaizen done`
|
|
67
68
|
or `kaizen worktree land`. It takes no bypass from Orchestration. `runs/<id>/handoff.json`
|
|
68
69
|
is written only by these commands and the board. A worktree cut while the project is on a
|
|
69
|
-
branch other than the default is cut from that local branch and records `base_branch
|
|
70
|
+
branch other than the default is cut from that local branch and records `base_branch`,
|
|
71
|
+
except with `--default`.
|
|
72
|
+
|
|
73
|
+
**A side run** (opened while another run is in flight, `SKILL.md` *Follow-ups are runs
|
|
74
|
+
too*) starts its worktree with `kaizen worktree start <id> --default`, so its branch comes
|
|
75
|
+
off the remote default branch and it never builds in the other run's folder. When the user
|
|
76
|
+
picked a second agent: exit 0 from `kaizen handoff start` means say the worktree agent is
|
|
77
|
+
building the side run, then go back to the run in flight instead of ending the turn; its
|
|
78
|
+
files, worktree and stage are untouched. Exit 3: ask the user whether to build the side run
|
|
79
|
+
here, in its own worktree, or leave it at its approved plan; never build it in the other
|
|
80
|
+
run's worktree. A side run without a remote to branch from stops and says so.
|
|
70
81
|
|
|
71
82
|
**Workers, only when the run has them.** When `01-plan.md` has a `## Workers` section and
|
|
72
83
|
`02-approval.md` says `workers: approved`, the build agent is the coordinator. Run
|
|
@@ -96,6 +96,8 @@ Woken by the line `kaizen run <id>: the worktree agent ended (...)`, or asked ab
|
|
|
96
96
|
read `state.json`, `handoff.json`, `03-impl.md` and `04-review.md`, whatever the line says:
|
|
97
97
|
it is a pointer, not a result. `done`: report what changed, the checks and open findings,
|
|
98
98
|
then take the final approval and land as usual; in `auto` carry on without stopping.
|
|
99
|
+
A side run's line can arrive while this agent is busy with another run: report the side run
|
|
100
|
+
and take its final approval without changing the other run's files or stage.
|
|
99
101
|
`blocked`, `failed` or `quiet`: say why and what is left, and keep the worktree. `quiet` means the second agent went silent and may still report; `kaizen handoff start <id>` opens a new one on the same worktree. A run with
|
|
100
102
|
`base_branch` lands by a local merge into that branch, with no push; if the project folder
|
|
101
103
|
is on another branch or the merge conflicts, `kaizen worktree land` says so and keeps the
|
|
@@ -28,6 +28,7 @@ anything.
|
|
|
28
28
|
| `/kaizen review [target]` | Review-only: audit existing code, no plan, no implementation |
|
|
29
29
|
| `/kaizen status` | List every run grouped waiting-on-you / in flight / done / abandoned, plus open backlog count |
|
|
30
30
|
| `kaizen done <id> [--user-approved]` | Finish a run; refused while the review gate waits on the user, `--user-approved` after a clear yes in chat |
|
|
31
|
+
| `kaizen model [planner\|builder\|reviewer]` | The model to pass on that stage subagent's Agent call, from `subagents.<stage>` then `subagents.model`; `inherit` means pass none |
|
|
31
32
|
| `kaizen state <id> key=value ...` | (1.69.0+) Set a run's `stage`, `awaiting` or `iteration` in `state.json`; refuses words no board knows (`done` goes through `kaizen done`) |
|
|
32
33
|
| `kaizen stats [<id>] [--json]` | (1.69.0+) Fix-round and CANNOT VERIFY rates, stage times, tokens for one run |
|
|
33
34
|
| `kaizen related <path> ...` | (1.69.0+) Earlier runs that changed these files |
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: kaizen-game
|
|
3
|
+
description: Design, build, verify and share any browser game (web track) — arcade, puzzle, runner, platformer, board or card game, 3D toy world, idle or story game, campaign or learning game — as a phone-first page with Three.js or plain Canvas/DOM, levels or rounds as separate modules, real-input Playwright play-throughs, frame-timing checks, and a public review link. Has an extra track for live event and learning games (content where the answer is an action in the game, rankings, a spectator view for Zoom). Use when the user wants to make a web game, a game design document (GDD), a playable game prototype, a game for an event, training or campaign, or wants an existing browser game fixed, smoothed or extended. Not for native, console or Unity/Godot games.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Kaizen game (web)
|
|
7
|
+
|
|
8
|
+
Any browser game, from brief to a link people can play: an arcade or puzzle game, a runner, a 3D toy world, a campaign game, a learning game.
|
|
9
|
+
The core flow (brief, concepts, GDD, build, verify, share) is the same for all of them.
|
|
10
|
+
|
|
11
|
+
**Tracks.** Pick one in the brief, and say which in the GDD:
|
|
12
|
+
- **Game** (default): any web game. Skip the content step and the event parts.
|
|
13
|
+
- **Event / learning**: a game with real-world content (training, compliance, onboarding, a campaign quiz) and often a live event with rankings and a shared screen.
|
|
14
|
+
This adds the "not a quiz in a skin" rule, the case model, `content.md`, and the run-of-show and spectator parts.
|
|
15
|
+
|
|
16
|
+
The lessons here come from a real event / learning project. It was a one-hour live compliance competition: 43 teams on phones, 12 playable rounds over two 3D islands, played in the browser, with Zoom used only by moderators.
|
|
17
|
+
It reached client review as a prototype. Steps marked **unproven** were planned there but not yet built. Say so when you reach them.
|
|
18
|
+
|
|
19
|
+
```
|
|
20
|
+
docs/
|
|
21
|
+
GDD.md GDD.pdf the design, approved before games are built
|
|
22
|
+
CONTENT-REVIEW.md event / learning track: every case with answer, reason, source, for the client's expert
|
|
23
|
+
.preview/ what the server shows
|
|
24
|
+
index.html landing: play link, downloads, "what's new" per version
|
|
25
|
+
game.html the game: one page, Three.js from an importmap, no build step
|
|
26
|
+
shared/data.js levels, tuning, content (one global, e.g. window.GDATA)
|
|
27
|
+
rounds/<key>.js one ES module per level or round, loaded with import() when it is entered
|
|
28
|
+
assets/ Kenney CC0 models and sounds actually used, with License.txt and CREDITS.md
|
|
29
|
+
v1/ v2/ … copies of game.html before each big pass
|
|
30
|
+
tools/serve.json which paths the public server may serve
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
`S=<this skill>/scripts`. Run scripts from the project folder.
|
|
34
|
+
|
|
35
|
+
## 0. Setup, once per machine
|
|
36
|
+
`$S/check.sh` lists what is missing (node, Playwright with Chromium, optional pandoc for the GDD PDF). `$S/setup.sh`
|
|
37
|
+
installs Playwright 1.62.1 and Chromium into `~/.kaizen/kaizen-game` (about 150 MB; tell the user first). If kaizen-book
|
|
38
|
+
already installed Playwright in `~/.kaizen/kaizen-book`, the scripts use that one.
|
|
39
|
+
|
|
40
|
+
## 1. Brief, then concepts
|
|
41
|
+
Read [`references/design.md`](references/design.md). Ask what kind of game it is, who plays, on what device, and how long a session lasts.
|
|
42
|
+
For the event / learning track, also ask **who the client is and their sector, before writing any content**. On the real project, content was first written for
|
|
43
|
+
the wrong sector and every case had to be rewritten.
|
|
44
|
+
When the direction is still open, run the `kaizen-concept` skill: truly different concepts, each with its signature
|
|
45
|
+
round playable to the result, on one review page. Build nothing big until one concept is picked.
|
|
46
|
+
|
|
47
|
+
## 2. GDD, approved
|
|
48
|
+
Write `docs/GDD.md` from the skeleton in `design.md`. Every game gets a core loop, controls on phone and laptop, a fail state and win state, tuning knobs, and a difficulty curve.
|
|
49
|
+
In the event / learning track, the rule that decides most of the design is that **the game is not a quiz in a skin**.
|
|
50
|
+
The question is a situation inside the game, and the answer is an action (dodge, stop, pick up, choose a path).
|
|
51
|
+
`node $S/gdd-pdf.mjs docs/GDD.md` builds `docs/GDD.pdf` for the client (needs pandoc).
|
|
52
|
+
Inside a kaizen run, the GDD approval is the plan approval.
|
|
53
|
+
|
|
54
|
+
## 3. Build
|
|
55
|
+
Read [`references/build.md`](references/build.md): page skeleton, `?screen=` jumps, the round shell, the module contract,
|
|
56
|
+
and the Three.js lessons (camera, disposal, touch, fallbacks), each of which cost a redo.
|
|
57
|
+
- Order that worked: playable flow first, then a UI pass (Apple HIG), then a richness pass (models, sound, light), then the real levels or rounds one by one.
|
|
58
|
+
- 2D games use the same skeleton with Canvas or DOM in place of Three.js. The lessons on screens, modules, fallbacks and verification still apply.
|
|
59
|
+
- Copy `game.html` to `v<N>/` before every big pass.
|
|
60
|
+
- Several rounds can be built at once by sub-agents, **one module file per agent**, with the contract in the reference module's header.
|
|
61
|
+
Write each agent a brief: files to read, a "keep" list of recent behaviour it must not undo, the verification, and the report format.
|
|
62
|
+
|
|
63
|
+
## 4. Content (event / learning track)
|
|
64
|
+
Read [`references/content.md`](references/content.md). Cases come from the client's real published rules, read in full.
|
|
65
|
+
Never invent an article number. Mark every case as a sample and list it in `docs/CONTENT-REVIEW.md`, with a column for what still needs the client's confirmation.
|
|
66
|
+
|
|
67
|
+
## 5. Verify
|
|
68
|
+
Read [`references/verify.md`](references/verify.md). The minimum before you say it works:
|
|
69
|
+
```
|
|
70
|
+
node $S/smoke.mjs http://127.0.0.1:4321/game.html --screens login,hub,result # 390×844 touch + 1440×900, errors, overflow, shots
|
|
71
|
+
node $S/frames.mjs http://127.0.0.1:4321/game.html?screen=hub --click 700,600 --gpu # frame gaps around one interaction
|
|
72
|
+
```
|
|
73
|
+
Then play every round **by real input** (taps, swipes, keys) to the result, once with mistakes, and look at every screenshot yourself.
|
|
74
|
+
"Smooth" is a measurement on the real GPU, not a guess. Swiftshader frame times mean nothing.
|
|
75
|
+
|
|
76
|
+
## 6. Share
|
|
77
|
+
Read [`references/ship.md`](references/ship.md). `PUBLIC=1 node $S/serve.mjs .preview 8060` serves only what
|
|
78
|
+
`tools/serve.json` allows. Expose it through the `deploy-tunnel` skill or any static host. Going public is outward-facing, so confirm with the user first.
|
|
79
|
+
Each version gets 3–5 "what's new" lines in the user's language on the landing page.
|
|
80
|
+
|
|
81
|
+
## Unproven (plan it, don't claim it)
|
|
82
|
+
Server-authoritative realtime or multiplayer play (WebSocket, a server clock, answer keys on the server), a host or moderator console,
|
|
83
|
+
saves that survive a refresh, a load test with simulated clients, tests on real cheap phones, and app-store wrapping. The GDD template
|
|
84
|
+
has sections for them. Until they are built, the prototype simulates other players, and the landing page says so.
|
|
85
|
+
|
|
86
|
+
## Improve this skill after each game
|
|
87
|
+
This skill grows from real projects. When a game reaches review, ask the user whether to fold its lessons back in, and add only what was proven in that project:
|
|
88
|
+
- a mistake that cost a redo goes to the "lessons" list of the matching reference, as one line with the measured evidence (`build.md`, `verify.md`, `content.md`);
|
|
89
|
+
- a check that caught a real bug goes into `verify.md` or a script;
|
|
90
|
+
- a step marked **unproven** that the project built and tested loses its mark, and its how-to goes into `ship.md` or `build.md`;
|
|
91
|
+
- a new genre that needed different rules gets its own short section in `design.md`.
|
|
92
|
+
Keep it generic: no client names, client content or project paths, because the skill is published.
|
|
93
|
+
|
|
94
|
+
## Kaizen
|
|
95
|
+
In a kaizen run: the brief and GDD approvals are the plan approval, each game or pass is a build, and the review plays
|
|
96
|
+
the game against the GDD using `verify.md`. Screenshots go in the run's `attachments/` for the Preview gate.
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
@page { size: A4; margin: 18mm 16mm; }
|
|
2
|
+
body { font: 10.5pt/1.5 Inter, -apple-system, "Segoe UI", sans-serif; color: #1d1d1f; max-width: none; }
|
|
3
|
+
h1 { font-size: 22pt; letter-spacing: -0.02em; margin: 0 0 4pt; }
|
|
4
|
+
h2 { font-size: 14pt; margin: 18pt 0 6pt; padding-top: 8pt; border-top: 1px solid #e5e5ea; break-after: avoid; }
|
|
5
|
+
h3 { font-size: 11pt; } p, li { orphans: 3; widows: 3; }
|
|
6
|
+
header#title-block-header { display: none; }
|
|
7
|
+
table { border-collapse: collapse; width: 100%; font-size: 9pt; margin: 6pt 0 10pt; break-inside: auto; }
|
|
8
|
+
th, td { border-bottom: 1px solid #e5e5ea; padding: 4pt 6pt; text-align: left; vertical-align: top; }
|
|
9
|
+
th { background: #f5f5f7; font-weight: 600; } tr { break-inside: avoid; }
|
|
10
|
+
code { font-size: 8.5pt; background: #f5f5f7; padding: 0 3pt; border-radius: 3pt; }
|
|
11
|
+
pre { background: #f5f5f7; padding: 8pt; border-radius: 6pt; font-size: 8.5pt; white-space: pre-wrap; }
|
|
12
|
+
hr { border: 0; }
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
# Build: page, rounds, Three.js lessons
|
|
2
|
+
|
|
3
|
+
## Stack for the prototype
|
|
4
|
+
- One `game.html`, no build step. Three.js from an importmap with an exact version, add-ons from the same version:
|
|
5
|
+
```html
|
|
6
|
+
<script type="importmap">{"imports":{"three":"https://cdn.jsdelivr.net/npm/three@0.170.0/build/three.module.js",
|
|
7
|
+
"three/addons/":"https://cdn.jsdelivr.net/npm/three@0.170.0/examples/jsm/"}}</script>
|
|
8
|
+
```
|
|
9
|
+
GLTFLoader, SkeletonUtils (to clone animated characters) and OrbitControls come from `three/addons/`.
|
|
10
|
+
- `shared/data.js` is a classic script setting one global (teams, rounds, cases), so concepts, game and tools all read the same data.
|
|
11
|
+
- Assets are Kenney CC0 packs (mini characters with animations, city, roads, car, nature, furniture kits, interface, impact and jingle sounds).
|
|
12
|
+
GLBs reference `Textures/colormap.png` next to them, so keep each pack's folder layout. Copy in only what you use, plus `License.txt`, and list the packs in `assets/CREDITS.md`.
|
|
13
|
+
Convert `.ogg` to `.m4a` (`ffmpeg -i x.ogg -c:a aac -b:a 96k x.m4a`) and pick by `audio.canPlayType`, because older iOS Safari cannot play Ogg.
|
|
14
|
+
- Music is a short procedural WebAudio loop that stays off until the first tap. One mute toggle controls everything.
|
|
15
|
+
- Targets: first load under 3 MB on 4G, each round under 1 MB extra, 30+ fps on a mid-range Android phone.
|
|
16
|
+
|
|
17
|
+
## Page skeleton
|
|
18
|
+
- **Screens.** One `go(name)` switches screens (login, character, lobby, hub, game, result, review, leaderboard, final, podium).
|
|
19
|
+
`?screen=<name>` jumps straight to any screen with sample state, so screenshots and agents need no click path. A direct jump into a game skips the intro and starts at once.
|
|
20
|
+
- **Spectator view.** `?view=spectator` (plus `&mode=final`) is a 1280×720 screen for the video call: large type (names 28 px or more, key numbers 48 px or more), flat colours (gradients turn to mush in compression), a room filter, and live top 10 bars.
|
|
21
|
+
- **Test hook.** `window.__game = { go, get view(), get S(), get gpu() }`, where `gpu` = `renderer.info.memory` plus counts. Scripts read state from it and never poke globals.
|
|
22
|
+
- **Honest labels.** Show a small "PROTOTYPE, simulated data" pill and a "sample question" note on content.
|
|
23
|
+
- **Fallbacks.** If WebGL is missing, each round has a 2D version. If GLBs fail to load (for example over `file://`), use primitive shapes. In both cases, log `console.warn` and never throw.
|
|
24
|
+
- **Accessibility.** Contrast at least 4.5:1, touch targets at least 44 px, a visible focus ring, labels on icon buttons, no colour-only signals.
|
|
25
|
+
Under `prefers-reduced-motion`, tweens jump to their end state. Every round must also be playable with laptop keys.
|
|
26
|
+
|
|
27
|
+
## Round shell and module contract
|
|
28
|
+
The page owns the clock, scoring and result. A round module only plays. Keep the contract as a comment at the top of the reference module, because every agent reads it there.
|
|
29
|
+
```
|
|
30
|
+
rounds/<key>.js
|
|
31
|
+
export const READY = true false = placeholder: the hub shows a "coming soon" sheet
|
|
32
|
+
export const ASSETS = [...] GLB paths preloaded before start()
|
|
33
|
+
export const CASES = [...] { id, prompt, action, reason, source } in play order (the review screen lists them)
|
|
34
|
+
export default function start(ctx)
|
|
35
|
+
|
|
36
|
+
ctx (everything a module may touch; it never reads page globals)
|
|
37
|
+
n, meta, root, stage, gl, THREE, data, S, RM (reduced motion)
|
|
38
|
+
sh: st { solved, wrong, pen, elapsed, running, ended }, total,
|
|
39
|
+
good(text, caseId) bad(text, spoken, caseId) (+penalty, case stays open)
|
|
40
|
+
miss(text, spoken, caseId) (+penalty, case closed) penalty(sec, text) end()
|
|
41
|
+
intro(steps, onStart) mount(view) makeCharacter(i) prop(path, opts) instanced(path, items)
|
|
42
|
+
lights(scene, …) tween(dur, fn, delay, done) sfx(name) say(text) buzz(ms)
|
|
43
|
+
later(fn, ms) every(fn, ms) onKey(fn) on(el, ev, fn) onSwipe(el, fn) (all removed on screen change)
|
|
44
|
+
```
|
|
45
|
+
- The shell ends the round when `solved === total`, or at the time limit including penalties. It stores the first result only, plus the solved and missed case ids for the review screen.
|
|
46
|
+
- `view = { scene, camera, resize(w, h), update(dt), onTap?, controls?(orbit), onMount?, onUnmount? }`.
|
|
47
|
+
- A module loads with `import()` when its building is entered. A missing or broken module shows the placeholder sheet instead of a blank screen.
|
|
48
|
+
- Once the shell and the reference module work, each further round is one file, so agents can build several at once.
|
|
49
|
+
|
|
50
|
+
## Three.js lessons (each one cost a redo)
|
|
51
|
+
- **One renderer, one canvas** for all screens. `mount(view)` and `unmount()` swap the scene and camera.
|
|
52
|
+
- **Release GPU memory on unmount.** Patch `EventDispatcher.prototype.addEventListener` so that every object registering a `'dispose'` listener goes into a `GPU` set.
|
|
53
|
+
That set is exactly what three.js uploaded. On unmount, dispose everything in it except the shared model, material and geometry caches.
|
|
54
|
+
Measured: textures 37 → 29 after five games in a row, against 137 → 445 without it. Also remove the DOM nodes the round created.
|
|
55
|
+
- **OrbitControls clamps zoom and angles every frame.** `minZoom`/`maxZoom` must cover every scripted camera move (intro, dive into a building). Otherwise the tween stalls halfway and looks like a stutter.
|
|
56
|
+
- **One camera move at a time.** Give each move a job id and ignore stale ones: `const id = ++camJob; tween(d, p => { if (id === camJob) fn(p); })`. Two tweens writing zoom at once jitter.
|
|
57
|
+
- **Never ease towards a stale target.** When flying to a building on a spinning island, ease the spin out first and aim at the building's live world position every frame.
|
|
58
|
+
- **`OrbitControls.dispose()` leaves an inline `touch-action: auto`** on the shared canvas. Clear it, or the next view loses its swipes to page scrolling.
|
|
59
|
+
- **Keep the old interactions when adding a new one.** Using drag to pan between islands silently removed drag-to-rotate, and the user noticed at once.
|
|
60
|
+
Before changing input handling, list what each gesture does now, and keep that list in the agent's brief.
|
|
61
|
+
- **Screen-sized labels** (sprites with `sizeAttenuation: false`) go into a registry at creation. Never `scene.traverse` every frame to find them.
|
|
62
|
+
- **Phones.** Pixel ratio capped at 2, `powerPreference: 'low-power'`, `PCFShadowMap` on touch devices (soft PCF on desktop), one shadow-casting light, instancing for repeated props (trees, lamps), and pause rendering when the tab is hidden.
|
|
63
|
+
- **Animated characters.** Clone with `SkeletonUtils.clone`. Use one `AnimationMixer` per character and crossfade clips (idle, walk, sprint, jump, fall, emote).
|
|
64
|
+
- **Labels must not collide** with fixed UI: test the tallest building's label against the segmented control at 1440×900 and 2000×1100.
|
|
65
|
+
|
|
66
|
+
## UI direction that the client approved (Apple HIG)
|
|
67
|
+
- Clarity: one purpose per screen; a large title of 34 px, body text of 17 px, `tabular-nums` for timers and scores.
|
|
68
|
+
- System font for the UI; one display font only for titles and game moments.
|
|
69
|
+
- Deference: neutral surfaces with one accent colour for primary actions, and no ornament.
|
|
70
|
+
- Depth: cards on a grouped background with soft shadows. Bottom sheets with a grabber for details. Blur only on controls that float over the 3D view.
|
|
71
|
+
- iOS patterns: inset grouped lists, segmented controls, and one primary button pinned at the bottom (`padding-bottom: max(16px, env(safe-area-inset-bottom))`).
|
|
72
|
+
- Motion: about 350–500 ms with `cubic-bezier(.32,.72,0,1)` and `scale(.97)` on press. Every tap gets feedback (sound, `navigator.vibrate(10)`).
|
|
73
|
+
- Thin line icons drawn as inline SVG. No emoji icons, no hype copy, no purple gradients, no fake stats.
|
|
74
|
+
- Login on a phone: the password field must stay visible above the keyboard. Keep the hero and the list short, and let Enter submit.
|
|
75
|
+
|
|
76
|
+
## Parallel agents
|
|
77
|
+
- First one agent builds the shell and one reference round end to end. Then one agent per remaining round, each editing only its own `rounds/<key>.js`.
|
|
78
|
+
If an agent needs a page change, it describes it in its report, and you apply it.
|
|
79
|
+
- The brief, as a file in the scratchpad: what the user asked (quoted), files to read first, the contract, the content rules, the "keep" list, the verification to run, and a word-capped report.
|
|
80
|
+
The report covers what was done, controls, case count, asset KB, weak spots, and the "what's new" lines.
|
|
81
|
+
- Tell every agent whether the site is live. On the real project, edits went public the moment they were saved, so "keep it working at every save" was in every brief.
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# Content: cases from real rules
|
|
2
|
+
|
|
3
|
+
Learning and event games live or die on content that the client's expert accepts. Write sample cases yourself, from sources,
|
|
4
|
+
so the client reviews something concrete instead of starting from a blank sheet.
|
|
5
|
+
|
|
6
|
+
## Sources
|
|
7
|
+
1. Know the client's sector and their own rules first (see the brief).
|
|
8
|
+
2. Find their **published** documents: guidelines, codes of conduct, policies, the regulator's rules for their sector.
|
|
9
|
+
Download each into its own folder and extract the text (`pdftotext -layout`), then read the parts you cite.
|
|
10
|
+
3. A rule cited in a case needs a document you read. Cite an article, chapter or paragraph number only when it is in the text you read. Otherwise cite the document title alone.
|
|
11
|
+
Quote thresholds, deadlines and channels exactly as written (for example "within 10 working days to the unit, 30 to the regulator", "exempt up to Rp1,000,000").
|
|
12
|
+
4. Where no source exists (an internal SOP you could not find), use a general standard (for example ISO 27001) and flag the case for confirmation.
|
|
13
|
+
Example domains used in phishing cases must be visibly made up, or lookalikes of the client's real domain.
|
|
14
|
+
|
|
15
|
+
## Writing cases
|
|
16
|
+
- Each case is a real situation from the players' work, in their words: their customers, partners and documents.
|
|
17
|
+
Don't use other sectors' terms (for example "nasabah" for an insurer's claimants).
|
|
18
|
+
- `prompt`: what the player sees in the game, short enough for a label or a sign.
|
|
19
|
+
- `action`: the correct thing to do. `reason`: one line a player understands. `source`: the document (and article if verified).
|
|
20
|
+
- Order: obvious first, subtle last. Keep the totals the GDD fixes, so times stay comparable.
|
|
21
|
+
- Mark everything as a sample that needs the client's check, in the UI and in the data.
|
|
22
|
+
- Check the fit on screen: word lengths in letter tiles and grids, and long sentences in cards and buttons.
|
|
23
|
+
|
|
24
|
+
## The review file (`docs/CONTENT-REVIEW.md`)
|
|
25
|
+
- One table per game: id, situation, correct action, reason, source, and **"needs confirmation"** (empty, or what exactly is uncertain).
|
|
26
|
+
- Generate it from the game data with a small script (import the modules and read `CASES`), so it never drifts from what players see. Rerun it after every content edit.
|
|
27
|
+
- Offer it as a download on the landing page next to the GDD, and list the open points in GDD section 14.
|
|
28
|
+
|
|
29
|
+
## After a rewrite
|
|
30
|
+
- `grep` the whole site for terms that must be gone (old sector words, wrong laws, wrong domains). The result must be empty.
|
|
31
|
+
- Spot-check three or four key facts back in the extracted source text, with line numbers.
|
|
32
|
+
- Replay each changed round at 390 px for overflow.
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
# Design: brief, concepts, GDD
|
|
2
|
+
|
|
3
|
+
## Brief: ask before anything is built
|
|
4
|
+
One message, grouped, with a default for each question so the user can answer "defaults are fine".
|
|
5
|
+
- **The game.** Genre or reference feel (described by mechanic, not by a game to copy), 2D or 3D, session length, solo or multiplayer, and what makes a player come back.
|
|
6
|
+
- **Track.** Just a game, or an event / learning game with real content (see below)?
|
|
7
|
+
- **Players.** How many, solo or teams, one device each? Phone, laptop or both (default: phone first, laptop works)?
|
|
8
|
+
- **Setting.** A live event (a fixed time, a host, everyone at once, rankings) or played anytime? How long, and how many rounds?
|
|
9
|
+
- **Client** (event / learning). The organisation, its sector, the unit that owns the content, and the person who signs it off.
|
|
10
|
+
Ask this first. Content written before the sector is known has to be rewritten: bank wording for an insurer, civil-servant rules for a state company.
|
|
11
|
+
- **Purpose.** What should players learn, practise or prove? What counts as winning?
|
|
12
|
+
- **Channel.** Zoom, Teams, a stage screen? Who shares what? (On the real project, Zoom was used by moderators only. Players played in their own browser.)
|
|
13
|
+
- **Language and tone.** The players' language, and everyday office or playful.
|
|
14
|
+
- **Brand and limits.** Logo, colours, real places to include, devices that must work, hosting rules, the event date.
|
|
15
|
+
|
|
16
|
+
Write the answers into GDD section 1 and keep the unknowns in section 14 (open questions).
|
|
17
|
+
|
|
18
|
+
## Concepts
|
|
19
|
+
When the direction is open, use `kaizen-concept`. What worked:
|
|
20
|
+
- Three truly different concepts, not one idea in three skins. For example: case files and stamps, a 3D toy town, a TV game show.
|
|
21
|
+
- All three share one `shared/data.js` (teams, sample cases, a `simulateRound`), so they are compared on design and not on content.
|
|
22
|
+
- Each concept plays its signature round to the result by real input, and has a spectator view for the shared screen.
|
|
23
|
+
- One review page with a vote per concept. The user picked one, then asked for two separate passes:
|
|
24
|
+
a UI pass ("follow Apple philosophy") and a richness pass (CC0 models and sound). Offer them as separate steps.
|
|
25
|
+
|
|
26
|
+
## Every game
|
|
27
|
+
- **Core loop** in one line (for example: run, dodge, collect, reach the goal). If it is not fun with the scoring removed, fix the loop first.
|
|
28
|
+
- **Controls on both devices.** Touch first (tap, swipe, hold, drag), with laptop keys as a bonus. No control may require a keyboard on a phone.
|
|
29
|
+
- **Win state, fail state, and feedback** under 1 s for every action.
|
|
30
|
+
- **Difficulty** rises across a session or level. Write the tuning knobs (speed, spacing, timers) in the GDD so they can be adjusted without redesign.
|
|
31
|
+
- **Juice where it counts.** Small camera kicks, particles, sound on every action, and a short slow-motion beat on big moments. Respect reduced motion.
|
|
32
|
+
|
|
33
|
+
## Event / learning track: not a quiz in a skin
|
|
34
|
+
The user rejected "Kahoot style" outright. In every round:
|
|
35
|
+
- The question is a **situation inside the game**: a vendor holding out a parcel on the street, a visitor without a badge, an email in the inbox.
|
|
36
|
+
- The answer is an **action**: dodge or collect, stop or let through, flag or open, put away, choose a path.
|
|
37
|
+
- Skill (speed, aim, timing) and knowledge both count, and knowledge decides.
|
|
38
|
+
- A text question is allowed only as a short checkpoint inside the action, such as a gate with three lanes. It never fills a whole screen.
|
|
39
|
+
|
|
40
|
+
## Shared systems for the event / learning track (state once in the GDD)
|
|
41
|
+
- **Case model.** `{ id, prompt, action, reason, source }`, in play order, the same for every player.
|
|
42
|
+
`reason` is one line a player understands. `source` names the real rule.
|
|
43
|
+
- **Ranking.** Cases solved first, then time with a fixed penalty per wrong action (for example 5 s), then fewer wrong actions.
|
|
44
|
+
Points per rank (for example 100, minus 3 per place, minimum 10). Top N go to a harder final. Add tie-breaks.
|
|
45
|
+
- **Cosmetic pickups** (coins) are shown on the result only and never change the ranking.
|
|
46
|
+
- **First result counts.** Replays are labelled as practice and leave the standings unchanged. Finals have no replay.
|
|
47
|
+
- **Answer review** after every round lists the round's cases with the correct action, reason and source, and highlights the player's mistakes.
|
|
48
|
+
This is the learning moment and the host's talking point. Build it from the solved and missed case sets, not from the order of play.
|
|
49
|
+
Otherwise a timeout or cases solved out of order give wrong rows.
|
|
50
|
+
- **Difficulty curve.** Obvious cases first and subtle ones last (a near-identical domain). The final is clearly harder than any round.
|
|
51
|
+
- **Fairness pillar.** The same content and the same clock for everyone. Timing never depends on the video call (Zoom lags 1–3 s).
|
|
52
|
+
|
|
53
|
+
## GDD skeleton (`docs/GDD.md`)
|
|
54
|
+
```
|
|
55
|
+
# <Name>: Game Design Document
|
|
56
|
+
Version, date, status line, client and content owner.
|
|
57
|
+
1. One-page overview: pitch, track, players, session or event shape, pillars, anti-pillars
|
|
58
|
+
2. Event format and run-of-show (live events only): table of time, segment, player screen, shared screen
|
|
59
|
+
3. Core loop and shared systems: loop diagram, scoring, progression, character, difficulty curve
|
|
60
|
+
(event / learning: case model, ranking, pickups, answer review)
|
|
61
|
+
4..N. One section per game, level or round:
|
|
62
|
+
Building or place, genre, what it teaches
|
|
63
|
+
Fantasy: one line
|
|
64
|
+
How it plays: controls on phone and on laptop, what the player does each second
|
|
65
|
+
Objects, enemies, obstacles (event / learning: the cases in the world, and the correct action for each)
|
|
66
|
+
Level or case data shape; fixed totals where times must be comparable
|
|
67
|
+
Feedback: correct and wrong, both under 1 s so play keeps flowing
|
|
68
|
+
Spectator: what the shared screen shows
|
|
69
|
+
Tuning knobs, edge cases (reconnect, hidden tab), effort S/M/L
|
|
70
|
+
N+1. Final
|
|
71
|
+
.. Screens and UI: table of screen and purpose; design language
|
|
72
|
+
.. Tech, content, accessibility: stack, server-authoritative rules, assets and sizes, performance targets, content pipeline
|
|
73
|
+
.. Build plan: steps and the result of each
|
|
74
|
+
.. Risks and fallback (phones, network, server, content errors, disputes, call delay)
|
|
75
|
+
.. Open questions for the client
|
|
76
|
+
```
|
|
77
|
+
Write each game section so another agent can build it without asking anything. The real project's sub-agents built five games in parallel from their sections alone.
|
|
78
|
+
|
|
79
|
+
## Originality
|
|
80
|
+
Genres and mechanics are free to use: a 3-lane runner, a memory match, a word search. Names, characters, art, music and levels are your own.
|
|
81
|
+
Never recreate a specific existing game, even when it is renamed. Kenney CC0 packs give a consistent toy look that belongs to nobody.
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
# Ship: a link the client can play
|
|
2
|
+
|
|
3
|
+
## Serve
|
|
4
|
+
`node $S/serve.mjs .preview 4321` serves the whole folder on 127.0.0.1 for you and your agents.
|
|
5
|
+
`PUBLIC=1 node $S/serve.mjs .preview 8060` serves only what `tools/serve.json` (or `--config <file>`) allows:
|
|
6
|
+
```json
|
|
7
|
+
{
|
|
8
|
+
"public": ["index.html", "game.html", "shared/data.js", "rounds/*.js", "assets/**"],
|
|
9
|
+
"downloads": { "/download/GDD.pdf": "../docs/GDD.pdf", "/download/Cases.md": "../docs/CONTENT-REVIEW.md" }
|
|
10
|
+
}
|
|
11
|
+
```
|
|
12
|
+
- `*` matches one path segment and `**` any depth. Download paths are relative to the config file, and are sent as attachments.
|
|
13
|
+
- Old versions (`v1/`), other concepts and scratch files stay private by default. Only list what the client should see.
|
|
14
|
+
- The server never throws on a bad request path: `//` and a lone `%` once took the public server down.
|
|
15
|
+
`node $S/serve.test.mjs` checks the path guard and the allowlist matching.
|
|
16
|
+
- Keep it running as a user service, so it survives your session:
|
|
17
|
+
`systemd-run --user --unit <name>-web -p WorkingDirectory=$PWD -E PUBLIC=1 node $S/serve.mjs .preview 8060`, or a unit file for reboots.
|
|
18
|
+
|
|
19
|
+
## Expose
|
|
20
|
+
Use the `deploy-tunnel` skill if it is installed (Cloudflare tunnel to a subdomain). Otherwise any static host works for the files.
|
|
21
|
+
Publishing is outward-facing, so confirm with the user before the first public link.
|
|
22
|
+
Once it is public, every save is live: tell agents, and keep the page working at each save.
|
|
23
|
+
|
|
24
|
+
## Landing page (`index.html`)
|
|
25
|
+
- The play link (and a "jump to the latest part" link for reviewers), the GDD (PDF and MD), and the case list for the content owner.
|
|
26
|
+
- A "what's new" list per version, 3–5 lines in the user's language, from each agent's report.
|
|
27
|
+
- An honest note about what is simulated (other teams, the live server).
|
|
28
|
+
|
|
29
|
+
## Before the real event (unproven: plan these in the GDD build plan)
|
|
30
|
+
- A server-authoritative game server: it sends one case at a time, keeps the answer keys, stamps time, and decides finish and rank.
|
|
31
|
+
Clients send only actions.
|
|
32
|
+
- Progress that survives a refresh or reconnect, one active device per account, and a moderator console (open, start, pause, end, void a case, export).
|
|
33
|
+
- A load test with simulated clients, tests on a cheap Android phone and an iPhone, and a full rehearsal with the hosts.
|
|
34
|
+
- A fallback (for example a form with the same cases) in case the server fails.
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# Verify: play it, look at it, measure it
|
|
2
|
+
|
|
3
|
+
## Browsers
|
|
4
|
+
- **Swiftshader** (CPU WebGL, works headless everywhere, deterministic): use it for screenshots and play-throughs.
|
|
5
|
+
Args: `--use-gl=angle --use-angle=swiftshader --enable-unsafe-swiftshader`. Frame times here are meaningless.
|
|
6
|
+
- **Real GPU** (`--gpu` in the scripts): `--enable-gpu --ignore-gpu-blocklist --use-angle=vulkan --enable-features=Vulkan`.
|
|
7
|
+
Use it for any claim about smoothness. The scripts print the WebGL renderer string, so check that it is not SwiftShader.
|
|
8
|
+
|
|
9
|
+
## The minimum, every pass
|
|
10
|
+
1. `node $S/smoke.mjs <url> --screens <list>` at 390×844 (touch, DPR 2) and 1440×900. It fails on page errors, console errors,
|
|
11
|
+
failed requests and horizontal overflow, and writes a screenshot per screen and size.
|
|
12
|
+
2. **Read every screenshot yourself.** Text overflowing a button, a label hidden behind a control, or a field under the dock show only in pictures.
|
|
13
|
+
Longer translated sentences break layouts that fitted the English sample.
|
|
14
|
+
3. **Play every round by real input** (Playwright `page.touchscreen.tap`, `page.mouse`, `page.keyboard`) to the result and the review screen.
|
|
15
|
+
Do it once clean and once with deliberate mistakes, and once let a round time out. Never call game functions to skip play, because that hides input bugs.
|
|
16
|
+
4. **Check the rules end to end.** Unlock gates fire without the URL shortcut, the final is closed to non-qualifiers,
|
|
17
|
+
a replay does not change the score, the review rows match what happened, and the podium leads back to the hub.
|
|
18
|
+
5. **Check leaks.** Read `__game.gpu` and `document.querySelectorAll('*').length` in the hub, then after playing several rounds in a row and returning.
|
|
19
|
+
The numbers should come back to about the hub baseline.
|
|
20
|
+
6. `file://` and no-WebGL fallbacks load without errors.
|
|
21
|
+
|
|
22
|
+
Write the long play-through as one `e2e.mjs` in the scratchpad and rerun it after every fix pass, adapting the selectors as the markup changes.
|
|
23
|
+
|
|
24
|
+
## When the user says it stutters
|
|
25
|
+
Measure before you change anything:
|
|
26
|
+
```
|
|
27
|
+
node $S/frames.mjs '<url>?screen=hub' --size 2000x1100 --click 700,600 --gpu --ms 2500
|
|
28
|
+
```
|
|
29
|
+
It wraps `requestAnimationFrame` and reports frame gaps (p50, p95, max, frames over 33 ms) plus long tasks around one interaction.
|
|
30
|
+
- **Gaps over 33 ms or long tasks:** it is a rendering or JS cost. Look for per-frame scene traversal, shader compiles on first view (warm them up with `renderer.compile`), and texture uploads.
|
|
31
|
+
- **A steady 60 fps that still "feels" jerky:** it is the motion. Log the camera every frame (a `page.route` that injects a log line into the page's render call).
|
|
32
|
+
Look for two tweens fighting, a clamp stopping a tween, a target that moves while it is being eased towards, or a spin that stops abruptly.
|
|
33
|
+
- Repeat at the user's window size. If it still feels wrong after a clean measurement, ask which browser and device they use. Don't guess further.
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
#!/bin/sh
|
|
2
|
+
# Lists what kaizen-game needs and whether it is here. Exit 1 if anything required is missing.
|
|
3
|
+
miss=0
|
|
4
|
+
command -v node >/dev/null 2>&1 && echo "ok node $(node -v)" || { echo "MISSING node"; miss=1; }
|
|
5
|
+
found=""
|
|
6
|
+
for h in "$KAIZEN_GAME_HOME" "$HOME/.kaizen/kaizen-game" "$HOME/.kaizen/kaizen-book"; do
|
|
7
|
+
[ -n "$h" ] && [ -d "$h/node_modules/playwright" ] && { found="$h"; break; }
|
|
8
|
+
done
|
|
9
|
+
[ -n "$found" ] && echo "ok playwright ($found)" || { echo "MISSING playwright: run scripts/setup.sh"; miss=1; }
|
|
10
|
+
command -v pandoc >/dev/null 2>&1 && echo "ok pandoc (GDD PDF)" || echo "- pandoc not found (optional, only for gdd-pdf.mjs)"
|
|
11
|
+
command -v ffmpeg >/dev/null 2>&1 && echo "ok ffmpeg (sound conversion)" || echo "- ffmpeg not found (optional, .ogg to .m4a)"
|
|
12
|
+
command -v pdftotext >/dev/null 2>&1 && echo "ok pdftotext (reading source rules)" || echo "- pdftotext not found (optional, poppler)"
|
|
13
|
+
exit $miss
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
// Frame timing around one interaction. Usage:
|
|
2
|
+
// node frames.mjs <url> [--click x,y | --tap x,y | --selector css] [--ms 2500] [--size 2000x1100] [--settle 5000] [--gpu]
|
|
3
|
+
// Wraps requestAnimationFrame before the page loads, so it works on any page. Prints the WebGL renderer
|
|
4
|
+
// (SwiftShader = CPU, timings meaningless), frame gaps p50/p95/max, frames over 33 ms, and long tasks.
|
|
5
|
+
import { chromium, SOFT, GPU, arg, flag } from './pw.mjs';
|
|
6
|
+
|
|
7
|
+
const url = process.argv[2];
|
|
8
|
+
if (!url || url.startsWith('--')) { console.error('usage: node frames.mjs <url> [--click x,y] [--gpu]'); process.exit(2); }
|
|
9
|
+
const [w, h] = String(arg('size', '1440x900')).split('x').map(Number), ms = +arg('ms', 2500);
|
|
10
|
+
const tap = arg('tap'), b = await chromium.launch({ headless: true, args: flag('gpu') ? GPU : SOFT });
|
|
11
|
+
const p = await b.newPage({ viewport: { width: w, height: h }, hasTouch: !!tap, isMobile: !!tap });
|
|
12
|
+
await p.addInitScript(() => {
|
|
13
|
+
window.__fr = []; window.__lt = [];
|
|
14
|
+
const raf = window.requestAnimationFrame.bind(window);
|
|
15
|
+
// count each animation frame once, whatever number of callbacks the page queues in it
|
|
16
|
+
let lastT = -1; window.requestAnimationFrame = cb => raf(t => { if (t !== lastT) { lastT = t; window.__fr.push(t); } cb(t); });
|
|
17
|
+
try { new PerformanceObserver(l => l.getEntries().forEach(e => window.__lt.push([Math.round(e.startTime), Math.round(e.duration)]))).observe({ type: 'longtask', buffered: true }); } catch {}
|
|
18
|
+
});
|
|
19
|
+
const errs = []; p.on('pageerror', e => errs.push(e.message));
|
|
20
|
+
await p.goto(url, { waitUntil: 'networkidle' }); await p.waitForTimeout(+arg('settle', 5000));
|
|
21
|
+
console.log('renderer:', await p.evaluate(() => { const g = document.createElement('canvas').getContext('webgl2') || document.createElement('canvas').getContext('webgl'); const d = g && g.getExtension('WEBGL_debug_renderer_info'); return d ? g.getParameter(d.UNMASKED_RENDERER_WEBGL) : 'no WebGL'; }));
|
|
22
|
+
const t0 = await p.evaluate(() => { window.__fr = []; window.__lt = []; return performance.now(); });
|
|
23
|
+
const xy = s => String(s).split(',').map(Number);
|
|
24
|
+
if (arg('click')) await p.mouse.click(...xy(arg('click')));
|
|
25
|
+
else if (tap) await p.touchscreen.tap(...xy(tap));
|
|
26
|
+
else if (arg('selector')) await p.click(arg('selector'));
|
|
27
|
+
await p.waitForTimeout(ms);
|
|
28
|
+
const { fr, lt } = await p.evaluate(() => ({ fr: window.__fr, lt: window.__lt }));
|
|
29
|
+
await b.close();
|
|
30
|
+
const gaps = fr.slice(1).map((t, i) => t - fr[i]).sort((a, z) => a - z), q = k => gaps.length ? gaps[Math.min(gaps.length - 1, Math.floor(k * gaps.length))].toFixed(1) : '-';
|
|
31
|
+
console.log(`frames ${fr.length} in ${ms} ms (${(fr.length / ms * 1000).toFixed(0)} fps) gap p50 ${q(.5)} p95 ${q(.95)} max ${q(1)} ms over 33 ms: ${gaps.filter(g => g > 33).length}`);
|
|
32
|
+
const late = lt.filter(([s]) => s >= t0);
|
|
33
|
+
console.log(late.length ? 'long tasks: ' + late.map(([s, d]) => `+${Math.round(s - t0)}ms ${d}ms`).join(', ') : 'long tasks: none');
|
|
34
|
+
if (errs.length) { console.log('page errors:', errs.join(' | ')); process.exit(1); }
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
// Builds an A4 PDF from a Markdown GDD: pandoc to HTML with assets/gdd.css, then Chromium print.
|
|
2
|
+
// Usage: node gdd-pdf.mjs docs/GDD.md [docs/GDD.pdf]
|
|
3
|
+
import { execFileSync } from 'node:child_process';
|
|
4
|
+
import fs from 'node:fs';
|
|
5
|
+
import os from 'node:os';
|
|
6
|
+
import path from 'node:path';
|
|
7
|
+
import { fileURLToPath } from 'node:url';
|
|
8
|
+
import { chromium } from './pw.mjs';
|
|
9
|
+
|
|
10
|
+
const md = process.argv[2]; if (!md) { console.error('usage: node gdd-pdf.mjs <GDD.md> [out.pdf]'); process.exit(2); }
|
|
11
|
+
const out = process.argv[3] || md.replace(/\.md$/i, '.pdf');
|
|
12
|
+
const css = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'assets', 'gdd.css');
|
|
13
|
+
const title = (fs.readFileSync(md, 'utf8').match(/^#\s+(.+)$/m) || [, path.basename(md, '.md')])[1];
|
|
14
|
+
const tmp = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'gdd-')), 'gdd.html');
|
|
15
|
+
execFileSync('pandoc', ['-f', 'gfm', md, '-s', '--metadata', 'title=' + title, '-c', css, '--embed-resources', '-o', tmp]);
|
|
16
|
+
const b = await chromium.launch(), p = await b.newPage();
|
|
17
|
+
await p.goto('file://' + tmp, { waitUntil: 'networkidle' });
|
|
18
|
+
await p.pdf({ path: out, format: 'A4', printBackground: true, margin: { top: '18mm', bottom: '18mm', left: '16mm', right: '16mm' } });
|
|
19
|
+
await b.close(); console.log('wrote', out);
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
// Finds Playwright: KAIZEN_GAME_HOME, then ~/.kaizen/kaizen-game, then kaizen-book's copy, then a normal import.
|
|
2
|
+
import { createRequire } from 'node:module';
|
|
3
|
+
import fs from 'node:fs';
|
|
4
|
+
import os from 'node:os';
|
|
5
|
+
import path from 'node:path';
|
|
6
|
+
|
|
7
|
+
const homes = [process.env.KAIZEN_GAME_HOME, path.join(os.homedir(), '.kaizen', 'kaizen-game'), path.join(os.homedir(), '.kaizen', 'kaizen-book')].filter(Boolean);
|
|
8
|
+
let pw;
|
|
9
|
+
for (const h of homes) {
|
|
10
|
+
if (!fs.existsSync(path.join(h, 'package.json'))) continue;
|
|
11
|
+
try { pw = createRequire(path.join(h, 'package.json'))('playwright'); break; } catch {}
|
|
12
|
+
}
|
|
13
|
+
if (!pw) try { pw = await import('playwright'); } catch { console.error('Playwright not found: run scripts/setup.sh'); process.exit(2); }
|
|
14
|
+
export const { chromium } = pw;
|
|
15
|
+
export const SOFT = ['--use-gl=angle', '--use-angle=swiftshader', '--enable-unsafe-swiftshader'];
|
|
16
|
+
export const GPU = ['--enable-gpu', '--ignore-gpu-blocklist', '--use-angle=vulkan', '--enable-features=Vulkan'];
|
|
17
|
+
export const arg = (name, def) => { const i = process.argv.indexOf('--' + name); return i < 0 ? def : (process.argv[i + 1] ?? true); };
|
|
18
|
+
export const flag = name => process.argv.includes('--' + name);
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
// Static server for a game folder. Usage: node serve.mjs [root=.preview] [port=4321] [--config tools/serve.json]
|
|
2
|
+
// PUBLIC=1 serves only the paths the config allows ("public" globs, "downloads" map); without PUBLIC it serves everything
|
|
3
|
+
// under root on 127.0.0.1 (HOST overrides). GET/HEAD only. A bad request path gets 400, never a crash.
|
|
4
|
+
import http from 'node:http';
|
|
5
|
+
import fs from 'node:fs/promises';
|
|
6
|
+
import { readFileSync } from 'node:fs';
|
|
7
|
+
import path from 'node:path';
|
|
8
|
+
import { fileURLToPath } from 'node:url';
|
|
9
|
+
|
|
10
|
+
const TYPES = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.mjs': 'text/javascript; charset=utf-8', '.css': 'text/css', '.json': 'application/json', '.md': 'text/markdown; charset=utf-8', '.pdf': 'application/pdf', '.glb': 'model/gltf-binary', '.gltf': 'model/gltf+json', '.png': 'image/png', '.jpg': 'image/jpeg', '.webp': 'image/webp', '.svg': 'image/svg+xml', '.m4a': 'audio/mp4', '.mp3': 'audio/mpeg', '.ogg': 'audio/ogg', '.woff2': 'font/woff2', '.txt': 'text/plain; charset=utf-8' };
|
|
11
|
+
|
|
12
|
+
// new URL('//', base) and decodeURIComponent('%') both throw; an uncaught throw takes the whole server down
|
|
13
|
+
export function reqPath(raw) {
|
|
14
|
+
try { return decodeURIComponent(new URL('http://x' + (String(raw).startsWith('/') ? raw : '/' + raw)).pathname); } catch { return null; }
|
|
15
|
+
}
|
|
16
|
+
// "*" = one path segment, "**" = any depth; matched against the path without its leading slash
|
|
17
|
+
export function globRe(g) {
|
|
18
|
+
const s = g.replace(/^\//, '').split(/(\*\*|\*)/).map(p => p === '**' ? '.+' : p === '*' ? '[^/]+' : p.replace(/[.+?^${}()|[\]\\]/g, '\\$&')).join('');
|
|
19
|
+
return new RegExp('^' + s + '$');
|
|
20
|
+
}
|
|
21
|
+
export function allowed(rel, res) {
|
|
22
|
+
const r = rel.replace(/^\//, '');
|
|
23
|
+
return !r.split('/').some(seg => seg === '..' || seg.startsWith('.')) && res.some(re => re.test(r));
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
if (process.argv[1] === fileURLToPath(import.meta.url)) {
|
|
27
|
+
const pos = process.argv.slice(2).filter((a, i, all) => !a.startsWith('--') && all[i - 1] !== '--config');
|
|
28
|
+
const ROOT = path.resolve(pos[0] || '.preview'), PORT = +(pos[1] || process.env.PORT || 4321);
|
|
29
|
+
const HOST = process.env.HOST || '127.0.0.1', PUBLIC = process.env.PUBLIC === '1';
|
|
30
|
+
const ci = process.argv.indexOf('--config'), cfgPath = path.resolve(ci > 0 ? process.argv[ci + 1] : 'tools/serve.json');
|
|
31
|
+
let cfg = { public: [], downloads: {} };
|
|
32
|
+
try { cfg = { ...cfg, ...JSON.parse(readFileSync(cfgPath, 'utf8')) }; }
|
|
33
|
+
catch (e) { if (PUBLIC) { console.error(`PUBLIC=1 needs a config (${cfgPath}): ${e.message}`); process.exit(1); } }
|
|
34
|
+
const RES = cfg.public.map(globRe);
|
|
35
|
+
const DL = Object.fromEntries(Object.entries(cfg.downloads || {}).map(([k, v]) => [k, path.resolve(path.dirname(cfgPath), v)]));
|
|
36
|
+
const send = (res, code, body, type = 'text/plain; charset=utf-8', head = {}) => {
|
|
37
|
+
res.writeHead(code, { 'content-type': type, 'cache-control': 'no-store', 'x-content-type-options': 'nosniff', ...head });
|
|
38
|
+
res.end(body);
|
|
39
|
+
};
|
|
40
|
+
http.createServer(async (req, res) => {
|
|
41
|
+
if (req.method !== 'GET' && req.method !== 'HEAD') return send(res, 405, 'method');
|
|
42
|
+
let rel = reqPath(req.url);
|
|
43
|
+
if (rel == null) return send(res, 400, 'bad request');
|
|
44
|
+
if (rel === '/') rel = '/index.html';
|
|
45
|
+
try {
|
|
46
|
+
if (DL[rel]) return send(res, 200, await fs.readFile(DL[rel]), TYPES[path.extname(rel)] || 'application/octet-stream', { 'content-disposition': `attachment; filename="${path.basename(rel)}"` });
|
|
47
|
+
if (PUBLIC && !allowed(rel, RES)) return send(res, 404, 'not found');
|
|
48
|
+
const file = path.resolve(ROOT, '.' + rel);
|
|
49
|
+
if (!file.startsWith(ROOT + path.sep)) return send(res, 403, 'forbidden');
|
|
50
|
+
send(res, 200, await fs.readFile(file), TYPES[path.extname(file)] || 'application/octet-stream');
|
|
51
|
+
} catch { send(res, 404, 'not found'); }
|
|
52
|
+
}).listen(PORT, HOST, () => console.log(`serving ${ROOT} at http://${HOST}:${PORT}${PUBLIC ? ` (public: ${cfgPath})` : ''}`));
|
|
53
|
+
}
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
// node serve.test.mjs: the path guard and allowlist matching of serve.mjs
|
|
2
|
+
import assert from 'node:assert';
|
|
3
|
+
import { reqPath, globRe, allowed } from './serve.mjs';
|
|
4
|
+
assert.equal(reqPath('//'), '//');
|
|
5
|
+
assert.equal(reqPath('/%'), null);
|
|
6
|
+
assert.equal(reqPath('/a/%2e%2e/x?q=1'), '/x'); // dot segments resolve, nothing climbs above root
|
|
7
|
+
assert.equal(reqPath('/a%20b'), '/a b');
|
|
8
|
+
const res = ['index.html', 'game.html', 'rounds/*.js', 'assets/**'].map(globRe);
|
|
9
|
+
assert.ok(allowed('/game.html', res));
|
|
10
|
+
assert.ok(allowed('/rounds/kurir.js', res));
|
|
11
|
+
assert.ok(!allowed('/rounds/sub/kurir.js', res)); // * is one segment
|
|
12
|
+
assert.ok(!allowed('/rounds/kurir.mjs', res));
|
|
13
|
+
assert.ok(allowed('/assets/kit/Textures/colormap.png', res));
|
|
14
|
+
assert.ok(!allowed('/v1/game.html', res)); // old versions stay private
|
|
15
|
+
assert.ok(!allowed('/assets/.env', res)); // no dotfiles, even under **
|
|
16
|
+
assert.ok(!allowed('/assets/../tools/serve.json', res));
|
|
17
|
+
assert.ok(!allowed('/gameXhtml', res)); // dots are literal
|
|
18
|
+
console.log('serve OK');
|