docs/plans/2026-06-15-4706-block-discussion-responsive-display.md
Objective: Fix #4706 block discussion responsive display; done when source issue/video is covered, responsive behavior is fixed or ruled out, verification and PR/tracker sync are complete.
Goal plan: docs/plans/2026-06-15-4706-block-discussion-responsive-display.md
Template: docs/plans/templates/task.md
Primary template: docs/plans/templates/task.md
Applied packs:
Task source:
block-discussion Cannot display properly when the width is less than 935pxsuggestion-toolbar-button / Plate Plus discussion example, block discussion cards that are visible on wide layouts must remain reachable/visible when the viewport narrows around 935px, without requiring text edits to force a rerender.Completion threshold:
node .agents/skills/autogoal/scripts/check-complete.mjs docs/plans/2026-06-15-4706-block-discussion-responsive-display.md passes.Verification surface:
pnpm turbo typecheck --filter=./apps/www, pnpm lint:fix, and registry changelog/generation checks if registry files change.Constraints:
Boundaries:
apps/www/src/registry/ui/block-discussion.tsx, closely related registry UI/test/changelog files, and this goal plan. Package code only if source evidence proves the issue is not UI-owned.https://platejs.org/docs/components/suggestion-toolbar-button equivalent local docs/example route or closest local registry demo containing discussion-kit / block-discussion.Output budget strategy:
rg over apps/www/src packages docs/solutions streamed too much output. Recovery: use focused sed on block-discussion files, targeted rg --files, capped browser logs, and screenshots/artifacts instead of broad dumps.Blocked condition:
Task state:
Current verdict:
discussion-pro; at browser width 935px the local docs iframe measured 873px wide, while the Pro discussion rail appears only when the iframe viewport is at least 900px. discussion-pro now declares a 900px iframe minimum, and BlockViewer exposes horizontal scroll when the preview panel is narrower.Completion rule:
update_goal(status: complete) while any required checklist item
remains unchecked. If an item does not apply, check it and add N/A: <reason>.update_goal(status: complete) until every completion threshold
above is satisfied, final handoff evidence is recorded, and
node .agents/skills/autogoal/scripts/check-complete.mjs docs/plans/2026-06-15-4706-block-discussion-responsive-display.md passes.Start Gates:
| Gate | Applies | Evidence |
|---|---|---|
| Skill analysis before edits | yes | Used task; loaded video-transcripts, autogoal, plate-ui, and shadcn as supporting guards. |
| Active goal checked or created | yes | get_goal returned none; create_goal created this #4706 objective. |
| Source of truth read before edits | yes | gh issue view 4706 --repo udecode/plate --json ... read body, labels, comments, screenshots, and video URL. |
| Tracker comments and attachments read | yes | Comments read; screenshots downloaded to /tmp/plate-4706-wide.png and /tmp/plate-4706-narrow.png; video transcript generated. |
| Video transcript evidence required | yes | Required and satisfied with normalized XML from generate_video_transcript.sh; tracker cache posted at https://github.com/udecode/plate/issues/4706#issuecomment-4705540660. |
docs/solutions checked for non-trivial existing-code work | yes | Read prior block-discussion stale path and shared-index solution notes; registry helper note says registry UI helper changes must update registry metadata/changelog. |
| TDD decision before behavior change or bug fix | yes | Use focused component test only if a current responsive/block-discussion spec surface exists; current block-discussion.spec.tsx referenced by old note is absent, so browser responsive proof may be primary. |
| Branch decision for code-changing task | yes | Created codex/4706-block-discussion-responsive from origin/main before code edits. |
| Release artifact decision | yes | If apps/www/src/registry/** changes, use registry changelog path; no package changeset unless published package code changes. |
| Browser tool decision for browser surface | yes | Use approved Browser tool for local responsive route proof; do not substitute standalone Playwright. |
| PR expectation decision | yes | Code-changing task should create PR after check. |
| Tracker sync expectation decision | yes | Transcript cache posted; final #4706 sync after PR or blocker. |
| Output budget strategy recorded | yes | Recorded above; broad output accident noted and recovery scoped. |
| Browser pack selected | yes | Applied browser pack. |
| Browser route / app surface identified | yes | Affected public route is /docs/components/suggestion-toolbar-button; local equivalent or closest discussion-demo/component docs route will be used. |
| Browser tool decision recorded | yes | Approved Browser first; live platejs.org can inform reproduction, local route owns fix proof. |
| Console/network caveat policy recorded | yes | Browser console/network proof will be recorded or explicitly caveated. |
| Package/API pack selected | yes | Applied package-api pack for registry release artifact gates. |
| Public surface or package boundary identified | yes | Public registry UI item block-discussion; no package export shape expected. |
| Release artifact path selected | yes | Registry changelog if registry UI changes; no .changeset for registry-only diff. |
changeset skill loaded when .changeset is required | no | N/A: not expected unless package code changes. |
| Barrel/export impact decision recorded | yes | No package exports/file-layout changes expected; pnpm brl N/A unless package exports change. |
Work Checklist:
<video-transcripts> XML, or marked N/A with reason..agents/**, .claude/**,
.codex/**, skills, hooks, commands, prompts, or user-action tooling..changeset, registry changelog, or explicit no-artifact reason..changeset work loads changeset and follows its package/version/prose rules.tooling/data/plate-ui-changelog.mdx and generated /registry/changelog/* JSON instead of adding a package changeset.main.Completion Gates:
| Gate | Applies | Required action | Evidence |
|---|---|---|---|
| Named verification threshold | yes | Run the command, proof, source audit, or artifact check named in this plan | Browser proof, pnpm turbo typecheck --filter=./apps/www, pnpm lint:fix, autoreview, and pnpm check passed. |
| Bug reproduced before fix | yes | Record failing test/repro or N/A with reason | Reproduced by measuring local docs at 935px: embedded discussion iframe width was 873px; direct Pro iframe hides cards below 900px. |
| Targeted behavior verification | yes | Run focused test/proof for changed behavior or record N/A | Browser proof: local /docs/components/suggestion-toolbar-button at 935px gives iframe minWidth=900px, wrapper clientWidth=873, scrollWidth=900, cards visible in screenshot. At 700px wrapper scroll reaches cards. |
| TypeScript or typed config changed | yes | Run relevant typecheck | pnpm turbo typecheck --filter=./apps/www passed after final patch. |
| Package exports or file layout changed | no | Run pnpm brl before final verification and keep generated barrel updates | N/A: no package exports or file layout changed. |
| Package manifests, lockfile, or install graph changed | no | Run pnpm install and relevant package checks | N/A: no manifest, lockfile, or install graph changes. |
| Agent rules or skills changed | no | Run pnpm install and verify generated skill sync | N/A: no agent rules or skills changed. |
| Workspace authority proof | yes | Run verification in the owning repo/package/app/route/tool and record cwd; do not count the wrong workspace as proof | Proof ran in /Users/zbeyens/git/plate against local apps/www dev route. |
| Browser surface changed | yes | Capture Browser Use proof or record explicit waiver/blocker | Browser proof captured via in-app Browser/node bridge on local route. |
| Browser final proof | yes | Attach screenshot or exact browser verification caveat when browser proof applies | Screenshots saved: /tmp/plate-4706-local-935-after-scroll-fix.jpg, /tmp/plate-4706-local-700-scrolled-after-scroll-fix.jpg. |
| CI-controlled template output changed | no | Restore generated template output or record why it is intentionally kept | N/A: no template output changed. |
| Package behavior or public API changed | no | Add a changeset or record why no changeset applies | N/A: docs-preview infrastructure only; no published package behavior/API delta. |
| Registry-only component work changed | no | Update tooling/data/plate-ui-changelog.mdx, run node tooling/scripts/generate-ui-changelog-entries.mjs --write, or record N/A | N/A: changed apps/www/src/components, not apps/www/src/registry/**. |
| Docs or content changed | yes | For docs-heavy work, use --template docs; for incidental docs, verify source-backed claims, links, examples, and rendered output or record N/A | Incidental docs-preview infra only; rendered local route verified. |
| High-risk mini gate | yes | For public API/runtime/package-boundary/browser/agent-action/command-contract changes, record realistic failure mode, proof plan, and why the chosen boundary is right; otherwise N/A | Risk: oversized iframe could clip cards. Accepted autoreview finding fixed by scrollable wrapper; Browser proof covers 935px visible and 700px reachable. |
| Agent-native review for agent/tooling changes | no | For .agents/**, .claude/**, .codex/**, skills, hooks, commands, prompts, or user-action tooling, load .agents/skills/agent-native-reviewer/SKILL.md and close accepted/actionable findings, or record N/A | N/A: no agent/tooling changes. |
| Local install corruption suspected | no | Run pnpm run reinstall once, rerun the exact failing command, or record N/A | N/A: no local env rot signal. |
| Autoreview for non-trivial implementation changes | yes | Load .agents/skills/autoreview/SKILL.md; use dirty local --mode local, branch/PR --mode branch --base <base>, or committed slice --mode commit --commit <ref> until no accepted/actionable findings, or record N/A for docs-only/trivial/no local patch | First run found clipped min-width bug; fixed. Final .agents/skills/autoreview/scripts/autoreview --mode local passed clean. |
| PR create or update | yes | Run check before PR work and sync PR body to the task-style final handoff | pnpm check passed; PR created: https://github.com/udecode/plate/pull/5020. |
| Task-style PR body verified | yes | Verify the PR body with gh pr view --json body; it must preserve auto-release blocks when applicable, must not include a current-PR self-link, and must use the kitcn PR #270 emoji format: ๐ Fixes ..., ๐ข 95-100% confidence, Phase / ๐งช Tests / ๐ Browser table, and bold emoji Outcome/Caveat/Design/Verified sections | gh pr view 5020 --json url,title,body,headRefName,baseRefName verified body shape and branch/base. |
| PR proof image hosting | no | If PR body needs browser proof, replace local image paths with hosted GitHub URLs or record N/A | N/A: PR body uses route/DOM proof, not embedded images. |
| Tracker sync-back | yes | Post concise issue/Linear sync after PR exists, or record N/A/blocker | Posted #4706 sync: https://github.com/udecode/plate/issues/4706#issuecomment-4705800886. |
| Final handoff contract | yes | Fill the final handoff fields below with exact PR/issue/confidence/tests/browser/outcome/caveats/design/verification content or N/A reason | Filled below. |
| Final lint | yes | Run pnpm lint:fix or scoped equivalent | pnpm lint:fix passed, no fixes applied. |
| Output budget discipline | yes | Verify no unbounded high-volume command output was streamed, or record the accidental output and recovery | Accidental broad rg and raw screenshot-byte outputs are recorded below; recovered with focused searches and saved screenshot files. |
| Goal plan complete | yes | Run node .agents/skills/autogoal/scripts/check-complete.mjs docs/plans/2026-06-15-4706-block-discussion-responsive-display.md | Passed. |
| Browser interaction proof | yes | Exercise the target route/interaction with the approved browser tool or record blocker | Local docs route verified at 935px and 700px with in-app Browser/node bridge. |
| Browser console/network check | caveat | Record console/network state or why it is not applicable | Browser wrapper did not expose event listeners (tab.playwright.on is not a function); DOM and screenshot proof recorded instead. |
| Browser final proof artifact | yes | Record screenshot/trace/route proof or exact caveat | /tmp/plate-4706-local-935-after-scroll-fix.jpg and /tmp/plate-4706-local-700-scrolled-after-scroll-fix.jpg. |
| Public API / package boundary proof | yes | Source-audit public API, exports, and package boundary impact | Only internal apps/www docs-preview metadata was extended; no package exports changed. |
| Release artifact classification | yes | Record whether the change is published package behavior/API/types/config/runtime, registry-only, or no published user-visible delta | Docs-preview site behavior only; no package/registry release artifact. |
| Published package changeset | no | If published package users see a delta, load changeset, add/update one .changeset/*.md per package, and prove no forbidden minor on @platejs/slate, @platejs/core, or platejs | N/A: no published package delta. |
| Registry changelog | no | If the change is registry-only under apps/www/src/registry/**, update tooling/data/plate-ui-changelog.mdx, run node tooling/scripts/generate-ui-changelog-entries.mjs --write, and do not add a package changeset | N/A: no registry files changed. |
| No release artifact | yes | If no artifact is needed, record the exact reason: internal-only, docs-only, agent-only, test-only, or no user-visible delta from main | Internal docs-preview behavior only, no published package or registry artifact. |
| Package typecheck/build/test | yes | Run owning package checks or record N/A with reason | pnpm turbo typecheck --filter=./apps/www and pnpm check passed. |
| Barrel/export generation | no | Run pnpm brl when exports or exported file layout changed, otherwise N/A | N/A: no exports or barrels touched. |
Phase / pass table:
| Phase | Status | Evidence | Next |
|---|---|---|---|
| Intake and source read | complete | Read #4706 source, comments, screenshots, video transcript, prior block-discussion notes, and current component. | implementation |
| Implementation | complete | discussion-pro declares a 900px iframe minimum; BlockViewer wraps fallback iframes in a scrollable container when a minimum width is present. | verification |
| Verification | complete | Browser proof, app typecheck, lint, autoreview, and pnpm check passed. | PR / tracker sync |
| PR / tracker sync | complete | PR #5020 created and #4706 sync comment posted. | final response |
| Closeout | complete | Final checker passed. | final response |
Findings:
block-discussion cards disappear or render incorrectly when width drops below about 935px on the Plate Plus suggestion-toolbar-button example.BlockDiscussion renders children in w-full, then a zero-size relative left-0 size-0 trigger beside it. That shape can lose the discussion trigger/rail when the editor consumes available width.BlockDiscussion should keep path ownership inside the rerendering component and that registry UI helper changes must be reflected in registry artifacts.apps/www/src/registry/ui/block-discussion.spec.tsx referenced by solution notes is not present in the current checkout.discussion-demo did not reproduce: at local /blocks/discussion-demo, the popover remained visible at 935px.https://pro.platejs.org/iframe/discussion shows discussion cards at iframe widths 900px and 935px, but hides them at 873px and below./docs/components/suggestion-toolbar-button at browser width 935px embeds the Pro iframe at 873px before the fix, which explains why the reporter saw the cards disappear around that viewport./docs/components/suggestion-toolbar-button at browser width 935px embeds discussion with CSS width/min-width 900px inside a wrapper with clientWidth=873, scrollWidth=900, and overflow-x: auto; cards are visible in the screenshot.Decisions and tradeoffs:
BlockDiscussion component logic: the local OSS component works, and the failure is the embedded Pro demo receiving an iframe viewport below its own desktop rail breakpoint.BlockViewer iframes or hardcoding a global desktop width.overflow-hidden panel is insufficient.apps/www/src/components/** docs preview behavior only, with no published package or registry file delta.Implementation notes:
apps/www/src/components/component-preview-pro.tsx and apps/www/src/components/block-viewer.tsx.ComponentPreviewPro now gives discussion a 900px minimum iframe viewport by default, with an iframeMinWidth prop escape hatch for future Pro examples.BlockViewer applies iframeMinWidth to fallback iframe previews and wraps them in overflow-x-auto overflow-y-hidden so the content is reachable when the docs preview panel is narrower than the requested iframe viewport.minWidth directly inside the existing hidden-overflow panel, which could crop the iframe below 900px. Autoreview caught this; the accepted fix is the scrollable wrapper plus 935px and 700px Browser proof.Review fixes:
Error attempts:
| Error / failed attempt | Count | Next different move | Resolution |
|---|---|---|---|
Broad source rg streamed too much output | 1 | Use focused sed/rg --files and browser artifacts | Recovered; useful files identified and broad output noted. |
| Second broad source search and raw screenshot-byte output streamed too much output | 2 | Use focused commands and write screenshots to /tmp instead of printing binary | Recovered; screenshots saved as files and inspected visually. |
Direct pnpm --dir apps/www exec tsc --noEmit --pretty false --incremental false failed on generated docs source | 1 | Use repo-required pnpm turbo typecheck --filter=./apps/www | Correct command passed; direct tsc was the wrong lane. |
Verification evidence:
/tmp/plate-4706-local-935-after-scroll-fix.jpg, /tmp/plate-4706-local-700-scrolled-after-scroll-fix.jpg.tab.playwright.on is not a function); DOM and visual proof were captured instead.pnpm lint:fix passed, no fixes applied.pnpm turbo typecheck --filter=./apps/www passed after final patch..agents/skills/autoreview/scripts/autoreview --mode local final run passed clean after fixing the accepted clipping finding.pnpm check passed. Caveats in green run: pre-existing apps/www/src/components/ui/sidebar.tsx hook warning; test output printed the existing "Detected multiple @platejs/core instances!" warning, with all tests passing.Final handoff contract:
pnpm lint:fix, pnpm turbo typecheck --filter=./apps/www, autoreview, pnpm check, Browser proof at 935px and 700px./docs/components/suggestion-toolbar-button verified at 935px with cards visible and at 700px with horizontal scroll reachability.pnpm check passed with existing warning output.ComponentPreviewPro + BlockViewer docs-preview iframe plumbing.minWidth inside hidden overflow cropped the iframe; accepted autoreview finding forced scroll wrapper.BlockDiscussion did not reproduce; changing registry UI would hit the wrong owner.pnpm lint:fix; pnpm turbo typecheck --filter=./apps/www; autoreview clean; pnpm check; Browser proof.gh pr view 5020 --repo udecode/plate --json url,title,body,headRefName,baseRefName.Task-style PR body contract:
<!-- auto-release:start --> block. If a changeset is
part of the diff and repo policy expects auto release, include that block.๐ Fixes #123 or ๐ Fixes โ N/A, then
an emoji confidence line like ๐ข 95-100% confidence.| Phase | ๐งช Tests | ๐ Browser |.Reproduced and Verified rows. Mark passing proof with ๐ข, repro or
failing proof with ๐ด, and non-applicable cells with โ N/A.**โ
Outcome**, **โ ๏ธ Caveat**,
**๐๏ธ Design**, and **๐งช Verified**.Summary / Verification PR body, an
adaptive prose body from a git helper skill, plain ## Outcome sections, or
an unrelated generated badge footer unless the caller or repo template
explicitly asks for it.gh pr view --json body output or a concise source-backed summary
of that output.Final handoff / sync:
/tmp.Timeline:
Reboot status:
| Question | Answer |
|---|---|
| Where am I? | Closeout complete; PR and tracker sync are done. |
| Where am I going? | Final response after checker, final push, and active goal completion. |
| What is the goal? | Fix #4706 so the Plate Plus discussion preview remains visible/reachable around the reported 935px docs viewport. |
| What have I learned? | The docs page gave discussion-pro an iframe viewport below its 900px discussion-rail breakpoint. |
| What have I done? | Added iframeMinWidth support for Pro previews, made minimum-width fallback iframes scrollable, verified locally, opened PR #5020, and synced #4706. |
Open risks: