@bro-code/crawl-space 0.0.0-stage → 2026.0.0

package/dist/esm/submit.js

@@ -0,0 +1,93 @@
+import { CONTEXT_LIMITS, collectContext } from './context.js';
+import { h } from './dom.js';
+import { sanitizeText } from './sanitize.js';
+const PROMPTS = { bug: 'What went wrong?', question: 'What would you like to know?' };
+export function createSubmitPanel(host) {
+    const bug = h('input', { type: 'radio', name: 'cs-type', value: 'bug', checked: true });
+    const question = h('input', { type: 'radio', name: 'cs-type', value: 'question' });
+    const prompt = h('label', { class: 'field-label', for: 'cs-description' });
+    const description = h('textarea', { id: 'cs-description', rows: '6' });
+    const counter = h('div', { class: 'counter' });
+    const include = h('input', { type: 'checkbox', checked: true });
+    const details = h('ul', { 'aria-label': 'Details sent with it' });
+    const detailsBox = h('div', { class: 'details' }, h('label', {}, include, 'Include these details'), details);
+    const message = h('p', { class: 'message', role: 'status' });
+    const send = h('button', { type: 'submit', class: 'primary' }, 'Send');
+    const form = h('form', {}, h('fieldset', { class: 'kinds' }, h('legend', { class: 'hidden-label' }, 'Type'), h('label', {}, bug, h('span', {}, 'Bug')), h('label', {}, question, h('span', {}, 'Question'))), prompt, description, counter, detailsBox, h('div', { class: 'actions' }, message, send));
+    let shown = [];
+    function say(kind, text) {
+        message.className = `message ${kind}`.trim();
+        message.textContent = text;
+    }
+    function update() {
+        prompt.textContent = question.checked ? PROMPTS.question : PROMPTS.bug;
+        counter.textContent = `${description.value.length} / ${host.options.maxLength}`;
+        details.classList.toggle('off', !include.checked);
+        for (const { field } of shown)
+            if (field)
+                field.disabled = !include.checked;
+    }
+    function contextToSend() {
+        const pairs = shown.flatMap(({ entry, field }) => {
+            const value = field ? sanitizeText(field.value, CONTEXT_LIMITS.maxValueLength) : entry.value;
+            return value === '' ? [] : [[entry.label, value]];
+        });
+        return pairs.length > 0 ? Object.fromEntries(pairs) : undefined;
+    }
+    form.addEventListener('change', update);
+    description.addEventListener('input', () => {
+        say('', '');
+        update();
+    });
+    form.addEventListener('submit', (event) => {
+        event.preventDefault();
+        const text = sanitizeText(description.value, host.options.maxLength);
+        if (text === '') {
+            say('error', 'Write something first.');
+            description.focus();
+            return;
+        }
+        const type = question.checked ? 'question' : 'bug';
+        const context = include.checked ? contextToSend() : undefined;
+        send.disabled = true;
+        say('', 'Sending...');
+        void host.api.submitReport({ type, description: text, ...(context && { context }) }).then((result) => {
+            send.disabled = false;
+            if (result.ok) {
+                form.reset();
+                update();
+                say('success', `Thanks! Your ${type === 'bug' ? 'report' : 'question'} was sent.`);
+            }
+            else if (result.reason === 'rate-limited') {
+                say('error', 'Too many sent in a short time. Please try again in a minute.');
+            }
+            else {
+                say('error', 'It could not be sent. Please try again.');
+            }
+        });
+    });
+    return {
+        element: form,
+        show() {
+            const before = new Map(shown.map((detail) => [detail.entry.label, detail]));
+            shown = collectContext(host.options).map((entry) => {
+                if (!entry.editable)
+                    return { entry };
+                const field = h('input', { type: 'text', value: entry.value, maxlength: String(CONTEXT_LIMITS.maxValueLength) });
+                const previous = before.get(entry.label);
+                if (previous?.field && previous.entry.value === entry.value)
+                    field.value = previous.field.value;
+                return { entry, field };
+            });
+            details.replaceChildren(...shown.map(({ entry, field }) => field
+                ? h('li', { class: 'editable' }, h('label', {}, h('span', { class: 'label' }, `${entry.label}: `), field))
+                : h('li', {}, h('span', { class: 'label' }, `${entry.label}: `), entry.value)));
+            detailsBox.hidden = shown.length === 0;
+            update();
+        },
+        refresh() {
+            description.maxLength = host.options.maxLength;
+            update();
+        },
+    };
+}

