@openchamber/sdk 2.5.0 → 2.5.2

package/dist/service-providers.js

@@ -15,6 +15,7 @@ export const BROWSER_CONTROL_ACTIONS = [
     'browser.snapshot',
     'browser.click',
     'browser.type',
+    'browser.select',
     'browser.scroll',
     'browser.back',
     'browser.forward',
@@ -72,3 +73,218 @@ export const readBrowserProviderRequest = (body) => {
     // and the host validated the parameters for this action before posting.
     return { requestId, action, parameters, context: readContext(context) };
 };
+/*
+ * Source control: a service with `provides: ["source-control"]` is the Git
+ * host `contributes.sourceControl` describes. OpenChamber keeps the user's
+ * accounts and tokens, the bindings, the idempotent mutation records and the
+ * caches; it forwards the resource reads and the three mutation steps to the
+ * service at `SOURCE_CONTROL_PROVIDER_PATH`. The service never sees a token: it
+ * reaches the forge through OpenChamber's outbound proxy
+ * (`createSourceControlForge`), which pins the instance origin and adds the
+ * stored token itself.
+ */
+/** Route on the service loopback OpenChamber posts every source-control call to. */
+export const SOURCE_CONTROL_PROVIDER_PATH = '/source-control';
+/** The `v` of every request; a service answers a version it does not know with HTTP 400. */
+export const SOURCE_CONTROL_PROVIDER_WIRE_VERSION = 1;
+/**
+ * Every call OpenChamber forwards. `auth.verify` reads who a candidate token
+ * belongs to and `auth.probe` whether the instance is this forge; the fifteen
+ * reads take the shell's own input without the session; the three
+ * `mutation.*` steps are the part of a write the service owns, while
+ * OpenChamber owns the kind, the normalized input, its digest, the
+ * idempotency record and when each step runs.
+ */
+export const SOURCE_CONTROL_PROVIDER_METHODS = [
+    'auth.verify',
+    'auth.probe',
+    'changeRequestStatus',
+    'listChangeRequests',
+    'changeRequestContext',
+    'listIssues',
+    'getIssue',
+    'issueComments',
+    'projectUpstream',
+    'projectBranches',
+    'listLabels',
+    'listReviewerCandidates',
+    'readChangeRequestPatch',
+    'readChangeRequestFile',
+    'liveSummaries',
+    'readChangeRequestHead',
+    'resolveChangeRequestSource',
+    'mutation.resolveTarget',
+    'mutation.perform',
+    'mutation.reconcile',
+];
+/** `changeRequestStatus` answers within the badge's own deadline; past it the last known status shows. */
+export const SOURCE_CONTROL_PROVIDER_STATUS_TIMEOUT_MS = 12_000;
+export const SOURCE_CONTROL_PROVIDER_READ_TIMEOUT_MS = 20_000;
+export const SOURCE_CONTROL_PROVIDER_MUTATION_TIMEOUT_MS = 30_000;
+export const SOURCE_CONTROL_PROVIDER_AUTH_TIMEOUT_MS = 15_000;
+/** Answers are read up to this many bytes, enough for a change request's patch or one file. */
+export const SOURCE_CONTROL_PROVIDER_RESPONSE_MAX = 8_000_000;
+/** Characters of `error.message` OpenChamber reads. */
+export const SOURCE_CONTROL_PROVIDER_ERROR_MESSAGE_MAX = 2_000;
+/** No call for this long stops the service; the next call starts it again. */
+export const SOURCE_CONTROL_PROVIDER_IDLE_MS = 10 * 60_000;
+/** Characters of a mutation's `providerTarget` JSON, which OpenChamber stores with the record. */
+export const SOURCE_CONTROL_PROVIDER_TARGET_MAX = 4_096;
+/** How long OpenChamber waits for the service to answer `method`. */
+export const sourceControlProviderTimeoutMs = (method) => {
+    if (method === 'changeRequestStatus')
+        return SOURCE_CONTROL_PROVIDER_STATUS_TIMEOUT_MS;
+    if (method === 'auth.verify' || method === 'auth.probe')
+        return SOURCE_CONTROL_PROVIDER_AUTH_TIMEOUT_MS;
+    if (method.startsWith('mutation.'))
+        return SOURCE_CONTROL_PROVIDER_MUTATION_TIMEOUT_MS;
+    return SOURCE_CONTROL_PROVIDER_READ_TIMEOUT_MS;
+};
+/**
+ * Environment variable with the base URL of OpenChamber's callback listener
+ * (`http://127.0.0.1:<port>`). Set only for a service that provides
+ * `source-control`; `createSourceControlForge` reads it.
+ */
+export const OPENCHAMBER_HOST_CALLBACK_URL = 'OPENCHAMBER_HOST_CALLBACK_URL';
+/** Route on the callback listener a service sends a forge request to. */
+export const SOURCE_CONTROL_OUTBOUND_PATH = '/source-control/outbound';
+export const SOURCE_CONTROL_OUTBOUND_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
+/** Request headers OpenChamber passes to the forge; it sets every other header itself. */
+export const SOURCE_CONTROL_OUTBOUND_REQUEST_HEADERS = ['accept', 'content-type', 'if-none-match', 'range'];
+/** Response headers OpenChamber hands back, plus any starting with `SOURCE_CONTROL_OUTBOUND_RESPONSE_HEADER_PREFIX`. */
+export const SOURCE_CONTROL_OUTBOUND_RESPONSE_HEADERS = ['content-type', 'link', 'etag', 'x-total-count', 'x-total', 'retry-after'];
+export const SOURCE_CONTROL_OUTBOUND_RESPONSE_HEADER_PREFIX = 'x-ratelimit-';
+/** Characters of an outbound request body. */
+export const SOURCE_CONTROL_OUTBOUND_BODY_MAX = 1_000_000;
+/** Bytes of a forge answer OpenChamber reads; a longer one is refused whole. */
+export const SOURCE_CONTROL_OUTBOUND_RESPONSE_MAX = 8_000_000;
+/** One forge request may take this long; the call's own deadline may end it sooner. */
+export const SOURCE_CONTROL_OUTBOUND_TIMEOUT_MS = 20_000;
+export const isSourceControlProviderMethod = (value) => (SOURCE_CONTROL_PROVIDER_METHODS.some((method) => method === value));
+/** `undefined` is a user that is neither `null` nor `{ id, login }`. */
+const readSessionUser = (user) => {
+    if (user === null)
+        return null;
+    if (Object(user) !== user || user === undefined)
+        return undefined;
+    const { id, login } = user;
+    if (!Number.isSafeInteger(id) || String(login) !== login || login.length === 0)
+        return undefined;
+    return { id: Number(id), login };
+};
+/** `undefined` is a session that is neither `null` nor `{ instance, handle, user }`. */
+const readSession = (session) => {
+    if (session === null)
+        return null;
+    if (Object(session) !== session || session === undefined)
+        return undefined;
+    const { instance, handle } = session;
+    if (String(instance) !== instance || instance.length === 0 || String(handle) !== handle || handle.length === 0)
+        return undefined;
+    const user = readSessionUser(session.user);
+    if (user === undefined)
+        return undefined;
+    return { instance, handle, user };
+};
+/**
+ * A service's read of the body OpenChamber posted to
+ * `SOURCE_CONTROL_PROVIDER_PATH`. OpenChamber built and validated `input`, so
+ * this checks the envelope, not every field, and the service bundle needs no
+ * schema library. `null` is a body that is not a source-control call of this
+ * wire version; answer it with HTTP 400.
+ */
+export const readSourceControlProviderRequest = (body) => {
+    let wire;
+    try {
+        const parsed = JSON.parse(body);
+        if (Object(parsed) !== parsed || parsed === null)
+            return null;
+        wire = parsed;
+    }
+    catch {
+        return null;
+    }
+    const { v, requestId, method, provider, input } = wire;
+    if (v !== SOURCE_CONTROL_PROVIDER_WIRE_VERSION)
+        return null;
+    if (String(requestId) !== requestId || requestId.length === 0)
+        return null;
+    if (String(provider) !== provider || provider.length === 0)
+        return null;
+    if (String(method) !== method || !isSourceControlProviderMethod(method))
+        return null;
+    if (Object(input) !== input || Array.isArray(input))
+        return null;
+    const session = readSession(wire.session);
+    if (session === undefined)
+        return null;
+    // SAFETY: `input` is a plain object parsed from JSON, so every value in it is JSON.
+    return { v: SOURCE_CONTROL_PROVIDER_WIRE_VERSION, requestId, method, provider, session, input: input };
+};
+/**
+ * OpenChamber refused the request (an expired handle, a path off the
+ * instance, a body too large), could not reach the forge, or did not answer.
+ * `status` is the callback listener's HTTP status, `0` when it gave none;
+ * `code` is its error code (`HOST_UNAVAILABLE` when there was no usable answer).
+ */
+export class SourceControlForgeError extends Error {
+    code;
+    status;
+    constructor(message, code, status) {
+        super(message);
+        this.name = 'SourceControlForgeError';
+        this.code = code;
+        this.status = status;
+    }
+}
+/**
+ * The service's way to the forge: OpenChamber's callback listener
+ * (`OPENCHAMBER_HOST_CALLBACK_URL`), which checks the handle, keeps the request
+ * on the instance origin and adds the token. Plain `fetch`, no dependencies.
+ * Throws `SourceControlForgeError` when OpenChamber refuses the request; a
+ * forge answer of any status, 401 included, resolves.
+ */
+export const createSourceControlForge = ({ env }) => {
+    const base = env[OPENCHAMBER_HOST_CALLBACK_URL];
+    if (!base)
+        throw new Error(`${OPENCHAMBER_HOST_CALLBACK_URL} is not set: only a service that provides "source-control" can reach a forge.`);
+    const url = `${base.replace(/\/+$/, '')}${SOURCE_CONTROL_OUTBOUND_PATH}`;
+    return {
+        async request(handle, request) {
+            let response;
+            try {
+                response = await fetch(url, {
+                    method: 'POST',
+                    headers: { authorization: `Bearer ${handle}`, 'content-type': 'application/json' },
+                    body: JSON.stringify(request),
+                    // A little past OpenChamber's own deadline, so its answer wins.
+                    signal: AbortSignal.timeout(SOURCE_CONTROL_OUTBOUND_TIMEOUT_MS + 5_000),
+                });
+            }
+            catch (error) {
+                throw new SourceControlForgeError(`OpenChamber did not answer: ${error instanceof Error ? error.message : String(error)}`, 'HOST_UNAVAILABLE', 0);
+            }
+            let answer;
+            try {
+                answer = Object(await response.json());
+            }
+            catch {
+                throw new SourceControlForgeError('OpenChamber answered with something other than JSON', 'HOST_UNAVAILABLE', response.status);
+            }
+            if (!response.ok) {
+                const message = answer.error?.message;
+                const code = answer.error?.code;
+                throw new SourceControlForgeError(String(message) === message && message.length > 0 ? message : `OpenChamber refused the request (${response.status})`, String(code) === code && code.length > 0 ? code : 'OUTBOUND_REFUSED', response.status);
+            }
+            if (!Number.isSafeInteger(answer.status) || String(answer.body) !== answer.body) {
+                throw new SourceControlForgeError('OpenChamber relayed a malformed forge answer', 'HOST_UNAVAILABLE', response.status);
+            }
+            const headers = {};
+            for (const [name, text] of Object.entries(Object(answer.headers ?? {}))) {
+                if (String(text) === text)
+                    headers[name] = text;
+            }
+            return { status: Number(answer.status), headers, body: answer.body };
+        },
+    };
+};

package/dist/status-view-schemas.d.ts

@@ -0,0 +1,166 @@
+import { z } from 'zod';
+/** A service's answer to `GET <source.path>`. Row ids and control ids are each unique. */
+export declare const guestStatusViewSchema: z.ZodObject<{
+    rows: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        kind: z.ZodLiteral<"line">;
+        id: z.ZodString;
+        label: z.ZodString;
+        icon: z.ZodOptional<z.ZodString>;
+        dot: z.ZodOptional<z.ZodEnum<{
+            accent: "accent";
+            default: "default";
+            error: "error";
+            info: "info";
+            muted: "muted";
+            success: "success";
+            warning: "warning";
+        }>>;
+        content: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+            kind: z.ZodLiteral<"bar">;
+            value: z.ZodNumber;
+            tone: z.ZodOptional<z.ZodEnum<{
+                accent: "accent";
+                default: "default";
+                error: "error";
+                info: "info";
+                muted: "muted";
+                success: "success";
+                warning: "warning";
+            }>>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"chart">;
+            values: z.ZodArray<z.ZodNumber>;
+            max: z.ZodOptional<z.ZodNumber>;
+            tone: z.ZodOptional<z.ZodEnum<{
+                accent: "accent";
+                default: "default";
+                error: "error";
+                info: "info";
+                muted: "muted";
+                success: "success";
+                warning: "warning";
+            }>>;
+            unit: z.ZodOptional<z.ZodEnum<{
+                bytes: "bytes";
+                count: "count";
+                percent: "percent";
+            }>>;
+            step: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"chips">;
+            chips: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                label: z.ZodString;
+                tone: z.ZodOptional<z.ZodEnum<{
+                    accent: "accent";
+                    default: "default";
+                    error: "error";
+                    info: "info";
+                    muted: "muted";
+                    success: "success";
+                    warning: "warning";
+                }>>;
+                url: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"text">;
+            text: z.ZodString;
+            tone: z.ZodOptional<z.ZodEnum<{
+                accent: "accent";
+                default: "default";
+                error: "error";
+                info: "info";
+                muted: "muted";
+                success: "success";
+                warning: "warning";
+            }>>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"segmented">;
+            id: z.ZodString;
+            label: z.ZodString;
+            value: z.ZodString;
+            options: z.ZodArray<z.ZodObject<{
+                value: z.ZodString;
+                label: z.ZodString;
+            }, z.core.$strict>>;
+            disabled: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>]>>;
+        value: z.ZodOptional<z.ZodString>;
+        valueTone: z.ZodOptional<z.ZodEnum<{
+            accent: "accent";
+            default: "default";
+            error: "error";
+            info: "info";
+            muted: "muted";
+            success: "success";
+            warning: "warning";
+        }>>;
+        badge: z.ZodOptional<z.ZodObject<{
+            label: z.ZodString;
+            tone: z.ZodOptional<z.ZodEnum<{
+                accent: "accent";
+                default: "default";
+                error: "error";
+                info: "info";
+                muted: "muted";
+                success: "success";
+                warning: "warning";
+            }>>;
+        }, z.core.$strict>>;
+        tooltip: z.ZodOptional<z.ZodString>;
+        actions: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+            kind: z.ZodLiteral<"button">;
+            id: z.ZodString;
+            label: z.ZodString;
+            variant: z.ZodOptional<z.ZodEnum<{
+                default: "default";
+                destructive: "destructive";
+                outline: "outline";
+            }>>;
+            confirm: z.ZodOptional<z.ZodString>;
+            disabled: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"switch">;
+            id: z.ZodString;
+            label: z.ZodString;
+            checked: z.ZodBoolean;
+            disabled: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"select">;
+            id: z.ZodString;
+            label: z.ZodString;
+            value: z.ZodString;
+            options: z.ZodArray<z.ZodObject<{
+                value: z.ZodString;
+                label: z.ZodString;
+            }, z.core.$strict>>;
+            disabled: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>]>>>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"note">;
+        id: z.ZodString;
+        text: z.ZodString;
+        tone: z.ZodOptional<z.ZodEnum<{
+            error: "error";
+            info: "info";
+            muted: "muted";
+            warning: "warning";
+        }>>;
+    }, z.core.$strict>]>>;
+    controls: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"button">;
+        id: z.ZodString;
+        label: z.ZodString;
+        disabled: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"select">;
+        id: z.ZodString;
+        label: z.ZodString;
+        value: z.ZodString;
+        options: z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            label: z.ZodString;
+        }, z.core.$strict>>;
+        disabled: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>], "kind">>>;
+}, z.core.$strict>;

