@flowsilver/algoviz 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,147 @@
-# Temporary Holding Version
+# AlgoViz
+
+**AI-Native Algorithm Execution Inspector**  
+*A local runtime for replaying and inspecting recorded algorithm executions.*
+
+## Try the offline preview
+
+Download the demo HTML from the [latest release](https://github.com/FlowSilver/AlgoViz/releases/latest) and open it in your browser. Step forward, step backward, or seek. Expand **State** to inspect the recorded values and use **Changes** to compare with the preceding recorded step.
+
+To generate the [knapsack preview](examples/knapsack/README.md) from a checkout with Node.js 22 or later:
+
+```sh
+npm ci
+npm run algoviz -- validate examples/knapsack/visualization.json examples/knapsack/trace.jsonl
+npm run algoviz -- preview examples/knapsack/visualization.json examples/knapsack/trace.jsonl
+```
+
+Open the printed `file://` URL. The generated HTML embeds the trace, spec, and inspector for offline use. Pass `--output preview.html` to choose a new file path.
+
+## What ships today
+
+- **Local validation and replay.** `validate` checks a JSON visualization spec and its JSONL execution trace. `preview` builds a self-contained inspector with synchronized views and timeline controls. [v1 protocol and replay API](docs/protocol.md)
+- **Side-by-side replay.** `compare` aligns two traces by episode and step in one offline HTML file. The FrozenLake example uses a custom grid renderer to investigate two verified 10,000-transition runs. [Record and compare FrozenLake](examples/frozenlake/README.md#compare-the-runs)
+- **Graph and Array views.** Graph edges support labels, and Array items can bind separate labels and values. The [BFS](examples/upstream-bfs/README.md) and [Dijkstra](examples/weighted-dijkstra/README.md) examples show graph state and frontier order. The [knapsack example](examples/knapsack/README.md#try-your-own-input) accepts a separate JSON input for capacity and items.
+- **Step inspection.** State shows the selected frame as JSON. Changes shows before and after values at the paths that changed from the preceding recorded step.
+- **Agent integration.** The [AlgoViz skill](.agents/skills/algoviz/SKILL.md) guides coding agents through choosing observation points, recording the trace, and verifying the result.
+
+## Positioning
+
+**AlgoViz is an extensible algorithm execution inspector and visualization runtime designed for AI coding agents.**
+
+A researcher or developer already has an algorithm and can simply ask their preferred coding agent:
+
+> “Use AlgoViz to visualize my pathfinding algorithm. Show the search space, frontier queue, and cost evolution.”
+
+The agent reads the existing algorithm, identifies meaningful internal states, and creates an adapter with minimal changes to the original implementation. The adapter records the run. AlgoViz validates and replays it with reusable renderers and inspection controls.
+
+AlgoViz **does not need a built-in LLM** and is not intended to replace coding agents such as Codex or Claude Code.
+
+## Why not just ask AI to generate a webpage?
+
+AlgoViz is designed for researchers and engineers who revisit algorithm runs and need reusable tooling for:
+
+- Inspecting state and changes at a known step across synchronized views.
+- Saving and sharing execution traces for offline replay.
+- Reusing the timeline, renderers, and validator across algorithms.
+
+The working hypothesis is that AI + AlgoViz reduces the effort to build and revise a reliable viewer. The [BFS pilot](benchmarks/README.md), [timed Dijkstra trial](benchmarks/dijkstra/README.md), and [FrozenLake comparison](benchmarks/frozenlake/README.md) report measurements.
+
+## Target users and use cases
+
+The primary audience is algorithm researchers, software engineers, and teams that need repeated access to internal execution state, including:
+
+- Graph search and path planning: expanded nodes, frontier queues, distances, and heuristic costs.
+- Dynamic programming and optimization: state tables, iterative convergence, and objective values.
+- Reinforcement learning and simulation: environment states, actions, rewards, and intermediate outcomes.
+- Novel algorithms: AI-generated adapters without requiring the algorithm to fit a predefined category.
+
+Educational sorting animations may be supported, but they are not the primary differentiator.
+
+## Adapt an algorithm
+
+1. The user asks an AI coding agent for a visualization in an existing repository.
+2. The agent inspects the algorithm and available state, then selects Graph, Array, or a locally registered custom renderer.
+3. The agent creates an **adapter** by reusing callbacks, logs, or iterators where possible and adding observation hooks where needed.
+4. The instrumented run produces an **Execution Trace**; the agent also generates a **Visualization Specification**.
+5. AlgoViz validates and loads both inputs, presenting an interactive execution inspector in the browser.
+6. The user saves or shares the trace and opens the offline HTML to inspect the run.
+
+> Principle: visualization should not alter the original algorithm's behavior. If an algorithm exposes only its final result, missing internal steps cannot be reconstructed reliably without additional instrumentation.
+
+## Architecture overview
+
+```text
+Existing algorithm (Python / C++ / Java / Rust / ...)
+                  │
+                  ▼
+AI Coding Agent ── AlgoViz docs, schemas, CLI / Skill
+                  │
+                  ▼
+Adapter / minimal instrumentation
+                  │
+           ┌──────┴───────────┐
+           ▼                  ▼
+    Execution Trace    Visualization Specification
+   (states and events)  (views, bindings, layout)
+           └──────┬───────────┘
+                  ▼
+           AlgoViz Runtime
+      validate · reconstruct · replay · sync
+                  │
+                  ▼
+  Graph and Array views · State and Changes panels
+                  │
+                  ▼
+        Browser-based Algorithm Inspector
+```
+
+### Three core abstractions
+
+- **State:** observable algorithm data at a particular step, modeled in a serializable way with stable identities.
+- **View:** declarative mapping from recorded data to a Graph, Array, or registered custom component.
+- **Transition:** state changes recorded in the trace, optionally augmented by semantic events for richer animation.
+
+### Two primary inputs
+
+| Input | Responsibility |
+| --- | --- |
+| **Visualization Specification** | Describes views, data sources, visual encodings, and layout without hard-coding algorithm names. |
+| **Execution Trace** | Records ordered state changes, optional semantic events, and metadata for deterministic replay. |
+
+Generic state updates are the source of truth for reconstruction. Semantic events such as `node.visit` or `array.swap` may enhance animations, but must not create a conflicting second state model.
+
+## Roadmap
+
+The [v0.4.0 milestone](https://github.com/FlowSilver/AlgoViz/milestone/4) tracks the FrozenLake comparison and npm publication. See the [development plan](OPEN_SOURCE_DEVELOPMENT.md#12-next-steps) and [open design questions](DECISIONS.md#open-design-questions) for what comes next.
+
+## Minimum viable product (v0.1.0)
+
+The first release established deterministic replay, the Graph and Array views, and an end-to-end adaptation of an existing BFS implementation. [v0.1.0 release](https://github.com/FlowSilver/AlgoViz/releases/tag/v0.1.0) · [First release scope](DECISIONS.md#v010-release-scope)
+
+## What success looks like
+
+The benchmark must be **asking AI to generate a standalone visualization directly**, not merely writing a frontend by hand. Measure time to first correct result, human interventions, correctness of displayed state, cost of adding views, value for comparing repeated runs, and performance on large traces.
+
+**Key question: for complex algorithms and iterative investigation, does AlgoViz actually make visualization easier and more reliable than AI-generated standalone code?**
+
+## Non-goals for now
+
+- Replacing AI coding agents or bundling a proprietary language model.
+- Automatically inferring every internal execution step from arbitrary untouched source code.
+- Providing a universal hosted compiler/runtime for all languages in the MVP.
+- Turning the DSL into a full frontend programming language with loops, functions, and arbitrary scripting.
+
+## Contributing
+
+Small algorithm examples with expected states and feedback on the [v1 protocol](docs/protocol.md) are welcome.
+
+- [Contributing guide](CONTRIBUTING.md) for opening issues and submitting changes.
+- [Design decisions](DECISIONS.md) and [development plan](OPEN_SOURCE_DEVELOPMENT.md) for the release scope and proposed backlog.
+- [Code of conduct](CODE_OF_CONDUCT.md) and [security policy](SECURITY.md) for reporting concerns.
+
+## License
+
+AlgoViz is licensed under the [Apache License 2.0](LICENSE).
+The vendored algorithms retain their upstream MIT licenses. [BFS license](examples/upstream-bfs/LICENSE-upstream.md) · [Dijkstra license](benchmarks/dijkstra/LICENSE-upstream.md) · [Knapsack license](examples/knapsack/LICENSE-upstream.md)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.

package/apps/inspector/comparison.js

@@ -0,0 +1,95 @@
+import { firstDifferentAction, indexRun } from "../../packages/core/comparison.js";
+import { attachInspection } from "./inspection.js";
+import { attachViews } from "./views.js";
+
+function attachRun(container, input, run, renderers, index) {
+  const panel = document.getElementById("comparison-run").content.firstElementChild.cloneNode(true);
+  const id = run.replay.seek(0).state.run?.id ?? `${index === 0 ? "Left" : "Right"} · ${input.traceSource}`;
+  panel.dataset.run = String(id);
+  panel.querySelector("h2").textContent = String(id);
+  container.append(panel);
+
+  const status = panel.querySelector("[data-run-status]");
+  const content = panel.querySelector("[data-run-content]");
+  const renderViews = attachViews(panel.querySelector(".views"), input.specText, renderers, index, "h3");
+  const inspect = attachInspection(run.replay, panel);
+  return (episode, step) => {
+    const entry = run.episodes[episode];
+    const available = entry && step < entry.actions.length;
+    content.hidden = !available;
+    panel.dataset.available = String(Boolean(available));
+    if (!available) {
+      status.textContent = entry ? `Episode ended at step ${entry.actions.length - 1}` : "Episode unavailable";
+      return;
+    }
+    const frame = run.replay.seek(entry.start + step);
+    const { last, status: outcome } = frame.state;
+    renderViews(frame);
+    inspect(frame);
+    status.textContent = last?.action
+      ? [last.action, typeof last.reward === "number" && `Reward ${last.reward}`, outcome].filter(Boolean).join(" · ")
+      : step === 0 ? "Episode start" : `Trace step ${frame.step}`;
+  };
+}
+
+export function startComparison(inputs, renderers, { seek, previous, next, stepLabel, error, showError }) {
+  const runs = inputs.map(indexRun);
+  const container = document.getElementById("comparison");
+  const form = document.getElementById("episode-form");
+  const episodeField = document.getElementById("episode");
+  const difference = document.getElementById("first-difference");
+  const lastEpisode = Math.max(...runs.map((run) => run.episodes.length)) - 1;
+  const show = inputs.map((input, index) => attachRun(container, input, runs[index], renderers, index));
+  let episode = 0;
+  let step = 0;
+  let differenceStep;
+
+  document.getElementById("single-run").hidden = true;
+  document.getElementById("source").textContent = "Run comparison";
+  container.hidden = false;
+  form.hidden = false;
+  difference.hidden = false;
+  episodeField.max = String(lastEpisode);
+
+  function lastStep(value) {
+    return Math.max(...runs.map((run) => run.episodes[value]?.actions.length ?? 0)) - 1;
+  }
+
+  function select(nextEpisode, nextStep) {
+    try {
+      for (const update of show) update(nextEpisode, nextStep);
+      if (nextEpisode !== episode || differenceStep === undefined) {
+        differenceStep = firstDifferentAction(runs, nextEpisode);
+      }
+      episode = nextEpisode;
+      step = nextStep;
+      const max = lastStep(episode);
+      episodeField.value = String(episode);
+      seek.max = String(max);
+      seek.value = String(step);
+      seek.disabled = max === 0;
+      previous.disabled = episode === 0 && step === 0;
+      next.disabled = episode === lastEpisode && step === max;
+      difference.disabled = differenceStep === undefined;
+      stepLabel.value = `Episode ${episode} · Step ${step} of ${max}`;
+      error.hidden = true;
+    } catch (cause) {
+      episodeField.value = String(episode);
+      seek.value = String(step);
+      showError(cause);
+    }
+  }
+
+  form.addEventListener("submit", (event) => {
+    event.preventDefault();
+    const value = episodeField.valueAsNumber;
+    if (Number.isInteger(value) && value >= 0 && value <= lastEpisode) select(value, 0);
+  });
+  difference.addEventListener("click", () => select(episode, differenceStep));
+  seek.addEventListener("input", () => select(episode, seek.valueAsNumber));
+  previous.addEventListener("click", () => step === 0
+    ? select(episode - 1, lastStep(episode - 1)) : select(episode, step - 1));
+  next.addEventListener("click", () => step === lastStep(episode)
+    ? select(episode + 1, 0) : select(episode, step + 1));
+  select(0, 0);
+}

package/apps/inspector/index.html

@@ -0,0 +1,71 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>AlgoViz</title>
+    <style>%STYLES%</style>
+  </head>
+  <body>
+    <main>
+      <header class="header">
+        <h1>AlgoViz</h1>
+        <span id="source"></span>
+      </header>
+      <div class="timeline" role="group" aria-label="Replay controls">
+        <form id="episode-form" class="episode-form" hidden>
+          <label>Episode <input id="episode" type="number" min="0" step="1" value="0" required></label>
+          <button type="submit">Go</button>
+        </form>
+        <div class="buttons">
+          <button type="button" id="previous" disabled>Previous</button>
+          <button type="button" id="next" disabled>Next</button>
+        </div>
+        <button type="button" id="first-difference" hidden disabled>First differing action</button>
+        <label class="seek" for="seek">
+          <span>Seek</span>
+          <input id="seek" type="range" min="0" max="0" value="0" disabled>
+        </label>
+        <output id="step" for="seek" aria-live="polite">Loading trace</output>
+      </div>
+      <p id="error" role="alert" hidden></p>
+      <div id="single-run">
+        <div id="views" class="views"></div>
+        <section class="inspection" aria-label="Step inspection">
+          <details id="state-panel" data-state-panel>
+            <summary>State</summary>
+            <pre id="state-json" data-state-json tabindex="0"></pre>
+          </details>
+          <details id="changes-panel" data-changes-panel open>
+            <summary>Changes</summary>
+            <div id="change-list" data-change-list></div>
+          </details>
+        </section>
+      </div>
+      <div id="comparison" hidden></div>
+      <template id="comparison-run">
+        <section class="comparison-run">
+          <header><h2></h2><p data-run-status></p></header>
+          <div data-run-content>
+            <div class="views"></div>
+            <section class="inspection" aria-label="Step inspection">
+              <details data-state-panel>
+                <summary>State</summary>
+                <pre data-state-json tabindex="0"></pre>
+              </details>
+              <details data-changes-panel open>
+                <summary>Changes</summary>
+                <div data-change-list></div>
+              </details>
+            </section>
+          </div>
+        </section>
+      </template>
+    </main>
+    <script type="application/json" id="preview-data">%DATA%</script>
+    <script>%SCRIPT%</script>
+    <!--
+%LICENSES%
+    -->
+  </body>
+</html>

package/apps/inspector/index.js

@@ -0,0 +1,61 @@
+import { loadReplay } from "../../packages/core/index.js";
+import { startComparison } from "./comparison.js";
+import { attachInspection } from "./inspection.js";
+import { attachViews } from "./views.js";
+
+const error = document.getElementById("error");
+const stepLabel = document.getElementById("step");
+const seek = document.getElementById("seek");
+const previous = document.getElementById("previous");
+const next = document.getElementById("next");
+
+function showError(cause) {
+  error.textContent = cause.message;
+  error.hidden = false;
+}
+
+function startSingle(input, renderers) {
+  const replay = loadReplay(input.traceText, input);
+  const root = document.getElementById("single-run");
+  const inspect = attachInspection(replay, root);
+  const renderViews = attachViews(document.getElementById("views"), input.specText, renderers, 0);
+  document.getElementById("source").textContent = input.traceSource;
+  seek.max = String(replay.lastStep);
+  seek.disabled = replay.lastStep === 0;
+
+  function render(frame) {
+    const { step } = frame;
+    renderViews(frame);
+    inspect(frame);
+    stepLabel.value = `Step ${step} of ${replay.lastStep}`;
+    seek.value = String(step);
+    previous.disabled = step === 0;
+    next.disabled = step === replay.lastStep;
+    error.hidden = true;
+  }
+
+  function navigate(action) {
+    try {
+      render(action());
+    } catch (cause) {
+      seek.value = String(replay.current.step);
+      showError(cause);
+    }
+  }
+
+  previous.addEventListener("click", () => navigate(() => replay.stepBackward()));
+  next.addEventListener("click", () => navigate(() => replay.stepForward()));
+  seek.addEventListener("input", () => navigate(() => replay.seek(seek.valueAsNumber)));
+  render(replay.current);
+}
+
+export function start(renderers) {
+  try {
+    const { runs } = JSON.parse(document.getElementById("preview-data").textContent);
+    if (runs.length === 2) startComparison(runs, renderers, { seek, previous, next, stepLabel, error, showError });
+    else startSingle(runs[0], renderers);
+  } catch (cause) {
+    stepLabel.value = "Trace unavailable";
+    showError(cause);
+  }
+}

package/apps/inspector/inspection.js

@@ -0,0 +1,62 @@
+function textElement(tag, text, className) {
+  const element = document.createElement(tag);
+  element.textContent = text;
+  if (className) element.className = className;
+  return element;
+}
+
+function changeValue(label, value, side) {
+  const field = document.createElement("div");
+  const content = value === undefined ? "Absent" : JSON.stringify(value, null, 2);
+  const block = textElement("pre", content, value === undefined ? "change-absent" : undefined);
+  block.dataset.changeSide = side;
+  field.append(textElement("span", label, "change-value-label"), block);
+  return field;
+}
+
+function renderChanges(changes, step) {
+  if (changes.length === 0) {
+    return textElement("p", step === 0 ? "Initial state" : "No state changes", "empty");
+  }
+
+  const list = document.createElement("ol");
+  list.className = "changes";
+  for (const change of changes) {
+    const row = document.createElement("li");
+    row.dataset.changePath = change.path;
+    row.dataset.changeKind = change.kind;
+    const heading = document.createElement("div");
+    heading.className = "change-heading";
+    heading.append(textElement("code", change.path), textElement("span", change.kind, "change-kind"));
+    const values = document.createElement("div");
+    values.className = "change-values";
+    values.append(changeValue("Before", change.before, "before"), changeValue("After", change.after, "after"));
+    row.append(heading, values);
+    list.append(row);
+  }
+  return list;
+}
+
+export function attachInspection(replay, root) {
+  const statePanel = root.querySelector("[data-state-panel]");
+  const changesPanel = root.querySelector("[data-changes-panel]");
+  const state = root.querySelector("[data-state-json]");
+  const changes = root.querySelector("[data-change-list]");
+  let frame;
+
+  function updateState() {
+    if (frame && statePanel.open) state.textContent = JSON.stringify(frame.state, null, 2);
+  }
+
+  function updateChanges() {
+    if (frame && changesPanel.open) changes.replaceChildren(renderChanges(replay.changes, frame.step));
+  }
+
+  statePanel.addEventListener("toggle", updateState);
+  changesPanel.addEventListener("toggle", updateChanges);
+  return (nextFrame) => {
+    frame = nextFrame;
+    updateState();
+    updateChanges();
+  };
+}