@typeonce/ritmo-devtools 0.6.0 → 0.7.0

package/src/Format.ts

@@ -119,6 +119,13 @@ export const system = (input: Debug.SystemDescription): string => {
   if (input.despawned) lines.push("  reads despawned")
   add("reads relation failures", input.relationFailures)
   add("services", input.services)
+  add("may spawn", input.commands.spawns)
+  add("may insert", input.commands.inserts)
+  add("may remove", input.commands.removes)
+  add("may despawn", input.commands.despawns)
+  add("may despawn scope", input.commands.despawnsScope)
+  add("may relate", input.commands.relates)
+  if (input.thisTick.length > 0) add("needs this tick", input.thisTick)
   add("when", input.when)
   add("pauses when", input.pauseWhen)
   if (input.local) lines.push("  local state")
@@ -269,6 +276,22 @@ export type LineKind =
   | "skip"
   | "transition"
   | "restore"
+  | "ignored"
+
+/**
+ * The text for a failed tick result nobody read: who failed, with what, how
+ * many later systems did not run, and when it was found unread.
+ */
+export const ignoredFailure = (event: Debug.FailureIgnoredEvent, options: ValueOptions = {}): string => {
+  const who = event.system === undefined ? `${event.schedule} did not run` : `${event.system} failed`
+  // A system failure shows what the system returned; anything else (missing requirements) as it is.
+  const error = typeof event.error === "object" && event.error !== null && (event.error as { readonly kind?: unknown }).kind === "SystemFailure"
+    ? (event.error as { readonly error: unknown }).error
+    : event.error
+  const later = `${event.skipped.length} later ${event.skipped.length === 1 ? "system" : "systems"} did not run`
+  const found = event.when === "next-tick" ? "not read before the next tick" : "not read before the session ended"
+  return `tick failure ignored: ${who} with ${value(error, options)}; ${later} (${found})`
+}
 
 /**
  * Structural equality for plain data: primitives by `Object.is`, arrays and
@@ -354,6 +377,8 @@ export const lines = (event: Debug.TraceEvent, options: ValueOptions = {}): Read
       return []
     case "restore":
       return [{ kind: "restore", frame: event.frame, schedule: "", system: undefined, entity: undefined, subject: undefined, noop: false, text: `restore ${event.ok ? "applied" : "rejected"}` }]
+    case "failure.ignored":
+      return [{ kind: "ignored", frame: event.frame, schedule: event.schedule, system: event.system, entity: undefined, subject: undefined, noop: false, text: ignoredFailure(event, options) }]
     case "transition":
       return [{
         kind: "transition",

package/src/Invariant.ts

@@ -1,28 +1,54 @@
 /**
  * Named world checks evaluated after every frame of a session run.
  *
- * A check returns a message describing the violation, or `undefined` when the
- * invariant holds. Read the world through `runtime.inspect(...)` with a
- * `Game.Inspector`, so the check stays typed and read-only.
+ * An invariant is a `Game.Inspector` whose projection returns a message
+ * describing the violation, or `undefined` when the invariant holds. The
+ * inspector declares its reads like a system and cannot write, so the check
+ * is typed and read-only, and `Session.make` rejects at compile time an
+ * invariant that reads a resource, service, or machine the runtime does not
+ * provide. The invariant is named after its inspector.
+ *
+ * Use `Invariant.fromInspector` for checks over the world during a session.
+ * Use `Game.Inspector` with `runtime.inspect(...)` directly for one-off reads
+ * in tests and scripts.
  *
  * @module Invariant
  * @docGroup devtools
  *
  * @example
  * ```ts
- * const PlayerInsideWorld = Invariant.make("player inside world", () => {
- *   for (const position of runtime.inspect(PlayerPositions)) {
- *     if (position.x < 0 || position.x > WORLD_WIDTH) return `player at x=${position.x}`
+ * const PlayerInsideWorld = Invariant.fromInspector(Game.Inspector("player inside world", {
+ *   queries: { players: Game.Query({ selection: { position: Game.Query.read(Position) }, with: [Player] }) }
+ * }, ({ queries }) => {
+ *   for (const { data } of queries.players.each()) {
+ *     const { x } = data.position.get()
+ *     if (x < 0 || x > WORLD_WIDTH) return `player at x=${x}`
  *   }
  *   return undefined
- * })
+ * }))
+ *
+ * const session = Session.make(runtime, { schedules: { update }, invariants: [PlayerInsideWorld] })
  * ```
  */
+import type * as Inspector from "@typeonce/ritmo/Inspector"
+
+export namespace Invariant {
+  /** An inspector usable as an invariant: it returns a violation message or `undefined`. */
+  export type CheckInspector = Inspector.InspectorDefinition<any, string | undefined, any, any, any>
+}
 
-export interface Invariant {
-  readonly name: string
-  /** A violation message, or `undefined` when the invariant holds. */
-  readonly check: () => string | undefined
+export interface Invariant<I extends Invariant.CheckInspector = Invariant.CheckInspector> {
+  /** The inspector's name, printed when the invariant is violated. */
+  readonly name: I["name"]
+  /** The read-only check: a violation message, or `undefined` when the invariant holds. */
+  readonly inspector: I
 }
 
-export const make = (name: string, check: () => string | undefined): Invariant => ({ name, check })
+/**
+ * Turns a `Game.Inspector` that returns `string | undefined` into an
+ * invariant for `Session.make({ invariants })`.
+ */
+export const fromInspector = <const I extends Invariant.CheckInspector>(inspector: I): Invariant<I> => ({
+  name: inspector.name,
+  inspector
+})

package/src/Lint.ts

@@ -0,0 +1,72 @@
+/**
+ * The static lints of a game's schedules, as a tool: `describe()`'s lints over
+ * a headless runtime, each with its fix, and a verdict (warnings fail, info
+ * does not).
+ *
+ * Run it from a game's `check` script with the CLI:
+ *
+ * ```sh
+ * ritmo-devtools lint src/simulation.ts
+ * ```
+ *
+ * The entry module exports `lintTarget`, a function that builds the game's
+ * headless runtime (made with `debug: { hostClock }`) and names its schedules: the
+ * ones ticked headless in `schedules`, and the ones that need a renderer or
+ * other host services in `describe` (described and linted, never run).
+ *
+ * Use `Session.make(...).describe()` instead to read the lints while
+ * debugging; this module is for the pass/fail check.
+ *
+ * @module Lint
+ * @docGroup devtools
+ *
+ * @example
+ * ```ts
+ * // src/simulation.ts
+ * export const lintTarget = (): Lint.Target<typeof Game.schema, typeof Game.schema> => {
+ *   const sim = createSimulation({ keyboard: Keyboard.scripted(bindings, []) })
+ *   return { runtime: sim.runtime, schedules: { setup: sim.setup, update: sim.update }, describe: { render } }
+ * }
+ * ```
+ */
+import type * as Debug from "@typeonce/ritmo/Debug"
+import type { AnyScheduleOrder, ExecutableScheduleDefinition } from "@typeonce/ritmo/Schedule"
+import type { Schema } from "@typeonce/ritmo/Schema"
+
+import * as Rendered from "./Rendered.ts"
+
+type AnySchedule<S extends Schema.Any, Root> = ExecutableScheduleDefinition<S, any, Root, any, any, AnyScheduleOrder>
+
+/** What `lintTarget` returns. */
+export interface Target<S extends Schema.Any, Root> {
+  /** A runtime made with `debug: { hostClock }`. */
+  readonly runtime: { readonly debug: Debug.Handle<S, Root> }
+  /** The schedules the game ticks, by name. */
+  readonly schedules: Readonly<Record<string, AnySchedule<S, Root>>>
+  /** Schedules to describe without running (a render schedule needing a renderer). */
+  readonly describe?: Readonly<Record<string, AnySchedule<S, Root>>>
+  /** Events the host publishes with `runtime.send` (UI requests, network messages): written, for the lints. */
+  readonly hostEvents?: ReadonlyArray<Schema.EventDescriptor<S>>
+}
+
+export interface Report {
+  readonly lints: ReadonlyArray<Debug.Lint>
+  readonly warnings: number
+  readonly infos: number
+  /** `true` when there is no warning-level lint. */
+  readonly ok: boolean
+}
+
+/** Lints the target's schedules. */
+export const run = <S extends Schema.Any, Root>(target: Target<S, Root>): Rendered.Rendered<Report> => {
+  target.runtime.debug.nameSchedules({ ...target.describe, ...target.schedules })
+  target.runtime.debug.declareHostEvents(target.hostEvents ?? [])
+  const lints = target.runtime.debug.describe().lints
+  const warnings = lints.filter((lint) => lint.severity === "warning").length
+  const report: Report = { lints, warnings, infos: lints.length - warnings, ok: warnings === 0 }
+  const lines = [
+    ...lints.flatMap((lint) => [`${lint.severity} ${lint.code} ${lint.subject}: ${lint.message}`, `  fix: ${lint.fix}`]),
+    `${warnings} ${warnings === 1 ? "warning" : "warnings"}, ${report.infos} info${warnings > 0 ? " (warnings fail)" : ""}`
+  ]
+  return Rendered.make(report, lines.join("\n"))
+}

package/src/Monitor.ts

@@ -14,7 +14,7 @@
  *
  * The monitor observes the runtime only while it is open, so a closed monitor
  * costs nothing. While open it reduces trace events to counts and shows its
- * own cost per tick. It needs a runtime made with `debug: true`.
+ * own cost per tick. It needs a runtime made with `debug: { hostClock }`, and the page passed as `host`.
  *
  * @module Monitor
  * @docGroup devtools
@@ -22,6 +22,7 @@
  * @example
  * ```ts
  * const monitor = Monitor.attach(runtime, {
+ *   host: window,
  *   schedules: { fixedUpdate: step, frame },
  *   pick: (event) => entityUnderPointer(event),
  *   locate: (entity) => screenPositionOf(entity)
@@ -30,7 +31,7 @@
  * ```
  */
 import type * as Debug from "@typeonce/ritmo/Debug"
-import type { ExecutableScheduleDefinition } from "@typeonce/ritmo/Schedule"
+import type { AnyScheduleOrder, ExecutableScheduleDefinition } from "@typeonce/ritmo/Schedule"
 import type { Schema } from "@typeonce/ritmo/Schema"
 
 import * as Format from "./Format.ts"
@@ -57,8 +58,14 @@ export interface Options<S extends Schema.Any, Root> {
    * panel and make up the system map. Name the schedule objects actually
    * passed to `tick`: nested schedules are flattened into them.
    */
-  readonly schedules: Readonly<Record<string, ExecutableScheduleDefinition<S, any, Root, any, any>>>
-  /** Where the panel is added. Defaults to `document.body`. */
+  readonly schedules: Readonly<Record<string, ExecutableScheduleDefinition<S, any, Root, any, any, AnyScheduleOrder>>>
+  /**
+   * The page the panel lives in, passed explicitly (`window`): its
+   * `document`, timers, animation frames, keyboard events, and
+   * `performance` clock. The monitor reads no globals.
+   */
+  readonly host: Window
+  /** Where the panel is added. Defaults to `host.document.body`. */
   readonly mount?: HTMLElement
   /** `KeyboardEvent.code` that toggles the panel. Defaults to `Backslash`. */
   readonly key?: string
@@ -70,6 +77,11 @@ export interface Options<S extends Schema.Any, Root> {
   readonly locate?: (entity: number) => { readonly x: number; readonly y: number } | undefined
   /** Milliseconds between panel refreshes. Defaults to 250. */
   readonly refreshMs?: number
+  /**
+   * A replay recorder (`Replay.recorder`): adds a "Save replay" button that
+   * saves the last seconds of play with the reason "Save replay button".
+   */
+  readonly replay?: { readonly save: (reason: string) => unknown }
 }
 
 export interface Monitor {
@@ -243,18 +255,19 @@ const STYLE = `
 export const attach = <S extends Schema.Any, Root>(runtime: Target<S, Root>, options: Options<S, Root>): Monitor => {
   const debug = runtime.debug
   debug.nameSchedules(options.schedules)
-  const mount = options.mount ?? document.body
+  const host = options.host
+  const mount = options.mount ?? host.document.body
   const key = options.key ?? "Backslash"
   const refreshMs = options.refreshMs ?? 250
 
-  if (document.getElementById("btm-style") === null) {
-    const style = document.createElement("style")
+  if (host.document.getElementById("btm-style") === null) {
+    const style = host.document.createElement("style")
     style.id = "btm-style"
     style.textContent = STYLE
-    document.head.append(style)
+    host.document.head.append(style)
   }
 
-  const root = document.createElement("div")
+  const root = host.document.createElement("div")
   root.className = "btm"
   root.innerHTML = `
     <button class="btm-toggle" type="button" title="Toggle the Ritmo monitor">◉ monitor</button>
@@ -264,6 +277,7 @@ export const attach = <S extends Schema.Any, Root>(runtime: Target<S, Root>, opt
         <button class="btm-tab" data-tab="overview" type="button">Overview</button>
         <button class="btm-tab" data-tab="systems" type="button">Systems</button>
         <button class="btm-tab" data-tab="entity" type="button">Entity</button>
+        ${options.replay === undefined ? "" : `<button class="btm-save-replay" type="button" title="Save the last seconds of play as a replay">Save replay</button>`}
         <button class="btm-close" type="button" title="Close">×</button>
       </div>
       <div class="btm-status"></div>
@@ -294,7 +308,7 @@ export const attach = <S extends Schema.Any, Root>(runtime: Target<S, Root>, opt
   let tab: Tab = "overview"
   let collector: Collector | undefined
   let stopObserving: (() => void) | undefined
-  let timer: ReturnType<typeof setInterval> | undefined
+  let timer: number | undefined
   let openedAt = 0
   let description: Debug.Description | undefined
   /** How many systems read each component, to name what systems spawn. */
@@ -515,20 +529,20 @@ export const attach = <S extends Schema.Any, Root>(runtime: Target<S, Root>, opt
 
   const render = () => {
     if (collector === undefined) return
-    const started = performance.now()
+    const started = host.performance.now()
     const history = collector.history
     const latest = history.slice(-RECENT)
     const overhead = latest.reduce((total, sample) => total + sample.overheadMs, 0)
     const ticks = latest.reduce((total, sample) => total + [...sample.schedules.values()].reduce((sum, window) => sum + window.ticks, 0), 0)
-    status.textContent = `observing for ${Math.round((performance.now() - openedAt) / 1000)}s · frame ${debug.frame()} · panel ${ticks === 0 ? "–" : number(overhead / ticks, 3)} ms/tick + ${number(renderMs, 1)} ms/refresh`
+    status.textContent = `observing for ${Math.round((host.performance.now() - openedAt) / 1000)}s · frame ${debug.frame()} · panel ${ticks === 0 ? "–" : number(overhead / ticks, 3)} ms/tick + ${number(renderMs, 1)} ms/refresh`
     status.title = "The panel's own work. Tracing (on only while the panel is open) also slows every system run a little, and the times shown include it: compare them with each other, not with a closed-monitor run."
     body.innerHTML = tab === "overview" ? renderOverview(history) : tab === "systems" ? renderSystems(history) : renderEntity()
-    renderMs = performance.now() - started
+    renderMs = host.performance.now() - started
   }
 
   const refresh = () => {
     if (collector === undefined) return
-    collector.sample(performance.now())
+    collector.sample(host.performance.now())
     render()
   }
 
@@ -539,7 +553,7 @@ export const attach = <S extends Schema.Any, Root>(runtime: Target<S, Root>, opt
       ring.style.left = `${at.x}px`
       ring.style.top = `${at.y}px`
     }
-    if (!panel.hidden) requestAnimationFrame(placeRing)
+    if (!panel.hidden) host.requestAnimationFrame(placeRing)
   }
 
   const setTab = (next: Tab) => {
@@ -555,14 +569,14 @@ export const attach = <S extends Schema.Any, Root>(runtime: Target<S, Root>, opt
     readers = new Map(description.access.components.map((entry) => [entry.name, entry.readers.length]))
     prefix = commonPrefix([...description.systems.map((system) => system.name), ...description.components.map((component) => component.name)])
     browse.replaceChildren(new Option("browse by component…", ""), ...description.components.map((component) => new Option(short(component.name), component.name)))
-    collector = new Collector(() => debug.population(), performance.now())
+    collector = new Collector(() => debug.population(), () => host.performance.now())
     collector.select(selected)
     stopObserving = debug.observe(collector.observe)
-    openedAt = performance.now()
+    openedAt = host.performance.now()
     panel.hidden = false
-    timer = setInterval(refresh, refreshMs)
+    timer = host.setInterval(refresh, refreshMs)
     setTab(tab)
-    requestAnimationFrame(placeRing)
+    host.requestAnimationFrame(placeRing)
   }
 
   const close = () => {
@@ -571,7 +585,7 @@ export const attach = <S extends Schema.Any, Root>(runtime: Target<S, Root>, opt
     ring.hidden = true
     stopObserving?.()
     stopObserving = undefined
-    if (timer !== undefined) clearInterval(timer)
+    if (timer !== undefined) host.clearInterval(timer)
     timer = undefined
     collector = undefined
     setPicking(false)
@@ -603,9 +617,9 @@ export const attach = <S extends Schema.Any, Root>(runtime: Target<S, Root>, opt
     picking = on
     pickButton.classList.toggle("is-on", on)
     pickButton.textContent = on ? "Click an entity… (Esc)" : "Pick on screen"
-    document.documentElement.classList.toggle("btm-picking", on)
-    if (on) window.addEventListener("pointerdown", onPick, { capture: true })
-    else window.removeEventListener("pointerdown", onPick, { capture: true })
+    host.document.documentElement.classList.toggle("btm-picking", on)
+    if (on) host.addEventListener("pointerdown", onPick, { capture: true })
+    else host.removeEventListener("pointerdown", onPick, { capture: true })
   }
 
   // ── Events ─────────────────────────────────────────────────────────────
@@ -620,9 +634,18 @@ export const attach = <S extends Schema.Any, Root>(runtime: Target<S, Root>, opt
       setPicking(false)
     }
   }
-  window.addEventListener("keydown", onKey)
+  host.addEventListener("keydown", onKey)
   toggleButton.addEventListener("click", () => (panel.hidden ? open() : close()))
   query<HTMLButtonElement>(".btm-close").addEventListener("click", close)
+  const replay = options.replay
+  if (replay !== undefined) {
+    const button = query<HTMLButtonElement>(".btm-save-replay")
+    button.addEventListener("click", () => {
+      replay.save("Save replay button")
+      button.textContent = "Saved"
+      host.setTimeout(() => { button.textContent = "Save replay" }, 1500)
+    })
+  }
   for (const button of root.querySelectorAll<HTMLButtonElement>(".btm-tab")) {
     button.addEventListener("click", () => setTab(button.dataset["tab"] as Tab))
   }
@@ -681,7 +704,7 @@ export const attach = <S extends Schema.Any, Root>(runtime: Target<S, Root>, opt
     select,
     detach: () => {
       close()
-      window.removeEventListener("keydown", onKey)
+      host.removeEventListener("keydown", onKey)
       root.remove()
     }
   }