@rose42/t3-feedback 0.1.0

package/dist/bridge/format.d.ts

@@ -0,0 +1,70 @@
+import type { FeedbackEnvelope } from "@rose42/feedback-capture";
+import { type T3FeedbackReportTypeGlyphResolved } from "../types.js";
+export { dataUrlSizeBytes, envelopeImageAttachments, envelopeScreenshotDataUrl, envelopeScreenshotDataUrls, isT3FeedbackAttachmentsValue, type T3FeedbackAttachmentsValue, type T3FeedbackImageAttachment, } from "./attachments.js";
+export declare const REPORT_TYPES: readonly ["bug", "feedback", "suggestion"];
+export type FeedbackReportType = (typeof REPORT_TYPES)[number];
+/**
+ * Title prefix for a report type: textual when glyph is `"icon"`, otherwise the
+ * emoji (built-in or custom map).
+ */
+export declare function reportTypeTitleLabel(type: FeedbackReportType, reportTypeGlyph?: T3FeedbackReportTypeGlyphResolved): string;
+/**
+ * Split a derived thread title into report type + display text without the
+ * `Bug:` / `Feedback:` / `Suggestion:` / emoji label (keeps an optional custom prefix).
+ */
+export declare function splitThreadTitleReportType(title: string, reportTypeGlyph?: T3FeedbackReportTypeGlyphResolved): {
+    reportType?: FeedbackReportType;
+    displayTitle: string;
+};
+/** Resolve report type from the envelope; unknown/missing → `bug`. */
+export declare function envelopeReportType(envelope: FeedbackEnvelope): FeedbackReportType;
+/** Collect-time hint: `**label:** value` */
+export type T3FeedbackFormatLabelValue = {
+    label: string;
+    value: string | number | boolean;
+};
+/** Collect-time hint: `### heading` + body paragraph */
+export type T3FeedbackFormatHeadingBody = {
+    heading: string;
+    body: string;
+};
+/** Collect-time hint: raw markdown section */
+export type T3FeedbackFormatMarkdown = {
+    markdown: string;
+};
+/**
+ * Render a custom plugin collect value using optional format hints, else defaults.
+ * Returns markdown lines (no trailing blank required from caller).
+ */
+export declare function formatCustomPluginSection(key: string, value: unknown): string[];
+/** Build the markdown body for a T3 turn from a plugin-keyed envelope. */
+export declare function formatFeedbackMessage(envelope: FeedbackEnvelope): string;
+/** Pathname from pageContext URL, or `/` when missing/invalid. */
+export declare function envelopePathname(envelope: FeedbackEnvelope): string;
+/**
+ * Display title for a new T3 thread (not a sticky lookup key).
+ * Shape: `[customPrefix: ]ReportType|Emoji: pathname · comment snippet`
+ * When `reportTypeGlyph` is `"emoji"` or a custom map, the type segment is an emoji.
+ */
+export declare function deriveThreadTitle(envelope: FeedbackEnvelope, prefix?: string, reportTypeGlyph?: T3FeedbackReportTypeGlyphResolved): string;
+/**
+ * Fallback only when `/.well-known/t3/environment` is unreachable.
+ * Desktop bridge registrations use this id; standalone `t3` servers mint a UUID.
+ */
+export declare const T3_PRIMARY_ENVIRONMENT_ID = "primary";
+/** Strip a trailing slash from an HTTP(S) origin. */
+export declare function normalizeOrigin(origin: string): string;
+/**
+ * Browser-facing origin for Open-in-T3 links.
+ * Explicit `openOrigin` / `T3_FEEDBACK_OPEN_ORIGIN` wins; otherwise the API
+ * `origin` is used as-is (no hostname rewrite — that can open a different
+ * container's host-forwarded T3 on shared ports).
+ */
+export declare function resolveOpenOrigin(apiOrigin: string, openOrigin?: string): string;
+/**
+ * Deep link into a thread: T3 web routes are `/$environmentId/$threadId`.
+ * Pass the server's `environmentId` from `/.well-known/t3/environment`.
+ */
+export declare function buildThreadOpenUrl(origin: string, threadId: string, environmentId: string): string;
+/** One-time pairing URL that T3 auto-submits (`/pair#token=…`). */
+export declare function buildPairOpenUrl(origin: string, credential: string): string;