package/dist/esm/themes.js

@@ -0,0 +1,85 @@
+const DEFAULT = {
+    background: '#121417',
+    surface: '#1c1f24',
+    text: '#e8eaed',
+    muted: '#9aa0a6',
+    border: '#33373d',
+    accent: '#5b9cff',
+    accentText: '#0b1220',
+    error: '#ff6b6b',
+    success: '#6fcf97',
+    font: "system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif",
+};
+const BROCODE = {
+    background: '#181818',
+    surface: '#222222',
+    text: '#ffffff',
+    muted: '#b0b0b0',
+    border: '#3c3c3c',
+    accent: '#7b9981',
+    accentText: '#ffffff',
+    error: '#ff5252',
+    success: '#96be4d',
+    font: 'Roboto, sans-serif',
+};
+const ROMBIE = {
+    background: '#0a0a12',
+    surface: '#15141f',
+    text: '#f1eef9',
+    muted: '#9a90bd',
+    border: '#302c47',
+    accent: '#ff2d78',
+    accentText: '#12060d',
+    error: '#ff5c5c',
+    success: '#00e5ff',
+    font: "system-ui, 'Segoe UI', Roboto, sans-serif",
+};
+export const THEMES = {
+    default: DEFAULT,
+    brocode: BROCODE,
+    rombie: ROMBIE,
+    'taut-wad': BROCODE,
+    custom: DEFAULT,
+};
+const COLOR_KEYS = Object.keys(DEFAULT);
+function isTheme(name) {
+    return Object.hasOwn(THEMES, name);
+}
+function isValid(key, value) {
+    if (typeof value !== 'string' || value.trim() === '')
+        return false;
+    return CSS.supports(key === 'font' ? 'font-family' : 'color', value);
+}
+export function resolveColors(config) {
+    const theme = config.theme ?? 'default';
+    if (typeof theme !== 'string' || !isTheme(theme)) {
+        console.warn(`[crawl-space] Unknown theme "${String(theme)}"; using "default".`);
+        return { ...DEFAULT };
+    }
+    if (theme !== 'custom') {
+        if (config.colors !== undefined) {
+            console.warn(`[crawl-space] "colors" is only used with theme "custom"; ignoring it.`);
+        }
+        return { ...THEMES[theme] };
+    }
+    const colors = { ...DEFAULT };
+    const given = config.colors ?? {};
+    if (typeof given !== 'object' || given === null || Array.isArray(given)) {
+        console.warn('[crawl-space] "colors" must be an object; using the default theme.');
+        return colors;
+    }
+    for (const [key, value] of Object.entries(given)) {
+        if (value === undefined)
+            continue;
+        if (!COLOR_KEYS.includes(key)) {
+            console.warn(`[crawl-space] Unknown color "${key}"; ignoring it.`);
+        }
+        else if (isValid(key, value)) {
+            colors[key] = value;
+        }
+        else {
+            console.warn(`[crawl-space] Invalid ${key} "${String(value)}"; using the default theme's.`);
+        }
+    }
+    return colors;
+}

package/dist/esm/types.js

@@ -0,0 +1 @@
+export {};

package/dist/types/api.d.ts

@@ -0,0 +1,20 @@
+import type { CrawlSpaceOptions, CrawlSpaceQaItem, CrawlSpaceReports, CrawlSpaceSubmission } from './types.js';
+/** `rate-limited` is a 429; `failed` is anything else: the network, another status or a malformed body. */
+export type ApiResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    reason: 'rate-limited' | 'failed';
+};
+export interface CrawlSpaceApi {
+    submitReport(submission: CrawlSpaceSubmission): Promise<ApiResult<{
+        id: number | string;
+    }>>;
+    getReports(): Promise<ApiResult<CrawlSpaceReports>>;
+    getQa(): Promise<ApiResult<CrawlSpaceQaItem[]>>;
+}
+/** Joins a base URL and a path with exactly one `/` between them. */
+export declare function joinUrl(base: string, path: string): string;
+/** A client for the crawl-space HTTP contract. Its calls resolve to an `ApiResult` and never throw. */
+export declare function createApiClient(options: Pick<CrawlSpaceOptions, 'api' | 'paths' | 'getToken'>): CrawlSpaceApi;

package/dist/types/button.d.ts

@@ -0,0 +1,8 @@
+import type { Host } from './host.js';
+/**
+ * `<crawl-space-button tab="active">` opens the dialog at `tab` (default
+ * `submit`). Its label is its text, or the title when it has none. With
+ * `floating` it is fixed in a corner, at `floating.position`. The inner button
+ * is `::part(button)`.
+ */
+export declare function defineButton(getHost: () => Host): CustomElementConstructor;

package/dist/types/context.d.ts

@@ -0,0 +1,15 @@
+import type { CrawlSpaceContextEntry, CrawlSpaceOptions } from './types.js';
+/** What brocodetech accepts in a report's context; it refuses more. */
+export declare const CONTEXT_LIMITS: {
+    readonly maxEntries: 12;
+    readonly maxKeyLength: 40;
+    readonly maxValueLength: 200;
+};
+/**
+ * The details sent with a report, in the order shown: Version, Page (the path
+ * only, through `scrubPath`), Browser, OS, then `getContext()`'s entries, which
+ * alone can be editable. Labels and values are sanitized and capped; an empty
+ * one, a non-string value or a repeated label is left out, and at most
+ * `CONTEXT_LIMITS.maxEntries` are kept.
+ */
+export declare function collectContext(options: Pick<CrawlSpaceOptions, 'version' | 'scrubPath' | 'getContext'>): CrawlSpaceContextEntry[];

package/dist/types/crawl-space.d.ts

@@ -0,0 +1,11 @@
+import type { CrawlSpaceController, CrawlSpaceOptions } from './types.js';
+/**
+ * Sets up the help desk: defines `<crawl-space-button>` and the dialog, adds
+ * the floating button when `floating` is set, and returns `open(tab?)` and
+ * `close()`. Call it once; a second call replaces the options and returns the
+ * same controller. Without a `window` it does nothing and returns a
+ * controller whose methods do nothing.
+ *
+ * @throws TypeError when `api` is not a non-empty string.
+ */
+export declare function createCrawlSpace(options: CrawlSpaceOptions): CrawlSpaceController;

package/dist/types/css.d.ts

