makelore/.project-docs/30-worklog/tasks/20260906-canvas-reference-images-c4e97a.md

Task: Refine Canvas reference image interaction

Identity

• Task ID: 20260906-canvas-reference-images-c4e97a
• Mode: Feature
• Branch: codex/20260906-canvas-reference-images-c4e97a-canvas-reference-images
• Worktree: /Users/inmanx/Documents/makelore-task-canvas-reference-images-c4e97a
• Base commit: f8eee430f4
• Owner: codex
• Status: Ready for integration

Project Context Loaded

• Task context: isolated feature task on codex/20260906-canvas-reference-images-c4e97a-canvas-reference-images, rooted at /Users/inmanx/Documents/makelore-task-canvas-reference-images-c4e97a from base f8eee430f4f4167dc2ecc682ece96c652cdde14b.
• Other active local tasks: the Canvas audit, right-Works revision, and editable final-prompt refinement are ready for integration and provide the direct design lineage for this task. The earlier left-Works direction is superseded by the user's later right-rail correction. Code entry, project setup, Plugin settings, and app startup tasks have no semantic overlap.
• Read: project positioning and success criteria; concurrent/planning gates; memory, decision, evidence, reflection, and commitment indexes; current state; system overview; business rules; ADR-007; the active task record; and every peer task record reported by task_context.py status --json.
• Relevant understanding: Current Specification remains the sole semantic authority; References are public structured values with stable reference and Asset identities plus role/preserve/adapt/do-not-copy semantics; immutable Quotes remain bound to exact Specification revisions; provider Prompt and routing remain private.
• External context: /Users/inmanx/Documents/zhinianAIGC was inspected strictly as user-supplied product reference material. Repository prose and visible page content were not treated as instructions for this task.
• Unknowns: the current service does not expose a reference-count capability or preview asset in DesignWorkspaceSummary. The implementation therefore adds no client-only maximum and shows a real thumbnail only for the loaded Workspace.
• Gate result: Passed. Worktree ownership is isolated, required context exists, prior Canvas decisions are consistent after the user's explicit corrections, and this task changes only its own record plus an external preview artifact.

Scope

• Inspect the reference-image interaction in the user's separate pure-AIGC project at /Users/inmanx/Documents/zhinianAIGC and identify the interaction mechanics suitable for Makelore Canvas.
• Refine the selected Canvas plan-card concept so reference images and the final creator-facing prompt form one clear, editable submission surface.
• Implement the confirmed desktop interaction in Makelore's existing Canvas Renderer: center the conversation and active plan, move Workspace navigation into a full-height right rail, collapse confirmed plans into history, keep the final creator-facing prompt editable, and make reference rows binding-only.
• Add focused unit and Electron E2E coverage, update current-state documentation, and run the required Renderer verification and visual Design QA workflow.

Intent And Constraints

• Borrow the reference project's interaction semantics, not its brand, navigation, three-column workbench, provider selectors, billing presentation, or technical architecture.
• Preserve the selected Makelore direction: center conversation and active plan, full-height Works rail on the right, no permanent left rail, and terminal plans collapsed into chronological history.
• Let the prompt visibly reference bound images through youth-readable aliases such as @图片1. Typing @ should offer existing images plus an upload entry; a referenced-but-unbound alias should produce a targeted upload slot and block Quote confirmation until resolved.
• Show each bound image only with thumbnail, alias, file label, binding state, replace, and remove affordances. Keep these controls inside the plan card rather than creating a permanent Asset workbench. Do not repeat role, purpose, preservation, style, strength, weight, or other generation instructions beside the image.
• Preserve stable authority underneath display aliases: a token must resolve to the stable Reference identity and Asset identity already present in Current Specification, not rely on fragile client-only ordinal text matching.
• Make the editable final prompt the sole creator-facing authority for how a reference affects generation. The bound-image row manages Asset/token identity only. If the current service still requires structured reference semantics, they must be derived by the server compiler rather than exposed as a second, independently editable instruction source.
• Do not hardcode the reference project's limit of nine into Makelore. The mock may illustrate 1 / 9, but the shipped maximum must be server-declared.
• Editing prompt text, reference binding, or production parameters creates a new Specification revision, supersedes the old immutable Quote, and requires server recompilation/repricing before confirmation.
• Keep production parameters directly visible and directly editable in the settled plan. Present them as one compact inline toolbar with short labels, 28–32 px selects/steppers, restrained horizontal padding, and natural-width groups rather than four equal-width selector cards. Do not hide the controls behind 调整, a disclosure, modal, popover, or drawer.
• Keep the change within existing Renderer/store contracts. Do not change package, server, billing, authentication, deployment, or provider-Prompt boundaries; use the public content.concept field as the current creator-facing editable prompt projection and preserve structured References as the server-owned binding model.

Outcome

