artifact-canvas: revisit VSCode issue-preview migration once typography tokens (#1053) and comment system v2 (#1055) land (decision record)

[amrmelsayed]

Status

Tracking / decision record. Defer until predecessors land; revisit then. Same shape as #1029 (canvas package-split decision record).

Current state

Codev: View Issue (packages/vscode/src/commands/view-issue.ts) renders a backlog issue's body + comments as markdown into a read-only codev-issue:<id>.md TextDocumentContentProvider document, then opens VS Code's built-in markdown preview against it. The artifact-canvas surface that owns spec / plan / review rendering (#945, mounted by #859) is not in the issue path.

Considered

• A. Status quo: VS Code built-in markdown preview. Today's behavior. Ships find / zoom / print / code-block-copy / scroll-sync / link-handling for free.
• B. Migrate issue preview to the same artifact-canvas surface specs / plans / reviews use. Single rendering pipeline for all markdown surfaces in Codev; foundation for "review an issue inline" (gutter +, marker minimap, comment cards).

Pros of migrating

• Consistent typography + theming across every markdown surface in the IDE (compounding once vscode: typography tokens for the Codev Markdown Preview (artifact canvas) #1053 ships typography tokens).
• One rendering pipeline means future rendering improvements (HTML policy, code highlighting, marker rendering) apply to issues automatically.
• Sets the stage for inline-comment affordance on issues: same gutter +, same card stack, same minimap workflow reviewers already learned on specs / plans / reviews.
• Easier to reason about correctness (single data-line model, one DOMPurify policy, one set of theme tokens).

Cons of migrating today

• Issues aren't on-disk files. The canvas's data-line model + <!-- REVIEW: --> marker syntax assume line-anchored content that lives on disk. The renderer side is content-agnostic and would work, but the comment-write path is wrong shape: MarkerAdapter.add() writes a marker comment to a file; issues need a forge API call. A new IssueMarkerAdapter (or extension of the contract) has to ship before the canvas's gutter + affordance makes sense on issues, otherwise users see a + that doesn't actually post a comment.
• Loss of built-in features. VS Code's built-in preview ships find, zoom, print, code-block-copy, scroll-sync out of the box. Migrating means re-earning those affordances on a high-traffic surface, or shipping with the regression.
• Shape mismatch. The canvas is currently tuned for the spec / plan / review shape: long-form prose, occasional fenced code, deliberate data-line block attribution. Issue bodies + comment threads have a different shape: multiple author blocks, GitHub-flavored emojis, frequent <details> / images / metadata, denser per-section. Works, but not tuned for the use case.

Decision

Defer. Today's cost/benefit doesn't favor a migration. The dominant value (consistent typography, inline-comment affordance) is theoretical until the predecessors below land. Revisit when those have shipped.

Predecessors / blockers

• vscode: typography tokens for the Codev Markdown Preview (artifact canvas) #1053, typography tokens for the canvas. Must land first to make the "consistent typography across surfaces" value real rather than theoretical. Until typography tokens exist, switching surfaces is a regression on issue readability (the built-in preview has decent defaults).
• Comment system v2: durable thread storage + full lifecycle (edit / delete / reply / resolve) #1055, Comment system v2 (durable thread storage + lifecycle). Must land first so an IssueMarkerAdapter has an API-backed marker store to write to. Without Comment system v2: durable thread storage + full lifecycle (edit / delete / reply / resolve) #1055's storage model, the canvas's marker contract has no way to bridge between on-disk REVIEW comments and forge-issue comments.

When to revisit

Once #1053 has shipped AND #1055 has shipped (or is committed for the next cycle):

1. Re-run this cost/benefit with the actual shipped state.
2. Either close this issue as "won't do" if the predecessors changed the calculus, or promote to a PIR for the migration itself (visual verification at dev-approval is load-bearing for typography on a new high-traffic surface).

Out of scope

• Implementing the migration (this is a decision record only).
• Changing how the existing built-in preview behaves.
• Replacing the codev-issue: URI scheme (it survives any migration: the content-provider seam is orthogonal to which preview surface mounts it).
• A Reopen with Codev Canvas opt-in for issues (premature; same MarkerAdapter gap applies).

Related

• Build foundational reusable package @cluesmith/codev-artifact-canvas for cross-surface markdown artifact review #945, artifact-canvas foundation.
• vscode: add review comments from the markdown preview pane (hover-+ per block, no editor mode-switch) #859, first VS Code consumer of artifact-canvas (specs / plans / reviews preview).
• artifact-canvas: defer a core/web/native package split until native rendering is a committed requirement (decision record) #1029, sibling decision-record pattern (canvas package split deferred until native rendering is a committed requirement).
• vscode: typography tokens for the Codev Markdown Preview (artifact canvas) #1053, typography tokens (predecessor; must land first).
• Comment system v2: durable thread storage + full lifecycle (edit / delete / reply / resolve) #1055, Comment system v2 durable thread storage (predecessor; must land first).
• packages/vscode/src/commands/view-issue.ts, current issue rendering path.