package/dist/bridge/format.js

@@ -0,0 +1,358 @@
+import { rankSourceHierarchy } from "@rose42/feedback-capture";
+import { envelopeImageAttachments, isT3FeedbackAttachmentsValue } from "./attachments.js";
+import { DEFAULT_REPORT_TYPE_EMOJIS } from "../types.js";
+export { dataUrlSizeBytes, envelopeImageAttachments, envelopeScreenshotDataUrl, envelopeScreenshotDataUrls, isT3FeedbackAttachmentsValue, } from "./attachments.js";
+export const REPORT_TYPES = ["bug", "feedback", "suggestion"];
+const REPORT_TYPE_HEADING = {
+    bug: "Bug report",
+    feedback: "Feedback",
+    suggestion: "Suggestion",
+};
+const REPORT_TYPE_TITLE = {
+    bug: "Bug",
+    feedback: "Feedback",
+    suggestion: "Suggestion",
+};
+/** Escape a literal for use inside a RegExp character class / alternation. */
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Title prefix for a report type: textual when glyph is `"icon"`, otherwise the
+ * emoji (built-in or custom map).
+ */
+export function reportTypeTitleLabel(type, reportTypeGlyph = "icon") {
+    if (reportTypeGlyph === "icon")
+        return REPORT_TYPE_TITLE[type];
+    if (reportTypeGlyph === "emoji")
+        return DEFAULT_REPORT_TYPE_EMOJIS[type];
+    return reportTypeGlyph[type];
+}
+/** Labels that may appear as `Label:` in a stored thread title, longest first. */
+function titleLabelsToMatch(reportTypeGlyph) {
+    const byLabel = new Map();
+    // Prefer longer textual labels first when building the alternation.
+    for (const type of ["suggestion", "feedback", "bug"]) {
+        byLabel.set(REPORT_TYPE_TITLE[type], type);
+        byLabel.set(DEFAULT_REPORT_TYPE_EMOJIS[type], type);
+    }
+    if (reportTypeGlyph && typeof reportTypeGlyph === "object") {
+        for (const type of REPORT_TYPES) {
+            byLabel.set(reportTypeGlyph[type], type);
+        }
+    }
+    return [...byLabel.entries()]
+        .map(([label, reportType]) => ({ label, reportType }))
+        .sort((a, b) => b.label.length - a.label.length);
+}
+/**
+ * Split a derived thread title into report type + display text without the
+ * `Bug:` / `Feedback:` / `Suggestion:` / emoji label (keeps an optional custom prefix).
+ */
+export function splitThreadTitleReportType(title, reportTypeGlyph) {
+    const trimmed = title.replace(/\s+/g, " ").trim();
+    if (!trimmed)
+        return { displayTitle: "" };
+    const labels = titleLabelsToMatch(reportTypeGlyph);
+    if (labels.length === 0)
+        return { displayTitle: trimmed };
+    const alternation = labels.map(({ label }) => escapeRegExp(label)).join("|");
+    const re = new RegExp(`^(?:(.+?):\\s+)?(${alternation}):\\s*(.*)$`);
+    const match = trimmed.match(re);
+    if (!match)
+        return { displayTitle: trimmed };
+    const custom = match[1]?.trim();
+    const typeLabel = match[2] ?? "";
+    const rest = (match[3] ?? "").trim();
+    const reportType = labels.find(({ label }) => label === typeLabel)?.reportType;
+    if (!reportType)
+        return { displayTitle: trimmed };
+    const displayTitle = custom ? `${custom}: ${rest}` : rest;
+    return { reportType, displayTitle: displayTitle || trimmed };
+}
+function formatSourceLocation(loc) {
+    const at = loc.column != null && loc.column > 0
+        ? `${loc.fileName}:${loc.line}:${loc.column}`
+        : `${loc.fileName}:${loc.line}`;
+    return loc.name ? `${at} (${loc.name})` : at;
+}
+function sameLoc(a, b) {
+    return (a.fileName === b.fileName &&
+        a.line === b.line &&
+        (a.column ?? 0) === (b.column ?? 0) &&
+        (a.name ?? "") === (b.name ?? ""));
+}
+/**
+ * Agent-facing component roles from a (possibly unranked) element target.
+ * Always surfaces leaf when anything resolved; primary/secondary when hierarchy.
+ */
+function componentRolesForAgent(target) {
+    const ranked = rankSourceHierarchy({
+        ...(target.component ? { component: target.component } : {}),
+        ...(target.leaf ? { leaf: target.leaf } : {}),
+        ...(target.owners && target.owners.length > 0 ? { owners: target.owners } : {}),
+    });
+    if (!ranked?.component && !ranked?.leaf)
+        return {};
+    const leaf = ranked.leaf ?? ranked.component;
+    const primary = ranked.leaf && ranked.component && !sameLoc(ranked.leaf, ranked.component)
+        ? ranked.component
+        : undefined;
+    const owners = ranked.owners ?? [];
+    const secondary = owners[0];
+    const rest = owners.slice(1);
+    return {
+        ...(leaf ? { leaf } : {}),
+        ...(primary ? { primary } : {}),
+        ...(secondary ? { secondary } : {}),
+        ...(rest.length > 0 ? { owners: rest } : {}),
+    };
+}
+function valueOf(result) {
+    return result?.ok === true ? result.value : undefined;
+}
+function formatArg(value) {
+    if (typeof value === "string")
+        return value;
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+function formatElementSection(target) {
+    const lines = [
+        "### Element",
+        `- **selector:** \`${target.selector}\``,
+        `- **tag:** \`${target.tagName}\``,
+    ];
+    if (target.id)
+        lines.push(`- **id:** \`${target.id}\``);
+    if (target.role)
+        lines.push(`- **role:** \`${target.role}\``);
+    if (target.name)
+        lines.push(`- **name:** ${target.name}`);
+    if (target.textSnippet)
+        lines.push(`- **text:** ${target.textSnippet}`);
+    const { x, y, width, height } = target.boundingBox;
+    lines.push(`- **bbox:** ${Math.round(x)}, ${Math.round(y)}, ${Math.round(width)}×${Math.round(height)}`);
+    const roles = componentRolesForAgent(target);
+    if (roles.leaf) {
+        lines.push(`- **leaf:** \`${formatSourceLocation(roles.leaf)}\``);
+    }
+    if (roles.primary) {
+        lines.push(`- **primary:** \`${formatSourceLocation(roles.primary)}\``);
+    }
+    if (roles.secondary) {
+        lines.push(`- **secondary:** \`${formatSourceLocation(roles.secondary)}\``);
+    }
+    if (roles.owners && roles.owners.length > 0) {
+        lines.push(`- **owners:** ${roles.owners.map((o) => `\`${formatSourceLocation(o)}\``).join(" ← ")}`);
+    }
+    if (target.styles && Object.keys(target.styles).length > 0) {
+        lines.push("", "**Computed styles:**", "```css");
+        for (const [prop, value] of Object.entries(target.styles)) {
+            lines.push(`${prop}: ${value};`);
+        }
+        lines.push("```");
+    }
+    if (target.innerHTMLSnippet) {
+        lines.push("", "```html", target.innerHTMLSnippet, "```");
+    }
+    lines.push("");
+    return lines;
+}
+/** Resolve report type from the envelope; unknown/missing → `bug`. */
+export function envelopeReportType(envelope) {
+    const raw = valueOf(envelope.reportType);
+    if (raw === "feedback" || raw === "suggestion" || raw === "bug")
+        return raw;
+    return "bug";
+}
+function isFormatLabelValue(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const record = value;
+    if (typeof record.label !== "string" || !record.label.trim())
+        return false;
+    const v = record.value;
+    return typeof v === "string" || typeof v === "number" || typeof v === "boolean";
+}
+function isFormatHeadingBody(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const record = value;
+    return (typeof record.heading === "string" &&
+        record.heading.trim().length > 0 &&
+        typeof record.body === "string");
+}
+function isFormatMarkdown(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const record = value;
+    return typeof record.markdown === "string" && record.markdown.trim().length > 0;
+}
+/**
+ * Render a custom plugin collect value using optional format hints, else defaults.
+ * Returns markdown lines (no trailing blank required from caller).
+ */
+export function formatCustomPluginSection(key, value) {
+    if (isFormatMarkdown(value)) {
+        return [value.markdown.trim(), ""];
+    }
+    if (isFormatHeadingBody(value)) {
+        return [`### ${value.heading.trim()}`, value.body, ""];
+    }
+    if (isFormatLabelValue(value)) {
+        return [`**${value.label.trim()}:** ${String(value.value)}`, ""];
+    }
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+        return [`**${key}:** ${String(value)}`, ""];
+    }
+    return [`### ${key}`, "```json", JSON.stringify(value, null, 2), "```", ""];
+}
+/** Build the markdown body for a T3 turn from a plugin-keyed envelope. */
+export function formatFeedbackMessage(envelope) {
+    const reportType = envelopeReportType(envelope);
+    const comment = valueOf(envelope.comment);
+    const page = valueOf(envelope.pageContext);
+    const versionInfo = valueOf(envelope.version);
+    const logs = valueOf(envelope.consoleLogs);
+    const element = valueOf(envelope.elementTarget);
+    const lines = [`## ${REPORT_TYPE_HEADING[reportType]}`, ""];
+    const documentTitle = valueOf(envelope.documentTitle);
+    // Render whatever collect plugins put in the envelope (reportTypes / field
+    // filtering happen at collect time — format does not re-gate by report type).
+    if (page) {
+        lines.push(`**URL:** ${page.url}`);
+        if (typeof documentTitle === "string" && documentTitle.trim()) {
+            lines.push(`**Title:** ${documentTitle.trim()}`);
+        }
+        if (page.viewport) {
+            lines.push(`**Viewport:** ${page.viewport.width}×${page.viewport.height} @${page.viewport.devicePixelRatio}x`);
+        }
+        if (page.capturedAt) {
+            lines.push(`**Captured:** ${page.capturedAt}`);
+        }
+        if (page.userAgent) {
+            lines.push(`**UA:** ${page.userAgent}`);
+        }
+        lines.push("");
+    }
+    else if (typeof documentTitle === "string" && documentTitle.trim()) {
+        lines.push(`**Title:** ${documentTitle.trim()}`, "");
+    }
+    if (versionInfo?.version) {
+        const hmr = typeof versionInfo.hmr === "number" && Number.isFinite(versionInfo.hmr)
+            ? ` · #${versionInfo.hmr}`
+            : "";
+        lines.push(`**Version:** ${versionInfo.version}${hmr}`, "");
+    }
+    lines.push("### Comment", comment?.trim() || "(no comment)", "");
+    const screenshotCount = envelopeImageAttachments(envelope).length;
+    if (screenshotCount > 0) {
+        lines.push(`**Screenshots:** ${screenshotCount} attached`, "");
+    }
+    if (element) {
+        lines.push(...formatElementSection(element));
+    }
+    if (logs && logs.length > 0) {
+        lines.push("### Console logs", "```");
+        for (const entry of logs.slice(-50)) {
+            const args = entry.args.map(formatArg).join(" ");
+            lines.push(`[${entry.timestamp}] ${entry.level}: ${args}`);
+        }
+        lines.push("```", "");
+    }
+    // Surface other plugin keys for custom / future plugins.
+    for (const [key, result] of Object.entries(envelope)) {
+        if (key === "comment" ||
+            key === "pageContext" ||
+            key === "screenshot" ||
+            key === "consoleLogs" ||
+            key === "elementTarget" ||
+            key === "reportType" ||
+            key === "version" ||
+            key === "documentTitle") {
+            continue;
+        }
+        if (!result || typeof result !== "object" || !("ok" in result))
+            continue;
+        const pr = result;
+        if (!pr.ok) {
+            lines.push(`### ${key}`, `_(collect failed: ${pr.error})_`, "");
+            continue;
+        }
+        // Image attachments are uploaded separately — never dump base64 into markdown.
+        if (isT3FeedbackAttachmentsValue(pr.value))
+            continue;
+        lines.push(...formatCustomPluginSection(key, pr.value));
+    }
+    return lines.join("\n").trimEnd() + "\n";
+}
+/** Pathname from pageContext URL, or `/` when missing/invalid. */
+export function envelopePathname(envelope) {
+    const page = valueOf(envelope.pageContext);
+    if (!page?.url)
+        return "/";
+    try {
+        return new URL(page.url).pathname || "/";
+    }
+    catch {
+        return "/";
+    }
+}
+/**
+ * Display title for a new T3 thread (not a sticky lookup key).
+ * Shape: `[customPrefix: ]ReportType|Emoji: pathname · comment snippet`
+ * When `reportTypeGlyph` is `"emoji"` or a custom map, the type segment is an emoji.
+ */
+export function deriveThreadTitle(envelope, prefix, reportTypeGlyph = "icon") {
+    const comment = valueOf(envelope.comment)
+        ?.replace(/\s+/g, " ")
+        .trim();
+    const path = envelopePathname(envelope);
+    const snippet = (comment || "feedback").slice(0, 48);
+    const typeLabel = reportTypeTitleLabel(envelopeReportType(envelope), reportTypeGlyph);
+    const base = `${typeLabel}: ${path} · ${snippet}`;
+    const trimmedPrefix = prefix?.trim();
+    const title = trimmedPrefix ? `${trimmedPrefix}: ${base}` : base;
+    return title.slice(0, 100);
+}
+/**
+ * Fallback only when `/.well-known/t3/environment` is unreachable.
+ * Desktop bridge registrations use this id; standalone `t3` servers mint a UUID.
+ */
+export const T3_PRIMARY_ENVIRONMENT_ID = "primary";
+/** Strip a trailing slash from an HTTP(S) origin. */
+export function normalizeOrigin(origin) {
+    return origin.trim().replace(/\/$/, "");
+}
+/**
+ * Browser-facing origin for Open-in-T3 links.
+ * Explicit `openOrigin` / `T3_FEEDBACK_OPEN_ORIGIN` wins; otherwise the API
+ * `origin` is used as-is (no hostname rewrite — that can open a different
+ * container's host-forwarded T3 on shared ports).
+ */
+export function resolveOpenOrigin(apiOrigin, openOrigin) {
+    const explicit = openOrigin?.trim();
+    if (explicit)
+        return normalizeOrigin(explicit);
+    return normalizeOrigin(apiOrigin);
+}
+/**
+ * Deep link into a thread: T3 web routes are `/$environmentId/$threadId`.
+ * Pass the server's `environmentId` from `/.well-known/t3/environment`.
+ */
+export function buildThreadOpenUrl(origin, threadId, environmentId) {
+    const base = normalizeOrigin(origin);
+    const env = environmentId.trim() || T3_PRIMARY_ENVIRONMENT_ID;
+    return `${base}/${encodeURIComponent(env)}/${encodeURIComponent(threadId)}`;
+}
+/** One-time pairing URL that T3 auto-submits (`/pair#token=…`). */
+export function buildPairOpenUrl(origin, credential) {
+    const base = normalizeOrigin(origin);
+    const token = credential.trim();
+    return `${base}/pair#token=${encodeURIComponent(token)}`;
+}

