@kolibri-day/feedback 0.0.0-stage → 0.1.1

package/dist/esm/kernel/feedback/messages.js

@@ -0,0 +1,135 @@
+// Every user- and operator-facing string the package produces, per language.
+//
+// English is the default; German ships alongside, because the first app to use this
+// speaks it. An app that needs different wording overrides single entries by
+// spreading:
+//
+//     const messages = { ...en, notice: { ...en.notice, selfHosted: (l) => `…${l}…` } };
+//
+// Parameterised strings are functions rather than templates with placeholders: the
+// compiler then checks every call site passes what the sentence needs.
+export const de = {
+    locale: 'de',
+    kinds: { BUG: 'Bug', IDEA: 'Idee', OTHER: 'Sonstiges' },
+    report: {
+        untitled: '(ohne Beschreibung)',
+        description: 'Beschreibung',
+        serverContext: 'Kontext (serverseitig ermittelt)',
+        clientContext: 'Kontext (clientseitig gemeldet — nicht verifiziert)',
+        field: 'Feld',
+        value: 'Wert',
+        reportedBy: 'Gemeldet von',
+        userId: 'Nutzer-ID',
+        reportedAtServer: 'Gemeldet am (Server)',
+        reportId: 'Report-ID',
+        url: 'URL',
+        pageTitle: 'Seitentitel',
+        viewport: 'Viewport',
+        screen: 'Bildschirm',
+        devicePixelRatio: 'Device Pixel Ratio',
+        userAgent: 'Browser (User-Agent)',
+        language: 'Sprache',
+        timezone: 'Zeitzone',
+        online: 'Online',
+        connection: 'Verbindung',
+        clientTime: 'Uhrzeit (Client)',
+        yes: 'ja',
+        no: 'nein',
+        openReport: 'Report in der App öffnen',
+    },
+    notice: {
+        selfHosted: (label) => `Der Screenshot zeigt diese Ansicht inkl. aller darin sichtbaren Daten und wird in eurem selbst-betriebenen ${label} gespeichert.`,
+        thirdParty: (label) => `Achtung: Der Screenshot zeigt diese Ansicht inkl. aller darin sichtbaren Daten und wird an ${label} übertragen — ein externes System außerhalb eurer eigenen Infrastruktur.`,
+    },
+    targets: {
+        fake: 'Test-Ziel (lokal)',
+        unconfigured: 'kein Zielsystem',
+    },
+    kolibri: {
+        unreachable: (path, detail) => `Kolibri nicht erreichbar (${path}): ${detail}`,
+        createRejected: (status, body) => `Kolibri hat die Task-Erstellung abgelehnt (HTTP ${status}): ${body}`,
+        uploadRejected: (status, body) => `Kolibri hat den Datei-Upload abgelehnt (HTTP ${status}): ${body}`,
+    },
+    config: {
+        targetUnset: 'FEEDBACK_TARGET ist nicht gesetzt — Reports werden gespeichert, aber an kein Zielsystem übermittelt.',
+        fakeInProduction: 'FEEDBACK_TARGET=fake in production — Reports gehen an kein echtes Zielsystem.',
+        missingVariables: (target, names) => `FEEDBACK_TARGET=${target}, aber folgende Variablen fehlen: ${names.join(', ')}.`,
+        notUuid: (variable, expected, value) => expected === 'workspace'
+            ? `${variable} muss eine UUID sein, kein Slug (ist: "${value}").`
+            : `${variable} muss eine UUID sein, kein Projekt-Key (ist: "${value}").`,
+        unknownTarget: (value, known) => `FEEDBACK_TARGET="${value}" ist unbekannt (erwartet: ${known.map((k) => `"${k}"`).join(' oder ')}).`,
+    },
+    input: {
+        messageRequired: 'Bitte beschreiben Sie kurz, worum es geht.',
+        messageTooLong: (max) => `Die Beschreibung ist zu lang (max. ${max} Zeichen).`,
+        unknownKind: 'Unbekannte Art der Rückmeldung.',
+        screenshotTooLarge: 'Der Screenshot ist zu groß.',
+        unsupportedImage: 'Nicht unterstütztes Bildformat.',
+        bodyTooLarge: 'Die Rückmeldung ist zu groß.',
+        invalidRequest: 'Ungültige Anfrage.',
+    },
+};
+export const en = {
+    locale: 'en',
+    kinds: { BUG: 'Bug', IDEA: 'Idea', OTHER: 'Other' },
+    report: {
+        untitled: '(no description)',
+        description: 'Description',
+        serverContext: 'Context (determined server-side)',
+        clientContext: 'Context (reported by the client — not verified)',
+        field: 'Field',
+        value: 'Value',
+        reportedBy: 'Reported by',
+        userId: 'User ID',
+        reportedAtServer: 'Reported at (server)',
+        reportId: 'Report ID',
+        url: 'URL',
+        pageTitle: 'Page title',
+        viewport: 'Viewport',
+        screen: 'Screen',
+        devicePixelRatio: 'Device pixel ratio',
+        userAgent: 'Browser (user agent)',
+        language: 'Language',
+        timezone: 'Time zone',
+        online: 'Online',
+        connection: 'Connection',
+        clientTime: 'Time (client)',
+        yes: 'yes',
+        no: 'no',
+        openReport: 'Open report in the app',
+    },
+    notice: {
+        selfHosted: (label) => `The screenshot shows this view, including any data visible in it, and is stored in your self-hosted ${label}.`,
+        thirdParty: (label) => `Attention: the screenshot shows this view, including any data visible in it, and is sent to ${label} — an external system outside your own infrastructure.`,
+    },
+    targets: {
+        fake: 'Test target (local)',
+        unconfigured: 'no target system',
+    },
+    kolibri: {
+        unreachable: (path, detail) => `Kolibri unreachable (${path}): ${detail}`,
+        createRejected: (status, body) => `Kolibri rejected the task creation (HTTP ${status}): ${body}`,
+        uploadRejected: (status, body) => `Kolibri rejected the file upload (HTTP ${status}): ${body}`,
+    },
+    config: {
+        targetUnset: 'FEEDBACK_TARGET is not set — reports are stored but delivered to no target system.',
+        fakeInProduction: 'FEEDBACK_TARGET=fake in production — reports reach no real target system.',
+        missingVariables: (target, names) => `FEEDBACK_TARGET=${target}, but these variables are missing: ${names.join(', ')}.`,
+        notUuid: (variable, expected, value) => expected === 'workspace'
+            ? `${variable} must be a UUID, not a slug (is: "${value}").`
+            : `${variable} must be a UUID, not a project key (is: "${value}").`,
+        unknownTarget: (value, known) => `FEEDBACK_TARGET="${value}" is unknown (expected: ${known.map((k) => `"${k}"`).join(' or ')}).`,
+    },
+    input: {
+        messageRequired: 'Please describe briefly what this is about.',
+        messageTooLong: (max) => `The description is too long (max. ${max} characters).`,
+        unknownKind: 'Unknown kind of feedback.',
+        screenshotTooLarge: 'The screenshot is too large.',
+        unsupportedImage: 'Unsupported image format.',
+        bodyTooLarge: 'The feedback is too large.',
+        invalidRequest: 'Invalid request.',
+    },
+};
+export const messages = { en, de };
+/** The kinds an app gets when it does not define its own. */
+export const DEFAULT_FEEDBACK_KINDS = ['BUG', 'IDEA', 'OTHER'];

