Widget: page-level / unanchored comments (start a thread without a pin)

[MateuszPaulski]

Start a thread without placing a pin — leave general feedback about the page (or the review as a whole) instead of having to click an element first. Today starting a thread is element-anchored: CreateThreadBody mandates anchor (packages/core/src/contract/requests.ts:22), and the create flow begins with a click that captures the element fingerprint.

Status: parking lot — page-scoped first cut; global/cross-page threads can follow.

Shape. Most of the infrastructure already exists:

• Display is solved. Threads with no live pin already render as the detached ThreadCard in the panel (the M8 orphan path). A pinless thread is essentially one born detached rather than orphaned by a DOM change.
• The data model anticipates it. The documented seam is scope: "page" | "global" with pageKey: null "allowed for future global threads" (docs/architecture.md), though the live zod still hard-codes scope: z.literal('page') (packages/core/src/schemas/thread.ts).

Real gaps:

1. Make anchor optional in CreateThreadBody and pick the model shape — likely a distinct state, not reusing orphaned (orphaned means lost its anchor, not never had one; conflating them muddies the self-heal/re-match policy). The contract is TDD-first (ADR-0010): failing core/adapter tests before code.
2. A create affordance that isn't an element click — e.g. a "comment on this page" button in the widget chrome that opens the composer straight into the panel.
3. Page vs. global scope. The smaller first cut is page-scoped (anchor omitted but pageKey set, so it shows in this page's panel and not others); truly cross-page/global threads (scope: "global", pageKey: null) follow.

Effort: medium — core schema + HTTP contract, both adapters' create/list, and a composer entry point. No anchoring/re-match work, since these threads opt out of that machinery. Worth an ADR note when picked up: it widens a public request shape and adds an anchor state.

[MateuszPaulski]

[MateuszPaulski]

Spec: Widget — page-level / unanchored comments (start a thread without a pin)

Problem

Starting a thread is always element-anchored: CreateThreadBody mandates anchor, and the create flow begins with a page click that captures an element fingerprint. Reviewers can't leave general feedback about a page without first picking an element. We want a "comment on this page" path that creates a pinless, page-scoped thread.

Approach

Make anchor optional across the contract and persisted model, and introduce a distinct anchorState value 'unanchored' for threads born without a pin. We deliberately do not reuse 'orphaned' — that means lost its anchor and drives the self-heal / "anchor lost" warning; conflating the two would mis-trigger re-match and the panel warning. Pinless threads opt out of the anchoring machinery entirely (never matched, never re-matched, never reported orphan), so there is zero new anchoring work.

The create affordance reuses the existing Composer (mode="newThread") and the existing detached/orphan display path (M8): a thread with no live pin already renders as a panel row and, when opened, as the DetachedThread card. Scope stays page-scoped: scope: z.literal('page') is untouched and pageKey is still set, so a page comment shows in that page's panel and nowhere else.

Rejected: reusing 'orphaned' (muddies re-match/self-heal policy and trips the "anchor lost" warning). Deferred: truly global / cross-page threads (scope:'global', pageKey:null) — a separate follow-up.

Implementation plan

Backend is TDD (ADR-0010): failing core/server/adapter-contract tests first, then implement.

Core contract/schema (@airnauts/airside-core)

• packages/core/src/schemas/thread.ts — AnchorState enum gains 'unanchored' → z.enum(['anchored','orphaned','unanchored']). In ThreadBase, anchor: Anchor → anchor: Anchor.optional() (one edit covers Thread, ThreadListItem, and both *View extends). Invariant (documented, not enforced by refine for pre-1.0 simplicity): anchor present iff anchorState ∈ {anchored, orphaned}; absent iff 'unanchored'.
• packages/core/src/contract/requests.ts — CreateThreadBody.anchor → Anchor.optional().
• OpenAPI (contract/openapi.ts) is generated from these zod schemas; the dist/openapi.json artifact regenerates at build — no manual edit.

Server (@airnauts/airside-server)

• packages/server/src/repository/types.ts — NewThread: anchor?: Anchor; anchorState: 'anchored' | 'unanchored' (orphaned is never created, only reached via updateAnchor).
• packages/server/src/use-cases/create-thread.ts — derive: const anchored = body.anchor !== undefined; pass anchor: body.anchor (may be undefined) and anchorState: anchored ? 'anchored' : 'unanchored'.
• packages/server/src/use-cases/refresh-anchor.ts / updateAnchor — non-blocking note: a refresh against an 'unanchored' thread is incoherent (no base anchor to heal). The client guard below means this is never called for page threads; an explicit server guard is out of scope for this cut (call it out, don't silently skip).

Adapters (create/list/get round-trip)

• packages/adapter-memory/src/in-memory.ts — clone(undefined) is fine; no change beyond types compiling.
• packages/adapter-mongo/src/repository.ts — spread-omit anchor when absent (mirror the existing pageTitle/selectionLost pattern, lines 91/95) rather than writing anchor: undefined.
• packages/adapter-postgres/src/repository.ts — JSON.stringify(thread) already drops undefined, so the jsonb doc round-trips; confirm in the contract test, no code change expected.

Client / widget (@airnauts/airside-client)

• packages/client/src/anchor/runtime.ts — at list ingestion, skip items with no anchor (equivalently anchorState === 'unanchored') so they never enter the retained set: no match attempt (avoids the rematch(undefined, root) crash), no orphan report, no placement. rematchAll/reposition only map over retained, so they're then safe.
• Create affordance — recommended (c): a "Comment on this page" button in the panel list header (packages/client/src/panel/PanelListView.tsx) that reveals an inline Composer (mode="newThread") at the top of the list. On submit, create with no anchor, then panel.openDetail(id) so the new thread shows in the panel detail (not as a floating DetachedThread card).
• Extract a shared create path to avoid duplicating MarkerLayer.createThread's side-effect sequence (createThread → CLEAR_DRAFT → runtime.refresh() → DETAIL_LOADED → OPEN → controller.notifyThreadCreated()). New hook packages/client/src/threads/useCreateThread.ts taking an optional anchor: the pin path (DraftPopover/MarkerLayer) passes the captured anchor; the page path passes undefined (and skips CLEAR_DRAFT/pin-focus, uses panel.openDetail). provenance + buildCaptureContext() are wired only into MarkerLayer today; host the hook (or thread provenance from app/app.tsx) so the panel consumer gets them too.
• packages/client/src/panel/PanelRow.tsx — 'unanchored' naturally does not trip the === 'orphaned' "anchor lost" warning. Optional: a subtle "page comment" label — out of scope for this cut.

Testing (TDD-first for backend)

• Core (schemas.test.ts, contract tests): CreateThreadBody parses with anchor omitted; Thread/ThreadListItem parse with anchorState:'unanchored' and no anchor; existing anchored fixtures still parse (back-compat).
• Server (create-thread use-case test): anchor present → anchorState:'anchored' + anchor persisted; anchor omitted → anchorState:'unanchored' + no anchor.
• Adapter contract (packages/test-support/src/repository-contract.ts + fixtures.ts): add a pinless create → getThread → listThreads round-trip (anchor absent survives, anchorState:'unanchored'). Extend fixtures with a makePageNewThread / makeAnchor-omitting helper. This one suite auto-covers memory, mongo, and postgres.
• Client: runtime test — an 'unanchored' list item is never placed and never triggers a refreshAnchor call (no crash). Panel test — the new "Comment on this page" composer submits with no anchor and opens the thread in the panel detail; PanelRow shows no "anchor lost" badge for 'unanchored'.
• Verify: pnpm test green across the changed packages, pnpm lint (biome) clean, OpenAPI regenerates at build.

Changeset

Minor bump (fixed group, pre-1.0; optional-field widening + additive enum value are non-breaking) covering airside-core, airside-server, airside-client, and the three adapters whose create paths/handling change (adapter-memory, adapter-mongo, adapter-postgres). One user-facing summary: "Start page-level comments without placing a pin."

Risks / open questions

• Create-affordance surface (owner decision). Recommended (c) panel-header button + inline composer — most literal to "into the panel," moderate wiring (provenance/captureContext must reach the panel via the shared hook). Alternatives: (a) Launcher-pill button opening a launcher-anchored popover composer — least wiring, reuses the MarkerLayer path almost verbatim, but the composer isn't visually "in the panel"; (b) Launcher button that opens the panel + inline composer — most wiring. All three end with the thread surfacing in the panel.
• No on-page pin for page comments (intended): a page comment is reachable only via the panel (and the detail view when opened), never as an on-page marker. Consistent with "display already solved," but a deliberate v1 limitation.
• Worth an ADR note when picked up: this widens a public request shape (CreateThreadBody.anchor optional) and adds an anchorState value — update docs/architecture.md §5 (anchorState: "anchored" | "orphaned" | "unanchored").

Out of scope

• Global / cross-page threads (scope:'global', pageKey:null) — a follow-up; scope stays z.literal('page').
• Any anchoring / re-match / self-heal changes (page comments opt out entirely).
• A server-side guard rejecting refresh-anchor on an 'unanchored' thread (client never calls it for page threads).
• An on-page indicator / pin for page comments and a "page comment" panel-row label.

---

🤖 Reply /approve to build, /revise <notes> to change it, or /stop to cancel.

[MateuszPaulski]

/approve