@kingsleyweb/bun-ui 0.0.0-stage → 3.0.0-rc.2

package/dts/jobs/browser/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../lib/jobs/browser/config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD,YAAY,EAAE,OAAO,EAAE,CAAC;AAExB,0FAA0F;AAC1F,eAAO,MAAM,yBAAyB,uBAAuB,CAAC;AAE9D,kDAAkD;AAClD,MAAM,WAAW,cAAc;IAC7B,+DAA+D;IAC/D,MAAM,EAAE,OAAO,CAAC;IAChB,0EAA0E;IAC1E,IAAI,EAAE,OAAO,CAAC;CACf;AAED,2EAA2E;AAC3E,MAAM,WAAW,YAAY;IAC3B,gFAAgF;IAChF,OAAO,EAAE,CAAC,CAAC;IACX,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAC;IACd,2GAA2G;IAC3G,QAAQ,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B;;;;;OAKG;IACH,SAAS,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;IACxD,2EAA2E;IAC3E,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;IAC1D,kCAAkC;IAClC,QAAQ,EAAE,cAAc,CAAC;IACzB,6BAA6B;IAC7B,KAAK,EAAE,OAAO,CAAC;IACf;;;;OAIG;IACH,YAAY,EAAE,cAAc,GAAG,IAAI,CAAC;CACrC"}

package/dts/jobs/browser/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `@kingsleyweb/bun-ui/jobs/browser`: the jobs UI's browser-safe contract,
+ * what `jobsUi()` inlines into the page and the app reads before its first
+ * request. No runtime import beyond constants and no domain package, so a
+ * browser bundle (or a host reading the injected config) may import it.
+ */
+export type { JobsUiConfig, JobsUiSections, UiTheme } from "./config.js";
+export { JOBS_UI_CONFIG_ELEMENT_ID } from "./config.js";
+export type { UiUnauthorized, UiUnauthorizedStatus } from "./unauthorized.js";
+//# sourceMappingURL=index.d.ts.map

package/dts/jobs/browser/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../lib/jobs/browser/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACtE,OAAO,EAAE,yBAAyB,EAAE,MAAM,UAAU,CAAC;AACrD,YAAY,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC"}

package/dts/jobs/browser/unauthorized.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The `unauthorized` option's shared types, re-exported from the kit
+ * (`lib/kit/browser/unauthorized.ts`), which `docsUi()` uses too, as it does
+ * the code both run: validation and the shell's `303` (`lib/kit/unauthorized`),
+ * and the browser's redirect (`app/kit/unauthorized`). Types only, so
+ * `lib/jobs/browser` stays free of runtime imports.
+ */
+export type { UiUnauthorized, UiUnauthorizedStatus, } from "../../kit/browser/unauthorized.js";
+//# sourceMappingURL=unauthorized.d.ts.map

package/dts/jobs/browser/unauthorized.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unauthorized.d.ts","sourceRoot":"","sources":["../../../lib/jobs/browser/unauthorized.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,YAAY,EACV,cAAc,EACd,oBAAoB,GACrB,MAAM,gCAAgC,CAAC"}

package/dts/jobs/index.d.ts