package/dist/esm/kernel/feedback/notice.d.ts

@@ -0,0 +1,10 @@
+import type { FeedbackTargetDescriptor } from './types.js';
+import { type FeedbackMessages } from './messages.js';
+/** Is the screenshot attached by default? Only inside our own trust boundary. */
+export declare function screenshotDefaultOn(target: Pick<FeedbackTargetDescriptor, 'trustBoundary'>): boolean;
+/**
+ * The notice text. Names what the screenshot contains AND where it goes — a warning
+ * that says only "a screenshot will be attached" tells the reporter nothing they
+ * could act on.
+ */
+export declare function screenshotNotice(target: FeedbackTargetDescriptor, messages?: FeedbackMessages): string;

package/dist/esm/kernel/feedback/notice.js

@@ -0,0 +1,15 @@
+import { en } from "./messages.js";
+/** Is the screenshot attached by default? Only inside our own trust boundary. */
+export function screenshotDefaultOn(target) {
+    return target.trustBoundary === 'self_hosted';
+}
+/**
+ * The notice text. Names what the screenshot contains AND where it goes — a warning
+ * that says only "a screenshot will be attached" tells the reporter nothing they
+ * could act on.
+ */
+export function screenshotNotice(target, messages = en) {
+    return target.trustBoundary === 'self_hosted'
+        ? messages.notice.selfHosted(target.label)
+        : messages.notice.thirdParty(target.label);
+}

