kandev/docs/plans/plugin-backed-canvases-ux-follow-up/plan.md

created, status, requirements, system_design, legacy_specs

created	status	requirements	system_design	legacy_specs
2026-08-30	in_progress	REQ-CANVASES-AGENT-WEB-APPS-001 REQ-CANVASES-AGENT-WEB-APPS-005 REQ-CANVASES-AGENT-WEB-APPS-006 REQ-CANVASES-AGENT-WEB-APPS-009 REQ-PLUGINS-ISOLATED-WEB-APPS-011	../../specs/canvases/system-design/agent-authored-web-apps.md ../../specs/plugins/system-design/isolated-web-app-contributions.md	../../specs/canvases/requirements/collaborative-canvases.md ../../specs/canvases/system-design/collaborative-canvases.md

Implementation Plan: Plugin-backed canvases UX follow-up

Subsequent design

The direct canvas creation package replaces Task 02's sidebar settings redirect with direct task-dialog launch. Completed results below remain historical. The new package owns replacement navigation and prompt tests; Task 07's outstanding external ACP evaluation is unchanged.

Overview

Correct the canvas discovery, creation, host, appearance, and authoring issues recorded in the follow-up investigation. Keep canvas creation in a normal task and preserve the isolated plugin runtime.

First, align workspace discovery and task launch. Then connect release events to the active task host. Correct host guidance and geometry before adding the appearance protocol. Finish with the authoring bundle because its scaffold depends on the final appearance contract.

Scope

In scope

• A folded-by-default canvas sidebar with explicit preference persistence.
• Feature-aware workspace Canvases cards, tabs, counts, and settings routes.
• Shared task-based canvas creation from workspace Canvases settings.
• Automatic first-release opening on desktop and phone task surfaces.
• Desktop tooltips and touch-visible lifecycle action descriptions.
• Full-height Dockview canvas rendering with direct and phone parity.
• A versioned, presentation-only host appearance protocol.
• A semantic-color authoring scaffold with live theme updates.
• One core authoring bundle, an exact inventory, and a generated scaffold.
• Disabled-path tests for every new features.canvases entry point.

Out of scope

• A blank canvas builder, package import, or direct source editor.
• An absolute Kandev host skill path for task agents.
• A privileged iframe SDK or bidirectional host API.
• A change to the features.canvases key, environment variable, restart rule, or shipped profile defaults.
• Canvas package, permission, promotion, or persistence model changes.

Technical approach

Workspace discovery

Remove Canvases from SECTION_ROUTE_MAP so direct routes do not force sidebar expansion. Preserve explicit section toggles through the current sidebar state.

Make WORKSPACE_SETTINGS_TABS feature-aware. Use the same filtered catalog in the settings tree, tab strip, headings, and workspace summary tiles. Remove appendWorkspaceCanvasNodes. Add active canvas counts only when the feature is enabled. Use six tiles only at a width that preserves readable labels.

Render WorkspaceCanvasesPage inside WorkspaceSettingsShell with the Canvases tab active. Keep the tab in the phone scroll strip even when the workspace card omits the canvas tile.

Guided task launch

Extend the task dialog preset contract with scratch source mode and a local executor preference. Add one CanvasTaskCreateLauncher that supplies localized title and prompt values. It keeps workflow and agent profile fields editable.

Use this launcher from workspace Canvases settings. The sidebar's empty setup row links to that page and does not create canvases directly. Successful creation follows the standard task-details route. The mobile settings entry uses the existing full-screen task dialog.

First-release host activation

Retain lifecycle payload identity as a bounded hint while HTTP remains the canvas source of truth. Add a task-scoped hook that reacts only to the active task's first activated or pending-permission release.

Desktop uses the current Dockview API to add and activate canvas:<canvasId>. It checks for an existing panel before insertion. Phone uses the focused canvas route. Events for another task do not change focus.

Host guidance and geometry

Wrap lifecycle actions with the existing tooltip pattern. Disabled controls use a focusable wrapper and explain the disabled reason. Mobile action rows show equivalent descriptions.

Add the missing h-full flex boundary in the canvas Dockview renderer. Do not change PageShell, the direct route, or phone h-dvh calculations.

Appearance protocol

Add a typed version 1 appearance envelope beside WebAppFrame. Resolve the active Kandev mode and fixed semantic token allowlist from host styles. Send the initial envelope to the exact iframe window after load. Keep the loading cover for one animation frame, then reveal the application.

