FE-1660: Explain blocked edits in read-only Petrinaut documents

[kube]

Summary

Trying to drag a node or use an editing shortcut on a read-only document shows a brief neutral notice. Repeated attempts reuse the same notice, and normal selection, panning, and zooming stay quiet.

On published examples, Make a local copy in the notice opens an editable copy using the local document URLs from the preceding PR. Other restrictions explain whether to switch to Edit or reset the simulation.

Links

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

Blocked by

• #9661

Changes

• Detect blocked node drags after six pixels of movement, preserving click-to-inspect behavior
• Explain blocked mutations, commands, and editing shortcuts while preserving permitted scenario edits
• Add notification IDs for deduplication and an optional action button
• Map the neutral notification tone to the toast library's supported informational type
• Expose readOnlyAction for hosts and connect example pages to their local-copy action
• Update the user guide and integration README, with a patch changeset for @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.

• Petrinaut suite: 857 tests passed; website suite: 463 tests passed
• New coverage checks drag thresholds, canceled gestures, quiet inspection and panning, blocked shortcuts, mutation restrictions, notice deduplication, focus preservation, and the action button
• Both packages' builds, type checks, and lints passed; repository formatting and architecture checks passed
• Browser verification on the local and deployed previews: a blocked place drag showed the notice, and its action opened a new editable local UUID URL that persisted after reload
• The Turbo execution graph is unchanged

How to test

• Open /examples/sir-epidemic-model on the website preview
• Click a place to inspect it, then drag it
• Confirm one brief read-only notice appears
• Try N, T, or Delete with a selected node and confirm the document remains unchanged
• Choose Make a local copy in the notice and edit the new copy

[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	Error		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

Low Risk
Changes are UX-layer feedback on existing read-only guards; document mutation rules are unchanged aside from user-visible notices and optional host callbacks.

Overview
Blocked edits in read-only Petrinaut surfaces now show a brief, deduplicated neutral toast instead of failing silently. Messages depend on why editing is blocked (host read-only, active simulation, or Simulate/Actual mode), and repeated attempts reuse the same notice via stable notification IDs.

Hosts can pass readOnlyAction on <Petrinaut /> so the notice includes an optional button (e.g. Make a local copy on published examples). Notifications gained optional action buttons, ID-based deduplication, and neutral tone mapped to informational toasts.

Feedback is wired through mutations, commands, keyboard shortcuts, canvas node placement, and node drags (after a small movement threshold so click-to-inspect stays quiet). Scenario edits allowed in Simulate mode still proceed without a notice. Docs, README, website example wiring, and tests cover the new behavior; @hashintel/petrinaut gets a patch changeset.

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

[cursor]

Stale Bugbot comment from a previous run.

[Copilot]

🟡 Changes recommended

Address the preview feedback behavior and preserve native undo when no history adapter is configured.

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

Pull request overview

Adds read-only feedback for blocked Petrinaut edits, including deduplicated notices and optional local-copy actions.

Changes:

• Detects blocked drags, shortcuts, mutations, and commands.
• Adds notification actions, deduplication, and contextual messaging.
• Updates integrations, tests, documentation, README, and changeset.

File summaries

File	Description
libs/@hashintel/petrinaut/src/ui/views/SDCPN/use-canvas-interactions.ts	Reports blocked canvas mutations.
libs/@hashintel/petrinaut/src/ui/views/SDCPN/renderers/react-flow/react-flow-canvas/use-read-only-node-drag.ts	Detects blocked node drags.
libs/@hashintel/petrinaut/src/ui/views/SDCPN/renderers/react-flow/react-flow-canvas/use-read-only-node-drag.test.tsx	Tests drag feedback behavior.
libs/@hashintel/petrinaut/src/ui/views/SDCPN/renderers/react-flow/react-flow-canvas.tsx	Installs drag handlers.
libs/@hashintel/petrinaut/src/ui/views/Editor/components/BottomBar/use-keyboard-shortcuts.ts	Explains blocked shortcuts.
libs/@hashintel/petrinaut/src/ui/views/Editor/components/BottomBar/use-keyboard-shortcuts.test.tsx	Tests shortcut feedback.
libs/@hashintel/petrinaut/src/ui/petrinaut.tsx	Exposes the read-only action prop.
libs/@hashintel/petrinaut/src/react/state/read-only-action-context.ts	Provides host action context.
libs/@hashintel/petrinaut/src/react/notifications/toaster.tsx	Renders notification actions.
libs/@hashintel/petrinaut/src/react/notifications/provider.tsx	Adds deduplication and informational tone mapping.
libs/@hashintel/petrinaut/src/react/notifications/provider.test.tsx	Tests notification behavior.
libs/@hashintel/petrinaut/src/react/notifications/context.ts	Extends notification input types.
libs/@hashintel/petrinaut/src/react/hooks/use-read-only-feedback.ts	Centralizes read-only notices.
libs/@hashintel/petrinaut/src/react/hooks/use-petrinaut-mutations.ts	Reports blocked mutations.
libs/@hashintel/petrinaut/src/react/hooks/use-petrinaut-mutations.test.tsx	Tests mutation feedback.
libs/@hashintel/petrinaut/src/react/hooks/use-petrinaut-commands.ts	Reports blocked commands.
libs/@hashintel/petrinaut/README.md	Documents the host action API.
libs/@hashintel/petrinaut/docs/drawing-a-net.md	Documents read-only behavior.
apps/petrinaut-website/src/examples/full-example-page.tsx	Connects the local-copy action.
.changeset/smooth-readonly-feedback.md	Adds the package changeset.

Review details

Suppressed comments (2)

libs/@hashintel/petrinaut/src/react/hooks/use-petrinaut-commands.ts:35

• The new behavior in this guard is the notification, but the existing use-petrinaut-commands.test.tsx cases only assert no-op return values and do not provide or inspect NotificationsContext.addNotification. A regression removing notifyReadOnly() here (or at the analogous auto-layout guard on line 44) would therefore leave the command tests green; add blocked paste and auto-layout assertions for the notice.

      if (isReadOnly) {
        notifyReadOnly();
        return { newItemIds: [] };

libs/@hashintel/petrinaut/src/react/hooks/use-read-only-feedback.ts:27

• The public PetrinautPreview does not provide a usable outcome for this shared feedback hook: without quickSimulation, it renders the canvas without NotificationsProvider (src/ui/preview/petrinaut-preview.tsx:311-345), so the default addNotification is a no-op; with Quick Simulation, the preview's mode is simulate but it intentionally exposes no Edit mode control (src/ui/preview/petrinaut-preview.tsx:321-345, docs/preview.md:64-67), so this message tells users to switch to an unavailable mode. Supply preview-specific notification wiring/copy or keep this feedback scoped to the full editor.

    const message =
      reason.kind === "host-readonly"
        ? "This document is read-only."
        : reason.kind === "simulation-active"
          ? "Reset the simulation to edit this net."
          : "Switch to Edit to change this net.";
    addNotification({
      id: `read-only:${petriNetId}:${reason.kind}`,
      message,
      tone: "neutral",
      durationMs: 4500,
      action: reason.kind === "host-readonly" ? action : undefined,

• Files reviewed: 20/20 changed files
• Comments generated: 1
• Review effort level: Lite

---

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

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