package/dist/status-view-schemas.js

@@ -0,0 +1,113 @@
+import { z } from 'zod';
+import { guestStatusControlsSchema } from './status-control-schemas.js';
+import { GUEST_STATUS_CONTROL_ID, GUEST_STATUS_CONTROL_LABEL_MAX, GUEST_STATUS_CONTROL_OPTIONS_MAX, GUEST_STATUS_CONTROL_VALUE_MAX, } from './status-controls.js';
+import { GUEST_STATUS_VIEW_ACTIONS_MAX, GUEST_STATUS_VIEW_CHART_POINTS_MAX, GUEST_STATUS_VIEW_CHIPS_MAX, GUEST_STATUS_VIEW_ICON, GUEST_STATUS_VIEW_NOTE_MAX, GUEST_STATUS_VIEW_ROWS_MAX, GUEST_STATUS_VIEW_SEGMENTS_MAX, GUEST_STATUS_VIEW_SEGMENTS_MIN, GUEST_STATUS_VIEW_TEXT_MAX, } from './status-view.js';
+const idSchema = z.string().regex(GUEST_STATUS_CONTROL_ID);
+const labelSchema = z.string().min(1).max(GUEST_STATUS_CONTROL_LABEL_MAX);
+const valueSchema = z.string().min(1).max(GUEST_STATUS_CONTROL_VALUE_MAX);
+const textSchema = z.string().min(1).max(GUEST_STATUS_VIEW_TEXT_MAX);
+const toneSchema = z.enum(['default', 'muted', 'accent', 'success', 'warning', 'error', 'info']);
+const finite = z.number().finite();
+const isWebUrl = (value) => {
+    try {
+        const url = new URL(value);
+        return url.protocol === 'http:' || url.protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+};
+const optionSchema = z.object({ value: valueSchema, label: labelSchema }).strict();
+/** One to `max` options with unique values, and `value` among them. */
+const choiceSchema = (kind, min, max) => z.object({
+    kind: z.literal(kind),
+    id: idSchema,
+    label: labelSchema,
+    value: valueSchema,
+    options: z.array(optionSchema).min(min).max(max),
+    disabled: z.boolean().optional(),
+}).strict().refine((choice) => new Set(choice.options.map((option) => option.value)).size === choice.options.length, { message: 'option values must be unique', path: ['options'] }).refine((choice) => choice.options.some((option) => option.value === choice.value), { message: 'value must be one of its options', path: ['value'] });
+const chipSchema = z.object({
+    id: idSchema,
+    label: labelSchema,
+    tone: toneSchema.optional(),
+    url: z.string().max(2_000).refine(isWebUrl, { message: 'chip url must be http(s)' }).optional(),
+}).strict();
+const contentSchema = z.union([
+    z.object({ kind: z.literal('bar'), value: finite.min(0).max(100), tone: toneSchema.optional() }).strict(),
+    z.object({
+        kind: z.literal('chart'),
+        values: z.array(finite.min(0)).max(GUEST_STATUS_VIEW_CHART_POINTS_MAX),
+        max: finite.positive().optional(),
+        tone: toneSchema.optional(),
+        unit: z.enum(['bytes', 'percent', 'count']).optional(),
+        step: finite.positive().max(3_600).optional(),
+    }).strict(),
+    z.object({
+        kind: z.literal('chips'),
+        chips: z.array(chipSchema).min(1).max(GUEST_STATUS_VIEW_CHIPS_MAX),
+    }).strict(),
+    z.object({ kind: z.literal('text'), text: textSchema, tone: toneSchema.optional() }).strict(),
+    choiceSchema('segmented', GUEST_STATUS_VIEW_SEGMENTS_MIN, GUEST_STATUS_VIEW_SEGMENTS_MAX),
+]);
+const actionSchema = z.union([
+    z.object({
+        kind: z.literal('button'),
+        id: idSchema,
+        label: labelSchema,
+        variant: z.enum(['default', 'outline', 'destructive']).optional(),
+        confirm: labelSchema.optional(),
+        disabled: z.boolean().optional(),
+    }).strict(),
+    z.object({
+        kind: z.literal('switch'),
+        id: idSchema,
+        label: labelSchema,
+        checked: z.boolean(),
+        disabled: z.boolean().optional(),
+    }).strict(),
+    choiceSchema('select', 1, GUEST_STATUS_CONTROL_OPTIONS_MAX),
+]);
+const rowSchema = z.union([
+    z.object({
+        kind: z.literal('line'),
+        id: idSchema,
+        label: labelSchema,
+        icon: z.string().regex(GUEST_STATUS_VIEW_ICON).optional(),
+        dot: toneSchema.optional(),
+        content: contentSchema.optional(),
+        value: valueSchema.optional(),
+        valueTone: toneSchema.optional(),
+        badge: z.object({ label: labelSchema, tone: toneSchema.optional() }).strict().optional(),
+        tooltip: textSchema.optional(),
+        actions: z.array(actionSchema).max(GUEST_STATUS_VIEW_ACTIONS_MAX).optional(),
+    }).strict(),
+    z.object({
+        kind: z.literal('note'),
+        id: idSchema,
+        text: z.string().min(1).max(GUEST_STATUS_VIEW_NOTE_MAX),
+        tone: z.enum(['muted', 'info', 'warning', 'error']).optional(),
+    }).strict(),
+]);
+/** Every id a view's controls answer to: header controls, line actions, segmented choices. */
+const controlIds = (view) => [
+    ...(view.controls ?? []).map((control) => control.id),
+    ...view.rows.flatMap((row) => (row.kind === 'line'
+        ? [
+            ...(row.actions ?? []).map((action) => action.id),
+            ...(row.content?.kind === 'segmented' ? [row.content.id] : []),
+        ]
+        : [])),
+];
+/** A service's answer to `GET <source.path>`. Row ids and control ids are each unique. */
+export const guestStatusViewSchema = z.object({
+    rows: z.array(rowSchema).max(GUEST_STATUS_VIEW_ROWS_MAX),
+    controls: guestStatusControlsSchema.optional(),
+}).strict().refine((view) => new Set(view.rows.map((row) => row.id)).size === view.rows.length, { message: 'row ids must be unique', path: ['rows'] }).refine((view) => {
+    const ids = controlIds(view);
+    return new Set(ids).size === ids.length;
+}, { message: 'control ids must be unique across the view' });
+const assertViewParsed = (value) => value;
+const assertViewContract = (value) => value;
+void assertViewParsed;
+void assertViewContract;

package/dist/status-view.d.ts

@@ -0,0 +1,129 @@
+import type { GuestStatusControl, GuestStatusControlOption } from './status-controls.ts';
+/** Fastest the host asks a service for its section, in ms. */
+export declare const GUEST_STATUS_SOURCE_INTERVAL_MIN = 1000;
+/** Slowest polling a source may ask for, in ms. */
+export declare const GUEST_STATUS_SOURCE_INTERVAL_MAX = 60000;
+/** Polling interval when the manifest names none, in ms. */
+export declare const GUEST_STATUS_SOURCE_INTERVAL_DEFAULT = 2000;
+export declare const GUEST_STATUS_VIEW_ROWS_MAX = 16;
+export declare const GUEST_STATUS_VIEW_ACTIONS_MAX = 2;
+export declare const GUEST_STATUS_VIEW_CHIPS_MAX = 6;
+export declare const GUEST_STATUS_VIEW_CHART_POINTS_MAX = 120;
+export declare const GUEST_STATUS_VIEW_SEGMENTS_MIN = 2;
+export declare const GUEST_STATUS_VIEW_SEGMENTS_MAX = 4;
+export declare const GUEST_STATUS_VIEW_TEXT_MAX = 200;
+export declare const GUEST_STATUS_VIEW_NOTE_MAX = 300;
+export declare const GUEST_STATUS_VIEW_ICON: RegExp;
+/** Where the host reads a source-backed section and how often. */
+export type StatusSectionSource = {
+    /** Service path, such as `/status`. */
+    path: string;
+    /** Milliseconds between reads while the section is on screen. */
+    interval?: number;
+};
+/**
+ * Colours come from the theme, never from the extension: `accent` is the
+ * theme's primary, the status tones are its status colours, `muted` is
+ * secondary text.
+ */
+export type GuestStatusTone = 'default' | 'muted' | 'accent' | 'success' | 'warning' | 'error' | 'info';
+/** How a chart's hover label formats a point. */
+export type GuestStatusChartUnit = 'bytes' | 'percent' | 'count';
+export type GuestStatusChip = {
+    id: string;
+    label: string;
+    tone?: GuestStatusTone;
+    /** An `http(s)` URL the chip opens; without one the chip is a label. */
+    url?: string;
+};
+/** What sits between a line's label and its value. */
+export type GuestStatusContent = {
+    kind: 'bar';
+    value: number;
+    tone?: GuestStatusTone;
+} | {
+    kind: 'chart';
+    /** Oldest first; the newest point sits at the right edge. */
+    values: number[];
+    /** Top of the chart; the largest value when omitted. */
+    max?: number;
+    tone?: GuestStatusTone;
+    unit?: GuestStatusChartUnit;
+    /** Seconds between points, for the hover's "12 s ago". */
+    step?: number;
+} | {
+    kind: 'chips';
+    chips: GuestStatusChip[];
+} | {
+    kind: 'text';
+    text: string;
+    tone?: GuestStatusTone;
+} | {
+    kind: 'segmented';
+    id: string;
+    label: string;
+    value: string;
+    options: GuestStatusControlOption[];
+    disabled?: boolean;
+};
+/** A control at the end of a line. Activating it posts `{ id, value? }` to the source path. */
+export type GuestStatusAction = {
+    kind: 'button';
+    id: string;
+    label: string;
+    variant?: 'default' | 'outline' | 'destructive';
+    /** Asked on the first click; the second click acts. */
+    confirm?: string;
+    disabled?: boolean;
+} | {
+    kind: 'switch';
+    id: string;
+    label: string;
+    checked: boolean;
+    disabled?: boolean;
+} | {
+    kind: 'select';
+    id: string;
+    label: string;
+    value: string;
+    options: GuestStatusControlOption[];
+    disabled?: boolean;
+};
+export type GuestStatusRow = {
+    kind: 'line';
+    id: string;
+    label: string;
+    /** A Remixicon name, as in `panel.icon`. */
+    icon?: string;
+    /** A status dot before the label. */
+    dot?: GuestStatusTone;
+    content?: GuestStatusContent;
+    value?: string;
+    valueTone?: GuestStatusTone;
+    badge?: {
+        label: string;
+        tone?: GuestStatusTone;
+    };
+    tooltip?: string;
+    actions?: GuestStatusAction[];
+} | {
+    kind: 'note';
+    id: string;
+    text: string;
+    tone?: 'muted' | 'info' | 'warning' | 'error';
+};
+/** The answer to `GET <source.path>`. */
+export type GuestStatusView = {
+    rows: GuestStatusRow[];
+    /** Header controls, the same declarations `setStatusControls` takes. */
+    controls?: GuestStatusControl[];
+};
+/**
+ * The body of `POST <source.path>` when the user activates a control. A switch
+ * sends `on` or `off`; a select or segmented control sends the chosen value; a
+ * button sends no value.
+ */
+export type GuestStatusActionEvent = {
+    id: string;
+    value?: string;
+};

package/dist/status-view.js

@@ -0,0 +1,15 @@
+/** Fastest the host asks a service for its section, in ms. */
+export const GUEST_STATUS_SOURCE_INTERVAL_MIN = 1_000;
+/** Slowest polling a source may ask for, in ms. */
+export const GUEST_STATUS_SOURCE_INTERVAL_MAX = 60_000;
+/** Polling interval when the manifest names none, in ms. */
+export const GUEST_STATUS_SOURCE_INTERVAL_DEFAULT = 2_000;
+export const GUEST_STATUS_VIEW_ROWS_MAX = 16;
+export const GUEST_STATUS_VIEW_ACTIONS_MAX = 2;
+export const GUEST_STATUS_VIEW_CHIPS_MAX = 6;
+export const GUEST_STATUS_VIEW_CHART_POINTS_MAX = 120;
+export const GUEST_STATUS_VIEW_SEGMENTS_MIN = 2;
+export const GUEST_STATUS_VIEW_SEGMENTS_MAX = 4;
+export const GUEST_STATUS_VIEW_TEXT_MAX = 200;
+export const GUEST_STATUS_VIEW_NOTE_MAX = 300;
+export const GUEST_STATUS_VIEW_ICON = /^[a-z0-9][a-z0-9-]{0,39}$/;