@rose42/t3-feedback 0.1.0

package/dist/types.js

@@ -0,0 +1,283 @@
+export const DEFAULT_FAB_CONFIG = {
+    visibility: "mobile",
+    mobileMaxWidth: 719,
+    position: { right: 16, bottom: 16 },
+    size: 44,
+};
+export function resolveFabConfig(fab) {
+    return {
+        visibility: fab?.visibility ?? DEFAULT_FAB_CONFIG.visibility,
+        mobileMaxWidth: fab?.mobileMaxWidth ?? DEFAULT_FAB_CONFIG.mobileMaxWidth,
+        position: fab?.position ?? DEFAULT_FAB_CONFIG.position,
+        size: fab?.size ?? DEFAULT_FAB_CONFIG.size,
+    };
+}
+/** Built-in emoji glyphs for Bug / Feedback / Suggestion when using `"emoji"` or a partial map. */
+export const DEFAULT_REPORT_TYPE_EMOJIS = {
+    bug: "🐛",
+    feedback: "💬",
+    suggestion: "💡",
+};
+export const DEFAULT_REPORT_TYPE_GLYPH = "icon";
+function trimGlyph(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed || undefined;
+}
+function glyphFromMap(map, lower, label) {
+    return trimGlyph(map[lower]) ?? trimGlyph(map[label]) ?? DEFAULT_REPORT_TYPE_EMOJIS[lower];
+}
+function isReportTypeGlyphMap(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+export function resolveReportTypeGlyph(value) {
+    if (value === "emoji")
+        return "emoji";
+    if (value === "icon" || value == null)
+        return DEFAULT_REPORT_TYPE_GLYPH;
+    if (!isReportTypeGlyphMap(value))
+        return DEFAULT_REPORT_TYPE_GLYPH;
+    return {
+        bug: glyphFromMap(value, "bug", "Bug"),
+        feedback: glyphFromMap(value, "feedback", "Feedback"),
+        suggestion: glyphFromMap(value, "suggestion", "Suggestion"),
+    };
+}
+export const DEFAULT_SHORTCUT = {
+    key: "f",
+    mod: true,
+    shift: true,
+    alt: false,
+};
+/** Default chord for element picking: Ctrl/⌘+Shift+E. */
+export const DEFAULT_PICK_SHORTCUT = {
+    key: "e",
+    mod: true,
+    shift: true,
+    alt: false,
+};
+/** Default chord for Capture screenshot: Ctrl/⌘+Shift+S. */
+export const DEFAULT_SCREENSHOT_SHORTCUT = {
+    key: "s",
+    mod: true,
+    shift: true,
+    alt: false,
+};
+/** Default chord for Record (frame burst): Ctrl/⌘+Shift+R. */
+export const DEFAULT_RECORD_SHORTCUT = {
+    key: "r",
+    mod: true,
+    shift: true,
+    alt: false,
+};
+/** Default Vite DEV endpoint for opening a file in the editor. */
+export const DEFAULT_OPEN_IN_EDITOR_ENDPOINT = "/__open-in-editor";
+export function resolveOpenInEditorConfig(value) {
+    if (value === false)
+        return null;
+    if (value === undefined || value === true) {
+        return { endpoint: DEFAULT_OPEN_IN_EDITOR_ENDPOINT };
+    }
+    const endpoint = typeof value.endpoint === "string" && value.endpoint.trim()
+        ? value.endpoint.trim()
+        : DEFAULT_OPEN_IN_EDITOR_ENDPOINT;
+    const urlTemplate = typeof value.urlTemplate === "string" && value.urlTemplate.trim()
+        ? value.urlTemplate.trim()
+        : undefined;
+    return urlTemplate ? { endpoint, urlTemplate } : { endpoint };
+}
+export function resolvePickConfig(pick) {
+    const shortcut = pick?.shortcut === false
+        ? null
+        : pick?.shortcut !== undefined
+            ? resolveShortcut(pick.shortcut)
+            : { ...DEFAULT_PICK_SHORTCUT };
+    const sourceFramework = pick?.sourceFramework === "react" ||
+        pick?.sourceFramework === "next" ||
+        pick?.sourceFramework === "vue" ||
+        pick?.sourceFramework === "svelte" ||
+        pick?.sourceFramework === "qwik" ||
+        pick?.sourceFramework === "locator" ||
+        pick?.sourceFramework === "none" ||
+        pick?.sourceFramework === "auto"
+        ? pick.sourceFramework
+        : "auto";
+    return {
+        shortcut,
+        afterPick: pick?.afterPick ?? "crop",
+        cropPaddingPx: pick?.cropPaddingPx ?? 12,
+        includeInnerHTML: pick?.includeInnerHTML === true,
+        maxInnerHTMLLength: pick?.maxInnerHTMLLength ?? 500,
+        styles: pick?.styles ?? "none",
+        sourceFramework,
+        openInEditor: resolveOpenInEditorConfig(pick?.openInEditor),
+    };
+}
+export function resolveScreenshotConfig(screenshot, pickCropPaddingPx = 12) {
+    const shortcut = screenshot?.shortcut === false
+        ? null
+        : screenshot?.shortcut !== undefined
+            ? resolveShortcut(screenshot.shortcut)
+            : { ...DEFAULT_SCREENSHOT_SHORTCUT };
+    const rawMax = screenshot?.maxImages;
+    const maxImages = rawMax === undefined || !Number.isFinite(rawMax)
+        ? 5
+        : Math.min(10, Math.max(1, Math.floor(rawMax)));
+    return {
+        shortcut,
+        crop: screenshot?.crop ?? "ui",
+        cropPaddingPx: screenshot?.cropPaddingPx ?? pickCropPaddingPx,
+        maxImages,
+    };
+}
+export function resolveRecordConfig(record) {
+    const shortcut = record?.shortcut === false
+        ? null
+        : record?.shortcut !== undefined
+            ? resolveShortcut(record.shortcut)
+            : { ...DEFAULT_RECORD_SHORTCUT };
+    return { shortcut };
+}
+/**
+ * Resolve plugin/mount shortcut options.
+ * - No `shortcut` / `shortcutKey`: Ctrl/⌘+Shift+F
+ * - `shortcut` object: omitted modifiers are `false`
+ * - Legacy `shortcutKey` only: same key with Ctrl/⌘+Shift
+ */
+export function resolveShortcut(shortcut, shortcutKey) {
+    if (shortcut) {
+        return {
+            key: (shortcut.key ?? shortcutKey ?? DEFAULT_SHORTCUT.key).toLowerCase(),
+            mod: shortcut.mod ?? false,
+            shift: shortcut.shift ?? false,
+            alt: shortcut.alt ?? false,
+        };
+    }
+    if (shortcutKey) {
+        return {
+            ...DEFAULT_SHORTCUT,
+            key: shortcutKey.toLowerCase(),
+        };
+    }
+    return { ...DEFAULT_SHORTCUT };
+}
+/** Human-readable chord label (e.g. `Ctrl/⌘+Shift+F` or `F (Ctrl/⌘+Shift+F in fields)`). */
+export function formatShortcutLabel(shortcut) {
+    const parts = [];
+    if (shortcut.mod)
+        parts.push("Ctrl/⌘");
+    if (shortcut.alt)
+        parts.push("Alt");
+    if (shortcut.shift)
+        parts.push("Shift");
+    parts.push(shortcut.key.toUpperCase());
+    const primary = parts.join("+");
+    if (shortcutRequiresModifier(shortcut))
+        return primary;
+    return `${primary} (Ctrl/⌘+Shift+${shortcut.key.toUpperCase()} in fields)`;
+}
+/** Whether `event` matches the resolved chord (modifiers must match exactly). */
+export function matchesShortcut(event, shortcut) {
+    if (event.key.toLowerCase() !== shortcut.key)
+        return false;
+    const modPressed = event.ctrlKey || event.metaKey;
+    if (shortcut.mod !== modPressed)
+        return false;
+    if (shortcut.shift !== event.shiftKey)
+        return false;
+    if (shortcut.alt !== event.altKey)
+        return false;
+    return true;
+}
+/** True when the chord requires at least one modifier (global; works while typing). */
+export function shortcutRequiresModifier(shortcut) {
+    return shortcut.mod || shortcut.shift || shortcut.alt;
+}
+/**
+ * Fixed escape hatch for bare-key shortcuts: same key with Ctrl/⌘+Shift
+ * (works in editable fields where the bare key is ignored).
+ */
+export function matchesBareKeyOverride(event, shortcut) {
+    if (shortcutRequiresModifier(shortcut))
+        return false;
+    if (event.key.toLowerCase() !== shortcut.key)
+        return false;
+    const modPressed = event.ctrlKey || event.metaKey;
+    return modPressed && event.shiftKey && !event.altKey;
+}
+const NON_TEXT_INPUT_TYPES = new Set([
+    "button",
+    "checkbox",
+    "radio",
+    "file",
+    "reset",
+    "submit",
+    "range",
+    "color",
+    "image",
+    "hidden",
+]);
+/**
+ * True when `target` is an editable / typing surface where a bare key
+ * should insert text instead of opening feedback.
+ */
+export function isEditableKeyboardTarget(target) {
+    if (!(target instanceof HTMLElement))
+        return false;
+    if (target.isContentEditable)
+        return true;
+    const tag = target.tagName;
+    if (tag === "TEXTAREA" || tag === "SELECT")
+        return true;
+    if (tag === "INPUT") {
+        const type = target.type.toLowerCase();
+        return !NON_TEXT_INPUT_TYPES.has(type);
+    }
+    return Boolean(target.closest('[contenteditable="true"], [role="textbox"]'));
+}
+/**
+ * Whether this keydown should open feedback.
+ * - Configured modified chords: exact match anywhere (including inputs).
+ * - Bare-key shortcuts: bare key outside editable fields, plus Ctrl/⌘+Shift+key
+ *   anywhere as a global override while typing.
+ */
+export function shouldOpenFromShortcut(event, shortcut) {
+    if (shortcutRequiresModifier(shortcut)) {
+        return matchesShortcut(event, shortcut);
+    }
+    if (matchesBareKeyOverride(event, shortcut))
+        return true;
+    if (!matchesShortcut(event, shortcut))
+        return false;
+    return !isEditableKeyboardTarget(event.target);
+}
+/** Built-in capture plugins selectable via `activePlugins`. Comment is always on. */
+export const T3_BUILTIN_PLUGIN_IDS = [
+    "pageContext",
+    "consoleLogs",
+    "screenshot",
+    "elementTarget",
+];
+/**
+ * Resolve which built-ins are active.
+ * - `active` omitted → all four (today’s defaults)
+ * - explicit list → only those ids (unknown strings ignored)
+ * - `includeConsoleLogs: false` strips `consoleLogs` (deprecated alias)
+ */
+export function resolveActivePlugins(active, includeConsoleLogs) {
+    const allowed = new Set(T3_BUILTIN_PLUGIN_IDS);
+    const ids = active === undefined
+        ? [...T3_BUILTIN_PLUGIN_IDS]
+        : active.filter((id) => allowed.has(id));
+    const set = new Set(ids);
+    if (includeConsoleLogs === false) {
+        set.delete("consoleLogs");
+    }
+    return set;
+}
+/** Stable ordered list of active built-in ids (for JSON client config). */
+export function resolveActivePluginList(active, includeConsoleLogs) {
+    const set = resolveActivePlugins(active, includeConsoleLogs);
+    return T3_BUILTIN_PLUGIN_IDS.filter((id) => set.has(id));
+}

package/docs/devcontainer.md

@@ -0,0 +1,160 @@
+# Devcontainer: T3 Code
+
+The Docker/devcontainer image ships with:
+
+| Tool                                                     | Binary                   | Role                                               |
+| -------------------------------------------------------- | ------------------------ | -------------------------------------------------- |
+| Node.js                                                  | `node` / `npm`           | Runtime (pinned in root `Dockerfile`)              |
+| pnpm                                                     | `pnpm`                   | Package manager                                    |
+| [T3 Code](https://github.com/pingdotgg/t3code)           | `t3`                     | Web UI / harness (`T3CODE_PORT`, default **3775**) |
+| [Cursor Agent](https://cursor.com/docs/cli/installation) | `agent` / `cursor-agent` | T3 provider CLI (auth separately)                  |
+
+Node / pnpm match the root `Dockerfile`. Rebuild the container after Dockerfile changes so these tools are present.
+
+The container runs as **root**. Named volumes survive rebuilds:
+
+| Volume               | Mount                    | Persists                                       |
+| -------------------- | ------------------------ | ---------------------------------------------- |
+| `t3-feedback-t3`     | `/root/.t3`              | T3 pairing, Connect credentials, `cloudflared` |
+| `t3-feedback-cursor` | `/root/.cursor`          | Cursor CLI config / project state              |
+| `cursor-agent-auth`  | `/root/.config/cursor`   | Cursor Agent login (`auth.json` on Linux)      |
+| `glab-auth`          | `/root/.config/glab-cli` | `glab` auth                                    |
+
+See [`.devcontainer/devcontainer.json`](../.devcontainer/devcontainer.json).
+
+## Sibling dependency (`@rose42/feedback-capture`)
+
+`package.json` depends on `@rose42/feedback-capture@0.1.0` from the registry.
+The devcontainer bind-mounts the **host sibling** clone and `pnpm link`s it after
+install so local edits to `feedback-capture` are used while developing:
+
+| Host                                          | Container                      |
+| --------------------------------------------- | ------------------------------ |
+| `${localWorkspaceFolder}/../feedback-capture` | `/workspaces/feedback-capture` |
+| this repo                                     | `/workspaces/t3-feedback`      |
+
+Clone both next to each other before opening the container:
+
+```text
+Documents/git/feedback-capture
+Documents/git/t3-feedback
+```
+
+`postCreateCommand` installs both packages, builds the sibling, then symlinks
+`node_modules/@rose42/feedback-capture` → `/workspaces/feedback-capture` (see
+[`link-local-feedback-capture.sh`](../.devcontainer/link-local-feedback-capture.sh)).
+That leaves `package.json` / the lockfile on registry `0.1.0`. Outside the
+container (CI, plain clones), install uses npm with no sibling required.
+
+On every container create/start, [`.devcontainer/t3-setup.sh`](../.devcontainer/t3-setup.sh)
+sets `PRETTY_HOSTNAME=t3-feedback` and prints whether **T3 Connect** is linked.
+
+## Open the environment
+
+1. Install the **Dev Containers** extension in Cursor / VS Code.
+2. Open this repo → Command Palette → **Dev Containers: Reopen in Container**.
+3. `postCreateCommand` runs `t3-setup.sh` + `pnpm install` (+ sibling build).
+4. Allow automatic tasks if prompted so **t3** starts on folder open ([`.vscode/tasks.json`](../.vscode/tasks.json)).
+
+## Two ways to reach this server
+
+| Path                                 | What it is                                                                  | Shows in T3 Code app?                  |
+| ------------------------------------ | --------------------------------------------------------------------------- | -------------------------------------- |
+| **Local browser** via forwarded port | `http://localhost:$T3CODE_PORT` + pairing token (default **3775**)          | No                                     |
+| **T3 Connect**                       | Cloud link + managed relay for phone / [app.t3.codes](https://app.t3.codes) | **Yes** — only after `t3 connect link` |
+
+Browser pairing and Connect are independent. Pairing a browser does **not** register the environment in the app.
+
+## Local UI (`T3CODE_PORT`)
+
+Port comes from **`T3CODE_PORT`** (default **3775**), set once in [`.devcontainer/devcontainer.json`](../.devcontainer/devcontainer.json) `remoteEnv` and inherited by the folder-open **t3** task and `t3-setup.sh`.
+
+T3 starts automatically when the folder opens (`runOn: folderOpen`). To start manually: Command Palette → **Tasks: Run Task** → **t3**, or:
+
+```bash
+t3 --no-browser --port "${T3CODE_PORT:-3775}"
+```
+
+Keep this project’s port unique vs other concurrent containers (`3773`, `3774`, …). Same host port ⇒ same browser origin ⇒ sessions kick each other off (`Invalid session token signature`).
+
+`T3_FEEDBACK_ORIGIN` / `T3_FEEDBACK_OPEN_ORIGIN` follow the same `T3CODE_PORT` default so the plugin bridges to this instance. Consumer projects must set both to **their** T3 port — not this plugin container's — or Open links will embed this environment's id/label.
+
+### Override on conflict
+
+1. On the **host**: `export T3CODE_PORT=3776` (or any free port), then **Dev Containers: Rebuild Container**.  
+   Or edit the default in `remoteEnv` (`${localEnv:T3CODE_PORT:3775}`).
+2. Update `forwardPorts` and `portsAttributes` in `devcontainer.json` to the same number (those keys cannot interpolate env).
+3. Reopen / restart the **t3** task; open `http://localhost:$T3CODE_PORT` from the Ports panel.
+
+Mint another pairing token while the server is running:
+
+```bash
+t3 pair
+```
+
+## T3 Connect (required for the phone / desktop app list)
+
+OAuth cannot be completed non-interactively inside the container. Linking is **one-time per environment volume**, then persists on `t3-feedback-t3`.
+
+### Link this environment
+
+1. Command Palette → **Tasks: Run Task** → **t3: connect link**
+   (or `t3 connect link --headless`)
+2. Open the printed URL on your **host** browser, sign in, paste the code back into the terminal.
+3. Decline any background-service / systemd prompt (**n**). Do not use `t3 service install` in this image — the folder-open **t3** task owns the process.
+4. Restart **t3** (stop the task terminal / re-run the **t3** task).
+5. **Tasks: Run Task** → **t3: connect status** (or `t3 connect status`).
+
+Expect:
+
+```text
+Exposure: enabled
+Environment link: provisioned
+```
+
+After that, the app should list **t3-feedback** (from `/etc/machine-info` `PRETTY_HOSTNAME`).
+
+### Multi-container notes
+
+- Each container needs its **own** `~/.t3` volume and its **own** `t3 connect link`.
+- Display names come from Linux `PRETTY_HOSTNAME` (set by `t3-setup.sh` here).
+- Connect has an environment-link quota (~3). Linking a 4th can fail with HTTP 403 — deregister an unused environment in the app (**Settings → T3 Connect**), then link again.
+
+Useful commands: `t3 connect status`, `t3 connect unlink`, `t3 connect logout`. Broader options: [T3 remote access](https://github.com/pingdotgg/t3code/blob/main/docs/user/remote-access.md).
+
+## Providers
+
+**Cursor Agent** is preinstalled (`agent` / `cursor-agent` on PATH). Authenticate once inside the container (survives rebuilds via the `cursor-agent-auth` volume):
+
+```bash
+agent login
+```
+
+On Linux the CLI writes `~/.config/cursor/auth.json`. `AGENT_CLI_CREDENTIAL_STORE=file` keeps credentials in that file instead of a keyring. Or set `CURSOR_API_KEY`.
+
+## Quick checklist (new machine / fresh volume)
+
+1. Ensure sibling `feedback-capture` is cloned next to this repo.
+2. Rebuild/reopen the devcontainer; read the `t3-setup.sh` banner in the create/start output.
+3. Allow automatic tasks (or run **t3**) → open forwarded **`T3CODE_PORT`** (default **3775**).
+4. If the banner says Connect is **not** linked: run **t3: connect link** → host OAuth → decline service prompt → restart **t3** → **t3: connect status** shows provisioned.
+5. `agent login` once (or set `CURSOR_API_KEY`), then start a thread against this workspace.
+
+## Troubleshooting
+
+| Symptom                                                           | Fix                                                                                                                                   |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `t3: command not found`                                           | Rebuild the image (`npm install -g t3@latest` is in the Dockerfile)                                                                   |
+| `Cannot find module '@rose42/feedback-capture'` / missing sibling | Clone `feedback-capture` as a sibling of this repo; reopen container so the bind mount exists                                         |
+| `cursor-agent: command not found`                                 | Rebuild the image; confirm `/root/.local/bin` is on `PATH`                                                                            |
+| T3 UI unreachable                                                 | Confirm `T3CODE_PORT` forwarded; use Ports panel “Open in Browser”                                                                    |
+| Pairing one container kicks the other offline                     | Use unique host ports (`T3CODE_PORT`, default **3775**; feedback-capture: **3774**; often **3773**). Re-pair each tab to its own URL. |
+| Need a different local port                                       | Set host `T3CODE_PORT`, sync `forwardPorts` / `portsAttributes`, rebuild (see [Override on conflict](#override-on-conflict))          |
+| Second environment missing in the T3 Code app                     | Connect not linked here (or `t3` not running). Run **t3: connect link**, restart **t3**                                               |
+| Stale T3                                                          | `npm install -g t3@latest`, or rebuild the container                                                                                  |
+
+## Security notes
+
+- Do not bake secrets into the image. Auth state belongs in the named `~/.t3` and `~/.config/cursor` volumes.
+- Prefer T3 Connect over exposing the container on the LAN.
+- `.dockerignore` keeps `.git`, `node_modules`, `.env*`, and build artifacts out of the image build context.

package/package.json

@@ -0,0 +1,107 @@
+{
+  "name": "@rose42/t3-feedback",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "DEV-only: capture app feedback and send it to a T3 Code thread (unofficial community tool)",
+  "license": "MIT",
+  "keywords": [
+    "feedback",
+    "screenshot",
+    "bug-report",
+    "devtools",
+    "vite",
+    "t3"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/rose42/t3-feedback.git"
+  },
+  "homepage": "https://gitlab.com/rose42/t3-feedback",
+  "bugs": {
+    "url": "https://gitlab.com/rose42/t3-feedback/-/issues"
+  },
+  "sideEffects": false,
+  "bin": {
+    "t3-feedback": "./dist/cli/bin.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "import": "./dist/plugin.js"
+    },
+    "./bridge": {
+      "types": "./dist/bridge/index.d.ts",
+      "import": "./dist/bridge/index.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "import": "./dist/client/index.js"
+    },
+    "./controls": {
+      "types": "./dist/controls.d.ts",
+      "import": "./dist/controls.js"
+    },
+    "./cli": {
+      "types": "./dist/cli/index.d.ts",
+      "import": "./dist/cli/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs",
+    "!dist/**/*.map"
+  ],
+  "scripts": {
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "release": "bash scripts/release.sh",
+    "prepublishOnly": "pnpm typecheck && pnpm lint && pnpm test && pnpm build"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "packageManager": "pnpm@10.21.0",
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
+  },
+  "dependencies": {
+    "@rose42/feedback-capture": "0.1.0",
+    "ws": "^8.18.3"
+  },
+  "peerDependencies": {
+    "vite": "^6.0.0 || ^7.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.1",
+    "@types/node": "^22.20.2",
+    "@types/ws": "^8.18.1",
+    "eslint": "^9.39.1",
+    "eslint-config-prettier": "^10.1.8",
+    "happy-dom": "^20.14.3",
+    "prettier": "^3.6.2",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.46.4",
+    "vite": "^7.0.0",
+    "vitest": "^3.2.7"
+  }
+}