package/dist/esm/kernel/feedback/types.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Whether the configured target is run by the same organisation as the app, or by
+ * someone else.
+ *
+ * This is the ONE property of a target that deliberately leaks upward into the UI,
+ * and it earns that: it drives the PRIVACY POSTURE, not the transport. A screenshot
+ * of an application view contains whatever data that view shows, so what the
+ * reporter is told before they attach it — and whether attaching is the default at
+ * all — depends on where those bytes are about to land.
+ *
+ * Self-hosted means the same data controller, no new processor, no third-country
+ * transfer: an internal data flow, not a disclosure. A third-party target is a
+ * genuinely different question (GDPR Art. 28 processor agreement), and putting the
+ * distinction in the TYPE is what forces whoever adds such a target to answer it
+ * rather than inherit an answer that was never about them.
+ */
+export type TrustBoundary = 'self_hosted' | 'third_party';
+/**
+ * What a target IS, independent of whether its credentials are present — the
+ * safe-to-serialize view a web tier hands to the browser so the privacy notice can
+ * name where the screenshot is going. Three strings, none of them secret.
+ */
+export interface FeedbackTargetDescriptor {
+    /** Stable id, persisted on the report ("kolibri"). */
+    name: string;
+    /** Display name for the notice ("Kolibri"). */
+    label: string;
+    trustBoundary: TrustBoundary;
+}
+/** A file to attach to the created item. In practice: one screenshot, sometimes none. */
+export interface FeedbackAttachment {
+    filename: string;
+    contentType: string;
+    bytes: Uint8Array;
+}
+/**
+ * Who filed the report — resolved SERVER-SIDE from the app's own session, never from
+ * the request body. The client posts a message, a kind, a screenshot and a bag of
+ * browser facts; who it claims to be is not among the things it gets to say.
+ */
+export interface FeedbackReporter {
+    id: string;
+    name: string;
+    /** Optional role, shown next to the name ("Max Mustermann (ADMIN)"). */
+    role?: string | null;
+}
+/** A scalar fact in one of the report's context tables. `null`/`undefined` render as "—". */
+export type FeedbackFactValue = string | number | boolean | null | undefined;
+/**
+ * Further SERVER-DERIVED facts for the trusted context table, as `[label, value]`
+ * pairs in display order (tenant, active workspace, feature flags …). A tuple list
+ * rather than a record so the order is exactly what the app wrote — a record would
+ * silently hoist integer-like labels to the front.
+ *
+ * A `null` value still renders its row: "no active workspace" is information, and an
+ * omitted row reads as a forgotten field.
+ */
+export type FeedbackServerContext = ReadonlyArray<readonly [label: string, value: FeedbackFactValue]>;
+/**
+ * Browser facts as REPORTED BY THE CLIENT. Every consumer must present these as
+ * client-reported rather than mixing them in with the server-derived context: a
+ * debugging artifact that blurs verified and self-reported facts is how people end up
+ * chasing ghosts. Loosely typed on purpose — a target formats whatever it is given and
+ * never depends on a particular key.
+ */
+export interface FeedbackClientContext {
+    url?: string;
+    title?: string;
+    viewport?: string;
+    screen?: string;
+    devicePixelRatio?: number;
+    userAgent?: string;
+    language?: string;
+    timezone?: string;
+    online?: boolean;
+    connection?: string | null;
+    clientTime?: string;
+    [key: string]: unknown;
+}
+/** A link from the ticket back to the report in the reporting app. */
+export interface FeedbackBacklink {
+    url: string;
+    /** Link text; defaults to the messages' `report.openReport`. */
+    label?: string;
+}
+/** The normalized report — the ONLY thing a FeedbackTarget consumes. */
+export interface FeedbackReport<K extends string = string> {
+    /**
+     * The app's own report id. Backlink, support reference — and for Kolibri the TASK
+     * id, which is what makes delivery idempotent. Must be a UUID for that target.
+     */
+    id: string;
+    kind: K;
+    message: string;
+    reporter: FeedbackReporter;
+    serverContext?: FeedbackServerContext;
+    client: FeedbackClientContext;
+    attachments: FeedbackAttachment[];
+    /** When the app received the report (server clock). */
+    createdAt: Date;
+    backlink?: FeedbackBacklink | null;
+}
+/** What the target created. `externalUrl` is the human backlink, when the target has one. */
+export interface FeedbackSubmission {
+    externalId: string;
+    externalUrl: string | null;
+    /** May be FEWER than the report's attachments — a partial upload is a real outcome. */
+    attachmentsUploaded: number;
+}
+/**
+ * A target failure, classified.
+ *
+ * `permanent` is what stops a retry policy burning its whole attempt budget on a
+ * misconfigured project id, and equally what stops a transient 502 being written off
+ * as a dead report. The rule: a 4xx that no amount of retrying will fix (auth,
+ * not-found, unprocessable) is permanent; 5xx, network and timeout are not.
+ *
+ * `externalId` is set when the failure happened AFTER the item was created (i.e. the
+ * attachment upload failed). A durable caller persists it so the retry resumes the
+ * upload instead of creating a second ticket.
+ */
+export declare class FeedbackTargetError extends Error {
+    readonly permanent: boolean;
+    readonly status?: number;
+    readonly externalId?: string;
+    readonly externalUrl?: string | null;
+    constructor(message: string, permanent: boolean, status?: number, externalId?: string, externalUrl?: string | null);
+}
+/**
+ * Resume hint for a retry: the item ALREADY EXISTS at the target with this id.
+ *
+ * Part of the interface rather than one target's detail, because it is inherent to any
+ * target that creates an item and attaches files in separate calls (Kolibri, Jira and
+ * Linear all do) — the window between those calls is exactly where a retry can
+ * duplicate a ticket. A target whose create is idempotent, as Kolibri's is, needs it
+ * only as a hint; one that creates atomically ignores it entirely.
+ */
+export interface FeedbackResume {
+    externalId: string;
+}
+export interface FeedbackTarget extends FeedbackTargetDescriptor {
+    /**
+     * Create the item and attach the report's files.
+     *
+     * Contract: throws FeedbackTargetError on failure — it does NOT retry internally.
+     * Retry belongs to the caller's durable queue, which is where the backoff, the
+     * attempt budget and the operator visibility live. A target that retried on its own
+     * would be a second, invisible retry policy layered under the real one.
+     *
+     * When `resume` is given the item must NOT be created again — only the remaining
+     * work (the attachment upload) is retried.
+     */
+    submit(report: FeedbackReport, resume?: FeedbackResume): Promise<FeedbackSubmission>;
+}
+/** The descriptor of a live target — what crosses to the browser. */
+export declare function describeTarget(target: FeedbackTargetDescriptor): FeedbackTargetDescriptor;
+/** Injected so HTTP targets are unit-testable without a network. */
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;

