From eded43c9b8abae13be28255464489a02b41a0a23 Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Tue, 30 Jun 2026 09:23:50 +1000
Subject: [PATCH 01/23] chore(porch): 1107 init pir

---
 .../status.yaml                                | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)
 create mode 100644 codev/projects/1107-vscode-replace-top-of-window-q/status.yaml

diff --git a/codev/projects/1107-vscode-replace-top-of-window-q/status.yaml b/codev/projects/1107-vscode-replace-top-of-window-q/status.yaml
new file mode 100644
index 000000000..9cbb2ef57
--- /dev/null
+++ b/codev/projects/1107-vscode-replace-top-of-window-q/status.yaml
@@ -0,0 +1,18 @@
+id: '1107'
+title: vscode-replace-top-of-window-q
+protocol: pir
+phase: plan
+plan_phases: []
+current_plan_phase: null
+gates:
+  plan-approval:
+    status: pending
+  dev-approval:
+    status: pending
+  pr:
+    status: pending
+iteration: 1
+build_complete: false
+history: []
+started_at: '2026-06-29T23:23:50.850Z'
+updated_at: '2026-06-29T23:23:50.851Z'

From 907ed56b883ac09de961ea5c9cb138781a2b09bb Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Tue, 30 Jun 2026 09:29:08 +1000
Subject: [PATCH 02/23] [PIR #1107] Plan draft: inline composer for
 preview-pane review comments

---
 .../1107-preview-inline-comment-composer.md   | 194 ++++++++++++++++++
 codev/state/pir-1107_thread.md                |  36 ++++
 2 files changed, 230 insertions(+)
 create mode 100644 codev/plans/1107-preview-inline-comment-composer.md
 create mode 100644 codev/state/pir-1107_thread.md

diff --git a/codev/plans/1107-preview-inline-comment-composer.md b/codev/plans/1107-preview-inline-comment-composer.md
new file mode 100644
index 000000000..2eb9ef72b
--- /dev/null
+++ b/codev/plans/1107-preview-inline-comment-composer.md
@@ -0,0 +1,194 @@
+# Plan — #1107: Inline composer for preview-pane review comments
+
+> PIR plan. The GitHub issue (#1107) is the implicit spec. This document is the
+> **plan-approval** artifact: how the change is built, where it lands, the risks,
+> and the test plan. Reviewed before any code is written.
+
+## Understanding
+
+Adding a review comment from the Codev Markdown Preview
+(`codev.openMarkdownPreview`) currently collects the comment body with
+`vscode.window.showInputBox` — rendered in VS Code's center-top Quick Pick
+chrome, physically far from the block the user clicked `+` on. The cognitive
+distance between the block being commented on and the input box is the friction
+the issue targets. The issue recommends **Option A**: render an inline composer
+in the webview/canvas itself, co-located with the block, so the visual anchor is
+preserved end-to-end while typing.
+
+What the codebase already gives us:
+
+- `packages/artifact-canvas/src/components/ArtifactCanvas.tsx` is the shared React
+  canvas. It already renders a React overlay **anchored at the active block's
+  vertical center** (`overlayTop`, set in `activateFromTarget`). Today that
+  overlay carries only the `CommentAffordance` (`+`) button, which calls
+  `onAddComment(line)` — the intent-only seam (spec 945 D6). The host then runs
+  the text input and write-back.
+- The marker-card stack (existing comments) is injected imperatively into the
+  innerHTML-managed body. The overlay, by contrast, is **React-owned** — which is
+  exactly where an interactive composer belongs (clean state / focus / Esc, no
+  "cards flash then vanish" re-render hazard).
+- `packages/core/src/review-markers.ts` `serializeReviewMarker` **already
+  normalizes the body to a single line** (`body.replace(/\s+/g, ' ').trim()`). So
+  a multi-line composer is purely an input ergonomics improvement; the on-disk
+  marker form is unchanged. **No marker-format change is in scope** — #1055 owns
+  the v2 format. Newlines typed in the composer collapse to spaces on write,
+  matching today's single-line `<!-- REVIEW(@author): body -->` convention.
+
+So the work is: move the text input from the host's Quick Pick into a
+React composer in the canvas overlay, and widen the comment-intent seam to carry
+the collected text.
+
+## Proposed change
+
+### 1. New composer component (artifact-canvas package)
+
+Add `packages/artifact-canvas/src/overlays/CommentComposer.tsx`: a small
+React component — a `<textarea>` plus **Submit** / **Cancel** affordances. Props:
+
+```ts
+interface CommentComposerProps {
+  line: number;                       // 0-based source line (for aria-label)
+  onSubmit: (text: string) => void;   // non-empty body
+  onCancel: () => void;
+}
+```
+
+Behavior:
+- Autofocuses the textarea on mount.
+- **Cmd/Ctrl+Enter submits**; **Enter inserts a newline** (multi-line natural);
+  **Esc cancels**. (This keystroke mapping is the main thing to confirm at the
+  dev-approval gate — see Risks.) Submit and Cancel buttons provide the same two
+  actions for mouse / accessibility.
+- Submit is a no-op (does not emit) when the trimmed body is empty — mirrors
+  today's `if (!text) return;` guard in the host.
+- `aria-label` on the textarea references the 1-based line (matches the
+  `CommentAffordance` accessibility convention).
+
+### 2. Wire the composer into ArtifactCanvas
+
+In `ArtifactCanvas.tsx`:
+- Add `composingLine: number | null` state.
+- The `+` click (`CommentAffordance.onActivate`) and the keyboard Enter/Space path
+  now **open the composer** (`setComposingLine(line)`) instead of calling
+  `onAddComment` directly.
+- When `composingLine !== null`, the overlay renders `<CommentComposer>` (anchored
+  at the same `overlayTop` as the `+`, so it appears right at the block) **instead
+  of** the `+` button.
+- On composer submit: call `onAddComment(line, text)`, then `setComposingLine(null)`.
+- On composer cancel / Esc: `setComposingLine(null)` and restore focus to the
+  block (or the `+`), so keyboard users aren't stranded.
+- Clear `composingLine` if a content reload removes the active block (extend the
+  existing `setActiveLine` reconciliation guard in the `[html, markers]` effect),
+  so the composer can't dangle over a line the new content no longer has.
+
+### 3. Widen the comment-intent seam
+
+In `packages/artifact-canvas/src/types.ts`, change:
+
+```ts
+onAddComment(line: number): void;
+// →
+onAddComment(line: number, text: string): void;
+```
+
+This is a deliberate contract amendment to the spec-945 "locked" public surface,
+recorded here as the PIR plan (the issue is the spec). The text is now collected
+inside the canvas, so the seam carries it. The only production consumer is the
+VSCode webview (updated below); `examples/main.tsx` is a dev aid (updated too).
+`MarkerAdapter.add` stays host-invoked and unchanged — the package still never
+writes markers itself (D6 invariant preserved).
+
+### 4. Host: drop the Quick Pick
+
+- `packages/vscode/src/markdown-preview/webview/main.ts`: change the callback to
+  `onAddComment: (line, text) => vscodeApi.postMessage({ type: 'addComment', line, text })`.
+- `packages/vscode/src/markdown-preview/preview-provider.ts`:
+  - The `onDidReceiveMessage` handler reads `m.text` (string) alongside `m.line`.
+  - `addComment(document, line, text)` **drops `showInputBox`** and writes the
+    marker directly from the posted `text` (guard empty → no-op). The
+    `WorkspaceEdit` / `serializeReviewMarker` / `document.save()` path is unchanged.
+  - Update the class doc comment (lines ~18-21) that describes the `showInputBox`
+    flow, so the architecture note matches the inline-composer reality.
+
+### 5. Styling
+
+Add `.codev-canvas-comment-composer` (and child) rules to
+`packages/artifact-canvas/src/styles/default-theme.css`, using the existing
+`--codev-canvas-*` tokens (border, background, accent, foreground) so the composer
+matches the preview's prose typography and theme. The composer is positioned via
+the existing overlay anchor; give it a sensible width and let it sit beside/below
+the block without overlapping prose.
+
+## Files to change
+
+| File | Change |
+|---|---|
+| `packages/artifact-canvas/src/overlays/CommentComposer.tsx` | **New** — textarea + Submit/Cancel composer |
+| `packages/artifact-canvas/src/components/ArtifactCanvas.tsx` | `composingLine` state; open composer on `+`/Enter; render composer in overlay; emit `onAddComment(line, text)` on submit; reconcile on reload |
+| `packages/artifact-canvas/src/types.ts` | `onAddComment(line, text)` signature + doc |
+| `packages/artifact-canvas/src/styles/default-theme.css` | `.codev-canvas-comment-composer` rules |
+| `packages/artifact-canvas/examples/main.tsx` | Update dev-example `onAddComment` to new signature |
+| `packages/vscode/src/markdown-preview/webview/main.ts` | Post `text` with `addComment` |
+| `packages/vscode/src/markdown-preview/preview-provider.ts` | Drop `showInputBox`; read `text` from message; write marker from it; update doc comment |
+| `packages/artifact-canvas/src/components/__tests__/artifact-canvas.test.tsx` | Update click/Enter tests to the open-composer→submit flow |
+| `packages/artifact-canvas/src/overlays/__tests__/comment-composer.test.tsx` | **New** — composer unit tests |
+
+## Risks & alternatives
+
+- **Keystroke mapping (primary dev-gate question).** Cmd/Ctrl+Enter-to-submit with
+  Enter=newline is the GitHub-review-composer convention and supports multi-line
+  naturally, but it changes the muscle memory from today's single-line
+  Enter-to-submit Quick Pick. This is exactly the kind of "does it feel right under
+  real usage" call the PIR dev-approval gate exists for — the reviewer runs the
+  preview and confirms submit / cancel / multi-line / focus behavior. Easy to flip
+  to Enter-submit + Shift+Enter-newline if preferred.
+- **Public-contract change.** Widening `onAddComment` touches the spec-945 "locked"
+  surface. Contained: one production consumer, updated in the same PR; the D6
+  "package never writes markers" invariant is preserved. Documented in types.ts and
+  the review's Architecture Updates.
+- **Imperative-body interaction.** The composer is React-owned in the overlay, NOT
+  injected into the innerHTML body, so it sidesteps the marker-card re-render hazard
+  entirely. The reconciliation guard for a vanished active line is extended to also
+  clear `composingLine`.
+- **Multi-line vs single-line storage.** The composer accepts multi-line input;
+  `serializeReviewMarker` collapses it to one line on write (unchanged behavior).
+  No marker-format change here. If #1055 (v2 format) lands later, the composer's
+  single submit site is the natural place to emit v2 markers.
+- **Alternatives considered & rejected:** Option B (VS Code Comments API) forces a
+  context switch back to the source editor, losing the read-while-write posture;
+  Option C (floating popup) is still essentially relocated Quick Pick UX. Option A
+  is the only one that preserves the visual anchor end-to-end (issue's recommendation).
+
+## Test plan
+
+**Unit (vitest, artifact-canvas):**
+- `comment-composer.test.tsx` (new): autofocus; Cmd/Ctrl+Enter submits trimmed body;
+  Enter inserts newline (does not submit); Esc cancels; empty/whitespace submit is a
+  no-op; Submit/Cancel buttons work.
+- `artifact-canvas.test.tsx` (updated): `+` click opens the composer (no immediate
+  `onAddComment`); submitting the composer emits `onAddComment(line, text)`; Enter on
+  a focused block opens the composer; the round-trip test drives text through the
+  composer; D6 invariant (`markerAdapter.add` never called by the package) preserved;
+  reload removing the active block clears the composer.
+
+**Build / typecheck:**
+- `pnpm --filter @cluesmith/codev-artifact-canvas check-types` and `build`.
+- `pnpm --filter @cluesmith/codev-vscode` build/typecheck (the webview script is
+  esbuild-bundled and excluded from tsc, per its file header — verify the host-side
+  `preview-provider.ts` typechecks).
+
+**Manual (dev-approval gate — the killer move):**
+Run the worktree, open a spec/plan/review in the Codev Markdown Preview, click `+`
+on several blocks (top, middle, bottom of a long doc), and confirm:
+- The composer appears at the block, not at the top of the window.
+- The block stays visible while typing (anchor preserved).
+- Submit writes the marker; the comment card appears below the block.
+- Multi-line input works; Esc cancels cleanly; focus is restored on cancel.
+- Keyboard-only flow (Tab to `+`, Enter to open, type, Cmd/Ctrl+Enter to submit).
+
+## Out of scope (per issue)
+
+Source-editor `Codev: Add Review Comment` (`commands/review.ts`); the summary
+webview (#860); codelens diff-editor comments (#1037); comment lifecycle
+edit/delete/reply/resolve (#1055); author identity / placeholder / discoverability
+(#857). Marker on-disk format change (#1055).
diff --git a/codev/state/pir-1107_thread.md b/codev/state/pir-1107_thread.md
new file mode 100644
index 000000000..9bca2eead
--- /dev/null
+++ b/codev/state/pir-1107_thread.md
@@ -0,0 +1,36 @@
+# PIR #1107 — Inline composer for preview-pane review comments
+
+Builder: `pir-1107` · Branch: `builder/pir-1107` · Protocol: PIR
+
+## Phase: Plan
+
+### Investigation (2026-06-30)
+Goal: replace `vscode.window.showInputBox` (center-top Quick Pick) in the markdown
+preview's add-comment flow with an inline composer co-located with the clicked block.
+
+Key files mapped:
+- `packages/vscode/src/markdown-preview/preview-provider.ts:92-113` — host `addComment`
+  uses `showInputBox`, then writes the marker via `WorkspaceEdit`.
+- `packages/vscode/src/markdown-preview/webview/main.ts` — webview bridge; posts
+  `{ type: 'addComment', line }` to the host; mounts `<ArtifactCanvas>`.
+- `packages/artifact-canvas/src/components/ArtifactCanvas.tsx` — shared React canvas.
+  `+` click / Enter on a focused block calls `onAddComment(line)` (intent-only seam, D6).
+  Overlay is React-rendered and anchored at the block's vertical center via `overlayTop`.
+- `packages/artifact-canvas/src/overlays/CommentAffordance.tsx` — the `+` button.
+- `packages/core/src/review-markers.ts` — `serializeReviewMarker` **already normalizes
+  body to single line** (`/\s+/g → ' '`). So multi-line composer input is fine; on-disk
+  format is unchanged. No marker-format change needed in this issue (#1055 owns v2 format).
+
+### Design decision
+Going with **Option A** (issue's recommendation): inline composer rendered by the
+webview/canvas. Render it as a React component in the existing overlay (anchored at the
+block via `overlayTop`) — keeps it React-owned (clean state / focus / Esc), avoids the
+innerHTML-managed body's "cards flash then vanish" hazard, reuses the anchor mechanism.
+
+Seam change: `onAddComment(line)` → `onAddComment(line, text)`. Click/Enter now *opens*
+the composer; submit emits with text. Host drops `showInputBox` and writes the marker
+directly from the posted text. Only production consumer is the vscode webview (+ a dev
+example), so blast radius is contained.
+
+Open UX question for the dev-approval gate: submit-on-Enter vs Cmd/Ctrl+Enter (with Enter
+= newline for multi-line). Leaning Cmd/Ctrl+Enter to submit + Esc to cancel + buttons.

From 1a1eb2f08e6ea99408b8432dc9dae5225dc36f2c Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Tue, 30 Jun 2026 09:29:21 +1000
Subject: [PATCH 03/23] chore(porch): 1107 plan-approval gate-requested

---
 codev/projects/1107-vscode-replace-top-of-window-q/status.yaml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/codev/projects/1107-vscode-replace-top-of-window-q/status.yaml b/codev/projects/1107-vscode-replace-top-of-window-q/status.yaml
index 9cbb2ef57..7583e42c0 100644
--- a/codev/projects/1107-vscode-replace-top-of-window-q/status.yaml
+++ b/codev/projects/1107-vscode-replace-top-of-window-q/status.yaml
@@ -7,6 +7,7 @@ current_plan_phase: null
 gates:
   plan-approval:
     status: pending
+    requested_at: '2026-06-29T23:29:21.703Z'
   dev-approval:
     status: pending
   pr:
@@ -15,4 +16,4 @@ iteration: 1
 build_complete: false
 history: []
 started_at: '2026-06-29T23:23:50.850Z'
-updated_at: '2026-06-29T23:23:50.851Z'
+updated_at: '2026-06-29T23:29:21.704Z'

From a650c60ee6c55440499bd8fd97cdba63d4dd8fff Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Tue, 30 Jun 2026 09:29:39 +1000
Subject: [PATCH 04/23] [PIR #1107] Update thread: plan-approval gate pending

---
 codev/state/pir-1107_thread.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/codev/state/pir-1107_thread.md b/codev/state/pir-1107_thread.md
index 9bca2eead..9cb67d011 100644
--- a/codev/state/pir-1107_thread.md
+++ b/codev/state/pir-1107_thread.md
@@ -34,3 +34,9 @@ example), so blast radius is contained.
 
 Open UX question for the dev-approval gate: submit-on-Enter vs Cmd/Ctrl+Enter (with Enter
 = newline for multi-line). Leaning Cmd/Ctrl+Enter to submit + Esc to cancel + buttons.
+
+### Plan committed → plan-approval gate pending (2026-06-30)
+Plan written to `codev/plans/1107-preview-inline-comment-composer.md`, committed and
+pushed (907ed56b). `porch check` + `porch done` passed; `plan-approval` gate is now
+**pending**. Waiting for human review. Implementation does not start until the gate is
+approved.

From a2c84366606f7c2deb73d8424a38fb9de8040b67 Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Tue, 30 Jun 2026 09:50:49 +1000
Subject: [PATCH 05/23] [PIR #1107] Revise plan: composer renders in-flow below
 block (portal)

---
 .../1107-preview-inline-comment-composer.md   | 96 ++++++++++++-------
 codev/state/pir-1107_thread.md                | 10 ++
 2 files changed, 72 insertions(+), 34 deletions(-)

diff --git a/codev/plans/1107-preview-inline-comment-composer.md b/codev/plans/1107-preview-inline-comment-composer.md
index 2eb9ef72b..c01929534 100644
--- a/codev/plans/1107-preview-inline-comment-composer.md
+++ b/codev/plans/1107-preview-inline-comment-composer.md
@@ -18,15 +18,22 @@ preserved end-to-end while typing.
 What the codebase already gives us:
 
 - `packages/artifact-canvas/src/components/ArtifactCanvas.tsx` is the shared React
-  canvas. It already renders a React overlay **anchored at the active block's
-  vertical center** (`overlayTop`, set in `activateFromTarget`). Today that
-  overlay carries only the `CommentAffordance` (`+`) button, which calls
-  `onAddComment(line)` — the intent-only seam (spec 945 D6). The host then runs
-  the text input and write-back.
-- The marker-card stack (existing comments) is injected imperatively into the
-  innerHTML-managed body. The overlay, by contrast, is **React-owned** — which is
-  exactly where an interactive composer belongs (clean state / focus / Esc, no
-  "cards flash then vanish" re-render hazard).
+  canvas. It renders a React overlay with the `CommentAffordance` (`+`) button
+  anchored at the active block's vertical center (`overlayTop`); the `+` calls
+  `onAddComment(line)` — the intent-only seam (spec 945 D6). The host then runs the
+  text input and write-back.
+- The **read-only comment cards** (existing comments) are injected imperatively as
+  **in-flow DOM siblings directly below the block** (`.codev-canvas-marker-cards`,
+  built in `buildMarkerCards` and inserted via `el.after(...)` in the `[html,
+  markers]` effect). They sit in normal flow and push following content down.
+- **Decision (reviewer, 2026-06-30): the composer renders in the same in-flow
+  location as those read-only cards** — directly below the block, where the comment
+  will live after submit — rather than in the left-gutter overlay. This keeps the
+  add flow visually consistent with the existing card pattern and sets the precedent
+  #1055 (edit mode) will reuse. To stay React-owned (clean state / focus / Esc) while
+  living in the innerHTML-managed body, the composer mounts via **`ReactDOM.createPortal`
+  into an in-flow placeholder element** injected below the block — the standard
+  React-into-imperative-DOM pattern.
 - `packages/core/src/review-markers.ts` `serializeReviewMarker` **already
   normalizes the body to a single line** (`body.replace(/\s+/g, ' ').trim()`). So
   a multi-line composer is purely an input ergonomics improvement; the on-disk
@@ -64,22 +71,33 @@ Behavior:
 - `aria-label` on the textarea references the 1-based line (matches the
   `CommentAffordance` accessibility convention).
 
-### 2. Wire the composer into ArtifactCanvas
+### 2. Wire the composer into ArtifactCanvas (in-flow, via portal)
 
 In `ArtifactCanvas.tsx`:
-- Add `composingLine: number | null` state.
+- Add `composingLine: number | null` state and a `composerHost: HTMLElement | null`
+  state (the in-flow placeholder node the composer portals into).
 - The `+` click (`CommentAffordance.onActivate`) and the keyboard Enter/Space path
   now **open the composer** (`setComposingLine(line)`) instead of calling
-  `onAddComment` directly.
-- When `composingLine !== null`, the overlay renders `<CommentComposer>` (anchored
-  at the same `overlayTop` as the `+`, so it appears right at the block) **instead
-  of** the `+` button.
+  `onAddComment` directly. The `+` for that line is suppressed while its composer is
+  open.
+- A dedicated effect keyed on `[composingLine, html, markers]` manages the
+  placeholder: remove any prior `.codev-canvas-comment-composer-host`, and if
+  `composingLine !== null`, find the first `[data-line="<composingLine>"]` block and
+  insert a fresh placeholder `<div>` **after the block's marker-card stack** (so the
+  composer sits below any existing comments, like appending to a thread). Store the
+  node via `setComposerHost`. This mirrors the marker-card injection and survives
+  markers-only updates (the body isn't rebuilt then; the effect re-runs and re-places
+  the placeholder). If the block no longer exists after a reload, clear
+  `composingLine` (so the composer can't dangle).
+- Render `composerHost && composingLine !== null ? createPortal(<CommentComposer
+  line={composingLine} ... />, composerHost) : null`. The portal keeps the composer's
+  state / focus / Esc React-owned even though its host node lives in the
+  imperatively-managed body.
 - On composer submit: call `onAddComment(line, text)`, then `setComposingLine(null)`.
-- On composer cancel / Esc: `setComposingLine(null)` and restore focus to the
-  block (or the `+`), so keyboard users aren't stranded.
-- Clear `composingLine` if a content reload removes the active block (extend the
-  existing `setActiveLine` reconciliation guard in the `[html, markers]` effect),
-  so the composer can't dangle over a line the new content no longer has.
+  The host write-back fires a document change → re-list → the new card renders in the
+  spot the composer occupied.
+- On composer cancel / Esc: `setComposingLine(null)` and restore focus to the block
+  (or its `+`), so keyboard users aren't stranded.
 
 ### 3. Widen the comment-intent seam
 
@@ -112,19 +130,21 @@ writes markers itself (D6 invariant preserved).
 
 ### 5. Styling
 
-Add `.codev-canvas-comment-composer` (and child) rules to
+Add `.codev-canvas-comment-composer-host` (the in-flow placeholder) and
+`.codev-canvas-comment-composer` (and child) rules to
 `packages/artifact-canvas/src/styles/default-theme.css`, using the existing
 `--codev-canvas-*` tokens (border, background, accent, foreground) so the composer
-matches the preview's prose typography and theme. The composer is positioned via
-the existing overlay anchor; give it a sensible width and let it sit beside/below
-the block without overlapping prose.
+matches the preview's prose typography and theme. Mirror the
+`.codev-canvas-marker-cards` left-rule / spacing so the open composer reads as the
+in-progress sibling of the comment cards it will become. The textarea is
+full-width within the prose column; Submit / Cancel sit on a footer row.
 
 ## Files to change
 
 | File | Change |
 |---|---|
 | `packages/artifact-canvas/src/overlays/CommentComposer.tsx` | **New** — textarea + Submit/Cancel composer |
-| `packages/artifact-canvas/src/components/ArtifactCanvas.tsx` | `composingLine` state; open composer on `+`/Enter; render composer in overlay; emit `onAddComment(line, text)` on submit; reconcile on reload |
+| `packages/artifact-canvas/src/components/ArtifactCanvas.tsx` | `composingLine` + `composerHost` state; open composer on `+`/Enter; inject in-flow placeholder below the block + `createPortal` the composer into it; emit `onAddComment(line, text)` on submit; reconcile on reload |
 | `packages/artifact-canvas/src/types.ts` | `onAddComment(line, text)` signature + doc |
 | `packages/artifact-canvas/src/styles/default-theme.css` | `.codev-canvas-comment-composer` rules |
 | `packages/artifact-canvas/examples/main.tsx` | Update dev-example `onAddComment` to new signature |
@@ -146,10 +166,16 @@ the block without overlapping prose.
   surface. Contained: one production consumer, updated in the same PR; the D6
   "package never writes markers" invariant is preserved. Documented in types.ts and
   the review's Architecture Updates.
-- **Imperative-body interaction.** The composer is React-owned in the overlay, NOT
-  injected into the innerHTML body, so it sidesteps the marker-card re-render hazard
-  entirely. The reconciliation guard for a vanished active line is extended to also
-  clear `composingLine`.
+- **Imperative-body interaction (the main implementation risk).** The composer lives
+  in-flow below the block, so its host placeholder is injected into the
+  innerHTML-managed body — the same surface as the read-only cards. The "cards flash
+  then vanish" hazard is avoided by (a) portalling the composer (React owns its
+  content / focus / state; only the host *node* is in the body), and (b) re-placing
+  the placeholder in the `[composingLine, html, markers]` effect, which re-runs on the
+  same triggers that rebuild/redecorate the body. A document change while composing
+  (rare — the reviewer is typing, not editing the file) rebuilds the body; the effect
+  re-injects the placeholder and the portal re-attaches. The reconciliation guard also
+  clears `composingLine` if the target block disappears on reload.
 - **Multi-line vs single-line storage.** The composer accepts multi-line input;
   `serializeReviewMarker` collapses it to one line on write (unchanged behavior).
   No marker-format change here. If #1055 (v2 format) lands later, the composer's
@@ -165,11 +191,13 @@ the block without overlapping prose.
 - `comment-composer.test.tsx` (new): autofocus; Cmd/Ctrl+Enter submits trimmed body;
   Enter inserts newline (does not submit); Esc cancels; empty/whitespace submit is a
   no-op; Submit/Cancel buttons work.
-- `artifact-canvas.test.tsx` (updated): `+` click opens the composer (no immediate
-  `onAddComment`); submitting the composer emits `onAddComment(line, text)`; Enter on
-  a focused block opens the composer; the round-trip test drives text through the
-  composer; D6 invariant (`markerAdapter.add` never called by the package) preserved;
-  reload removing the active block clears the composer.
+- `artifact-canvas.test.tsx` (updated): `+` click opens the composer **in-flow below
+  the block** (placeholder is a sibling after the block / its card stack, not in the
+  gutter; no immediate `onAddComment`); submitting the composer emits
+  `onAddComment(line, text)`; Enter on a focused block opens the composer; the
+  round-trip test drives text through the composer; D6 invariant (`markerAdapter.add`
+  never called by the package) preserved; reload removing the active block clears the
+  composer.
 
 **Build / typecheck:**
 - `pnpm --filter @cluesmith/codev-artifact-canvas check-types` and `build`.
diff --git a/codev/state/pir-1107_thread.md b/codev/state/pir-1107_thread.md
index 9cb67d011..6386fc182 100644
--- a/codev/state/pir-1107_thread.md
+++ b/codev/state/pir-1107_thread.md
@@ -40,3 +40,13 @@ Plan written to `codev/plans/1107-preview-inline-comment-composer.md`, committed
 pushed (907ed56b). `porch check` + `porch done` passed; `plan-approval` gate is now
 **pending**. Waiting for human review. Implementation does not start until the gate is
 approved.
+
+### Plan revised on reviewer feedback (2026-06-30)
+Reviewer asked to show the visual and questioned placement vs the existing read-only
+cards. Settled a design fork: **composer renders in-flow directly below the block**
+(same location as the read-only `.codev-canvas-marker-cards`), not in the gutter
+overlay. Implementation: inject an in-flow placeholder below the block and
+`createPortal` the composer into it (React-owned state/focus/Esc, in-flow position).
+Clarified scope: this issue is **add only**; edit/delete/reply/resolve = #1055. The
+composer sets the visual precedent #1055's edit mode will reuse. Plan sections 1, 2,
+5, files table, risks, and test plan updated + recommitted. Gate still pending.

From 04458ccf6f6f09ad1b67aee4a76ac6d98e0f3ca9 Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Tue, 30 Jun 2026 09:52:15 +1000
Subject: [PATCH 06/23] chore(porch): 1107 plan-approval gate-approved

---
 .../projects/1107-vscode-replace-top-of-window-q/status.yaml | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/codev/projects/1107-vscode-replace-top-of-window-q/status.yaml b/codev/projects/1107-vscode-replace-top-of-window-q/status.yaml
index 7583e42c0..f94f51e36 100644
--- a/codev/projects/1107-vscode-replace-top-of-window-q/status.yaml
+++ b/codev/projects/1107-vscode-replace-top-of-window-q/status.yaml
@@ -6,8 +6,9 @@ plan_phases: []
 current_plan_phase: null
 gates:
   plan-approval:
-    status: pending
+    status: approved
     requested_at: '2026-06-29T23:29:21.703Z'
+    approved_at: '2026-06-29T23:52:15.206Z'
   dev-approval:
     status: pending
   pr:
@@ -16,4 +17,4 @@ iteration: 1
 build_complete: false
 history: []
 started_at: '2026-06-29T23:23:50.850Z'
-updated_at: '2026-06-29T23:29:21.704Z'
+updated_at: '2026-06-29T23:52:15.207Z'

From 4ec07ef6d07fc3eb88f9d88480ba1e98289e2b43 Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Tue, 30 Jun 2026 09:52:23 +1000
Subject: [PATCH 07/23] chore(porch): 1107 implement phase-transition

---
 .../projects/1107-vscode-replace-top-of-window-q/status.yaml  | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/codev/projects/1107-vscode-replace-top-of-window-q/status.yaml b/codev/projects/1107-vscode-replace-top-of-window-q/status.yaml
index f94f51e36..350a39a9c 100644
--- a/codev/projects/1107-vscode-replace-top-of-window-q/status.yaml
+++ b/codev/projects/1107-vscode-replace-top-of-window-q/status.yaml
@@ -1,7 +1,7 @@
 id: '1107'
 title: vscode-replace-top-of-window-q
 protocol: pir
-phase: plan
+phase: implement
 plan_phases: []
 current_plan_phase: null
 gates:
@@ -17,4 +17,4 @@ iteration: 1
 build_complete: false
 history: []
 started_at: '2026-06-29T23:23:50.850Z'
-updated_at: '2026-06-29T23:52:15.207Z'
+updated_at: '2026-06-29T23:52:23.651Z'

From 87a6788d9902f8ca42276c99127c9face0982e79 Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Tue, 30 Jun 2026 10:01:12 +1000
Subject: [PATCH 08/23] [PIR #1107] artifact-canvas: inline comment composer;
 widen onAddComment seam to (line, text)

---
 packages/artifact-canvas/examples/main.tsx    |  8 +-
 .../src/__tests__/end-to-end.test.tsx         | 34 ++++---
 .../src/components/ArtifactCanvas.tsx         | 86 ++++++++++++++++-
 .../__tests__/artifact-canvas.test.tsx        | 95 +++++++++++++++++--
 .../src/overlays/CommentComposer.tsx          | 94 ++++++++++++++++++
 .../__tests__/comment-composer.test.tsx       | 83 ++++++++++++++++
 .../src/styles/default-theme.css              | 58 +++++++++++
 packages/artifact-canvas/src/types.ts         | 12 ++-
 8 files changed, 434 insertions(+), 36 deletions(-)
 create mode 100644 packages/artifact-canvas/src/overlays/CommentComposer.tsx
 create mode 100644 packages/artifact-canvas/src/overlays/__tests__/comment-composer.test.tsx

diff --git a/packages/artifact-canvas/examples/main.tsx b/packages/artifact-canvas/examples/main.tsx
index d9fbc8ce8..c1f31fcad 100644
--- a/packages/artifact-canvas/examples/main.tsx
+++ b/packages/artifact-canvas/examples/main.tsx
@@ -17,10 +17,10 @@ import '../src/styles/default-theme.css';
 const host = createStubHost(SAMPLE_ARTIFACT);
 
 function Example(): React.ReactElement {
-  const onAddComment = (line: number) => {
-    // Host glue (spec D6): the package emits intent; the host collects input + writes back.
-    const text = window.prompt(`Comment on line ${line + 1}:`);
-    if (text) void host.markerAdapter.add('artifact://sample.md', line, text, 'you');
+  const onAddComment = (line: number, text: string) => {
+    // Host glue (spec D6): the canvas's inline composer (#1107) collects the body and passes it
+    // here; the host just writes it back. (Pre-#1107 this used window.prompt for the input.)
+    void host.markerAdapter.add('artifact://sample.md', line, text, 'you');
   };
   return React.createElement(
     'div',
diff --git a/packages/artifact-canvas/src/__tests__/end-to-end.test.tsx b/packages/artifact-canvas/src/__tests__/end-to-end.test.tsx
index e25d668a7..3b364a7fc 100644
--- a/packages/artifact-canvas/src/__tests__/end-to-end.test.tsx
+++ b/packages/artifact-canvas/src/__tests__/end-to-end.test.tsx
@@ -6,7 +6,8 @@
  * via BOTH mouse and keyboard:
  *
  *   render → existing marker shows → hover/focus a block → click/Enter the `+` →
- *   onAddComment(line) fires (0-based, spec D5) → host glue calls MarkerAdapter.add →
+ *   the inline composer opens (#1107) → type a body → Cmd/Ctrl+Enter →
+ *   onAddComment(line, text) fires (0-based, spec D5) → host glue calls MarkerAdapter.add →
  *   the marker is serialized INTO the text → FileAdapter.watch replays the new text →
  *   MarkerAdapter.list re-derives from that text → the new marker renders.
  *
@@ -22,11 +23,11 @@ import { createStubHost } from './fixtures/stub-adapters.js';
 
 afterEach(cleanup);
 
-/** Host glue (spec D6): the package emits intent; the host performs input + write-back. */
-function mountWithHost(initial: string, author = 'reviewer', body = 'please clarify') {
+/** Host glue (spec D6): the canvas's composer collects the body; the host writes it back. */
+function mountWithHost(initial: string, author = 'reviewer') {
   const host = createStubHost(initial);
-  const onAddComment = vi.fn((line: number) => {
-    void host.markerAdapter.add('artifact://sample.md', line, body, author);
+  const onAddComment = vi.fn((line: number, text: string) => {
+    void host.markerAdapter.add('artifact://sample.md', line, text, author);
   });
   render(
     <ArtifactCanvas
@@ -48,6 +49,13 @@ async function firstParagraph(): Promise<HTMLElement> {
   });
 }
 
+/** Type `body` into the inline composer (#1107) and submit it with Cmd/Ctrl+Enter. */
+async function composeAndSubmit(body: string): Promise<void> {
+  const input = await screen.findByRole('textbox', { name: /add comment on line/i });
+  fireEvent.change(input, { target: { value: body } });
+  fireEvent.keyDown(input, { key: 'Enter', metaKey: true });
+}
+
 describe('ArtifactCanvas end-to-end (Phase 4 contract proof)', () => {
   it('renders the sample artifact and its pre-existing marker', async () => {
     mountWithHost(SAMPLE_ARTIFACT);
@@ -57,16 +65,17 @@ describe('ArtifactCanvas end-to-end (Phase 4 contract proof)', () => {
     await waitFor(() => expect(document.querySelector('.codev-canvas-has-marker')).not.toBeNull());
   });
 
-  it('MOUSE: hover → click "+" → round-trips a new marker THROUGH TEXT', async () => {
-    const { host, onAddComment } = mountWithHost(SAMPLE_ARTIFACT, 'alice', 'tighten this');
+  it('MOUSE: hover → click "+" → compose → submit → round-trips a new marker THROUGH TEXT', async () => {
+    const { host, onAddComment } = mountWithHost(SAMPLE_ARTIFACT, 'alice');
     const p = await firstParagraph();
     const line = Number(p.getAttribute('data-line'));
 
     fireEvent.mouseOver(p);
     fireEvent.click(await screen.findByRole('button', { name: /add comment on line/i }));
+    await composeAndSubmit('tighten this');
 
-    // Intent fired with the 0-based line; the package never wrote the marker itself (D6).
-    expect(onAddComment).toHaveBeenCalledWith(line);
+    // Intent fired with the 0-based line + composed text; the package never wrote the marker (D6).
+    expect(onAddComment).toHaveBeenCalledWith(line, 'tighten this');
 
     // The host's add serialized the marker INTO the text store (proves round-trip through text).
     await waitFor(() =>
@@ -82,15 +91,16 @@ describe('ArtifactCanvas end-to-end (Phase 4 contract proof)', () => {
     });
   });
 
-  it('KEYBOARD: focus → Enter → round-trips a new marker THROUGH TEXT', async () => {
-    const { host, onAddComment } = mountWithHost(SAMPLE_ARTIFACT, 'bob', 'needs a test');
+  it('KEYBOARD: focus → Enter → compose → submit → round-trips a new marker THROUGH TEXT', async () => {
+    const { host, onAddComment } = mountWithHost(SAMPLE_ARTIFACT, 'bob');
     const p = await firstParagraph();
     const line = Number(p.getAttribute('data-line'));
 
     expect(p.tabIndex).toBe(0); // keyboard-reachable (accessibility AC)
     fireEvent.keyDown(p, { key: 'Enter' });
+    await composeAndSubmit('needs a test');
 
-    expect(onAddComment).toHaveBeenCalledWith(line);
+    expect(onAddComment).toHaveBeenCalledWith(line, 'needs a test');
     await waitFor(() =>
       expect(host.store.getText()).toContain('<!-- REVIEW(@bob): needs a test -->'),
     );
diff --git a/packages/artifact-canvas/src/components/ArtifactCanvas.tsx b/packages/artifact-canvas/src/components/ArtifactCanvas.tsx
index 270b61532..e7f4ef102 100644
--- a/packages/artifact-canvas/src/components/ArtifactCanvas.tsx
+++ b/packages/artifact-canvas/src/components/ArtifactCanvas.tsx
@@ -1,7 +1,9 @@
 import * as React from 'react';
+import { createPortal } from 'react-dom';
 import type { ArtifactCanvasProps, ReviewMarker } from '../types.js';
 import { renderMarkdown } from '../renderer/renderer.js';
 import { CommentAffordance } from '../overlays/CommentAffordance.js';
+import { CommentComposer } from '../overlays/CommentComposer.js';
 import { MarkerMinimap } from '../overlays/MarkerMinimap.js';
 
 /**
@@ -60,6 +62,10 @@ export function ArtifactCanvas(props: ArtifactCanvasProps): React.ReactElement {
   const [activeLine, setActiveLine] = React.useState<number | null>(null);
   // Vertical offset (px, relative to the canvas) of the active block, so the overlay anchors to it.
   const [overlayTop, setOverlayTop] = React.useState(0);
+  // The line currently being commented on (the inline composer is open for it), and the in-flow
+  // placeholder node the composer portals into — injected directly below that block (#1107).
+  const [composingLine, setComposingLine] = React.useState<number | null>(null);
+  const [composerHost, setComposerHost] = React.useState<HTMLElement | null>(null);
   const bodyRef = React.useRef<HTMLDivElement>(null);
 
   const report = React.useCallback(
@@ -215,6 +221,62 @@ export function ArtifactCanvas(props: ArtifactCanvasProps): React.ReactElement {
     );
   }, [html, markers]);
 
+  // Manage the in-flow composer placeholder (#1107). When `composingLine` is set, inject a
+  // placeholder `<div>` directly below that block — AFTER its marker-card stack if present, so the
+  // composer reads as the in-progress sibling of the existing comments — and hand the node to the
+  // portal below. Declared AFTER the marker-card decoration effect so the card stack already exists
+  // when we pick the insertion anchor. Idempotent: if a correctly-placed host already exists for
+  // this line we leave it (prevents a setState→re-run loop); an `html` change wipes the body, so the
+  // node disconnects and we re-create it. If the target block vanished on reload, close the composer.
+  React.useEffect(() => {
+    const root = bodyRef.current;
+    if (!root) { return; }
+
+    if (composingLine === null) {
+      if (composerHost) { composerHost.remove(); setComposerHost(null); }
+      return;
+    }
+    const block = root.querySelector(`[data-line="${composingLine}"]`);
+    if (!block) {
+      if (composerHost) { composerHost.remove(); }
+      setComposerHost(null);
+      setComposingLine(null);
+      return;
+    }
+    // Anchor below the block's marker-card stack when it has one, else directly below the block.
+    let anchor: Element = block;
+    const sib = block.nextElementSibling;
+    if (sib?.classList.contains('codev-canvas-marker-cards')) { anchor = sib; }
+
+    if (composerHost?.isConnected && composerHost.previousElementSibling === anchor) {
+      return; // already placed correctly — nothing to do (avoids an infinite re-run)
+    }
+    composerHost?.remove();
+    const host = document.createElement('div');
+    host.className = 'codev-canvas-comment-composer-host';
+    anchor.after(host);
+    setComposerHost(host);
+  }, [composingLine, html, markers, composerHost]);
+
+  // Comment-intent seam (#1107): clicking "+" / pressing Enter opens the inline composer for the
+  // line; submitting emits `onAddComment(line, text)` (the host writes the marker); cancel/Esc just
+  // closes it and restores focus to the block so keyboard users aren't stranded.
+  const openComposer = (line: number): void => setComposingLine(line);
+  const submitComposer = (text: string): void => {
+    if (composingLine === null) { return; }
+    onAddComment(composingLine, text);
+    setComposingLine(null);
+  };
+  const cancelComposer = (): void => {
+    const line = composingLine;
+    setComposingLine(null);
+    if (line !== null) {
+      // The block element persists across this state change (the body is not rebuilt), so focus it
+      // synchronously to return the reviewer to where they were.
+      bodyRef.current?.querySelector<HTMLElement>(`[data-line="${line}"]`)?.focus();
+    }
+  };
+
   const lineFromEvent = (target: EventTarget | null): number | null => {
     const el = (target as HTMLElement | null)?.closest?.('[data-line]') as HTMLElement | null;
     if (!el) return null;
@@ -256,21 +318,35 @@ export function ArtifactCanvas(props: ArtifactCanvasProps): React.ReactElement {
           const l = lineFromEvent(e.target);
           if (l !== null) {
             e.preventDefault();
-            onAddComment(l); // intent only (D6)
+            openComposer(l); // open the inline composer for this block (#1107)
           }
         }
       },
       // No `dangerouslySetInnerHTML`: the body's content is set imperatively in the effect above so
       // React never re-commits it (which would wipe the injected cards). Rendered with no children.
     }),
-    // The overlay now carries ONLY the "+" add-comment affordance. Existing markers render as
+    // The overlay carries ONLY the "+" add-comment affordance. Existing markers render as
     // always-visible inline cards below their block (injected above), not in this hover overlay —
-    // that's the layout fix that stopped the cards overlapping the block content (#863).
-    activeLine !== null
+    // that's the layout fix that stopped the cards overlapping the block content (#863). The "+"
+    // is suppressed for the line whose composer is open (the composer is shown there instead).
+    activeLine !== null && activeLine !== composingLine
       ? React.createElement(
           'div',
           { className: 'codev-canvas-overlay', style: { top: overlayTop } },
-          React.createElement(CommentAffordance, { line: activeLine, onActivate: onAddComment }),
+          React.createElement(CommentAffordance, { line: activeLine, onActivate: openComposer }),
+        )
+      : null,
+    // Inline composer (#1107): portalled into the in-flow placeholder injected directly below the
+    // block, so the reviewer types where the comment will live. Keeping it React-owned (rather than
+    // hand-built DOM in the imperatively-managed body) gives clean state / focus / Esc handling.
+    composingLine !== null && composerHost
+      ? createPortal(
+          React.createElement(CommentComposer, {
+            line: composingLine,
+            onSubmit: submitComposer,
+            onCancel: cancelComposer,
+          }),
+          composerHost,
         )
       : null,
     React.createElement(MarkerMinimap, { markers, bodyRef }),
diff --git a/packages/artifact-canvas/src/components/__tests__/artifact-canvas.test.tsx b/packages/artifact-canvas/src/components/__tests__/artifact-canvas.test.tsx
index 6ebfc453a..54d9d57d4 100644
--- a/packages/artifact-canvas/src/components/__tests__/artifact-canvas.test.tsx
+++ b/packages/artifact-canvas/src/components/__tests__/artifact-canvas.test.tsx
@@ -57,7 +57,7 @@ describe('ArtifactCanvas (Phase 3)', () => {
     expect(host.markerAdapter.list).toHaveBeenCalled();
   });
 
-  it('hover shows the "+" affordance; clicking emits onAddComment with the 0-based line (scenario 2)', async () => {
+  it('hover shows the "+" affordance; clicking opens the inline composer below the block (#1107)', async () => {
     const host = makeHost('# Title\n\nA paragraph.');
     const onAddComment = vi.fn();
     render(<ArtifactCanvas uri="x" {...host} onAddComment={onAddComment} />);
@@ -69,12 +69,37 @@ describe('ArtifactCanvas (Phase 3)', () => {
     fireEvent.mouseOver(p);
     const plus = await screen.findByRole('button', { name: /add comment on line/i });
     fireEvent.click(plus);
-    expect(onAddComment).toHaveBeenCalledWith(Number(p.getAttribute('data-line')));
+    // Clicking "+" no longer emits intent directly (#1107) — it opens the composer in-flow below
+    // the block, where the comment will live.
+    const composer = await screen.findByRole('textbox', { name: /add comment on line/i });
+    const host_el = composer.closest('.codev-canvas-comment-composer-host');
+    expect(host_el).not.toBeNull();
+    expect(p.nextElementSibling).toBe(host_el); // placed directly below the block
+    expect(onAddComment).not.toHaveBeenCalled();
     // The package must NOT write the marker itself (D6 intent-only / invariant scenario 6).
     expect(host.markerAdapter.add).not.toHaveBeenCalled();
   });
 
-  it('is keyboard-activatable: Enter on a focused block emits onAddComment (accessibility AC)', async () => {
+  it('composer submit (Cmd/Ctrl+Enter) emits onAddComment(line, text) (#1107)', async () => {
+    const host = makeHost('# Title\n\nA paragraph.');
+    const onAddComment = vi.fn();
+    render(<ArtifactCanvas uri="x" {...host} onAddComment={onAddComment} />);
+    const p = await waitFor(() => {
+      const el = document.querySelector('p[data-line]');
+      if (!el) throw new Error('no paragraph yet');
+      return el as HTMLElement;
+    });
+    const line = Number(p.getAttribute('data-line'));
+    fireEvent.mouseOver(p);
+    fireEvent.click(await screen.findByRole('button', { name: /add comment on line/i }));
+    const composer = await screen.findByRole('textbox', { name: /add comment on line/i });
+    fireEvent.change(composer, { target: { value: 'please clarify' } });
+    fireEvent.keyDown(composer, { key: 'Enter', metaKey: true });
+    expect(onAddComment).toHaveBeenCalledWith(line, 'please clarify');
+    expect(host.markerAdapter.add).not.toHaveBeenCalled(); // host writes; package never does (D6)
+  });
+
+  it('is keyboard-activatable: Enter on a focused block opens the composer (accessibility AC)', async () => {
     const host = makeHost('A paragraph.');
     const onAddComment = vi.fn();
     render(<ArtifactCanvas uri="x" {...host} onAddComment={onAddComment} />);
@@ -85,14 +110,16 @@ describe('ArtifactCanvas (Phase 3)', () => {
     });
     expect(p.tabIndex).toBe(0); // focusable
     fireEvent.keyDown(p, { key: 'Enter' });
-    expect(onAddComment).toHaveBeenCalledWith(0);
+    const composer = await screen.findByRole('textbox', { name: /add comment on line/i });
+    expect(composer).not.toBeNull();
+    expect(onAddComment).not.toHaveBeenCalled(); // opens composer, doesn't emit yet
   });
 
-  it('round-trips a marker through text: host add → watch → re-list → marker renders (scenario 3)', async () => {
+  it('round-trips a marker through text: composer submit → host add → watch → re-list → renders (scenario 3)', async () => {
     const host = makeHost('A paragraph.'); // line 0, no markers
-    const onAddComment = vi.fn((line: number) => {
-      // Host glue: collect text + write back via MarkerAdapter.add (which serializes into the file text).
-      void host.markerAdapter.add('x', line, 'please clarify', 'reviewer');
+    const onAddComment = vi.fn((line: number, text: string) => {
+      // Host glue: write back via MarkerAdapter.add (which serializes into the file text).
+      void host.markerAdapter.add('x', line, text, 'reviewer');
     });
     render(<ArtifactCanvas uri="x" {...host} onAddComment={onAddComment} />);
     const p = await waitFor(() => {
@@ -102,10 +129,57 @@ describe('ArtifactCanvas (Phase 3)', () => {
     });
     fireEvent.mouseOver(p);
     fireEvent.click(await screen.findByRole('button', { name: /add comment on line/i }));
+    const composer = await screen.findByRole('textbox', { name: /add comment on line/i });
+    fireEvent.change(composer, { target: { value: 'please clarify' } });
+    fireEvent.keyDown(composer, { key: 'Enter', ctrlKey: true });
     expect(host.markerAdapter.add).toHaveBeenCalled();
     // After the host writes + the watcher fires, the component re-lists and renders the marker.
     await waitFor(() => expect(document.querySelector('.codev-canvas-has-marker')).not.toBeNull());
     expect(host.text()).toContain('<!-- REVIEW(@reviewer): please clarify -->'); // proves text round-trip
+    // The composer closes after submit.
+    expect(document.querySelector('.codev-canvas-comment-composer')).toBeNull();
+  });
+
+  it('Esc / Cancel closes the composer without emitting (#1107)', async () => {
+    const host = makeHost('A paragraph.');
+    const onAddComment = vi.fn();
+    render(<ArtifactCanvas uri="x" {...host} onAddComment={onAddComment} />);
+    const p = await waitFor(() => {
+      const el = document.querySelector('p[data-line]');
+      if (!el) throw new Error('no paragraph yet');
+      return el as HTMLElement;
+    });
+    fireEvent.mouseOver(p);
+    fireEvent.click(await screen.findByRole('button', { name: /add comment on line/i }));
+    const composer = await screen.findByRole('textbox', { name: /add comment on line/i });
+    fireEvent.keyDown(composer, { key: 'Escape' });
+    await waitFor(() =>
+      expect(document.querySelector('.codev-canvas-comment-composer')).toBeNull(),
+    );
+    expect(onAddComment).not.toHaveBeenCalled();
+    // The placeholder host is cleaned up too (no orphan node left in the body).
+    expect(document.querySelector('.codev-canvas-comment-composer-host')).toBeNull();
+  });
+
+  it('a reload that removes the active block closes the composer (#1107)', async () => {
+    const host = makeHost('first para\n\nsecond para');
+    const onAddComment = vi.fn();
+    render(<ArtifactCanvas uri="x" {...host} onAddComment={onAddComment} />);
+    // Open the composer on the LAST paragraph, then shrink the document so that line is gone.
+    const paras = await waitFor(() => {
+      const els = document.querySelectorAll('p[data-line]');
+      if (els.length < 2) throw new Error('paragraphs not rendered yet');
+      return els;
+    });
+    const last = paras[paras.length - 1] as HTMLElement;
+    fireEvent.mouseOver(last);
+    fireEvent.click(await screen.findByRole('button', { name: /add comment on line/i }));
+    expect(await screen.findByRole('textbox', { name: /add comment on line/i })).not.toBeNull();
+    // A watch reload to a shorter document removes the block the composer was anchored to.
+    await act(async () => { host.watchers.forEach((cb) => cb('only one para now')); });
+    await waitFor(() =>
+      expect(document.querySelector('.codev-canvas-comment-composer')).toBeNull(),
+    );
   });
 
   it('drops an out-of-range marker and warns ONCE even across reloads (deferred #4)', async () => {
@@ -256,7 +330,7 @@ describe('ArtifactCanvas (Phase 3)', () => {
     expect(cards.querySelector('img')).toBeNull();
   });
 
-  it('activates on Space (not just Enter) on a focused block', async () => {
+  it('activates on Space (not just Enter) on a focused block — opens the composer (#1107)', async () => {
     const host = makeHost('A paragraph.');
     const onAddComment = vi.fn();
     render(<ArtifactCanvas uri="x" {...host} onAddComment={onAddComment} />);
@@ -266,7 +340,8 @@ describe('ArtifactCanvas (Phase 3)', () => {
       return el as HTMLElement;
     });
     fireEvent.keyDown(p, { key: ' ' });
-    expect(onAddComment).toHaveBeenCalledWith(0);
+    expect(await screen.findByRole('textbox', { name: /add comment on line/i })).not.toBeNull();
+    expect(onAddComment).not.toHaveBeenCalled(); // opens composer; emit happens on submit
   });
 
   it('keeps previously-rendered markers when a LATER list() rejects (D2 — prior markers preserved)', async () => {
diff --git a/packages/artifact-canvas/src/overlays/CommentComposer.tsx b/packages/artifact-canvas/src/overlays/CommentComposer.tsx
new file mode 100644
index 000000000..a9148f972
--- /dev/null
+++ b/packages/artifact-canvas/src/overlays/CommentComposer.tsx
@@ -0,0 +1,94 @@
+import * as React from 'react';
+
+export interface CommentComposerProps {
+  /** 0-based source line this composer targets (for the accessible label). */
+  line: number;
+  /** Invoked with the trimmed, non-empty body when the reviewer submits. */
+  onSubmit: (text: string) => void;
+  /** Invoked when the reviewer cancels (Esc / Cancel button) without submitting. */
+  onCancel: () => void;
+}
+
+/**
+ * Inline comment composer (#1107). Replaces the old center-top `showInputBox` Quick Pick: it is
+ * rendered in-flow directly below the block being commented on (the host portals it into a
+ * placeholder there), so the reviewer types the comment exactly where it will live — the visual
+ * anchor is preserved end-to-end.
+ *
+ * Keystrokes (the UX confirmed at the PIR dev-approval gate):
+ *  - **Cmd/Ctrl+Enter** submits (matches the GitHub review-composer convention).
+ *  - **Enter** inserts a newline — the body is multi-line-natural (a `<textarea>`, not a one-line
+ *    input). Newlines collapse to a single space only at write time (`serializeReviewMarker`), so
+ *    the on-disk single-line marker format is unchanged.
+ *  - **Esc** cancels.
+ *
+ * It only signals intent via `onSubmit` / `onCancel`; it never writes a marker itself (the host
+ * does that, preserving the package's D6 invariant). An empty / whitespace-only body is a no-op.
+ */
+export function CommentComposer({ line, onSubmit, onCancel }: CommentComposerProps): React.ReactElement {
+  const [text, setText] = React.useState('');
+  const textareaRef = React.useRef<HTMLTextAreaElement>(null);
+
+  // Autofocus on mount so the reviewer can type immediately after clicking "+".
+  React.useEffect(() => {
+    textareaRef.current?.focus();
+  }, []);
+
+  const submit = (): void => {
+    const body = text.trim();
+    if (!body) { return; } // mirrors the host's old `if (!text) return;` guard
+    onSubmit(body);
+  };
+
+  const onKeyDown = (e: React.KeyboardEvent<HTMLTextAreaElement>): void => {
+    if (e.key === 'Enter' && (e.metaKey || e.ctrlKey)) {
+      e.preventDefault();
+      submit();
+    } else if (e.key === 'Escape') {
+      e.preventDefault();
+      onCancel();
+    }
+    // Plain Enter falls through to the textarea's default (insert a newline).
+  };
+
+  const empty = text.trim().length === 0;
+
+  return React.createElement(
+    'div',
+    { className: 'codev-canvas-comment-composer' },
+    React.createElement('textarea', {
+      ref: textareaRef,
+      className: 'codev-canvas-comment-composer-input',
+      // Human-facing line numbers are 1-based; the data model stays 0-based (spec D5).
+      'aria-label': `Add comment on line ${line + 1}`,
+      placeholder: 'Add a review comment… (⌘/Ctrl+Enter to submit, Esc to cancel)',
+      rows: 3,
+      value: text,
+      onChange: (e: React.ChangeEvent<HTMLTextAreaElement>) => setText(e.target.value),
+      onKeyDown,
+    }),
+    React.createElement(
+      'div',
+      { className: 'codev-canvas-comment-composer-actions' },
+      React.createElement(
+        'button',
+        {
+          type: 'button',
+          className: 'codev-canvas-comment-composer-cancel',
+          onClick: onCancel,
+        },
+        'Cancel',
+      ),
+      React.createElement(
+        'button',
+        {
+          type: 'button',
+          className: 'codev-canvas-comment-composer-submit',
+          onClick: submit,
+          disabled: empty,
+        },
+        'Comment',
+      ),
+    ),
+  );
+}
diff --git a/packages/artifact-canvas/src/overlays/__tests__/comment-composer.test.tsx b/packages/artifact-canvas/src/overlays/__tests__/comment-composer.test.tsx
new file mode 100644
index 000000000..3f84ff6cf
--- /dev/null
+++ b/packages/artifact-canvas/src/overlays/__tests__/comment-composer.test.tsx
@@ -0,0 +1,83 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { render, screen, fireEvent, cleanup } from '@testing-library/react';
+import * as React from 'react';
+import { CommentComposer } from '../CommentComposer.js';
+
+afterEach(cleanup);
+
+/**
+ * Unit tests for the inline comment composer (#1107). Verifies the keystroke contract confirmed at
+ * the PIR dev-approval gate: Cmd/Ctrl+Enter submits, plain Enter is a newline (not submit), Esc
+ * cancels, empty bodies are no-ops, and the buttons mirror those two actions.
+ */
+function setup(line = 0) {
+  const onSubmit = vi.fn();
+  const onCancel = vi.fn();
+  render(React.createElement(CommentComposer, { line, onSubmit, onCancel }));
+  const input = screen.getByRole('textbox', { name: /add comment on line/i }) as HTMLTextAreaElement;
+  return { onSubmit, onCancel, input };
+}
+
+describe('CommentComposer (#1107)', () => {
+  it('autofocuses the textarea on mount', () => {
+    const { input } = setup();
+    expect(document.activeElement).toBe(input);
+  });
+
+  it('labels the textarea with the 1-based line number', () => {
+    setup(4); // 0-based 4 → "line 5"
+    expect(screen.getByRole('textbox', { name: /add comment on line 5/i })).not.toBeNull();
+  });
+
+  it('Cmd+Enter submits the trimmed body', () => {
+    const { onSubmit, input } = setup();
+    fireEvent.change(input, { target: { value: '  please clarify  ' } });
+    fireEvent.keyDown(input, { key: 'Enter', metaKey: true });
+    expect(onSubmit).toHaveBeenCalledWith('please clarify');
+  });
+
+  it('Ctrl+Enter submits (non-mac)', () => {
+    const { onSubmit, input } = setup();
+    fireEvent.change(input, { target: { value: 'looks good' } });
+    fireEvent.keyDown(input, { key: 'Enter', ctrlKey: true });
+    expect(onSubmit).toHaveBeenCalledWith('looks good');
+  });
+
+  it('plain Enter does NOT submit (newline in the textarea)', () => {
+    const { onSubmit, input } = setup();
+    fireEvent.change(input, { target: { value: 'line one' } });
+    fireEvent.keyDown(input, { key: 'Enter' });
+    expect(onSubmit).not.toHaveBeenCalled();
+  });
+
+  it('Esc cancels without submitting', () => {
+    const { onSubmit, onCancel, input } = setup();
+    fireEvent.change(input, { target: { value: 'discard me' } });
+    fireEvent.keyDown(input, { key: 'Escape' });
+    expect(onCancel).toHaveBeenCalled();
+    expect(onSubmit).not.toHaveBeenCalled();
+  });
+
+  it('empty / whitespace-only submit is a no-op', () => {
+    const { onSubmit, input } = setup();
+    fireEvent.change(input, { target: { value: '   ' } });
+    fireEvent.keyDown(input, { key: 'Enter', metaKey: true });
+    expect(onSubmit).not.toHaveBeenCalled();
+  });
+
+  it('Comment button submits; it is disabled while the body is empty', () => {
+    const { onSubmit, input } = setup();
+    const submit = screen.getByRole('button', { name: /^comment$/i }) as HTMLButtonElement;
+    expect(submit.disabled).toBe(true);
+    fireEvent.change(input, { target: { value: 'ship it' } });
+    expect(submit.disabled).toBe(false);
+    fireEvent.click(submit);
+    expect(onSubmit).toHaveBeenCalledWith('ship it');
+  });
+
+  it('Cancel button cancels', () => {
+    const { onCancel } = setup();
+    fireEvent.click(screen.getByRole('button', { name: /cancel/i }));
+    expect(onCancel).toHaveBeenCalled();
+  });
+});
diff --git a/packages/artifact-canvas/src/styles/default-theme.css b/packages/artifact-canvas/src/styles/default-theme.css
index 54d5d189f..7f7d7956b 100644
--- a/packages/artifact-canvas/src/styles/default-theme.css
+++ b/packages/artifact-canvas/src/styles/default-theme.css
@@ -284,6 +284,64 @@
 .codev-canvas-marker-card-icon { margin-right: 4px; }
 .codev-canvas-marker-card-author { font-weight: 600; color: var(--codev-canvas-muted); margin-right: 4px; }
 
+/* Inline comment composer (#1107): rendered in-flow directly below the block (the host portals it
+   into `.codev-canvas-comment-composer-host`), mirroring the marker-card stack's left rule + spacing
+   so the open composer reads as the in-progress sibling of the comments it will become. The host is
+   a layout-only wrapper; all chrome lives on `.codev-canvas-comment-composer`. */
+.codev-canvas-comment-composer-host { display: block; }
+.codev-canvas-comment-composer {
+  margin: 4px 0 10px;
+  padding-left: 8px;
+  border-left: 2px solid var(--codev-canvas-comment-marker);
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+.codev-canvas-comment-composer-input {
+  width: 100%;
+  box-sizing: border-box;
+  resize: vertical;
+  font: inherit;
+  color: var(--codev-canvas-foreground);
+  background: var(--codev-canvas-background);
+  border: 1px solid var(--codev-canvas-border);
+  border-radius: 4px;
+  padding: 6px 8px;
+}
+.codev-canvas-comment-composer-input:focus-visible {
+  outline: 2px solid var(--codev-canvas-accent);
+  outline-offset: 1px;
+}
+.codev-canvas-comment-composer-actions {
+  display: flex;
+  justify-content: flex-end;
+  gap: 8px;
+}
+.codev-canvas-comment-composer-actions button {
+  font: inherit;
+  cursor: pointer;
+  border-radius: 4px;
+  border: 1px solid var(--codev-canvas-border);
+  padding: 3px 12px;
+}
+.codev-canvas-comment-composer-cancel {
+  background: var(--codev-canvas-background);
+  color: var(--codev-canvas-foreground);
+}
+.codev-canvas-comment-composer-submit {
+  background: var(--codev-canvas-accent);
+  color: var(--codev-canvas-background);
+  border-color: var(--codev-canvas-accent);
+}
+.codev-canvas-comment-composer-submit:disabled {
+  opacity: 0.5;
+  cursor: default;
+}
+.codev-canvas-comment-composer-actions button:focus-visible {
+  outline: 2px solid var(--codev-canvas-accent);
+  outline-offset: 1px;
+}
+
 /* Right-edge marker minimap (#863): a fixed, narrow column of dots — one per REVIEW marker,
    positioned proportional to the marker's place in the document. The column itself is
    click-transparent (pointer-events: none) so only the dots are interactive, and it is narrow
diff --git a/packages/artifact-canvas/src/types.ts b/packages/artifact-canvas/src/types.ts
index 3cffe3efc..9f9ecbffd 100644
--- a/packages/artifact-canvas/src/types.ts
+++ b/packages/artifact-canvas/src/types.ts
@@ -46,9 +46,11 @@ export interface ReviewMarker {
 /**
  * Public props of the React canvas component — the host-facing contract.
  *
- * `onAddComment` is the single canonical comment-intent seam (spec D6): the overlay calls it
- * with a 0-based line; the host performs the text input and calls its own
- * `MarkerAdapter.add(...)`. The package never calls `add` itself.
+ * `onAddComment` is the single canonical comment-intent seam (spec D6): the canvas collects the
+ * body via its inline composer (#1107) and calls this with the 0-based line **and** the trimmed
+ * text; the host writes the marker via its own `MarkerAdapter.add(...)`. The package never calls
+ * `add` itself. (Contract amendment #1107: the seam gained the `text` argument when the text input
+ * moved from the host's `showInputBox` into the canvas's inline composer.)
  */
 export interface ArtifactCanvasProps {
   /** Host-opaque document identifier; the package never interprets it as a filesystem path. */
@@ -56,8 +58,8 @@ export interface ArtifactCanvasProps {
   fileAdapter: FileAdapter;
   markerAdapter: MarkerAdapter;
   themeAdapter: ThemeAdapter;
-  /** Comment-intent event (spec D6); `line` is 0-based (spec D5). */
-  onAddComment(line: number): void;
+  /** Comment-intent event (spec D6); `line` is 0-based (spec D5), `text` is the trimmed body (#1107). */
+  onAddComment(line: number, text: string): void;
   /** Optional host error sink; the package never throws out of an event handler (spec D2). */
   onError?(err: unknown): void;
   /**

From 1f5e0614e6df5ff46ea28f4286337d8344d2bd8d Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Tue, 30 Jun 2026 10:01:17 +1000
Subject: [PATCH 09/23] [PIR #1107] vscode preview: drop showInputBox; write
 marker from composer-collected text

---
 .../src/markdown-preview/preview-provider.ts  | 29 ++++++++++---------
 .../src/markdown-preview/webview/main.ts      | 10 ++++---
 2 files changed, 21 insertions(+), 18 deletions(-)

diff --git a/packages/vscode/src/markdown-preview/preview-provider.ts b/packages/vscode/src/markdown-preview/preview-provider.ts
index 2e0e71c36..996110666 100644
--- a/packages/vscode/src/markdown-preview/preview-provider.ts
+++ b/packages/vscode/src/markdown-preview/preview-provider.ts
@@ -15,10 +15,11 @@
  *   `parseReviewMarkers`. Both come from `@cluesmith/codev-core/review-markers`,
  *   so this surface and the editor Comments-API path write/parse identical bytes.
  * - Content + markers are pushed into the webview, which mounts `<ArtifactCanvas>`
- *   (see `webview/main.ts`). The canvas emits an `addComment` intent; the host
- *   collects the text via `showInputBox` and writes the marker with a
- *   `WorkspaceEdit`. The document change re-pushes — the round-trip goes through
- *   the file text, matching the package's design.
+ *   (see `webview/main.ts`). The canvas's inline composer (#1107) collects the
+ *   comment body and emits an `addComment` intent carrying `{ line, text }`; the
+ *   host writes the marker with a `WorkspaceEdit`. The document change re-pushes —
+ *   the round-trip goes through the file text, matching the package's design.
+ *   (Pre-#1107 the host collected the body via a center-top `showInputBox`.)
  *
  * Registered with `priority: "option"` so it never replaces the default `.md`
  * editor or the built-in preview; it is opt-in via "Reopen With…" or the
@@ -81,21 +82,21 @@ export class MarkdownPreviewProvider implements vscode.CustomTextEditorProvider
 
     panel.webview.onDidReceiveMessage((msg: unknown) => {
       if (!msg || typeof msg !== 'object') { return; }
-      const m = msg as { type?: string; line?: number };
+      const m = msg as { type?: string; line?: number; text?: string };
       if (m.type === 'ready') { pushUpdate(); return; }
-      if (m.type === 'addComment' && typeof m.line === 'number') {
-        this.addComment(document, m.line);
+      if (m.type === 'addComment' && typeof m.line === 'number' && typeof m.text === 'string') {
+        this.addComment(document, m.line, m.text);
       }
     });
   }
 
-  /** Collect comment text from the user and write the marker (host side of D6). */
-  private async addComment(document: vscode.TextDocument, line: number): Promise<void> {
-    const text = await vscode.window.showInputBox({
-      prompt: 'Add review comment',
-      placeHolder: 'Type your review comment, then Enter to submit',
-    });
-    if (!text) { return; }
+  /**
+   * Write the marker for a comment the inline composer collected (host side of D6, #1107). The
+   * body arrives with the `addComment` message — the canvas's composer replaced the old
+   * `showInputBox` (#1107), so there is no host-side text prompt anymore.
+   */
+  private async addComment(document: vscode.TextDocument, line: number, text: string): Promise<void> {
+    if (!text.trim()) { return; }
     const author = this.overviewCache.getData()?.currentUser ?? 'architect';
     const indent =
       line < document.lineCount
diff --git a/packages/vscode/src/markdown-preview/webview/main.ts b/packages/vscode/src/markdown-preview/webview/main.ts
index 582a5cfa0..5b455942d 100644
--- a/packages/vscode/src/markdown-preview/webview/main.ts
+++ b/packages/vscode/src/markdown-preview/webview/main.ts
@@ -11,9 +11,10 @@
  *    refresh signal (re-read + re-list).
  *  - webview -> host `{ type: 'ready' }`: sent once on mount so the host pushes
  *    the first update.
- *  - webview -> host `{ type: 'addComment', line }`: the canvas's comment intent
- *    (0-based line). The host runs the InputBox + write-back; the resulting
- *    document change comes back as another `update`.
+ *  - webview -> host `{ type: 'addComment', line, text }`: the canvas's comment
+ *    intent (0-based line) with the body the inline composer collected (#1107).
+ *    The host writes the marker; the resulting document change comes back as
+ *    another `update`. (Pre-#1107 the host collected the text via `showInputBox`.)
  *
  * This file is bundled by esbuild as a browser IIFE (`dist/webview/markdown-preview.js`)
  * and is intentionally excluded from the extension's `tsc` typecheck (it targets
@@ -72,7 +73,8 @@ function render(): void {
       fileAdapter,
       markerAdapter,
       themeAdapter,
-      onAddComment: (line: number) => vscodeApi.postMessage({ type: 'addComment', line }),
+      onAddComment: (line: number, text: string) =>
+        vscodeApi.postMessage({ type: 'addComment', line, text }),
       refreshKey,
     }),
   );

From 7241db8711105de40a7ce86deab5dbbdbaad19fa Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Tue, 30 Jun 2026 10:01:36 +1000
Subject: [PATCH 10/23] [PIR #1107] Update thread: implement phase complete

---
 codev/state/pir-1107_thread.md | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/codev/state/pir-1107_thread.md b/codev/state/pir-1107_thread.md
index 6386fc182..9fe264a6d 100644
--- a/codev/state/pir-1107_thread.md
+++ b/codev/state/pir-1107_thread.md
@@ -50,3 +50,27 @@ overlay. Implementation: inject an in-flow placeholder below the block and
 Clarified scope: this issue is **add only**; edit/delete/reply/resolve = #1055. The
 composer sets the visual precedent #1055's edit mode will reuse. Plan sections 1, 2,
 5, files table, risks, and test plan updated + recommitted. Gate still pending.
+
+## Phase: Implement
+
+### Implemented (2026-06-30)
+plan-approval approved → implement phase. Built the inline composer per the approved plan:
+- New `CommentComposer.tsx` (textarea + Submit/Cancel; ⌘/Ctrl+Enter submits, Enter = newline,
+  Esc cancels, empty = no-op) + unit tests.
+- `types.ts`: `onAddComment(line)` → `onAddComment(line, text)` (contract amendment, documented).
+- `ArtifactCanvas.tsx`: `composingLine` + `composerHost` state; `+`/Enter/Space open the composer;
+  in-flow placeholder injected below the block (after the marker-card stack) via a dedicated
+  idempotent effect; composer `createPortal`'d into it; submit emits `(line, text)` + closes;
+  Esc/Cancel closes + restores focus; reload removing the block closes it; `+` suppressed for the
+  composing line. Updated existing unit + e2e tests to drive through the composer; added
+  Esc-closes + reload-clears tests.
+- CSS: `.codev-canvas-comment-composer*` mirroring the marker-card left-rule/spacing.
+- Host: `webview/main.ts` posts `{line, text}`; `preview-provider.ts` drops `showInputBox`, writes
+  the marker from the posted text. Doc comments updated.
+
+**Verification:** artifact-canvas `check-types` + `build` ✓, `test` ✓ (68 tests). vscode
+`check-types` (host + webview) ✓, esbuild bundle ✓, `lint` ✓, `test:unit` ✓ (516). Note: had to
+build codev-core/types first (pre-existing build-order, unrelated to this change).
+
+→ dev-approval gate next. Reviewer should run the worktree and exercise the composer in the
+Codev Markdown Preview. Key UX to confirm: ⌘/Ctrl+Enter-to-submit (vs old Enter-to-submit).

From fe7efbfbcc05b033ad4c09cc44c79da6a5f2ea92 Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Tue, 30 Jun 2026 10:03:33 +1000
Subject: [PATCH 11/23] chore(porch): 1107 dev-approval gate-requested

---
 codev/projects/1107-vscode-replace-top-of-window-q/status.yaml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/codev/projects/1107-vscode-replace-top-of-window-q/status.yaml b/codev/projects/1107-vscode-replace-top-of-window-q/status.yaml
index 350a39a9c..c362805ca 100644
--- a/codev/projects/1107-vscode-replace-top-of-window-q/status.yaml
+++ b/codev/projects/1107-vscode-replace-top-of-window-q/status.yaml
@@ -11,10 +11,11 @@ gates:
     approved_at: '2026-06-29T23:52:15.206Z'
   dev-approval:
     status: pending
+    requested_at: '2026-06-30T00:03:33.675Z'
   pr:
     status: pending
 iteration: 1
 build_complete: false
 history: []
 started_at: '2026-06-29T23:23:50.850Z'
-updated_at: '2026-06-29T23:52:23.651Z'
+updated_at: '2026-06-30T00:03:33.675Z'

From 69b6e39c45c9a959faa70c81269013d0a3aff95c Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Tue, 30 Jun 2026 10:21:46 +1000
Subject: [PATCH 12/23] [PIR #1107] Define named webview<->host message
 protocol types (review feedback)

---
 .../vscode/src/markdown-preview/messages.ts   | 24 +++++++++++++++++++
 .../src/markdown-preview/preview-provider.ts  | 10 +++++---
 .../src/markdown-preview/webview/main.ts      |  5 ++--
 3 files changed, 34 insertions(+), 5 deletions(-)
 create mode 100644 packages/vscode/src/markdown-preview/messages.ts

diff --git a/packages/vscode/src/markdown-preview/messages.ts b/packages/vscode/src/markdown-preview/messages.ts
new file mode 100644
index 000000000..68e60ccd1
--- /dev/null
+++ b/packages/vscode/src/markdown-preview/messages.ts
@@ -0,0 +1,24 @@
+/**
+ * Message protocol for the Codev Markdown Preview (#859, #1107).
+ *
+ * The preview is a `CustomTextEditor` webview (`webview/main.ts`) talking to the extension host
+ * (`preview-provider.ts`) over `postMessage`. These two unions are the two directions of that
+ * channel, named here so both ends share one definition and cannot drift.
+ *
+ * Host-side inbound data is untrusted — it crosses the `postMessage` boundary — so the host still
+ * validates the payload fields at runtime before acting. These types document the shape of a
+ * well-formed message; they do not vouch that a given runtime value conforms.
+ */
+import type { ReviewMarker } from '@cluesmith/codev-core/review-markers';
+
+/** Host → webview: push the current document text + parsed markers for rendering. */
+export interface HostToWebviewMessage {
+  type: 'update';
+  content: string;
+  markers: ReviewMarker[];
+}
+
+/** Webview → host: the canvas's lifecycle + comment-intent messages. */
+export type WebviewToHostMessage =
+  | { type: 'ready' }
+  | { type: 'addComment'; line: number; text: string };
diff --git a/packages/vscode/src/markdown-preview/preview-provider.ts b/packages/vscode/src/markdown-preview/preview-provider.ts
index 996110666..88c6b8574 100644
--- a/packages/vscode/src/markdown-preview/preview-provider.ts
+++ b/packages/vscode/src/markdown-preview/preview-provider.ts
@@ -33,6 +33,7 @@ import {
   parseReviewMarkers,
 } from '@cluesmith/codev-core/review-markers';
 import { renderMarkdownPreviewHtml } from './preview-template.js';
+import type { HostToWebviewMessage, WebviewToHostMessage } from './messages.js';
 import type { OverviewCache } from '../views/overview-data.js';
 
 export class MarkdownPreviewProvider implements vscode.CustomTextEditorProvider {
@@ -68,11 +69,12 @@ export class MarkdownPreviewProvider implements vscode.CustomTextEditorProvider
       // Send the raw document text: the canvas renderer strips REVIEW/comment lines itself
       // (and keeps blocks intact + data-line accurate), so the host no longer pre-hides them.
       const text = document.getText();
-      panel.webview.postMessage({
+      const message: HostToWebviewMessage = {
         type: 'update',
         content: text,
         markers: parseReviewMarkers(text),
-      });
+      };
+      panel.webview.postMessage(message);
     };
 
     const changeSub = vscode.workspace.onDidChangeTextDocument((e) => {
@@ -82,7 +84,9 @@ export class MarkdownPreviewProvider implements vscode.CustomTextEditorProvider
 
     panel.webview.onDidReceiveMessage((msg: unknown) => {
       if (!msg || typeof msg !== 'object') { return; }
-      const m = msg as { type?: string; line?: number; text?: string };
+      // Untrusted input from the webview: cast to the protocol union for the discriminant, but still
+      // validate the `addComment` payload fields at runtime before acting on them.
+      const m = msg as WebviewToHostMessage;
       if (m.type === 'ready') { pushUpdate(); return; }
       if (m.type === 'addComment' && typeof m.line === 'number' && typeof m.text === 'string') {
         this.addComment(document, m.line, m.text);
diff --git a/packages/vscode/src/markdown-preview/webview/main.ts b/packages/vscode/src/markdown-preview/webview/main.ts
index 5b455942d..ffe14da81 100644
--- a/packages/vscode/src/markdown-preview/webview/main.ts
+++ b/packages/vscode/src/markdown-preview/webview/main.ts
@@ -33,8 +33,9 @@ import {
   type ReviewMarker,
 } from '@cluesmith/codev-artifact-canvas';
 import '@cluesmith/codev-artifact-canvas/default-theme.css';
+import type { HostToWebviewMessage, WebviewToHostMessage } from '../messages.js';
 
-declare function acquireVsCodeApi(): { postMessage(message: unknown): void };
+declare function acquireVsCodeApi(): { postMessage(message: WebviewToHostMessage): void };
 
 const vscodeApi = acquireVsCodeApi();
 // Host-opaque document id — the host already knows which document this editor is
@@ -81,7 +82,7 @@ function render(): void {
 }
 
 window.addEventListener('message', (event: MessageEvent) => {
-  const msg = event.data as { type?: string; content?: string; markers?: ReviewMarker[] };
+  const msg = event.data as HostToWebviewMessage | null;
   if (msg?.type !== 'update') { return; }
   content = msg.content ?? '';
   markers = msg.markers ?? [];

From 73b9eda3c3cae69453bca7f9d2b5abe0f605299d Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Tue, 30 Jun 2026 10:22:02 +1000
Subject: [PATCH 13/23] [PIR #1107] Update thread: dev-gate feedback round 1
 (message protocol types)

---
 codev/state/pir-1107_thread.md | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/codev/state/pir-1107_thread.md b/codev/state/pir-1107_thread.md
index 9fe264a6d..d0a45257d 100644
--- a/codev/state/pir-1107_thread.md
+++ b/codev/state/pir-1107_thread.md
@@ -74,3 +74,12 @@ build codev-core/types first (pre-existing build-order, unrelated to this change
 
 → dev-approval gate next. Reviewer should run the worktree and exercise the composer in the
 Codev Markdown Preview. Key UX to confirm: ⌘/Ctrl+Enter-to-submit (vs old Enter-to-submit).
+
+### Dev-gate feedback round 1 (2026-06-30)
+Reviewer flagged `preview-provider.ts` inline anonymous message type. The postMessage value is
+genuinely untrusted/unknown at the boundary, so runtime validation stays — but the shape is now a
+named, shared protocol: new `markdown-preview/messages.ts` with `HostToWebviewMessage` +
+`WebviewToHostMessage`, used by BOTH host (`preview-provider.ts`) and webview (`main.ts`) so the
+two ends can't drift. Host casts unknown→union for the discriminant, still validates addComment
+fields at runtime. check-types (host+webview) ✓, esbuild ✓, lint ✓, test:unit ✓ (516). Gate still
+pending.

From 2b9528c48a78a94a3f44290d89248f5e2bd265a5 Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Tue, 30 Jun 2026 10:30:00 +1000
Subject: [PATCH 14/23] [PIR #1107] Convert artifact-canvas source components
 from React.createElement to JSX (review feedback)

---
 .../src/components/ArtifactCanvas.tsx         | 86 +++++++++----------
 .../src/overlays/CommentAffordance.tsx        | 20 ++---
 .../src/overlays/CommentComposer.tsx          | 68 +++++++--------
 .../src/overlays/MarkerMinimap.tsx            | 38 ++++----
 .../src/renderer/MarkdownView.tsx             | 10 ++-
 5 files changed, 108 insertions(+), 114 deletions(-)

diff --git a/packages/artifact-canvas/src/components/ArtifactCanvas.tsx b/packages/artifact-canvas/src/components/ArtifactCanvas.tsx
index e7f4ef102..fae52bcd4 100644
--- a/packages/artifact-canvas/src/components/ArtifactCanvas.tsx
+++ b/packages/artifact-canvas/src/components/ArtifactCanvas.tsx
@@ -305,50 +305,48 @@ export function ArtifactCanvas(props: ArtifactCanvasProps): React.ReactElement {
     setOverlayTop(el.offsetTop + lineHeight / 2);
   };
 
-  return React.createElement(
-    'div',
-    { className: 'codev-artifact-canvas', onMouseLeave: () => setActiveLine(null) },
-    React.createElement('div', {
-      ref: bodyRef,
-      className: 'codev-artifact-canvas-body',
-      onMouseOver: (e: React.MouseEvent) => activateFromTarget(e.target),
-      onFocus: (e: React.FocusEvent) => activateFromTarget(e.target),
-      onKeyDown: (e: React.KeyboardEvent) => {
-        if (e.key === 'Enter' || e.key === ' ') {
-          const l = lineFromEvent(e.target);
-          if (l !== null) {
-            e.preventDefault();
-            openComposer(l); // open the inline composer for this block (#1107)
+  return (
+    <div className="codev-artifact-canvas" onMouseLeave={() => setActiveLine(null)}>
+      {/* No `dangerouslySetInnerHTML`: the body's content is set imperatively in the effect above so
+          React never re-commits it (which would wipe the injected cards). Rendered with no children. */}
+      <div
+        ref={bodyRef}
+        className="codev-artifact-canvas-body"
+        onMouseOver={(e) => activateFromTarget(e.target)}
+        onFocus={(e) => activateFromTarget(e.target)}
+        onKeyDown={(e) => {
+          if (e.key === 'Enter' || e.key === ' ') {
+            const l = lineFromEvent(e.target);
+            if (l !== null) {
+              e.preventDefault();
+              openComposer(l); // open the inline composer for this block (#1107)
+            }
           }
-        }
-      },
-      // No `dangerouslySetInnerHTML`: the body's content is set imperatively in the effect above so
-      // React never re-commits it (which would wipe the injected cards). Rendered with no children.
-    }),
-    // The overlay carries ONLY the "+" add-comment affordance. Existing markers render as
-    // always-visible inline cards below their block (injected above), not in this hover overlay —
-    // that's the layout fix that stopped the cards overlapping the block content (#863). The "+"
-    // is suppressed for the line whose composer is open (the composer is shown there instead).
-    activeLine !== null && activeLine !== composingLine
-      ? React.createElement(
-          'div',
-          { className: 'codev-canvas-overlay', style: { top: overlayTop } },
-          React.createElement(CommentAffordance, { line: activeLine, onActivate: openComposer }),
-        )
-      : null,
-    // Inline composer (#1107): portalled into the in-flow placeholder injected directly below the
-    // block, so the reviewer types where the comment will live. Keeping it React-owned (rather than
-    // hand-built DOM in the imperatively-managed body) gives clean state / focus / Esc handling.
-    composingLine !== null && composerHost
-      ? createPortal(
-          React.createElement(CommentComposer, {
-            line: composingLine,
-            onSubmit: submitComposer,
-            onCancel: cancelComposer,
-          }),
-          composerHost,
-        )
-      : null,
-    React.createElement(MarkerMinimap, { markers, bodyRef }),
+        }}
+      />
+      {/* The overlay carries ONLY the "+" add-comment affordance. Existing markers render as
+          always-visible inline cards below their block (injected above), not in this hover overlay —
+          that's the layout fix that stopped the cards overlapping the block content (#863). The "+"
+          is suppressed for the line whose composer is open (the composer is shown there instead). */}
+      {activeLine !== null && activeLine !== composingLine ? (
+        <div className="codev-canvas-overlay" style={{ top: overlayTop }}>
+          <CommentAffordance line={activeLine} onActivate={openComposer} />
+        </div>
+      ) : null}
+      {/* Inline composer (#1107): portalled into the in-flow placeholder injected directly below the
+          block, so the reviewer types where the comment will live. Keeping it React-owned (rather than
+          hand-built DOM in the imperatively-managed body) gives clean state / focus / Esc handling. */}
+      {composingLine !== null && composerHost
+        ? createPortal(
+            <CommentComposer
+              line={composingLine}
+              onSubmit={submitComposer}
+              onCancel={cancelComposer}
+            />,
+            composerHost,
+          )
+        : null}
+      <MarkerMinimap markers={markers} bodyRef={bodyRef} />
+    </div>
   );
 }
diff --git a/packages/artifact-canvas/src/overlays/CommentAffordance.tsx b/packages/artifact-canvas/src/overlays/CommentAffordance.tsx
index 4334b0c5f..ae548a1f1 100644
--- a/packages/artifact-canvas/src/overlays/CommentAffordance.tsx
+++ b/packages/artifact-canvas/src/overlays/CommentAffordance.tsx
@@ -13,16 +13,16 @@ export interface CommentAffordanceProps {
  * It only signals *intent* — it never writes a marker (the host does that via MarkerAdapter.add).
  */
 export function CommentAffordance({ line, onActivate }: CommentAffordanceProps): React.ReactElement {
-  return React.createElement(
-    'button',
-    {
-      type: 'button',
-      className: 'codev-canvas-add-comment',
+  return (
+    <button
+      type="button"
+      className="codev-canvas-add-comment"
       // Human-facing line numbers are 1-based; the seam value stays 0-based (D5).
-      'aria-label': `Add comment on line ${line + 1}`,
-      'data-add-comment-line': String(line),
-      onClick: () => onActivate(line),
-    },
-    '+',
+      aria-label={`Add comment on line ${line + 1}`}
+      data-add-comment-line={String(line)}
+      onClick={() => onActivate(line)}
+    >
+      +
+    </button>
   );
 }
diff --git a/packages/artifact-canvas/src/overlays/CommentComposer.tsx b/packages/artifact-canvas/src/overlays/CommentComposer.tsx
index a9148f972..52a2309db 100644
--- a/packages/artifact-canvas/src/overlays/CommentComposer.tsx
+++ b/packages/artifact-canvas/src/overlays/CommentComposer.tsx
@@ -53,42 +53,36 @@ export function CommentComposer({ line, onSubmit, onCancel }: CommentComposerPro
 
   const empty = text.trim().length === 0;
 
-  return React.createElement(
-    'div',
-    { className: 'codev-canvas-comment-composer' },
-    React.createElement('textarea', {
-      ref: textareaRef,
-      className: 'codev-canvas-comment-composer-input',
-      // Human-facing line numbers are 1-based; the data model stays 0-based (spec D5).
-      'aria-label': `Add comment on line ${line + 1}`,
-      placeholder: 'Add a review comment… (⌘/Ctrl+Enter to submit, Esc to cancel)',
-      rows: 3,
-      value: text,
-      onChange: (e: React.ChangeEvent<HTMLTextAreaElement>) => setText(e.target.value),
-      onKeyDown,
-    }),
-    React.createElement(
-      'div',
-      { className: 'codev-canvas-comment-composer-actions' },
-      React.createElement(
-        'button',
-        {
-          type: 'button',
-          className: 'codev-canvas-comment-composer-cancel',
-          onClick: onCancel,
-        },
-        'Cancel',
-      ),
-      React.createElement(
-        'button',
-        {
-          type: 'button',
-          className: 'codev-canvas-comment-composer-submit',
-          onClick: submit,
-          disabled: empty,
-        },
-        'Comment',
-      ),
-    ),
+  return (
+    <div className="codev-canvas-comment-composer">
+      <textarea
+        ref={textareaRef}
+        className="codev-canvas-comment-composer-input"
+        // Human-facing line numbers are 1-based; the data model stays 0-based (spec D5).
+        aria-label={`Add comment on line ${line + 1}`}
+        placeholder="Add a review comment… (⌘/Ctrl+Enter to submit, Esc to cancel)"
+        rows={3}
+        value={text}
+        onChange={(e) => setText(e.target.value)}
+        onKeyDown={onKeyDown}
+      />
+      <div className="codev-canvas-comment-composer-actions">
+        <button
+          type="button"
+          className="codev-canvas-comment-composer-cancel"
+          onClick={onCancel}
+        >
+          Cancel
+        </button>
+        <button
+          type="button"
+          className="codev-canvas-comment-composer-submit"
+          onClick={submit}
+          disabled={empty}
+        >
+          Comment
+        </button>
+      </div>
+    </div>
   );
 }
diff --git a/packages/artifact-canvas/src/overlays/MarkerMinimap.tsx b/packages/artifact-canvas/src/overlays/MarkerMinimap.tsx
index 7df753ffb..b9e84e84c 100644
--- a/packages/artifact-canvas/src/overlays/MarkerMinimap.tsx
+++ b/packages/artifact-canvas/src/overlays/MarkerMinimap.tsx
@@ -64,24 +64,24 @@ export function MarkerMinimap({ markers, bodyRef }: MarkerMinimapProps): React.R
 
   if (markers.length === 0) return null; // hidden when the doc has zero markers (AC)
 
-  return React.createElement(
-    'div',
-    { className: 'codev-canvas-minimap', 'aria-label': 'Review marker minimap' },
-    dots.map((dot, i) =>
-      React.createElement('button', {
-        key: String(i),
-        type: 'button',
-        className: 'codev-canvas-minimap-dot',
-        style: { top: `${dot.frac * 100}%` },
-        title: `${dot.marker.author}: ${truncate(dot.marker.text)}`,
-        'aria-label': `Jump to comment by ${dot.marker.author} on line ${dot.marker.line + 1}`,
-        onClick: () => {
-          const el = bodyRef.current?.querySelector<HTMLElement>(
-            `[data-line="${dot.marker.line}"]`,
-          );
-          el?.scrollIntoView({ behavior: 'smooth', block: 'center' });
-        },
-      }),
-    ),
+  return (
+    <div className="codev-canvas-minimap" aria-label="Review marker minimap">
+      {dots.map((dot, i) => (
+        <button
+          key={String(i)}
+          type="button"
+          className="codev-canvas-minimap-dot"
+          style={{ top: `${dot.frac * 100}%` }}
+          title={`${dot.marker.author}: ${truncate(dot.marker.text)}`}
+          aria-label={`Jump to comment by ${dot.marker.author} on line ${dot.marker.line + 1}`}
+          onClick={() => {
+            const el = bodyRef.current?.querySelector<HTMLElement>(
+              `[data-line="${dot.marker.line}"]`,
+            );
+            el?.scrollIntoView({ behavior: 'smooth', block: 'center' });
+          }}
+        />
+      ))}
+    </div>
   );
 }
diff --git a/packages/artifact-canvas/src/renderer/MarkdownView.tsx b/packages/artifact-canvas/src/renderer/MarkdownView.tsx
index 18b0bc7ca..295cd9bd3 100644
--- a/packages/artifact-canvas/src/renderer/MarkdownView.tsx
+++ b/packages/artifact-canvas/src/renderer/MarkdownView.tsx
@@ -15,8 +15,10 @@ export interface MarkdownViewProps {
  */
 export function MarkdownView({ source }: MarkdownViewProps): React.ReactElement {
   const html = React.useMemo(() => renderMarkdown(source), [source]);
-  return React.createElement('div', {
-    className: 'codev-artifact-canvas-rendered',
-    dangerouslySetInnerHTML: { __html: html },
-  });
+  return (
+    <div
+      className="codev-artifact-canvas-rendered"
+      dangerouslySetInnerHTML={{ __html: html }}
+    />
+  );
 }

From 87bcc183b6953b77c4e33d87ede00658ac0c24d5 Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Tue, 30 Jun 2026 10:30:14 +1000
Subject: [PATCH 15/23] [PIR #1107] Update thread: dev-gate feedback round 2
 (JSX conversion)

---
 codev/state/pir-1107_thread.md | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/codev/state/pir-1107_thread.md b/codev/state/pir-1107_thread.md
index d0a45257d..3866c9f4d 100644
--- a/codev/state/pir-1107_thread.md
+++ b/codev/state/pir-1107_thread.md
@@ -83,3 +83,12 @@ named, shared protocol: new `markdown-preview/messages.ts` with `HostToWebviewMe
 two ends can't drift. Host casts unknown→union for the discriminant, still validates addComment
 fields at runtime. check-types (host+webview) ✓, esbuild ✓, lint ✓, test:unit ✓ (516). Gate still
 pending.
+
+### Dev-gate feedback round 2 (2026-06-30)
+Reviewer questioned `React.createElement` style in CommentComposer. Clarified it IS a real
+component (createElement vs JSX is just syntax). Reviewer chose to convert the WHOLE package to
+JSX (accepted scope expansion beyond #1107). Converted all 5 source components — CommentComposer,
+ArtifactCanvas, CommentAffordance, MarkerMinimap, MarkdownView — from createElement to JSX
+(package tsconfig already had jsx: react-jsx; tests already used JSX, so build supported it).
+Behavior unchanged. artifact-canvas check-types ✓ + test ✓ (68) + build ✓; vscode check-types ✓ +
+esbuild ✓ + test:unit ✓ (516). Gate still pending.

From fb4a6b0ccb217552104ac13d2b451f1e30c06a65 Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Tue, 30 Jun 2026 10:39:35 +1000
Subject: [PATCH 16/23] chore(porch): 1107 dev-approval gate-approved

---
 .../projects/1107-vscode-replace-top-of-window-q/status.yaml | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/codev/projects/1107-vscode-replace-top-of-window-q/status.yaml b/codev/projects/1107-vscode-replace-top-of-window-q/status.yaml
index c362805ca..a8dad80d1 100644
--- a/codev/projects/1107-vscode-replace-top-of-window-q/status.yaml
+++ b/codev/projects/1107-vscode-replace-top-of-window-q/status.yaml
@@ -10,12 +10,13 @@ gates:
     requested_at: '2026-06-29T23:29:21.703Z'
     approved_at: '2026-06-29T23:52:15.206Z'
   dev-approval:
-    status: pending
+    status: approved
     requested_at: '2026-06-30T00:03:33.675Z'
+    approved_at: '2026-06-30T00:39:35.411Z'
   pr:
     status: pending
 iteration: 1
 build_complete: false
 history: []
 started_at: '2026-06-29T23:23:50.850Z'
-updated_at: '2026-06-30T00:03:33.675Z'
+updated_at: '2026-06-30T00:39:35.412Z'

From f71e0412242c3617bf3d3859da2caabae655e70b Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Tue, 30 Jun 2026 10:39:52 +1000
Subject: [PATCH 17/23] chore(porch): 1107 review phase-transition

---
 .../projects/1107-vscode-replace-top-of-window-q/status.yaml  | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/codev/projects/1107-vscode-replace-top-of-window-q/status.yaml b/codev/projects/1107-vscode-replace-top-of-window-q/status.yaml
index a8dad80d1..0d0dc8f61 100644
--- a/codev/projects/1107-vscode-replace-top-of-window-q/status.yaml
+++ b/codev/projects/1107-vscode-replace-top-of-window-q/status.yaml
@@ -1,7 +1,7 @@
 id: '1107'
 title: vscode-replace-top-of-window-q
 protocol: pir
-phase: implement
+phase: review
 plan_phases: []
 current_plan_phase: null
 gates:
@@ -19,4 +19,4 @@ iteration: 1
 build_complete: false
 history: []
 started_at: '2026-06-29T23:23:50.850Z'
-updated_at: '2026-06-30T00:39:35.412Z'
+updated_at: '2026-06-30T00:39:52.285Z'

From fd87b4f78ee4a21888de098d47c859d2d6866df2 Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Tue, 30 Jun 2026 10:44:17 +1000
Subject: [PATCH 18/23] [PIR #1107] Review + retrospective; arch.md +
 lessons-learned.md updates

---
 codev/resources/arch.md                       |   2 +-
 codev/resources/lessons-learned.md            |   1 +
 .../1107-preview-inline-comment-composer.md   | 113 ++++++++++++++++++
 codev/state/pir-1107_thread.md                |  15 +++
 4 files changed, 130 insertions(+), 1 deletion(-)
 create mode 100644 codev/reviews/1107-preview-inline-comment-composer.md

diff --git a/codev/resources/arch.md b/codev/resources/arch.md
index 554fd4901..df473f558 100644
--- a/codev/resources/arch.md
+++ b/codev/resources/arch.md
@@ -1104,7 +1104,7 @@ The VS Code extension (`packages/vscode`) is a thin client over Tower's existing
 - **Panel view container (#812)**: The extension contributes view containers to **two** locations — `activitybar.codev` (the 7-section sidebar) and `panel.codevPanel` (bottom panel, wide-short geometry). The panel exists as scaffolding for views whose shape suits a wide layout (timelines, rosters, tables); migrations are tracked separately (#813/#814/#815). Panel views are plain `TreeDataProvider`s, identical in kind to sidebar providers — VS Code lets the same view types live in either location. A `codev.panelContainerEmpty` context key gates a placeholder view that hides once real views register — **#921's `codev.devServer` is the first such view, so the panel now ships non-empty** (the key is seeded `false`). VS Code gives no control over panel-tab *position* (it lands last, in the `…` overflow), so the extension does a one-time, globalState-guarded reveal (`workbench.view.extension.codevPanel`) on first activation for discoverability.
 - **Codev Dev surface (#921)**: The single `afx dev` PTY gets two complementary surfaces, both driven off the one `TerminalManager.onDidChangeDevTerminals` event (single source of truth, so chip and tab never drift on start/stop/swap): a `codev.devServer` panel `TreeDataProvider` (first real `codevPanel` tenant — status header of target / live-ticking uptime / best-effort port, plus title-bar Stop / Restart / Switch-Target / Show-Hide-sidebar actions gated by a `codev.devServerRunning` key) and an always-visible **status-bar chip** (`StatusBarItem`, left, priority 99) shown only while a dev runs, clicking through to the tab. The native `Codev: <name> (dev)` terminal stays as the output surface (coexist) — the new tab is a status/control surface, not an output mirror, so there is no second PTY/xterm re-plumbing. Uptime needs a start time `listDevTerminals()` doesn't carry, so `TerminalManager` keeps a `builderId → startedAt` map. Pure formatters (`views/dev-server-format.ts`: uptime, port-from-config) are vitest-tested.
 - **Startup CLI preflight (#791)**: On `activate()` the extension verifies the `codev` CLI is installed and at least its own `package.json` version (`codev --version`, resolved like `resolveAfxPath`, cached per session, 400ms-bounded, fire-and-forget so activation never blocks). Missing → `Get started with Codev` walkthrough; outdated → upgrade notification; either dismissed → CLI-dependent commands no-op with one "run setup" toast. Commands register through two helpers — `reg` (unguarded) and `regCli` (guarded) — so the registrar name *is* the guard policy (no separate list). Preflight also sets the `codev.cliReady` context key, which drives the walkthrough's Verify-step completion. Lives in `src/preflight/` (`preflight-core.ts` pure + unit-tested, `preflight.ts` vscode glue).
-- **Markdown Preview / artifact-canvas host integration (#859)**: The first integration of the shared `@cluesmith/codev-artifact-canvas` React surface into a host. A read-only `CustomTextEditor` (`codev.markdownPreview`, `priority: "option"` so it never replaces the default `.md` editor; selector scoped to `**/codev/{specs,plans,reviews}/**/*.md`) renders an artifact and lets a reviewer add comments by hovering a block and clicking `+`. It is the extension's **first bundled React webview**: a *second* esbuild entry (`esbuild.js`, browser/IIFE, bundles react/react-dom/the canvas + emits `markdown-preview.css`), type-checked by a dedicated `tsconfig.webview.json` (DOM libs) since the host `tsconfig.json` excludes the browser dir. Host↔webview bridge (`markdown-preview/preview-provider.ts`, HTML in a sibling `preview-template.ts` per #920): the host posts **raw** document text + parsed markers; the webview mounts `<ArtifactCanvas>`; `onAddComment(line)` → host `showInputBox` → `WorkspaceEdit` → the round-trip goes through the file text. **Cross-cutting invariants this established**: (1) the on-disk REVIEW-marker convention (`<!-- REVIEW(@author): text -->`, a marker annotates the nearest non-marker line above it) lives in `@cluesmith/codev-core/review-markers` so every host (vscode now, dashboard later) writes/parses identical bytes — the editor Comments-API path (`comments/plan-review.ts`) shares it. (2) The canvas renderer runs markdown-it with **`html: true` + DOMPurify as the sole guard** (#1042 amends spec-945 D7: safe static HTML renders, scripts/handlers/`javascript:` stripped, document JS never executes) and **strips full-line HTML comments before block parsing** with a cleaned→original line map (#1036), so markers never render as text and never split a multi-line block while `data-line` stays accurate.
+- **Markdown Preview / artifact-canvas host integration (#859)**: The first integration of the shared `@cluesmith/codev-artifact-canvas` React surface into a host. A read-only `CustomTextEditor` (`codev.markdownPreview`, `priority: "option"` so it never replaces the default `.md` editor; selector scoped to `**/codev/{specs,plans,reviews}/**/*.md`) renders an artifact and lets a reviewer add comments by hovering a block and clicking `+`. It is the extension's **first bundled React webview**: a *second* esbuild entry (`esbuild.js`, browser/IIFE, bundles react/react-dom/the canvas + emits `markdown-preview.css`), type-checked by a dedicated `tsconfig.webview.json` (DOM libs) since the host `tsconfig.json` excludes the browser dir. Host↔webview bridge (`markdown-preview/preview-provider.ts`, HTML in a sibling `preview-template.ts` per #920; the two `postMessage` directions are a named protocol in `markdown-preview/messages.ts`, `HostToWebviewMessage` / `WebviewToHostMessage`, shared by both ends so they can't drift — #1107): the host posts **raw** document text + parsed markers; the webview mounts `<ArtifactCanvas>`; the reviewer's `+`/Enter opens an **inline composer rendered in-flow below the block** (`overlays/CommentComposer.tsx`, portalled into a placeholder there — #1107 replaced the old center-top `showInputBox`); on submit `onAddComment(line, text)` → host `WorkspaceEdit` → the round-trip goes through the file text. (Host-side inbound `postMessage` data is untrusted, so the host still validates payload fields at runtime despite the named type.) **Cross-cutting invariants this established**: (1) the on-disk REVIEW-marker convention (`<!-- REVIEW(@author): text -->`, a marker annotates the nearest non-marker line above it) lives in `@cluesmith/codev-core/review-markers` so every host (vscode now, dashboard later) writes/parses identical bytes — the editor Comments-API path (`comments/plan-review.ts`) shares it. (2) The canvas renderer runs markdown-it with **`html: true` + DOMPurify as the sole guard** (#1042 amends spec-945 D7: safe static HTML renders, scripts/handlers/`javascript:` stripped, document JS never executes) and **strips full-line HTML comments before block parsing** with a cleaned→original line map (#1036), so markers never render as text and never split a multi-line block while `data-line` stays accurate.
 - **Builders diff-review: navigation + active-file sync (#1060/#1066)**: The "current builder/file" in a diff review is **derived from the active editor, not stored**. The diff-inject registry (`diff-inject-codelens.ts`) maps each right-side worktree fsPath → `{ builderId, relPath, hunks }`; because a worktree-absolute path is unique per builder, two builders that changed the same relative path stay distinct. Everything keys off `getDiffInjectEntry(activeEditor.fsPath)`: cross-file keyboard nav (`codev.diffNextFile`/`diffPreviousFile`, #1060) and the Builders-tree active-file reveal (#1066). Navigation walks **one builder's** changed-file list (it never crosses builders) in the **visible tree order** — depth-first via `flattenTreeOrder(buildFilePathTree(...))` in tree-view mode, raw git `--name-status` order in flat mode — and **wraps** at both ends (`computeNavTarget` modulo) to match VSCode's built-in hunk navigation, which also wraps. The reveal (#1066, Explorer-style, gated by `codev.buildersAutoReveal`) requires two pieces of TreeView groundwork: file rows carry a stable `<builderId>::<relPath>` id and `BuildersProvider.getParent` reconstructs the full chain (file → compacted folder(s) → builder → group), since `reveal` matches by id and walks parents while the subtree is still collapsed. It fires on **both** the active-editor change AND the diff-inject registry change, because a programmatic diff open registers its entry *after* the editor activates (same dual-trigger the lens context-key sync uses).
 - **Agents view + group-by axes (#1104)**: The sidebar's primary work view is **Agents** (view id `codev.agents`, formerly `codev.builders` — only the user-facing id/label changed; internal symbols like `BuildersProvider` and the `codev.buildersGroupBy` setting keep their names). It groups in-flight builders by **exactly one of three axes** (`stage` | `area` | `architect`), each a `BuilderGrouping` strategy in `views/builder-grouping.ts`; `architect` groups by `spawnedByArchitect` (null folds into `main`, matching the affinity router) and a childless architect produces no group, so the work view shows owners-of-work while the *full* roster stays in Workspace > Architects. The axis is a single toolbar button (see the no-`toggled` lesson). The architect roster the Add-Architect flow needs rides on **`/api/overview` as `architects: ArchitectState[]`** (additive wire field), built by a shared `liveArchitects(entry, manager)` helper in `tower-routes.ts` reused by the `/api/state` dashboard-state path so the two payloads can't drift — `liveArchitects` (running-session set, from `terminal_sessions`) is distinct from state.ts's `getArchitects` (persisted `architect` table). `Codev: Add Architect` is conversational: it resolves `main` from that roster and routes a request via `sendMessage('architect:main', …)` rather than creating the architect directly.
 - **Running-Tower version probe (#983)**: A second preflight dimension catches the case the CLI check structurally can't — an `npm install -g` upgrade that updated the on-disk binary but left **Tower running stale in-memory code**. Tower exposes read-only `GET /api/version` (`{ version, startedAt }`, wire type `TowerVersionInfo` in `codev-types`, served from `RouteContext` so it reports the *running* process's version, not the disk binary; unauthenticated like `/health`). On each `connected` transition the extension probes it (`TowerClient.getVersion()`, returning the raw `{ status }` so the preflight distinguishes a 404 "Tower too old to report" from an unreachable Tower). Divergence fires **only on `running < installedCLI`** — the case a restart actually fixes; running-vs-extension is left to #791 (a restart can't load code that isn't installed). The toast offers a `Restart Tower` action (`afx tower stop && afx tower start`, local host only — safe to self-invoke because #991 scoped `afx tower stop` to the listening process; remote hosts get informational wording). The two async inputs (installed-CLI version, running-Tower version) are reconciled against the startup race by re-probing once the CLI check resolves. Decision/wording logic is pure + unit-tested in `preflight-core.ts` (`decideTowerStatus`, `towerDivergenceMessage`).
diff --git a/codev/resources/lessons-learned.md b/codev/resources/lessons-learned.md
index 461535810..a06c3242f 100644
--- a/codev/resources/lessons-learned.md
+++ b/codev/resources/lessons-learned.md
@@ -163,6 +163,7 @@ Generalizable wisdom extracted from review documents, ordered by impact. Updated
 - [From 0589] Concept command abstraction (shell command per operation, env vars for params, JSON on stdout) is an effective pattern for decoupling from a specific CLI tool. Default commands wrap the existing tool, overrides in config enable alternatives. Key: provide both sync and async variants, support `raw` mode for non-JSON output, and always thread the config through all call sites.
 - [From 0589] When migrating multiple call sites to a new abstraction, configuration threading (passing `forgeConfig`/`workspaceRoot` to every call) is easy to miss at non-obvious sites like porch checks and merge instructions. Phase-scoped consultation reviews are effective at catching these gaps.
 - [From 818] An acceptance criterion of "rule structurally identical to X" is a written-rule trap when the rule lives as duplicated prose in two views. Two copies drift even with diligence; the only durable enforcement is one shared function both views import. Extract when the second consumer lands — not before (no abstraction without users) and not later (drift starts on day one).
+- [From 1107] To place an *interactive* React widget (text input, buttons) inside an `innerHTML`-managed body, don't hand-build DOM there — inject an empty placeholder node in an effect and `createPortal` the React component into it. React owns the widget's state/focus/keyboard, while it still sits in normal document flow. Make the placeholder-injection effect idempotent (reuse a correctly-placed node; bail when `previousElementSibling` already matches the anchor) or the `setState`-on-inject loops; an `html` rebuild disconnects the node, which the same guard detects and re-creates. This is the read-while-write composer (#1107) but applies to any overlay/widget over imperatively-rendered content.
 
 ## Process
 
diff --git a/codev/reviews/1107-preview-inline-comment-composer.md b/codev/reviews/1107-preview-inline-comment-composer.md
new file mode 100644
index 000000000..1790ae547
--- /dev/null
+++ b/codev/reviews/1107-preview-inline-comment-composer.md
@@ -0,0 +1,113 @@
+# PIR Review: Inline composer for preview-pane review comments
+
+Fixes #1107
+
+## Summary
+
+Adding a review comment from the Codev Markdown Preview previously opened
+`vscode.window.showInputBox` — a center-top Quick Pick far from the block the
+reviewer clicked `+` on, breaking the visual anchor while typing. This replaces it
+with an **inline composer rendered in-flow directly below the block** (a textarea
+with Submit/Cancel), so the reviewer types the comment exactly where it will live.
+The comment-intent seam widened from `onAddComment(line)` to
+`onAddComment(line, text)`; the host dropped its text prompt and writes the marker
+straight from the body the composer collected. The on-disk REVIEW-marker format is
+unchanged (multi-line input collapses to single-line at write time, as before).
+
+## Files Changed
+
+- `packages/artifact-canvas/src/overlays/CommentComposer.tsx` (+88 / −0) — new composer component
+- `packages/artifact-canvas/src/overlays/__tests__/comment-composer.test.tsx` (+83 / −0) — new unit tests
+- `packages/artifact-canvas/src/components/ArtifactCanvas.tsx` (+~110 / −~24) — composer state, in-flow placeholder injection, portal wiring; JSX conversion
+- `packages/artifact-canvas/src/components/__tests__/artifact-canvas.test.tsx` (+~80 / −~15) — open-composer→submit flow, Esc/reload coverage
+- `packages/artifact-canvas/src/__tests__/end-to-end.test.tsx` (+~20 / −~14) — drive round-trip through the composer
+- `packages/artifact-canvas/src/types.ts` (+8 / −4) — `onAddComment(line, text)` contract amendment
+- `packages/artifact-canvas/src/overlays/CommentAffordance.tsx` (+11 / −9) — JSX conversion
+- `packages/artifact-canvas/src/overlays/MarkerMinimap.tsx` (+21 / −17) — JSX conversion
+- `packages/artifact-canvas/src/renderer/MarkdownView.tsx` (+7 / −3) — JSX conversion
+- `packages/artifact-canvas/src/styles/default-theme.css` (+58 / −0) — composer styling
+- `packages/artifact-canvas/examples/main.tsx` (+4 / −4) — example uses the new seam
+- `packages/vscode/src/markdown-preview/messages.ts` (+24 / −0) — new named webview↔host protocol types
+- `packages/vscode/src/markdown-preview/preview-provider.ts` (+~22 / −~15) — drop `showInputBox`; write from posted text; use protocol types
+- `packages/vscode/src/markdown-preview/webview/main.ts` (+~9 / −~6) — post `{line, text}`; use protocol types
+- `codev/plans/1107-preview-inline-comment-composer.md`, `codev/reviews/1107-preview-inline-comment-composer.md`, `codev/state/pir-1107_thread.md` — PIR artifacts
+- `codev/resources/arch.md`, `codev/resources/lessons-learned.md` — governance updates (below)
+
+## Commits
+
+- `87a6788d` [PIR #1107] artifact-canvas: inline comment composer; widen onAddComment seam to (line, text)
+- `1f5e0614` [PIR #1107] vscode preview: drop showInputBox; write marker from composer-collected text
+- `69b6e39c` [PIR #1107] Define named webview<->host message protocol types (review feedback)
+- `2b9528c4` [PIR #1107] Convert artifact-canvas source components from React.createElement to JSX (review feedback)
+- (plus thread-update commits)
+
+## Test Results
+
+- `pnpm --filter @cluesmith/codev-artifact-canvas build`: ✓ pass
+- `pnpm --filter @cluesmith/codev-artifact-canvas test`: ✓ pass (68 tests; 9 new composer unit tests + updated canvas/e2e tests driving the open-composer→submit flow)
+- `pnpm --filter @cluesmith/codev-artifact-canvas check-types`: ✓ pass
+- vscode `check-types` (host + `tsconfig.webview.json`): ✓ pass
+- vscode esbuild bundle (`node esbuild.js --production`): ✓ pass
+- vscode `lint`: ✓ pass
+- vscode `test:unit`: ✓ pass (516 tests)
+- Manual verification: confirmed by the human at the `dev-approval` gate — composer appears at the block (not the window top), block stays visible while typing, ⌘/Ctrl+Enter submits, Esc cancels and restores focus, multi-line input works, submitted comment collapses into the persisted card in place.
+
+## Architecture Updates
+
+**COLD — `codev/resources/arch.md` updated** (the "Markdown Preview / artifact-canvas
+host integration" entry). The previous text described the now-removed flow
+(`onAddComment(line)` → host `showInputBox` → `WorkspaceEdit`). Updated to reflect:
+the inline composer (`overlays/CommentComposer.tsx`, portalled in-flow below the
+block), the widened `onAddComment(line, text)` seam, and the new named host↔webview
+message protocol (`markdown-preview/messages.ts`, shared by both ends; inbound data
+still validated at runtime because it's untrusted).
+
+**HOT — no `arch-critical.md` change.** This is a package-level seam/UX change, not a
+framework-wide cross-cutting fact; it does not meet the hot-tier bar (and the file is
+at/near its cap). Correctly routed to the cold reference.
+
+## Lessons Learned Updates
+
+**COLD — `codev/resources/lessons-learned.md` updated** (Architecture section): the
+reusable pattern for placing an *interactive* React widget inside an
+`innerHTML`-managed body — inject a placeholder node in an effect and `createPortal`
+the component into it, with an idempotent injection effect to avoid a
+`setState`-on-inject loop. Spec-narrow recipe → cold tier, not the capped hot file.
+
+**HOT — no `lessons-critical.md` change.** No behavior-changing cross-cutting rule
+emerged that warrants displacing a capped hot lesson.
+
+## Things to Look At During PR Review
+
+- **`ArtifactCanvas.tsx` placeholder-injection effect** — the trickiest part. It
+  injects an in-flow `.codev-canvas-comment-composer-host` below the block (after the
+  marker-card stack if present) and is guarded to be idempotent: it bails when a
+  correctly-placed host already exists (`isConnected && previousElementSibling ===
+  anchor`), so the `setComposerHost` call doesn't loop. An `html` rebuild disconnects
+  the node and the guard re-creates it. Worth a careful read.
+- **Event isolation via portal** — the composer's DOM lives inside the body div, but
+  React routes synthetic events through the *fiber* tree (the portal's parent is the
+  canvas root, not the body div), so the body's `onKeyDown` "open composer" handler
+  does not fire for keystrokes typed into the composer. This is why plain Enter in the
+  textarea inserts a newline rather than re-triggering the open path.
+- **Keystroke choice** — ⌘/Ctrl+Enter submits, Enter = newline, Esc cancels (GitHub
+  review-composer convention). This changed the old single-line Enter-to-submit muscle
+  memory; confirmed acceptable at the dev-approval gate.
+- **Untrusted `postMessage`** — `preview-provider.ts` casts inbound to the named union
+  for the discriminant but still validates `line`/`text` at runtime. The named type
+  documents the shape; it does not vouch for an arbitrary runtime value.
+- **Scope note (JSX conversion)** — at the reviewer's request, all five artifact-canvas
+  source components were converted from `React.createElement` to JSX in this PR (not
+  just the new file), so the package is internally consistent. Behavior is unchanged;
+  it inflates the diff. The package's `tsconfig.json` already had `"jsx": "react-jsx"`.
+
+## How to Test Locally
+
+- **View diff**: VSCode sidebar → right-click builder `pir-1107` → **View Diff**
+- **Run dev server**: VSCode sidebar → **Run Dev Server**, or `afx dev pir-1107`
+- **What to verify**:
+  - Open a `codev/specs|plans|reviews/*.md` in the Codev Markdown Preview ("Reopen With… → Codev Markdown Preview").
+  - Click `+` on blocks at the top, middle, and bottom of a long doc — the composer appears at the block each time, and the block stays visible while typing.
+  - ⌘/Ctrl+Enter submits and the comment collapses into the persisted card in place; Esc cancels and returns focus to the block.
+  - Keyboard-only: Tab to `+`, Enter to open, type, ⌘/Ctrl+Enter to submit.
+  - Multi-line input works (Enter = newline); the on-disk marker is still single-line.
diff --git a/codev/state/pir-1107_thread.md b/codev/state/pir-1107_thread.md
index 3866c9f4d..9d2149f57 100644
--- a/codev/state/pir-1107_thread.md
+++ b/codev/state/pir-1107_thread.md
@@ -92,3 +92,18 @@ ArtifactCanvas, CommentAffordance, MarkerMinimap, MarkdownView — from createEl
 (package tsconfig already had jsx: react-jsx; tests already used JSX, so build supported it).
 Behavior unchanged. artifact-canvas check-types ✓ + test ✓ (68) + build ✓; vscode check-types ✓ +
 esbuild ✓ + test:unit ✓ (516). Gate still pending.
+
+## Phase: Review
+
+### Review artifact + governance (2026-06-30)
+dev-approval approved → review phase. Wrote `codev/reviews/1107-preview-inline-comment-composer.md`
+(Summary / Files / Commits / Test Results / Architecture Updates / Lessons Learned / Things to Look
+At / How to Test). Governance routing (Spec 987 cold tier):
+- arch.md: updated the "Markdown Preview / artifact-canvas host integration" entry — old text
+  described the removed `onAddComment(line)`→`showInputBox` flow; now describes inline composer +
+  `(line,text)` seam + named messages.ts protocol. No hot arch-critical change (package-level, not
+  framework-wide; file near cap).
+- lessons-learned.md (Architecture): added the createPortal-into-innerHTML-managed-body pattern with
+  the idempotent-injection guard. No hot lessons-critical change.
+Next: open PR with review as body, `porch done --pr`, then `porch done` → single CMAP-2 advisory
+pass → pr gate.

From 79188fb4ae602704b34f1b70efd67e2762669e2d Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Tue, 30 Jun 2026 10:44:34 +1000
Subject: [PATCH 19/23] chore(porch): 1107 record PR #1121

---
 .../1107-vscode-replace-top-of-window-q/status.yaml        | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/codev/projects/1107-vscode-replace-top-of-window-q/status.yaml b/codev/projects/1107-vscode-replace-top-of-window-q/status.yaml
index 0d0dc8f61..5cf7e7e99 100644
--- a/codev/projects/1107-vscode-replace-top-of-window-q/status.yaml
+++ b/codev/projects/1107-vscode-replace-top-of-window-q/status.yaml
@@ -19,4 +19,9 @@ iteration: 1
 build_complete: false
 history: []
 started_at: '2026-06-29T23:23:50.850Z'
-updated_at: '2026-06-30T00:39:52.285Z'
+updated_at: '2026-06-30T00:44:34.712Z'
+pr_history:
+  - phase: review
+    pr_number: 1121
+    branch: builder/pir-1107
+    created_at: '2026-06-30T00:44:34.712Z'

From 1b71297da52e8dd38d7b70cfe60f6d6de2784459 Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Tue, 30 Jun 2026 10:44:42 +1000
Subject: [PATCH 20/23] chore(porch): 1107 review build-complete

---
 .../projects/1107-vscode-replace-top-of-window-q/status.yaml  | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/codev/projects/1107-vscode-replace-top-of-window-q/status.yaml b/codev/projects/1107-vscode-replace-top-of-window-q/status.yaml
index 5cf7e7e99..d25f9986b 100644
--- a/codev/projects/1107-vscode-replace-top-of-window-q/status.yaml
+++ b/codev/projects/1107-vscode-replace-top-of-window-q/status.yaml
@@ -16,10 +16,10 @@ gates:
   pr:
     status: pending
 iteration: 1
-build_complete: false
+build_complete: true
 history: []
 started_at: '2026-06-29T23:23:50.850Z'
-updated_at: '2026-06-30T00:44:34.712Z'
+updated_at: '2026-06-30T00:44:42.310Z'
 pr_history:
   - phase: review
     pr_number: 1121

From 27c2c87aba6951dabae645de13b1b475b4e958c8 Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Tue, 30 Jun 2026 10:51:53 +1000
Subject: [PATCH 21/23] [PIR #1107] Append new comment below existing thread
 (markerAppendLine); fix stale header comment

---
 .../core/src/__tests__/review-markers.test.ts | 34 +++++++++++++++++++
 packages/core/src/review-markers.ts           | 18 ++++++++++
 .../src/markdown-preview/preview-provider.ts  | 16 +++++----
 3 files changed, 62 insertions(+), 6 deletions(-)

diff --git a/packages/core/src/__tests__/review-markers.test.ts b/packages/core/src/__tests__/review-markers.test.ts
index 3e8fe0e6b..eee5db45e 100644
--- a/packages/core/src/__tests__/review-markers.test.ts
+++ b/packages/core/src/__tests__/review-markers.test.ts
@@ -3,6 +3,7 @@ import {
   serializeReviewMarker,
   parseReviewMarkers,
   markerInsertionLine,
+  markerAppendLine,
   isReviewMarkerLine,
   isEligibleReviewPath,
 } from '../review-markers.js';
@@ -80,6 +81,39 @@ describe('round-trip (insert → parse)', () => {
   });
 });
 
+describe('markerAppendLine (#1107 — append below an existing thread)', () => {
+  it('equals markerInsertionLine when the block has no existing markers', () => {
+    const text = '# Heading\nbody paragraph';
+    expect(markerAppendLine(text, 0)).toBe(markerInsertionLine(0)); // -> 1
+  });
+
+  it('appends AFTER a run of stacked markers so the newest comment is last (regression for #1107)', () => {
+    // Block on line 0 with two stacked markers on lines 1 and 2.
+    const text = [
+      '# Heading',
+      serializeReviewMarker('a', 'first'),
+      serializeReviewMarker('b', 'second'),
+      'body paragraph',
+    ].join('\n');
+    // markerInsertionLine would prepend at line 1 (top of the thread); append lands at line 3.
+    expect(markerInsertionLine(0)).toBe(1);
+    const appendAt = markerAppendLine(text, 0);
+    expect(appendAt).toBe(3);
+
+    // Writing there keeps the existing two first and the new one last, in file/render order.
+    const lines = text.split('\n');
+    lines.splice(appendAt, 0, serializeReviewMarker('c', 'third'));
+    const markers = parseReviewMarkers(lines.join('\n'));
+    expect(markers.map((m) => m.text)).toEqual(['first', 'second', 'third']);
+    expect(markers.every((m) => m.line === 0)).toBe(true); // all anchor to the heading
+  });
+
+  it('handles a block whose marker run reaches end-of-file', () => {
+    const text = ['para', serializeReviewMarker('a', 'only')].join('\n'); // marker on the last line
+    expect(markerAppendLine(text, 0)).toBe(2); // just past the run (end of file)
+  });
+});
+
 describe('isReviewMarkerLine / isEligibleReviewPath', () => {
   it('detects marker lines', () => {
     expect(isReviewMarkerLine('  <!-- REVIEW(@a): x -->')).toBe(true);
diff --git a/packages/core/src/review-markers.ts b/packages/core/src/review-markers.ts
index 46eac3e92..064112536 100644
--- a/packages/core/src/review-markers.ts
+++ b/packages/core/src/review-markers.ts
@@ -90,6 +90,24 @@ export function markerInsertionLine(annotatedLine: number): number {
   return annotatedLine + 1;
 }
 
+/**
+ * The file line a new marker should be written to so it **appends below** any markers already
+ * stacked on `annotatedLine` — i.e. the line after the contiguous run of REVIEW markers that
+ * immediately follows the annotated line. With no existing markers this is just
+ * `markerInsertionLine(annotatedLine)`. Because markers render in file order (a run all anchors to
+ * the block above it), appending after the run makes the newest comment the **last** card in the
+ * block's thread. Shared in core so any host that appends to a thread agrees on the convention.
+ * Pure (operates on the document text), so it is unit-testable without a host.
+ */
+export function markerAppendLine(text: string, annotatedLine: number): number {
+  const lines = text.split('\n');
+  let insertAt = markerInsertionLine(annotatedLine);
+  while (insertAt < lines.length && isReviewMarkerLine(lines[insertAt])) {
+    insertAt++;
+  }
+  return insertAt;
+}
+
 /**
  * Parse all review markers out of `text` into `ReviewMarker`s, mapping each to
  * the 0-based logical line it annotates: the nearest line ABOVE the marker that
diff --git a/packages/vscode/src/markdown-preview/preview-provider.ts b/packages/vscode/src/markdown-preview/preview-provider.ts
index 88c6b8574..4710c761b 100644
--- a/packages/vscode/src/markdown-preview/preview-provider.ts
+++ b/packages/vscode/src/markdown-preview/preview-provider.ts
@@ -10,10 +10,11 @@
  * which is exactly what the artifact-canvas package is for.
  *
  * Architecture (host side of the package's adapter contract):
- * - The host reads `document.getText()`, hides markers for rendering via the
- *   shared `stripMarkersForRender` (the #1036 fix), and parses markers via
- *   `parseReviewMarkers`. Both come from `@cluesmith/codev-core/review-markers`,
- *   so this surface and the editor Comments-API path write/parse identical bytes.
+ * - The host posts the **raw** document text and parses markers via `parseReviewMarkers`
+ *   (from `@cluesmith/codev-core/review-markers`); the canvas renderer strips full-line
+ *   REVIEW/comment lines itself before block parsing (the #1036/#1042 fix), so the host no
+ *   longer pre-hides them. The shared core codec means this surface and the editor
+ *   Comments-API path write/parse identical bytes.
  * - Content + markers are pushed into the webview, which mounts `<ArtifactCanvas>`
  *   (see `webview/main.ts`). The canvas's inline composer (#1107) collects the
  *   comment body and emits an `addComment` intent carrying `{ line, text }`; the
@@ -29,7 +30,7 @@
 import * as vscode from 'vscode';
 import {
   serializeReviewMarker,
-  markerInsertionLine,
+  markerAppendLine,
   parseReviewMarkers,
 } from '@cluesmith/codev-core/review-markers';
 import { renderMarkdownPreviewHtml } from './preview-template.js';
@@ -107,9 +108,12 @@ export class MarkdownPreviewProvider implements vscode.CustomTextEditorProvider
         ? (document.lineAt(line).text.match(/^\s*/)?.[0] ?? '')
         : '';
     const edit = new vscode.WorkspaceEdit();
+    // Append below any markers already stacked on this block so the new comment lands where the
+    // inline composer appeared (in-flow below the existing cards), not at the top of the thread
+    // (#1107). markerInsertionLine alone (line+1) would prepend ahead of an existing run.
     edit.insert(
       document.uri,
-      new vscode.Position(markerInsertionLine(line), 0),
+      new vscode.Position(markerAppendLine(document.getText(), line), 0),
       serializeReviewMarker(author, text, indent) + '\n',
     );
     await vscode.workspace.applyEdit(edit);

From b12642134e2aeaccffcb1b245cd1d6730677df17 Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Tue, 30 Jun 2026 10:52:09 +1000
Subject: [PATCH 22/23] [PIR #1107] Document consultation finding + fix in
 review; update thread

---
 .../1107-preview-inline-comment-composer.md   | 34 +++++++++++++++++++
 codev/state/pir-1107_thread.md                | 13 +++++++
 2 files changed, 47 insertions(+)

diff --git a/codev/reviews/1107-preview-inline-comment-composer.md b/codev/reviews/1107-preview-inline-comment-composer.md
index 1790ae547..85ba090e4 100644
--- a/codev/reviews/1107-preview-inline-comment-composer.md
+++ b/codev/reviews/1107-preview-inline-comment-composer.md
@@ -27,6 +27,8 @@ unchanged (multi-line input collapses to single-line at write time, as before).
 - `packages/artifact-canvas/src/renderer/MarkdownView.tsx` (+7 / −3) — JSX conversion
 - `packages/artifact-canvas/src/styles/default-theme.css` (+58 / −0) — composer styling
 - `packages/artifact-canvas/examples/main.tsx` (+4 / −4) — example uses the new seam
+- `packages/core/src/review-markers.ts` (+19 / −0) — new `markerAppendLine` codec helper (append-below-thread)
+- `packages/core/src/__tests__/review-markers.test.ts` (+27 / −0) — `markerAppendLine` regression tests
 - `packages/vscode/src/markdown-preview/messages.ts` (+24 / −0) — new named webview↔host protocol types
 - `packages/vscode/src/markdown-preview/preview-provider.ts` (+~22 / −~15) — drop `showInputBox`; write from posted text; use protocol types
 - `packages/vscode/src/markdown-preview/webview/main.ts` (+~9 / −~6) — post `{line, text}`; use protocol types
@@ -77,6 +79,38 @@ the component into it, with an idempotent injection effect to avoid a
 **HOT — no `lessons-critical.md` change.** No behavior-changing cross-cutting rule
 emerged that warrants displacing a capped hot lesson.
 
+## Consultation Findings (PIR single advisory pass)
+
+The PR-stage consultation (claude + codex, `type=impl`, `max_iterations: 1`) returned:
+**claude = APPROVE (HIGH)**, **codex = REQUEST_CHANGES (HIGH)**.
+
+**Codex finding (real defect — FIXED in `4a…` + regression test):** the host inserted
+the new marker at `markerInsertionLine(line)` (line+1), which *prepends* ahead of any
+markers already stacked on the block — so for a block with existing comments, the new
+card rendered at the **top** of the thread, while the inline composer had appeared
+**below** the existing cards. Visual position ≠ result, and it violated the approved
+plan's append-to-thread behavior.
+- **Fix:** added `markerAppendLine(text, annotatedLine)` to `@cluesmith/codev-core/review-markers`
+  (returns the line after the contiguous marker run; falls back to `markerInsertionLine`
+  when the block has none). `preview-provider.ts` now inserts there, so the new comment
+  lands where the composer was (newest-last).
+- **Regression test:** `packages/core/src/__tests__/review-markers.test.ts` — `markerAppendLine`
+  appends after a 2-marker run (asserts file/render order `first, second, third`, all
+  anchored to the block) and handles end-of-file; without the fix the new comment would
+  be first.
+- **Codex's other two points:** (a) the stacked-comment path lacked coverage — addressed
+  by the regression test above; (b) the stale `stripMarkersForRender` header comment in
+  `preview-provider.ts` — corrected to describe the raw-text + renderer-strips flow.
+
+**⚠️ Escalation for the `pr` gate (PIR will not re-review this):** the fix changes the
+canvas surface to append-below (newest-last). The **editor** Comments-API path
+(`comments/plan-review.ts:171`) still inserts at `markerInsertionLine(line)` (newest-first),
+so the two authoring surfaces now stack a *new* comment on an already-commented block in
+different order. Aligning the editor path is **out of scope for #1107** (the issue lists
+it as out of scope) and is a one-line change best done deliberately — recommend a
+follow-up issue. Please confirm the append-below choice (it matches this PR's approved
+plan and conventional thread UX) at the gate.
+
 ## Things to Look At During PR Review
 
 - **`ArtifactCanvas.tsx` placeholder-injection effect** — the trickiest part. It
diff --git a/codev/state/pir-1107_thread.md b/codev/state/pir-1107_thread.md
index 9d2149f57..c37178957 100644
--- a/codev/state/pir-1107_thread.md
+++ b/codev/state/pir-1107_thread.md
@@ -107,3 +107,16 @@ At / How to Test). Governance routing (Spec 987 cold tier):
   the idempotent-injection guard. No hot lessons-critical change.
 Next: open PR with review as body, `porch done --pr`, then `porch done` → single CMAP-2 advisory
 pass → pr gate.
+
+### Consultation results + fix (2026-06-30)
+PR #1121 opened. 2-way CMAP-2 (claude+codex, single pass): claude=APPROVE(HIGH),
+codex=REQUEST_CHANGES(HIGH). Verified all 3 codex claims against code — all valid:
+1. REAL DEFECT: host inserted at markerInsertionLine (line+1) = prepend, so a new comment on a
+   block with existing markers rendered at TOP of the stack while the composer appeared BELOW.
+   Fixed: added core `markerAppendLine` (insert after the contiguous marker run = newest-last,
+   matching composer position + approved plan). Regression test in core review-markers.test.ts.
+2. Test gap (stacked path) → covered by the new core test.
+3. Stale `stripMarkersForRender` header comment → corrected to raw-text+renderer-strips.
+Escalating at pr gate: editor path (plan-review.ts:171) still prepends (out of scope #1107) →
+recommend follow-up issue to align. core build+test ✓ (32), vscode check-types/esbuild/lint/
+test:unit ✓ (516). PIR single-pass: no re-consult; human verifies at pr gate.

From cf3617aae138bc567143ac3769dacb3572d79651 Mon Sep 17 00:00:00 2001
From: Amr Elsayed <amrmelsayed@users.noreply.github.com>
Date: Tue, 30 Jun 2026 10:53:16 +1000
Subject: [PATCH 23/23] chore(porch): 1107 pr gate-requested

---
 .../projects/1107-vscode-replace-top-of-window-q/status.yaml  | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/codev/projects/1107-vscode-replace-top-of-window-q/status.yaml b/codev/projects/1107-vscode-replace-top-of-window-q/status.yaml
index d25f9986b..e8088efab 100644
--- a/codev/projects/1107-vscode-replace-top-of-window-q/status.yaml
+++ b/codev/projects/1107-vscode-replace-top-of-window-q/status.yaml
@@ -15,13 +15,15 @@ gates:
     approved_at: '2026-06-30T00:39:35.411Z'
   pr:
     status: pending
+    requested_at: '2026-06-30T00:53:16.329Z'
 iteration: 1
 build_complete: true
 history: []
 started_at: '2026-06-29T23:23:50.850Z'
-updated_at: '2026-06-30T00:44:42.310Z'
+updated_at: '2026-06-30T00:53:16.329Z'
 pr_history:
   - phase: review
     pr_number: 1121
     branch: builder/pir-1107
     created_at: '2026-06-30T00:44:34.712Z'
+pr_ready_for_human: true