Revive Halo as a scoped React action runtime

.github/workflows/ci.yml

@@ -1,26 +1,35 @@
 name: CI
 
-on: push
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+permissions:
+  contents: read
 
 jobs:
-  build:
+  build-and-test:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-
-      - uses: actions/setup-node@v3
+      - name: Check out repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
 
-      - uses: thomashoneyman/setup-purescript@main
+      - name: Set up Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
-          purescript: "0.15.4"
-          spago: "0.20.9"
+          node-version: 22
+          cache: npm
 
-      - name: Cache PureScript dependencies
-        uses: actions/cache@v2
-        with:
-          key: ${{ runner.os }}-spago-${{ hashFiles('**/*.dhall') }}
-          path: |
-            .spago
-            output
+      - name: Install pinned tools
+        run: npm ci
+
+      - name: Check formatting
+        run: npm run format:check
+
+      - name: Build
+        run: npm run build -- --strict
 
-      - run: npm test
+      - name: Test
+        run: npm test

.gitignore

@@ -1,13 +1,5 @@
-/bower_components/
 /node_modules/
-/.pulp-cache/
 /output/
-/generated-docs/*
-!/generated-docs/md
-/generated-docs/md/*
-!/generated-docs/md/React.Halo.*
-/.psc-package/
-/.psc*
-/.purs*
-/.psa*
-/.spago
+/.spago/
+/.spec-results
+/generated-docs/

AGENTS.md

@@ -0,0 +1,35 @@
+# Repository instructions for agents
+
+Use this file as the repository control plane. Do not treat it as a substitute for the reader and maintainer documentation.
+
+## Read the relevant sources first
+
+For an unfamiliar task, route yourself by scope:
+
+- Read [README.md](README.md) for the product boundary and current public mental model.
+- Use the [guide index](docs/guide.md) to select the relevant public contract: [actions and state](docs/guide/actions-and-state.md), [managed work](docs/guide/managed-work.md), or [lifecycle and resources](docs/guide/lifecycle-and-resources.md).
+- Read [docs/architecture.md](docs/architecture.md) before changing runtime ownership, interpreters, concurrency, subscriptions, or error handling.
+- Read [CONTRIBUTING.md](CONTRIBUTING.md) for setup, validation, and pull request readiness.
+- Inspect [`React.Halo`](src/React/Halo.purs) and the public module that owns an API before changing its contract.
+- Inspect the corresponding modules under `test/Test/Halo/` before changing behavior; tests are executable contracts for runtime invariants.
+
+Before changing dependencies or developer commands, inspect `package.json`, `spago.yaml`, and `.github/workflows/ci.yml`. `package.json` owns tool pins and scripts; `spago.yaml` owns PureScript dependencies and the package set; CI owns automated pull request checks.
+
+## Preserve repository boundaries
+
+- Keep `React.Halo` as the intentional public API root. Keep the state-focused API in the separately qualified `React.Halo.Task`; do not flatten its generic names through the root. Do not expose internal runtime ownership types as a shortcut.
+- Keep React integration in the component/hook boundary and runtime ownership in `React.Halo.Internal.Runtime`. Read the architecture document instead of duplicating its rules here.
+- Keep application capabilities routed through the application monad and its `m ~> Aff` interpreter.
+- Do not add npm runtime dependencies or an npm runtime entry point. The npm package is development tooling only.
+- Update public docs, compile-checked examples, and focused deterministic tests when public behavior changes.
+- Do not hand-edit or commit `generated-docs/`, `output/`, `.spago/`, or `node_modules/`; they are ignored generated or dependency state.
+
+## Validate completion
+
+Use focused checks while iterating. Before declaring a repository change complete, run the full sequence in [CONTRIBUTING.md](CONTRIBUTING.md): format check, strict and pedantic build, full tests, and docs generation. Review the final diff, verify local documentation links, and run a whitespace check. Report any skipped, failed, or unavailable validation precisely.
+
+There is no real DOM fixture. Describe successful runtime tests and compile checks accurately; do not claim browser mounting coverage.
+
+## Require explicit approval for external actions
+
+Do not push commits, publish packages or documentation, create a release, edit GitHub or pull request state, or change any other external resource without current, action-specific authorization. Repository change approval does not imply release or publication approval.

CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# Contributing
+
+This guide covers local setup, validation, and pull request readiness. Start with the [README](README.md) for the public mental model, use the [guide index](docs/guide.md) to find the relevant usage chapter, and read the [architecture notes](docs/architecture.md) before changing runtime ownership or cancellation behavior.
+
+## Set up the checkout
+
+Use Node.js 22 with npm to match CI, then install the locked development tools:
+
+```console
+npm ci
+```
+
+`package.json` is the source of truth for tool pins and npm scripts. `spago.yaml` owns the PureScript dependencies and package set. CI owns the automated checks run for pull requests.
+
+Halo has no npm runtime entry point or npm runtime dependencies. Do not add an npm runtime dependency to provide behavior that belongs in PureScript or an existing PureScript package. Add or change PureScript dependencies in `spago.yaml`.
+
+## Develop and validate
+
+During implementation, run the smallest relevant build or test that gives useful feedback. Changes to runtime ownership, cancellation, subscriptions, interpreters, or public behavior need focused regression coverage in the corresponding test module.
+
+Before marking a pull request ready, run the full local validation sequence from the repository root:
+
+```console
+npm run format:check
+npm run build -- --strict --pedantic-packages
+npm test
+npx spago docs
+```
+
+Use `npm run format` to apply the repository formatter when the format check fails. A focused check helps iteration but does not replace the full sequence before review.
+
+The documentation command writes generated API pages to `generated-docs/`. Spago also writes build and dependency state to `output/` and `.spago/`. These paths are ignored; do not hand-edit or commit them.
+
+## Keep behavior, tests, and docs aligned
+
+`React.Halo` is the public API root; the generic state-focused names in `React.Halo.Task` form a separate qualified surface. When a change affects either module's exported types or behavior:
+
+- update the relevant public module documentation;
+- update the README or guide when their guidance changes, and keep exact API contracts in public source comments used by generated documentation;
+- keep examples in `test/Test/Halo/DocExamples.purs` compiling; and
+- add or update deterministic tests for the changed invariant.
+
+Use [docs/architecture.md](docs/architecture.md) to find the runtime contract and the tests that protect it. The runtime tests exercise ownership directly without a real DOM fixture, so report validation as runtime or compile coverage rather than as a mounted-browser test.
+
+Documentation-only changes still require link inspection and documentation generation. Run the complete validation sequence when preparing the pull request so CI-facing code, examples, and package checks remain covered.
+
+## Check pull request readiness
+
+Before requesting review, confirm that:
+
+- the change is focused and its public effect is clear;
+- formatting, strict and pedantic build, full tests, and docs generation pass;
+- public API changes include matching documentation and tests;
+- generated or dependency output is not staged; and
+- the final diff contains only intended files and no whitespace errors.