docs/widget-specs/render-monitor.md

# Widget spec — `picsart_render_monitor`

Progress board for async generations. Kills the "ping me in five minutes"
pattern: the widget polls the jobs itself and reports completions back into
the conversation, waking the assistant without the user doing anything.

## Tool input

```ts
{
  title?: string,                    // "sc01 drafts"
  jobs: Array<{
    job: Record<string, unknown>,    // the handle from picsart_generate { async: true } → { job }
    model: string,                   // model id — picsart_job_status needs it
    label: string,                   // shot id or asset tag, e.g. "1A"
    prompt?: string,                 // forwarded to job_status for result shaping
    saveToDrive?: boolean
  }>,                                // 1..24
  note?: string
}
```

## Behavior

- Per job, poll `host.callTool('picsart_job_status', { job, model, prompt?,
  saveToDrive? })` every ~5s (staggered): running → progress percent/ETA;
  COMPLETED → thumbnail from the returned media payload; FAILED/CANCELED →
  error chip. `picsart_job_status` is free and widget-accessible.
- **When every job is terminal, send `render_monitor_feedback` automatically**
  (per `skills/film/references/WIDGET-FEEDBACK.md`) — done URLs + failures.
  A `Send now` affordance exists for impatient partial reports; silent publish
  streams progress context while running.
- Layout: title + overall bar; one row per job (label, model, progress bar or
  thumbnail, status chip); reduced-motion respected.
- **This board is the ONLY progress surface a dispatch opens (2026-09-07).**
  `picsart_generate` carries the media gallery as its static output template,
  so the host opens that widget once per call whether or not the call has
  pixels to show. For an async dispatch the gallery now draws nothing
  at all — not while the submit is in flight, not on the `ACCEPTED` receipt —
  because it used to shimmer "Generating your image…" over a skeleton grid
  directly above this board, once per call in a batch. And async is now the
  DEFAULT for every media mode, image included, precisely so this board is the
  one surface that narrates a render. Fixed in the widget (`media-gallery` v11),
  not in doctrine: nothing a prompt does can decline a
  declaration-time output template.

## Build notes

Net-new widget, standard registration checklist. Poll loop must stagger
requests and stop on unmount/completion; thumbnails render from the completed
payload's asset URLs (Picsart CDN, allowed by the widget CSP). Reuse
`useFeedbackSender` (the auto-send on completion is still a real
`sendMessage`), shared progress/`MediaPreview` components where they fit.