package/dist/esm/kernel/feedback/types.js

@@ -0,0 +1,42 @@
+// The feedback-target seam — the one contract the capture/UI side and the delivery
+// side both depend on, and the reason a different issue tracker can replace the
+// configured one without either of them changing.
+//
+// Consumers depend ONLY on this interface and the normalized report shape below,
+// never on a concrete HTTP client. `KolibriFeedbackTarget` is the real
+// implementation; `FakeFeedbackTarget` drives tests and local development. A future
+// Linear/Jira target slots in next to it and nothing on the capture side is touched.
+//
+// Deliberately NOT on this interface: update/comment/close/list. Feedback is
+// one-directional (the app posts, humans work the ticket in the tracker's own UI), so
+// declaring round-trip methods would be inventing a contract no caller needs.
+/**
+ * A target failure, classified.
+ *
+ * `permanent` is what stops a retry policy burning its whole attempt budget on a
+ * misconfigured project id, and equally what stops a transient 502 being written off
+ * as a dead report. The rule: a 4xx that no amount of retrying will fix (auth,
+ * not-found, unprocessable) is permanent; 5xx, network and timeout are not.
+ *
+ * `externalId` is set when the failure happened AFTER the item was created (i.e. the
+ * attachment upload failed). A durable caller persists it so the retry resumes the
+ * upload instead of creating a second ticket.
+ */
+export class FeedbackTargetError extends Error {
+    permanent;
+    status;
+    externalId;
+    externalUrl;
+    constructor(message, permanent, status, externalId, externalUrl) {
+        super(message);
+        this.name = 'FeedbackTargetError';
+        this.permanent = permanent;
+        this.status = status;
+        this.externalId = externalId;
+        this.externalUrl = externalUrl;
+    }
+}
+/** The descriptor of a live target — what crosses to the browser. */
+export function describeTarget(target) {
+    return { name: target.name, label: target.label, trustBoundary: target.trustBoundary };
+}

