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: f8eee430f4f4167dc2ecc682ece96c652cdde14b
- 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.