Boot: Let the editor canvas navigate between entity records

[youknowriad]

What?

Lets the extensible site editor's canvas navigate into a nested entity — a template part or synced pattern reached from the block inspector — and back out again, restoring the block you were on.

Why?

The editor delegates this to two settings the host supplies. onNavigateToEntityRecord is in the block editor settings allowlist, and the block inspector gates its edit affordance on it: ( isSyncedPattern || isTemplatePartBlock ) && onNavigateToEntityRecord. onNavigateToPreviousEntityRecord is read straight off the editor settings by the document bar, where hasBackButton = !! onNavigateToPreviousEntityRecord || !! unlockedPatternInfo.

Neither was passed in the extensible site editor, so the Edit button never rendered — there was no way into a template part from the canvas, and no way back out.

How?

Both callbacks come from the canvas, which is what knows the route scheme, and travel through the settings object it already passes to the lazy editor. @wordpress/lazy-editor and @wordpress/editor are untouched.

• Navigating in goes to /types/{postType}/edit/{postId}, with the ID encoded — template and template part IDs carry a theme//slug form that has to survive being placed in a path, the same way routes/template-part-list builds its edit links.
• Navigating back uses the router's history, exposed only when TanStack's useCanGoBack says there is somewhere to go. Returning undefined otherwise is what keeps the document bar's back button conditional, matching edit-post, which returns undefined at stack depth 1.
• Selection is stashed into the current URL as selectedBlock on the way out, and restored on the way back.

Two departures from how edit-site does this, both deliberate:

The restore runs in the post-edit route's loader, not while rendering. edit-site applies it synchronously during render, from useResolveEditedEntity, so the selection is in the entity's edits before the provider resets its blocks — which also forces a hasEntityRecord guard, because editEntityRecord throws on an unloaded record, and a ref to apply it once. In this router the loader is a better fit: it runs before the route component renders at all, and beforeLoad has already resolved the record, so neither the guard nor the ref is needed. It also avoids mutating a ref during render, which react-hooks/refs rejects.

The settings object is now memoized. It was rebuilt inline on every render, and the provider pushes settings into the store whenever their identity changes. That was pre-existing churn; with callbacks in the object it would also mean the inspector's affordance identity changing every render, so it needed fixing here.

The viewport half of edit-site's equivalent is not ported: it depends on ViewportSync, which the canvas doesn't have yet, so the parameter would be inert on both ends. Worth a follow-up alongside that hook.

Testing Instructions

1. Enable Gutenberg → Experiments → Extensible Site Editor and open Appearance → Design.
2. Open a template that contains a template part (a header, say) in the editor canvas.
3. Select the template part block and open the block inspector. Confirm an Edit affordance appears — on trunk there is none.
4. Activate it and confirm the canvas navigates into the template part, with its own edit URL.
5. Confirm the document bar now offers a back button, and that it returns you to the template.
6. Confirm the block you had selected before navigating in is selected again on return.
7. Repeat with a synced pattern.
8. Confirm the back button is not offered when you open an entity directly, with no history to return to.

Testing Instructions for Keyboard

Reach the Edit affordance in the inspector by keyboard and activate it with Enter; on the nested entity, Tab to the document bar's back button and activate it. Focus should land somewhere sensible in the parent, on the restored selection.

Screenshots or screencast

Use of AI Tools

Authored with Claude Code (Claude Opus 5), including this description; reviewed by the PR author.

Verified: lint clean on both packages; tsc --build packages/boot --force exits 0; the build succeeds. Not verified: no browser pass, so every step above still needs a manual run — in particular that the loader-based selection restore lands early enough in practice, which is the part that departs from the edit-site implementation.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: youknowriad <youknowriad@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[github-actions]

Size Change: +914 B (+0.01%)

Total Size: 7.72 MB

📦 View Changed

Filename	Size	Change
build/modules/boot/index.min.js	52.3 kB	+789 B (+1.53%)
build/modules/edit-site-init/index.min.js	1.69 kB	+108 B (+6.85%)	🔍
build/modules/lazy-editor/index.min.js	14.8 kB	+17 B (+0.11%)

_{compressed-size-action}

[github-actions]

Flaky tests detected in 1231ebc.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/31786744824
📝 Reported tests:

adds and activates a new tab when pressing Enter at the end of a tab label in /test/e2e/specs/editor/blocks/tabs.spec.js, passed after 2 failed attempts.

Error: expect(locator).toHaveCount(expected) failed

Locator:  locator('[name="editor-canvas"]').contentFrame().getByRole('tab')
Expected: 3
Received: 2
Timeout:  5000ms

Call log:
  - Expect "toHaveCount" with timeout 5000ms
  - waiting for locator('[name="editor-canvas"]').contentFrame().getByRole('tab')
    14 × locator resolved to 2 elements
       - unexpected value "2"

    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/blocks/tabs.spec.js:146:25
Error: expect(locator).toHaveCount(expected) failed

Locator:  locator('[name="editor-canvas"]').contentFrame().getByRole('tab')
Expected: 3
Received: 2
Timeout:  5000ms

Call log:
  - Expect "toHaveCount" with timeout 5000ms
  - waiting for locator('[name="editor-canvas"]').contentFrame().getByRole('tab')
    14 × locator resolved to 2 elements
       - unexpected value "2"

    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/blocks/tabs.spec.js:146:25

[youknowriad]

I need to move forward. I have follow-ups but happy to address any feedback.