package/dist/bridge/http.d.ts

@@ -0,0 +1,31 @@
+import type { T3FeedbackReportTypeGlyphResolved } from "../types.js";
+export type T3FeedbackBridgeRoute = "feedback" | "threads" | "settle" | "open" | "source" | null;
+/**
+ * Options for the host-agnostic Fetch handler (Vite middleware, Next Route Handler, …).
+ * Env vars (`T3_FEEDBACK_*`) apply when fields are omitted — same as the Vite plugin.
+ */
+export type T3FeedbackBridgeServerOptions = {
+    /**
+     * HTTP path prefix the client posts to (no trailing slash).
+     * Default: `/__t3-feedback`. Next hosts typically use `/api/t3-feedback`.
+     */
+    basePath?: string;
+    origin?: string;
+    openOrigin?: string;
+    workspaceRootHints?: string[];
+    threadTitlePrefix?: string;
+    reportTypeGlyph?: T3FeedbackReportTypeGlyphResolved;
+    token?: string;
+};
+/** Resolve which bridge route a pathname maps to under `basePath`. */
+export declare function matchT3FeedbackRoute(pathname: string, basePath?: string): T3FeedbackBridgeRoute;
+/**
+ * Host-agnostic T3 feedback bridge for the Fetch API.
+ *
+ * Wire from Vite `configureServer` or a Next.js Route Handler. Returns `null`
+ * when the request is not for this bridge (caller should fall through).
+ *
+ * DEV-only: once a bridge route matches, refuses unless
+ * `process.env.NODE_ENV === "development"` (404 JSON).
+ */
+export declare function handleT3FeedbackRequest(request: Request, options?: T3FeedbackBridgeServerOptions): Promise<Response | null>;