package/dist/esm/kolibri.d.ts

@@ -0,0 +1,2 @@
+export { KolibriFeedbackTarget, KOLIBRI_TARGET, UUID_PATTERN, isPermanentStatus, type KolibriConfig, } from './adapters/kolibri/target.js';
+export { kolibriConfigFromEnv, KOLIBRI_ENV_VARS, type Env, type KolibriEnvResult } from './adapters/kolibri/env.js';

package/dist/esm/kolibri.js

@@ -0,0 +1,3 @@
+// @kolibri-day/feedback/kolibri — Kolibri as a feedback target. Runs anywhere fetch does.
+export { KolibriFeedbackTarget, KOLIBRI_TARGET, UUID_PATTERN, isPermanentStatus, } from "./adapters/kolibri/target.js";
+export { kolibriConfigFromEnv, KOLIBRI_ENV_VARS } from "./adapters/kolibri/env.js";

package/dist/esm/preflight-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/esm/preflight-cli.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// The `kolibri-feedback-preflight` command. All of it lives in
+// adapters/kolibri/preflight.ts; this file only hands it the process.
+import { runPreflight } from "./adapters/kolibri/preflight.js";
+runPreflight(process.env, process.argv.slice(2)).then((code) => process.exit(code), (error) => {
+    console.error(error);
+    process.exit(1);
+});

package/dist/esm/react.d.ts

@@ -0,0 +1,3 @@
+export { FeedbackReporterProvider, useFeedback, useFeedbackReporter, type FeedbackActions, type FeedbackReporterState, type FeedbackReporterProviderProps, } from './adapters/react/reporter.js';
+export type { CaptureState } from './adapters/capture/reporter.js';
+export type { CaptureResult } from './adapters/capture/capture.js';

package/dist/esm/react.js

@@ -0,0 +1,3 @@
+'use client';
+// @kolibri-day/feedback/react — the reporter's state for React (18+), without markup.
+export { FeedbackReporterProvider, useFeedback, useFeedbackReporter, } from "./adapters/react/reporter.js";

package/dist/esm/server.d.ts

@@ -0,0 +1,4 @@
+export { resolveFeedbackTarget, describeFeedbackTarget, type ResolvedFeedbackTarget, type ResolveOptions, } from './wiring.js';
+export { readFeedbackForm, parseFeedbackInput, sanitizeClientContext, FeedbackInputError, DEFAULT_LIMITS, type FeedbackLimits, type FeedbackInput, type FeedbackScreenshotInput, type ParsedFeedbackInput, type ParseOptions, } from './kernel/feedback/input.js';
+export { dispatchFeedback, MAX_ERROR_LENGTH, type FeedbackStore, type StoredFeedback, type StoredFeedbackStatus, type FeedbackSubmittedUpdate, type FeedbackFailureUpdate, type DispatchResult, type DispatchOptions, type DispatchLogger, } from './kernel/feedback/dispatch.js';
+export type { Env } from './adapters/kolibri/env.js';

package/dist/esm/server.js

@@ -0,0 +1,6 @@
+// @kolibri-day/feedback/server — what runs next to the app's own session and storage:
+// resolving the configured target, reading and validating an incoming report, and
+// delivering a stored report with the right retry semantics.
+export { resolveFeedbackTarget, describeFeedbackTarget, } from "./wiring.js";
+export { readFeedbackForm, parseFeedbackInput, sanitizeClientContext, FeedbackInputError, DEFAULT_LIMITS, } from "./kernel/feedback/input.js";
+export { dispatchFeedback, MAX_ERROR_LENGTH, } from "./kernel/feedback/dispatch.js";

package/dist/esm/wiring.d.ts

