feat(generation): add validated SSE task adapter

[xyh202131]

Summary

• implement Generation create, query and SSE subscription behind GenerationApis
• inject user identity, request transport, stream transport and project image-size resolution
• request exactly 4 character candidates, 1 action first frame and 16 complete animation frames
• validate task identity, input payload, action type, terminal result, contiguous frame indexes and status/error invariants
• close SSE on terminal or fatal payload errors, require an error handler, and keep native EventSource reconnect behavior without polling

Scope

Frontend only. The backend SSE endpoint is not claimed as implemented here. No page, WorkflowRun, Controller, backend, database, log or build artifact is included.

Verification

• changed-file format check: passed
• lint: passed
• typecheck: passed
• tests: 4 files, 14 tests passed
• production build: passed
• repository-wide format:check remains blocked by 41 pre-existing files on main; this PR keeps the generation change minimal

Refs #78

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
windup	Ready	Preview	Aug 4, 2026 8:07am

[fennoai]

Review summary: two issues stand out.

Findings without inline locations

• frontend/src/entities/generation/index.ts:102: The complete-animation result type only preserves URLs, but the backend action frame DTO already carries duration_ms and the frontend Frame model can store durationMs. Once this adapter maps the task into GenerationResult, that timing data is gone and downstream character writes will have to invent defaults.

[fennoai]

This changes first_frame to /generation/action, which may be the intended runtime contract, but it now disagrees with the repo-facing API contract in frontend/API_CONTRACT.md that still documents /generation/image here. Please update that doc in the same change set, otherwise callers will implement the wrong endpoint.

[johnnyzhang-eng]

实测反馈：契约对得上，但终态不关流会无限重连；另外目前零 UI 消费者

在集成分支（main + #117 + #119 + #111 + 本 PR）上验证，并对一台真实部署的后端订阅了一个已完成的任务。

1. 契约是对的，两处可以放心

• 事件名：服务端实际只吐一种事件名 task_update，靠 payload 里的 status 区分状态，payload 五个键 task_id / task_type / status / result / error_message。本 PR 只监听 task_update 是对的。
  ⚠️ 注意另有一份设计文档写的是 status / progress / completed / failed 四个事件名，与线上实际行为不符，别照那份改。
• URL 拼接带了 project_id，与后端强制要求的 query 参数一致。

2. 终态之后 EventSource 会每 3 秒重连一次，需要显式 close

服务端发完终态事件就关流，但响应里带了 retry: 3000。浏览器原生 EventSource 把「连接关闭」当成断线，于是按 retry 间隔重连——实测 45 秒内重连 15 次，每次都重新收到同一条 completed 事件，测试结束时强制 close，readyState 仍停在 CONNECTING。

也就是说：任务早就结束了，前端还在每 3 秒打一次请求，且业务回调会被重复触发。

修法二选一（前者更稳）：

• 前端在收到 status 为终态（completed / failed）时显式 es.close()；
• 或服务端在关流前不下发 retry，改用一个明确的终止事件。

3. 目前全仓没有调用方

搜 createGenerationApis 的调用点，除测试外为 0。要接进界面还差组合根注入四样：baseUrl、userId、transport: { request, stream }（需要把 #117 的 client 与 shared/api/stream.ts 的 subscribeToEventStream 适配进来）、resolveImageSize(projectId)。这一层目前没人认领，本 PR 合了之后界面上仍然摸不到。