@bro-code/crawl-space

A help desk for any web app (bug reports, active issues, Q&A) as framework-free custom elements, themed, against a documented HTTP API.

One call gives an app a dialog with three tabs:

• Submit: a bug or a question, with the details that help (version, page, browser, OS and anything the app adds), shown before sending under an "Include these details" checkbox the user can untick.
• Active: the signed-in user's own reports first, in every status and with the developer's answer, then everyone's reports being worked on.
• Q&A: published questions and their answers.

The elements live in a shadow DOM, so the page's CSS doesn't reach them and theirs doesn't leak out. It works with any library or none, has no runtime dependencies, and does nothing when imported. Without a window (server rendering), createCrawlSpace does nothing and returns a controller whose methods do nothing.

Installation

npm install @bro-code/crawl-space

Usage

Keep the settings in the app's bro.config.json:

{
  "crawlSpace": {
    "api": "http://localhost:8080/api/crawl-space/my-app",
    "theme": "brocode"
  }
}

A browser can't read that file at runtime, so import the section and pass it in, with the parts only code can supply (TypeScript needs resolveJsonModule, which moduleResolution: "bundler" turns on; Vite keeps only the imported section in the bundle):

import { createCrawlSpace } from '@bro-code/crawl-space';
import { crawlSpace } from '../bro.config.json';

const help = createCrawlSpace({
  ...crawlSpace,
  // The API's address can come from the app's env instead.
  api: import.meta.env.VITE_API_URL ? `${import.meta.env.VITE_API_URL}/crawl-space/my-app` : crawlSpace.api,
  getToken: () => localStorage.getItem('token'),
  version: '1.4.0',
});

A CommonJS build is included too: const { createCrawlSpace } = require('@bro-code/crawl-space');.