package/dist/bridge/http.js

@@ -0,0 +1,169 @@
+import { resolveOpenOrigin } from "./format.js";
+import { T3_FEEDBACK_API_PATH, T3_FEEDBACK_OPEN_SUFFIX, T3_FEEDBACK_SETTLE_SUFFIX, T3_FEEDBACK_SOURCE_SUFFIX, T3_FEEDBACK_THREADS_SUFFIX, } from "./paths.js";
+import { parseFeedbackPost, parseOpenHandoffRequest, parseSettlePost, parseThreadProbeIds, } from "./parse.js";
+import { readWorkspaceSourceFile } from "./readSource.js";
+import { createOpenHandoff, listThreadsInT3, probeThreadsInT3, sendFeedbackToT3, settleThreadsInT3, } from "./sendFeedback.js";
+import path from "node:path";
+const DEFAULT_ORIGIN = "http://localhost:3773";
+function pathResolveUp(from, levels) {
+    let current = from;
+    for (let i = 0; i < levels; i += 1)
+        current = path.resolve(current, "..");
+    return current;
+}
+function normalizeBasePath(basePath) {
+    const trimmed = basePath.trim() || T3_FEEDBACK_API_PATH;
+    return trimmed.replace(/\/$/, "") || T3_FEEDBACK_API_PATH;
+}
+/** Resolve which bridge route a pathname maps to under `basePath`. */
+export function matchT3FeedbackRoute(pathname, basePath = T3_FEEDBACK_API_PATH) {
+    const base = normalizeBasePath(basePath);
+    if (pathname === `${base}${T3_FEEDBACK_THREADS_SUFFIX}`)
+        return "threads";
+    if (pathname === `${base}${T3_FEEDBACK_SETTLE_SUFFIX}`)
+        return "settle";
+    if (pathname === `${base}${T3_FEEDBACK_OPEN_SUFFIX}`)
+        return "open";
+    if (pathname === `${base}${T3_FEEDBACK_SOURCE_SUFFIX}`)
+        return "source";
+    if (pathname === base || pathname === `${base}/`)
+        return "feedback";
+    return null;
+}
+function jsonResponse(status, body) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { "Content-Type": "application/json" },
+    });
+}
+function resolveBridgeEnv(options) {
+    const origin = options.origin ?? process.env.T3_FEEDBACK_ORIGIN ?? process.env.T3_ORIGIN ?? DEFAULT_ORIGIN;
+    const openOrigin = resolveOpenOrigin(origin, options.openOrigin ?? process.env.T3_FEEDBACK_OPEN_ORIGIN);
+    const workspaceRootHints = options.workspaceRootHints ??
+        [process.env.T3_FEEDBACK_WORKSPACE_HINT, process.cwd()].filter((value) => Boolean(value));
+    const threadTitlePrefix = options.threadTitlePrefix?.trim() || undefined;
+    const token = options.token ?? process.env.T3_FEEDBACK_TOKEN;
+    return {
+        origin,
+        openOrigin,
+        workspaceRootHints,
+        ...(threadTitlePrefix ? { threadTitlePrefix } : {}),
+        ...(options.reportTypeGlyph ? { reportTypeGlyph: options.reportTypeGlyph } : {}),
+        ...(token ? { token } : {}),
+        basePath: normalizeBasePath(options.basePath ?? T3_FEEDBACK_API_PATH),
+    };
+}
+/**
+ * Host-agnostic T3 feedback bridge for the Fetch API.
+ *
+ * Wire from Vite `configureServer` or a Next.js Route Handler. Returns `null`
+ * when the request is not for this bridge (caller should fall through).
+ *
+ * DEV-only: once a bridge route matches, refuses unless
+ * `process.env.NODE_ENV === "development"` (404 JSON).
+ */
+export async function handleT3FeedbackRequest(request, options = {}) {
+    const resolved = resolveBridgeEnv(options);
+    const url = new URL(request.url);
+    const route = matchT3FeedbackRoute(url.pathname, resolved.basePath);
+    if (!route)
+        return null;
+    if (process.env.NODE_ENV !== "development") {
+        return jsonResponse(404, {
+            error: "t3-feedback bridge is available only when NODE_ENV=development",
+        });
+    }
+    const bridgeOpts = {
+        origin: resolved.origin,
+        workspaceRootHints: resolved.workspaceRootHints,
+        ...(resolved.token ? { token: resolved.token } : {}),
+    };
+    try {
+        if (route === "threads" && request.method === "GET") {
+            const ids = parseThreadProbeIds(url.href);
+            if (ids.length === 0) {
+                const threads = await listThreadsInT3(bridgeOpts);
+                const body = { threads };
+                return jsonResponse(200, body);
+            }
+            const threads = await probeThreadsInT3(ids, bridgeOpts);
+            const body = { threads };
+            return jsonResponse(200, body);
+        }
+        if (route === "settle" && request.method === "POST") {
+            const body = await request.json().catch(() => null);
+            const ids = parseSettlePost(body);
+            if (ids === null) {
+                return jsonResponse(400, {
+                    error: "Invalid settle body; expected { threadIds: string[] }",
+                });
+            }
+            const threads = await settleThreadsInT3(ids, bridgeOpts);
+            const response = { threads };
+            return jsonResponse(200, response);
+        }
+        if (route === "open" && (request.method === "GET" || request.method === "POST")) {
+            const body = request.method === "POST" ? await request.json().catch(() => undefined) : undefined;
+            const parsed = parseOpenHandoffRequest(url.href, body);
+            if (!parsed) {
+                return jsonResponse(400, {
+                    error: "Invalid open request; expected threadId",
+                });
+            }
+            const handoff = await createOpenHandoff(parsed.threadId, {
+                origin: resolved.origin,
+                openOrigin: resolved.openOrigin,
+            });
+            return jsonResponse(200, handoff);
+        }
+        if (route === "source" && request.method === "GET") {
+            const file = url.searchParams.get("file")?.trim() ?? "";
+            if (!file) {
+                return jsonResponse(400, { error: "Missing file query param" });
+            }
+            const hints = [
+                ...resolved.workspaceRootHints,
+                // Next Route Handlers often run with cwd = apps/b2b.
+                process.cwd(),
+                pathResolveUp(process.cwd(), 1),
+                pathResolveUp(process.cwd(), 2),
+            ].filter((value, index, all) => {
+                return Boolean(value) && all.indexOf(value) === index;
+            });
+            const read = await readWorkspaceSourceFile(file, hints);
+            if (!read) {
+                return jsonResponse(404, { error: `Source not found: ${file}` });
+            }
+            return new Response(read.content, {
+                status: 200,
+                headers: {
+                    "Content-Type": "text/plain; charset=utf-8",
+                    "Cache-Control": "no-store",
+                },
+            });
+        }
+        if (route === "feedback" && request.method === "POST") {
+            const body = await request.json().catch(() => null);
+            const parsed = parseFeedbackPost(body);
+            if (!parsed) {
+                return jsonResponse(400, { error: "Invalid feedback envelope" });
+            }
+            const result = await sendFeedbackToT3(parsed.envelope, {
+                origin: resolved.origin,
+                openOrigin: resolved.openOrigin,
+                workspaceRootHints: resolved.workspaceRootHints,
+                ...(resolved.reportTypeGlyph ? { reportTypeGlyph: resolved.reportTypeGlyph } : {}),
+                ...(resolved.threadTitlePrefix ? { threadTitlePrefix: resolved.threadTitlePrefix } : {}),
+                ...(parsed.threadId ? { threadId: parsed.threadId } : {}),
+                ...(resolved.token ? { token: resolved.token } : {}),
+            });
+            return jsonResponse(200, result);
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error("[t3-feedback]", message);
+        return jsonResponse(502, { error: message });
+    }
+    return null;
+}

package/dist/bridge/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Host-agnostic Node bridge for T3 feedback.
+ * Use from Vite middleware, Next Route Handlers, or any Fetch-capable HTTP host.
+ * Do not import this entry from browser code.
+ */
+export { handleT3FeedbackRequest, matchT3FeedbackRoute, type T3FeedbackBridgeRoute, type T3FeedbackBridgeServerOptions, } from "./http.js";
+export { parseFeedbackPost, parseOpenHandoffRequest, parseSettlePost, parseThreadProbeIds, } from "./parse.js";
+export { T3_FEEDBACK_API_PATH, T3_FEEDBACK_OPEN_PATH, T3_FEEDBACK_OPEN_SUFFIX, T3_FEEDBACK_SETTLE_PATH, T3_FEEDBACK_SETTLE_SUFFIX, T3_FEEDBACK_SOURCE_SUFFIX, T3_FEEDBACK_THREADS_PATH, T3_FEEDBACK_THREADS_SUFFIX, } from "./paths.js";
+export { readWorkspaceSourceFile } from "./readSource.js";
+export { clearT3EnvironmentIdCache, createOpenHandoff, issuePairingCredential, listThreadsInT3, parseT3JsonStdout, pickProject, probeThreadsInT3, resolveT3Environment, resolveT3EnvironmentId, sendFeedbackToT3, settleThreadsInT3, type ProbeThreadsOptions, type ShellSnapshot, type T3BridgeOptions, type T3EnvironmentDescriptor, } from "./sendFeedback.js";
+export { buildPairOpenUrl, buildThreadOpenUrl, deriveThreadTitle, formatCustomPluginSection, formatFeedbackMessage, normalizeOrigin, resolveOpenOrigin, type T3FeedbackFormatHeadingBody, type T3FeedbackFormatLabelValue, type T3FeedbackFormatMarkdown, } from "./format.js";
+export { dataUrlSizeBytes, envelopeImageAttachments, isT3FeedbackAttachmentsValue, type T3FeedbackAttachmentsValue, type T3FeedbackImageAttachment, } from "./attachments.js";
+export type { FeedbackSendResult, ThreadListItem, ThreadProbeResult, ThreadProbeState, ThreadSettleResult, ThreadsListResponse, ThreadsProbeResponse, ThreadsSettleResponse, T3FeedbackOpenHandoff, T3FeedbackReportTypeGlyphResolved, } from "../types.js";

package/dist/bridge/index.js

@@ -0,0 +1,12 @@
+/**
+ * Host-agnostic Node bridge for T3 feedback.
+ * Use from Vite middleware, Next Route Handlers, or any Fetch-capable HTTP host.
+ * Do not import this entry from browser code.
+ */
+export { handleT3FeedbackRequest, matchT3FeedbackRoute, } from "./http.js";
+export { parseFeedbackPost, parseOpenHandoffRequest, parseSettlePost, parseThreadProbeIds, } from "./parse.js";
+export { T3_FEEDBACK_API_PATH, T3_FEEDBACK_OPEN_PATH, T3_FEEDBACK_OPEN_SUFFIX, T3_FEEDBACK_SETTLE_PATH, T3_FEEDBACK_SETTLE_SUFFIX, T3_FEEDBACK_SOURCE_SUFFIX, T3_FEEDBACK_THREADS_PATH, T3_FEEDBACK_THREADS_SUFFIX, } from "./paths.js";
+export { readWorkspaceSourceFile } from "./readSource.js";
+export { clearT3EnvironmentIdCache, createOpenHandoff, issuePairingCredential, listThreadsInT3, parseT3JsonStdout, pickProject, probeThreadsInT3, resolveT3Environment, resolveT3EnvironmentId, sendFeedbackToT3, settleThreadsInT3, } from "./sendFeedback.js";
+export { buildPairOpenUrl, buildThreadOpenUrl, deriveThreadTitle, formatCustomPluginSection, formatFeedbackMessage, normalizeOrigin, resolveOpenOrigin, } from "./format.js";
+export { dataUrlSizeBytes, envelopeImageAttachments, isT3FeedbackAttachmentsValue, } from "./attachments.js";

package/dist/bridge/parse.d.ts

@@ -0,0 +1,16 @@
+import type { FeedbackEnvelope } from "@rose42/feedback-capture";
+/** POST body: raw envelope, or `{ envelope, threadId? }` for session reuse. */
+export declare function parseFeedbackPost(body: unknown): {
+    envelope: FeedbackEnvelope;
+    threadId?: string;
+} | null;
+/** Parse `?ids=a,b` from the threads probe URL. */
+export declare function parseThreadProbeIds(url: string): string[];
+/** POST body: `{ threadIds: string[] }` (also accepts singular `threadId`). */
+export declare function parseSettlePost(body: unknown): string[] | null;
+/** Parse `{ threadId, environmentId?, projectId? }` from open query string or JSON body. */
+export declare function parseOpenHandoffRequest(url: string, body?: unknown): {
+    threadId: string;
+    environmentId?: string;
+    projectId?: string;
+} | null;