FE-1500: add versioned examples and read-only pages

[kube]

🌟 What is the purpose of this PR?

Publishes seven Petrinaut models as immutable, versioned website examples: a catalog page, canonical /examples/<slug>/versions/<revision> pages rendering the full Petrinaut component read-only, and app-like URL navigation for the example pages and the local demo. Stacked on the controlled-navigation PR.

🔗 Related links

• FE-1500

🔍 What does this change?

• Adds the model sources under src/examples/models/v1 and deterministic precompiled HIR runtime artifacts under src/examples/generated/v1, produced by scripts/generate-example-artifacts.ts (examples:generate / examples:check).
• Adds the catalog: metadata (titles, playback config, parameter bounds), a cached model loader, and a runtime-artifact loader.
• Adds /examples and canonical example routes that render <Petrinaut readonly presentationProfile="review"> from an in-memory read-only document handle.
• Encodes app locations in search params (navigation-search.ts): mode, section, resource, scenario, subnet, selection, and creation-drawer overlays, with push for destinations and replace for normalization.
• Routes the local-storage demo: net identity moves into the URL and the demo threads a navigation controller, so mode, selection, drawers, and net switches are Back/Forward destinations.
• Per-key search validation runs through zod (already a dependency): enum and string fallbacks are .optional().catch(undefined) schemas, and the "type:id" selection encoding is a bidirectional z.codec. Cross-field rules (pair completeness, overlay precedence, tri-state scenario) stay plain code.
• The codec laws are property-tested with fast-check: decoding never throws on generated garbage, encode(decode(s)) is a fixed point (what the embed redirect relies on), and every decodable state survives encode then decode.

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

This PR:

• does not modify any publishable blocks or libraries, or modifications do not need publishing

📜 Does this require a change to the docs?

The changes in this PR:

• are internal and do not require a docs change

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

The changes in this PR:

• do not affect the execution graph

⚠️ Known issues

• The industrial-gas-supply-sdcpn slug is reserved in the catalog but not yet published.

🛡 What tests cover this?

• New: catalog.test.ts (every catalog entry loads, every scenario has generated HIR, one immutable snapshot per revision), navigation-search.test.ts, navigation-search.property.test.ts (fast-check codec laws over generated search inputs), readonly-example-handle.test.ts, -index.test.tsx, local-storage-demo-app.test.tsx.
• CI: examples:check fails when the generated artifacts do not match the models.

❓ How to test this?

1. Checkout the branch and run yarn workspace @apps/petrinaut-website dev.
2. Open /examples, pick an example, select items, switch subnets, open a creation drawer.
3. Confirm the URL tracks each step and Back/Forward walk the same states, and that editing is not possible.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
hash	Ready	Preview	Aug 29, 2026 8:19pm
petrinaut	Ready	Preview	Aug 29, 2026 8:19pm
petrinaut-docs	Ready	Preview	Aug 29, 2026 8:19pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hashdotdesign-tokens	Ignored	Preview	Aug 29, 2026 8:19pm

[cursor]

PR Summary

Medium Risk
Touches public example routes and depends on checked-in HIR staying aligned with petrinaut-core compilation; URL navigation changes affect back/forward behavior for the demo and embeds, though coverage is mostly website-scoped and tested.

Overview
Adds a versioned demo library on the Petrinaut website: seven SDCPN models under models/v1, a lightweight catalog metadata layer (playback limits, parameter bounds, no heavy imports), and cached loaders for models plus precompiled HIR in generated/v1.

A new generate-example-artifacts script compiles each example through petrinaut-core (model HIR + per-scenario HIR) and writes checked-in JSON; examples:generate / examples:check keep artifacts in sync with the models in CI.

/examples lists examples in a catalog UI; per-example routes render the full Petrinaut UI as read-only (presentationProfile="review") via a stable in-memory createJsonDocHandle keyed by slug@revision. The PR description also wires URL search-param navigation (mode, selection, drawers) for example pages and the editable local demo, with zod validation and fast-check property tests on the search codec.

Unit tests assert every catalog entry loads, scenario parameters sit within declared bounds, generated HIR covers all scenarios, and loaders return singleton snapshots per revision.

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

[cursor]

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

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

^{Reviewed by Cursor Bugbot for commit 51ca609. Configure here.}

[cursor]

Example routes drop queued navigations

Medium Severity

Example onNavigate applies each Petrinaut updater to the router’s committed previous search instead of the host’s latest pending location. Sequential updates in the same event, or before the router commits, can drop earlier changes, so the URL no longer tracks selection, drawers, or subnet switches and Back/Forward can skip states.

Additional Locations (1)

• apps/petrinaut-website/src/routes/examples.$slug.index.tsx#L24-L29

 

^{Reviewed by Cursor Bugbot for commit 51ca609. Configure here.}