FE-1129: Token encoding playground (Storybook)

[kube]

🌟 What is the purpose of this PR?

Adds a dev-only Storybook playground for inspecting how token values are encoded into the simulation frame buffers: define a colour's dimensions, author a token value in a typed Monaco editor, and see the exact bits stored — with coercion round-trips made visible (input 2.7 → stored 3 → reads back 3).

It doubles as the visual testbed for the packed-struct token layout (format v2, follow-up PR), and lands a small enabler: the token value codec is now exported from @hashintel/petrinaut-core instead of being duplicated in UI components.

🔗 Related links

• FE-1129: Petrinaut: token encoding playground (Storybook) (internal)
• Stacked on H-6519: Add discrete token attribute types #8764; the format-v2 PR stacks on this one.

🚫 Blocked by

• H-6519: Add discrete token attribute types #8764 (base branch — merges first)

🔍 What does this change?

• Exports the token value codec (coerceTokenAttributeValue, coerceTokenRecord, encodeTokenAttributeValue, decodeTokenAttributeValue, decodeTokenRecord, defaultTokenAttributeValue) and compileUserCode from @hashintel/petrinaut-core; the spreadsheet and initial-state editors reuse defaultTokenAttributeValue instead of local switches.
• Adds src/ui/dev/token-encoding-playground/ with a Storybook story (Dev / Token Encoding Playground):
  • store-free dimensions editor (name + Real/Integer/Boolean select);
  • Monaco value editor (export default Token(() => ({ … }))) typed against declarations generated live from the dimensions;
  • a compact memory view: one byte (8 bits) per row grouped by slot, one colour per field with IEEE-754 anatomy shading (sign/exponent/mantissa), hatched padding, hover highlights the whole slot and reveals offset/size/hex and the coercion round-trip in a side panel; toggle between logical (MSB→LSB) and little-endian memory byte order.
• Evaluation runs the real product pipeline (compileUserCode + the real codec), debounced, with errors displayed inline.
• Monaco's built-in TypeScript language service is imported for the playground only and strictly scoped to its mount: silenced at module load, enabled while mounted, disabled with markers cleared on unmount — so it never shadows the SDCPN LSP in the product's editors (verified: opening the playground then an LSP-backed editor story shows zero foreign diagnostics).

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

This PR:

• modifies an npm-publishable library and I have added a changeset file(s)

📜 Does this require a change to the docs?

The changes in this PR:

• are internal and do not require a docs change
  • (dev-only Storybook tooling — explicitly out of scope for the user guide)

🕸️ Does this require a change to the Turbo Graph?

The changes in this PR:

• do not affect the execution graph

⚠️ Known issues

