[Yuqing (mydmdm)]

Summary

Progresses #351 with the approved File Reference Preview Comment phase, following the merged Note Comment phase (#352) and read-only File Explorer (#355).

• Add Comment to a single nonempty contiguous selection in the existing UTF-8 file preview. Capture text and bounded context from CodeMirror's loaded document model, including virtualized lines, without reading more bytes or ingesting the whole file.
• Freeze source-device identity, canonical file path, filesystem contentVersion, UTF-16 selection range and loaded-document extent/completeness. Extend the canonical shared quote schema and escaped source-specific renderer; preserve metadata through dispatch, retry, draft consumption/restoration, durable envelopes, transcript/history and browser hydration.
• Extract the existing Note destination-aware editor into PreviewCommentEditor; reuse the same existing-conversation picker, ownership/busy/fork rules and hidden-draft View input notification. Do not create/realize Agents, automatically send or navigate.
• Keep the viewer lazy, readonly and plain text. Disable new captures while loading or showing a read failure. An opened Comment retains its labeled capture-time snapshot across source refresh/read-more/failure.
• Update device-files, preview, agent-context, API and web architecture contracts.

Scope boundaries

Chat and Note retain existing behavior. Ink/Lasso, raw Note source mode, PDF/Web/Office/media previews and bootstrap execution-machine identity are unchanged. No new endpoint, dependency, subtree modification, remote file write/import or permission expansion. A source-device path is not a claim that the receiving Agent can access that device. The filesystem version is not a content hash or retained historical revision.

Validation

• Repository pnpm typecheck, pnpm format, pnpm lint:fix: passed. Lint reports zero errors and 337 existing warnings; focused lint on new implementation/tests is clean. Final affected web/server type checks and formatting/whitespace checks passed.
• Web: 12 files / 273 tests passed, including File Preview/CodeMirror selection, Note/Chat comments, destination rules, draft/history/dispatch/retry and unchanged Ink picker/submission/toolbar.
• Shared Agent schema: 32 tests passed.
• Server envelope, canonical prompt/replay and transcript history: 84 tests passed.
• Isolated Chromium Playwright: 9 browser tests passed (2 File mouse/touch, 2 existing Note mouse/touch, 5 existing Chat quotation cases). New file tests mock only device-files HTTP results and exercise production Preview/CodeMirror/staging/focus behavior without a connected device.
• Localization parity, copyright headers and git diff --check: passed.
• File-source template reviewed with the agent-primitives rubric; no findings.

Known limitations

• The extended browser run also selected 10 existing Ink toolbar specs; all stop before mounting Ink at a pre-existing alpha fixture mismatch: they assert 12 playground toolbars, while feat(files): add read-only connected-device explorer #355 added the thirteenth File Reference specimen. Both the stale assertion and extra specimen are present in the unchanged alpha baseline. This PR does not change those unrelated fixtures; the Ink unit regressions pass.
• Real Agentlet reads, physical iPad/native selection menus, pen hardware and non-Chromium browsers were not verified in this phase. Unsent drafts remain runtime-only.
• File previews remain loaded-prefix views capped at 256 KiB. No automatic full-file reads or persistent file annotations are added.

This is a new phase PR to alpha; it does not merge a PR, close the issue, deploy or release.