FE-1835: Add a compiler from Petri nets to Zeroth reactive modules, with its playground

README.md

@@ -38,6 +38,7 @@ The `pocs` folder contains **proof of concepts** and other one-off experiments.
 - [`distributed_collab`](pocs/distributed_collab) - **Distributed Collab**: a BEAM VM based system for publishing/subscribing to JSON Patches with core logic implemented in Rust
 - [`hash-agents`](pocs/hash-agents) - **HASH Agents**: an experimental setup for writing Python-based 'agents' that interface with LLMs
 - [`hash_helm_chart`](pocs/hash_helm_chart) - **HASH Helm Charts**: An experimental [Helm](https://helm.sh) chart for deploying (now outdated, legacy) instances of HASH on Kubernetes
+- [`zeroth-playground`](pocs/zeroth-playground) - **Zeroth Playground**: a compiler from Petri nets to Zeroth reactive modules, with a playground that shows each net beside the Python it compiles to
 
 A number of older POCs can be found in our `hasharchives` organization, including:
 - [`wasm-ts-esm-in-node-jest-and-nextjs`](https://github.com/hasharchives/wasm-ts-esm-in-node-jest-and-nextjs) - A **Wasm + TypeScript + ESM in Node.js, Jest and Next.js 13** example project

pocs/zeroth-playground/.gitignore

@@ -0,0 +1,6 @@
+node_modules/
+dist/
+screenshots/
+*.log
+.DS_Store
+*.tmp.ts

pocs/zeroth-playground/AGENTS.md

@@ -0,0 +1,46 @@
+# AGENTS.md
+
+This repository holds a compiler from Petri nets to Zeroth reactive modules, the examples it is shown on, the open questions on what the compilation means, and a playground for all three. The input is a Petri net written in YAML as the Petri net IR. The output is Python that builds the modules with `zrth.sugar`, the Python DSL of Zeroth's reactive-modules library. The playground shows the IR, the Python, a preview of the net and a documentation page per example, and builds to one HTML file.
+
+| Folder | Holds |
+| --- | --- |
+| `compiler/` | the compiler, with its public API in `index.ts`. It imports nothing outside the folder but js-yaml and zod |
+| `examples/` | one folder per example net, and the catalog that collects them |
+| `semantics/` | one folder per open question on the semantics of the compilation, and the register that collects them |
+| `playground/` | the React app, which imports only `compiler/index.ts`, the examples and the semantics register |
+
+The compiler was copied from the HASH monorepo (hashintel/hash), and this copy is the one to change. The target DSL is `python/zrth/sugar.py` in [zeroth-research/reactive-modules](https://github.com/zeroth-research/reactive-modules), on its `spn` branch. That branch names the step method `next`; its `main` branch accepts only `update`.
+
+## Commands
+
+```bash
+pnpm install      # Node 24 or later
+pnpm exec playwright install chromium   # once, for pnpm screenshot and the headless checks
+pnpm dev          # http://localhost:5173, `#<example-id>` opens an example
+pnpm lint:tsc     # type-check, then check compiler/ on its own
+pnpm test         # unit tests (vitest)
+pnpm build        # dist/index.html, one self-contained file
+pnpm screenshot   # the listed examples and the Compiler view, into screenshots/
+ZRTH_PATH=/path/to/zrth pnpm check:zrth   # import every example's Python into zrth; not a gate
+```
+
+## Docs
+
+| File | Read it for |
+| --- | --- |
+| [compiler/README.md](compiler/README.md) | what the compiler reads and writes, one step of the net, the pipeline, the options and diagnostics, the code-parser hook, extending it |
+| [compiler/mapping.md](compiler/mapping.md) | the design shared by HASH and Zeroth: each mapping, its options, the open questions |
+| [examples/README.md](examples/README.md) | the example ladder, an example's folder and options, adding an example and its page |
+| [semantics/README.md](semantics/README.md) | the question register: the topics, a question's folder and status, adding a question |
+| [playground/README.md](playground/README.md) | the playground's folders, data flow and conventions, the single-file budget, the gates, the tests, checking the UI headlessly |
+
+## Rules
+
+- Settling a question, on either side, updates its folder in [semantics/](semantics/README.md) in the same change: its status in `meta.ts` and the decision on its page. [compiler/mapping.md](compiler/mapping.md) links the question and lists the tooling questions alone; a question listed there alone is updated there.
+- Keep the build to one HTML file that opens from `file://`. Measure the bundle before adding a dependency.
+- Write React as described in [playground/README.md](playground/README.md#conventions): `React.FC` constants with no React type imports, values derived in render, effects only for systems React does not own. `pnpm build` fails on every React Compiler diagnostic.
+- Write every test as GIVEN, WHEN, THEN, as [playground/README.md](playground/README.md#tests) describes.
+- Run `pnpm lint:tsc`, `pnpm test` and `pnpm build` before each commit. Check visible changes headlessly, as described in [playground/README.md](playground/README.md#checking-the-ui).
+- When these docs do not settle a decision, take the simplest option and say so in the commit message.
+- Commit messages: an imperative summary of the visible effect, then a body with the choices made.
+- A change to the structure, the pipeline, the example workflow or the question workflow updates the matching README in the same commit.

pocs/zeroth-playground/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

pocs/zeroth-playground/README.md

@@ -0,0 +1,33 @@
+# zeroth-playground
+
+This repository compiles a Petri net into Zeroth reactive modules, so that [zrth](https://github.com/zeroth-research/reactive-modules), Zeroth's reactive-modules library, can run and check it. The input is a net written in YAML as the Petri net IR; the output is Python that builds the modules with `zrth.sugar`.
+
+The playground shows the compiler at work on one screen: an example's documentation on the left, its IR in the middle, the Python module on the right and a preview of the net under them. It builds to one HTML file that opens from disk.
+
+## Running
+
+It needs Node 24 or later and pnpm.
+
+```bash
+pnpm install
+pnpm dev
+```
+
+`pnpm build` writes `dist/index.html`, one file with the JavaScript, the CSS, the fonts (Inter and JetBrains Mono) and the editor worker inlined, about 6.6 MB. It opens from `file://` and can be sent as an attachment. A comment at its top names every package and font it bundles, with the licence and the source of each. A URL hash names the example to open: `index.html#birth-death`.
+
+`pnpm test` runs the unit tests, `pnpm lint:tsc` type-checks, and `pnpm screenshot` opens the built file in Playwright's Chromium and screenshots the examples the picker lists, then the Compiler and Semantics views, at 1440×900 into `screenshots/`. Install that Chromium once with `pnpm exec playwright install chromium`.
+
+## What it does
+
+- **Views.** The IR editor has highlighting, completion of the IR's keys and places, and a hover that reads the IR trace. The module view lists the Python files and the diagnostics, each at the IR line of its item. The preview draws the net as an SVG laid out with elkjs.
+- **Options beside the IR.** The Compiler options panel under the IR editor holds the compiler options; the IR carries none. An option that does not apply to the net is greyed, with the reason. Each example opens with its own options, and Reset restores them with the text.
+- **Cross-highlighting.** Hovering a line in either editor lights the lines on the other side that name the same net item, and the item in the preview. Hovering a place or a transition in the preview lights its lines on both sides.
+- **The example ladder.** The examples climb from nets compiled in steps, plain or with coins, to nets compiled in continuous time under clocks, each adding one idea and named by it. The picker in the header lists them. Each has a page; most end with open questions, each naming who can settle it: HASH, Zeroth or both. Two pages carry a CSS animation, and *Rates as clocks* has an explorer with a Δt slider, a draw and the coin's rate.
+- **The Compiler view.** A switch in the header opens a guide, a graph of the pipeline's stages and a card per stage with a live sample from the open example. `#compiler`, or `#compiler/capacity`, opens it.
+- **The Semantics view.** The questions still open between HASH and Zeroth on what a net means as modules, grouped by topic. Each one quotes the Python that shows it today and opens the example that shows it. `#semantics`, or `#semantics/ties-under-clocks`, opens it.
+
+The coloured example, Bucket, carries a code string and is refused with `code-not-parsed`: reading the code back needs a parser built on the TypeScript compiler, far past the single-file budget. The picker leaves it out; `#bucket` opens it, with the refusal and the page.
+
+## Working on it
+
+[AGENTS.md](AGENTS.md) is the entry point for people and agents: commands, rules, and links to the READMEs of [compiler/](compiler/README.md), [examples/](examples/README.md) and [playground/](playground/README.md), and to [compiler/mapping.md](compiler/mapping.md), the design shared with Zeroth.