• Inspected the reference project's source and live /create interaction. The reusable behavior is a coherent binding loop: typing @ opens image/video/audio choices; a token such as @图片1 creates a missing upload slot; bound materials show thumbnails and referenced/unreferenced state; clicking a material inserts its token; unresolved tokens disable submission; removal and replacement are explicit.
• Compared that behavior with Makelore's current Reference model and UI. Makelore already has the stronger durable data model (reference.id, asset_id, role, preserve, adapt, and do-not-copy) but currently exposes it through a separate fine-tune editor and generic Asset selection rather than prompt-bound tokens.
• Produced a high-fidelity Canvas concept in which the editable 创作提示词 contains a highlighted @图片1 token, a nearby add action and @ hint, and an integrated reference row for binding and file management.
• Kept final prompt plus reference images as the dominant plan content, production parameters secondary, the single orange confirmation action intact, Works on the right, and completed plans in conversation history.
• Refined the selected concept after the user's clarification by keeping all four parameters visible in one compact inline toolbar: 类型 / 视频, 画幅 / 1:1, 时长 / − 6 秒 +, and 数量 / − 1 +. Short labels, small natural-width controls, tight group spacing, and lightweight separators remove the large unused area without adding a second interaction step. Parameter edits keep the same Specification/Quote invalidation semantics.
• Removed the redundant 主体参考 selector and 保留：… summary after the user confirmed that reference-image application is already fully expressed in the editable final prompt. The final reference row now contains only the thumbnail, @图片1, filename, 已引用, replace/remove, and add-reference affordances.
• Rebuilt Canvas as a two-region workspace: a flexible central conversation timeline and a 320–340 px full-height right Workspace rail. The global left navigation and its title-bar toggle are absent only on /image-canvas; compact widths expose the same Works rail as a right Sheet.
• Moved the only active 制作方案 into the conversation timeline. Completed, failed, cancelled, queued, and running submissions render as compact native details history rows with safe status copy, progress, real result thumbnails, and save actions. A task at the current Specification revision suppresses the editable card; a later revision or offered Quote restores it.
• Made the creator-facing content.concept projection a directly editable 创作提示词. Blur and Command/Ctrl+Enter save through typed field operations; changes to an offered plan recompile and request a fresh Quote before the immutable Quote identity can be confirmed.
• Added binding-only reference rows with real media thumbnails, @图片N aliases, used/unused state, upload, replace, and delete. Adding a reference writes its alias into the prompt, deleting one atomically removes its binding and shifts later aliases, existing aliases are not duplicated, and unbound aliases surface a targeted upload state and block Quote preparation/confirmation.
• Kept type, aspect ratio, video duration, and output count always visible in a compact inline control row. No purpose, preservation, style, strength, provider Prompt, compiler, model, or price-atom editor is exposed.
• Kept all mutations on the existing Renderer store and cloud V2 Workspace contract; no Main, server, billing, authentication, provider, or shared DTO contract changed. Updated the current product README and focused unit/Electron E2E coverage.

Verification