@@ -0,0 +1,2 @@
+export declare const BUTTON_CSS = "\n:host { display: inline-block; }\n:host([hidden]) { display: none; }\n:host([floating]) { position: fixed; z-index: 2147483000; }\n:host([floating][data-position='bottom-right']) { right: 16px; bottom: 16px; }\n:host([floating][data-position='bottom-left']) { left: 16px; bottom: 16px; }\n:host([floating][data-position='top-right']) { right: 16px; top: 16px; }\n:host([floating][data-position='top-left']) { left: 16px; top: 16px; }\nbutton {\n  padding: 9px 16px;\n  border: none;\n  border-radius: 8px;\n  background: var(--cs-accent);\n  color: var(--cs-accent-text);\n  font: 600 14px/1.2 var(--cs-font);\n  cursor: pointer;\n}\n:host([floating]) button { padding: 11px 18px; border-radius: 999px; box-shadow: 0 6px 18px rgba(0, 0, 0, 0.4); }\nbutton:hover { filter: brightness(1.1); }\nbutton:focus-visible { outline: 2px solid var(--cs-text); outline-offset: 2px; }\n";
+export declare const DIALOG_CSS = "\n:host { all: initial; }\n*, *::before, *::after { box-sizing: border-box; }\ndialog {\n  width: min(560px, calc(100vw - 32px));\n  max-height: min(720px, calc(100vh - 32px));\n  padding: 0;\n  border: 1px solid var(--cs-border);\n  border-radius: 12px;\n  background: var(--cs-background);\n  color: var(--cs-text);\n  font: 14px/1.45 var(--cs-font);\n  box-shadow: 0 24px 64px rgba(0, 0, 0, 0.5);\n  overflow: hidden;\n}\ndialog[open] { display: flex; flex-direction: column; }\ndialog::backdrop { background: rgba(0, 0, 0, 0.6); }\nbutton, input, textarea { font: inherit; color: inherit; }\nbutton { cursor: pointer; }\nbutton:disabled { cursor: default; opacity: 0.6; }\n:focus-visible { outline: 2px solid var(--cs-accent); outline-offset: 2px; }\nheader { display: flex; align-items: center; justify-content: space-between; gap: 12px; padding: 14px 12px 0 20px; }\nh2 { margin: 0; font-size: 18px; font-weight: 600; }\n.close { display: grid; place-items: center; width: 32px; height: 32px; padding: 0; border: none; border-radius: 8px; background: none; color: var(--cs-muted); }\n.close:hover { background: var(--cs-surface); color: var(--cs-text); }\n.close svg { width: 16px; height: 16px; fill: none; stroke: currentColor; stroke-width: 2; stroke-linecap: round; }\n[role='tablist'] { display: flex; gap: 4px; padding: 8px 14px 0; border-bottom: 1px solid var(--cs-border); }\n[role='tab'] { margin-bottom: -1px; padding: 9px 10px; border: none; border-bottom: 2px solid transparent; background: none; color: var(--cs-muted); font-weight: 600; }\n[role='tab']:hover { color: var(--cs-text); }\n[role='tab'][aria-selected='true'] { border-bottom-color: var(--cs-accent); color: var(--cs-text); }\n[role='tabpanel'] { flex: 1 1 auto; min-height: 0; padding: 16px 20px 20px; overflow-y: auto; }\n[role='tabpanel'][hidden] { display: none; }\n.hidden-label { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; }\n.kinds { display: inline-flex; gap: 3px; margin: 0 0 14px; padding: 3px; border: 1px solid var(--cs-border); border-radius: 8px; }\n.kinds label { position: relative; }\n.kinds input { position: absolute; inset: 0; margin: 0; opacity: 0; cursor: pointer; }\n.kinds span { display: block; padding: 5px 14px; border-radius: 6px; color: var(--cs-muted); font-weight: 600; }\n.kinds input:checked + span { background: var(--cs-accent); color: var(--cs-accent-text); }\n.kinds input:focus-visible + span { outline: 2px solid var(--cs-accent); outline-offset: 2px; }\n.field-label { display: block; margin-bottom: 6px; font-weight: 600; }\ntextarea { display: block; width: 100%; min-height: 130px; padding: 10px 12px; border: 1px solid var(--cs-border); border-radius: 8px; background: var(--cs-surface); resize: vertical; }\ntextarea:focus-visible { outline-offset: 0; }\n.counter { margin-top: 4px; color: var(--cs-muted); font-size: 12px; text-align: right; }\n.details { margin-top: 12px; padding: 10px 12px; border: 1px solid var(--cs-border); border-radius: 8px; background: var(--cs-surface); }\n.details label { display: flex; align-items: center; gap: 8px; font-weight: 600; cursor: pointer; }\n.details input { width: 16px; height: 16px; margin: 0; accent-color: var(--cs-accent); }\n.details ul { margin: 8px 0 0; padding: 0; list-style: none; color: var(--cs-muted); font-size: 12px; }\n.details ul.off { opacity: 0.45; }\n.details li { overflow-wrap: anywhere; }\n.details .label { color: var(--cs-text); }\n.details li.editable { margin: 2px 0; }\n.details li.editable label { gap: 4px; font-weight: inherit; cursor: auto; }\n.details li.editable .label { flex: none; }\n.details li.editable input { flex: 1 1 auto; min-width: 0; width: auto; height: auto; padding: 2px 6px; border: 1px solid var(--cs-border); border-radius: 4px; background: var(--cs-background); color: var(--cs-text); font: inherit; }\n.details li.editable input:focus-visible { outline: 2px solid var(--cs-accent); outline-offset: 1px; }\n.details li.editable input:disabled { cursor: not-allowed; }\n.actions { display: flex; align-items: center; justify-content: flex-end; gap: 12px; margin-top: 16px; }\n.message { flex: 1; margin: 0; font-size: 13px; }\n.error { color: var(--cs-error); }\n.success { color: var(--cs-success); }\n.primary { padding: 9px 18px; border: none; border-radius: 8px; background: var(--cs-accent); color: var(--cs-accent-text); font-weight: 600; }\n.primary:hover:not(:disabled) { filter: brightness(1.1); }\n.secondary { padding: 6px 12px; border: 1px solid var(--cs-border); border-radius: 8px; background: none; }\nsection + section { margin-top: 18px; }\nh3 { margin: 0 0 8px; color: var(--cs-muted); font-size: 12px; font-weight: 600; letter-spacing: 0.05em; text-transform: uppercase; }\n.list { display: grid; gap: 8px; margin: 0; padding: 0; list-style: none; }\n.item { padding: 10px 12px; border: 1px solid var(--cs-border); border-radius: 8px; background: var(--cs-surface); }\n.meta { display: flex; flex-wrap: wrap; align-items: center; gap: 6px 10px; margin-bottom: 6px; color: var(--cs-muted); font-size: 12px; }\n.badge { padding: 1px 8px; border: 1px solid var(--cs-border); border-radius: 999px; color: var(--cs-text); }\n.badge.in_progress { border-color: var(--cs-accent); color: var(--cs-accent); }\n.badge.resolved { border-color: var(--cs-success); color: var(--cs-success); }\n.text { margin: 0; white-space: pre-wrap; overflow-wrap: anywhere; }\n.answer { margin-top: 8px; padding-left: 10px; border-left: 2px solid var(--cs-accent); }\n.answer-label { color: var(--cs-muted); font-size: 12px; font-weight: 600; }\n.note { margin: 0; color: var(--cs-muted); }\n.failed { display: flex; align-items: center; gap: 12px; }\ndetails { border: 1px solid var(--cs-border); border-radius: 8px; background: var(--cs-surface); }\nsummary { padding: 10px 12px; font-weight: 600; cursor: pointer; }\ndetails .text { padding: 0 12px 12px; }\n";