@@ -0,0 +1,24 @@
+export { ASSET_CACHE_CONTROL, DEFAULT_BASE_PATH, DEFAULT_TITLE, jobsUi, } from "./jobsUi.js";
+/**
+ * `@kingsleyweb/bun-ui/jobs`: a management UI and API documentation viewer
+ * for the `@kingsleyweb/bun-jobs` management API. Needs
+ * `@kingsleyweb/bun-jobs`, an optional peer of the package that this entry
+ * (and `./lib/jobs/*`) alone requires.
+ *
+ * ```ts
+ * const api = createJobsApi({ jobs, basePath: "/jobs-api", authorize });
+ * const ui = jobsUi({ api, basePath: "/jobs" });
+ * app.use(api.basePath, api.router);
+ * app.use(ui.basePath, ui.router);
+ * ```
+ *
+ * The bundle machinery (`lib/jobs/assets.ts`: building, writing and loading
+ * `dist/jobs/`) is internal: `scripts/build.ts` and the tests import it directly.
+ * `JobsUiBaseOptions` stays public because both option interfaces extend it,
+ * so it is part of the options' declared shape.
+ */
+export type { UiUnauthorized, UiUnauthorizedStatus, } from "./browser/unauthorized.js";
+export type { JobsUiConfig, JobsUiSections, UiTheme } from "./browser/config.js";
+export { JOBS_UI_CONFIG_ELEMENT_ID } from "./browser/config.js";
+export type { JobsUi, JobsUiApiOptions, JobsUiUnauthorizedOptions, JobsUiAuthorize, JobsUiAuthorizeContext, JobsUiAuthorizeResult, JobsUiBaseOptions, JobsUiOptions, JobsUiUrlOptions, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dts/jobs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../lib/jobs/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,aAAa,EACb,MAAM,GACP,MAAM,UAAU,CAAC;AAClB;;;;;;;;;;;;;;;;;GAiBG;AACH,YAAY,EACV,cAAc,EACd,oBAAoB,GACrB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC9E,OAAO,EAAE,yBAAyB,EAAE,MAAM,kBAAkB,CAAC;AAC7D,YAAY,EACV,MAAM,EACN,gBAAgB,EAChB,yBAAyB,EACzB,eAAe,EACf,sBAAsB,EACtB,qBAAqB,EACrB,iBAAiB,EACjB,aAAa,EACb,gBAAgB,GACjB,MAAM,SAAS,CAAC"}

package/dts/jobs/jobsUi.d.ts

@@ -0,0 +1,63 @@
+import type { JobsUi, JobsUiOptions } from "./types.js";
+import { ASSET_CACHE_CONTROL } from "../kit/browser/shared.js";
+/** The UI's default mount path. */
+export declare const DEFAULT_BASE_PATH = "/jobs";
+/** The default page title. */
+export declare const DEFAULT_TITLE = "Jobs";
+/** The path under `basePath` the bundle is served from. */
+export declare const ASSETS_SUBPATH = "/assets";
+export { ASSET_CACHE_CONTROL };
+export { DEFAULT_RETURN_PARAM, DEFAULT_UNAUTHORIZED_STATUSES, } from "../kit/browser/unauthorized.js";
+/** Where the bundle comes from; tests point these at a fixture. */
+export interface JobsUiInternals {
+    /** The dist directory read when present. Defaults to the package's `dist/`. */
+    distDir?: string;
+    /** The entry built in memory without a dist. Defaults to `app/main.tsx`. */
+    entry?: string;
+}
+/**
+ * Validates and normalises an absolute mount path, as the API validates its
+ * `basePath`: absolute, trailing slashes dropped, not `"/"`, and only
+ * segments of letters, digits, `_`, `.`, `~` and `-`.
+ */
+export declare function normalizeBasePath(value: unknown, what: string): string;
+/**
+ * The read-only summary a newer API exposes as `api.info` (bun-jobs'
+ * `JobsApiInfo`). Typed structurally and feature-detected, so the UI works
+ * with an API that predates it and prefers it once it is there.
+ */
+export interface JobsApiInfoLike {
+    /** The API's CSRF settings; `header` is lower-cased, `null` for none. */
+    csrf?: {
+        header?: string | null;
+    };
+    /** Full paths of the spec documents actually routed, or `null` when docs are off. */
+    docs?: {
+        openapi: string;
+        asyncapi?: string;
+    } | null;
+    /** The socket's full path and, for a dedicated socket, its bound port; `null` without one. */
+    websocket?: {
+        path: string;
+        port?: number;
+    } | null;
+}
+/**
+ * Creates the UI with an explicit bundle source. {@link jobsUi} is this with
+ * the package's own `dist/` and `app/main.tsx`; tests point it at a fixture.
+ */
+export declare function createJobsUi(options: JobsUiOptions, internals?: JobsUiInternals): JobsUi;
+/**
+ * Creates the management UI: validates the options (throwing `ConfigError`
+ * for anything unusable), resolves the configuration the app is given, and
+ * builds the router.
+ *
+ * ```ts
+ * const api = createJobsApi({ jobs, basePath: "/admin/jobs-api", authorize });
+ * const ui = jobsUi({ api, basePath: "/admin/jobs" });
+ * app.use(api.basePath, api.router);
+ * app.use(ui.basePath, ui.router);
+ * ```
+ */
+export declare function jobsUi(options: JobsUiOptions): JobsUi;
+//# sourceMappingURL=jobsUi.d.ts.map

package/dts/jobs/jobsUi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jobsUi.d.ts","sourceRoot":"","sources":["../../lib/jobs/jobsUi.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EACV,MAAM,EAGN,aAAa,EACd,MAAM,SAAS,CAAC;AAIjB,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAa5D,mCAAmC;AACnC,eAAO,MAAM,iBAAiB,UAAU,CAAC;AAEzC,8BAA8B;AAC9B,eAAO,MAAM,aAAa,SAAS,CAAC;AAEpC,2DAA2D;AAC3D,eAAO,MAAM,cAAc,YAAY,CAAC;AAExC,OAAO,EAAE,mBAAmB,EAAE,CAAC;AAU/B,OAAO,EACL,oBAAoB,EACpB,6BAA6B,GAC9B,MAAM,6BAA6B,CAAC;AAErC,mEAAmE;AACnE,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAyBtE;AAgGD;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,yEAAyE;IACzE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAClC,qFAAqF;IACrF,IAAI,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACrD,8FAA8F;IAC9F,SAAS,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CACpD;AA2OD;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,aAAa,EACtB,SAAS,GAAE,eAAoB,GAC9B,MAAM,CA4OR;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAErD"}

package/dts/jobs/shell.d.ts

@@ -0,0 +1,77 @@
+import type { UiAssets } from "./assets.js";
+/**
+ * The HTML shell: the one page every client route answers with, and the
+ * Content-Security-Policy it is served under.
+ *
+ * Everything in it is fixed per mount except the nonce, which is fresh per
+ * request. The configuration travels as a nonce'd
+ * `<script type="application/json">`, escaped for a script context, so a title
+ * containing `</script>` cannot end the element early.
+ */
+import type { JobsUiConfig } from "./browser/config.js";
+/** A fresh CSP nonce: 128 random bits, base64. */
+export declare function createNonce(): string;
+/** Escapes text for an HTML text node or a quoted attribute value. */
+export declare function escapeHtml(value: string): string;
+/**
+ * Serialises a value as JSON that is safe inside a `<script>` element: `<`,
+ * `>` and `&` become `<`/`>`/`&` (so neither `</script>` nor
+ * `<!--` can appear), and U+2028/U+2029 are escaped too. The result is still
+ * valid JSON that parses back to the same value.
+ */
+export declare function jsonForScript(value: unknown): string;
+/** Inputs to {@link cspHeader}. */
+export interface CspOptions {
+    /** This request's nonce. */
+    nonce: string;
+    /**
+     * `connect-src` sources after `'self'`, usually from {@link connectSources}.
+     * A source that is not a single CSP token (whitespace, `;` or `,`) is
+     * dropped rather than written into the header. Defaults to none.
+     */
+    connectSrc?: readonly string[];
+}
+/**
+ * The shell's Content-Security-Policy. Scripts only from this origin and
+ * carrying the nonce; styles only from files (no inline `<style>`, no `style`
+ * attributes in markup — setting `element.style` from script is still fine);
+ * connections to `'self'` plus `connectSrc`.
+ */
+export declare function cspHeader(options: CspOptions): string;
+/** Inputs to {@link connectSources}. */
+export interface ConnectSourcesOptions {
+    /**
+     * The request's `Host` (`host[:port]`), i.e. the page's origin as the
+     * browser loaded it. Attacker-controlled on a misrouted request, so anything
+     * outside the `host[:port]` grammar is ignored, never copied into the header.
+     */
+    host: string | undefined;
+    /** Whether the page is `https`: its socket sources are then `wss:`, else `ws:`. */
+    secure: boolean;
+    /**
+     * The API's origin when it is elsewhere (`"https://api.example"`); added in
+     * its `http(s)` and `ws(s)` forms. Omitted for a same-origin API.
+     */
+    apiOrigin?: string;
+    /**
+     * A dedicated socket port (`config.websocket.port`); adds that port's
+     * `ws(s)` origin on the page's hostname. Omitted when the socket shares the
+     * page's port.
+     */
+    websocketPort?: number | null;
+}
+/**
+ * The `connect-src` sources after `'self'`: the `ws(s)` form of the page's own
+ * origin (older WebKit does not let `'self'` match `ws:`/`wss:`), a dedicated
+ * socket port on the same hostname, and a cross-origin API in both forms.
+ * Never a bare `ws:` or `wss:`, which would allow a socket to any host.
+ */
+export declare function connectSources(options: ConnectSourcesOptions): string[];
+/** A renderer for one mount: fixed parts computed once, the nonce per call. */
+export type ShellRenderer = (nonce: string) => string;
+/**
+ * Prepares the shell for a mount and a bundle. The returned function only
+ * splices a nonce in.
+ */
+export declare function createShellRenderer(config: JobsUiConfig, assets: UiAssets): ShellRenderer;
+//# sourceMappingURL=shell.d.ts.map

package/dts/jobs/shell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell.d.ts","sourceRoot":"","sources":["../../lib/jobs/shell.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACzC;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,YAAY,EAAW,MAAM,kBAAkB,CAAC;AAI9D,kDAAkD;AAClD,wBAAgB,WAAW,IAAI,MAAM,CAIpC;AAED,sEAAsE;AACtE,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAOhD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAOpD;AAOD,mCAAmC;AACnC,MAAM,WAAW,UAAU;IACzB,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAChC;AAKD;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,UAAU,GAAG,MAAM,CAerD;AAWD,wCAAwC;AACxC,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,mFAAmF;IACnF,MAAM,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,MAAM,EAAE,CA4BvE;AAED,+EAA+E;AAC/E,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;AAEtD;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,QAAQ,GACf,aAAa,CAqCf"}

package/dts/jobs/types.d.ts

@@ -0,0 +1,146 @@
+import type { BunRequest, BunRouter, LoggerLike, RouterHandler } from "@kingsleyweb/bun-common";
+import type { JobsApi, JobsApiAuthorizeResult } from "@kingsleyweb/bun-jobs";
+import type { UnauthorizedOptions } from "../kit/browser/unauthorized.js";
+import type { JobsUiConfig, JobsUiSections, UiTheme } from "./browser/config.js";
+/** What {@link JobsUiOptions.authorize} is told about the request being decided. */
+export interface JobsUiAuthorizeContext {
+    /** `true` for a bundle file under `<basePath>/assets/`, `false` for the HTML shell. */
+    asset: boolean;
+    /** The request's full path, e.g. `"/jobs/queues/mail"` (no query string). */
+    path: string;
+}
+/**
+ * What `authorize` answers — the same shape as the API's: `true`/`false`, or
+ * `{ allow: true }` / `{ allow: false, status?: 401 | 403, reason? }`.
+ * A denial is a 401 only when `status` is exactly `401`; any other `status`
+ * (a `429`, a `500`, a string) is a 403, as the API does — fail closed. Rate
+ * limiting belongs in `middleware`, which can answer 429 itself. Anything
+ * that is not one of these shapes denies with 403.
+ */
+export type JobsUiAuthorizeResult = JobsApiAuthorizeResult;
+/**
+ * Decides whether a request may load the UI. May be async; a throw (or a
+ * rejection) is a 500. A denial is 401 for `status: 401` and 403 for every
+ * other status — see {@link JobsUiAuthorizeResult}.
+ */
+export type JobsUiAuthorize = (req: BunRequest, context: JobsUiAuthorizeContext) => JobsUiAuthorizeResult | Promise<JobsUiAuthorizeResult>;
+/**
+ * Where to send the browser when an authorization check fails, instead of
+ * leaving it on a page whose screens report the failure. See
+ * {@link JobsUiBaseOptions.unauthorized}; the fields are described on
+ * `UnauthorizedOptions`, which `docsUi()` takes too.
+ */
+export type JobsUiUnauthorizedOptions = UnauthorizedOptions;
+/** Options shared by both ways of pointing the UI at its API. */
+export interface JobsUiBaseOptions {
+    /**
+     * Header every mutation must carry, as the API's `csrf.header`, or `false`
+     * for none (`config.csrfHeader` is then `null`). Unset: what `api` reports
+     * once the API exposes it (`api.info.csrf.header`, feature-detected), else
+     * none (`config.csrfHeader: null`). Until the API reports it, set it by hand
+     * to match the API's `csrf.header`.
+     */
+    csrfHeader?: string | false;
+    /**
+     * Absolute path the UI is mounted at: no trailing slash, not `"/"`, segments
+     * of letters, digits, `_`, `.`, `~` and `-`. Must not equal or sit under
+     * the API's `basePath`. Defaults to `"/jobs"`.
+     */
+    basePath?: string;
+    /** Page title and brand text. Defaults to `"Jobs"`. */
+    title?: string;
+    /**
+     * Sections to enable. Each defaults to `true`; switching both off is a
+     * `ConfigError`.
+     */
+    sections?: Partial<JobsUiSections>;
+    /**
+     * Guards the shell and the bundle — **not** the data, which the API's own
+     * `authorize` protects. Same result shape as the API's, and fails closed
+     * the same way: a denial is 401 only for `status: 401` and 403 for any
+     * other status (`429` included), an unrecognised answer is 403 and a throw
+     * is 500. Omitted: everyone may load the page.
+     */
+    authorize?: JobsUiAuthorize;
+    /**
+     * Sends the browser to a sign-in (or any other) page when the caller is not
+     * authorized, instead of showing the failure on every screen. Off by
+     * default (today's behaviour: the shell answers a problem, screens show
+     * their messages).
+     *
+     * With it set, for a status in `statuses` (`[401]` by default):
+     *
+     * - **The shell:** a browser navigation (`GET`/`HEAD` of a page, not a
+     *   bundle file) that `authorize` denies answers `303 See Other` to `redirectTo`.
+     *   A bundle file, and a request that is not a navigation (a script's
+     *   `fetch`, an `Accept` without `text/html`), keep the problem answer.
+     * - **The app:** the first API call (any query or mutation) or live-events
+     *   message that fails with such a status sends the browser to `redirectTo` with
+     *   `location.assign`, once per page load.
+     *
+     * A denial `middleware` answers itself is not redirected: only
+     * `authorize`'s. The target is fixed here, never read from the request, so
+     * it cannot be an open redirect. See {@link JobsUiUnauthorizedOptions}.
+     */
+    unauthorized?: JobsUiUnauthorizedOptions;
+    /**
+     * Middleware run before every UI route, on the `GET`/`HEAD` requests the UI
+     * answers (session loading, a rate limiter). Runs before `authorize`.
+     * Defaults to none.
+     */
+    middleware?: readonly RouterHandler[];
+    /** Initial colour scheme. Defaults to `"system"` (follows `prefers-color-scheme`). */
+    theme?: UiTheme;
+    /**
+     * Where the bundle comes from. Unset (default): the prebuilt `dist/` when
+     * present, else an in-memory `Bun.build` on the first request. `true`:
+     * always build in memory. `false`: `dist/` is required — `jobsUi()` throws
+     * a `ConfigError` without it.
+     */
+    dev?: boolean;
+    /** Logger, or anything `resolveLogger` accepts. Defaults to a console logger. */
+    logger?: LoggerLike;
+}
+/** `jobsUi()` beside a `createJobsApi` in the same process. */
+export interface JobsUiApiOptions extends JobsUiBaseOptions {
+    /**
+     * The API this UI manages. Its `basePath`, WebSocket path/port and docs
+     * paths are read from it.
+     */
+    api: JobsApi;
+    /** Not with `api`. */
+    apiUrl?: never;
+}
+/** `jobsUi()` for an API in another process or on another origin. */
+export interface JobsUiUrlOptions extends JobsUiBaseOptions {
+    /**
+     * Base URL of the API, no trailing slash needed: a same-origin absolute
+     * path (`"/jobs-api"`) or an `http(s)://` URL. Either way the path follows
+     * `basePath`'s segment rules (checked on the string as written, so `..`, a
+     * space or `%2F` is refused rather than normalised away) and may not carry
+     * a query or a fragment; a URL may not carry credentials, and its path may
+     * be empty (the API at the origin root). The WebSocket and docs paths are
+     * then discovered by the app from `/meta` at runtime (`config.websocket`
+     * and `config.docs` are `null`). A URL's origin is added to the CSP's
+     * `connect-src` in `http(s)` and `ws(s)` form. A cross-origin API needs
+     * CORS, CSRF and WebSocket origins configured on its side.
+     */
+    apiUrl: string;
+    /** Not with `apiUrl`. */
+    api?: never;
+}
+/** Options for `jobsUi()`: exactly one of `api` and `apiUrl`. */
+export type JobsUiOptions = JobsUiApiOptions | JobsUiUrlOptions;
+/** A mountable UI. */
+export interface JobsUi {
+    /**
+     * Serves the shell and the bundle. Mount with `use(ui.basePath, ui.router)`,
+     * on a bun-common or a bun-nest adapter.
+     */
+    readonly router: BunRouter;
+    /** The normalised `basePath`, no trailing slash. */
+    readonly basePath: string;
+    /** The configuration injected into every page, frozen. */
+    readonly config: Readonly<JobsUiConfig>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dts/jobs/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../lib/jobs/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,SAAS,EACT,UAAU,EACV,aAAa,EACd,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAC7E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AACvE,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAE9E,oFAAoF;AACpF,MAAM,WAAW,sBAAsB;IACrC,uFAAuF;IACvF,KAAK,EAAE,OAAO,CAAC;IACf,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,qBAAqB,GAAG,sBAAsB,CAAC;AAE3D;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,CAC5B,GAAG,EAAE,UAAU,EACf,OAAO,EAAE,sBAAsB,KAC5B,qBAAqB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;AAE5D;;;;;GAKG;AACH,MAAM,MAAM,yBAAyB,GAAG,mBAAmB,CAAC;AAE5D,iEAAiE;AACjE,MAAM,WAAW,iBAAiB;IAChC;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;IACnC;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,YAAY,CAAC,EAAE,yBAAyB,CAAC;IACzC;;;;OAIG;IACH,UAAU,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IACtC,sFAAsF;IACtF,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,iFAAiF;IACjF,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB;AAED,+DAA+D;AAC/D,MAAM,WAAW,gBAAiB,SAAQ,iBAAiB;IACzD;;;OAGG;IACH,GAAG,EAAE,OAAO,CAAC;IACb,sBAAsB;IACtB,MAAM,CAAC,EAAE,KAAK,CAAC;CAChB;AAED,qEAAqE;AACrE,MAAM,WAAW,gBAAiB,SAAQ,iBAAiB;IACzD;;;;;;;;;;;OAWG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,yBAAyB;IACzB,GAAG,CAAC,EAAE,KAAK,CAAC;CACb;AAED,iEAAiE;AACjE,MAAM,MAAM,aAAa,GAAG,gBAAgB,GAAG,gBAAgB,CAAC;AAEhE,sBAAsB;AACtB,MAAM,WAAW,MAAM;IACrB;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,oDAAoD;IACpD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,YAAY,CAAC,CAAC;CACzC"}

package/dts/kit/browser/shared.d.ts

@@ -0,0 +1,10 @@
+/**
+ * What every UI of the package shares and a browser may import: no runtime
+ * import, no domain package. The root entry (`@kingsleyweb/bun-ui`) and each
+ * UI's `/<ui>/browser` entry re-export from here.
+ */
+/** Colour scheme a UI starts in. `"system"` follows `prefers-color-scheme`. */
+export type UiTheme = "system" | "light" | "dark";
+/** `Cache-Control` for hashed bundle files: their name changes with their content. */
+export declare const ASSET_CACHE_CONTROL = "public, max-age=31536000, immutable";
+//# sourceMappingURL=shared.d.ts.map

package/dts/kit/browser/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../../lib/kit/browser/shared.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,+EAA+E;AAC/E,MAAM,MAAM,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAC;AAElD,sFAAsF;AACtF,eAAO,MAAM,mBAAmB,wCAAwC,CAAC"}

package/dts/kit/browser/unauthorized.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The `unauthorized` option: where to send the browser when the caller turns
+ * out not to be signed in. Shared by `docsUi()` and `jobsUi()`,
+ * on both sides of each: the server (the shell's 303) and the app (an API
+ * 401). Types, defaults and pure functions only, with no runtime imports: the
+ * apps bundle this file for the browser.
+ */
+/** A status that can trigger the redirect: 401 (not signed in) or 403 (not allowed). */
+export type UiUnauthorizedStatus = 401 | 403;
+/**
+ * The `unauthorized` option as a host writes it: where to send the browser
+ * when an authorization check fails, instead of leaving it on a page that
+ * reports the failure.
+ */
+export interface UnauthorizedOptions {
+    /**
+     * Where to go: a path on this host starting with one `/` (`"/login"`,
+     * `"/auth/sign-in?app=jobs"`), or an absolute `http:`/`https:` URL (an
+     * identity provider's sign-in page). Required. A path inside the UI's own
+     * `basePath` is a `ConfigError`: the UI would redirect to itself.
+     * `javascript:`, `data:`, `//host` and anything else are refused.
+     */
+    redirectTo: string;
+    /**
+     * Query parameter that carries the page the user was on, so the sign-in
+     * page can send them back: path, query and (in the browser) fragment,
+     * always a relative URL starting with one `/` (e.g.
+     * `/login?returnTo=%2Fdocs%2Fhttp`). `false` adds nothing. Defaults to
+     * `"returnTo"`. Letters, digits, `_`, `.`, `~` and `-` only. The sign-in
+     * page must still check the value before redirecting to it.
+     */
+    returnParam?: string | false;
+    /**
+     * Which failures redirect. Defaults to `[401]`: only "not signed in". A 403
+     * means signed in but not allowed, which the page explains itself; add
+     * `403` to redirect on that too. Must be a non-empty array of `401` and
+     * `403`.
+     */
+    statuses?: readonly UiUnauthorizedStatus[];
+}
+/** The resolved `unauthorized` option, as the browser receives it in the page's config. */
+export interface UiUnauthorized {
+    /** The target: a path (`"/login"`) or an absolute `http(s)` URL, validated on the server. */
+    redirectTo: string;
+    /** The query parameter that carries the in-app location back, or `null` for none. */
+    returnParam: string | null;
+    /** The statuses that redirect, ascending and without repeats (`[401]` by default). */
+    statuses: readonly UiUnauthorizedStatus[];
+}
+/** `unauthorized.returnParam` when unset. */
+export declare const DEFAULT_RETURN_PARAM = "returnTo";
+/** `unauthorized.statuses` when unset: only "not signed in". */
+export declare const DEFAULT_UNAUTHORIZED_STATUSES: readonly UiUnauthorizedStatus[];
+/**
+ * Whether a value read back from a page's config has the shape of a
+ * {@link UiUnauthorized}: enough that a stale or hand-edited shell fails with
+ * a message instead of a broken redirect. The server validated the values.
+ */
+export declare function isUiUnauthorized(value: unknown): value is UiUnauthorized;
+/**
+ * Makes an in-app location safe to hand back as a relative URL: it starts
+ * with exactly one `/` (never `//` or `/\`, which a browser reads as another
+ * host). Anything not starting with `/` becomes `/`.
+ */
+export declare function relativeReturnPath(location: string): string;
+/**
+ * The URL to send the browser to: `redirectTo`, with `returnParam` set to
+ * `returnPath` (made relative by {@link relativeReturnPath}) when both are
+ * given. A path target stays a path; an absolute target stays absolute. A
+ * `returnParam` already in `redirectTo`'s query is replaced, and its
+ * fragment is kept.
+ */
+export declare function unauthorizedRedirectUrl(redirect: Pick<UiUnauthorized, "redirectTo" | "returnParam">, returnPath: string | undefined): string;
+//# sourceMappingURL=unauthorized.d.ts.map

package/dts/kit/browser/unauthorized.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unauthorized.d.ts","sourceRoot":"","sources":["../../../lib/kit/browser/unauthorized.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,wFAAwF;AACxF,MAAM,MAAM,oBAAoB,GAAG,GAAG,GAAG,GAAG,CAAC;AAE7C;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;OAMG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;CAC5C;AAED,2FAA2F;AAC3F,MAAM,WAAW,cAAc;IAC7B,6FAA6F;IAC7F,UAAU,EAAE,MAAM,CAAC;IACnB,qFAAqF;IACrF,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,sFAAsF;IACtF,QAAQ,EAAE,SAAS,oBAAoB,EAAE,CAAC;CAC3C;AAED,6CAA6C;AAC7C,eAAO,MAAM,oBAAoB,aAAa,CAAC;AAE/C,gEAAgE;AAChE,eAAO,MAAM,6BAA6B,EAAE,SAAS,oBAAoB,EACnD,CAAC;AAEvB;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAWxE;AAKD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAK3D;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,IAAI,CAAC,cAAc,EAAE,YAAY,GAAG,aAAa,CAAC,EAC5D,UAAU,EAAE,MAAM,GAAG,SAAS,GAC7B,MAAM,CAUR"}

package/dts/kit/unauthorized.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The server half of the `unauthorized` option, shared by `docsUi()` and
+ * `jobsUi()`: validating it, telling a page navigation from any other
+ * request, and answering the shell's `303`. The browser half is
+ * `app/kit/unauthorized.ts` (`./docs/embed/unauthorized`); what both need is
+ * `lib/kit/browser/unauthorized.ts`.
+ */
+import type { BunRequest, BunResponse } from "@kingsleyweb/bun-common";
+import type { UiUnauthorized } from "./browser/unauthorized.js";
+/**
+ * Builds the error a refused option throws: each caller passes its own
+ * `ConfigError` (`docsUi()` bun-common's, `jobsUi()` bun-jobs'), so a refusal
+ * is the class that caller's users already catch.
+ */
+export type UnauthorizedConfigError = (
+/** What is wrong, starting with the option's name. */
+message: string, 
+/** The offending values, for the error's context. */
+context: Record<string, unknown>) => Error;
+/**
+ * Validates the `unauthorized` option and fills in its defaults; `null` when
+ * it is unset (the option is off). Every refusal is thrown as `fail` builds
+ * it.
+ *
+ * @param value The option as the host passed it.
+ * @param basePath The UI's normalised `basePath`, for the redirect-loop check.
+ * @param fail Builds the caller's own `ConfigError`.
+ */
+export declare function resolveUnauthorized(value: unknown, basePath: string, fail: UnauthorizedConfigError): UiUnauthorized | null;
+/**
+ * Whether a request is a browser navigation, the only kind a redirect helps:
+ * `Sec-Fetch-Mode: navigate` when the browser sends the header (every
+ * current one does), else an `Accept` naming `text/html`. A script's
+ * `fetch`, `curl` (whose `Accept` is the any-type wildcard) and a health
+ * probe are not, and keep the problem.
+ */
+export declare function isNavigation(req: BunRequest): boolean;
+/**
+ * Whether a denial with `status` should be answered with the redirect: the
+ * option is on, the route is a page of the shell (not a bundle file, not a
+ * document the viewer fetches), the status is listed, and the request is a
+ * navigation.
+ */
+export declare function redirectsDenial(redirect: UiUnauthorized | null, shell: boolean, status: number, req: BunRequest): redirect is UiUnauthorized;
+/** Answers `303 See Other` to the sign-in target, carrying the request's own path and query back. */
+export declare function sendUnauthorizedRedirect(req: BunRequest, res: BunResponse, redirect: UiUnauthorized): void;
+//# sourceMappingURL=unauthorized.d.ts.map

package/dts/kit/unauthorized.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unauthorized.d.ts","sourceRoot":"","sources":["../../lib/kit/unauthorized.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACvE,OAAO,KAAK,EACV,cAAc,EAEf,MAAM,wBAAwB,CAAC;AAOhC;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG;AACpC,sDAAsD;AACtD,OAAO,EAAE,MAAM;AACf,qDAAqD;AACrD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC7B,KAAK,CAAC;AAsFX;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,uBAAuB,GAC5B,cAAc,GAAG,IAAI,CA8CvB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAMrD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,cAAc,GAAG,IAAI,EAC/B,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,UAAU,GACd,QAAQ,IAAI,cAAc,CAO5B;AAED,qGAAqG;AACrG,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,UAAU,EACf,GAAG,EAAE,WAAW,EAChB,QAAQ,EAAE,cAAc,GACvB,IAAI,CAMN"}