Send another envelope after a live host theme change. The scaffold validates the parent window, message type, version, mode, token keys, and value bounds. It maps valid values to documented CSS custom properties with safe fallbacks.

Authoring efficiency

Change the default read_canvas_authoring_skill_kandev response to one compact core bundle with the exact reference inventory. Keep optional allowlisted path reads for details.

Make create_canvas_kandev materialize the complete minimal scaffold and return its exact inventory. Agents use native file tools after creation. Do not return an absolute Kandev host path. Keep the response shape equal for local, Docker, and SSH executors.

Tests

Acceptance criteria	Evidence
AC-CANVASES-AGENT-WEB-APPS-001.2	Lifecycle handler and Dockview deduplication tests, desktop and phone Playwright
AC-CANVASES-AGENT-WEB-APPS-001.7	Feature-off catalog, count, launcher, route, and event tests
AC-CANVASES-AGENT-WEB-APPS-001.8	Core-bundle and inventory golden tests, handler-level ACP contract test; external ACP evaluation pending
AC-CANVASES-AGENT-WEB-APPS-001.9	Local, Docker, and SSH response-shape tests
AC-CANVASES-AGENT-WEB-APPS-005.2-.9	Sidebar state, settings catalog, responsive card, route, and navigation tests
AC-CANVASES-AGENT-WEB-APPS-006.1-.7	Host action tests and rendered desktop and phone geometry assertions
AC-CANVASES-AGENT-WEB-APPS-009.1-.5	Task preset tests and desktop and phone task-creation flows
AC-PLUGINS-ISOLATED-WEB-APPS-011.1-.4	Appearance schema, frame delivery, source validation, and computed-color tests

E2E tests

• apps/web/e2e/tests/canvas/plugin-canvas.spec.ts covers folded navigation, workspace discovery, sidebar setup guidance, automatic panel opening, lifecycle help, full-height geometry, and live appearance changes.
• apps/web/e2e/tests/canvas/mobile-plugin-canvas.spec.ts covers the workspace Create canvas action through the full-screen task dialog, scratch/local defaults, editable workflow and agent controls, focused first-release route, visible permission approval, action descriptions, viewport containment, and live appearance changes.
• Both files run with Playwright retries disabled during implementation. They assert user outcomes and bounding-box relationships, not fixed sleeps.

Work orders

• Task 01: Align workspace canvas discovery
• Task 02: Add guided canvas task launch
• Task 03: Open the first task release
• Task 04: Explain canvas lifecycle actions
• Task 05: Fill the canvas host viewport
• Task 06: Add isolated application appearance
• Task 07: Reduce authoring skill reads

Implementation is sequential in the primary conversation. A later user request can authorize Codex implementation subagents. No work order authorizes Kandev task or session delegation.

Verification results

Tasks 01 through 06 are implemented. Task 07 has the implementation and in-process contract coverage, but remains in progress until an external ACP provider evaluation is captured. Earlier focused web verification passed 7 test files and 69 tests. The follow-up focused web suite passed 15 files and 73 tests. The affected backend packages passed 1,149 tests, and the full backend suite passed with the repository config override cleared. The full web suite passed 1,687 files, 14,375 tests, and 4 skipped tests. Desktop and phone canvas Playwright flows passed with retries disabled. Web typecheck, lint, i18n checks, the new-code ratchet, specification lint, harness lint, shell syntax, and diff checks passed. Current remediation-focused backend, lifecycle, and resource-guard tests also pass; the external ACP evaluation is outstanding.

The local web test runners now bound Vitest parallelism and E2E shard/worker counts by default. E2E runs use one worker per shard and at most three local shards, with lower limits on low-memory hosts. Higher parallelism requires an explicit opt-in environment variable, and the E2E skill documents the safe defaults for future sessions.

Follow-up repair

The canvas runtime and permission repair adds startup acknowledgement before appearance reveal and replaces the release review layout. Its work orders 03-04 own those changes and desktop/mobile tests. The external ACP evaluation remains pending here; this repair neither completes that evaluation nor replaces this package's historical results.

Risks

• A feature-aware tab catalog can accidentally fetch canvas data while the feature is disabled.
• A task preset can overwrite durable last-used choices instead of applying a launch-only preference.
• A delayed lifecycle event can open a duplicate panel or steal another task's focus.
• An unbounded appearance message can become an accidental host API.
• Theme reveal timing can flash stale colors if the iframe is shown too early.
• Scaffold files and the embedded skill inventory can drift without one golden source.