Call it once, at startup. A second call (a dev server's hot reload) replaces the options and returns the same controller.

There are three ways to open it:

help.open();        // the Submit tab
help.open('qa');    // or 'active'
help.close();

<!-- Anywhere in a template; its text is the label (the title when empty). -->
<crawl-space-button tab="active">What's being fixed?</crawl-space-button>

{ "crawlSpace": { "api": "...", "floating": { "position": "bottom-right" } } }

floating adds a button fixed in a corner of the page. <crawl-space-button floating> does the same in a template.

Options

In bro.config.json (CrawlSpaceConfig)

| Field | Default | | |---|---|---| | api | | Required. The API's base URL; the routes below go under it. | | paths.reports | /reports | The reports route. | | paths.qa | /qa | The Q&A route. | | theme | default | default, brocode, rombie, taut-wad or custom. See Themes. | | colors | | With theme: 'custom', any of the ten theme values over default's. | | floating.position | bottom-right | Adds the floating button: bottom-right, bottom-left, top-right or top-left. | | title | Help & bug reports | The dialog's title and the buttons' default label. | | maxLength | 2000 | The longest description accepted. |

In code only (CrawlSpaceOptions)

| Option | | |---|---| | getToken | () => string \| null \| Promise<string \| null>. The signed-in user's token, sent as Authorization: Bearer <token>; null when signed out. | | version | The app's version, sent as a detail. | | scrubPath | (path) => string. Takes anything private out of the page path (a room code, a token) before it is shown or sent. | | getContext | () => Record<string, string \| CrawlSpaceDetail>. More details, label to value, shown and sent after the built-in ones. A { value, editable: true } detail is shown in a field the user can change or clear. | | onOpenChange | (open) => void, called when the dialog opens and closes (to pause an app's own keyboard or gamepad handling, say). |

An invalid api throws a TypeError. Anything else that's invalid falls back to its default with a console.warn.

The details

In order: Version, Page (location.pathname only, never the query or hash, through scrubPath), Browser (name and major version), OS (name only), then getContext()'s entries. Each label and value is cleaned with sanitizeText; empty ones and repeated labels are left out. brocodetech accepts up to 12 entries, labels up to 40 characters and values up to 200, and the package keeps to that.

Only the app's own details can be editable, so the user can correct or remove something the app guessed (which game they were playing, say) while the built-in four stay as collected:

getContext: () => ({
  Console: { value: 'NES', editable: true },
  'Last game': { value: lastGameTitle, editable: true },
}),

The field is sent as it reads when the report goes, cleaned the same way; a field left empty leaves that detail out. Unticking "Include these details" disables the fields and sends none of the details. An edit lasts while the dialog switches tabs, as long as the app's value for it stays the same; a sent report puts the app's values back.

Themes

| | default | brocode | rombie | taut-wad | |---|---|---|---|---| | background | #121417 | #181818 | #0a0a12 | #181818 | | surface | #1c1f24 | #222222 | #15141f | #222222 | | text | #e8eaed | #ffffff | #f1eef9 | #ffffff | | muted | #9aa0a6 | #b0b0b0 | #9a90bd | #b0b0b0 | | border | #33373d | #3c3c3c | #302c47 | #3c3c3c | | accent | #5b9cff | #7b9981 | #ff2d78 | #7b9981 | | accentText | #0b1220 | #ffffff | #12060d | #ffffff | | error | #ff6b6b | #ff5252 | #ff5c5c | #ff5252 | | success | #6fcf97 | #96be4d | #00e5ff | #96be4d | | font | system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif | Roboto, sans-serif | system-ui, 'Segoe UI', Roboto, sans-serif | Roboto, sans-serif |

custom starts from default:

{ "crawlSpace": { "api": "...", "theme": "custom", "colors": { "accent": "#e91e63", "font": "Georgia, serif" } } }

Each color is checked with CSS.supports('color', ...) and the font with CSS.supports('font-family', ...); a missing or invalid one keeps default's, with a warning for the invalid ones. An unknown theme is default, with a warning.

Restyling

The theme is set as custom properties on each element, and a page's own rules win over them:

crawl-space-button,
crawl-space-dialog {
  --cs-accent: #e91e63;
}

The properties are --cs-background, --cs-surface, --cs-text, --cs-muted, --cs-border, --cs-accent, --cs-accent-text, --cs-error, --cs-success and --cs-font. The button itself is a part:

crawl-space-button::part(button) {
  border-radius: 0;
  text-transform: uppercase;
}

Small screens and touch

Two rules apply in every app, whatever the theme, and are not options:

• Below 600px wide, the dialog fills the screen: the full width, and the full height in dvh, so a phone's browser bars don't cut it off, with no border, rounded corners or shadow. Each tab still scrolls inside it. From 600px it is the card.
• On touch input ((hover: none)), the close button (48 by 48), the tabs, the Bug and Question toggle, the "Include these details" row and its checkbox (24px), Send, Try again and the Q&A questions are at least 48px tall, with at least 8px between neighbours. With a mouse they keep their smaller sizes.

Setup per library

The elements are plain custom elements. Tell a framework's template compiler they aren't its components:

Vue (vite.config.ts):

vue({
  template: { compilerOptions: { isCustomElement: (tag) => tag.startsWith('crawl-space-') } },
});

Angular: add CUSTOM_ELEMENTS_SCHEMA to the schemas of each standalone component (or module) whose template uses <crawl-space-button>.

React 19 renders custom elements as they are; declare the button for JSX once, in a .d.ts:

import type { DetailedHTMLProps, HTMLAttributes } from 'react';

declare module 'react' {
  namespace JSX {
    interface IntrinsicElements {
      'crawl-space-button': DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement> & {
        tab?: 'submit' | 'active' | 'qa';
        floating?: boolean;
      };
    }
  }
}

HTTP API

Any server can back it. brocodetech's /api/crawl-space/:app routes are the reference implementation. Every request sends Accept: application/json, and Authorization: Bearer <token> when getToken returns a token.

POST {api}{paths.reports}

Sends a report.

{ "type": "bug", "description": "The save is gone", "context": { "Version": "1.4.0", "Page": "/play" } }

• type is bug or question. description is cleaned with sanitizeText and at most maxLength long. context is left out when the user unticks the details.
• 201 with { "id": 12 } on success. 429 tells the user to try again in a minute; any other status is a failure, and the text is kept so they can resend.

GET {api}{paths.reports}

{ "mine": [Report], "active": [Report] }

• mine is the signed-in user's reports in every status (brocodetech leaves out ones resolved or dismissed more than 30 days ago), empty when there's no token. Its answer is shown.
• active is everyone else's reports being worked on.

A Report is { id, type, status, description, answer, createdAt, updatedAt }: id a number or string, status one of new, in_progress, resolved and dismissed, answer a string or null, and the dates ISO 8601.

GET {api}{paths.qa}

An array of { id, question, answer, updatedAt }.

What the client trusts

Responses are checked: a malformed item is dropped, fields the contract doesn't name are ignored, and a malformed body is a failed load. Everything from the API and from users is rendered as text, never markup. The server stays the authority: it should validate and limit what it accepts, limit how often an address can post, and never put a reporter's account, email or details in a public response.

An API on another origin than the site must allow the site's origin in CORS, for GET and POST with the Content-Type and Authorization headers.

API

| Export | | |---|---| | createCrawlSpace(options) | Sets everything up and returns { open(tab?), close() }. | | sanitizeText(text, maxLength) | Cleans text a user typed: 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). | | Types | CrawlSpaceConfig, CrawlSpaceOptions, CrawlSpaceController, CrawlSpaceTab, CrawlSpaceTheme, CrawlSpaceColors, CrawlSpacePosition, CrawlSpaceDetail, CrawlSpaceContextEntry, CrawlSpaceSubmission, CrawlSpaceReport, CrawlSpaceReports, CrawlSpaceReportType, CrawlSpaceReportStatus, CrawlSpaceQaItem. |

The dialog is a native modal <dialog>: it sits above everything on the page, Escape closes it, focus stays inside while it's open and goes back to what opened it. The arrow keys, Home and End move between the tabs.

License

MIT - see LICENSE.

Changelog

[2026.1.0] - 2026-11-11

Changed

• Below 600px wide the dialog fills the screen (full width, 100dvh tall, no border, radius or shadow), and on touch input ((hover: none)) its close button, tabs, Bug and Question toggle, details row and checkbox, Send, Try again and Q&A questions are at least 48px tall with at least 8px between them. Both apply in every app; a mouse keeps today's sizes.

[2026.0.0] - 2026-11-04

Added

• Initial release.
• createCrawlSpace(options), with open(tab?) and close(), the <crawl-space-button> element and the floating button.
• The Submit, Active and Q&A tabs, against the documented HTTP API.
• Details from getContext the user can change or clear before sending ({ value, editable: true }).
• The default, brocode, rombie, taut-wad and custom themes, the --cs-* properties and ::part(button).
• sanitizeText(text, maxLength).