FE-1500: add the embedded Petrinaut preview

[kube]

Summary

Before this PR, embedding a net meant mounting the full Petrinaut component in read-only mode. That loads Monaco, the language server, experiments, optimizations, and the AI assistant for a page that only shows a model, and its chrome is sized for authoring.

PetrinautPreview, exported from @hashintel/petrinaut/preview, is a compact read-only surface for showing a net inside another application. It reuses the editor's canvas, navigation, and property inspection and mounts none of the authoring tooling. Its chrome follows the editor's: a flat outlined header, a square badge, and an inspector docked beside the canvas.

Links

• Ticket FE-1500
• Docs Preview

Changes

Provider layers

• PetrinautProvider splits into PetrinautDocumentProvider and PetrinautCanvasProvider

  The document layer holds the instance, net management, the undo/redo bridge, user settings, and the SDCPN store.
  The canvas layer holds playback, active net, editor, and execution frame.
  User settings sit in the document layer so a simulation provider mounted between the layers reads the Ad-hoc scenarios setting.

• Provider behaviour is unchanged for the full editor

Preview surface

• PetrinautPreview in src/ui/preview/

  In-memory read-only document, header with net selector, title, and View only badge, the shared SDCPNView, and the compact inspector.

• Navigation adapter projects the preview's URL contract onto the full controller

  PetrinautPreviewNavigationState carries scenario, subnet, and selection.

• Compact properties panel docked beside the canvas

  A flat bordered column on wide embeds, a band under the canvas on narrow ones, content slightly scaled down.

• preview presentation profile

  No mutation actions, no source code, no custom visualizers, no viewport settings, compact controls.
  The editor's presentationProfile prop excludes it.

• Embed-scale chrome follows the editor's top bar

  48px header with the same flat 1px outline and title weight, square badge, no shadow or blur anywhere.
  The minimap no longer dodges the editor's absent right panel in the preview profile.

• User guide page docs/preview.md registered in the docs index and the AI assistant's doc list

Test coverage

• navigation-adapter.test.ts:

  Projection between the preview contract and the full navigation state.

• ai.test.ts, petrinaut-docs-content.test.ts:

  Registration of the new user guide page.

• build:lib:

  The new preview entry builds.

How to test

• yarn workspace @hashintel/petrinaut build:lib
• Render <PetrinautPreview definition={...} title="..." /> from @hashintel/petrinaut/preview in a host page
• Pan, zoom, fit, minimap
• Select a node

  Expect inspector docked right of the canvas with square corners

• Net selector > a subnet

  Expect no editing affordance anywhere

[vercel]

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

Project	Deployment	Actions	Updated
hash	Ready	Preview	Sep 4, 2026 9:36am UTC
petrinaut	Ready	Preview	Sep 4, 2026 9:36am UTC
petrinaut-docs	Ready	Preview	Sep 4, 2026 9:36am UTC

1 Skipped Deployment

Project	Deployment	Actions	Updated
hashdotdesign-tokens	Ignored	Preview	Sep 4, 2026 9:36am UTC

[cursor]

PR Summary

Medium Risk
Public API and provider-tree refactor touch shared React context wiring, though the full editor path is meant to be behavior-preserving and preview is read-only with no workers.

Overview
Adds PetrinautPreview, a compact read-only embed exported from @hashintel/petrinaut/preview, so hosts can show a net without mounting the full editor (Monaco/LSP, simulation workers, experiments, optimizations, or AI).

The preview builds an in-memory read-only document and reuses SDCPNView, pan/zoom/fit/minimap, shared inspector content (via a responsive docked panel), and a compact root/subnet selector. Optional host navigation is limited to scenario, subnet, and selection through a navigation adapter; a new preview presentation profile hides mutations, source, custom visualizers, and viewport settings. PetrinautProvider is refactored into PetrinautDocumentProvider and PetrinautCanvasProvider so preview can mount document + canvas layers without editor-only workers; full-editor stacking is intended to stay the same.

Also adds the preview package export and Vite lib entry, user guide preview.md, and AI doc registration; NetNavigationList is shared with an optional onSelect callback; the minimap skips editor properties-panel offset in preview profile.

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

[semgrep-code-hashintel]

Semgrep found 4 detect-replaceall-sanitization findings:

• apps/petrinaut-website/api/oembed.ts
  • L86-91 - Triage
  • L86-90 - Triage
  • L86-88 - Triage
  • L86-87 - Triage

Detected a call to replaceAll() in an attempt to HTML escape the string value .replaceAll("&", "&amp;") .replaceAll('"', "&quot;") .replaceAll("'", "&#39;") .replaceAll("<", "&lt;"). Manually sanitizing input through a manually built list can be circumvented in many situations, and it's better to use a well known sanitization library such as sanitize-html or DOMPurify.

[semgrep-code-hashintel]

Semgrep found 1 regex_dos finding:

• apps/petrinaut-website/src/main/app/brunch-demo/brunch-endpoint.ts
  • L8-18 - Triage

Ensure that the regex used to compare with user supplied input is safe from regular expression denial of service.

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

[Copilot]

🟡 Changes recommended

The public navigation contract exposes scenario state that the preview provider tree never applies.

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

Pull request overview

Adds a compact, read-only Petrinaut embed surface with shared canvas and inspection infrastructure.

Changes:

• Introduces PetrinautPreview and its package entry point.
• Splits document and canvas providers for lightweight composition.
• Adds preview presentation settings, navigation tests, and documentation.

File summaries

File	Description
.changeset/petrinaut-embedded-preview.md	Records package patches.
libs/@hashintel/petrinaut/package.json	Exports the preview bundle.
libs/@hashintel/petrinaut/vite.config.ts	Builds the preview entry.
libs/@hashintel/petrinaut/src/preview.ts	Defines the public source entry.
libs/@hashintel/petrinaut/src/react/index.ts	Exports layered providers.
libs/@hashintel/petrinaut/src/react/petrinaut-provider.tsx	Uses the new provider layers.
libs/@hashintel/petrinaut/src/react/petrinaut-provider-layers.tsx	Implements reusable provider layers.
libs/@hashintel/petrinaut/src/ui/petrinaut.tsx	Reserves the preview profile.
libs/@hashintel/petrinaut/src/ui/preview/index.ts	Aggregates preview exports.
libs/@hashintel/petrinaut/src/ui/preview/navigation-adapter.ts	Adapts preview navigation state.
libs/@hashintel/petrinaut/src/ui/preview/navigation-adapter.test.ts	Tests navigation projection.
libs/@hashintel/petrinaut/src/ui/preview/petrinaut-preview.tsx	Composes the preview surface.
libs/@hashintel/petrinaut/src/ui/preview/preview-net-navigation.tsx	Adds compact net selection.
libs/@hashintel/petrinaut/src/ui/preview/properties-panel.tsx	Adds the responsive inspector.
libs/@hashintel/petrinaut/src/ui/views/shared/presentation-context.tsx	Defines preview capabilities.
libs/@hashintel/petrinaut/src/ui/views/SDCPN/components/mini-map.tsx	Adjusts preview minimap placement.
libs/@hashintel/petrinaut/src/ui/views/Editor/panels/LeftSideBar/subviews/nets-list.tsx	Supports selection callbacks.
libs/@hashintel/petrinaut/src/ui/views/Editor/panels/ai-assistant-panel/petrinaut-docs-content.ts	Registers preview documentation.
libs/@hashintel/petrinaut/docs/README.md	Links the preview guide.
libs/@hashintel/petrinaut/docs/preview.md	Documents preview behavior.
libs/@hashintel/petrinaut-core/src/ai.ts	Registers preview AI documentation metadata.

Review details

• Files reviewed: 21/21 changed files
• Comments generated: 2
• Review effort level: Balanced

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.