FE-1659: Give local Petrinaut documents UUID URLs and copy examples

[kube]

Summary

Local demo documents open at /local/<UUID>, so bookmarks, reloads, and browser history reopen the selected file. Documents stay in the browser's local storage.

Published examples offer Make a local copy in the top bar. The copy opens at its own local URL with editing enabled.

Links

• Ticket FE-1695
• Website preview
• Ticket FE-1659 (internal)
• Docs Drawing a net

Blocked by

• #9664

Changes

• Assign persistent UUIDs to saved documents while preserving legacy storage keys and attached conversations
• Give new, imported, and copied documents distinct UUIDs
• Redirect / to the most recently edited document and /new to a new document
• Keep empty documents when switching files so their URLs remain usable
• Explain missing local documents and provide a link back to Petrinaut
• Handle failed example-copy writes with an inline error
• Update the user guide and website README, with a patch changeset for the guide bundled in @hashintel/petrinaut

Test coverage

After the 14 September rebase, affected package builds, unit tests, types, lint and architecture checks passed on the integrated stack. Browser recordings and manual checks listed below predate this rebase.

• Website suite: 463 tests passed, including UUID migration, duplicate repair, independent copies, direct routes, missing files, and Back/Forward navigation
• Website build, type check, lint, repository formatting, and architecture check passed
• Browser verification: copied a published example, edited its local copy, and reloaded the UUID URL
• The Turbo execution graph is unchanged

How to test

• Open /examples/sir-epidemic-model on the website preview
• Choose Make a local copy and confirm the URL is /local/<UUID>
• Rename the copy, move a place, and reload
• Create another document from Menu > New, then use Back and Forward
• Open /local/550e8400-e29b-41d4-a716-446655440000 in a browser without that file and confirm the recovery message

[vercel]

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

Project	Deployment	Actions	Updated
hash	Ready	Preview	Sep 15, 2026 8:50pm UTC
petrinaut	Error		Sep 15, 2026 8:50pm UTC
petrinaut-docs	Ready	Preview	Sep 15, 2026 8:50pm UTC

1 Skipped Deployment

Project	Deployment	Actions	Updated
hashdotdesign-tokens	Ignored	Preview	Sep 15, 2026 8:50pm UTC

[cursor]

PR Summary

Medium Risk
Routing and localStorage identity/migration affect how every demo document is opened and persisted; mistakes could break bookmarks or multi-tab behavior, but scope is limited to the website demo layer.

Overview
Local browser-saved nets now have stable /local/<UUID> URLs so reloads, bookmarks, and Back/Forward reopen the intended file. / redirects to the most recently edited document (or creates one); /new always creates a new empty document and redirects to its UUID. Legacy storage keys and AI conversation keys are preserved while UUIDs are assigned or repaired on read.

Published examples gain a top-bar “Make a local copy” that clones the model into local storage and navigates to the new UUID; storage failures surface an inline alert without leaving the example.

Document lifecycle changes: empty nets are no longer deleted when switching files; new records use UUIDs as ids; writes that must persist throw when localStorage is unavailable. Missing UUIDs show a dedicated recovery page instead of a generic 404.

Docs (website README, drawing guide) and a patch changeset document the behavior.

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

[Copilot]

🟡 Changes recommended

The central editor-to-UUID navigation workflow lacks integration coverage.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds persistent UUID routes for browser-local Petrinaut documents and enables editable copies of published examples.

Changes:

• Adds UUID migration, creation, routing, and navigation.
• Adds example copying and missing-document recovery.
• Updates tests, documentation, and release metadata.

File summaries

File	Description
.changeset/local-document-urls.md	Adds the Petrinaut patch changeset.
apps/petrinaut-website/README.md	Documents local UUID routes and copies.
apps/petrinaut-website/src/examples/full-example-page.tsx	Adds the copy action and error alert.
apps/petrinaut-website/src/main/app/local-storage-demo/local-storage-demo-app.tsx	Connects document selection to routing.
apps/petrinaut-website/src/main/app/local-storage-demo/resolve-crew-reservation-bundle.test.ts	Adds UUID data to the fixture.
apps/petrinaut-website/src/main/app/local-storage-demo/use-local-storage-sdcpns.test.ts	Tests UUID migration and copies.
apps/petrinaut-website/src/main/app/local-storage-demo/use-local-storage-sdcpns.ts	Implements UUID persistence and migration.
apps/petrinaut-website/src/routes/-local.test.tsx	Tests local routes and history.
apps/petrinaut-website/src/routes/-new.test.ts	Tests distinct /new documents.
apps/petrinaut-website/src/routes/-not-found-page.tsx	Supports customized recovery messages.
apps/petrinaut-website/src/routes/__root.tsx	Adapts root not-found rendering.
apps/petrinaut-website/src/routes/examples.$slug.tsx	Saves and opens example copies.
apps/petrinaut-website/src/routes/index.tsx	Redirects home to the latest document.
apps/petrinaut-website/src/routes/local.$uuid.tsx	Adds the local-document route.
apps/petrinaut-website/src/routes/new.tsx	Redirects new documents to UUID URLs.
libs/@hashintel/petrinaut/docs/drawing-a-net.md	Documents local URLs and example copies.

Review details

• Files reviewed: 16/16 changed files
• Comments generated: 1
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[cursor]

Stale Bugbot comment from a previous run.

[kube]

This is specific to Brunch fixture and should be flagged as something to remove soon.

We should not have (too much) spaghetti in the app.

[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 59624f5. Configure here.}