@ozvi/widget 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ozvi contributors
+
+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

@@ -1,3 +1,287 @@
-# Temporary Holding Version
+# @ozvi/widget
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Ozvi inside your app, MIT:
+
+- `<ozvi-widget>`: the floating feedback widget (bug reports with masked context, ideas with voting), Preact in shadow DOM;
+- `window.Ozvi`: a JavaScript API to open it from your own buttons, prefill it, identify the person and listen to events;
+- `<ozvi-roadmap>` and `<ozvi-changelog>`: inline embeds (with a "What's new" badge);
+- `@ozvi/widget`, `@ozvi/widget/react`, `@ozvi/widget/vue`: typed ESM wrappers.
+
+```html
+<script src="https://feedback.example.com/widget.js" defer></script>
+<ozvi-widget project="billiwo" token-url="/api/ozvi-token" app-version="2.14.0"></ozvi-widget>
+```
+
+- Entry points: "Report a bug" (private, auto-context + masked screenshot), "Suggest an idea" (top ideas, search, voting
+  and a new idea with similar ideas shown while typing, all inside the widget) and "My reports" (the board in a new tab).
+- Styled only through `--oz-*` variables from `@ozvi/theme` `toCss(theme, ":host")`; fonts only from the Ozvi host
+  (`/fonts/css`), never from Google.
+- **Size**: `widget.js` stays within **20 kB gzip** (a test fails above it: `src/size.test.ts`; today 18.4 kB). Everything
+  else loads on demand and reuses the widget's Preact: `widget-shot.js` (screenshot, 9.6 kB), `widget-annotate.js`
+  (mark-up, 3.9 kB), `widget-ideas.js` (ideas, 4.9 kB), `widget-embeds.js` (roadmap/changelog, 4.9 kB).
+
+## JavaScript API
+
+Everything the attributes do, plus control from your code. `window.Ozvi` exists once `widget.js` has run. To call it
+earlier (from inline code, or before the `defer` script), paste the stub first; it queues calls and `widget.js` runs
+them in order:
+
+```html
+<script>(function(w,m){var o=w.Ozvi=w.Ozvi||function(){(o.q=o.q||[]).push(arguments)};o.q=o.q||[];m.forEach(function(k){o[k]=o[k]||function(){o.q.push([k].concat([].slice.call(arguments)))}})})(window,["init","open","close","toggle","prefill","identify","logout","setTraits","setLanguage","on","off","configure"])</script>
+<script src="https://feedback.example.com/widget.js" defer></script>
+```
+
+| Call | What it does |
+|---|---|
+| `Ozvi.open(tab?)` | `"menu"` (default), `"bug"` (screenshot + form), `"ideas"` (list with search and voting), `"idea"` (new idea form), `"mine"` (the person's reports on the board, new tab) |
+| `Ozvi.close()`, `Ozvi.toggle(tab?)`, `Ozvi.isOpen()` | |
+| `Ozvi.prefill({ title, body, kind })` | text for the next bug report (`kind: "bug"`, default) or idea (`"idea"`); `null` clears. Cleared after a successful send |
+| `Ozvi.identify(token \| () => token \| { token, id })` | use this SSO token (or a function returning a fresh one) instead of `token-url`; `id` only keys the local "seen" state of the changelog |
+| `Ozvi.logout()` | forget the identity and any cached token (call it when the person signs out of your app) |
+| `Ozvi.setTraits({ plan: "Pro" })` | shown to the team with bug reports as "Page data (unverified)". Traits that matter (MRR, plan for sorting) belong in the **signed** token (`traits` in `signOzviToken`) |
+| `Ozvi.setLanguage("en")` | `sk`, `cs`, `en`; switches the widget and the embeds at once |
+| `Ozvi.on(event, fn)` → `unsubscribe`, `Ozvi.off(event, fn)` | see events below |
+| `Ozvi.init({ project, tokenUrl, ... })` | adds an `<ozvi-widget>` with these options (attributes in camelCase) if there isn't one |
+| `Ozvi.configure({...})` | same as `window.OzviConfig` (below) |
+| `Ozvi.ready` | a Promise resolving to the API once `widget.js` has loaded; with the stub use `Ozvi("ready", fn)` |
+| `Ozvi("open", "ideas")` | snippet-style call, works before and after load |
+
+The element is a handle too: `document.querySelector("ozvi-widget").open("ideas")` (`open`, `close`, `toggle`, `prefill`).
+
+**Events** (`Ozvi.on`, and as DOM events `ozvi:<name>` bubbling from `<ozvi-widget>`):
+
+| Event | Detail |
+|---|---|
+| `open` | `{ tab }` |
+| `close` | `{}` |
+| `submit` | `{ kind: "bug" \| "idea", title }` before sending |
+| `submitted` | `{ kind, number, url, pending }`: `pending` is `"approval"` or `"links"` when the post waits for the team's approval |
+| `error` | `{ kind?: "bug" \| "idea" \| "vote", message }`; `message` is already in the widget's language |
+
+```js
+Ozvi.on("submitted", ({ kind, number, url, pending }) => analytics.track("feedback_sent", { kind, number, pending: !!pending }));
+document.querySelector("#help-menu .feedback").addEventListener("click", () => Ozvi.open("ideas"));
+Ozvi.prefill({ kind: "bug", title: "Export failed", body: `Invoice ${invoice.id}` }); Ozvi.open("bug");
+```
+
+Voting in the widget follows the board: simple or importance (1–3, the button cycles 0 → 1 → 2 → 3 → 0) and the vote
+budget, all enforced by the server. Voting doesn't subscribe anyone to e-mails. Ideas from outside the team can wait
+for approval; the widget says so and `submitted.pending` is set.
+
+## Inline roadmap and changelog
+
+```html
+<ozvi-roadmap project="billiwo" limit="5"></ozvi-roadmap>
+<ozvi-changelog project="billiwo" limit="3"></ozvi-changelog>
+<ozvi-changelog project="billiwo" mode="badge" align="end"></ozvi-changelog>
+```
+
+They need `widget.js` on the page (it defines the tags and loads `widget-embeds.js` when one appears). Shadow DOM,
+the project theme, keyboard and screen-reader friendly, and they reflow down to 320 px (lanes stack under 640 px).
+
+| Attribute | |
+|---|---|
+| `project` | required |
+| `host` | Ozvi base URL (default: where `widget.js` came from) |
+| `lang` | `sk` / `cs` / `en` (default: `<html lang>`, then the browser) |
+| `heading` | own heading text, or `none` to hide it (it stays for screen readers) |
+| `limit` | roadmap: cards per lane (default 5); changelog: entries (default 5, max 20) |
+| `lanes` | roadmap: `planned,in_progress,shipped` (any subset) |
+| `mode` | changelog: `list` (default) or `badge`: a "What's new" button with the unseen count and a popover |
+| `align` | changelog badge: `end` opens the popover to the left (button at the right edge) |
+| `token-url` / `token` | only for boards whose ideas aren't public |
+
+**Unseen count**: entries newer than the last one the person has seen. Stored in `localStorage` only (per Ozvi host,
+project and person: `identify({ id })` or the id inside the SSO token, else anonymous); nothing is sent to Ozvi. The inline
+list counts as seen after it has been on screen for a moment, the badge when it is opened. `<ozvi-changelog>` fires
+`ozvi:unseen` with `{ count }`, so you can put the number on your own menu item:
+
+```js
+document.querySelector("ozvi-changelog").addEventListener("ozvi:unseen", (e) => (menuBadge.textContent = e.detail.count || ""));
+```
+
+Public boards serve the roadmap and changelog to any site (read-only, no cookies, no token). Boards with private ideas
+answer only with a token, and only to origins in the project's allowed origins.
+
+## npm: ESM, React, Vue
+
+```js
+import { loadOzvi, ozvi } from "@ozvi/widget";
+loadOzvi({ host: "https://feedback.example.com", project: "acme", tokenUrl: "/api/ozvi-token" });
+ozvi.open("ideas"); // queued until widget.js has loaded; a no-op on the server
+```
+
+```tsx
+"use client"; // Next.js App Router: the hooks and components are client components
+import { OzviWidget, OzviChangelog, OzviRoadmap, useOzvi, useOzviEvent } from "@ozvi/widget/react";
+
+export function Feedback() {
+  const ozvi = useOzvi();
+  useOzviEvent("submitted", (d) => console.log("sent", d.number));
+  return (
+    <>
+      <OzviWidget host="https://feedback.example.com" project="acme" tokenUrl="/api/ozvi-token" launcher="none" />
+      <button onClick={() => ozvi.open("ideas")}>Ideas</button>
+      <OzviChangelog host="https://feedback.example.com" project="acme" mode="badge" onUnseen={(n) => setBadge(n)} />
+    </>
+  );
+}
+```
+
+```ts
+// Vue 3 / Nuxt
+import { OzviPlugin, OzviRoadmap, OzviChangelog, useOzvi, useOzviEvent } from "@ozvi/widget/vue";
+app.use(OzviPlugin, { host: "https://feedback.example.com", project: "acme", tokenUrl: "/api/ozvi-token" });
+// <OzviChangelog host="https://feedback.example.com" project="acme" :limit="3" @unseen="n => badge = n" />
+// Using <ozvi-*> tags directly in templates: compilerOptions.isCustomElement = (tag) => tag.startsWith("ozvi-")
+```
+
+Types for everything (`OzviApi`, `OzviEvents`, `OzviOptions`, …) come with the package.
+
+**SSR / Next.js**: importing is safe on the server; nothing touches `window` until an effect runs, the components render
+plain custom-element tags (hydration-safe, the shadow DOM attaches after `widget.js` loads), and `ozvi.*` calls are
+no-ops on the server. Give the token endpoint a route handler that signs with `@ozvi/sdk`:
+
+```ts
+// app/api/ozvi-token/route.ts
+import { signOzviToken } from "@ozvi/sdk";
+export async function GET() {
+  const user = await currentUser(); // your auth
+  if (!user) return new Response(null, { status: 401 });
+  return Response.json({ token: signOzviToken({ id: user.id, email: user.email, name: user.name }, process.env.OZVI_SSO_SECRET!) });
+}
+```
+
+The widget caches a token from `token-url` until a minute before it expires (10 minutes by default), so browsing ideas
+and voting don't hit your endpoint on every click.
+
+## Strict CSP
+
+The widget runs under a nonce-based CSP without `unsafe-inline` or `unsafe-eval`:
+
+- give the `<script>` a nonce (`<script nonce="…" src=".../widget.js">`, or `loadOzvi({ nonce })` / `<OzviWidget nonce>`).
+  `widget.js` passes it on to every script it loads on demand and to every `<style>` it adds (inside its shadow roots and
+  the screenshot's temporary blur style); with `'strict-dynamic'` nothing else is needed for scripts;
+- or set it explicitly: `window.OzviConfig = { nonce: "…" }`.
+
+Directives the widget needs (replace the host with yours):
+
+```
+script-src 'nonce-RANDOM' 'strict-dynamic' https://feedback.example.com;
+style-src 'nonce-RANDOM' https://feedback.example.com;
+font-src https://feedback.example.com;
+connect-src https://feedback.example.com;
+img-src 'self' blob: data: https://feedback.example.com;
+```
+
+`style-src` lists the Ozvi host for the font stylesheet (`/fonts/css`); `img-src blob: data:` is for the screenshot
+preview. Inline `style` attributes are never used in markup (only through CSSOM, which CSP allows).
+
+## What a bug report captures
+
+Everything below is kept **in memory only**, is **masked in the browser before it is kept**, and leaves the page
+**only when the person sends a bug report**. The reporter can untick "Attach the request log and recent steps"
+before sending. The network log, steps and session links are visible **to the project team only** (not to the
+reporter on the board, not in webhooks or GitHub issues); the Ozvi server masks and bounds them again.
+
+| What | Detail | Never |
+|---|---|---|
+| Page | URL (masked), app version, browser, window size, language | |
+| Screenshot | visible viewport without the widget; private data **covered with solid boxes before the image is made** (see [Screenshot privacy](#screenshot-privacy)); the reporter can mark it up, blur more (burned into the pixels) or remove it | form values, e-mails, phone numbers, IBANs, card numbers, tokens, `[data-ozvi-mask]` |
+| Console errors | last 20, 300 characters each | |
+| Network log | last 30 `fetch`/`XMLHttpRequest` calls: method, URL, status, duration, size, failed flag | request/response headers (so no `Authorization`, no `Cookie`); bodies unless you turn them on |
+| Request bodies | only with `networkBodies: true`, only for **failed** requests, masked, max 2 000 characters each | bodies of successful requests |
+| Steps | last 30: route changes, clicks on buttons/links/tabs by accessible name, form submits by form name | what anyone typed: input, textarea and select values are never read |
+| Session links | Sentry replay, PostHog session, LogRocket session, when you pass them or allow detection | |
+
+**Masking** (in `@ozvi/sdk/mask`, the same code runs in the browser and on the server):
+
+- query/fragment parameters, JSON keys (at any depth) and form fields whose **name** matches
+  `token|secret|passw|pwd|key|auth|session|card|iban|cvv|cvc|otp|signature|cookie|csrf|xsrf|jwt|bearer|ssn|credential`
+  get the value `***`;
+- in any value: JWTs, `Bearer`/`Basic` credentials, e-mail addresses, IBANs and card numbers (Luhn-checked) become `***`;
+- `user:password@` is removed from URLs;
+- clicks inside `[data-ozvi-mask]` are logged as `***`, and masked parts of a button's text are replaced by `***`.
+
+Requests to Ozvi itself and to your `token-url` are never logged.
+
+## Screenshot privacy
+
+The screenshot is drawn from a **copy** of the page that the widget edits first; the page the person
+sees is never touched, and what is covered never becomes pixels (covered text is drawn transparent on a
+solid box, covered images are not drawn). Nothing to set up for the common cases:
+
+| Covered automatically | How |
+|---|---|
+| Values of every `input`, `textarea`, `select` and `contenteditable` | shown as `•••••` or a box; checkboxes and radios keep their state |
+| E-mail addresses, phone numbers (9–15 digits), IBANs, card numbers (Luhn-checked), JWTs and `Bearer`/`Basic` credentials in any text | the match is boxed, the rest of the sentence stays readable |
+| Everything inside `[data-ozvi-mask]` | text, images, canvas and video of the element, boxed |
+
+Shapes can't find everything: **mark names, notes, diagnoses, amounts or anything else private** with
+`data-ozvi-mask`:
+
+```html
+<td data-ozvi-mask>Jana Kováčová</td>
+<p data-ozvi-mask>{{ client.note }}</p>
+```
+
+For apps where almost everything on screen is private (health, finance, HR), cover **all** text and
+images and reveal only the parts that help the team, such as navigation and headings:
+
+```js
+window.OzviConfig = { mask: "all" };
+```
+```html
+<nav data-ozvi-unmask>…</nav>
+<h1 data-ozvi-unmask>Invoice settings</h1>
+```
+
+If the copy can't be masked (an unexpected error), the report goes **without** a screenshot, never with
+an unmasked one. The reporter still sees the screenshot before sending and can remove it.
+
+## Configuration
+
+Simple switches as attributes:
+
+| Attribute | Effect |
+|---|---|
+| `network="off"` | no network log |
+| `network="bodies"` | also keep masked bodies of failed requests |
+| `actions="off"` | no step timeline |
+| `links="auto"` | detect Sentry / PostHog / LogRocket session links from their globals |
+
+Everything else via `window.OzviConfig` (set it **before** `widget.js` so the first requests are covered) or
+`Ozvi.configure({...})` later:
+
+```js
+window.OzviConfig = {
+  network: true,          // false = no network log
+  networkBodies: false,   // true = masked bodies of failed requests (max 2 000 chars)
+  actions: true,          // false = no step timeline
+  // Last word on every logged request, after the built-in masking (which runs again afterwards).
+  // Return the entry (changed or not), or null to drop it.
+  maskRequest(entry) {
+    if (entry.url.includes("/internal/")) return null;
+    return { ...entry, url: entry.url.replace(/\/customers\/\d+/, "/customers/:id") };
+  },
+  // Session links shown to the team as buttons; a function is called when the report is sent.
+  links: {
+    sentry: () => `https://acme.sentry.io/replays/${Sentry.getReplay()?.getReplayId()}/`,
+    posthog: () => posthog.get_session_replay_url({ withTimestamp: true }),
+    logrocket: () => LogRocket.sessionURL,
+  },
+  detectLinks: false,     // true = read them from window.Sentry / posthog / LogRocket yourself
+  sentryOrg: "acme",      // needed for the detected Sentry replay URL (https://<org>.sentry.io/replays/<id>/)
+  mask: "auto",           // "all" = screenshots cover all text and images except [data-ozvi-unmask]
+};
+```
+
+A `maskRequest` that throws drops the entry (it never leaks what it meant to hide). Only `http(s)` session links
+are accepted.
+
+## Screenshot mark-up
+
+"Mark up" on the screenshot opens the editor (`widget-annotate.js`, ~4 kB gzip, loaded on click): box, arrow,
+highlight, blur. Keyboard: pick a tool, focus the image, **Enter** adds the shape in the middle, **arrows** move it,
+**Shift+arrows** resize it, **Delete** removes it, **Ctrl/Cmd+Z** undoes, **Escape** or "Use as is" skips the mark-up.
+The marked-up JPEG replaces the original, so blurred areas never leave the browser.

package/dist/capture.d.ts

@@ -0,0 +1,94 @@
+/**
+ * What the widget remembers so the team can reproduce a bug: the last requests (network log), the last
+ * user actions (route changes, clicks by accessible name, form submits) and console errors.
+ * Everything is masked BEFORE it is kept, lives only in memory, and leaves the page only with a bug report.
+ *
+ * Host app configuration (set before widget.js loads, or later via Ozvi.configure):
+ *   window.OzviConfig = {
+ *     network: false,              // no network log
+ *     networkBodies: true,         // also keep bodies of FAILED requests (masked, max 2 000 chars)
+ *     actions: false,              // no action timeline
+ *     maskRequest: (e) => e,       // last word on every request: change it, or return null to drop it
+ *     links: { sentry: () => url, posthog: url, logrocket: url },
+ *     detectLinks: true,           // read session links from Sentry/PostHog/LogRocket globals
+ *     sentryOrg: "acme",           // needed to build the Sentry replay URL
+ *   }
+ * Attributes on <ozvi-widget> do the same for the simple cases: network="off|bodies", actions="off", links="auto".
+ */
+export interface NetEntry {
+    at: number;
+    method: string;
+    url: string;
+    status: number;
+    ms: number;
+    failed: boolean;
+    size?: number;
+    type?: string;
+    error?: string;
+    req?: string;
+    res?: string;
+}
+export interface Action {
+    at: number;
+    kind: "nav" | "click" | "submit";
+    label: string;
+    role?: string;
+}
+export interface LogLine {
+    at: number;
+    text: string;
+}
+export type LinkKind = "sentry" | "posthog" | "logrocket";
+export interface OzviConfig {
+    network?: boolean;
+    networkBodies?: boolean;
+    actions?: boolean;
+    maskRequest?: (e: NetEntry) => NetEntry | null | false | undefined | void;
+    links?: Partial<Record<LinkKind, string | (() => string | null | undefined)>>;
+    detectLinks?: boolean;
+    sentryOrg?: string;
+}
+export declare const MAX_NET = 30;
+export declare const MAX_ACTIONS = 30;
+export declare const MAX_ERRORS = 20;
+export declare const BODY_LIMIT = 2000;
+/** Fixed-size buffer: the oldest entry falls out. */
+export declare function ring<T>(max: number): {
+    push(x: T): void;
+    list: () => T[];
+    clear(): void;
+};
+export declare const net: {
+    push(x: NetEntry): void;
+    list: () => NetEntry[];
+    clear(): void;
+};
+export declare const actions: {
+    push(x: Action): void;
+    list: () => Action[];
+    clear(): void;
+};
+export declare const errors: {
+    push(x: LogLine): void;
+    list: () => LogLine[];
+    clear(): void;
+};
+/** URL prefixes never logged: the Ozvi host and the host app's token endpoint (its response IS a token). */
+export declare const ignored: string[];
+/** Built-in masking, then the host's maskRequest hook, then masking again (the hook may add data). */
+export declare function finish(e: NetEntry): void;
+export declare function installNetwork(): void;
+/** The accessible name of a clicked control, never an input's value (except button-like inputs, whose value IS the label). */
+export declare function nameOf(el: Element): string;
+export declare function installActions(): void;
+export declare function installErrors(): void;
+/** Session links the host set, plus (only when allowed) the ones its Sentry / PostHog / LogRocket expose. */
+export declare function sessionLinks(): Partial<Record<LinkKind, string>>;
+/** What goes into a bug report's context; respects the opt-outs at the moment of sending too. */
+export declare function snapshot(): {
+    network: NetEntry[];
+    actions: Action[];
+    errors: LogLine[];
+    links: Partial<Record<LinkKind, string>>;
+};
+export declare function install(): void;

package/dist/chunk-O2YKRMB5.js

@@ -0,0 +1,67 @@
+// src/loader.ts
+var METHODS = ["init", "open", "close", "toggle", "isOpen", "prefill", "identify", "logout", "setTraits", "setLanguage", "on", "off", "configure"];
+var inBrowser = () => typeof window !== "undefined" && typeof document !== "undefined";
+function getOzvi() {
+  if (!inBrowser()) return null;
+  const w = window;
+  if (!w.Ozvi) {
+    const stub = function(...a) {
+      stub.q.push(a);
+    };
+    stub.q = [];
+    for (const m of METHODS) stub[m] = (...a) => {
+      stub.q.push([m, ...a]);
+    };
+    stub.ready = new Promise((res) => stub.q.push(["ready", res]));
+    w.Ozvi = stub;
+  }
+  return w.Ozvi;
+}
+var loading = null;
+function loadOzvi(opts = {}) {
+  if (!inBrowser()) return Promise.reject(new Error("loadOzvi() runs in the browser; call it from an effect"));
+  const w = window;
+  const { src, nonce, config, ...init } = opts;
+  if (config || nonce) w.OzviConfig = { ...w.OzviConfig, ...config, ...nonce && { nonce } };
+  const api = getOzvi();
+  if (init.project) api.init(init);
+  if (!loading) {
+    const url = src ?? `${(init.host ?? "").replace(/\/$/, "")}/widget.js`;
+    loading = new Promise((res, rej) => {
+      const existing = document.querySelector(`script[src="${url}"]`);
+      if (existing && window.Ozvi && "version" in window.Ozvi) return res();
+      const s = existing ?? document.createElement("script");
+      s.addEventListener("load", () => res());
+      s.addEventListener("error", () => {
+        loading = null;
+        rej(new Error(`Ozvi widget.js could not load from ${url}`));
+      });
+      if (!existing) {
+        s.src = url;
+        s.async = true;
+        if (nonce) s.nonce = nonce;
+        document.head.appendChild(s);
+      }
+    }).then(() => window.Ozvi.ready);
+  }
+  return loading;
+}
+var ozvi = Object.fromEntries(
+  METHODS.map((m) => [m, (...a) => {
+    const api = getOzvi();
+    if (!api) return m === "on" ? () => {
+    } : m === "isOpen" ? false : void 0;
+    if (m === "on" && !("version" in api)) {
+      api.on(...a);
+      return () => getOzvi().off(...a);
+    }
+    if (m === "isOpen" && !("version" in api)) return false;
+    return api[m](...a);
+  }])
+);
+
+export {
+  getOzvi,
+  loadOzvi,
+  ozvi
+};

package/dist/loader.d.ts

@@ -0,0 +1,33 @@
+import type { OzviApi, OzviConfig, OzviOptions } from "./types";
+/**
+ * @ozvi/widget — plain ESM entry. Loads widget.js from your Ozvi host once and gives you the API.
+ * Safe to import during server rendering: nothing touches `window` until you call a function in the browser,
+ * and on the server every call is a no-op.
+ *
+ *   import { loadOzvi, ozvi } from "@ozvi/widget";
+ *   loadOzvi({ host: "https://feedback.example.com", project: "acme", tokenUrl: "/api/ozvi-token" });
+ *   ozvi.open("ideas");           // queued until widget.js has loaded
+ */
+export type * from "./types";
+export interface LoadOptions extends Partial<OzviOptions> {
+    /** URL of widget.js; default `${host}/widget.js`. */
+    src?: string;
+    /** CSP nonce for the <script> (and everything the widget adds after it). */
+    nonce?: string;
+    /** window.OzviConfig (network log, masking hooks, session links), applied before widget.js runs. */
+    config?: OzviConfig;
+}
+/** window.Ozvi, or the snippet stub that queues calls until widget.js replaces it. */
+export declare function getOzvi(): OzviApi | null;
+/**
+ * Adds widget.js (once) and, with `project`, an <ozvi-widget> (Ozvi.init). Resolves with window.Ozvi when ready.
+ * Rejects on the server and when the script cannot load (CSP, network).
+ */
+export declare function loadOzvi(opts?: LoadOptions): Promise<OzviApi>;
+/**
+ * The API without waiting: every call goes to window.Ozvi (queued before widget.js loads, no-op on the server).
+ * `on` returns an unsubscribe function in the browser.
+ */
+export declare const ozvi: Omit<OzviApi, "ready" | "version" | "isOpen"> & {
+    isOpen(): boolean;
+};

package/dist/loader.js

@@ -0,0 +1,10 @@
+import {
+  getOzvi,
+  loadOzvi,
+  ozvi
+} from "./chunk-O2YKRMB5.js";
+export {
+  getOzvi,
+  loadOzvi,
+  ozvi
+};

package/dist/react.d.ts

@@ -0,0 +1,44 @@
+import { type ReactElement } from "react";
+import { type LoadOptions } from "./loader";
+import type { OzviEventName, OzviListener, OzviOptions } from "./types";
+/**
+ * @ozvi/widget/react — hook and components. Works with SSR (Next.js App Router and Pages): nothing runs on the
+ * server except rendering the custom element tags; widget.js loads in an effect. Mark files that use the hooks
+ * with "use client" in the App Router.
+ *
+ *   <OzviWidget host="https://feedback.example.com" project="acme" tokenUrl="/api/ozvi-token" />
+ *   const ozvi = useOzvi(); ozvi.open("ideas");
+ *   <OzviChangelog host="https://feedback.example.com" project="acme" limit={3} />
+ */
+export * from "./loader";
+/** The API (stable object; calls before widget.js loads are queued). */
+export declare function useOzvi(): Omit<import("./types").OzviApi, "isOpen" | "ready" | "version"> & {
+    isOpen(): boolean;
+};
+/** Subscribes to a widget event for the lifetime of the component. */
+export declare function useOzviEvent<E extends OzviEventName>(event: E, handler: OzviListener<E>): void;
+export type OzviWidgetProps = OzviOptions & Pick<LoadOptions, "src" | "nonce" | "config">;
+/** The floating widget: renders <ozvi-widget> and loads widget.js once. */
+export declare function OzviWidget({ src, nonce, config, ...opts }: OzviWidgetProps): ReactElement;
+export interface OzviEmbedProps {
+    project: string;
+    host?: string;
+    lang?: "sk" | "cs" | "en";
+    heading?: string;
+    tokenUrl?: string;
+    src?: string;
+    nonce?: string;
+    className?: string;
+}
+/** Inline roadmap: planned / in progress / shipped, `limit` cards per lane. */
+export declare function OzviRoadmap(props: OzviEmbedProps & {
+    limit?: number;
+    lanes?: string;
+}): ReactElement;
+/** Inline changelog (latest `limit` entries) or, with mode="badge", a "What's new" button with the unseen count. */
+export declare function OzviChangelog({ onUnseen, ...props }: OzviEmbedProps & {
+    limit?: number;
+    mode?: "list" | "badge";
+    align?: "start" | "end";
+    onUnseen?: (count: number) => void;
+}): ReactElement;

package/dist/react.js

@@ -0,0 +1,55 @@
+import {
+  getOzvi,
+  loadOzvi,
+  ozvi
+} from "./chunk-O2YKRMB5.js";
+
+// src/react.ts
+import { createElement, useEffect, useRef } from "react";
+var kebab = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => v != null && v !== "").map(([k, v]) => [k.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`), String(v)]));
+function useOzvi() {
+  return ozvi;
+}
+function useOzviEvent(event, handler) {
+  const ref = useRef(handler);
+  ref.current = handler;
+  useEffect(() => ozvi.on(event, ((d) => ref.current(d))), [event]);
+}
+function OzviWidget({ src, nonce, config, ...opts }) {
+  useEffect(() => {
+    loadOzvi({ src, nonce, config, host: opts.host }).catch((e) => console.warn(e));
+  }, [src, opts.host]);
+  return createElement("ozvi-widget", { ...kebab(opts), suppressHydrationWarning: true });
+}
+function embed(tag, props, ref) {
+  const { src, nonce, className, ...rest } = props;
+  useEffect(() => {
+    loadOzvi({ src, nonce, host: rest.host }).catch((e) => console.warn(e));
+  }, [src, rest.host]);
+  return createElement(tag, { ...kebab(rest), class: className, ref, suppressHydrationWarning: true });
+}
+function OzviRoadmap(props) {
+  return embed("ozvi-roadmap", props);
+}
+function OzviChangelog({ onUnseen, ...props }) {
+  const cb = useRef(onUnseen);
+  cb.current = onUnseen;
+  const el = useRef(null);
+  useEffect(() => {
+    const node = el.current;
+    const h = (e) => cb.current?.(e.detail.count);
+    node?.addEventListener("ozvi:unseen", h);
+    return () => node?.removeEventListener("ozvi:unseen", h);
+  }, []);
+  return embed("ozvi-changelog", props, el);
+}
+export {
+  OzviChangelog,
+  OzviRoadmap,
+  OzviWidget,
+  getOzvi,
+  loadOzvi,
+  ozvi,
+  useOzvi,
+  useOzviEvent
+};

