@universelle/sentinel-report 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Universelle
+
+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,164 @@
-# Temporary Holding Version
+# @universelle/sentinel-report
 
-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.
+[SENTINEL](https://sentinel.cervilla.es)'s report button: let real users tell you **what fails** («Algo falla») or
+**what they miss** («Echo en falta…»), with the technical context of their visit.
+
+With the user's text it sends only:
+
+- the page's **path**, never its query string or fragment, which can carry tokens;
+- the browser: user agent, language, viewport and screen;
+- the visit's last **console errors and warnings**;
+- the visit's **failed requests**: path and status;
+- the **pages visited**, including client-side navigation.
+
+It never sends anything typed into your site. The receiving SENTINEL only accepts reports from the site's own origin,
+with rate limits.
+
+```sh
+npm i @universelle/sentinel-report
+```
+
+## The ready-made button (any site or framework)
+
+```js
+import "@universelle/sentinel-report/element";
+```
+
+```html
+<sentinel-report site="your-site"></sentinel-report>
+```
+
+Or with no install, one line in your `<head>`:
+
+```html
+<script src="https://sentinel.cervilla.es/widget.js" data-site="your-site" async></script>
+```
+
+### Attributes
+
+| Attribute | Values |
+|---|---|
+| `site` | Your site's name in SENTINEL (required). |
+| `endpoint` | Another SENTINEL (default `https://sentinel.cervilla.es`). |
+| `label`, `heading` | Text of the button and of the panel's title. |
+| `position` | `bottom-right` (default), `bottom-left`, `inline`. |
+| `theme` | `auto` (default, follows the system), `light`, `dark`. |
+| `hide-mark` | Hides SENTINEL's mark on the button. |
+
+For any other word (for example another language), set the `texts` property:
+`element.texts = { heading: "Tell us", send: "Send" }`.
+
+### Styling
+
+Set CSS custom properties on the element:
+
+| Property | What it styles |
+|---|---|
+| `--sentinel-accent`, `--sentinel-accent-fg` | The button and the selected option. |
+| `--sentinel-bg`, `--sentinel-fg`, `--sentinel-muted`, `--sentinel-line` | The panel. |
+| `--sentinel-ok`, `--sentinel-error` | The status messages. |
+| `--sentinel-radius`, `--sentinel-font`, `--sentinel-offset`, `--sentinel-z` | Corners, font, distance to the edge, stacking. |
+
+Any piece can also be styled with `::part()`: `button`, `mark`, `label`, `panel`, `header`, `title`, `close`, `kinds`,
+`kind`, `text`, `email`, `note`, `send` and `status`.
+
+```css
+sentinel-report {
+  --sentinel-accent: #1f7a3f;
+  --sentinel-radius: 6px;
+}
+sentinel-report::part(panel) {
+  border: 2px solid #1f7a3f;
+}
+```
+
+### Your own trigger
+
+Put any element in the `trigger` slot. Clicking it opens the panel, and the default button isn't shown:
+
+```html
+<sentinel-report site="your-site" position="inline">
+  <a slot="trigger" href="#report">Report a problem with this page</a>
+</sentinel-report>
+```
+
+### Events and methods
+
+- Events: `sentinel-sent` (`detail.kind`) and `sentinel-error` (`detail.error`). Both bubble and are composed.
+- Methods: `open()` and `close()`.
+
+## React
+
+```tsx
+import { ReportButton } from "@universelle/sentinel-report/react";
+
+<ReportButton
+  site="your-site"
+  label="Give us your opinion"
+  style={{ "--sentinel-accent": "#6b3fc4" }}
+  onSent={(kind) => track("report", kind)}
+/>
+
+// Your own trigger:
+<ReportButton site="your-site" position="inline">
+  <a href="#report">Report a problem</a>
+</ReportButton>
+```
+
+### Your own form
+
+`useSentinelReport` records the visit and sends; the design is all yours:
+
+```tsx
+import { useSentinelReport } from "@universelle/sentinel-report/react";
+
+const { send, status } = useSentinelReport({ site: "your-site" });
+// status: "idle" | "sending" | "sent" | "error"
+await send({ kind: "bug", text, email });
+```
+
+Without React:
+
+```js
+import { createReporter } from "@universelle/sentinel-report";
+
+await createReporter({ site: "your-site" }).send({ kind: "wish", text: "Export the table" });
+```
+
+## Branding: SENTINEL's mark
+
+For your own button, a footer or a "Protected by SENTINEL" line. The eye and the star take the text colour
+(`currentColor`), so the mark works on light and dark backgrounds; the moon is always the brand's green.
+
+```tsx
+import { SentinelMark, useSentinelReport } from "@universelle/sentinel-report/react";
+
+<button onClick={…}>
+  <SentinelMark size={20} /> Report a problem
+</button>
+
+// title makes it an image with a name, for screen readers:
+<SentinelMark size={32} title="SENTINEL" />
+```
+
+Without React:
+
+```html
+<script type="module">import "@universelle/sentinel-report/element";</script>
+<span style="color: #6b3fc4">Made with <sentinel-mark size="20" label="SENTINEL"></sentinel-mark></span>
+```
+
+```js
+import { markSvg, MARK_SHAPES } from "@universelle/sentinel-report";
+
+button.innerHTML = `${markSvg({ size: 20 })} Report`;
+```
+
+`markSvg` gives you the `<svg>` as a string. `MARK_SHAPES` gives you its inside, for your own `<svg viewBox="0 0 100 100">`.
+
+## Notes
+
+- **Content Security Policy:** allow `connect-src https://sentinel.cervilla.es`, plus `script-src` if you use the
+  one-line widget.
+- **Load it early.** Context is recorded from the moment the package loads, so errors from before that are not seen.
+- No dependencies. React (≥ 18) is an optional peer.

package/dist/core.d.ts

@@ -0,0 +1,56 @@
+export declare const DEFAULT_ENDPOINT = "https://sentinel.cervilla.es";
+export type ReportKind = "bug" | "wish";
+export type ConsoleEntry = {
+    level: "error" | "warn";
+    message: string;
+    at: string;
+};
+export type FailedRequest = {
+    path: string;
+    status: number;
+};
+/** What goes with the text: the same shape SENTINEL validates. */
+export type Context = {
+    page: {
+        path: string;
+        title: string;
+    };
+    device: {
+        userAgent: string;
+        language: string;
+        viewport: string;
+        screen: string;
+    };
+    console: ConsoleEntry[];
+    network: FailedRequest[];
+    trail: string[];
+};
+export type Report = {
+    kind: ReportKind;
+    text: string;
+    email?: string;
+};
+export type Reporter = {
+    /** Sends a report; rejects with an `Error` whose message is the HTTP status (or the network error). */
+    send(report: Report): Promise<void>;
+    /** What would go with a report right now. */
+    context(): Context;
+};
+type Capture = {
+    logs: ConsoleEntry[];
+    network: FailedRequest[];
+    trail: string[];
+    fetch: typeof fetch;
+};
+declare global {
+    interface Window {
+        __sentinelCapture?: Capture;
+    }
+}
+/** Starts recording the visit's context (once per page; later calls return the same recording). */
+export declare function capture(): Capture;
+export declare function createReporter(options: {
+    site: string;
+    endpoint?: string;
+}): Reporter;
+export {};

package/dist/core.js

@@ -0,0 +1,108 @@
+// The core, with no framework: it records the technical context of the visit (console errors, failed requests,
+// pages visited) and sends a report to SENTINEL. What it never sends: the query string or fragment of any URL (they
+// can carry tokens) or anything typed into the site. Installed once per page, whoever asks first.
+export const DEFAULT_ENDPOINT = "https://sentinel.cervilla.es";
+const MAX = 20;
+function clip(text) {
+    return String(text).replace(/\s+/g, " ").slice(0, 300);
+}
+function pathOf(url) {
+    try {
+        return new URL(url, location.href).pathname;
+    }
+    catch {
+        return "?";
+    }
+}
+function push(list, item) {
+    list.push(item);
+    if (list.length > MAX)
+        list.shift();
+}
+function describe(value) {
+    if (value instanceof Error)
+        return value.message;
+    if (typeof value === "string")
+        return value;
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+function watchConsole(capture) {
+    const pageConsole = window.console;
+    for (const level of ["error", "warn"]) {
+        const original = pageConsole[level];
+        pageConsole[level] = (...args) => {
+            push(capture.logs, { level, message: clip(args.map(describe).join(" ")), at: new Date().toISOString() });
+            original.apply(pageConsole, args);
+        };
+    }
+    window.addEventListener("error", (event) => push(capture.logs, { level: "error", message: clip(event.message || "error"), at: new Date().toISOString() }));
+    window.addEventListener("unhandledrejection", (event) => push(capture.logs, { level: "error", message: clip(describe(event.reason ?? "promesa rechazada")), at: new Date().toISOString() }));
+}
+function watchFetch(capture) {
+    const original = capture.fetch;
+    window.fetch = async (...args) => {
+        const url = args[0] instanceof Request ? args[0].url : String(args[0]);
+        try {
+            const response = await original(...args);
+            if (response.status >= 400)
+                push(capture.network, { path: pathOf(url), status: response.status });
+            return response;
+        }
+        catch (error) {
+            push(capture.network, { path: pathOf(url), status: 0 });
+            throw error;
+        }
+    };
+}
+function watchNavigation(capture) {
+    const visit = () => {
+        if (capture.trail[capture.trail.length - 1] !== location.pathname)
+            push(capture.trail, location.pathname);
+    };
+    for (const method of ["pushState", "replaceState"]) {
+        const original = history[method];
+        history[method] = function (...args) {
+            const result = original.apply(this, args);
+            visit();
+            return result;
+        };
+    }
+    window.addEventListener("popstate", visit);
+}
+/** Starts recording the visit's context (once per page; later calls return the same recording). */
+export function capture() {
+    if (window.__sentinelCapture !== undefined)
+        return window.__sentinelCapture;
+    const recording = { logs: [], network: [], trail: [location.pathname], fetch: window.fetch.bind(window) };
+    window.__sentinelCapture = recording;
+    watchConsole(recording);
+    watchFetch(recording);
+    watchNavigation(recording);
+    return recording;
+}
+export function createReporter(options) {
+    const recording = capture();
+    const url = `${(options.endpoint ?? DEFAULT_ENDPOINT).replace(/\/+$/, "")}/reports/${encodeURIComponent(options.site)}`;
+    const context = () => ({
+        page: { path: location.pathname, title: document.title.slice(0, 200) },
+        device: { userAgent: navigator.userAgent.slice(0, 300), language: navigator.language, viewport: `${innerWidth}x${innerHeight}`, screen: `${screen.width}x${screen.height}` },
+        console: recording.logs.slice(),
+        network: recording.network.slice(),
+        trail: recording.trail.slice(),
+    });
+    return {
+        context,
+        async send(report) {
+            const body = { kind: report.kind, text: report.text.trim(), ...(report.email?.trim() ? { email: report.email.trim() } : {}), ...context() };
+            // With the page's own fetch from before it was watched: SENTINEL's request is not part of the visit.
+            const response = await recording.fetch(url, { method: "POST", mode: "cors", credentials: "omit", keepalive: true, headers: { "content-type": "application/json" }, body: JSON.stringify(body) });
+            if (!response.ok)
+                throw new Error(String(response.status));
+        },
+    };
+}

package/dist/element.d.ts

@@ -0,0 +1,52 @@
+export type Texts = {
+    label: string;
+    heading: string;
+    bug: string;
+    wish: string;
+    bugPlaceholder: string;
+    wishPlaceholder: string;
+    email: string;
+    note: string;
+    send: string;
+    sent: string;
+    failed: string;
+    tooShort: string;
+    close: string;
+};
+export declare const DEFAULT_TEXTS: Texts;
+export declare class SentinelReport extends HTMLElement {
+    static observedAttributes: string[];
+    private reporter;
+    private kind;
+    private custom;
+    private readonly root;
+    constructor();
+    /** Every word of the component; set any of them (e.g. for another language). */
+    get texts(): Texts;
+    set texts(value: Partial<Texts>);
+    connectedCallback(): void;
+    attributeChangedCallback(): void;
+    private get panel();
+    open(): void;
+    close(): void;
+    private render;
+    private wire;
+    private say;
+    private submit;
+}
+/**
+ * `<sentinel-mark size="24" label="…">`: SENTINEL's mark on its own, for your branding without React. It takes the
+ * text colour (`color` on the element); `label` makes it an image with that name, otherwise it is decorative.
+ */
+export declare class SentinelMark extends HTMLElement {
+    static observedAttributes: string[];
+    connectedCallback(): void;
+    attributeChangedCallback(): void;
+    private render;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "sentinel-report": SentinelReport;
+        "sentinel-mark": SentinelMark;
+    }
+}

package/dist/element.js

@@ -0,0 +1,184 @@
+// `<sentinel-report site="…">`: the report button as a web component, for any site or framework. Importing this
+// module defines it. Stylable from outside without touching its insides:
+//   - CSS custom properties: --sentinel-accent, --sentinel-accent-fg (the button), --sentinel-bg, --sentinel-fg,
+//     --sentinel-muted, --sentinel-line (the panel), --sentinel-radius, --sentinel-font, --sentinel-offset, --sentinel-z;
+//   - `::part()`: button, mark, label, panel, header, title, close, kinds, kind, text, email, note, send, status;
+//   - your own trigger, in the `trigger` slot (then the default button isn't shown);
+//   - attributes: site, endpoint, label, heading, position (bottom-right | bottom-left | inline), theme
+//     (auto | light | dark), hide-mark; and the `texts` property for every other word.
+// Events: `sentinel-sent` (detail: { kind }) and `sentinel-error` (detail: { error }). Methods: open(), close().
+import { capture, createReporter } from "./core.js";
+import { markSvg } from "./logo.js";
+import { MARK } from "./mark.js";
+export const DEFAULT_TEXTS = {
+    label: "¿Algo falla?",
+    heading: "Cuéntanos",
+    bug: "Algo falla",
+    wish: "Echo en falta…",
+    bugPlaceholder: "Qué intentabas hacer y qué ha pasado",
+    wishPlaceholder: "Qué te gustaría poder hacer aquí",
+    email: "Tu email, si quieres respuesta (opcional)",
+    note: "Con tu mensaje enviamos la página en la que estás, tu navegador y los errores técnicos de esta visita. Nada de lo que hayas escrito en la web.",
+    send: "Enviar",
+    sent: "Gracias. Lo revisamos.",
+    failed: "No se ha podido enviar. Prueba otra vez en un momento.",
+    tooShort: "Cuéntanos un poco más (al menos 5 letras).",
+    close: "Cerrar",
+};
+const STYLE = `
+:host{--_accent:var(--sentinel-accent,#17201b);--_accent-fg:var(--sentinel-accent-fg,#fff);--_bg:var(--sentinel-bg,#fff);--_fg:var(--sentinel-fg,#17201b);--_muted:var(--sentinel-muted,#69736c);--_line:var(--sentinel-line,#e3e7e2);--_ok:var(--sentinel-ok,#1f7a3f);--_err:var(--sentinel-error,#c4321f);--_radius:var(--sentinel-radius,14px);--_offset:var(--sentinel-offset,16px);
+ position:fixed;right:max(var(--_offset),env(safe-area-inset-right,0px));bottom:max(var(--_offset),env(safe-area-inset-bottom,0px));z-index:var(--sentinel-z,2147483000);display:grid;justify-items:end;gap:10px;font-family:var(--sentinel-font,Inter,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif);color:var(--_fg)}
+:host([position="bottom-left"]){right:auto;left:max(var(--_offset),env(safe-area-inset-left,0px));justify-items:start}
+:host([position="inline"]){position:static;justify-items:start}
+@media (prefers-color-scheme:dark){:host(:not([theme="light"])){--_bg:var(--sentinel-bg,#1a201c);--_fg:var(--sentinel-fg,#e8ece8);--_muted:var(--sentinel-muted,#9aa49d);--_line:var(--sentinel-line,#2c342e);--_ok:var(--sentinel-ok,#5cc983);--_err:var(--sentinel-error,#ff6b57)}}
+:host([theme="dark"]){--_bg:var(--sentinel-bg,#1a201c);--_fg:var(--sentinel-fg,#e8ece8);--_muted:var(--sentinel-muted,#9aa49d);--_line:var(--sentinel-line,#2c342e);--_ok:var(--sentinel-ok,#5cc983);--_err:var(--sentinel-error,#ff6b57)}
+*{box-sizing:border-box;font-family:inherit}
+[hidden]{display:none!important}
+.open{display:inline-flex;align-items:center;gap:8px;border:0;border-radius:99px;padding:9px 16px 9px 12px;background:var(--_accent);color:var(--_accent-fg);font-size:14px;font-weight:600;cursor:pointer;box-shadow:0 4px 18px rgba(0,0,0,.18)}
+.mark{width:28px;height:28px;flex:none;margin:-2px 0}
+:host([hide-mark]) .mark{display:none}
+.panel{width:min(340px,calc(100vw - 32px));background:var(--_bg);color:var(--_fg);border:1px solid var(--_line);border-radius:var(--_radius);box-shadow:0 10px 40px rgba(0,0,0,.2);padding:16px;display:grid;gap:12px}
+.head{display:flex;justify-content:space-between;align-items:center}.title{font-size:15px;font-weight:700;margin:0}
+.x{border:0;background:none;color:var(--_muted);font-size:20px;line-height:1;cursor:pointer;padding:2px 6px}
+.kinds{display:grid;grid-template-columns:1fr 1fr;gap:6px}
+.kind{border:1px solid var(--_line);background:none;color:var(--_fg);border-radius:calc(var(--_radius) - 5px);padding:8px;font-size:13px;cursor:pointer}
+.kind[aria-pressed="true"]{border-color:var(--_accent);background:var(--_accent);color:var(--_accent-fg);font-weight:600}
+textarea,input{width:100%;font-size:14px;padding:9px 10px;border:1px solid var(--_line);border-radius:calc(var(--_radius) - 5px);background:var(--_bg);color:var(--_fg)}
+textarea{min-height:96px;resize:vertical}
+.note{font-size:12px;color:var(--_muted);margin:0;line-height:1.4}
+.send{border:0;border-radius:calc(var(--_radius) - 5px);padding:10px;background:var(--_accent);color:var(--_accent-fg);font-size:14px;font-weight:600;cursor:pointer}
+.send:disabled{opacity:.5;cursor:wait}
+.status{font-size:14px;margin:0}.status.ok{color:var(--_ok)}.status.err{color:var(--_err)}
+`;
+function escape(text) {
+    return text.replace(/[&<>"']/g, (char) => `&#${char.charCodeAt(0)};`);
+}
+export class SentinelReport extends HTMLElement {
+    static observedAttributes = ["site", "endpoint", "label", "heading"];
+    reporter;
+    kind = "bug";
+    custom = {};
+    root;
+    constructor() {
+        super();
+        this.root = this.attachShadow({ mode: "open" });
+    }
+    /** Every word of the component; set any of them (e.g. for another language). */
+    get texts() {
+        return { ...DEFAULT_TEXTS, ...this.custom, ...(this.getAttribute("label") ? { label: this.getAttribute("label") } : {}), ...(this.getAttribute("heading") ? { heading: this.getAttribute("heading") } : {}) };
+    }
+    set texts(value) {
+        this.custom = value;
+        this.render();
+    }
+    connectedCallback() {
+        // Recording starts as soon as the button is on the page, so the report carries the visit's errors.
+        capture();
+        this.render();
+    }
+    attributeChangedCallback() {
+        this.reporter = undefined;
+        if (this.isConnected)
+            this.render();
+    }
+    get panel() {
+        return this.root.querySelector(".panel");
+    }
+    open() {
+        this.panel.hidden = false;
+        this.root.querySelector(".open")?.setAttribute("hidden", "");
+        this.root.querySelector("textarea")?.focus();
+    }
+    close() {
+        this.panel.hidden = true;
+        if (!this.root.querySelector('slot[name="trigger"]')?.assignedElements().length)
+            this.root.querySelector(".open")?.removeAttribute("hidden");
+    }
+    render() {
+        const t = this.texts;
+        this.root.innerHTML = `<style>${STYLE}</style>
+<div class="panel" part="panel" role="dialog" aria-modal="false" aria-label="${escape(t.heading)}" hidden>
+<div class="head" part="header"><p class="title" part="title">${escape(t.heading)}</p><button class="x" part="close" aria-label="${escape(t.close)}">×</button></div>
+<div class="kinds" part="kinds" role="group"><button class="kind" part="kind" data-kind="bug" aria-pressed="${this.kind === "bug"}">${escape(t.bug)}</button><button class="kind" part="kind" data-kind="wish" aria-pressed="${this.kind === "wish"}">${escape(t.wish)}</button></div>
+<textarea part="text" maxlength="2000" aria-label="${escape(t.heading)}" placeholder="${escape(this.kind === "bug" ? t.bugPlaceholder : t.wishPlaceholder)}"></textarea>
+<input part="email" type="email" maxlength="200" placeholder="${escape(t.email)}" aria-label="${escape(t.email)}">
+<p class="note" part="note">${escape(t.note)}</p>
+<button class="send" part="send">${escape(t.send)}</button><p class="status" part="status" role="status" hidden></p>
+</div>
+<slot name="trigger"><button class="open" part="button" aria-haspopup="dialog">${MARK}<span part="label">${escape(t.label)}</span></button></slot>`;
+        this.wire();
+    }
+    wire() {
+        const $ = (selector) => this.root.querySelector(selector);
+        const slot = $('slot[name="trigger"]');
+        slot.addEventListener("click", () => this.open());
+        $(".x").addEventListener("click", () => this.close());
+        this.panel.addEventListener("keydown", (event) => event.key === "Escape" && this.close());
+        for (const button of this.root.querySelectorAll(".kind")) {
+            button.addEventListener("click", () => {
+                this.kind = button.dataset.kind;
+                for (const other of this.root.querySelectorAll(".kind"))
+                    other.setAttribute("aria-pressed", String(other === button));
+                $("textarea").placeholder = this.kind === "bug" ? this.texts.bugPlaceholder : this.texts.wishPlaceholder;
+            });
+        }
+        $(".send").addEventListener("click", () => void this.submit());
+    }
+    say(message, tone) {
+        const status = this.root.querySelector(".status");
+        status.textContent = message;
+        status.className = `status ${tone}`;
+        status.hidden = false;
+    }
+    async submit() {
+        const text = this.root.querySelector("textarea");
+        const email = this.root.querySelector("input");
+        const send = this.root.querySelector(".send");
+        if (text.value.trim().length < 5)
+            return this.say(this.texts.tooShort, "err");
+        const site = this.getAttribute("site");
+        if (!site)
+            return this.say(this.texts.failed, "err");
+        this.reporter ??= createReporter({ site, endpoint: this.getAttribute("endpoint") ?? undefined });
+        send.disabled = true;
+        try {
+            await this.reporter.send({ kind: this.kind, text: text.value, email: email.value });
+            text.value = "";
+            this.say(this.texts.sent, "ok");
+            this.dispatchEvent(new CustomEvent("sentinel-sent", { detail: { kind: this.kind }, bubbles: true, composed: true }));
+            setTimeout(() => {
+                this.root.querySelector(".status").hidden = true;
+                this.close();
+            }, 2500);
+        }
+        catch (error) {
+            this.say(this.texts.failed, "err");
+            this.dispatchEvent(new CustomEvent("sentinel-error", { detail: { error }, bubbles: true, composed: true }));
+        }
+        finally {
+            send.disabled = false;
+        }
+    }
+}
+/**
+ * `<sentinel-mark size="24" label="…">`: SENTINEL's mark on its own, for your branding without React. It takes the
+ * text colour (`color` on the element); `label` makes it an image with that name, otherwise it is decorative.
+ */
+export class SentinelMark extends HTMLElement {
+    static observedAttributes = ["size", "label"];
+    connectedCallback() {
+        this.render();
+    }
+    attributeChangedCallback() {
+        if (this.isConnected)
+            this.render();
+    }
+    render() {
+        this.style.display ||= "inline-flex";
+        this.innerHTML = markSvg({ size: this.getAttribute("size") ?? "1em", title: this.getAttribute("label") ?? undefined });
+    }
+}
+if (typeof customElements !== "undefined" && customElements.get("sentinel-report") === undefined)
+    customElements.define("sentinel-report", SentinelReport);
+if (typeof customElements !== "undefined" && customElements.get("sentinel-mark") === undefined)
+    customElements.define("sentinel-mark", SentinelMark);

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { capture, createReporter, DEFAULT_ENDPOINT } from "./core.js";
+export { MARK_SHAPES, markSvg } from "./logo.js";
+export type { Context, ConsoleEntry, FailedRequest, Report, ReportKind, Reporter } from "./core.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+// @universelle/sentinel-report: the core, with no framework. For the ready-made button, `…/element` (any site) or
+// `…/react`; to build your own form, `createReporter` here or `useSentinelReport` in React.
+export { capture, createReporter, DEFAULT_ENDPOINT } from "./core.js";
+export { MARK_SHAPES, markSvg } from "./logo.js";

package/dist/logo.d.ts

@@ -0,0 +1,8 @@
+import { MARK_SHAPES } from "./mark.js";
+export { MARK_SHAPES };
+/** The mark as an `<svg>`: decorative by default; with `title`, an image with that name for screen readers. */
+export declare function markSvg(options?: {
+    size?: number | string;
+    title?: string;
+    className?: string;
+}): string;

package/dist/logo.js

@@ -0,0 +1,14 @@
+// SENTINEL's mark for your own branding (a button of your own, a footer…): as an SVG string. The eye and the star take
+// the text colour (currentColor), so it works on light and dark backgrounds; the moon is always the brand's green.
+import { MARK_SHAPES } from "./mark.js";
+export { MARK_SHAPES };
+function escape(text) {
+    return text.replace(/[&<>"']/g, (char) => `&#${char.charCodeAt(0)};`);
+}
+/** The mark as an `<svg>`: decorative by default; with `title`, an image with that name for screen readers. */
+export function markSvg(options = {}) {
+    const size = options.size ?? 24;
+    const label = options.title ? ` role="img" aria-label="${escape(options.title)}"` : ' aria-hidden="true" focusable="false"';
+    const cls = options.className ? ` class="${escape(options.className)}"` : "";
+    return `<svg${cls} viewBox="0 0 100 100" width="${escape(String(size))}" height="${escape(String(size))}"${label}>${options.title ? `<title>${escape(options.title)}</title>` : ""}${MARK_SHAPES}</svg>`;
+}

package/dist/mark.d.ts

@@ -0,0 +1,2 @@
+export declare const MARK_SHAPES = "<path d=\"M14 50 Q50 14 86 50 Q50 86 14 50Z\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"7\" stroke-linejoin=\"round\"/><path d=\"M51.1 40.2 A11 11 0 1 0 59.77 53.22 A7.86 7.86 0 0 1 51.1 40.2Z\" fill=\"#3fbf6f\"/><path d=\"M20.9258 28C20.6615 27.82 20.4223 27.6072 20.2143 27.3671C19.9961 26.9641 19.8024 26.549 19.6343 26.1238C17.3476 21.0763 13.2746 16.9981 8.15841 14.6333C7.94143 14.5501 7.7297 14.4545 7.5243 14.347C6.80512 13.9024 6.82832 13.2921 7.57843 12.84C7.74361 12.7589 7.91411 12.6884 8.08881 12.6291C13.3854 10.5226 17.6112 6.45934 19.8431 1.32691C20.0751 0.814541 20.0906 0.0309247 20.8562 0.000785591C21.6217 -0.0293535 21.7377 0.814541 21.9852 1.35704C23.0822 3.90828 24.6892 6.22141 26.7125 8.16176C28.7358 10.1021 31.135 11.6309 33.7704 12.6592C33.9933 12.7315 34.2104 12.8196 34.42 12.9229C35.1933 13.3524 35.1933 13.925 34.42 14.3621C33.9406 14.6333 33.3992 14.8066 32.8734 15.0628C28.0444 17.4681 24.2329 21.4457 22.1012 26.3047C21.9511 26.6872 21.7755 27.0597 21.5753 27.4198C21.3859 27.6401 21.1675 27.8352 20.9258 28Z\" fill=\"currentColor\" transform=\"translate(57.64 44.71) scale(0.3367) translate(-21 -14)\"/>";
+export declare const MARK = "<svg class=\"mark\" part=\"mark\" viewBox=\"0 0 100 100\" aria-hidden=\"true\" focusable=\"false\"><path d=\"M14 50 Q50 14 86 50 Q50 86 14 50Z\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"7\" stroke-linejoin=\"round\"/><path d=\"M51.1 40.2 A11 11 0 1 0 59.77 53.22 A7.86 7.86 0 0 1 51.1 40.2Z\" fill=\"#3fbf6f\"/><path d=\"M20.9258 28C20.6615 27.82 20.4223 27.6072 20.2143 27.3671C19.9961 26.9641 19.8024 26.549 19.6343 26.1238C17.3476 21.0763 13.2746 16.9981 8.15841 14.6333C7.94143 14.5501 7.7297 14.4545 7.5243 14.347C6.80512 13.9024 6.82832 13.2921 7.57843 12.84C7.74361 12.7589 7.91411 12.6884 8.08881 12.6291C13.3854 10.5226 17.6112 6.45934 19.8431 1.32691C20.0751 0.814541 20.0906 0.0309247 20.8562 0.000785591C21.6217 -0.0293535 21.7377 0.814541 21.9852 1.35704C23.0822 3.90828 24.6892 6.22141 26.7125 8.16176C28.7358 10.1021 31.135 11.6309 33.7704 12.6592C33.9933 12.7315 34.2104 12.8196 34.42 12.9229C35.1933 13.3524 35.1933 13.925 34.42 14.3621C33.9406 14.6333 33.3992 14.8066 32.8734 15.0628C28.0444 17.4681 24.2329 21.4457 22.1012 26.3047C21.9511 26.6872 21.7755 27.0597 21.5753 27.4198C21.3859 27.6401 21.1675 27.8352 20.9258 28Z\" fill=\"currentColor\" transform=\"translate(57.64 44.71) scale(0.3367) translate(-21 -14)\"/></svg>";

package/dist/mark.js

@@ -0,0 +1,4 @@
+// SENTINEL's mark (generated from the main repo's src/brand.ts by `pnpm brand`; do not edit by hand). The eye and
+// the star take the text colour (currentColor); the moon is always the brand's green.
+export const MARK_SHAPES = "<path d=\"M14 50 Q50 14 86 50 Q50 86 14 50Z\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"7\" stroke-linejoin=\"round\"/><path d=\"M51.1 40.2 A11 11 0 1 0 59.77 53.22 A7.86 7.86 0 0 1 51.1 40.2Z\" fill=\"#3fbf6f\"/><path d=\"M20.9258 28C20.6615 27.82 20.4223 27.6072 20.2143 27.3671C19.9961 26.9641 19.8024 26.549 19.6343 26.1238C17.3476 21.0763 13.2746 16.9981 8.15841 14.6333C7.94143 14.5501 7.7297 14.4545 7.5243 14.347C6.80512 13.9024 6.82832 13.2921 7.57843 12.84C7.74361 12.7589 7.91411 12.6884 8.08881 12.6291C13.3854 10.5226 17.6112 6.45934 19.8431 1.32691C20.0751 0.814541 20.0906 0.0309247 20.8562 0.000785591C21.6217 -0.0293535 21.7377 0.814541 21.9852 1.35704C23.0822 3.90828 24.6892 6.22141 26.7125 8.16176C28.7358 10.1021 31.135 11.6309 33.7704 12.6592C33.9933 12.7315 34.2104 12.8196 34.42 12.9229C35.1933 13.3524 35.1933 13.925 34.42 14.3621C33.9406 14.6333 33.3992 14.8066 32.8734 15.0628C28.0444 17.4681 24.2329 21.4457 22.1012 26.3047C21.9511 26.6872 21.7755 27.0597 21.5753 27.4198C21.3859 27.6401 21.1675 27.8352 20.9258 28Z\" fill=\"currentColor\" transform=\"translate(57.64 44.71) scale(0.3367) translate(-21 -14)\"/>";
+export const MARK = "<svg class=\"mark\" part=\"mark\" viewBox=\"0 0 100 100\" aria-hidden=\"true\" focusable=\"false\"><path d=\"M14 50 Q50 14 86 50 Q50 86 14 50Z\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"7\" stroke-linejoin=\"round\"/><path d=\"M51.1 40.2 A11 11 0 1 0 59.77 53.22 A7.86 7.86 0 0 1 51.1 40.2Z\" fill=\"#3fbf6f\"/><path d=\"M20.9258 28C20.6615 27.82 20.4223 27.6072 20.2143 27.3671C19.9961 26.9641 19.8024 26.549 19.6343 26.1238C17.3476 21.0763 13.2746 16.9981 8.15841 14.6333C7.94143 14.5501 7.7297 14.4545 7.5243 14.347C6.80512 13.9024 6.82832 13.2921 7.57843 12.84C7.74361 12.7589 7.91411 12.6884 8.08881 12.6291C13.3854 10.5226 17.6112 6.45934 19.8431 1.32691C20.0751 0.814541 20.0906 0.0309247 20.8562 0.000785591C21.6217 -0.0293535 21.7377 0.814541 21.9852 1.35704C23.0822 3.90828 24.6892 6.22141 26.7125 8.16176C28.7358 10.1021 31.135 11.6309 33.7704 12.6592C33.9933 12.7315 34.2104 12.8196 34.42 12.9229C35.1933 13.3524 35.1933 13.925 34.42 14.3621C33.9406 14.6333 33.3992 14.8066 32.8734 15.0628C28.0444 17.4681 24.2329 21.4457 22.1012 26.3047C21.9511 26.6872 21.7755 27.0597 21.5753 27.4198C21.3859 27.6401 21.1675 27.8352 20.9258 28Z\" fill=\"currentColor\" transform=\"translate(57.64 44.71) scale(0.3367) translate(-21 -14)\"/></svg>";

package/dist/react.d.ts

@@ -0,0 +1,69 @@
+import { type CSSProperties, type ReactNode } from "react";
+import { type Report } from "./core.js";
+import type { Texts } from "./element.js";
+import "./element.js";
+export type ReportButtonProps = {
+    site: string;
+    endpoint?: string;
+    label?: string;
+    heading?: string;
+    position?: "bottom-right" | "bottom-left" | "inline";
+    theme?: "auto" | "light" | "dark";
+    hideMark?: boolean;
+    texts?: Partial<Texts>;
+    className?: string;
+    /** CSS custom properties too: `{ "--sentinel-accent": "#6b3fc4" }`. */
+    style?: CSSProperties & Record<`--sentinel-${string}`, string>;
+    onSent?: (kind: Report["kind"]) => void;
+    onError?: (error: unknown) => void;
+    /** Your own trigger instead of the default button: clicking it opens the form. */
+    children?: ReactNode;
+};
+export declare function ReportButton({ site, endpoint, label, heading, position, theme, hideMark, texts, className, style, onSent, onError, children }: ReportButtonProps): import("react").DOMElement<Record<string, unknown>, Element>;
+export type SentinelMarkProps = {
+    /** Width and height (a number is px; default `1em`, the size of the text around it). */
+    size?: number | string;
+    /** A name for screen readers; without it, the mark is decorative. */
+    title?: string;
+    className?: string;
+    style?: CSSProperties;
+};
+/** SENTINEL's mark, for your own button or footer. It takes the text colour (`color`); the moon stays green. */
+export declare function SentinelMark({ size, title, className, style }: SentinelMarkProps): import("react").DOMElement<{
+    dangerouslySetInnerHTML: {
+        __html: string;
+    };
+    role: string;
+    "aria-label": string;
+    "aria-hidden"?: undefined;
+    focusable?: undefined;
+    viewBox: string;
+    width: string | number;
+    height: string | number;
+    className: string | undefined;
+    style: CSSProperties | undefined;
+} | {
+    dangerouslySetInnerHTML: {
+        __html: string;
+    };
+    "aria-hidden": boolean;
+    focusable: string;
+    role?: undefined;
+    "aria-label"?: undefined;
+    viewBox: string;
+    width: string | number;
+    height: string | number;
+    className: string | undefined;
+    style: CSSProperties | undefined;
+}, Element>;
+export type ReportStatus = "idle" | "sending" | "sent" | "error";
+/** For your own form: records the visit from the first render and sends with its context. */
+export declare function useSentinelReport(options: {
+    site: string;
+    endpoint?: string;
+}): {
+    send: (report: Report) => Promise<boolean>;
+    status: ReportStatus;
+    error: unknown;
+    context: () => import("./core.js").Context | undefined;
+};

package/dist/react.js

@@ -0,0 +1,58 @@
+// React: the ready-made button (`<ReportButton>`, the web component with typed props and events) and a hook for your
+// own form (`useSentinelReport`, which records the context and sends; the look is all yours).
+import { createElement, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { capture, createReporter } from "./core.js";
+import { MARK_SHAPES } from "./mark.js";
+import "./element.js";
+export function ReportButton({ site, endpoint, label, heading, position, theme, hideMark, texts, className, style, onSent, onError, children }) {
+    const ref = useRef(null);
+    useEffect(() => {
+        const element = ref.current;
+        if (element === null)
+            return;
+        if (texts)
+            element.texts = texts;
+        const sent = (event) => onSent?.(event.detail.kind);
+        const failed = (event) => onError?.(event.detail.error);
+        element.addEventListener("sentinel-sent", sent);
+        element.addEventListener("sentinel-error", failed);
+        return () => {
+            element.removeEventListener("sentinel-sent", sent);
+            element.removeEventListener("sentinel-error", failed);
+        };
+    }, [texts, onSent, onError]);
+    const attributes = { ref, site, endpoint, label, heading, position, theme, class: className, style };
+    if (hideMark)
+        attributes["hide-mark"] = "";
+    return createElement("sentinel-report", attributes, children === undefined ? undefined : createElement("span", { slot: "trigger", style: { display: "contents" } }, children));
+}
+/** SENTINEL's mark, for your own button or footer. It takes the text colour (`color`); the moon stays green. */
+export function SentinelMark({ size = "1em", title, className, style }) {
+    const label = title ? { role: "img", "aria-label": title } : { "aria-hidden": true, focusable: "false" };
+    return createElement("svg", { viewBox: "0 0 100 100", width: size, height: size, className, style, ...label, dangerouslySetInnerHTML: { __html: `${title ? `<title>${title.replace(/[&<>"']/g, (char) => `&#${char.charCodeAt(0)};`)}</title>` : ""}${MARK_SHAPES}` } });
+}
+/** For your own form: records the visit from the first render and sends with its context. */
+export function useSentinelReport(options) {
+    const reporter = useMemo(() => (typeof window === "undefined" ? undefined : createReporter(options)), [options.site, options.endpoint]);
+    const [status, setStatus] = useState("idle");
+    const [error, setError] = useState(undefined);
+    useEffect(() => {
+        capture();
+    }, []);
+    const send = useCallback(async (report) => {
+        if (reporter === undefined)
+            return false;
+        setStatus("sending");
+        try {
+            await reporter.send(report);
+            setStatus("sent");
+            return true;
+        }
+        catch (failure) {
+            setError(failure);
+            setStatus("error");
+            return false;
+        }
+    }, [reporter]);
+    return { send, status, error, context: () => reporter?.context() };
+}

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@universelle/sentinel-report",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "SENTINEL's report button: let real users tell you what fails or what they miss, with the technical context of their visit.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": [
+    "./dist/element.js",
+    "./src/element.ts",
+    "./src/widget.ts"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./element": {
+      "types": "./dist/element.d.ts",
+      "default": "./dist/element.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "default": "./dist/react.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "19.2.2",
+    "react": "19.2.0",
+    "react-dom": "19.2.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "sentinel",
+    "bug report",
+    "feedback",
+    "web component",
+    "react"
+  ],
+  "homepage": "https://sentinel.cervilla.es",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JavierCervilla/Sentinel.git",
+    "directory": "packages/report"
+  }
+}