Carlos Florêncio
62 lines
3.1 KiB
Markdown
62 lines
3.1 KiB
Markdown
---
|
|
id: canvases-task-entry-presentation-design
|
|
title: Task-entry canvas presentation
|
|
status: draft
|
|
system: canvases
|
|
owners:
|
|
- canvases
|
|
created: 2026-09-21
|
|
last_updated: 2026-09-21
|
|
requirements:
|
|
- REQ-CANVASES-AGENT-WEB-APPS-001
|
|
- REQ-CANVASES-AGENT-WEB-APPS-006
|
|
---
|
|
|
|
# Task-entry canvas presentation
|
|
|
|
Lifecycle hints accelerate discovery but cannot establish that discovery is
|
|
complete. They disappear on reload and can expire from the bounded hint list.
|
|
`useTaskCanvases` supplies the authorized HTTP inventory on task entry and
|
|
lifecycle refresh. Enable the existing task-page query for desktop as well as
|
|
phones, and pass its result to `useTaskCanvasLifecycleActivation`.
|
|
Refresh the inventory after WebSocket reconnection. Do not create a polling loop.
|
|
|
|
Filter each candidate by task scope, exact task/workspace identity, and current
|
|
release eligibility. Reuse the metadata rules in
|
|
`canvasLifecycleActivationDecision`, including first-release permission review.
|
|
A failed list request is not an empty authoritative inventory. Never record
|
|
presentation or remove saved panels because a fetch failed.
|
|
|
|
On desktop, wait for the current task environment and layout restoration to
|
|
settle. Recheck task, environment, and request generation before insertion.
|
|
Use the main editor group resolved by the existing layout helpers. Add all
|
|
eligible unseen canvases in creation-time order, with canvas ID as a tie-breaker.
|
|
Focus only the last added panel once per reconciliation batch. An existing
|
|
panel counts as presented without changing its placement or active state.
|
|
|
|
Keep presentation receipts in host-owned `sessionStorage`, keyed by user,
|
|
workspace, task, canvas, and a stable tab identity. Reuse the PR-panel
|
|
offered-marker pattern from `lib/local-storage.ts`. Detect a duplicated
|
|
`sessionStorage` namespace through the live page owner in `localStorage` and
|
|
rotate the tab identity before reading receipts. Store receipts only after
|
|
successful insertion or confirmed mobile route entry. Manual opening and
|
|
restored panels also record receipts. A receipt suppresses reopening after
|
|
close and survives reload in the same tab. A new tab can offer the canvas
|
|
again. Release IDs are not part of receipt identity. No database migration or
|
|
cross-device preference is needed. Storage errors use a tab-memory fallback
|
|
and never block manual access.
|
|
|
|
On phones, select the same deterministic last candidate and navigate once to
|
|
`canvasHref`. Record the other eligible candidates as offered only after that
|
|
navigation succeeds. The existing picker exposes them without repeated redirects
|
|
on Back. Reuse `task-layout.tsx` and `CanvasHostFrame` for the focused route,
|
|
safe areas, scrolling, and touch controls. Drafts and permission-review hosts
|
|
must retain their existing distinction.
|
|
|
|
The [recovery work package](../../../plans/canvas-runtime-entry-recovery/plan.md)
|
|
owns implementation and regression coverage for this reconciliation.
|
|
|
|
This design extends the [canvas lifecycle design](agent-authored-web-apps.md).
|
|
It implements first-presentation criteria under requirement 001 and the focused
|
|
phone route under requirement 006. Canvas metadata remains authoritative.
|