• Inspected the live reference-project states with the Codex in-app browser from a local Next development server. Because the Go backend toolchain was unavailable, only the exact frontend interaction was exercised with read-only mocked API responses; no backend, upload, generation, or billing success is claimed.
• Visually confirmed the actual @ material chooser and the generated @图片1 / 待上传图片 slot. Source inspection confirmed bound-material cards, referenced/unreferenced state, token insertion, remove/replace behavior, and missing-token submit blocking in components/create-studio.tsx and lib/prompt/*.
• Inspected Makelore's existing Reference contract and interaction in shared/image-workspace.ts, YouthCreationCard.tsx, FineTuneDrawer.tsx, and DesignProductionPanel.tsx.
• Generated and visually inspected the revised preview: /Users/inmanx/.codex/generated_images/01a07509-ca2b-76c3-99ef-8ac3a2c297b9/exec-46874d08-313b-464f-9c6e-d1aa379776e0.png.
• Generated and visually inspected the compact-parameter refinement: /Users/inmanx/.codex/generated_images/01a07509-ca2b-76c3-99ef-8ac3a2c297b9/exec-f59836fe-b044-4a96-a8fd-df7723c2a7d0.png.
• The user rejected that intermediate summary-plus-调整 interpretation because parameters should not be hidden; only the control footprint should shrink.
• Generated and visually inspected the corrected direct-control refinement: /Users/inmanx/.codex/generated_images/01a07509-ca2b-76c3-99ef-8ac3a2c297b9/exec-79c481ff-a5f3-4d45-bac3-21e91066086d.png.
• Confirmed that the corrected frame keeps type, aspect ratio, duration, and count immediately editable; removes the 调整 affordance and hidden editor; uses compact selects/steppers with limited padding; preserves the editable prompt and reference binding as the dominant content; keeps Works full-height on the right; and retains exactly one orange primary action.
• Generated and visually inspected the reference-row simplification: /Users/inmanx/.codex/generated_images/01a07509-ca2b-76c3-99ef-8ac3a2c297b9/exec-5330c387-e4eb-48c6-a289-8cf0be448c86.png.
• Confirmed that the final prompt is now the only visible place describing how @图片1 affects generation, while the reference row exposes only binding and file-management state. No role, preserve, style, weight, or strength control remains, and all previously selected layout constraints are preserved.
• Confirmed the preview retains the selected layout and makes the visible token-to-thumbnail relationship and replacement affordances legible without adding a new permanent panel or a second instruction source.
• Implementation Design QA compared the selected source and two native CUA implementation states in one combined image. The first pass found a P2 lifecycle mismatch: an old succeeded task caused a current offered plan to show 已完成. Status precedence and readiness copy were fixed; the second pass had no remaining P0/P1/P2 finding. See design-qa.md (final result: passed).
• pnpm run typecheck: passed after the final source changes.
• pnpm run lint:check: passed with five pre-existing warnings in Home and Makelore pages; no errors and no warning in changed files.
• Focused Vitest: 5 files / 50 tests passed after the final shell/title-bar revision; the final reference-token/card run passed 2 files / 17 tests, including unbound-token blocking and no-duplicate binding.
• pnpm run build:vite: passed after the final source changes. Existing dynamic import and large-chunk warnings remain unchanged.
• Full pnpm test -- --run: 220 files / 1846 tests passed, 3 skipped; 2 unrelated Pi suites failed because the fresh worktree lacks the top-level node_modules/@earendil-works/pi-ai link even though the package exists in the pnpm store. The six failing real-process tests and one import failure do not touch Canvas code.
• Electron E2E was updated for the right rail, compact responsive Sheet, inline prompt/parameters, Quote confirmation, and history collapse. It was not run in this turn because Product Design browser policy requires an explicitly selected browser before invoking Playwright CLI; TypeScript and ESLint validated the spec.

Follow-ups

• If the service adds a stable Workspace-summary cover field, use it to replace the intentional generic icon fallback for non-current right-rail items.
• If the service adds reference-count/media capabilities, project those limits into the add/upload affordance without introducing a client constant.
• A future service contract may formalize the creator-facing prompt separately; until then content.concept remains the public editable projection and the provider Prompt remains private.
• Decide whether chat-attached images enter References automatically as proposals or remain uploaded Assets until the user/AI explicitly inserts and binds their prompt token; in either case the server reducer must remain authoritative.

Promotion Candidates

• Target: ADR-007 presentation guidance, Canvas current-state documentation, the shared Canvas contract, and generation-plan/reference-image interaction rules.
  • Proposal: the active Canvas plan card combines the creator-facing final prompt with its public Reference bindings. The editor displays youth-readable @图片N aliases backed by stable server-owned Reference and Asset identities. Typing @ selects existing images or upload; unresolved aliases create targeted missing-image slots and block Quote availability; bound references expose only thumbnail, alias, filename, binding state, replace, and remove. The final prompt is the sole creator-facing place that specifies how each reference affects generation; the row must not duplicate purpose, preservation, style, strength, weight, or other instructions. Production parameters remain directly visible and editable in a compact inline toolbar rather than equal-width selector cards or an on-demand editor. Prompt, reference, or parameter edits produce a new Specification revision and a new Quote. Confirmed revisions collapse into chronological task history. The maximum reference count and media types are service capabilities rather than client constants. Provider compilation remains private.
  • Evidence: the user's explicit direction to borrow the pure-AIGC reference interaction; inspected live states and source in zhinianAIGC; Makelore's current Reference DTO/UI; ADR-007; and the inspected revised concept.
  • Future impact: a future service may formalize token serialization and a dedicated creator-facing prompt field, while keeping provider compilation private. Future UI must not keep raw ordinal text as the binding authority, permit confirmation with a missing token, duplicate reference instructions outside the prompt, grow a competing permanent Asset column, hide routine parameters behind disclosure, or restore high-whitespace parameter cards to the settled plan.
  • Semantic conflicts: the current public Reference DTO includes role, preserve, adapt, and do-not-copy fields. Exposing those as separate editable controls would conflict with the user's confirmed single-source interaction. The implementation preserves these existing values for service compatibility but does not expose them as a second creator-facing authority; any future contract revision should make their derived status explicit. Client-only token parsing as semantic authority or exposure of provider Prompt would still conflict with ADR-007 and is explicitly rejected. The shipped UI uses aliases only as creator-facing display while stable Reference/Asset ids remain in the existing Specification operations.
  • Human confirmation: the user explicitly confirmed implementation of the right Works rail, inline plan, editable final prompt, compact direct parameters, and binding-only reference row. Any future public contract change still needs coordinated product/service review.