makelore/.project-docs/30-worklog/tasks/20260916-design-media-client-a7d3e9c1.md

Task: Diagnose Design production form media switching

Identity

• Task ID: 20260916-design-media-client-a7d3e9c1
• Mode: Feature
• Branch: codex/20260916-design-media-client-a7d3e9c1-design-media-client
• Worktree: D:\Datas\OthersProjects.codex-worktrees\makelore\20260916-design-media-client-a7d3e9c1
• Base commit: b723c7220b
• Owner: codex
• Status: Ready for Integration

Scope

• Client implementation: own the shared/Main command and capability serialization, image-workspace store preparation action, YouthCreationCard capability-aware media/reference controls, explicit video first-frame binding, history playback/preview/reuse actions, and the related tests plus scripts/diagnostics/design-video-flow.test.tsx and its isolated Vitest config. Work only in this isolated client worktree; do not touch server, root main, provider calls or paid generation.

Intent And Constraints

• Implement the agreed prepare_generation input and generation_options capability contract while preserving direct edits, stable operation identities, replay/unknown recovery and public assistant activity boundaries. A prepare operation never creates a chat bubble; blockers remain visible and actionable until the user supplies the missing input.
• User authorized parallel client implementation. Concurrent and Planning Gates passed in this isolated worktree; accepted Design ADR and related project context loaded. Server companion: 20260916-design-media-blockers-6c8e2a91. Packaging and other active task scopes remain read-only and do not overlap this work.
• Root resumed exclusive client file ownership after pausing the authorized client worker for final contract/UI verification. Existing worker edits are retained; no second worker, root-main write or ownership takeover occurred.

Outcome

• Implementation complete locally. The shared contract carries capability-specific generation options and a prepare_generation user input; Main validates/serializes it and maps server snake_case capability fields into Renderer camelCase state. The store exposes prepareGeneration() and requestQuote() prepares the current draft before requesting an immutable revision-bound quote.
• YouthCreationCard media changes now call prepare, use real available aspect/duration/output limits, expose an explicit video first-frame selection path and retain references across media changes. Existing references can be promoted to first frame without deleting their assets; unsupported image references are shown with an explicit removal action. Save state no longer treats a blocked preparation as ready.
• DesignPlanHistory now presents generated videos with native controls, a large preview, download, and an explicit historical-image-to-video-first-frame action. The action only binds the asset to the design; it never deletes or silently selects among multiple images.
• The previous diagnosis is now addressed in the owned client slice: direct edits remain deterministic, while prepare_generation is the explicit semantic preparation command. Media conversion no longer pretends to be ready; the server response updates the form and blockers, and the UI keeps the recovery action visible.
• The old “已引用” display is now accompanied by actual reference-role handling. Uploading the first image for a video binds it as first_frame; selecting an existing image promotes it in place, preserves aliases and does not delete assets. Switching back to image leaves references intact and shows an explicit removal path when the real capability does not support them.
• The visible controls now consume capability-specific availability, ratios, durations, output limits and reference roles. The video option is not advertised when the server says it is unavailable, and invalid values remain visible as unavailable instead of being silently rewritten.
• The active history rail now exposes native video controls, a large video preview, download and “用作视频首帧” for historical images. All media URLs continue through the existing Main-owned resolver; no direct renderer HTTP was added.
• Final parent verification fixed actual path failures: entering video saves the supported duration rather than only displaying it; missing capability data disables generation instead of inventing options; prepare rejection stops quotation even without a live blocker event; failed conversion restores the saved medium. Explicit removal clears the starting-image pointer, and a prepared prompt is displayed from the server result rather than overwritten with the pre-preparation text.
• Youth-facing copy uses 视频开始画面 and 用这张图做视频. Actual first-frame selection shows 已选用 independently of @ aliases. Unsupported reference usage and missing starting images offer explicit guidance; assets are retained. The make-interfaces-feel-better skill influenced only new-control hit areas: video preview/download and history-image reuse use 40px targets, with video actions moved above native playback controls so they do not cover them.

Verification

• Initial pass read YouthCreationCard media/upload/button handlers, image-workspace store command construction, youth-issue-copy, production capability constructor and compiler in the paired server task. Follow-up implementation is component/store/adapter scoped; deployed version remains unverified.
• From this client worktree, DESIGN_DIAGNOSTIC_PYTHON points to the server Python and DESIGN_DIAGNOSTIC_SERVER to its companion worktree. pnpm exec vitest run --config scripts/diagnostics/vitest.design-flow.config.ts --reporter=verbose passed 2 tests. Commands are prepare (media/duration) -> prepare (selected image/motion) -> prepare (before quote) -> request_quote -> explicit confirm_generation. No client-side shot injection; the Python bridge invokes actual Workspace preparation and compiler with a fixture Reasoner. Quote/confirmation transport remains simulated; a separate real server lifecycle test covers Task execution with fixture provider/storage/ledger.
• Targeted final client run: pnpm exec vitest run tests/unit/video-first-frame.test.ts tests/unit/youth-creation-card.test.tsx tests/unit/works-square-design-workspace.test.ts tests/unit/image-workspace-route.test.ts tests/unit/image-workspace-store.test.ts --maxWorkers=1 passed 5 files / 76 tests. Typecheck and Vite Renderer/Main/Preload/utility builds passed. Whole-repository lint has 0 errors and 8 pre-existing warnings outside this slice. Build warnings concern stale browser data, existing chunk sizes and mixed imports.
• Electron E2E fixture updated for capabilities and requires prepare before quote at the latest revision; the Electron E2E suite was not run. No claim of desktop rendering/media decoding from jsdom assertions. Final docs/drift/whitespace gates are run before committing this handoff.
• Existing root node_modules reused through an ignored junction in this owned worktree; no packages installed or manifests changed. Tests use jsdom, simulated upload/HTTP/pricing, local server processes and a synthetic completed-video presentation fixture. No desktop app, real LLM, gateway transport, video playback bytes, production API or paid generation used.

Follow-ups

• Local client/server flow acceptance is complete with the stated fixtures. Keep semantic motion arrangement in the Agent and deterministic binding/cleanup in application code. Merge/deployment are not authorized by this implementation turn; update both server and client contracts together when subsequently approved.
• Reference selection must distinguish actual supported uses from a mere text mention. For video, explicitly identify which asset starts the clip; for image, align selectable uses with real backend capabilities. Do not silently drop references.
• Improve actionable capability-aware messages and controls. Separately verify installed client/server versions if deployed behavior differs from this local reproduction.
• Deployed acceptance remains pending: an explicitly approved real short-video generation must verify staging, model acceptance, output ingestion, event/reconnect behavior and actual playback bytes together. No production availability or generation-quality claim from fixture-backed passes; no paid generation was performed.

Promotion Candidates

• Target: accepted Design living-form ADR and UI capability coverage. Proposal: simple controls must produce semantically coherent drafts and cannot advertise success from text reference tokens alone. Evidence: exact client command/adapter changes, focused tests and paired compiler replay. Future impact: close a user-facing dead end without requiring children to edit first-frame/Shot fields. Human confirmation was provided for this implementation slice; integration into root main remains outside this child task.