package/dist/types/dialog.d.ts

@@ -0,0 +1,13 @@
+import type { Host } from './host.js';
+import type { CrawlSpaceTab } from './types.js';
+export interface DialogElement extends HTMLElement {
+    /** Opens at `tab`, or switches to it when already open. */
+    showTab(tab: CrawlSpaceTab): void;
+    hide(): void;
+}
+/**
+ * `<crawl-space-dialog>`, added to `document.body` on first open. A native
+ * modal `<dialog>` gives the top layer, Escape to close, a focus trap and focus
+ * back to whatever opened it.
+ */
+export declare function defineDialog(getHost: () => Host): CustomElementConstructor;

package/dist/types/dom.d.ts

@@ -0,0 +1,6 @@
+export type Child = Node | string | null | undefined | false;
+/**
+ * Creates an element with attributes (`true` sets an empty one, `false` none)
+ * and children. Strings become text nodes, never markup.
+ */
+export declare function h<K extends keyof HTMLElementTagNameMap>(tag: K, attributes?: Record<string, string | boolean>, ...children: Child[]): HTMLElementTagNameMap[K];

package/dist/types/host.d.ts

@@ -0,0 +1,17 @@
+import type { CrawlSpaceApi } from './api.js';
+import type { ResolvedOptions } from './options.js';
+import type { Styles } from './styles.js';
+import type { CrawlSpaceTab } from './types.js';
+export interface Refreshable {
+    /** Picks up replaced options: title, theme, limits. */
+    refresh(): void;
+}
+/** What the elements share with the controller. A second `createCrawlSpace` replaces `options` and `api` in place. */
+export interface Host {
+    readonly options: ResolvedOptions;
+    readonly api: CrawlSpaceApi;
+    readonly styles: Styles;
+    /** The elements in the document, refreshed when the options are replaced. */
+    readonly connected: Set<Refreshable>;
+    open(tab: CrawlSpaceTab): void;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+export type { CrawlSpaceColors, CrawlSpaceConfig, CrawlSpaceContextEntry, CrawlSpaceController, CrawlSpaceDetail, CrawlSpaceOptions, CrawlSpacePosition, CrawlSpaceQaItem, CrawlSpaceReport, CrawlSpaceReportStatus, CrawlSpaceReportType, CrawlSpaceReports, CrawlSpaceSubmission, CrawlSpaceTab, CrawlSpaceTheme, } from './types.js';
+export { createCrawlSpace } from './crawl-space.js';
+export { sanitizeText } from './sanitize.js';

package/dist/types/lists.d.ts

@@ -0,0 +1,9 @@
+import type { Host } from './host.js';
+/** A tab's content. `show` runs each time the tab is shown. */
+export interface Panel {
+    readonly element: HTMLElement;
+    show(): void;
+    refresh?(): void;
+}
+export declare function createActivePanel(host: Host): Panel;
+export declare function createQaPanel(host: Host): Panel;

package/dist/types/options.d.ts

@@ -0,0 +1,23 @@
+import type { CrawlSpaceColors, CrawlSpaceOptions, CrawlSpacePosition, CrawlSpaceTab } from './types.js';
+/** The options after checking, with every default filled in. */
+export interface ResolvedOptions {
+    api: string;
+    paths: {
+        reports: string;
+        qa: string;
+    };
+    colors: CrawlSpaceColors;
+    /** Where the floating button goes; null for none. */
+    floating: CrawlSpacePosition | null;
+    title: string;
+    maxLength: number;
+    getToken?: CrawlSpaceOptions['getToken'];
+    version?: string;
+    scrubPath?: CrawlSpaceOptions['scrubPath'];
+    getContext?: CrawlSpaceOptions['getContext'];
+    onOpenChange?: CrawlSpaceOptions['onOpenChange'];
+}
+/** A tab name, or `submit` (with a warning for anything but nothing) when it isn't one. */
+export declare function toTab(value: unknown): CrawlSpaceTab;
+/** Checks the options at the package's boundary: `api` must be set; anything else invalid falls back with a warning. */
+export declare function resolveOptions(options: CrawlSpaceOptions): ResolvedOptions;

package/dist/types/sanitize.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Cleans text a user typed before it is sent: NFC, no control, zero-width or
+ * bidi characters, `\n` line ends, runs of three or more blank lines collapsed
+ * to one, trimmed, and at most `maxLength` UTF-16 units (never ending in half
+ * of a surrogate pair). The server stays the authority on what it accepts.
+ */
+export declare function sanitizeText(text: string, maxLength: number): string;

package/dist/types/styles.d.ts

@@ -0,0 +1,14 @@
+import type { CrawlSpaceColors } from './types.js';
+/**
+ * The theme as custom properties in a `:host` rule. A page's own rules beat
+ * `:host`, so `crawl-space-button { --cs-accent: ... }` overrides it.
+ */
+export declare function themeCss(colors: CrawlSpaceColors): string;
+export interface Styles {
+    /** Gives a shadow root `css` and the current theme. Safe to call again. */
+    apply(root: ShadowRoot, css: string): void;
+    /** Replaces the theme; roots without constructable sheets pick it up on their next `apply`. */
+    setColors(colors: CrawlSpaceColors): void;
+}
+/** One theme shared by every element: a constructable stylesheet where supported, else a `<style>` in each root. */
+export declare function createStyles(colors: CrawlSpaceColors): Styles;

package/dist/types/submit.d.ts

@@ -0,0 +1,4 @@
+import type { Host } from './host.js';
+import type { Panel } from './lists.js';
+/** The Submit tab: a bug or a question, and the details that go with it when ticked. */
+export declare function createSubmitPanel(host: Host): Panel;

package/dist/types/themes.d.ts

@@ -0,0 +1,5 @@
+import type { CrawlSpaceColors, CrawlSpaceConfig, CrawlSpaceTheme } from './types.js';
+/** Each preset's colors. `custom` is the base that `colors` go over. */
+export declare const THEMES: Readonly<Record<CrawlSpaceTheme, Readonly<CrawlSpaceColors>>>;
+/** The colors for a config's `theme`, with `colors` over `default` for `custom`. */
+export declare function resolveColors(config: Pick<CrawlSpaceConfig, 'theme' | 'colors'>): CrawlSpaceColors;

package/dist/types/types.d.ts

@@ -0,0 +1,112 @@
+/** The preset themes. `custom` is `colors` over `default`. */
+export type CrawlSpaceTheme = 'default' | 'brocode' | 'rombie' | 'taut-wad' | 'custom';
+export type CrawlSpacePosition = 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+/** Every value is a CSS color, except `font`, which is a CSS `font-family`. */
+export interface CrawlSpaceColors {
+    background: string;
+    surface: string;
+    text: string;
+    muted: string;
+    border: string;
+    accent: string;
+    /** Text on an `accent` background. */
+    accentText: string;
+    error: string;
+    success: string;
+    font: string;
+}
+/**
+ * The JSON-safe settings, kept in the app's `bro.config.json` and passed in.
+ * `theme` and `position` also take a plain `string`, because a JSON import types
+ * them that way; an unknown name falls back to the default with a warning.
+ */
+export interface CrawlSpaceConfig {
+    /** Base URL of the API, e.g. `https://api.example.com/api/crawl-space/my-app`. */
+    api: string;
+    /** Route paths under `api`. Default: `/reports` and `/qa`. */
+    paths?: {
+        reports?: string;
+        qa?: string;
+    };
+    /** Default: `default`. */
+    theme?: CrawlSpaceTheme | (string & {});
+    /** Used with `theme: 'custom'`; a missing or invalid value falls back to `default`'s. */
+    colors?: Partial<CrawlSpaceColors>;
+    /** Adds a floating button at `position` (default `bottom-right`). */
+    floating?: {
+        position?: CrawlSpacePosition | (string & {});
+    };
+    /** Dialog title and default button label. Default: `Help & bug reports`. */
+    title?: string;
+    /** Longest description accepted. Default: 2000. */
+    maxLength?: number;
+}
+/** The config plus the parts only code can supply. */
+export interface CrawlSpaceOptions extends CrawlSpaceConfig {
+    /** The signed-in user's token, sent as `Authorization: Bearer <token>`; null when signed out. */
+    getToken?: () => string | null | Promise<string | null>;
+    /** The app's version, sent as context. */
+    version?: string;
+    /** Removes anything private from the page path before it is shown or sent. */
+    scrubPath?: (path: string) => string;
+    /**
+     * More context entries, label to value, shown and sent after the built-in ones. A string is shown as it is; a
+     * `CrawlSpaceDetail` with `editable: true` is shown in a field the user can change or clear.
+     */
+    getContext?: () => Record<string, string | CrawlSpaceDetail>;
+    /** Called with true when the dialog opens and false when it closes. */
+    onOpenChange?: (open: boolean) => void;
+}
+export type CrawlSpaceTab = 'submit' | 'active' | 'qa';
+/** What `createCrawlSpace` returns. */
+export interface CrawlSpaceController {
+    /** Opens the dialog at `tab` (default `submit`), or switches to it if already open. */
+    open(tab?: CrawlSpaceTab): void;
+    close(): void;
+}
+/** A detail from `getContext`, with whether the user can change it before sending. */
+export interface CrawlSpaceDetail {
+    value: string;
+    editable?: boolean;
+}
+/** One line of the details sent with a report. */
+export interface CrawlSpaceContextEntry {
+    label: string;
+    value: string;
+    editable: boolean;
+}
+export type CrawlSpaceReportType = 'bug' | 'question';
+export type CrawlSpaceReportStatus = 'new' | 'in_progress' | 'resolved' | 'dismissed';
+/** The body of `POST {api}{paths.reports}`. */
+export interface CrawlSpaceSubmission {
+    type: CrawlSpaceReportType;
+    description: string;
+    /** Label to value; left out when the user unticks the details. */
+    context?: Record<string, string>;
+}
+export interface CrawlSpaceReport {
+    id: number | string;
+    type: CrawlSpaceReportType;
+    status: CrawlSpaceReportStatus;
+    description: string;
+    /** The developer's answer; only ever sent for the user's own reports. */
+    answer: string | null;
+    /** ISO 8601. */
+    createdAt: string;
+    /** ISO 8601. */
+    updatedAt: string;
+}
+export interface CrawlSpaceQaItem {
+    id: number | string;
+    question: string;
+    answer: string;
+    /** ISO 8601. */
+    updatedAt: string;
+}
+/** The body of `GET {api}{paths.reports}`. */
+export interface CrawlSpaceReports {
+    /** The signed-in user's reports in every status; empty when signed out. */
+    mine: CrawlSpaceReport[];
+    /** Everyone else's reports being worked on. */
+    active: CrawlSpaceReport[];
+}

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "@bro-code/crawl-space",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2026.0.0",
+  "type": "module",
+  "description": "A help desk for any web app (bug reports, active issues, Q&A) as framework-free custom elements, themed, against a documented HTTP API.",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "npm run build:esm && npm run build:cjs && npm run build:types && npm run build:fixup",
+    "build:esm": "tsc --project tsconfig.esm.json",
+    "build:cjs": "tsc --project tsconfig.cjs.json",
+    "build:types": "tsc --project tsconfig.types.json",
+    "build:fixup": "node scripts/fixup.cjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src/",
+    "prepublishOnly": "npm run lint && npm run test && npm run build",
+    "preversion": "npm run lint && npm run test",
+    "version": "git add -A"
+  },
+  "keywords": [
+    "help-desk",
+    "bug-report",
+    "feedback",
+    "custom-elements",
+    "web-components",
+    "browser",
+    "bro-code"
+  ],
+  "author": "Bro Code Technologies",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Bro-Code-Technologies/bro-code-package-maker.git",
+    "directory": "packages/crawl-space"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@eslint/js": "~10.0.1",
+    "eslint": "~10.13.0",
+    "happy-dom": "~21.0.4",
+    "typescript": "~6.0.3",
+    "typescript-eslint": "~8.72.1",
+    "vitest": "~4.1.12"
+  }
+}