• The playground evaluates authored code in-page (same compileUserCode pipeline and same-realm sandboxing posture as the product's code surfaces) — acceptable for a dev tool, not a hardened boundary.

🐾 Next steps

• Format v2 (packed struct token layout) stacks on this PR and switches the playground to render the real engine layout module.
• 128-bit field rendering (UUID, FE-1121) once that type lands.

🛡 What tests cover this?

• libs/@hashintel/petrinaut/src/ui/dev/token-encoding-playground/physical-layout.test.ts (layout ordering/padding/stride, encode/decode round-trips, IEEE-754 bit extraction)
• Full test:unit, lint:tsc (tsgo), lint:eslint (oxlint) for both petrinaut packages

❓ How to test this?

1. yarn dev in libs/@hashintel/petrinaut, open Dev / Token Encoding Playground.
2. Edit dimensions (add a Boolean, rename one) — the editor's Token type updates live; wrong-typed values get squiggles.
3. Enter count: 2.7 — the memory view shows the stored value 3 and the round-trip line.
4. Hover slots/legend chips — whole-slot highlight + details panel.
5. Open Components / CodeEditor / With LSP afterwards — no stray TypeScript diagnostics on the product editor.

📹 Demo

The story itself is the demo — screenshots in the Storybook story render exactly what reviewers will see locally.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hash	Ready	Preview, Comment	Jul 7, 2026 10:41am
petrinaut	Ready	Preview, Comment	Jul 7, 2026 10:41am

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hashdotdesign-tokens	Ignored	Preview	Jul 7, 2026 10:41am

[cursor]

PR Summary

Low Risk
Changes are mostly dev-only UI and additive public exports; Monaco global worker/config patching is scoped to playground mount/unmount with explicit LSP isolation.

Overview
Exports the simulation token value codec (encode/decode/coerce, defaultTokenAttributeValue) and compileUserCode from @hashintel/petrinaut-core, with a patch changeset. Spreadsheet and initial-state editors now call defaultTokenAttributeValue instead of local type switches.

Adds a Dev / Token Encoding Playground Storybook story: edit colour dimensions, author Token(() => ({ … })) in Monaco with live-generated types, and inspect encoded bytes via v1 (uniform f64) or v2 (packed struct) layouts using the real codec and compileUserCode (debounced). A memory view shows per-field bits, padding, IEEE-754 shading, and input → stored → decoded round-trips.

Monaco’s built-in TypeScript service is enabled only while the playground is mounted (worker routing + extra libs), then disabled and markers cleared so it does not compete with the SDCPN LSP. Unit tests cover layout, encode/decode, and bit/hex helpers.

^{Reviewed by Cursor Bugbot for commit 77540f0. Bugbot is set up for automated code reviews on this repo. Configure here.}

[Copilot]

Pull request overview

Adds a dev-only Storybook playground in @hashintel/petrinaut for inspecting how typed token values are coerced/encoded into simulation buffers, and moves the “token value codec” + compileUserCode to public exports in @hashintel/petrinaut-core so UI surfaces can reuse the canonical defaults/encoding logic.

Changes:

• Exported token value codec helpers and compileUserCode from @hashintel/petrinaut-core (with a changeset) and reused defaultTokenAttributeValue in UI editors.
• Added a new Storybook “Dev / Token Encoding Playground” with a dimensions editor, Monaco-based typed token editor, and a byte/bit memory visualization for v1 vs planned v2 layouts.
• Added unit coverage for layout/padding, encode/decode round-trips, and IEEE-754 bit extraction.

Reviewed changes

Copilot reviewed 11 out of 12 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
libs/@hashintel/petrinaut/src/ui/views/Editor/panels/PropertiesPanel/place-properties/subviews/place-initial-state/initial-state-editor.tsx	Reuses defaultTokenAttributeValue from core instead of local defaults logic.
libs/@hashintel/petrinaut/src/ui/components/spreadsheet.tsx	Reuses defaultTokenAttributeValue for spreadsheet default cell values.
libs/@hashintel/petrinaut-core/src/index.ts	Re-exports token codec helpers + compileUserCode from the core package entrypoint.
.changeset/token-codec-exports.md	Versions the public API change (core minor, petrinaut patch).
libs/@hashintel/petrinaut/src/ui/dev/token-encoding-playground/token-encoding-playground.tsx	Implements the playground UI and debounced evaluation pipeline.
libs/@hashintel/petrinaut/src/ui/dev/token-encoding-playground/token-memory-view.tsx	Renders encoded token bytes/bits with hover-driven field detail.
libs/@hashintel/petrinaut/src/ui/dev/token-encoding-playground/physical-layout.ts	Computes v1/v2 layouts and encodes/decodes tokens via the real core codec.
libs/@hashintel/petrinaut/src/ui/dev/token-encoding-playground/dimension-editor.tsx	Store-free dimension/type editor for the playground.
libs/@hashintel/petrinaut/src/ui/dev/token-encoding-playground/playground-monaco.ts	Adds Story-scoped Monaco TypeScript contribution wiring + token type defs generation.
libs/@hashintel/petrinaut/src/ui/dev/token-encoding-playground/monaco-typescript.d.ts	Declares minimal types for Monaco TS contribution APIs used by the playground.
libs/@hashintel/petrinaut/src/ui/dev/token-encoding-playground/token-encoding-playground.stories.tsx	Registers the Storybook story under “Dev / Token Encoding Playground”.
libs/@hashintel/petrinaut/src/ui/dev/token-encoding-playground/physical-layout.test.ts	Adds unit tests for layout, round-trips, and bit/hex inspection.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 12 changed files in this pull request and generated 4 comments.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 12 changed files in this pull request and generated 1 comment.

The base branch was changed.

[kube]

• FE-1153: Collapse per-type switches into a type-policy registry #8964
• FE-769: Add String token dimension type (string interning) #8956
• FE-1121, FE-769, FE-1153: UUID & String token dimension types, type-policy registry #8953
• FE-1139: Simulation architecture documentation #8951
• FE-1130: Token frame format v2 — packed struct token layout #8944
• FE-1129: Token encoding playground (Storybook) #8943 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 890dfa4. Configure here.}

[Copilot]

Pull request overview

Copilot reviewed 11 out of 12 changed files in this pull request and generated no new comments.