|
| 1 | +# Known issues — deferred to post-Rust-port |
| 2 | + |
| 3 | +## Demos disabled in `docs:build` pending API migration |
| 4 | + |
| 5 | +**Symptom:** `pnpm run docs:build` previously ran 4 demos under `demos/`; 3 of them now fail with errors like `"state" is not exported by ... dist/core/index.js, imported by src/lib/counter.ts`. |
| 6 | + |
| 7 | +**Cause:** The standalone `state` / `derived` / `producer` / `effect` exports were removed from `packages/pure-ts/src/core/sugar.ts` at some point during the Graph narrow-waist refactor (per `project_graph_narrow_waist.md` memory). The "Graph narrow-waist" decision moved these to Graph methods (`Graph.state()` / `Graph.derived()` / `Graph.effect()` / `Graph.produce()`), but the migration of demos / examples / generated docs that still consume the old standalone API was never completed. |
| 8 | + |
| 9 | +**Affected callers** (NOT migrated yet): |
| 10 | +- `demos/compat-matrix/src/lib/counter.ts` |
| 11 | +- `demos/knowledge-graph/src/lib/{lazy-adapter.ts, chapters/reactive.ts}` |
| 12 | +- `demos/pagerduty-triage/src/lib/pipeline.ts` |
| 13 | +- `examples/basic/state-and-derived/index.ts` |
| 14 | +- `examples/framework/{react,solid,svelte,vue}/src/store.ts` |
| 15 | +- `examples/{harness-refine-hello, inbox-reducer, knowledge-graph, reactive-layout, spending-alerts}/*.ts` |
| 16 | +- `packages/cli/tests/dispatch.test.ts` (not in `pnpm test` path; not blocking) |
| 17 | +- `packages/mcp-server/tests/tools.test.ts` (not in `pnpm test` path; not blocking) |
| 18 | +- 100+ generated `website/src/content/docs/api/*.md` (auto-regenerated; will heal once symbols are re-added or REGISTRY is migrated) |
| 19 | +- `website/scripts/gen-api-docs.mjs` REGISTRY (218 entries point at the missing symbols) |
| 20 | + |
| 21 | +**Workaround in place:** Root `package.json` `docs:build` script skips the 3 broken demos (`compat-matrix`, `knowledge-graph`, `pagerduty-triage`) and only builds `reactive-layout`. CI is unblocked but the demos are NOT shipped to the website's static output. |
| 22 | + |
| 23 | +**Decision deferred to:** post-Rust-port (after M5 close + facade build, per PART 13 of `archive/docs/SESSION-rust-port-architecture.md`). Two paths: |
| 24 | +- **A — Re-add standalone `state`/`derived`/`producer`/`effect`** as thin wrappers around `node()` in `core/sugar.ts`. Restores public surface; coexists with Graph methods. Minimal surgery, restores 100+ callers. |
| 25 | +- **B — Migrate every caller** to Graph methods. Heavier, changes demo/example pedagogical surface (every demo grows a Graph instance). |
| 26 | + |
| 27 | +Path A is the cheaper restore. Punt the decision until after the Rust port settles the API surface, since some of those callers may also be affected by other API churn. |
| 28 | + |
| 29 | +## Restoring this when ready |
| 30 | + |
| 31 | +1. Pick A or B and execute. |
| 32 | +2. Edit root `package.json` `docs:build` script to restore the 3 demos: |
| 33 | + ``` |
| 34 | + pnpm build && pnpm --dir website build && \ |
| 35 | + pnpm --dir demos/compat-matrix build && \ |
| 36 | + pnpm --dir demos/reactive-layout build && \ |
| 37 | + pnpm --dir demos/knowledge-graph build && \ |
| 38 | + pnpm --dir demos/pagerduty-triage build && \ |
| 39 | + cp -r demos/compat-matrix/dist/. website/dist/demos/compat-matrix/ && \ |
| 40 | + cp -r demos/reactive-layout/dist/. website/dist/demos/reactive-layout/ && \ |
| 41 | + cp -r demos/knowledge-graph/dist/. website/dist/demos/knowledge-graph/ && \ |
| 42 | + cp -r demos/pagerduty-triage/dist/. website/dist/demos/pagerduty-triage/ |
| 43 | + ``` |
| 44 | +3. Delete this section from `known-issues.md`. |
0 commit comments