@rose42/t3-feedback 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rose42
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,516 @@
+# @rose42/t3-feedback
+
+> **DEV-only community tool.** In development, capture a screenshot + note from your
+> running app and send it into a [T3 Code](https://t3.codes) thread — without leaving
+> the page. Not affiliated with T3 / pingdotgg.
+
+**Status:** unofficial. The bridge talks to T3 via the `t3` CLI (`auth session` /
+`auth pairing`), `/.well-known/t3/environment`, websocket tickets, and private WS
+RPCs (e.g. thread create / settle). Those surfaces can change without notice; pin
+a known-good T3 / `t3` CLI version and expect breakage across upgrades. There is no
+supported public “ingest feedback” API yet.
+
+**Never for production.** Vite integration is serve-only (`apply: "serve"`). Next
+(and any custom host) must mount the bridge + client in development only.
+
+Wire it as a Vite plugin (`/plugin`) or, for Next and other hosts, the same overlay
+(`/client`) plus a Node Fetch bridge (`/bridge`). Headless envelopes and silent
+capture helpers come from [`@rose42/feedback-capture`](https://www.npmjs.com/package/@rose42/feedback-capture)
+(UI-free); this package owns the overlay UI, host plugin fields (`label` /
+`reportTypes` / `ui` / `shortcuts`), and the T3 bridge.
+
+### Core loop
+
+1. In DEV, open the panel (shortcut or FAB), optionally pick an element / crop a shot.
+2. Send → **New** thread or **Continue** an existing one.
+3. Toast offers **Open in T3** (pairing handoff); working threads stay on the activity chip until they settle.
+
+By default the panel offers **New** and a play-icon **Continue** control (thread title excerpt) as the send actions (soft-defaults Continue when the last
+send on this route was the same report type within ~15 minutes). A chevron opens a searchable list of project threads from T3 (search
+prefilled with the current pathname). From the comment field: **Ctrl/⌘+Enter** submits the soft-default,
+**Ctrl/⌘+Shift+Enter** always New, **Alt+Enter** always Continue.
+
+After a successful send the compose panel closes immediately. A short toast offers **Open in T3**, and
+working threads stay on the FAB as a badge + activity popover (Open / Continue / Settle / Dismiss) until they
+settle (live probe when available, **Settle** via `thread.settle`, local dismiss, or ~45 minute TTL). The activity chip stays visible even
+when the normal FAB is mobile-only or hidden.
+
+**Open in T3** mints a one-time pairing link (`/pair#token=…`), opens it in a named window so the browser
+session cookie is established, then navigates that window to the thread. Browser links use `openOrigin`
+(default: same as `origin`, typically `localhost`) so host Port-forward cookies match.
+
+In-progress compose state (comment, screenshots, picked element) is saved to `sessionStorage` and
+restored after a page reload; if the panel was open, it reopens automatically. **Cancel** (panel ×)
+discards the draft; Esc or clicking outside closes and keeps it. A successful send also clears the
+draft.
+
+## Install
+
+**Recommended (hybrid init):** from your app root, detect Next / Vite / Node, confirm,
+install this package if missing (npm or pnpm), then wire connector files:
+
+```bash
+# one-shot (downloads the package, runs its `t3-feedback` bin):
+pnpm dlx @rose42/t3-feedback init
+npx -p @rose42/t3-feedback t3-feedback init
+
+# after it is already a dependency:
+pnpm exec t3-feedback init
+npx t3-feedback init
+```
+
+`init` prints a plan and asks before writing. Useful flags: `--yes`, `--dry-run`,
+`--no-install`, `--host next|vite|node`.
+
+Manual install only:
+
+```bash
+pnpm add -D @rose42/t3-feedback
+# or: npm i -D @rose42/t3-feedback
+```
+
+Until published, develop against a sibling clone via the
+[devcontainer](https://gitlab.com/rose42/t3-feedback/-/blob/main/docs/devcontainer.md)
+(local symlink of a sibling [`feedback-capture`](https://gitlab.com/rose42/feedback-capture) clone).
+`package.json` stays on the registry version (`0.1.0`).
+
+Then from a consumer app that depends on this package via `file:` / workspace link:
+
+```bash
+pnpm exec t3-feedback init --no-install
+```
+
+See [docs/devcontainer.md](https://gitlab.com/rose42/t3-feedback/-/blob/main/docs/devcontainer.md)
+for the local DX container (`T3CODE_PORT`, default **3775** — [change in
+`.devcontainer/devcontainer.json`](https://gitlab.com/rose42/t3-feedback/-/blob/main/.devcontainer/devcontainer.json),
+sibling bind-mount).
+
+## Usage
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { t3FeedbackPlugin } from "@rose42/t3-feedback/plugin";
+
+export default defineConfig({
+  plugins: [
+    t3FeedbackPlugin({
+      workspaceRootHints: [process.cwd()],
+      // injectClient: true by default
+      // shortcut: { key: "f" }, // bare F; omitted mods are false
+      // // or { key: "f", mod: true, shift: true } for Ctrl/⌘+Shift+F
+      // threadReuse: "ask", // or "session-route" | "never"
+      // threadTitle: "Checkout", // optional title prefix
+      // origin: "http://localhost:3773",
+    }),
+  ],
+});
+```
+
+In DEV, open the app and press **Ctrl/⌘+Shift+F** (or click the ✎ FAB),
+**Ctrl/⌘+Shift+E** to pick an element, or **Ctrl/⌘+Shift+S** to capture a
+screenshot. No `main.tsx` import is required when `injectClient` is left on.
+
+**Pick element** (button or shortcut) stores a DOM target. Component source is
+best-effort via `pick.sourceFramework` (`"auto"` default — try qwik/locator/next/react/vue/svelte;
+pin `"next"` on Next.js hosts so Turbopack `_debugStack` frames skip `react-jsx-runtime`);
+or pin one / `"none"`). By default
+(`pick.afterPick: "crop"`) it then captures the tab and silently crops to the
+element — no crop overlay. Configure with:
+
+```ts
+t3FeedbackPlugin({
+  // Open panel
+  shortcut: { key: "f", mod: true, shift: true },
+  pick: {
+    // Start picking immediately (default Ctrl/⌘+Shift+E). `false` to disable.
+    shortcut: { key: "e", mod: true, shift: true },
+    // After pick: "crop" (default) | "capture" | "none"
+    afterPick: "crop",
+    cropPaddingPx: 12,
+    // Component source: "auto" | "react" | "vue" | "svelte" | "qwik" | "locator" | "none"
+    sourceFramework: "auto",
+    // Clickable path → open in IDE via Vite `/__open-in-editor` (default: on).
+    // openInEditor: false,
+    // openInEditor: { urlTemplate: "vscode://file/{file}:{line}:{column}" },
+    // Include truncated innerHTML in the agent message (default: false)
+    includeInnerHTML: false,
+    // Curated getComputedStyle: "none" | "layout" | "computed"
+    styles: "none",
+  },
+  screenshot: {
+    // Capture / Change region: "ui" (default — crop on demand from thumbs;
+    // Capture focuses the new crop control so Enter opens it) | "auto" | "none"
+    crop: "ui",
+    // Max images per report (capture + paste + burst). Default 5 (1–10).
+    // maxImages: 5,
+  },
+  // Record / burst shortcut (default Ctrl/⌘+Shift+R). `false` to disable.
+  // record: { shortcut: { key: "r", mod: true, shift: true } },
+  // Built-in capture plugins (omit = all four). Comment is always collected.
+  // activePlugins: ["pageContext", "consoleLogs", "screenshot", "elementTarget"],
+  // pluginOptions: { consoleLogs: { maxEntries: 200 } },
+  // Vite-resolved module paths — default export is a FeedbackCapturePlugin (or array/factory).
+  // customPlugins: ["./src/dev/routePlugin.ts"],
+});
+```
+
+Those `pick.includeInnerHTML` / `pick.styles` values are **panel defaults**. The overlay
+also shows per-session toggles (innerHTML checkbox + styles segmented control) that override them
+and persist in `sessionStorage` for the tab.
+
+### Capture plugins
+
+| Built-in        | Role                                                                  |
+| --------------- | --------------------------------------------------------------------- |
+| `pageContext`   | URL / viewport / locale on the envelope                               |
+| `consoleLogs`   | Ring-buffered console output (`pluginOptions.consoleLogs.maxEntries`) |
+| `screenshot`    | Capture / paste / record gallery → `envelope.screenshot`              |
+| `elementTarget` | Pick-element UI → `envelope.elementTarget`                            |
+
+Omit `activePlugins` to keep today’s defaults (all four). An explicit list enables only those
+ids; the comment field is always collected. Custom plugins cannot be JSON-serialized into the
+injected client — pass Vite-resolved module ids/paths via `customPlugins` instead.
+
+**Report-type profiles.** Panel hints come from `buildReportTypeHint` using the active
+builtins (`pageContext`, `consoleLogs`, screenshot attachments) and the same
+`reportTypes` / page-context field filtering as collect. Markdown formatting just
+renders what landed in the envelope. `screenshot` / `elementTarget` stay available for
+every type when listed in `activePlugins`. Customs can set their own `reportTypes` the
+same way. Override a hint via `copy.reportTypeBugHint` / `reportTypeFeedbackHint` /
+`reportTypeSuggestionHint` if needed.
+
+```ts
+// src/dev/routePlugin.ts
+import type { FeedbackCapturePluginWithUi } from "@rose42/t3-feedback/client";
+
+export default {
+  id: "route",
+  collect: () => window.location.pathname,
+} satisfies FeedbackCapturePluginWithUi;
+```
+
+```ts
+t3FeedbackPlugin({
+  activePlugins: ["pageContext", "consoleLogs", "screenshot", "elementTarget"],
+  customPlugins: ["./src/dev/routePlugin.ts"],
+});
+```
+
+Each entry’s **default export** (or plugin-shaped named exports) may be a plugin, an array, or a
+zero-arg factory. Relative paths resolve against the Vite project root; bare package ids are left
+as import specifiers.
+
+Optional **host** plugin fields on `FeedbackCapturePluginWithUi` (not on core
+`@rose42/feedback-capture` plugins):
+
+| Field         | Role                                                                                           |
+| ------------- | ---------------------------------------------------------------------------------------------- |
+| `label`       | Auto-register a live preview chip in the `beforeComment` slot (skipped when `ui` is set)       |
+| `reportTypes` | Only collect when the selected type is in the list (`"bug"` \| `"feedback"` \| `"suggestion"`) |
+| `ui`          | Own panel UI: one contribution or an array, each targeting a shared slot                       |
+| `shortcuts`   | Own global keyboard chords (one or an array); registered for the mount lifetime                |
+
+**Image attachments.** Any plugin may `collect()` a value shaped as
+`{ attachments: [{ dataUrl, name?, mimeType? }] }`. Those images are merged with the built-in
+`screenshot` gallery (deduped by `dataUrl`) and uploaded as T3 message attachments. Use
+`ctx.media` from UI / shortcut host context for viewport capture, crop, clipboard image, and
+frame burst helpers (the feedback root is hidden automatically during capture).
+
+**Markdown formatting.** Custom collect values are dumped generically unless you return a hint
+shape: `{ label, value }` → `**label:** value`, `{ heading, body }` → a `###` section, or
+`{ markdown }` → raw markdown. Reserved built-in keys keep their first-class formatting.
+
+```ts
+import type { FeedbackCapturePluginWithUi } from "@rose42/t3-feedback/client";
+
+let lastShot: string | undefined;
+
+export default {
+  id: "routeShot",
+  collect: () =>
+    lastShot ? { attachments: [{ dataUrl: lastShot, name: "route.png" }] } : undefined,
+  ui: {
+    id: "routeShot-ui",
+    slot: "actionsTools",
+    mount(container, ctx) {
+      const btn = document.createElement("button");
+      btn.type = "button";
+      btn.textContent = "Route shot";
+      btn.onclick = async () => {
+        const url = await ctx.media.captureScreenshot();
+        if (url) lastShot = url;
+        ctx.persistDraft();
+      };
+      container.append(btn);
+    },
+  },
+} satisfies FeedbackCapturePluginWithUi;
+```
+
+**Shell vs plugins.** The host owns only the FAB (open / activity / toast) and the send-action
+cluster (New / Continue / thread picker / submit, plus comment-field send keydowns and the
+open-panel chord). Everything else in the panel — report type, comment field, element target,
+screenshot gallery, collect-only builtins, and customs — is a capture plugin on the same
+`ui` / `shortcuts` / `collect` surface.
+
+Shared slots: `beforeComment`, `comment`, `attachments`, `actionsTools`.
+
+```ts
+import type { FeedbackCapturePluginWithUi } from "@rose42/t3-feedback/client";
+
+export default {
+  id: "documentTitle",
+  label: "Document title",
+  reportTypes: ["feedback"],
+  collect: () => document.title.trim() || undefined,
+} satisfies FeedbackCapturePluginWithUi;
+```
+
+Register interactive UI into a slot (instead of / in addition to `label`):
+
+```ts
+import type { FeedbackCapturePluginWithUi } from "@rose42/t3-feedback/client";
+
+export default {
+  id: "routeHint",
+  collect: () => window.location.pathname,
+  ui: {
+    id: "routeHint-panel",
+    slot: "beforeComment",
+    mount(container) {
+      const el = document.createElement("div");
+      el.textContent = `Path: ${window.location.pathname}`;
+      container.append(el);
+    },
+  },
+  shortcuts: {
+    id: "routeHint-open",
+    shortcut: { key: "h", mod: true, shift: true },
+    run: ({ openPanel }) => openPanel(),
+  },
+} satisfies FeedbackCapturePluginWithUi;
+```
+
+Built-in pick / capture / record chords go through the same plugin shortcut registry as customs
+(first match wins). The shell only registers the open-panel chord. Built-in element, screenshot,
+comment, and report-type panels are slot contributions (element / screenshot gated by
+`activePlugins`).
+
+### Open from your UI
+
+With the client injected (default), open or close the panel from app code with
+zero imports — useful for a touchscreen menu item:
+
+```ts
+if (import.meta.env.DEV) {
+  window.dispatchEvent(new CustomEvent("t3-feedback:open"));
+  // window.dispatchEvent(new CustomEvent("t3-feedback:close"));
+}
+```
+
+Optional typed helpers (tiny; does not pull the overlay/`/client` bundle):
+
+```ts
+import { openT3Feedback } from "@rose42/t3-feedback/controls";
+
+if (import.meta.env.DEV) {
+  openT3Feedback();
+}
+```
+
+Events are a no-op if the feedback client is not mounted.
+
+### Manual mount (advanced / no inject)
+
+Prefer `customPlugins` + inject when possible. For imperative mount (custom `transport`,
+`resolveSource`, or extra `plugins` instances):
+
+```ts
+// vite.config.ts
+t3FeedbackPlugin({ injectClient: false, workspaceRootHints: [process.cwd()] });
+```
+
+```ts
+// main.ts
+if (import.meta.env.DEV) {
+  void import("@rose42/t3-feedback/client").then(({ mountT3Feedback }) => {
+    const feedback = mountT3Feedback({
+      // activePlugins: ["pageContext", "screenshot"],
+      // plugins: [/* extra @rose42/feedback-capture plugins */],
+    });
+    // feedback.open() / feedback.pick() / feedback.capture() / feedback.record() / feedback.close() / feedback.unmount()
+  });
+}
+```
+
+### Next.js (DEV Route Handler + explicit mount)
+
+The Vite plugin cannot run under Next. Use the same `/client` overlay and the Node
+`/bridge` entry. **DEV only** — do not ship this route or client mount in production
+builds (see the status note at the top of this README).
+
+1. **Route Handler** — call `handleT3FeedbackRequest`. The handler itself
+   returns 404 unless `NODE_ENV === "development"` (keep the route out of
+   production bundles anyway):
+
+```ts
+// app/api/t3-feedback/[[...path]]/route.ts
+import { handleT3FeedbackRequest } from "@rose42/t3-feedback/bridge";
+
+const bridge = {
+  basePath: "/api/t3-feedback",
+  workspaceRootHints: [process.cwd()],
+};
+
+async function handle(request: Request) {
+  const response = await handleT3FeedbackRequest(request, bridge);
+  return response ?? new Response(null, { status: 404 });
+}
+
+export const GET = handle;
+export const POST = handle;
+```
+
+2. **Client mount** — DEV-only `"use client"` bootstrap that
+   `import()`s `@rose42/t3-feedback/client` and calls
+   `mountT3Feedback({ endpoint: "/api/t3-feedback", … })` (same options as the
+   Vite plugin’s client config). Open from the app with
+   `window.dispatchEvent(new CustomEvent("t3-feedback:open"))`.
+
+`vite` is an **optional** peer — Next hosts only need `/bridge` + `/client`.
+
+Fully custom UI: build an envelope with `@rose42/feedback-capture` and
+`POST /__t3-feedback` yourself (raw envelope, or
+`{ envelope, threadId? }` to reuse a thread); keep the Vite plugin for the T3
+bridge. After a successful send, the JSON body includes `openUrl` for an
+Open-in-T3 handoff (bare thread URL using the server's `environmentId` from
+`/.well-known/t3/environment`; the injected UI also calls
+`GET /__t3-feedback/open?threadId=` for a fresh `pairUrl` + `threadUrl`
+so pairing is automatic). Working-thread status can be polled via
+`GET /__t3-feedback/threads?ids=…` (returns `{ threads: [{ threadId, state }] }`
+with `state` of `working` | `settled` | `unknown`). Without `ids`, the same path
+lists the matched project’s threads for the continue picker
+(`{ threads: [{ threadId, title, state, updatedAt? }] }`). Activity **Settle** calls
+`POST /__t3-feedback/settle` with `{ threadIds }` to dispatch T3 `thread.settle`
+(returns `{ threads: [{ threadId, ok, skipped? }] }`). **Dismiss** / **Clear all**
+only clear the local activity list.
+
+## Options
+
+| Option               | Default                                      | Notes                                                                                                                                                                                                                                           |
+| -------------------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `origin`             | `http://localhost:3773`                      | Overridable via `T3_FEEDBACK_ORIGIN` / `T3_ORIGIN`                                                                                                                                                                                              |
+| `openOrigin`         | same as `origin`                             | Host-browser URL for Open-in-T3 (`T3_FEEDBACK_OPEN_ORIGIN`). Set explicitly in multi-container setups; do not point at another project's T3.                                                                                                    |
+| `threadReuse`        | `"ask"`                                      | `"ask"` replaces Send with New / ▶ {title} ▾: **Ctrl/⌘+Enter** soft-default, **Ctrl/⌘+Shift+Enter** New, **Alt+Enter** Continue; chevron lists project threads (search); `"session-route"` always reuses per pathname; `"never"` always creates |
+| `threadTitle`        | _(none)_                                     | Optional prefix for new thread titles (`Bug: path · comment`)                                                                                                                                                                                   |
+| `workspaceRootHints` | `[cwd]` (+ `T3_FEEDBACK_WORKSPACE_HINT`)     | Match T3 project by workspace path                                                                                                                                                                                                              |
+| `shortcut`           | _(omit for Ctrl/⌘+Shift+F)_                  | When set, omitted `mod`/`shift`/`alt` are `false` (e.g. `{ key: "f" }` = bare F). Bare keys skip editable fields; Ctrl/⌘+Shift+key still opens while typing                                                                                     |
+| `shortcutKey`        | _(deprecated)_                               | Key-only alias; prefer `shortcut.key`                                                                                                                                                                                                           |
+| `pick`               | Ctrl/⌘+Shift+E, `afterPick: "crop"`          | Pick shortcut (`false` to disable), after-pick capture/crop, padding; `openInEditor` (default on) makes resolved file paths clickable via Vite `/__open-in-editor` or a `urlTemplate`                                                           |
+| `screenshot`         | Ctrl/⌘+Shift+S, `crop: "ui"`, `maxImages: 5` | Capture shortcut (`false` to disable); crop `"ui"` (on-demand from thumbs) \| `"auto"` \| `"none"`; gallery cap                                                                                                                                 |
+| `record`             | Ctrl/⌘+Shift+R                               | Record / frame-burst shortcut (`false` to disable); gated with `screenshot` in `activePlugins`                                                                                                                                                  |
+| `activePlugins`      | all four built-ins                           | `pageContext` \| `consoleLogs` \| `screenshot` \| `elementTarget` — omit for defaults                                                                                                                                                           |
+| `pluginOptions`      | `consoleLogs.maxEntries: 200`                | Serializable options for selected built-ins                                                                                                                                                                                                     |
+| `customPlugins`      | `[]`                                         | Vite-resolved module paths/ids imported into the injected client                                                                                                                                                                                |
+| `injectClient`       | `true`                                       | HTML inject of the overlay                                                                                                                                                                                                                      |
+| `fab`                | mobile-only, bottom-right                    | FAB visibility / position / size                                                                                                                                                                                                                |
+| `reportTypeGlyph`    | `"icon"`                                     | `"icon"` (SVG + textual titles), `"emoji"`, or a map `{ Bug, Feedback, Suggestion }` — emoji/map also prefix new chat names                                                                                                                     |
+| `version`            | _(none)_                                     | App version on bug/feedback reports; DEV also attaches HMR `#n`                                                                                                                                                                                 |
+
+## Environment
+
+| Variable                           | Role                                                                                      |
+| ---------------------------------- | ----------------------------------------------------------------------------------------- |
+| `T3_FEEDBACK_ORIGIN` / `T3_ORIGIN` | T3 HTTP origin                                                                            |
+| `T3_FEEDBACK_OPEN_ORIGIN`          | Browser origin for Open-in-T3 (default: same as `T3_FEEDBACK_ORIGIN`)                     |
+| `T3_FEEDBACK_TOKEN`                | Pre-issued bearer (skips `t3 auth session issue`)                                         |
+| `T3_FEEDBACK_WORKSPACE_HINT`       | Extra workspace path hint                                                                 |
+| `LAUNCH_EDITOR`                    | Editor binary for Vite `/__open-in-editor` (e.g. `cursor`, `code`) when auto-detect fails |
+
+When the feedback plugin runs in a **different** container/project than this one, point
+`T3_FEEDBACK_ORIGIN` at **that** project's T3 (`http://localhost:<its-port>` or an
+in-container hostname), and set `T3_FEEDBACK_OPEN_ORIGIN` to the host Port-forward URL for
+the **same** port (`http://localhost:<its-port>`) when they differ. Unique host ports per
+container avoid opening the wrong environment (check the Vite log line
+`[t3-feedback] T3 environment … (label)`).
+
+**Runtime prerequisites:** T3 Code running, and either `t3` on `PATH` or
+`T3_FEEDBACK_TOKEN` set. Browser needs `getDisplayMedia` (paste image works as fallback).
+
+When element pick resolves a component file, the ELEMENT chip path is a link that
+opens the IDE. Default is Vite’s `/__open-in-editor` (same as the error overlay) —
+that only works when the browser and Vite share a machine that can launch an
+editor (`LAUNCH_EDITOR=cursor` or `code` if auto-detect fails).
+
+When the **browser is on the host** and Vite runs in a **container/remote**, use a
+protocol URL instead so the OS / Cursor handles the open:
+
+```ts
+t3FeedbackPlugin({
+  pick: {
+    openInEditor: {
+      // `{file}` is whatever the sourcemap returns (often relative). Prefix with
+      // an absolute project root when your scheme requires absolute paths.
+      urlTemplate: `cursor://file${process.cwd()}/{file}:{line}:{column}`,
+    },
+  },
+});
+```
+
+With `urlTemplate`, the chip renders a real `<a href>` (not a fetch to Vite).
+`vscode://file/…` also works if that scheme is bound to your editor.
+
+## Package scripts
+
+```bash
+pnpm install
+pnpm typecheck
+pnpm lint
+pnpm format:check
+pnpm test
+pnpm build
+```
+
+Watch `dist/` while developing against a consumer:
+
+```bash
+pnpm dev
+```
+
+## Release
+
+Releases are driven by **version tags** (`vX.Y.Z`). Pushing a tag runs CI: verify → GitLab Release (dist tarball in the package registry) → publish to public npm.
+
+CI installs `@rose42/feedback-capture@0.1.0` from npm. Local/devcontainer work
+symlinks a sibling [`feedback-capture`](https://gitlab.com/rose42/feedback-capture) clone
+into `node_modules` without changing the declared dependency.
+
+### One-time npm + GitLab setup
+
+1. Create or join the **`rose42`** org on [npmjs.com](https://www.npmjs.com) with permission to publish `@rose42/*`.
+2. Create an npm **Automation** (or granular) access token with publish rights for `@rose42/t3-feedback` (or the whole `@rose42` org).
+3. In GitLab: **Settings → CI/CD → Variables** → add:
+   - Key: `NPM_TOKEN`
+   - Value: the token
+   - Flags: **Masked**; use **Protected** only if `v*` tags are protected (otherwise leave Protected off so tag pipelines can read it).
+4. Optional local check: `pnpm login` then `pnpm publish --dry-run --access public`.
+
+### Cut a release
+
+Requires a clean git worktree. Bumps `package.json`, commits, tags `vX.Y.Z`, and pushes (with `--follow-tags`) so the tag pipeline runs. Ensure `NPM_TOKEN` is set in GitLab before the first publish.
+
+```bash
+pnpm release -- 0.1.0    # first release
+# later:
+pnpm release -- patch    # or: minor | major
+```
+
+After the pipeline succeeds:
+
+- npm: [`@rose42/t3-feedback`](https://www.npmjs.com/package/@rose42/t3-feedback)
+- GitLab: **Deploy → Releases** (asset links to the generic package tarball)
+
+## License
+
+MIT © Rose42

package/dist/bridge/attachments.d.ts

@@ -0,0 +1,27 @@
+import type { FeedbackEnvelope } from "@rose42/feedback-capture";
+export type T3FeedbackImageAttachment = {
+    dataUrl: string;
+    name?: string;
+    /** Defaults to `image/png` when omitted. */
+    mimeType?: string;
+};
+/** Recognized `collect()` value for any plugin id — merged into T3 message attachments. */
+export type T3FeedbackAttachmentsValue = {
+    attachments: T3FeedbackImageAttachment[];
+};
+/**
+ * PNG data URLs from the screenshot plugin.
+ * Accepts legacy single `string` or `string[]`.
+ */
+export declare function envelopeScreenshotDataUrls(envelope: FeedbackEnvelope): string[];
+/** First PNG data URL from the screenshot plugin, if present. */
+export declare function envelopeScreenshotDataUrl(envelope: FeedbackEnvelope): string | undefined;
+export declare function dataUrlSizeBytes(dataUrl: string): number;
+/** True when `value` is the attachment collect shape (at least one valid item). */
+export declare function isT3FeedbackAttachmentsValue(value: unknown): value is T3FeedbackAttachmentsValue;
+/**
+ * Image attachments for the T3 thread message: legacy `screenshot` URLs plus any
+ * plugin collect value shaped as {@link T3FeedbackAttachmentsValue}.
+ * Dedupes by `dataUrl` (first wins).
+ */
+export declare function envelopeImageAttachments(envelope: FeedbackEnvelope): T3FeedbackImageAttachment[];

package/dist/bridge/attachments.js

@@ -0,0 +1,109 @@
+function valueOf(result) {
+    if (!result || !result.ok)
+        return undefined;
+    return result.value;
+}
+/**
+ * PNG data URLs from the screenshot plugin.
+ * Accepts legacy single `string` or `string[]`.
+ */
+export function envelopeScreenshotDataUrls(envelope) {
+    const value = valueOf(envelope.screenshot);
+    if (value === undefined)
+        return [];
+    if (typeof value === "string")
+        return value ? [value] : [];
+    if (Array.isArray(value)) {
+        return value.filter((item) => typeof item === "string" && item.length > 0);
+    }
+    return [];
+}
+/** First PNG data URL from the screenshot plugin, if present. */
+export function envelopeScreenshotDataUrl(envelope) {
+    return envelopeScreenshotDataUrls(envelope)[0];
+}
+export function dataUrlSizeBytes(dataUrl) {
+    const base64 = dataUrl.split(",")[1] ?? "";
+    return Math.floor((base64.length * 3) / 4);
+}
+function isNonEmptyDataUrl(value) {
+    return typeof value === "string" && value.length > 0;
+}
+function normalizeAttachmentItem(item) {
+    if (!item || typeof item !== "object")
+        return undefined;
+    const record = item;
+    if (!isNonEmptyDataUrl(record.dataUrl))
+        return undefined;
+    const out = { dataUrl: record.dataUrl };
+    if (typeof record.name === "string" && record.name.trim()) {
+        out.name = record.name.trim();
+    }
+    if (typeof record.mimeType === "string" && record.mimeType.trim()) {
+        out.mimeType = record.mimeType.trim();
+    }
+    return out;
+}
+/** True when `value` is the attachment collect shape (at least one valid item). */
+export function isT3FeedbackAttachmentsValue(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const attachments = value.attachments;
+    if (!Array.isArray(attachments))
+        return false;
+    return attachments.some((item) => normalizeAttachmentItem(item) !== undefined);
+}
+function attachmentsFromValue(value) {
+    if (!value || typeof value !== "object")
+        return [];
+    const attachments = value.attachments;
+    if (!Array.isArray(attachments))
+        return [];
+    const out = [];
+    for (const item of attachments) {
+        const normalized = normalizeAttachmentItem(item);
+        if (normalized)
+            out.push(normalized);
+    }
+    return out;
+}
+/**
+ * Image attachments for the T3 thread message: legacy `screenshot` URLs plus any
+ * plugin collect value shaped as {@link T3FeedbackAttachmentsValue}.
+ * Dedupes by `dataUrl` (first wins).
+ */
+export function envelopeImageAttachments(envelope) {
+    const out = [];
+    const seen = new Set();
+    const push = (item) => {
+        if (seen.has(item.dataUrl))
+            return;
+        seen.add(item.dataUrl);
+        out.push(item);
+    };
+    const legacy = envelopeScreenshotDataUrls(envelope);
+    for (let i = 0; i < legacy.length; i++) {
+        const dataUrl = legacy[i];
+        push({
+            dataUrl,
+            name: legacy.length === 1 ? "feedback.png" : `feedback-${i + 1}.png`,
+            mimeType: "image/png",
+        });
+    }
+    for (const [key, result] of Object.entries(envelope)) {
+        if (key === "screenshot")
+            continue;
+        if (!result || typeof result !== "object" || !("ok" in result))
+            continue;
+        const pr = result;
+        if (!pr.ok)
+            continue;
+        for (const item of attachmentsFromValue(pr.value)) {
+            push({
+                ...item,
+                mimeType: item.mimeType ?? "image/png",
+            });
+        }
+    }
+    return out;
+}