@@ -0,0 +1,38 @@
+import type { FeedbackTarget, FeedbackTargetDescriptor, FetchLike } from './kernel/feedback/types.js';
+import { type Env } from './adapters/kolibri/env.js';
+import { type FeedbackMessages } from './kernel/feedback/messages.js';
+export interface ResolvedFeedbackTarget {
+    target: FeedbackTarget;
+    /** Set when the target is a placeholder — log it once at boot. */
+    warning: string | null;
+}
+export interface ResolveOptions {
+    /** Language of the configuration warnings, the ticket body and the target errors. Default: German. */
+    messages?: FeedbackMessages;
+    /** Display labels for the app's own kinds, used in ticket titles. */
+    kindLabels?: Readonly<Record<string, string>>;
+    /** Per-request timeout for HTTP targets. */
+    timeoutMs?: number;
+    /** For tests. */
+    fetch?: FetchLike;
+}
+/**
+ * Build the configured target.
+ *
+ * NEVER THROWS. A misconfiguration produces an UnconfiguredFeedbackTarget plus a
+ * warning, not an exception: failing a worker's boot over a feedback variable would
+ * take every other job in that process down with it. The failure still surfaces — at
+ * boot as the warning, and per report as a permanent failure naming the problem.
+ */
+export declare function resolveFeedbackTarget(env?: Env, options?: ResolveOptions): ResolvedFeedbackTarget;
+/**
+ * Where would a screenshot land? — answered WITHOUT credentials.
+ *
+ * A web tier legitimately holds no tracker token: it only needs FEEDBACK_TARGET so the
+ * reporter's notice can name the destination. Resolving from that alone would yield
+ * the unconfigured placeholder and a notice like "is stored in your self-hosted no
+ * target system" — broken, and a false statement about where data goes. So a known
+ * choice is described from its static descriptor; only an unset or unknown choice
+ * falls through to the resolver, which is where "no target" is the honest answer.
+ */
+export declare function describeFeedbackTarget(env?: Env, options?: Pick<ResolveOptions, 'messages'>): FeedbackTargetDescriptor;

package/dist/esm/wiring.js

@@ -0,0 +1,68 @@
+import { FakeFeedbackTarget, UnconfiguredFeedbackTarget } from "./kernel/feedback/fake-target.js";
+import { KolibriFeedbackTarget, KOLIBRI_TARGET } from "./adapters/kolibri/target.js";
+import { kolibriConfigFromEnv } from "./adapters/kolibri/env.js";
+import { en } from "./kernel/feedback/messages.js";
+const KNOWN_TARGETS = ['kolibri', 'fake'];
+function processEnv() {
+    return globalThis.process?.env ?? {};
+}
+/**
+ * Build the configured target.
+ *
+ * NEVER THROWS. A misconfiguration produces an UnconfiguredFeedbackTarget plus a
+ * warning, not an exception: failing a worker's boot over a feedback variable would
+ * take every other job in that process down with it. The failure still surfaces — at
+ * boot as the warning, and per report as a permanent failure naming the problem.
+ */
+export function resolveFeedbackTarget(env = processEnv(), options = {}) {
+    const messages = options.messages ?? en;
+    const choice = (env.FEEDBACK_TARGET ?? '').trim().toLowerCase();
+    const isProduction = env.NODE_ENV === 'production';
+    const unconfigured = (reason) => ({
+        target: new UnconfiguredFeedbackTarget(reason, messages.targets.unconfigured),
+        warning: reason,
+    });
+    if (choice === '' || choice === 'fake') {
+        // Unset in production is NOT treated as "use the fake". A silently-swallowing
+        // target in production is the one outcome worse than a loud failure: people go on
+        // filing reports that reach nobody.
+        if (choice === '' && isProduction)
+            return unconfigured(messages.config.targetUnset);
+        return {
+            target: new FakeFeedbackTarget({ label: messages.targets.fake }),
+            warning: isProduction ? messages.config.fakeInProduction : null,
+        };
+    }
+    if (choice === 'kolibri') {
+        const read = kolibriConfigFromEnv(env, messages);
+        if (!read.ok)
+            return unconfigured(read.reason);
+        return {
+            target: new KolibriFeedbackTarget({ ...read.config, messages, kindLabels: options.kindLabels, timeoutMs: options.timeoutMs }, options.fetch),
+            // A configured Kolibri target is only as good as its preflight — the token's
+            // write scope over the upload route cannot be assumed (see the README).
+            warning: null,
+        };
+    }
+    return unconfigured(messages.config.unknownTarget(choice, KNOWN_TARGETS));
+}
+/**
+ * Where would a screenshot land? — answered WITHOUT credentials.
+ *
+ * A web tier legitimately holds no tracker token: it only needs FEEDBACK_TARGET so the
+ * reporter's notice can name the destination. Resolving from that alone would yield
+ * the unconfigured placeholder and a notice like "is stored in your self-hosted no
+ * target system" — broken, and a false statement about where data goes. So a known
+ * choice is described from its static descriptor; only an unset or unknown choice
+ * falls through to the resolver, which is where "no target" is the honest answer.
+ */
+export function describeFeedbackTarget(env = processEnv(), options = {}) {
+    const messages = options.messages ?? en;
+    const choice = (env.FEEDBACK_TARGET ?? '').trim().toLowerCase();
+    if (choice === KOLIBRI_TARGET.name)
+        return { ...KOLIBRI_TARGET };
+    if (choice === 'fake')
+        return { name: 'fake', label: messages.targets.fake, trustBoundary: 'self_hosted' };
+    const { target } = resolveFeedbackTarget(env, { messages });
+    return { name: target.name, label: target.label, trustBoundary: target.trustBoundary };
+}

