FE-1567: Add optional description and metadata fields to SDCPN nodes

[claude]

Requested by Ciaran Morinan · Slack thread

Before: SDCPN elements carry no human-readable summary apart from Scenario.description and Metric.description, and a host embedding Petrinaut (such as the Flows→Petrinaut migration, H-6769) has nowhere to store its own data on a net.

After: Place, Transition, Subnet, ComponentInstance, Color, and the net root carry an optional description; Transition, Subnet, ComponentInstance, and the net root also carry an optional metadata record of JSON values, opaque to Petrinaut and never rendered. Arcs carry neither. Descriptions are editable in the place, transition, component-instance, and type properties panels. Files written before this change still validate, and files carrying the new fields round-trip through export and import.

How: The fields are added to the SDCPN types and the strict zod entity schemas (the update-action schemas derive from those, so AI actions and the properties panels accept them without further changes). The file-format schemas gain the fields on their standalone subnet and net-root objects, the export key order includes them, SDCPNInput/normalizeSDCPN pass them through for hosts, and a shared draft-field textarea renders the description editors.

🔗 Related links

• FE-1567: Add optional description and metadata fields to SDCPN nodes (internal)
• H-6769: Replace Flows Definitions view with Petrinaut view of a net (internal)

🔍 What does this change?

• libs/@hashintel/petrinaut-core: description/metadata on the SDCPN types, entity schemas, file-format schemas, export key order, and SDCPNInput/normalizeSDCPN
• libs/@hashintel/petrinaut: a DescriptionField/DescriptionTextArea component, wired into the place, transition, component-instance, and type properties panels; user-guide note in docs/drawing-a-net.md

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:

• require changes to docs which are made as part of this PR

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

The changes in this PR:

• do not affect the execution graph

🐾 Next steps

• Subnets and the net root have no properties panel, so their description is schema-only for now; editing UI can follow if wanted.
• Node tooltips do not show descriptions; there is no existing hover-summary pattern on canvas nodes to extend.

🛡 What tests cover this?

• parse-sdcpn-file.test.ts: parse tests for files with and without the new fields, versioned and legacy formats
• serialize-sdcpn.test.ts: round-trip and key-order tests now exercise the fields on the net root, transitions, and subnets

❓ How to test this?

1. Checkout the branch and run the Petrinaut demo site (yarn dev in libs/@hashintel/petrinaut)
2. Select a place, transition, component instance, or type and edit its Description in the properties panel
3. Export the net (YAML or JSON), confirm the description is written, and re-import it
4. Import a pre-existing SDCPN file without the fields and confirm it still validates

[vercel]

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

Project	Deployment	Actions	Updated
petrinaut	Ready	Preview	Sep 4, 2026 5:25pm UTC
petrinaut-docs	Ready	Preview	Sep 4, 2026 5:25pm UTC

2 Skipped Deployments

Project	Deployment	Actions	Updated
hash	Ignored	Preview	Sep 4, 2026 5:25pm UTC
hashdotdesign-tokens	Ignored	Preview	Sep 4, 2026 5:25pm UTC

[cursor]

PR Summary

Medium Risk
Additive changes to the published SDCPN file format and two npm libraries; behavior risk is limited by optional fields and parse/serialize tests, but embedders may start relying on metadata persistence.

Overview
Adds optional description and host-opaque metadata to SDCPN entities in @hashintel/petrinaut-core (types, Zod schemas, file parse/serialize, and normalizeSDCPN preservation) so older files still validate and new fields round-trip on export/import.

@hashintel/petrinaut exposes description editing in the place, transition, component-instance, and type property panels via a shared description field component; metadata and descriptions on subnets/net root remain schema-only for now.

The Petrinaut website drops normalizeExampleDefinition and loads parsed models directly, and fills the gases/semiconductor example JSON with element- and net-level descriptions. Patch changesets and a publishing-packages agent skill document release conventions.

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

[claude]

The Integration (@tests/hash-playwright) check is red on 7363092 on tests/hash-playwright/tests/extension/browser-plugin.spec.ts:256 (extension one-off inference; 1 failed, 33 passed). This PR doesn't touch the extension or that spec. The same spec flaked on main's merge queue for #9529 yesterday before passing. A re-run of the failed job was already tried and failed the same way (test timeout while opening the extension popup). No fix PR or issue exists yet, so standing down on it rather than widening this PR.

---

Generated by Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 60.89%. Comparing base (eea4e1f) to head (363b0bb).
⚠️ Report is 9 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #9484   +/-   ##
=======================================
  Coverage   60.89%   60.89%           
=======================================
  Files        1461     1461           
  Lines      146725   146725           
  Branches     6744     6744           
=======================================
+ Hits        89343    89345    +2     
+ Misses      56264    56262    -2     
  Partials     1118     1118           

Flag	Coverage Δ
apps.hash-api	15.41% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.