feat: add experience-toolbar starter example [EXT-7365]

[Jared Jolton (jjolton-contentful)]

Note

This example targets an App SDK location that's currently in limited/internal availability. The Experience Editor toolbar location isn't generally available yet, so an app built from this example won't be installable in most spaces for the time being. The example is published now so the code and patterns are here to explore and build against ahead of a wider rollout.

Especially curious? If you'd like to try the toolbar location early, reach out to Contentful support — we're happy to talk through early-access options.

EXT-7365

Summary

• Adds a Create Contentful App example at examples/experience-toolbar for the new Experience Editor toolbar App SDK location (LOCATION_EXPERIENCE_TOOLBAR), scaffoldable via npx create-contentful-app --example experience-toolbar.
• Typed with ExperienceEditorToolbarAppSDK from @contentful/app-sdk@^4.63.1. Demonstrates every pattern in the ticket AC:
  • location detection — sdk.location.is(locations.LOCATION_EXPERIENCE_TOOLBAR) in App.tsx
  • reading sdk.experiences.context to tell experience vs. fragment apart (+ onContextChanged)
  • subscribing to sdk.experiences.experience.selection.onChange()
  • resolving the selected node via sdk.experiences.experience.getNode(nodeId) and reading its properties
  • driving the canvas from the toolbar via sdk.experiences.experience.selection.highlight()
• React-only; no Data Assembly or save()/publish() (per ticket excluded scope). Mirrors examples/typescript conventions (Vite + Vitest + Forma 36).

Two deviations from the AC (intentional — flagging for review)

1. --example, not --template. The AC says --template experience-toolbar, but the CLI scaffolds repo examples via --example <name> (resolved from apps/examples/ via the GitHub API on master). --template is a fixed allowlist of framework starters (IGNORED_EXAMPLE_FOLDERS). Delivered as an example, matching how editor-assignment, page-location, etc. ship. The ticket hedges with "(or equivalent)".
2. No app-definition.json. No example in the repo ships a manifest, and the toolbar location is not an EditorInterface target state — visibility is determined solely by whether the location is registered on the app definition. Documented registration via create-app-definition / add-locations in the README and a ConfigScreen note instead of inventing a manifest the CLI would strip.

Verification status

• ✅ Type-verified: tsc --noEmit clean against the published app-sdk types.
• ✅ vite build clean.
• ✅ 7/7 Vitest specs pass (mocked SDK drives selection, properties, and canvas-highlight paths).
• ⚠️ Not runtime-verified inside a live Experience Editor — the host renderer serving sdk.experiences is still rolling out (EXT-7363/EXT-7364). The README states this explicitly. API shapes match the published types exactly.

Test plan

• npm install && npm run build in examples/experience-toolbar succeeds
• npm run test:ci passes
• npx create-contentful-app --example experience-toolbar scaffolds a working project (once merged to master, since the CLI reads examples from the GitHub API)
• (When host renderer lands) install into a space, register the experience-toolbar location, open an experience, and confirm context/selection/properties render live

Generated with Claude Code

[Josh Lewis (lewisjcs)]

⚔️ The Gauntlet — ✅ 0 Blockers · 2 advisory

_{🤖 AI-powered · your code, through the lanes}

🛑 Blockers	0
⚠️ Concerns	0
💡 Nits	2
🔒 Security	clean ✓
🧪 Lanes	code-quality-audit · adversarial · doc-review (PR body) · security

Re-review (2026-07-09) covering the six commits since the last pass — canvas-highlight button, the sdk.exo → sdk.experiences rename, the UiMode surface removal, and two app-sdk bumps up to ^4.63.1. Both prior concerns are resolved with real tests, not just taken on faith. Two small items surfaced in the delta itself; no blockers.

Update (2026-07-09): the README staleness concern is resolved — the stale form-mode gating sentence was removed. Two nits remain open.

Findings

	Lens	Finding	Location	Status
⚠️	code-quality-audit / Staleness	The README still says the "Highlight on canvas" button is disabled in form mode, but that gating was fully removed from the component in this same delta.	README.md:88	✅ Resolved
💡	doc-review / Memory rules — no local paths	Orphaned [EXT-7365]: …?atlOrigin=… reference-link still carries an Atlassian smartlink token into a public repo.	PR description footer	🔴 Still open
💡	code-quality-audit / Gaps	formatPropertyValue's ternary has a dead false-branch — app-sdk 4.63.1's EntryBinding.type is a single literal, so the non-'entry' arm can never execute.	src/locations/ExperienceToolbar.tsx:233	🔴 Still open
⚠️	adversarial-review / Hidden Assumptions	getProperties never rejected in the mock, so the loading-spinner and error paths were untested.	test/mocks/mockSdk.ts:16	✅ Resolved
⚠️	code-quality-audit / Gap	The binding branch of formatPropertyValue was never exercised.	src/locations/ExperienceToolbar.tsx:222	✅ Resolved
💡	code-quality-standards / Rule 5	Initial getProperties().catch() reset state silently with no log.	src/locations/ExperienceToolbar.tsx:101	✅ Resolved

🤖 Machine-readable findings (for agents)

{
  "tool": "gauntlet",
  "schema": "v1",
  "reviewed_ref": "5e27e878f",
  "verdict": { "blockers": 0, "concerns": 0, "nits": 2, "security": "clean" },
  "findings": [
    { "severity": "nit", "location": "PR description footer", "lens": "doc-review / Memory rules — no local paths", "confidence": 88, "claim": "Orphaned reference-link definition still carries an Atlassian smartlink tracking token into a public repo.", "recommendation": "Delete the trailing reference-style definition; the inline top link suffices." },
    { "severity": "nit", "location": "src/locations/ExperienceToolbar.tsx:233", "lens": "code-quality-audit / Gaps", "confidence": 85, "claim": "formatPropertyValue's binding-type ternary has an unreachable false branch under app-sdk 4.63.1's EntryBinding shape.", "recommendation": "Simplify to a direct entry -> entryId template string; drop the ternary." }
  ]
}

---

_{🎮 The Gauntlet · an AI review harness built by Josh C.S. Lewis · reviewed at 5e27e878f. Everything but the 🛑 is advisory.}

[wiz-inc-38d59fb8d7]

Wiz Scan Summary

Scanner	Findings
Vulnerabilities	-
Sensitive Data	-
Secrets	-
IaC Misconfigurations	-
SAST Findings	-
Software Management Findings	-
Total	-

View scan details in Wiz

To detect these findings earlier in the dev lifecycle, try using Wiz Code VS Code Extension.