package/package.json

@@ -1,6 +1,84 @@
 {
   "name": "@kolibri-day/feedback",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "In-app feedback with a screenshot of the current view, delivered to Kolibri — or to any tracker behind the same target interface.",
+  "license": "MIT",
+  "author": "Kolibri contributors",
+  "homepage": "https://github.com/LucaFrankfurt/AIfirstPMO/tree/main/packages/feedback#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LucaFrankfurt/AIfirstPMO.git",
+    "directory": "packages/feedback"
+  },
+  "bugs": "https://github.com/LucaFrankfurt/AIfirstPMO/issues",
+  "keywords": ["feedback", "bug-report", "screenshot", "kolibri", "issue-tracker", "react"],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/cjs/index.d.ts",
+  "exports": {
+    ".": {
+      "import": { "types": "./dist/esm/index.d.ts", "default": "./dist/esm/index.js" },
+      "require": { "types": "./dist/cjs/index.d.ts", "default": "./dist/cjs/index.js" }
+    },
+    "./kolibri": {
+      "import": { "types": "./dist/esm/kolibri.d.ts", "default": "./dist/esm/kolibri.js" },
+      "require": { "types": "./dist/cjs/kolibri.d.ts", "default": "./dist/cjs/kolibri.js" }
+    },
+    "./server": {
+      "import": { "types": "./dist/esm/server.d.ts", "default": "./dist/esm/server.js" },
+      "require": { "types": "./dist/cjs/server.d.ts", "default": "./dist/cjs/server.js" }
+    },
+    "./browser": {
+      "import": { "types": "./dist/esm/browser.d.ts", "default": "./dist/esm/browser.js" },
+      "require": { "types": "./dist/cjs/browser.d.ts", "default": "./dist/cjs/browser.js" }
+    },
+    "./react": {
+      "import": { "types": "./dist/esm/react.d.ts", "default": "./dist/esm/react.js" },
+      "require": { "types": "./dist/cjs/react.d.ts", "default": "./dist/cjs/react.js" }
+    },
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "kolibri": ["./dist/cjs/kolibri.d.ts"],
+      "server": ["./dist/cjs/server.d.ts"],
+      "browser": ["./dist/cjs/browser.d.ts"],
+      "react": ["./dist/cjs/react.d.ts"]
+    }
+  },
+  "bin": {
+    "kolibri-feedback-preflight": "dist/cjs/preflight-cli.js"
+  },
+  "files": ["dist", "fixtures", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.esm.json && tsc -p tsconfig.cjs.json && node scripts/postbuild.mjs",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "node --test test/*.test.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "html2canvas": "^1.4.1",
+    "modern-screenshot": "^4.7.0",
+    "react": "^18.2.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "html2canvas": { "optional": true },
+    "modern-screenshot": { "optional": true },
+    "react": { "optional": true }
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.0",
+    "html2canvas": "^1.4.1",
+    "modern-screenshot": "^4.7.0",
+    "react": "^19.2.0",
+    "typescript": "^5.9.2"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}