@typeonce/ritmo-devtools 0.14.0 → 0.16.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/CHANGELOG.md +283 -0
- package/README.md +303 -55
- package/dist/Desync.d.ts +23 -3
- package/dist/Desync.d.ts.map +1 -1
- package/dist/Desync.js +17 -15
- package/dist/Desync.js.map +1 -1
- package/dist/Determinism.d.ts +20 -6
- package/dist/Determinism.d.ts.map +1 -1
- package/dist/Determinism.js +11 -3
- package/dist/Determinism.js.map +1 -1
- package/dist/Format.d.ts +43 -8
- package/dist/Format.d.ts.map +1 -1
- package/dist/Format.js +66 -31
- package/dist/Format.js.map +1 -1
- package/dist/Fuzz.d.ts +275 -0
- package/dist/Fuzz.d.ts.map +1 -0
- package/dist/Fuzz.js +362 -0
- package/dist/Fuzz.js.map +1 -0
- package/dist/Invariant.d.ts +9 -2
- package/dist/Invariant.d.ts.map +1 -1
- package/dist/Invariant.js.map +1 -1
- package/dist/Lint.d.ts +11 -5
- package/dist/Lint.d.ts.map +1 -1
- package/dist/Lint.js.map +1 -1
- package/dist/PlaywrightEngine.d.ts +29 -0
- package/dist/PlaywrightEngine.d.ts.map +1 -0
- package/dist/PlaywrightEngine.js +196 -0
- package/dist/PlaywrightEngine.js.map +1 -0
- package/dist/Replay.d.ts +47 -23
- package/dist/Replay.d.ts.map +1 -1
- package/dist/Replay.js +26 -30
- package/dist/Replay.js.map +1 -1
- package/dist/ReplayNodeSink.d.ts.map +1 -1
- package/dist/ReplayNodeSink.js +4 -1
- package/dist/ReplayNodeSink.js.map +1 -1
- package/dist/ReplayVitePlugin.d.ts +1 -0
- package/dist/ReplayVitePlugin.d.ts.map +1 -1
- package/dist/ReplayVitePlugin.js.map +1 -1
- package/dist/Session.d.ts +224 -18
- package/dist/Session.d.ts.map +1 -1
- package/dist/Session.js +571 -58
- package/dist/Session.js.map +1 -1
- package/dist/Verify.d.ts +150 -0
- package/dist/Verify.d.ts.map +1 -0
- package/dist/Verify.js +154 -0
- package/dist/Verify.js.map +1 -0
- package/dist/cli.js +157 -16
- package/dist/cli.js.map +1 -1
- package/dist/index.d.ts +3 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +3 -2
- package/dist/index.js.map +1 -1
- package/dist/internal/dependencyScan.d.ts +44 -0
- package/dist/internal/dependencyScan.d.ts.map +1 -0
- package/dist/internal/dependencyScan.js +313 -0
- package/dist/internal/dependencyScan.js.map +1 -0
- package/dist/internal/fuzzNetwork.d.ts +56 -0
- package/dist/internal/fuzzNetwork.d.ts.map +1 -0
- package/dist/internal/fuzzNetwork.js +96 -0
- package/dist/internal/fuzzNetwork.js.map +1 -0
- package/dist/internal/simulationCoverage.d.ts.map +1 -1
- package/dist/internal/simulationCoverage.js +2 -1
- package/dist/internal/simulationCoverage.js.map +1 -1
- package/dist/internal/skillLink.d.ts +14 -0
- package/dist/internal/skillLink.d.ts.map +1 -0
- package/dist/internal/skillLink.js +46 -0
- package/dist/internal/skillLink.js.map +1 -0
- package/dist/internal/values.d.ts +9 -1
- package/dist/internal/values.d.ts.map +1 -1
- package/dist/internal/values.js +11 -1
- package/dist/internal/values.js.map +1 -1
- package/dist/internal/verifyRunner.d.ts +19 -0
- package/dist/internal/verifyRunner.d.ts.map +1 -0
- package/dist/internal/verifyRunner.js +47 -0
- package/dist/internal/verifyRunner.js.map +1 -0
- package/dist/internal/version.d.ts +1 -1
- package/dist/internal/version.js +1 -1
- package/package.json +28 -3
- package/src/Desync.ts +40 -17
- package/src/Determinism.ts +49 -11
- package/src/Format.ts +101 -34
- package/src/Fuzz.ts +551 -0
- package/src/Invariant.ts +9 -2
- package/src/Lint.ts +11 -5
- package/src/PlaywrightEngine.ts +232 -0
- package/src/Replay.ts +100 -47
- package/src/ReplayNodeSink.ts +4 -1
- package/src/ReplayVitePlugin.ts +1 -0
- package/src/Session.ts +816 -73
- package/src/Verify.ts +276 -0
- package/src/cli.ts +150 -15
- package/src/index.ts +3 -2
- package/src/internal/dependencyScan.ts +356 -0
- package/src/internal/fuzzNetwork.ts +130 -0
- package/src/internal/simulationCoverage.ts +2 -1
- package/src/internal/skillLink.ts +53 -0
- package/src/internal/values.ts +20 -1
- package/src/internal/verifyRunner.ts +46 -0
- package/src/internal/version.ts +1 -1
- package/dist/Monitor.d.ts +0 -101
- package/dist/Monitor.d.ts.map +0 -1
- package/dist/Monitor.js +0 -602
- package/dist/Monitor.js.map +0 -1
- package/dist/internal/monitor.d.ts +0 -126
- package/dist/internal/monitor.d.ts.map +0 -1
- package/dist/internal/monitor.js +0 -279
- package/dist/internal/monitor.js.map +0 -1
- package/src/Monitor.ts +0 -713
- package/src/internal/monitor.ts +0 -370
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,288 @@
|
|
|
1
1
|
# @typeonce/ritmo-devtools
|
|
2
2
|
|
|
3
|
+
## 0.16.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- be9af72: `ritmo-devtools lint` notes when the project does not link the Ritmo skill from the installed package (`skill-not-linked`: neither `.agents/skills/ritmo` nor `.claude/skills/ritmo` links `node_modules/@typeonce/ritmo/skills/ritmo`), or holds a copy that goes stale on upgrade (`skill-copied`). Both are notes: the exit code is unchanged.
|
|
8
|
+
|
|
9
|
+
### Patch Changes
|
|
10
|
+
|
|
11
|
+
- 9b0379e: **Every JSDoc `@example` now compiles against the current API.** Examples are type-checked in CI as a game would import them, so they no longer cite exports that do not exist or call them with the wrong arguments. What changed in meaning:
|
|
12
|
+
|
|
13
|
+
- `Game.Runtime.make(...)` with a constructed resource (a `Clock.resource`, a `Descriptor.ConstructedResource`) returns a `Result` that may fail: the examples check `ok` instead of reading `.value`.
|
|
14
|
+
- A captured input resource is typed from its source: `Descriptor.TransientResource<InputCapture.SnapshotOf<typeof KeyboardInput>>()`, not `Keyboard.Snapshot<...>`.
|
|
15
|
+
- `Netcode.seats(...)` returns a `Result`: check it instead of `.value!`.
|
|
16
|
+
- `Lint.Target<typeof Game.schema, typeof Root>` takes the schema root second.
|
|
17
|
+
- `NodeRegistry.make` infers the node type from `attach`'s parameter, with no explicit generic.
|
|
18
|
+
|
|
19
|
+
- 9290521: Docs from upgrading two games across several versions:
|
|
20
|
+
|
|
21
|
+
- The skill's state-and-upgrades playbook lists the breaks that still compile, per version, and `SETUP.md` says a new lint rule is off until `.oxlintrc.json` lists it.
|
|
22
|
+
- The 0.13 `Decode` entry has a table from each `Decode` codec to Zod and Effect; handle schemas use `z.unknown().refine(Entity.isHandle(...))`, not `z.custom`.
|
|
23
|
+
- The `Snapshot.version` JSDoc says how to rewrite a format 2 save; `WorldSnapshot.relations` says targets are sorted by id while each target's sources keep their order.
|
|
24
|
+
- `ritmo-devtools lint`'s `uncovered-simulation-module` message names the usual cause: a host module imported at the top of the lint entry instead of inside `lintTarget`. The README shows a debug script reusing `lintTarget`.
|
|
25
|
+
- The `Replay` docs and the 0.15 changelog say how to keep a playtester's save button without the monitor: `recorder.save(reason)` from a key handler.
|
|
26
|
+
- `Touch.Layout` shows how to draw a layout with no `null` zones, and `Pointer.Actions` says to build test doubles with `Pointer.scripted`.
|
|
27
|
+
- The `use-ops-for-math` example uses `Angle.wrap` for a signed turn, and the spatial-grid reference defines its `made` helper.
|
|
28
|
+
|
|
29
|
+
- 9290521: A replay saved to disk verifies when the world holds `-0`. `runtime.checksum()` hashed `-0` apart from `0`, but JSON writes `-0` as `0`, so every replay read back from a file failed `Verify.acrossEngines` and `ritmo-devtools verify` ("DIVERGED at tick N") while the same replay verified in memory. `checksum()` now hashes `-0` as `0`, as a save writes it. Replays recorded before this fix with `-0` in the world still hold the old hashes: record them again.
|
|
30
|
+
|
|
31
|
+
`Desync.compare` and every devtools printout write `-0` with its sign, so a `-0` / `0` difference no longer reads `0 -> 0`.
|
|
32
|
+
|
|
33
|
+
- Updated dependencies [9b0379e]
|
|
34
|
+
- Updated dependencies [be9af72]
|
|
35
|
+
- Updated dependencies [9b0379e]
|
|
36
|
+
- Updated dependencies [9290521]
|
|
37
|
+
- Updated dependencies [9290521]
|
|
38
|
+
- Updated dependencies [9290521]
|
|
39
|
+
- Updated dependencies [1b55d21]
|
|
40
|
+
- @typeonce/ritmo@0.16.0
|
|
41
|
+
- @typeonce/ritmo-netcode@0.16.0
|
|
42
|
+
|
|
43
|
+
## 0.15.0
|
|
44
|
+
|
|
45
|
+
### Minor Changes
|
|
46
|
+
|
|
47
|
+
- 4c867ef: **Browser input replays and fuzzes through the one descriptor the page reads.** A game that declared its input service as the whole `Controls` merge (or a device) could not be opened from a replay or fuzzed: `playback.source(...)` hands back a plain `snapshot()` source, which has no `rebind` or `dispose`. Declare the service as `InputCapture.SourceOf<...>` the merge, device, or pool (its `snapshot()` only, still marked as draining, so systems keep reading the captured resource). The live merge provides it in the page, scripted devices in tests, `playback.source(ControlsInput)` in a replay, and `Fuzz.input` in the fuzzer; the page keeps the merge to rebind and dispose it.
|
|
48
|
+
|
|
49
|
+
```ts
|
|
50
|
+
const ControlsInput =
|
|
51
|
+
Descriptor.Service<
|
|
52
|
+
InputCapture.SourceOf<ReturnType<typeof makeControls>>
|
|
53
|
+
>()("Game/Controls");
|
|
54
|
+
const devices = { keyboard: Keyboard.idle(keys), gamepad: Gamepad.idle(pad) };
|
|
55
|
+
const Fuzzed = Fuzz.input(ControlsInput, {
|
|
56
|
+
generate: (random) => Actions.random(random, devices),
|
|
57
|
+
neutral: Actions.idle(devices),
|
|
58
|
+
});
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
- `Controls.actions(...).random(random, devices)` draws a merged snapshot a real merge could report: each button idle, held, just pressed, tapped, or just released, and each vector zero, one of eight directions, or a tilt shorter than 1. Device data stays as given, every action is available, and no device is last used.
|
|
62
|
+
- `Controls.players(...).random(random, frame, { devices, seats })` draws a pool's snapshot with the listed slots seated from frame 1 (reporting `event: "joined"` there, with idle input, as `pool.seat` in setup does) and their input drawn after. A pool is one source carrying every slot, because one `snapshot()` drains every pooled device and decides joins across them.
|
|
63
|
+
- `Replay.Playback.source` and `Fuzz.input` take any `snapshot()`-only source service, including ones that mark `snapshot()` with `System.Consumes` (`InputCapture.SourceOf`, `Netcode.Source`). A service declared as the whole device is a compile error naming the fix: "has more than snapshot(), so a replay cannot provide it". `Replay.SourceData<Value>` names the data a source returns.
|
|
64
|
+
|
|
65
|
+
- 45458dc: **A stream of the relation edges a target's despawn dropped.** When the target of a `Descriptor.Relation` despawns, the runtime removes every edge to it. A system now reads those edges once, with the same rules as `readRelationFailures`: each reader sees what was dropped since its own previous run, a reader gated by `when` drops what was published meanwhile, one under `pauseWhen` reads it later, a reader that fell behind by more than `Runtime.streamCapacity` records sees `lagged() === true`, and checkpoints rewind it.
|
|
66
|
+
|
|
67
|
+
```ts
|
|
68
|
+
const DropTargets = Game.System(
|
|
69
|
+
"Game/DropTargets",
|
|
70
|
+
{
|
|
71
|
+
droppedRelations: { lost: Game.System.readDroppedRelations(Targeting) },
|
|
72
|
+
commands: Game.System.commands(Game.System.inserts(Idle)),
|
|
73
|
+
},
|
|
74
|
+
({ droppedRelations, commands }) => {
|
|
75
|
+
for (const { source } of droppedRelations.lost.all())
|
|
76
|
+
commands.insert(source, [Idle, {}]);
|
|
77
|
+
}
|
|
78
|
+
);
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
- Records are `Relation.Relation.Dropped`: `{ relation, source, target }` as entity ids. Only a target's despawn records an edge: `commands.unrelate`, relating the source elsewhere, and the source's own despawn record nothing. A `Descriptor.Hierarchy` records nothing, since its children despawn with their parent.
|
|
82
|
+
- Inspectors can read `droppedRelations` too.
|
|
83
|
+
- Debug traces carry a `relationDropped` effect on the despawn that dropped the edge, and devtools journals it as `Game/Targeting from e7 to e12 dropped: e12 despawned`. `describe()` lists a system's `droppedRelations` (`reads dropped relations: ...` in devtools), and `streams()` reports the `droppedRelation` streams.
|
|
84
|
+
- **Breaking for code that switches over debug types:** `Debug.Effect` has a new `relationDropped` kind, `Debug.StreamStatus["kind"]` and `Debug.MissedRead["kind"]` have a new `droppedRelation` kind, and `Debug.SystemDescription` has a new `droppedRelations` field. Add the case to an exhaustive `switch`, and the field to a hand-built `SystemDescription`.
|
|
85
|
+
|
|
86
|
+
- c75daff: **Breaking: `Ops` and `Random` moved from `@typeonce/ritmo-math` into `@typeonce/ritmo`.** Determinism belongs to the runtime: every simulation needs same-bits math and a seeded generator, with or without the 2D helpers. The modules are unchanged; only the import path moves, and `@typeonce/ritmo-math` no longer exports them. The `Ops` header now states that its list is closed: the 22 functions engines may approximate and `**`; everything else on `Math` is already exact. `@typeonce/ritmo-devtools` and `@typeonce/ritmo-netcode` no longer depend on `@typeonce/ritmo-math`.
|
|
87
|
+
|
|
88
|
+
```diff
|
|
89
|
+
- import { Ops, Random } from "@typeonce/ritmo-math"
|
|
90
|
+
+ import { Ops, Random } from "@typeonce/ritmo"
|
|
91
|
+
- import * as Random from "@typeonce/ritmo-math/Random"
|
|
92
|
+
+ import * as Random from "@typeonce/ritmo/Random"
|
|
93
|
+
- import * as Ops from "@typeonce/ritmo-math/Ops"
|
|
94
|
+
+ import * as Ops from "@typeonce/ritmo/Ops"
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
`oxlint --fix` with `ritmo/use-ops-for-math` adds the new import where a `Math` call is rewritten; other imports need the path changed by hand.
|
|
98
|
+
|
|
99
|
+
- c20f20b: **Descriptor metadata: a field's unit, range, and hint next to its schema.** Every component and resource constructor (`Component`, `ConstructedComponent`, `TransientComponent`, `Resource`, `ConstructedResource`, `TransientResource`) takes an optional `meta` option keyed by the value's top-level fields. Each field gets `unit?: string`, `range?: readonly [min, max]` (number fields only), and `hint?: string` (one sentence an agent reads).
|
|
100
|
+
|
|
101
|
+
```ts
|
|
102
|
+
const Health = Descriptor.ConstructedComponent(z.object({ hp: z.number() }))(
|
|
103
|
+
"Game/Health",
|
|
104
|
+
{
|
|
105
|
+
meta: {
|
|
106
|
+
hp: {
|
|
107
|
+
unit: "points",
|
|
108
|
+
range: [0, 100],
|
|
109
|
+
hint: "Hit points left; 0 despawns the entity.",
|
|
110
|
+
},
|
|
111
|
+
},
|
|
112
|
+
}
|
|
113
|
+
);
|
|
114
|
+
const Tuning = Descriptor.Resource<{ speed: number }>()("Game/Tuning", {
|
|
115
|
+
meta: { speed: { unit: "px/s", range: [0, 400] } },
|
|
116
|
+
});
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
- A key that is not a field of the value does not compile (`not a field of this value`, with the value's fields under `fields`); `range` on a non-number field does not compile (`` `range` is only for number fields``); a key other than `unit`, `range`, or `hint` does not compile. A malformed option from an unchecked caller throws, naming the descriptor.
|
|
120
|
+
- Metadata never replaces validation: the schema still decides what is valid, and snapshots do not save it. It is checked once at the constructor, frozen, and listed by `runtime.debug.describe()` as `meta` on every `ComponentDescription` and `ResourceDescription` (`{}` when none).
|
|
121
|
+
- Resource constructors now take an options argument (`ResourceOptions`); `ComponentOptions` gains `meta`. New types: `FieldMeta`, `MetaField`, `CheckedMeta`, `CheckedOptions`, `MetaInput`.
|
|
122
|
+
- Devtools: `session.report()` raises an `out-of-range` warning for every write (system writes, resources, spawns, inserts) of a number outside its declared range: `e1 Game/Health.hp written as 120, declared range [0, 100] by Game/Heal at frame 42`. The scan runs only in debug sessions; production runtimes never read the metadata.
|
|
123
|
+
- Devtools: `session.describe()` lists each field's metadata under its component or resource; `Format.fieldMeta(field, meta)` prints one field's line. The monitor's Entity tab shows units next to values and each field's unit, range, and hint in the value's tooltip.
|
|
124
|
+
|
|
125
|
+
- c8320b4: **Entity labels in devtools output.** `Session.make(runtime, { ..., labels: Labels })` takes a `Game.Inspector` returning a `ReadonlyMap<number, string>` (entity id to label), and every entity in the session's text prints as `player e12` instead of `e12`: journal and `why` lines, `dump`, report warnings, and invariant messages (write entities as `e${id}` in the message). Labels are evaluated after every frame of a `run`, so a line shows the label its entity had at the end of that frame, and a despawned entity keeps its last label. They run only in the debug session: the runtime and production builds do not change.
|
|
126
|
+
|
|
127
|
+
```ts
|
|
128
|
+
const Labels = Game.Inspector(
|
|
129
|
+
"labels",
|
|
130
|
+
{
|
|
131
|
+
queries: {
|
|
132
|
+
players: Game.Query({
|
|
133
|
+
selection: { position: Game.Query.read(Position) },
|
|
134
|
+
with: [Player],
|
|
135
|
+
}),
|
|
136
|
+
},
|
|
137
|
+
},
|
|
138
|
+
({ queries }) =>
|
|
139
|
+
new Map(
|
|
140
|
+
queries.players
|
|
141
|
+
.each()
|
|
142
|
+
.map((match) => [match.entity.id, "player"] as const)
|
|
143
|
+
)
|
|
144
|
+
);
|
|
145
|
+
const session = Session.make(runtime, {
|
|
146
|
+
hostClock,
|
|
147
|
+
schedules: { update },
|
|
148
|
+
labels: Labels,
|
|
149
|
+
});
|
|
150
|
+
session.why(12, Position); // "player e12 Game/Position is now {x:4}; ..."
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
- An inspector returning anything else does not compile (`labels must return a ReadonlyMap<number, string> from entity id to label`); one reading a resource, service, or machine the runtime does not provide names it under `__fixLabelsRequirements__`, like invariants.
|
|
154
|
+
- `Replay.session(make, file, { labels })` and `Determinism.check(make, { ..., labels })` take the same inspector. A determinism difference inside an entity now carries `entity` (its id) and `label`.
|
|
155
|
+
- `Desync.compare(mine, theirs, { labels: runtime.inspect(Labels) })` names entities with the labels it is given. `Difference` gains `entity`.
|
|
156
|
+
- `Format.entity(id, labels)` is the one way devtools prints an entity; `Format.lines` and `Format.dump` take labels, and `Format.Line` gains `label`.
|
|
157
|
+
- A `run` whose labels inspector throws stops with `reason: "labels-threw"`.
|
|
158
|
+
- **Breaking: `Desync.compare` text prints entities as `e12` (`player e12` with labels), not `entity 12`.** `Difference.path` is unchanged; match on it, or on the new `entity`, instead of the text.
|
|
159
|
+
- **Breaking: `Determinism.check`'s factory returns the whole debug runtime** (`inspect`, `services`, `resourceValues`, `machineValues` as well as `debug` and `tryTick`), so `labels` is checked against its provisions. Return the `Game.Runtime.make(...).value` itself rather than an object picking `debug` and `tryTick`.
|
|
160
|
+
- **Breaking: `Session.Stop` has a new `labels-threw` reason.** An exhaustive `switch` on `stop.reason` adds the case.
|
|
161
|
+
|
|
162
|
+
- 14fbe8f: **`Fuzz.run` finds a bug before anyone plays into it, and shrinks it to a replay.** It builds a fresh simulation per run with the same `make(playback)` factory `Replay.session` opens replays with, feeds each fuzzed `snapshot()` source a value drawn from a seeded `Random` (from `@typeonce/ritmo`) every frame, and ticks the schedule in a `Session` until an invariant breaks, a system fails, or something throws. The failing timeline is then shrunk by delta debugging (ranges of frames dropped, then each value moved toward the input's `neutral`), re-running the simulation for every candidate, and returned as a `Found` error carrying the shrunk `Replay.ReplayFile`, the run's seed, the failing frame, and the shrink statistics; `Flaky`, `InvalidOptions`, and `Unreplayable` are the other failures. Declare an input with `Fuzz.input(Source, { generate: (random, frame) => value, neutral })`; the value is typed as the source's. `Replay.session(make, file, { invariants })` now checks invariants on every replayed tick, so the shrunk replay plays to the same violation and becomes the regression test. `Replay.Target` gains optional type parameters for the schedules and provisions, so the invariants are checked against the runtime at compile time.
|
|
163
|
+
|
|
164
|
+
```ts
|
|
165
|
+
const found = Fuzz.run(make, {
|
|
166
|
+
schedule: "update",
|
|
167
|
+
setup: "setup",
|
|
168
|
+
inputs: [Fuzz.input(PadInput, { generate, neutral: { key: 0 } })],
|
|
169
|
+
invariants: [Alive],
|
|
170
|
+
frames: 3000,
|
|
171
|
+
seed: 7,
|
|
172
|
+
});
|
|
173
|
+
if (!found.ok && found.error._tag === "Found") sink.save(found.error.replay);
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
- 7722666: **`Fuzz.run` fuzzes a rollback game over a faulty network with an optional `network`.** Declare every seat's input with `Fuzz.seats(Seats, { codec, count, idle, generate: (random, frame, seat) => input })` and pass `network: { seed, latencyMS, jitterMS, loss, step }`: each seat plays on its own peer (a fresh `make(playback)`, whose `playback.source(Seats)` is that peer's `seats.source`), joined by a seeded `MemoryNetworkLink` and driven by `Netcode.rollback` sessions, with invariants checked on every peer. A desync or any other session failure is the new `SessionFailed` violation (`seat`, and the `Netcode.SessionError`), and shrinking shrinks the input timeline one seat at a time with the network seed fixed. Over a network, a schedule that cannot be rewound or a runtime that cannot save does not compile, as for `Netcode.rollback`. Devtools now depends on `@typeonce/ritmo-netcode`.
|
|
177
|
+
|
|
178
|
+
`Fuzz.Violation` gains `SessionFailed`: a `switch` over it that must be exhaustive needs the new case:
|
|
179
|
+
|
|
180
|
+
```diff
|
|
181
|
+
case "Defect": return ...
|
|
182
|
+
+ case "SessionFailed": return `seat ${violation.seat}: ${violation.error._tag}`
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
- a9159bc: **Breaking: the live browser monitor is removed.** `Monitor` (`Monitor.attach`, `Monitor.Collector`, `recentSystem`, `recentSchedule`, and their types) is gone, with no replacement export: debugging is headless and text-first, and the package no longer needs the `DOM` lib. Record the browser session as a replay and debug it with a `Session`:
|
|
186
|
+
|
|
187
|
+
```diff
|
|
188
|
+
- Monitor.attach(runtime, { schedules, host: window, replay: recorder })
|
|
189
|
+
+ const recorder = Replay.recorder(runtime, { schedule: simulate, name: "simulate", keep: 30, step: STEP, sink: ReplayViteSink.make({ fetch: (url, init) => fetch(url, init) }), hostClock: BrowserHostClock.make(window), saveOn: { failure: true } })
|
|
190
|
+
+ // In Node: Replay.session(make, file.value) or Session.make(runtime, { hostClock: HostClock.test(), schedules }), then why / journal / report.
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
To find an entity without clicking it, give the session a `labels` inspector and filter `session.dump({ with: [Player] })`.
|
|
194
|
+
|
|
195
|
+
The monitor's "Save replay" button goes too. Bind `recorder.save(reason)` to a key or button in the host instead, so a playtester can still keep the last seconds: `window.addEventListener("keydown", (event) => { if (event.key === "F8") recorder.save("playtester pressed F8") })`.
|
|
196
|
+
|
|
197
|
+
- 01959dd: Step one frame a system at a time.
|
|
198
|
+
|
|
199
|
+
- `session.step(name)` begins one frame of a named schedule and returns a `SteppedFrame`: `until(System)` runs the steps before that system and stops there, `next()` runs exactly one step (a system or a marker), `check()` asks the invariants mid-frame, and `finish()` runs the rest and returns the same `RunResult` as `run(name, { frames: 1 })`, with labels and invariants evaluated at the end of the frame. `until` takes the system value, and only a system the schedule runs as a step compiles. `journal`, `why`, and `dump` show the partial frame.
|
|
200
|
+
- Core: `runtime.debug.beginFrame(schedule)` returns a `Debug.FrameCursor` (`next()`, `remaining()`) for the frame `tryTick(schedule)` would run, with the same commits, markers, reader cursors, and trace and host events. While a frame is open, `tick`, `tryTick`, `send`, `snapshot`, `checksum`, `restore`, `checkpoint`, `rewind`, and another `beginFrame` throw; `session.run` and `session.step` throw until `finish()`.
|
|
201
|
+
- `Format.step` prints one schedule step.
|
|
202
|
+
- `Session.Session` takes a third type parameter, the record of schedules, which `Session.make` infers.
|
|
203
|
+
|
|
204
|
+
- 89cc400: Add `ritmo-devtools verify <entry> <replay> --engines node,chromium,webkit,firefox`: plays a replay in Node (twice, and against its recording) and in real browser engines, and prints the first tick whose world differs with every value that differs there. Exit code 1 on a difference or an engine that did not run, 2 on a usage error; `--json` for JSON. `<entry>` exports `replayTarget`, the `make(playback)` factory `Replay.session` takes.
|
|
205
|
+
|
|
206
|
+
The same check from code is the new `Verify` module (`Verify.acrossEngines(make, file, { engines })`, returning `Verified` or `ReplayInvalid` / `NotVerified` with one `Agreed`, `Diverged`, `EngineMissing`, or `EngineFailed` outcome per engine), and the new `PlaywrightEngine` module (Node host) runs Chromium, WebKit, and Firefox headless. `playwright` and `vite` are optional peer dependencies, needed only for browser engines; `--engines node` needs neither.
|
|
207
|
+
|
|
208
|
+
- c75daff: **Breaking: `Replay.verify` is removed.** `Verify.acrossEngines(make, file)` is the one replay check: with no engines it plays the replay twice in this process and against the recording, as `Replay.verify` did; with engines it also runs browsers. It is async and fails with `NotVerified` (each outcome names the engine, tick, and values) instead of returning `deterministic: false`.
|
|
209
|
+
|
|
210
|
+
```diff
|
|
211
|
+
- const same = Replay.verify(make, file)
|
|
212
|
+
- expect(same.ok && same.value.data.deterministic).toBe(true)
|
|
213
|
+
+ const same = await Verify.acrossEngines(make, file)
|
|
214
|
+
+ expect(same.ok).toBe(true) // same.error.text says where it differs
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
**`ritmo-devtools scan <entry>` lists the determinism risks in dependencies.** oxlint skips `node_modules`, so a library the simulation calls can still use `Math.sin`. The scan resolves every file the simulation entry imports, `node_modules` included (with rolldown, which Vite 8 already brings), and runs `ritmo/use-ops-for-math`, `ritmo/use-clock-for-time`, and `ritmo/use-random-for-randomness` over them with the game's own oxlint. It prints the findings per package with `file:line:column`, or JSON with `--json`, and always exits 0 when it ran: it is a hint. `oxlint` and `rolldown` are optional peer dependencies.
|
|
218
|
+
|
|
219
|
+
```sh
|
|
220
|
+
ritmo-devtools scan src/simulation/index.ts
|
|
221
|
+
# fake-physics (2 findings)
|
|
222
|
+
# node_modules/fake-physics/index.js:4:17 ritmo/use-ops-for-math Math.sin
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
- 233b93f: **`why` follows the reads behind a value.** `session.why(entity, Component, { depth })` and `session.whyResource(Resource, { depth })` indent, under each change, what the writing system declared it reads and the latest traced fact that could have produced the value it saw: an event's sends since the system's previous run and their sender, the latest change of a component of the same entity (read in the query that wrote it), of a resource, or of a machine. Each `depth` step goes one system further back; `depth: 1`, the default, prints exactly what it printed before.
|
|
226
|
+
|
|
227
|
+
```ts
|
|
228
|
+
session.why(12, Health, { depth: 3 });
|
|
229
|
+
// f181 update Game/ApplyDamage write e12 Game/Health 70 -> 40
|
|
230
|
+
// read Game/Damage [{amount:30}] (declared), emitted by Game/Hitscan at f181
|
|
231
|
+
// read resource Game/Aim {target:12} (declared), written by Game/AimAtNewest at f180
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
- The trace records writes, not reads, so every such line ends in `(declared)`: a possible cause, not an observed read. A query over other entities prints only how many entities match it now (`read Game/Position of 14 matching entities now (declared; the trace does not say which it read)`).
|
|
235
|
+
- A system already in the chain prints `(cycle: not followed)`. `limit` also caps the reads under each line.
|
|
236
|
+
- `Session.WhyOptions` is the options type. `Format.Line` gains `depth` (0 for every journal line), `Format.LineKind` gains `read`, and `Format.line` prints a line with `depth` above 0 as its text, indented.
|
|
237
|
+
|
|
238
|
+
### Patch Changes
|
|
239
|
+
|
|
240
|
+
- d01a735: **Zod schemas work with Ritmo: the schema back to the saved form is under `"~encode"`, not `encode`.** Zod (from 4.1) gives every schema an `encode()` method, which Ritmo read as its encode schema: `Descriptor.ConstructedComponent(z.object(...))` did not compile, and with a cast `runtime.snapshot()` threw `Cannot read properties of undefined (reading 'validate')`. The key now starts with `~`, like Standard Schema's own `~standard`, so no library's methods collide with it. A Zod, Valibot, or ArkType schema of plain data passes as it is; Ritmo's tests now save and load a schema of each, and of Effect, through JSON.
|
|
241
|
+
|
|
242
|
+
- **Breaking: a codec carries its encode schema as `"~encode"`.** The Effect helper from the skill's `references/effect.md` (or a hand-written codec) renames the key:
|
|
243
|
+
|
|
244
|
+
```diff
|
|
245
|
+
return {
|
|
246
|
+
"~standard": Schema.toStandardSchemaV1(json)["~standard"],
|
|
247
|
+
- encode: Schema.toStandardSchemaV1(Schema.flip(json))
|
|
248
|
+
+ "~encode": Schema.toStandardSchemaV1(Schema.flip(json))
|
|
249
|
+
}
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
A transforming schema without it fails with `give it a ~encode schema back to the saved form`.
|
|
253
|
+
|
|
254
|
+
- **Values that transform** (a `Date`, a `Map`) save through a `"~encode"` from any library. Zod's comes from the new `references/zod.md` helper, built on Zod's own `safeEncode`: `Descriptor.ConstructedComponent(codec(z.codec(z.iso.datetime(), z.date(), { decode, encode })))`. With Valibot, ArkType, or any other Standard Schema library, write the reverse schema by hand:
|
|
255
|
+
|
|
256
|
+
```ts
|
|
257
|
+
const Born = Descriptor.ConstructedComponent({
|
|
258
|
+
"~standard": v.pipe(
|
|
259
|
+
v.string(),
|
|
260
|
+
v.isoTimestamp(),
|
|
261
|
+
v.transform((text) => new Date(text))
|
|
262
|
+
)["~standard"],
|
|
263
|
+
"~encode": v.pipe(
|
|
264
|
+
v.date(),
|
|
265
|
+
v.transform((date) => date.toISOString())
|
|
266
|
+
),
|
|
267
|
+
})("Game/Born");
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
- **Handles and deadlines inside a game's schema** are built from their guards with a schema that narrows to the guard's type: `z.unknown().refine(Entity.isHandle(Root))` in Zod, `v.pipe(v.unknown(), v.guard(...))` in Valibot, `type("unknown").narrow(...)` in ArkType, `Schema.declare(...)` in Effect. The docs said `z.custom(guard)`, which types the value as `unknown`.
|
|
271
|
+
|
|
272
|
+
- Updated dependencies [3a195b7]
|
|
273
|
+
- Updated dependencies [d01a735]
|
|
274
|
+
- Updated dependencies [45458dc]
|
|
275
|
+
- Updated dependencies [c75daff]
|
|
276
|
+
- Updated dependencies [b77b17d]
|
|
277
|
+
- Updated dependencies [c20f20b]
|
|
278
|
+
- Updated dependencies [01959dd]
|
|
279
|
+
- Updated dependencies [637fa1f]
|
|
280
|
+
- Updated dependencies [44e9b42]
|
|
281
|
+
- Updated dependencies [6b0d73e]
|
|
282
|
+
- Updated dependencies [7722666]
|
|
283
|
+
- @typeonce/ritmo@0.15.0
|
|
284
|
+
- @typeonce/ritmo-netcode@0.15.0
|
|
285
|
+
|
|
3
286
|
## 0.14.0
|
|
4
287
|
|
|
5
288
|
### Minor Changes
|