@dorsk/hmm 0.0.0-stage → 0.1.0

package/dist/core.js

@@ -0,0 +1,50 @@
+import { LIMITS } from "./envelope.js";
+import { httpTransport } from "./transport.js";
+export const uid = () => {
+    const c = globalThis.crypto;
+    if (c.randomUUID)
+        return c.randomUUID();
+    return [...c.getRandomValues(new Uint8Array(16))]
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('');
+};
+export function storageOf(get) {
+    try {
+        const storage = get();
+        storage.getItem('hmm');
+        return storage;
+    }
+    catch {
+        return null;
+    }
+}
+export function clamp(envelope) {
+    return {
+        ...envelope,
+        comment: envelope.comment.slice(0, LIMITS.comment),
+        page: envelope.page && { ...envelope.page, url: envelope.page.url.slice(0, LIMITS.url) },
+        items: envelope.items.map((item) => ({
+            ...item,
+            url: item.url.slice(0, LIMITS.url),
+            comment: item.comment.slice(0, LIMITS.comment),
+        })),
+    };
+}
+/** Throws when the options cannot deliver a report. */
+export function transportOf(options) {
+    if (!/^[A-Za-z0-9._-]{1,128}$/.test(options?.projectKey ?? ''))
+        throw new Error('hmm: projectKey must be 1 to 128 letters, digits, dots, dashes or underscores');
+    const transport = options.transport ??
+        (options.endpoint ? httpTransport(options.endpoint, options.projectKey) : null);
+    if (!transport)
+        throw new Error('hmm: either endpoint or transport is required');
+    return transport;
+}
+/** The report as shown to the user: image data replaced by its size. */
+export const readable = (envelope) => JSON.stringify({
+    ...envelope,
+    attachments: envelope.attachments.map((a) => ({
+        ...a,
+        data: `<${Math.round((a.data.length * 3) / 4 / 1024)} KB of PNG>`,
+    })),
+}, null, 2);

package/dist/draft.d.ts

@@ -0,0 +1,12 @@
+import { type Attachment, type Category, type Item } from './envelope.ts';
+export type Draft = {
+    category: Category;
+    comment: string;
+    items: Item[];
+    attachments: Attachment[];
+};
+export declare const emptyDraft: () => Draft;
+export declare const isEmpty: (draft: Draft) => boolean;
+export declare function loadDraft(storage: Storage | null, key: string): Draft;
+/** Best effort: a draft too large for the storage quota stays in memory only. */
+export declare function saveDraft(storage: Storage | null, key: string, draft: Draft): void;

package/dist/draft.js

@@ -0,0 +1,44 @@
+import { CATEGORIES, validateEnvelope, } from "./envelope.js";
+export const emptyDraft = () => ({
+    category: 'idea',
+    comment: '',
+    items: [],
+    attachments: [],
+});
+export const isEmpty = (draft) => !draft.comment.trim() && draft.items.length === 0;
+const wellFormed = (draft) => validateEnvelope({
+    v: 1,
+    id: 'draft',
+    kind: 'feedback',
+    project: 'draft',
+    createdAt: '1970-01-01T00:00:00Z',
+    client: { name: '', version: '' },
+    context: {},
+    comment: draft.comment,
+    items: draft.items,
+    attachments: draft.attachments,
+}).ok;
+export function loadDraft(storage, key) {
+    try {
+        const parsed = JSON.parse(storage?.getItem(key) ?? 'null');
+        if (parsed && CATEGORIES.includes(parsed.category) && wellFormed(parsed))
+            return parsed;
+    }
+    catch { }
+    return emptyDraft();
+}
+/** Best effort: a draft too large for the storage quota stays in memory only. */
+export function saveDraft(storage, key, draft) {
+    try {
+        if (isEmpty(draft))
+            storage?.removeItem(key);
+        else
+            storage?.setItem(key, JSON.stringify(draft));
+    }
+    catch {
+        try {
+            storage?.removeItem(key);
+        }
+        catch { }
+    }
+}

package/dist/envelope.d.ts

@@ -0,0 +1,103 @@
+export declare const ENVELOPE_VERSION: 1;
+export declare const KINDS: readonly ["feedback", "error", "alert"];
+export declare const CATEGORIES: readonly ["idea", "problem", "question", "other"];
+export type Kind = (typeof KINDS)[number];
+export type Category = (typeof CATEGORIES)[number];
+export declare const LIMITS: {
+    readonly comment: 5000;
+    readonly items: 20;
+    readonly attachments: 10;
+    readonly attachmentChars: 2800000;
+    readonly attachmentSide: 8192;
+    readonly contextChars: 16000;
+    readonly contextKeys: 50;
+    readonly url: 2000;
+    readonly selector: 1000;
+    readonly text: 400;
+    readonly html: 2000;
+    readonly attrs: 40;
+    readonly attrName: 100;
+    readonly attrValue: 400;
+    readonly short: 500;
+};
+export type Rect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+export type Target = {
+    selector: string;
+    tag: string;
+    text: string;
+    html: string;
+    attrs: Record<string, string>;
+    rect: Rect;
+    source?: {
+        file: string;
+        line: number;
+        column: number;
+    };
+};
+export type ElementItem = {
+    id: string;
+    type: 'element';
+    url: string;
+    comment: string;
+    target: Target;
+    attachment?: string;
+};
+export type ScreenshotItem = {
+    id: string;
+    type: 'screenshot';
+    url: string;
+    comment: string;
+    attachment: string;
+};
+export type Item = ElementItem | ScreenshotItem;
+export type Attachment = {
+    id: string;
+    mime: 'image/png';
+    width: number;
+    height: number;
+    /** Base64 without a data URL prefix. */
+    data: string;
+};
+export type Page = {
+    url: string;
+    title: string;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    userAgent: string;
+    language: string;
+};
+export type Envelope = {
+    v: typeof ENVELOPE_VERSION;
+    id: string;
+    kind: Kind;
+    category?: Category;
+    /** Groups repeats of the same error or alert. */
+    fingerprint?: string;
+    project: string;
+    createdAt: string;
+    client: {
+        name: string;
+        version: string;
+    };
+    page?: Page;
+    context: Record<string, unknown>;
+    comment: string;
+    items: Item[];
+    attachments: Attachment[];
+};
+export type Validation = {
+    ok: true;
+    envelope: Envelope;
+} | {
+    ok: false;
+    errors: string[];
+};
+/** Strict structural check, shared by the widget before sending and by servers on receipt. */
+export declare function validateEnvelope(data: unknown): Validation;

package/dist/envelope.js

@@ -0,0 +1,218 @@
+export const ENVELOPE_VERSION = 1;
+export const KINDS = ['feedback', 'error', 'alert'];
+export const CATEGORIES = ['idea', 'problem', 'question', 'other'];
+export const LIMITS = {
+    comment: 5000,
+    items: 20,
+    attachments: 10,
+    attachmentChars: 2_800_000,
+    attachmentSide: 8192,
+    contextChars: 16_000,
+    contextKeys: 50,
+    url: 2000,
+    selector: 1000,
+    text: 400,
+    html: 2000,
+    attrs: 40,
+    attrName: 100,
+    attrValue: 400,
+    short: 500,
+};
+const ID = /^[A-Za-z0-9_-]{1,64}$/;
+const PROJECT = /^[A-Za-z0-9._-]{1,128}$/;
+const TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/;
+const BASE64 = /^[A-Za-z0-9+/]+={0,2}$/;
+class Check {
+    errors = [];
+    fail(path, message) {
+        this.errors.push(`${path}: ${message}`);
+        return false;
+    }
+    object(value, path, required, optional = []) {
+        if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+            this.fail(path, 'must be an object');
+            return null;
+        }
+        const obj = value;
+        for (const key of required)
+            if (!(key in obj))
+                this.fail(`${path}.${key}`, 'is required');
+        for (const key of Object.keys(obj)) {
+            if (!required.includes(key) && !optional.includes(key))
+                this.fail(`${path}.${key}`, 'is not allowed');
+        }
+        return obj;
+    }
+    string(value, path, max, pattern) {
+        if (typeof value !== 'string')
+            return this.fail(path, 'must be a string');
+        if (value.length > max)
+            return this.fail(path, `must be at most ${max} characters`);
+        if (pattern && !pattern.test(value))
+            return this.fail(path, 'has an invalid format');
+        return true;
+    }
+    int(value, path, min, max) {
+        if (typeof value !== 'number' || !Number.isInteger(value))
+            return this.fail(path, 'must be an integer');
+        if (value < min || value > max)
+            return this.fail(path, `must be between ${min} and ${max}`);
+        return true;
+    }
+    oneOf(value, path, values) {
+        return values.includes(value) || this.fail(path, `must be one of ${values.join(', ')}`);
+    }
+    array(value, path, max) {
+        if (!Array.isArray(value)) {
+            this.fail(path, 'must be an array');
+            return null;
+        }
+        if (value.length > max)
+            this.fail(path, `must have at most ${max} entries`);
+        return value;
+    }
+}
+const COORD = 1_000_000;
+function checkTarget(c, value, path) {
+    const t = c.object(value, path, ['selector', 'tag', 'text', 'html', 'attrs', 'rect'], ['source']);
+    if (!t)
+        return;
+    c.string(t.selector, `${path}.selector`, LIMITS.selector);
+    c.string(t.tag, `${path}.tag`, 100);
+    c.string(t.text, `${path}.text`, LIMITS.text);
+    c.string(t.html, `${path}.html`, LIMITS.html);
+    const attrs = c.object(t.attrs, `${path}.attrs`, [], Object.keys(t.attrs ?? {}));
+    if (attrs) {
+        const names = Object.keys(attrs);
+        if (names.length > LIMITS.attrs)
+            c.fail(`${path}.attrs`, `must have at most ${LIMITS.attrs} entries`);
+        for (const name of names) {
+            if (name.length > LIMITS.attrName)
+                c.fail(`${path}.attrs`, 'has a name that is too long');
+            c.string(attrs[name], `${path}.attrs.${name}`, LIMITS.attrValue);
+        }
+    }
+    const rect = c.object(t.rect, `${path}.rect`, ['x', 'y', 'width', 'height']);
+    if (rect) {
+        c.int(rect.x, `${path}.rect.x`, -COORD, COORD);
+        c.int(rect.y, `${path}.rect.y`, -COORD, COORD);
+        c.int(rect.width, `${path}.rect.width`, 0, COORD);
+        c.int(rect.height, `${path}.rect.height`, 0, COORD);
+    }
+    if ('source' in t) {
+        const source = c.object(t.source, `${path}.source`, ['file', 'line', 'column']);
+        if (source) {
+            c.string(source.file, `${path}.source.file`, LIMITS.short);
+            c.int(source.line, `${path}.source.line`, 0, COORD);
+            c.int(source.column, `${path}.source.column`, 0, COORD);
+        }
+    }
+}
+function checkItem(c, value, path, attachmentIds) {
+    const type = value?.type;
+    if (type !== 'element' && type !== 'screenshot') {
+        c.fail(`${path}.type`, 'must be one of element, screenshot');
+        return;
+    }
+    const item = type === 'element'
+        ? c.object(value, path, ['id', 'type', 'url', 'comment', 'target'], ['attachment'])
+        : c.object(value, path, ['id', 'type', 'url', 'comment', 'attachment']);
+    if (!item)
+        return;
+    c.string(item.id, `${path}.id`, 64, ID);
+    c.string(item.url, `${path}.url`, LIMITS.url);
+    c.string(item.comment, `${path}.comment`, LIMITS.comment);
+    if (type === 'element')
+        checkTarget(c, item.target, `${path}.target`);
+    if ('attachment' in item && c.string(item.attachment, `${path}.attachment`, 64, ID)) {
+        if (!attachmentIds.has(item.attachment))
+            c.fail(`${path}.attachment`, 'does not match an attachment');
+    }
+}
+function checkAttachment(c, value, path) {
+    const a = c.object(value, path, ['id', 'mime', 'width', 'height', 'data']);
+    if (!a)
+        return;
+    c.string(a.id, `${path}.id`, 64, ID);
+    c.oneOf(a.mime, `${path}.mime`, ['image/png']);
+    c.int(a.width, `${path}.width`, 1, LIMITS.attachmentSide);
+    c.int(a.height, `${path}.height`, 1, LIMITS.attachmentSide);
+    c.string(a.data, `${path}.data`, LIMITS.attachmentChars, BASE64);
+}
+function checkPage(c, value, path) {
+    const page = c.object(value, path, ['url', 'title', 'viewport', 'userAgent', 'language']);
+    if (!page)
+        return;
+    c.string(page.url, `${path}.url`, LIMITS.url);
+    c.string(page.title, `${path}.title`, LIMITS.short);
+    c.string(page.userAgent, `${path}.userAgent`, LIMITS.short);
+    c.string(page.language, `${path}.language`, 100);
+    const viewport = c.object(page.viewport, `${path}.viewport`, ['width', 'height']);
+    if (viewport) {
+        c.int(viewport.width, `${path}.viewport.width`, 0, COORD);
+        c.int(viewport.height, `${path}.viewport.height`, 0, COORD);
+    }
+}
+/** Strict structural check, shared by the widget before sending and by servers on receipt. */
+export function validateEnvelope(data) {
+    const c = new Check();
+    const e = c.object(data, 'envelope', [
+        'v',
+        'id',
+        'kind',
+        'project',
+        'createdAt',
+        'client',
+        'context',
+        'comment',
+        'items',
+        'attachments',
+    ], ['category', 'fingerprint', 'page']);
+    if (!e)
+        return { ok: false, errors: c.errors };
+    c.oneOf(e.v, 'envelope.v', [ENVELOPE_VERSION]);
+    c.string(e.id, 'envelope.id', 64, ID);
+    c.oneOf(e.kind, 'envelope.kind', KINDS);
+    if ('category' in e)
+        c.oneOf(e.category, 'envelope.category', CATEGORIES);
+    if ('fingerprint' in e)
+        c.string(e.fingerprint, 'envelope.fingerprint', LIMITS.short);
+    c.string(e.project, 'envelope.project', 128, PROJECT);
+    c.string(e.createdAt, 'envelope.createdAt', 40, TIMESTAMP);
+    c.string(e.comment, 'envelope.comment', LIMITS.comment);
+    const client = c.object(e.client, 'envelope.client', ['name', 'version']);
+    if (client) {
+        c.string(client.name, 'envelope.client.name', 100);
+        c.string(client.version, 'envelope.client.version', 100);
+    }
+    if ('page' in e)
+        checkPage(c, e.page, 'envelope.page');
+    const context = c.object(e.context, 'envelope.context', [], Object.keys(e.context ?? {}));
+    if (context) {
+        if (Object.keys(context).length > LIMITS.contextKeys)
+            c.fail('envelope.context', `must have at most ${LIMITS.contextKeys} keys`);
+        let size = Number.POSITIVE_INFINITY;
+        try {
+            size = JSON.stringify(context).length;
+        }
+        catch { }
+        if (size > LIMITS.contextChars)
+            c.fail('envelope.context', `must serialise to at most ${LIMITS.contextChars} characters`);
+    }
+    const attachments = c.array(e.attachments, 'envelope.attachments', LIMITS.attachments);
+    const ids = new Set();
+    attachments?.forEach((a, i) => {
+        checkAttachment(c, a, `envelope.attachments[${i}]`);
+        const id = a?.id;
+        if (typeof id === 'string') {
+            if (ids.has(id))
+                c.fail(`envelope.attachments[${i}].id`, 'is duplicated');
+            ids.add(id);
+        }
+    });
+    const items = c.array(e.items, 'envelope.items', LIMITS.items);
+    items?.forEach((item, i) => {
+        checkItem(c, item, `envelope.items[${i}]`, ids);
+    });
+    return c.errors.length ? { ok: false, errors: c.errors } : { ok: true, envelope: e };
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+import { type Handle, type Options } from './core.ts';
+import Hmm from './Hmm.svelte';
+export type { Handle, Options } from './core.ts';
+export { type Attachment, CATEGORIES, type Category, type ElementItem, ENVELOPE_VERSION, type Envelope, type Item, KINDS, type Kind, LIMITS, type Page, type Rect, type ScreenshotItem, type Target, type Validation, validateEnvelope, } from './envelope.ts';
+export { LABELS, type Labels } from './labels.ts';
+export { redactEnvelope, redactText, redactUrl } from './redact.ts';
+export { httpTransport, SendError, type Transport } from './transport.ts';
+export { VERSION } from './version.ts';
+export { Hmm };
+/** Mounts `Hmm` on the document body, for hosts without a Svelte tree. A second call replaces the first instance. */
+export declare function init(options: Options): Handle;

package/dist/index.js

@@ -0,0 +1,32 @@
+import { mount, unmount } from 'svelte';
+import { transportOf } from "./core.js";
+import Hmm from './Hmm.svelte';
+export { CATEGORIES, ENVELOPE_VERSION, KINDS, LIMITS, validateEnvelope, } from "./envelope.js";
+export { LABELS } from "./labels.js";
+export { redactEnvelope, redactText, redactUrl } from "./redact.js";
+export { httpTransport, SendError } from "./transport.js";
+export { VERSION } from "./version.js";
+export { Hmm };
+let current = null;
+/** Mounts `Hmm` on the document body, for hosts without a Svelte tree. A second call replaces the first instance. */
+export function init(options) {
+    transportOf(options);
+    if (!document.body)
+        throw new Error('hmm: call init after the document body exists');
+    current?.destroy();
+    const component = mount(Hmm, { target: document.body, props: options });
+    const handle = {
+        open: () => component.show(),
+        close: () => component.hide(),
+        destroy() {
+            void unmount(component);
+            if (current === handle)
+                current = null;
+        },
+        get isOpen() {
+            return component.isOpen();
+        },
+    };
+    current = handle;
+    return handle;
+}

package/dist/inspect.d.ts

@@ -0,0 +1,4 @@
+import type { Target } from './envelope.ts';
+export declare function selectorOf(el: Element): string;
+export declare function describeElement(el: Element): Target;
+export declare const labelOf: (target: Target) => string;

package/dist/inspect.js

@@ -0,0 +1,75 @@
+const SCOPED_CLASS = /^(svelte|s)-[\w-]{5,}$/;
+const HOOK_ATTRS = ['data-testid', 'data-test'];
+const KEPT_ATTRS = ['role', 'aria-label', 'href', 'name', 'type', 'title', 'alt'];
+const SECRET_INPUT = 'input[type="password"]';
+function sourceOf(el) {
+    for (let node = el; node; node = node.parentElement) {
+        const loc = node.__svelte_meta?.loc;
+        if (loc)
+            return { file: loc.file.slice(0, 400), line: loc.line, column: loc.column ?? 0 };
+    }
+    return undefined;
+}
+export function selectorOf(el) {
+    const doc = el.ownerDocument;
+    const parts = [];
+    for (let node = el; node && node.nodeType === 1 && node !== doc.documentElement; node = node.parentElement) {
+        for (const attr of HOOK_ATTRS) {
+            const value = node.getAttribute(attr);
+            if (value) {
+                parts.unshift(`[${attr}="${CSS.escape(value)}"]`);
+                return parts.join(' > ');
+            }
+        }
+        if (node.id && !/\d{3,}/.test(node.id)) {
+            parts.unshift(`#${CSS.escape(node.id)}`);
+            return parts.join(' > ');
+        }
+        let part = node.localName;
+        const classes = [...node.classList].filter((c) => !SCOPED_CLASS.test(c)).slice(0, 2);
+        if (classes.length)
+            part += classes.map((c) => `.${CSS.escape(c)}`).join('');
+        const current = node;
+        const siblings = current.parentElement
+            ? [...current.parentElement.children].filter((s) => s.localName === current.localName)
+            : [];
+        if (siblings.length > 1)
+            part += `:nth-of-type(${siblings.indexOf(current) + 1})`;
+        parts.unshift(part);
+        if (parts.length >= 6)
+            break;
+    }
+    return parts.join(' > ').slice(0, 800);
+}
+const squash = (text, max) => {
+    const flat = text.replace(/\s+/g, ' ').trim();
+    return flat.length > max ? `${flat.slice(0, max)}…` : flat;
+};
+export function describeElement(el) {
+    const attrs = {};
+    for (const a of [...el.attributes].slice(0, 30)) {
+        if ((a.name.startsWith('data-') || KEPT_ATTRS.includes(a.name)) && a.name.length <= 80)
+            attrs[a.name] = a.value.slice(0, 200);
+    }
+    const r = el.getBoundingClientRect();
+    const secret = el.matches(SECRET_INPUT) || el.querySelector(SECRET_INPUT) !== null;
+    const target = {
+        selector: selectorOf(el),
+        tag: el.localName.slice(0, 80),
+        // biome-ignore lint/performance/useDomNodeTextContent: innerText leaves out hidden text
+        text: squash(el.innerText ?? el.textContent ?? '', 200),
+        html: secret ? '' : squash(el.outerHTML, 1000),
+        attrs,
+        rect: {
+            x: Math.round(r.x),
+            y: Math.round(r.y),
+            width: Math.round(r.width),
+            height: Math.round(r.height),
+        },
+    };
+    const source = sourceOf(el);
+    if (source)
+        target.source = source;
+    return target;
+}
+export const labelOf = (target) => target.text ? `<${target.tag}> ${target.text.slice(0, 40)}` : `<${target.tag}>`;

package/dist/labels.d.ts

@@ -0,0 +1,36 @@
+export declare const LABELS: {
+    launcher: string;
+    title: string;
+    close: string;
+    idea: string;
+    problem: string;
+    question: string;
+    other: string;
+    commentPlaceholder: string;
+    pick: string;
+    shot: string;
+    pickHint: string;
+    capturing: string;
+    itemPlaceholder: string;
+    screenshot: string;
+    remove: string;
+    removeImage: string;
+    discard: string;
+    review: string;
+    back: string;
+    send: string;
+    reviewIntro: string;
+    category: string;
+    page: string;
+    comment: string;
+    context: string;
+    raw: string;
+    sent: string;
+    queued: string;
+    failed: string;
+    blocked: string;
+    shotFailed: string;
+    full: string;
+    done: string;
+};
+export type Labels = typeof LABELS;

package/dist/labels.js

@@ -0,0 +1,35 @@
+export const LABELS = {
+    launcher: 'Feedback',
+    title: 'Send feedback',
+    close: 'Close',
+    idea: 'Idea',
+    problem: 'Problem',
+    question: 'Question',
+    other: 'Other',
+    commentPlaceholder: 'What did you notice, or what would you like to see?',
+    pick: 'Select something on the page',
+    shot: 'Add screenshot',
+    pickHint: 'Click what you mean. Press Esc to cancel.',
+    capturing: 'Capturing…',
+    itemPlaceholder: 'What about this?',
+    screenshot: 'Screenshot',
+    remove: 'Remove',
+    removeImage: 'Remove image',
+    discard: 'Discard',
+    review: 'Review',
+    back: 'Back',
+    send: 'Send',
+    reviewIntro: 'This is everything that will be sent.',
+    category: 'Type',
+    page: 'Page',
+    comment: 'Comment',
+    context: 'Details',
+    raw: 'Raw data',
+    sent: 'Thanks, your feedback was sent.',
+    queued: 'The connection failed. Your feedback is saved and will be sent automatically.',
+    failed: 'Sending failed. Please try again.',
+    blocked: 'This feedback cannot be sent from this page.',
+    shotFailed: 'The screenshot could not be taken.',
+    full: 'You have reached the maximum for one report.',
+    done: 'Done',
+};

package/dist/picker.d.ts

@@ -0,0 +1,2 @@
+/** The page element under a point, ignoring the widget itself. */
+export declare const elementAt: (doc: Document, host: Element, x: number, y: number) => Element | null;

package/dist/picker.js

@@ -0,0 +1,4 @@
+/** The page element under a point, ignoring the widget itself. */
+export const elementAt = (doc, host, x, y) => doc
+    .elementsFromPoint(x, y)
+    .find((el) => el !== host && !host.contains(el) && el !== doc.documentElement && el !== doc.body) ?? null;

package/dist/redact.d.ts

@@ -0,0 +1,5 @@
+import type { Envelope } from './envelope.ts';
+export declare function redactText(text: string): string;
+export declare function redactUrl(url: string): string;
+/** Scrubs every string except attachment image data; images cannot be scrubbed. */
+export declare function redactEnvelope(envelope: Envelope): Envelope;