Skip to content

feat: Circuit diagram style, embed fix, strict-typed core and unit tests - #6

Merged
lam0819 merged 2 commits into
mainfrom
feat/circuit-style-tests-strict
Nov 18, 2026
Merged

lam0819 merged 2 commits into
mainfrom
feat/circuit-style-tests-strict

Conversation

@lam0819

@lam0819 lam0819 commented Nov 17, 2026

Copy link
Copy Markdown
Contributor

Summary

  • New Circuit diagram style, based on the reference screenshot: a dark board, flat chip-shaped blocks with an inset top and pins, thin steel-blue lines, plain capital labels and a light-blue highlight. It works in 2D, 3D and Snapshot.
  • Embed fix: /embed/3d could not load Three.js, and 3D client links (/3d/) returned 404. Both work now, with or without a trailing slash.
  • PHPStan level 10 equivalent, enforced: the shared core (helpers, markdown reader, all 23 Mermaid parsers, layout, diagram styles and settings UI) is fully typed and must have 0 TypeScript strict-mode errors. That rule has no baseline.
  • Testable: new npm test unit tests run in CI.

Six diagram styles

Bugs found and fixed

Bug Where Fix
The 3D embed (/embed/3d, /embed/3d/) could not load vendor/three.module.js, so it showed nothing. Fonts and favicons were also 404 under /embed/. server.js Pages under /3d/, /embed/ and /embed/3d/ now find their relative assets.
"Copy client link" in 3D produced …/3d/, which returned 404. link helpers Links are built without a trailing slash (pageUrl()), and the server accepts both forms.
A ZenUML participant declared by name only (a line with just Alice) crashed the parser. parseZen if(m=a&&b) assigned a boolean and read m[1] before m was set. Fixed, with a regression test. Found by the strict types.
server.js also served package.json, and could serve tools/, server.js and any dotfiles if deployed. server.js Private files are refused. Malformed URLs and NUL bytes give 404.

Code checks (npm run check, also in CI)

Step Must be
Shared core in sync (tools/sync-parser.py --check) in sync
ESLint, including tests/ 0 problems
TypeScript checkJs on the page scripts, plus server.js, tools/ and tests/ in strict mode 0 errors
TypeScript strict on the page scripts shared core: 0 (no baseline); rest: no new errors. The baseline went from 1,995 to 809.
npm test (node:test, 63 tests) all pass

How it's organised:

  • The whole shared core is now one block, copied from index.html into 3d.html by tools/sync-parser.py. The only difference between the pages, layout spacing, comes from IS_3D_PAGE.
  • JSDoc typedefs cover the data model: FxNode, FxLink, Step, Graph, Scene, MdDoc, DiagramStyle, plus per-parser types.
  • tests/load-core.mjs evaluates the shared core straight out of index.html in a Node VM, so the pages stay standalone files and the logic is still unit-testable.
  • tests/parser.snapshot.json pins the parsed output (nodes, links, step text) of every example. All typing changes were made against that snapshot, so the parser output did not change except the one bug fix. To accept an intended change, run npm run test:update.

Testing

  • npm run check passes.
  • In headless Chromium, all 24 examples load in 2D and 3D across all six styles without errors.
  • Snapshot exports work in Circuit style, in 2D and 3D.
  • With node server.js, the client and embed links from 2D and 3D load without errors or 404s, both with and without a trailing slash, and inside an iframe.

Refs AHL-571.

🤖 Generated with Claude Code

solutionforest team and others added 2 commits November 17, 2026 19:30
- /3d/, /embed/ and /embed/3d/ (trailing slash) now serve the pages, and
  vendor/, fonts and favicons requested relative to those paths are
  found. Before, the 3D embed could not load Three.js and 3D client
  links (/3d/) were 404.
- Never serve dotfiles, node_modules, package/tsconfig files, tools/,
  tests/ or server.js; reject malformed URLs and NUL bytes.
- Export resolveFile/handle and only listen when run directly, so the
  routes are unit-tested (tests/server.test.mjs).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Circuit style: dark board, flat chip-shaped blocks with an inset top
  and pins (2D and 3D), thin steel-blue lines, plain monospace capital
  labels, light-blue highlight.
- Client and embed links are built without a trailing slash (pageUrl).
- The whole shared core (helpers, markdown + 23 Mermaid parsers, layout,
  diagram styles/settings UI) is one synced block and is fully typed
  with JSDoc: 0 TypeScript strict-mode errors, enforced with no baseline.
  The baseline for the rest went from 1995 to 809.
- Bug found by the strict types: a ZenUML participant declared by name
  only (e.g. a line with just Alice) crashed the parser (assignment
  precedence in if(m=...&&...)). Fixed, with a regression test.
- Unit tests (node:test): every example parses into a valid graph,
  behaviour tests per new type, parser-output snapshot, style
  completeness, 3d core equals index core, server routes. Run in CI.
- server.js, tools and tests are type-checked in strict mode.
- README: Circuit style, Code checks section; AGENTS notes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@lam0819
lam0819 merged commit 7b26cfa into main Nov 18, 2026
1 check passed
@lam0819
lam0819 deleted the feat/circuit-style-tests-strict branch November 18, 2026 01:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant