@dorsk/hmm 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dorsk
+
+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,163 @@
-# Temporary Holding Version
+# @dorsk/hmm
 
-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.
+A feedback panel for Svelte 5 apps built on [tsumikit](https://github.com/DorskFR/tsumikit). The
+user opens "Send feedback", selects elements on the page, comments on them, adds screenshots,
+reviews exactly what will be sent, and sends it to an endpoint you own.
+
+The panel is made of tsumikit components (`Card`, `Button`, `Textarea`, `SegmentedControl`, …), so
+it has no palette, font or control shapes of its own: it looks like the app it is in and follows
+its theme.
+
+![The panel open on a demo page, with a selected element and a screenshot](docs/widget.png)
+
+## Install
+
+```sh
+npm install @dorsk/hmm
+```
+
+`svelte` (^5) and `@dorsk/tsumikit` (>=0.82.0 <1) are peer dependencies: the panel is rendered by
+the copies your app already has. The app must load tsumikit's stylesheet, as any tsumikit app does.
+
+```svelte
+<script lang="ts">
+	import { Hmm } from '@dorsk/hmm';
+</script>
+
+<Hmm
+	projectKey="my-app"
+	endpoint="https://feedback.example.com"
+	context={() => ({ appVersion: '1.4.2', route: currentRouteName() })}
+/>
+```
+
+Render it once, near the root of the app. To open it from your own button, hide the floating one
+and bind `open`:
+
+```svelte
+<Button onclick={() => (feedbackOpen = true)}>Feedback</Button>
+<Hmm projectKey="my-app" endpoint="…" launcher={false} bind:open={feedbackOpen} />
+```
+
+Outside a Svelte tree, `init` mounts the same component on `<body>`:
+
+```ts
+import { init } from '@dorsk/hmm';
+
+const feedback = init({ projectKey: 'my-app', endpoint: 'https://feedback.example.com' });
+feedback.open();
+```
+
+`init` returns `{ open(), close(), destroy(), isOpen }`. Calling it again replaces the previous
+instance.
+
+## Props
+
+`init` takes the same fields as an object.
+
+| Prop | Type | Purpose |
+|---|---|---|
+| `projectKey` | `string` | Required. Public identifier of the project, sent with every report. Letters, digits, `.`, `_` and `-`. |
+| `endpoint` | `string` | Base URL of the ingest server. Required unless `transport` is set. |
+| `transport` | `(envelope) => Promise<void>` | Replaces the HTTP POST, for hosts that relay reports through their own backend. Throw an error with `retryable: false` to mark a permanent failure. |
+| `context` | `() => object` | Extra data added to every report. May be async. |
+| `beforeSend` | `(envelope) => envelope \| null` | Change a report, or drop it by returning `null`. Runs before the review, so the user sees the result. |
+| `launcher` | `boolean` | `false` hides the floating button. |
+| `position` | `'bottom-right' \| 'bottom-left'` | Corner for the button and the panel. |
+| `labels` | `Partial<Labels>` | Override any text. The defaults are exported as `LABELS`. |
+| `onSent` | `(envelope) => void` | Called after a report is delivered. |
+| `open` | `boolean` | Bindable. Whether the panel is shown. |
+
+## Styling
+
+Colours, spacing, radii and type come from the tsumikit tokens in scope where `Hmm` is rendered, so
+a `data-theme` switch or a token override on an ancestor applies to the panel too. The panel sits
+at `--z-toast`; set `--hmm-z-index` on an ancestor to move it.
+
+## What is sent
+
+One JSON document, the envelope, described by
+[`schema/envelope.v1.json`](schema/envelope.v1.json) and by the `Envelope` type.
+
+```jsonc
+{
+	"v": 1,
+	"id": "b6f0c9a2-…",
+	"kind": "feedback",            // "error" and "alert" are reserved for non-widget clients
+	"category": "idea",            // idea | problem | question | other
+	"project": "my-app",
+	"createdAt": "2026-11-12T08:00:00.000Z",
+	"client": { "name": "@dorsk/hmm", "version": "0.1.0" },
+	"page": { "url": "…", "title": "…", "viewport": { "width": 1280, "height": 800 }, "userAgent": "…", "language": "en" },
+	"context": { "appVersion": "1.4.2" },
+	"comment": "What about a dark mode?",
+	"items": [
+		{ "id": "…", "type": "element", "url": "…", "comment": "…", "target": { "selector": "#buy", "tag": "button", "text": "…", "html": "…", "attrs": {}, "rect": {} }, "attachment": "…" },
+		{ "id": "…", "type": "screenshot", "url": "…", "comment": "", "attachment": "…" }
+	],
+	"attachments": [{ "id": "…", "mime": "image/png", "width": 1280, "height": 800, "data": "<base64>" }]
+}
+```
+
+Limits: 20 items, 10 attachments, about 2 MB per image, 5,000 characters per comment, 16,000
+characters of serialised context. They are exported as `LIMITS`.
+
+## HTTP contract
+
+```
+POST <endpoint>/v1/reports
+content-type: application/json
+x-hmm-key: <projectKey>
+
+<envelope>
+```
+
+- Any `2xx` answer counts as delivered.
+- `408`, `429`, `5xx` and network errors are retried: the report is stored in `localStorage` and
+  sent on the next page load or when the browser comes back online. At most five reports wait.
+- Any other `4xx` is a permanent failure. The user sees an error and keeps the draft.
+- The server must answer the CORS preflight and allow the `content-type` and `x-hmm-key` headers.
+- No cookies or credentials are sent.
+
+Servers can reuse the validator without pulling in any DOM code:
+
+```ts
+import { validateEnvelope } from '@dorsk/hmm/envelope';
+
+const result = validateEnvelope(JSON.parse(body));
+if (!result.ok) return reject(result.errors);
+```
+
+Treat every field as untrusted input. The validator checks structure and size only; it does not
+make the text safe to render or to hand to an agent, and it does not decode the images.
+
+## Privacy
+
+- Nothing leaves the page until the user presses Send on the review screen, which lists every
+  field and image, with the raw JSON one click away.
+- Before the review, all text is scrubbed of JWTs, bearer tokens, common API key formats, private
+  keys and `password=`-style pairs. URLs lose their credentials and secret-looking query
+  parameters. `redactText`, `redactUrl` and `redactEnvelope` are exported.
+- The HTML of an element is not recorded when it is, or contains, a password field.
+- Screenshots cannot be scrubbed. They are shown in the review and each one can be removed.
+
+## Limitations
+
+- Svelte 5 and tsumikit only. A page without tsumikit's stylesheet renders the panel unstyled.
+- An open `<dialog>` modal makes the rest of the page inert, the panel included.
+- Screenshots are rendered from the DOM, not captured from the screen. Cross-origin images without
+  CORS, `<video>`, and canvases tainted by cross-origin content come out blank.
+- A strict Content Security Policy must allow `data:` in `img-src` for the thumbnails.
+- Elements inside iframes or closed shadow roots cannot be selected.
+
+## Development
+
+```sh
+npm install
+npm run demo     # demo shop on http://localhost:4188 with an in-memory receiver
+npm test         # unit tests and Chromium browser tests
+npm run lint     # biome and tsumikit-lint
+npm run check    # svelte-check
+```
+
+MIT licensed.