package/dist/types.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Public types of the Ozvi widget JavaScript API (window.Ozvi, the <ozvi-widget> element, @ozvi/widget,
+ * @ozvi/widget/react, @ozvi/widget/vue). Type-only: nothing here ends up in widget.js.
+ */
+export interface NetEntry {
+    at: number;
+    method: string;
+    url: string;
+    status: number;
+    ms: number;
+    failed: boolean;
+    size?: number;
+    type?: string;
+    error?: string;
+    req?: string;
+    res?: string;
+}
+export type LinkKind = "sentry" | "posthog" | "logrocket";
+/** window.OzviConfig / Ozvi.configure(): what bug reports capture (README, "Configuration"). */
+export interface OzviConfig {
+    network?: boolean;
+    networkBodies?: boolean;
+    actions?: boolean;
+    maskRequest?: (e: NetEntry) => NetEntry | null | false | undefined | void;
+    links?: Partial<Record<LinkKind, string | (() => string | null | undefined)>>;
+    detectLinks?: boolean;
+    sentryOrg?: string;
+    /**
+     * Screenshot privacy. "auto" (default): form values, e-mails, phone numbers, IBANs, card numbers, tokens and
+     * [data-ozvi-mask] are covered. "all": every text and image is covered except inside [data-ozvi-unmask].
+     */
+    mask?: "auto" | "all";
+    /** CSP nonce for scripts and styles the widget adds (default: the nonce of the widget.js <script>). */
+    nonce?: string;
+}
+export type OzviLang = "sk" | "cs" | "en" | "pl" | "hu" | "de";
+/** Which part of the widget to open. "mine" opens the person's reports on the board in a new tab. */
+export type OzviTab = "menu" | "bug" | "ideas" | "idea" | "mine";
+export interface OzviPrefill {
+    title?: string;
+    body?: string;
+    /** Which form the text goes to; default "bug". */
+    kind?: "bug" | "idea";
+}
+/** Something that returns a fresh signOzviToken() value from your backend. */
+export type OzviTokenSource = string | (() => string | Promise<string>);
+export interface OzviIdentity {
+    /** A signOzviToken() value or a function returning one. Without it the widget asks `token-url`. */
+    token?: OzviTokenSource;
+    /** Your user id; only used to remember, per person, which changelog entries they have seen. */
+    id?: string;
+}
+/** Shown to the team with bug reports as "Page data (unverified)". Signed traits belong in the SSO token. */
+export type OzviTraits = Record<string, string | number | boolean | null | undefined>;
+export interface OzviEvents {
+    open: {
+        tab: OzviTab;
+    };
+    close: Record<string, never>;
+    submit: {
+        kind: "bug" | "idea";
+        title: string;
+    };
+    /** The report or idea was saved. `pending` is set when it waits for the team's approval. */
+    submitted: {
+        kind: "bug" | "idea";
+        number: number;
+        url: string;
+        pending: string | null;
+    };
+    error: {
+        kind?: "bug" | "idea" | "vote";
+        message: string;
+    };
+}
+export type OzviEventName = keyof OzviEvents;
+export type OzviListener<E extends OzviEventName> = (detail: OzviEvents[E]) => void;
+/** What init() / loadOzvi() / <OzviWidget> accept: the <ozvi-widget> attributes in camelCase. */
+export interface OzviOptions {
+    project: string;
+    /** Ozvi base URL; defaults to where widget.js was loaded from. */
+    host?: string;
+    /** Same-origin endpoint of your app returning {"token": "..."} (preferred: always fresh). */
+    tokenUrl?: string;
+    token?: string;
+    appVersion?: string;
+    /** "none" hides the floating button; open it with Ozvi.open(). */
+    launcher?: "none" | "button";
+    lang?: OzviLang;
+    label?: string;
+    network?: "off" | "bodies";
+    actions?: "off";
+    links?: "auto";
+}
+export interface OzviApi {
+    /** Snippet-style call: Ozvi("open", "ideas"). */
+    (method: string, ...args: unknown[]): unknown;
+    readonly version: string;
+    /** Resolves once widget.js has loaded and calls queued before that have run. */
+    readonly ready: Promise<OzviApi>;
+    /** Adds an <ozvi-widget> to the page (once) and returns it. */
+    init(options: OzviOptions): HTMLElement;
+    open(tab?: OzviTab): void;
+    close(): void;
+    toggle(tab?: OzviTab): void;
+    isOpen(): boolean;
+    /** Text for the next bug report or idea form; null clears it. */
+    prefill(p: OzviPrefill | null): void;
+    identify(who: OzviTokenSource | OzviIdentity): void;
+    /** Forgets the identity and any cached token (call it when the person signs out of your app). */
+    logout(): void;
+    setTraits(traits: OzviTraits): void;
+    setLanguage(lang: OzviLang): void;
+    on<E extends OzviEventName>(event: E, fn: OzviListener<E>): () => void;
+    off<E extends OzviEventName>(event: E, fn: OzviListener<E>): void;
+    configure(c: OzviConfig): void;
+}

package/dist/vue.d.ts

@@ -0,0 +1,83 @@
+import { type App, type PropType } from "vue";
+import { type LoadOptions } from "./loader";
+import type { OzviEventName, OzviListener } from "./types";
+/**
+ * @ozvi/widget/vue — plugin, composables and components. SSR-safe (Nuxt): widget.js loads only in the browser.
+ *
+ *   app.use(OzviPlugin, { host: "https://feedback.example.com", project: "acme", tokenUrl: "/api/ozvi-token" });
+ *   const ozvi = useOzvi(); ozvi.open("ideas");
+ *   <OzviChangelog host="https://feedback.example.com" project="acme" :limit="3" />
+ *
+ * Using the <ozvi-*> tags directly in templates? Tell Vue they are custom elements:
+ * compilerOptions.isCustomElement = (tag) => tag.startsWith("ozvi-").
+ */
+export * from "./loader";
+/** app.use(OzviPlugin, options): loads widget.js and adds the floating widget (when `project` is given). */
+export declare const OzviPlugin: {
+    install(app: App, opts?: LoadOptions): void;
+};
+export declare const useOzvi: () => Omit<import("./types").OzviApi, "isOpen" | "ready" | "version"> & {
+    isOpen(): boolean;
+};
+/** Subscribes to a widget event while the calling component is mounted. */
+export declare function useOzviEvent<E extends OzviEventName>(event: E, handler: OzviListener<E>): void;
+/** Inline roadmap: planned / in progress / shipped. */
+export declare const OzviRoadmap: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    project: {
+        type: StringConstructor;
+        required: boolean;
+    };
+    host: StringConstructor;
+    lang: StringConstructor;
+    heading: StringConstructor;
+    tokenUrl: StringConstructor;
+    src: StringConstructor;
+    nonce: StringConstructor;
+    limit: PropType<number | string>;
+}>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, "unseen"[], "unseen", import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+    project: {
+        type: StringConstructor;
+        required: boolean;
+    };
+    host: StringConstructor;
+    lang: StringConstructor;
+    heading: StringConstructor;
+    tokenUrl: StringConstructor;
+    src: StringConstructor;
+    nonce: StringConstructor;
+    limit: PropType<number | string>;
+}>> & Readonly<{
+    onUnseen?: ((...args: any[]) => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+/** Inline changelog or, with mode="badge", a "What's new" button with the unseen count (emits `unseen`). */
+export declare const OzviChangelog: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    project: {
+        type: StringConstructor;
+        required: boolean;
+    };
+    host: StringConstructor;
+    lang: StringConstructor;
+    heading: StringConstructor;
+    tokenUrl: StringConstructor;
+    src: StringConstructor;
+    nonce: StringConstructor;
+    limit: PropType<number | string>;
+}>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, "unseen"[], "unseen", import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+    project: {
+        type: StringConstructor;
+        required: boolean;
+    };
+    host: StringConstructor;
+    lang: StringConstructor;
+    heading: StringConstructor;
+    tokenUrl: StringConstructor;
+    src: StringConstructor;
+    nonce: StringConstructor;
+    limit: PropType<number | string>;
+}>> & Readonly<{
+    onUnseen?: ((...args: any[]) => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;

package/dist/vue.js

@@ -0,0 +1,61 @@
+import {
+  getOzvi,
+  loadOzvi,
+  ozvi
+} from "./chunk-O2YKRMB5.js";
+
+// src/vue.ts
+import { defineComponent, h, onBeforeUnmount, onMounted, ref } from "vue";
+var OzviPlugin = {
+  install(app, opts = {}) {
+    app.config.globalProperties.$ozvi = ozvi;
+    if (typeof window !== "undefined") loadOzvi(opts).catch((e) => console.warn(e));
+  }
+};
+var useOzvi = () => ozvi;
+function useOzviEvent(event, handler) {
+  let off;
+  onMounted(() => {
+    off = ozvi.on(event, handler);
+  });
+  onBeforeUnmount(() => off?.());
+}
+var common = {
+  project: { type: String, required: true },
+  host: String,
+  lang: String,
+  heading: String,
+  tokenUrl: String,
+  src: String,
+  nonce: String,
+  limit: [Number, String]
+};
+var attrs = (p) => Object.fromEntries(Object.entries(p).filter(([k, v]) => v != null && v !== "" && k !== "src" && k !== "nonce").map(([k, v]) => [k.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`), String(v)]));
+function embed(tag, extra) {
+  return defineComponent({
+    props: { ...common, ...extra },
+    emits: ["unseen"],
+    setup(props, { emit }) {
+      const el = ref(null);
+      const onUnseen = (e) => emit("unseen", e.detail.count);
+      onMounted(() => {
+        loadOzvi({ src: props.src, nonce: props.nonce, host: props.host }).catch((e) => console.warn(e));
+        el.value?.addEventListener("ozvi:unseen", onUnseen);
+      });
+      onBeforeUnmount(() => el.value?.removeEventListener("ozvi:unseen", onUnseen));
+      return () => h(tag, { ...attrs(props), ref: el });
+    }
+  });
+}
+var OzviRoadmap = embed("ozvi-roadmap", { lanes: String });
+var OzviChangelog = embed("ozvi-changelog", { mode: String, align: String });
+export {
+  OzviChangelog,
+  OzviPlugin,
+  OzviRoadmap,
+  getOzvi,
+  loadOzvi,
+  ozvi,
+  useOzvi,
+  useOzviEvent
+};

package/package.json

@@ -1,6 +1,70 @@
 {
   "name": "@ozvi/widget",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "license": "MIT",
+  "description": "Ozvi feedback widget for your app: bug reports with masked screenshots, ideas and voting, roadmap and changelog embeds. Plain ESM, React and Vue. MIT.",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/loader.d.ts",
+      "import": "./dist/loader.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    },
+    "./vue": {
+      "types": "./dist/vue.d.ts",
+      "import": "./dist/vue.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "react": ">=18",
+    "vue": ">=3.3"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "19.3.0",
+    "esbuild": "^0.28.2",
+    "happy-dom": "20.0.10",
+    "modern-screenshot": "^4.7.0",
+    "preact": "^10.29.8",
+    "react": "19.3.1",
+    "vue": "3.5.45"
+  },
+  "homepage": "https://ozvi.io/docs/widget",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xzamiska/ozvi.git",
+    "directory": "packages/widget"
+  },
+  "keywords": [
+    "feedback",
+    "bug-report",
+    "widget",
+    "roadmap",
+    "changelog",
+    "ozvi"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "typecheck": "tsc -p .",
+    "test": "vitest run"
+  }
 }