@mccaskie-labs/workbench-config 0.1.20 → 0.1.22

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @mccaskie-labs/workbench-config
 
+## 0.1.22
+
+### Patch Changes
+
+- Brand assets: `checkLogo` (PNG or JPEG by its own bytes, at most 256 KiB, SVG refused because Gmail and Outlook don't show it), `placeholderLogo` (a 96 × 96 PNG of the name's initials on the colour), `colourForId` (a steady colour per project id that white text reads on), `parseColour`, `whiteContrast`, `shownSize` and `LOGO_PATHS`. Used by Control's brand pages and each app's Brand settings page.
+
+## 0.1.21
+
+### Patch Changes
+
+- The `ui` component: `capabilities/ui.json` (rules and probes for `@mccaskie-labs/workbench-ui`) joins the manifests, and `ui` joins the component list.
+
 ## 0.1.20
 
 ### Patch Changes

package/README.md

@@ -28,6 +28,7 @@ const { WORKBENCH_GATEWAY_KEY } = config.parse(env)
 | `redact(value)`, `redactAll(text, secrets)` | `[redacted]` in place of a secret, for logs |
 | `capabilities`, `MANIFEST_VERSION`, `capabilitySchema` | The Workbench capabilities manifests and their schema. The JSON files are also at `@mccaskie-labs/workbench-config/capabilities/<component>.json` |
 | `defineBrand(json)`, `brandSchema`, `resolveBrand`, `BRAND_DEFAULTS`, `BRAND_FILE` | The app's brand file, `brand.json` at the repo root: `name`, `siteUrl` (https), `logo.url` (https PNG, JPEG or SVG; optional `alt`, `width`, `height`), `colours.primary` (`#rrggbb`; `text`, `background`, `muted` default), optional `fonts.heading`/`fonts.body` (`{ family, url? }`, `url` an https stylesheet), `supportEmail` and `footer`. Unknown keys fail. Account emails, PDFs and Supabase's sign-in emails all read it |
+| `checkLogo(bytes)`, `placeholderLogo(name, colour)`, `colourForId(id)`, `parseColour`, `whiteContrast`, `shownSize`, `LOGO_PATHS`, `MAX_LOGO_BYTES`, `BrandAssetError` | Setting a brand from an upload: the logo is checked by its own bytes (PNG or JPEG, at most 256 KiB; SVG refused because Gmail and Outlook don't show it), a project with no logo gets its initials on its colour as a 96 × 96 PNG, and a project with no colour gets a steady one from its id that white text reads on (WCAG 4.5:1). Runs in Workers, the browser and Node |
 | `VENDOR_SETTINGS`, `resolveVendorSettings(file, env)`, `vendorSettingsFileSchema`, `VENDOR_SETTINGS_FILE`, `SEND_EMAIL_HOOK`, `SEND_EMAIL_HOOK_PATH`, `SEND_EMAIL_HOOK_SECRET` | The vendor settings baseline: settings that live in a vendor dashboard (field, value, where it is, what breaks if it changes). A project changes a row in `vendor-settings.json` at its repo root, with a reason. Control applies it with `vendor_settings_apply` and compares it every day |
 | `DEFAULT_GATEWAY_URL` | `https://gateway.mccaskielabs.dev` |
 

package/capabilities/schema.json

@@ -32,7 +32,8 @@
         "r2",
         "kv",
         "github",
-        "strings"
+        "strings",
+        "ui"
       ]
     },
     "title": {

package/capabilities/ui.json

@@ -0,0 +1,91 @@
+{
+  "$schema": "./schema.json",
+  "format": 1,
+  "component": "ui",
+  "title": "One look for every page",
+  "summary": "workbench-ui gives every Workbench page the same dark look: the page shell, a top bar with the environment tag, cards that fold, jump pills, outcome pills, and one way to write times, money and durations. It returns HTML text in the app's own Worker, with no Gateway call and no cost.",
+  "status": "built",
+  "surfaces": {
+    "package": [
+      "shell",
+      "topBar",
+      "card",
+      "jumpNav",
+      "SECTIONS_SCRIPT",
+      "pill",
+      "chip",
+      "when",
+      "shortWhen",
+      "timeLeft",
+      "money",
+      "duration",
+      "escape",
+      "STYLE",
+      "CSS"
+    ]
+  },
+  "rules": [
+    {
+      "id": "ui.one-look",
+      "kind": "must",
+      "text": "Build every page a person opens with shell (or STYLE for a page that writes its own document), so each page has the same top bar, cards and pills.",
+      "enforced_by": "review",
+      "probe": "ui.page"
+    },
+    {
+      "id": "ui.environment-tag",
+      "kind": "must",
+      "text": "Pass the environment to topBar, so every page says whether it is staging or production.",
+      "enforced_by": "review",
+      "probe": "ui.page"
+    },
+    {
+      "id": "ui.escape",
+      "kind": "must",
+      "text": "Escape any text that goes into an HTML argument (a card's inner, a top bar's extra) with escape. Arguments described as plain text are escaped for you.",
+      "enforced_by": "review",
+      "probe": "ui.page"
+    },
+    {
+      "id": "ui.no-own-colours",
+      "kind": "must_not",
+      "text": "Give a page its own colours. A page's own rules go after the shared ones and use the colour tokens (--surface, --line, --pass and so on).",
+      "enforced_by": "review",
+      "probe": "ui.page"
+    },
+    {
+      "id": "ui.one-format",
+      "kind": "must",
+      "text": "Write the times, amounts and durations a page shows with when, shortWhen, timeLeft, money and duration, not hand-built strings.",
+      "enforced_by": "review",
+      "probe": "ui.formats"
+    }
+  ],
+  "examples": [
+    {
+      "id": "ui.example.page",
+      "title": "A page with one folding card",
+      "lang": "ts",
+      "probe": "ui.page",
+      "code": "import { workbenchEnv } from '@mccaskie-labs/workbench-config'\nimport { card, pill, shell, shortWhen, topBar } from '@mccaskie-labs/workbench-ui'\n\nconst html = shell({\n  title: 'Orders',\n  site: 'my-app',\n  top: topBar({ name: 'my-app', href: '/', env: workbenchEnv(env), links: [['History', '/history']] }),\n  body: card('Last order', `<div class=\"body\">${pill('pass', 'Sent')} ${shortWhen(order.sent_at)}</div>`, {\n    id: 'last-order',\n    about: 'The most recent order and when it went out.',\n    collapsible: true,\n  }),\n})"
+    }
+  ],
+  "probes": [
+    {
+      "id": "ui.page",
+      "half": "runtime",
+      "expect": "pass",
+      "smoke": true,
+      "cost_hint_usd": 0,
+      "note": "In the Worker itself: builds one page with shell, topBar, jumpNav, a folding card and a pill, and checks the shared stylesheet is there with its colour tokens, the environment tag is shown, the pill carries its tone, the jump pill points at the card, and markup in a plain-text title and in text passed through escape both come out escaped"
+    },
+    {
+      "id": "ui.formats",
+      "half": "runtime",
+      "expect": "pass",
+      "smoke": true,
+      "cost_hint_usd": 0,
+      "note": "In the Worker itself: compares money (US$0.0042, US$12.50, and an en dash for nothing), duration (640 ms, 2.35 s, 3 min 5 s) and timeLeft against a fixed now (42 minutes left) with the expected text, and checks when and shortWhen write one fixed moment as its Manila day and hour with UTC beside it"
+    }
+  ]
+}

package/dist/brand-assets.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Checks and makes a brand's logo and colour, the same way wherever a brand
+ * is set: Control's new-project and Brand pages, and the Brand settings page
+ * inside each app (decided by Robert, 11 November 2026). Runs in Workers, the
+ * browser and Node: no Node built-ins.
+ */
+/** The logo emails and PDFs show. Gmail and Outlook don't show SVG, so PNG or JPEG only. */
+export declare const MAX_LOGO_BYTES: number;
+/** Where an app serves its logo, by type. Control's Access bypass opens exactly these paths. */
+export declare const LOGO_PATHS: {
+    readonly png: "/brand/logo.png";
+    readonly jpg: "/brand/logo.jpg";
+};
+export type LogoExt = keyof typeof LOGO_PATHS;
+export declare const LOGO_CONTENT_TYPES: Record<LogoExt, string>;
+export type BrandAssetErrorCode = "invalid_logo" | "svg_logo" | "logo_too_big" | "invalid_colour";
+/** A logo or colour that can't be used. The message is safe to show the person uploading. */
+export declare class BrandAssetError extends Error {
+    readonly code: BrandAssetErrorCode;
+    constructor(code: BrandAssetErrorCode, message: string);
+}
+export interface CheckedLogo {
+    ext: LogoExt;
+    contentType: string;
+    /** Pixel size, read from the file. */
+    width: number;
+    height: number;
+}
+/** Checks an uploaded logo by its own bytes (not its name or declared type). Throws a BrandAssetError. */
+export declare function checkLogo(bytes: Uint8Array): CheckedLogo;
+/** The size a logo is shown at in brand.json: 48 pixels high, at most 240 wide. */
+export declare function shownSize(logo: Pick<CheckedLogo, "width" | "height">): {
+    width: number;
+    height: number;
+};
+/** "#1F4E79" or "1f4e79" as "#1f4e79". Throws a BrandAssetError. */
+export declare function parseColour(text: string): string;
+/** WCAG contrast ratio of white text on this colour; 4.5 or more reads well. */
+export declare function whiteContrast(colour: string): number;
+/** A steady colour for a project id: always the same for that id, dark enough for white text. */
+export declare function colourForId(id: string): string;
+/** Up to two letters for a name: "Galing Gear" is GG, "wb-probe" is WP, "imprint" is I. */
+export declare function initials(name: string): string;
+/** A 96 × 96 PNG of the name's initials on the colour, for a project with no logo yet. */
+export declare function placeholderLogo(name: string, colour: string): Promise<Uint8Array>;

package/dist/brand-assets.js

@@ -0,0 +1,221 @@
+/**
+ * Checks and makes a brand's logo and colour, the same way wherever a brand
+ * is set: Control's new-project and Brand pages, and the Brand settings page
+ * inside each app (decided by Robert, 11 November 2026). Runs in Workers, the
+ * browser and Node: no Node built-ins.
+ */
+/** The logo emails and PDFs show. Gmail and Outlook don't show SVG, so PNG or JPEG only. */
+export const MAX_LOGO_BYTES = 256 * 1024;
+/** Where an app serves its logo, by type. Control's Access bypass opens exactly these paths. */
+export const LOGO_PATHS = { png: "/brand/logo.png", jpg: "/brand/logo.jpg" };
+export const LOGO_CONTENT_TYPES = { png: "image/png", jpg: "image/jpeg" };
+/** A logo or colour that can't be used. The message is safe to show the person uploading. */
+export class BrandAssetError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "BrandAssetError";
+        this.code = code;
+    }
+}
+/** Checks an uploaded logo by its own bytes (not its name or declared type). Throws a BrandAssetError. */
+export function checkLogo(bytes) {
+    if (bytes.length === 0)
+        throw new BrandAssetError("invalid_logo", "The logo file is empty.");
+    if (bytes.length > MAX_LOGO_BYTES) {
+        throw new BrandAssetError("logo_too_big", `The logo is ${Math.ceil(bytes.length / 1024)} KiB; the limit is ${MAX_LOGO_BYTES / 1024} KiB. A PNG about 256 pixels high is plenty.`);
+    }
+    const png = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+    let size = null;
+    let ext;
+    if (bytes.length > 24 && png.every((v, i) => bytes[i] === v)) {
+        ext = "png";
+        const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+        size = { width: dv.getUint32(16), height: dv.getUint32(20) };
+    }
+    else if (bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) {
+        ext = "jpg";
+        size = jpegSize(bytes);
+    }
+    else {
+        const head = new TextDecoder().decode(bytes.subarray(0, 512)).toLowerCase();
+        if (head.includes("<svg")) {
+            throw new BrandAssetError("svg_logo", "That's an SVG. Gmail and Outlook don't show SVG, so save the logo as a PNG first.");
+        }
+        throw new BrandAssetError("invalid_logo", "The logo must be a PNG or JPEG.");
+    }
+    if (!size || !size.width || !size.height) {
+        throw new BrandAssetError("invalid_logo", "The logo's size can't be read; save it again as a PNG.");
+    }
+    return { ext, contentType: LOGO_CONTENT_TYPES[ext], ...size };
+}
+function jpegSize(b) {
+    let i = 2;
+    while (i + 9 < b.length) {
+        if (b[i] !== 0xff)
+            return null;
+        const marker = b[i + 1];
+        const len = (b[i + 2] << 8) | b[i + 3];
+        const sof = marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc;
+        if (sof)
+            return { height: (b[i + 5] << 8) | b[i + 6], width: (b[i + 7] << 8) | b[i + 8] };
+        i += 2 + len;
+    }
+    return null;
+}
+/** The size a logo is shown at in brand.json: 48 pixels high, at most 240 wide. */
+export function shownSize(logo) {
+    return { width: Math.min(240, Math.max(16, Math.round((48 * logo.width) / logo.height))), height: 48 };
+}
+// ── Colour ───────────────────────────────────────────────────────────────────
+/** "#1F4E79" or "1f4e79" as "#1f4e79". Throws a BrandAssetError. */
+export function parseColour(text) {
+    const t = String(text ?? "").trim().replace(/^#?/, "#").toLowerCase();
+    if (!/^#[0-9a-f]{6}$/.test(t))
+        throw new BrandAssetError("invalid_colour", `"${text}" isn't a colour. Use six hex digits, for example #1f4e79.`);
+    return t;
+}
+const rgb = (colour) => [1, 3, 5].map((i) => parseInt(colour.slice(i, i + 2), 16));
+function luminance(colour) {
+    const [r, g, b] = rgb(colour).map((v) => {
+        const c = v / 255;
+        return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+    });
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+/** WCAG contrast ratio of white text on this colour; 4.5 or more reads well. */
+export function whiteContrast(colour) {
+    return 1.05 / (luminance(colour) + 0.05);
+}
+const hex2 = (n) => Math.round(n).toString(16).padStart(2, "0");
+function hsl(hue, s, l) {
+    const k = (n) => (n + hue / 30) % 12;
+    const a = s * Math.min(l, 1 - l);
+    const f = (n) => 255 * (l - a * Math.max(-1, Math.min(k(n) - 3, Math.min(9 - k(n), 1))));
+    return `#${hex2(f(0))}${hex2(f(8))}${hex2(f(4))}`;
+}
+/** A steady colour for a project id: always the same for that id, dark enough for white text. */
+export function colourForId(id) {
+    let h = 2166136261;
+    for (const c of String(id))
+        h = Math.imul(h ^ c.charCodeAt(0), 16777619) >>> 0;
+    const hue = h % 360;
+    // Yellows and greens are bright at the same lightness, so darken until white text reads.
+    for (let l = 0.38;; l -= 0.02) {
+        const colour = hsl(hue, 0.55, l);
+        if (whiteContrast(colour) >= 4.5 || l <= 0.1)
+            return colour;
+    }
+}
+// ── Placeholder logo ─────────────────────────────────────────────────────────
+// 5 × 7 letters and digits, top row first.
+const GLYPHS = {
+    A: "01110 10001 10001 11111 10001 10001 10001", B: "11110 10001 10001 11110 10001 10001 11110",
+    C: "01110 10001 10000 10000 10000 10001 01110", D: "11110 10001 10001 10001 10001 10001 11110",
+    E: "11111 10000 10000 11110 10000 10000 11111", F: "11111 10000 10000 11110 10000 10000 10000",
+    G: "01110 10001 10000 10111 10001 10001 01111", H: "10001 10001 10001 11111 10001 10001 10001",
+    I: "01110 00100 00100 00100 00100 00100 01110", J: "00111 00010 00010 00010 00010 10010 01100",
+    K: "10001 10010 10100 11000 10100 10010 10001", L: "10000 10000 10000 10000 10000 10000 11111",
+    M: "10001 11011 10101 10101 10001 10001 10001", N: "10001 10001 11001 10101 10011 10001 10001",
+    O: "01110 10001 10001 10001 10001 10001 01110", P: "11110 10001 10001 11110 10000 10000 10000",
+    Q: "01110 10001 10001 10001 10101 10010 01101", R: "11110 10001 10001 11110 10100 10010 10001",
+    S: "01111 10000 10000 01110 00001 00001 11110", T: "11111 00100 00100 00100 00100 00100 00100",
+    U: "10001 10001 10001 10001 10001 10001 01110", V: "10001 10001 10001 10001 10001 01010 00100",
+    W: "10001 10001 10001 10101 10101 10101 01010", X: "10001 10001 01010 00100 01010 10001 10001",
+    Y: "10001 10001 10001 01010 00100 00100 00100", Z: "11111 00001 00010 00100 01000 10000 11111",
+    0: "01110 10001 10011 10101 11001 10001 01110", 1: "00100 01100 00100 00100 00100 00100 01110",
+    2: "01110 10001 00001 00010 00100 01000 11111", 3: "11111 00010 00100 00010 00001 10001 01110",
+    4: "00010 00110 01010 10010 11111 00010 00010", 5: "11111 10000 11110 00001 00001 10001 01110",
+    6: "00110 01000 10000 11110 10001 10001 01110", 7: "11111 00001 00010 00100 01000 01000 01000",
+    8: "01110 10001 10001 01110 10001 10001 01110", 9: "01110 10001 10001 01111 00001 00010 01100",
+};
+/** Up to two letters for a name: "Galing Gear" is GG, "wb-probe" is WP, "imprint" is I. */
+export function initials(name) {
+    const words = String(name).toUpperCase().split(/[^A-Z0-9]+/).filter(Boolean);
+    return words.slice(0, 2).map((w) => w[0]).join("") || "?";
+}
+const SIZE = 96;
+const SCALE = 6;
+/** A 96 × 96 PNG of the name's initials on the colour, for a project with no logo yet. */
+export async function placeholderLogo(name, colour) {
+    const bg = rgb(parseColour(colour));
+    const fg = whiteContrast(colour) >= 4.5 ? [255, 255, 255] : [26, 26, 26];
+    const text = initials(name).split("").filter((c) => GLYPHS[c]);
+    // One filter byte (0) then RGB per row.
+    const stride = 1 + SIZE * 3;
+    const raw = new Uint8Array(SIZE * stride);
+    for (let y = 0; y < SIZE; y++)
+        for (let x = 0; x < SIZE; x++)
+            raw.set(bg, y * stride + 1 + x * 3);
+    const glyphW = 5 * SCALE;
+    const width = text.length * glyphW + Math.max(0, text.length - 1) * SCALE;
+    const x0 = Math.floor((SIZE - width) / 2);
+    const y0 = Math.floor((SIZE - 7 * SCALE) / 2);
+    text.forEach((c, k) => {
+        GLYPHS[c].split(" ").forEach((row, gy) => {
+            for (let gx = 0; gx < 5; gx++) {
+                if (row[gx] !== "1")
+                    continue;
+                for (let dy = 0; dy < SCALE; dy++) {
+                    for (let dx = 0; dx < SCALE; dx++) {
+                        const X = x0 + k * (glyphW + SCALE) + gx * SCALE + dx;
+                        const Y = y0 + gy * SCALE + dy;
+                        raw.set(fg, Y * stride + 1 + X * 3);
+                    }
+                }
+            }
+        });
+    });
+    const ihdr = new Uint8Array(13);
+    const dv = new DataView(ihdr.buffer);
+    dv.setUint32(0, SIZE);
+    dv.setUint32(4, SIZE);
+    ihdr[8] = 8; // bit depth
+    ihdr[9] = 2; // RGB
+    return concat([
+        new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+        chunk("IHDR", ihdr),
+        chunk("IDAT", await zlib(raw)),
+        chunk("IEND", new Uint8Array(0)),
+    ]);
+}
+/** zlib-wrapped deflate, as PNG's IDAT wants ("deflate" in CompressionStream is the zlib format). */
+async function zlib(data) {
+    const stream = new Blob([data]).stream().pipeThrough(new CompressionStream("deflate"));
+    return new Uint8Array(await new Response(stream).arrayBuffer());
+}
+const CRC_TABLE = (() => {
+    const t = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        t[n] = c >>> 0;
+    }
+    return t;
+})();
+function crc32(bytes) {
+    let c = 0xffffffff;
+    for (const b of bytes)
+        c = CRC_TABLE[(c ^ b) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+}
+function chunk(type, data) {
+    const out = new Uint8Array(12 + data.length);
+    const dv = new DataView(out.buffer);
+    dv.setUint32(0, data.length);
+    for (let i = 0; i < 4; i++)
+        out[4 + i] = type.charCodeAt(i);
+    out.set(data, 8);
+    dv.setUint32(8 + data.length, crc32(out.subarray(4, 8 + data.length)));
+    return out;
+}
+function concat(parts) {
+    const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+    let at = 0;
+    for (const p of parts) {
+        out.set(p, at);
+        at += p.length;
+    }
+    return out;
+}

package/dist/capabilities.gen.d.ts

@@ -1,4 +1,4 @@
-export declare const MANIFEST_VERSION: "71462ff7fe4c";
+export declare const MANIFEST_VERSION: "2216125e22d4";
 export declare const capabilities: {
     readonly ai: {
         readonly $schema: "./schema.json";
@@ -1642,6 +1642,70 @@ export declare const capabilities: {
             readonly note: "The app's own checkStrings run passes in its tests, and npx workbench-strings check passes in CI";
         }];
     };
+    readonly ui: {
+        readonly $schema: "./schema.json";
+        readonly format: 1;
+        readonly component: "ui";
+        readonly title: "One look for every page";
+        readonly summary: "workbench-ui gives every Workbench page the same dark look: the page shell, a top bar with the environment tag, cards that fold, jump pills, outcome pills, and one way to write times, money and durations. It returns HTML text in the app's own Worker, with no Gateway call and no cost.";
+        readonly status: "built";
+        readonly surfaces: {
+            readonly package: readonly ["shell", "topBar", "card", "jumpNav", "SECTIONS_SCRIPT", "pill", "chip", "when", "shortWhen", "timeLeft", "money", "duration", "escape", "STYLE", "CSS"];
+        };
+        readonly rules: readonly [{
+            readonly id: "ui.one-look";
+            readonly kind: "must";
+            readonly text: "Build every page a person opens with shell (or STYLE for a page that writes its own document), so each page has the same top bar, cards and pills.";
+            readonly enforced_by: "review";
+            readonly probe: "ui.page";
+        }, {
+            readonly id: "ui.environment-tag";
+            readonly kind: "must";
+            readonly text: "Pass the environment to topBar, so every page says whether it is staging or production.";
+            readonly enforced_by: "review";
+            readonly probe: "ui.page";
+        }, {
+            readonly id: "ui.escape";
+            readonly kind: "must";
+            readonly text: "Escape any text that goes into an HTML argument (a card's inner, a top bar's extra) with escape. Arguments described as plain text are escaped for you.";
+            readonly enforced_by: "review";
+            readonly probe: "ui.page";
+        }, {
+            readonly id: "ui.no-own-colours";
+            readonly kind: "must_not";
+            readonly text: "Give a page its own colours. A page's own rules go after the shared ones and use the colour tokens (--surface, --line, --pass and so on).";
+            readonly enforced_by: "review";
+            readonly probe: "ui.page";
+        }, {
+            readonly id: "ui.one-format";
+            readonly kind: "must";
+            readonly text: "Write the times, amounts and durations a page shows with when, shortWhen, timeLeft, money and duration, not hand-built strings.";
+            readonly enforced_by: "review";
+            readonly probe: "ui.formats";
+        }];
+        readonly examples: readonly [{
+            readonly id: "ui.example.page";
+            readonly title: "A page with one folding card";
+            readonly lang: "ts";
+            readonly code: "import { workbenchEnv } from '@mccaskie-labs/workbench-config'\nimport { card, pill, shell, shortWhen, topBar } from '@mccaskie-labs/workbench-ui'\n\nconst html = shell({\n  title: 'Orders',\n  site: 'my-app',\n  top: topBar({ name: 'my-app', href: '/', env: workbenchEnv(env), links: [['History', '/history']] }),\n  body: card('Last order', `<div class=\"body\">${pill('pass', 'Sent')} ${shortWhen(order.sent_at)}</div>`, {\n    id: 'last-order',\n    about: 'The most recent order and when it went out.',\n    collapsible: true,\n  }),\n})";
+            readonly probe: "ui.page";
+        }];
+        readonly probes: readonly [{
+            readonly id: "ui.page";
+            readonly half: "runtime";
+            readonly expect: "pass";
+            readonly smoke: true;
+            readonly cost_hint_usd: 0;
+            readonly note: "In the Worker itself: builds one page with shell, topBar, jumpNav, a folding card and a pill, and checks the shared stylesheet is there with its colour tokens, the environment tag is shown, the pill carries its tone, the jump pill points at the card, and markup in a plain-text title and in text passed through escape both come out escaped";
+        }, {
+            readonly id: "ui.formats";
+            readonly half: "runtime";
+            readonly expect: "pass";
+            readonly smoke: true;
+            readonly cost_hint_usd: 0;
+            readonly note: "In the Worker itself: compares money (US$0.0042, US$12.50, and an en dash for nothing), duration (640 ms, 2.35 s, 3 min 5 s) and timeLeft against a fixed now (42 minutes left) with the expected text, and checks when and shortWhen write one fixed moment as its Manila day and hour with UTC beside it";
+        }];
+    };
 };
 export type Alias = (typeof capabilities)["ai"]["allowed"]["aliases"][number]["alias"];
 export type GatewayScope = (typeof capabilities)["gateway"]["allowed"]["scopes"][number];

package/dist/capabilities.gen.js

@@ -1,6 +1,6 @@
 // Generated by `npm run capabilities:build` from capabilities/*.json. Do not edit.
 // check:capabilities fails in Checks when this file is stale.
-export const MANIFEST_VERSION = "71462ff7fe4c";
+export const MANIFEST_VERSION = "2216125e22d4";
 export const capabilities = {
     "ai": {
         "$schema": "./schema.json",
@@ -2204,5 +2204,96 @@ export const capabilities = {
                 "note": "The app's own checkStrings run passes in its tests, and npx workbench-strings check passes in CI"
             }
         ]
+    },
+    "ui": {
+        "$schema": "./schema.json",
+        "format": 1,
+        "component": "ui",
+        "title": "One look for every page",
+        "summary": "workbench-ui gives every Workbench page the same dark look: the page shell, a top bar with the environment tag, cards that fold, jump pills, outcome pills, and one way to write times, money and durations. It returns HTML text in the app's own Worker, with no Gateway call and no cost.",
+        "status": "built",
+        "surfaces": {
+            "package": [
+                "shell",
+                "topBar",
+                "card",
+                "jumpNav",
+                "SECTIONS_SCRIPT",
+                "pill",
+                "chip",
+                "when",
+                "shortWhen",
+                "timeLeft",
+                "money",
+                "duration",
+                "escape",
+                "STYLE",
+                "CSS"
+            ]
+        },
+        "rules": [
+            {
+                "id": "ui.one-look",
+                "kind": "must",
+                "text": "Build every page a person opens with shell (or STYLE for a page that writes its own document), so each page has the same top bar, cards and pills.",
+                "enforced_by": "review",
+                "probe": "ui.page"
+            },
+            {
+                "id": "ui.environment-tag",
+                "kind": "must",
+                "text": "Pass the environment to topBar, so every page says whether it is staging or production.",
+                "enforced_by": "review",
+                "probe": "ui.page"
+            },
+            {
+                "id": "ui.escape",
+                "kind": "must",
+                "text": "Escape any text that goes into an HTML argument (a card's inner, a top bar's extra) with escape. Arguments described as plain text are escaped for you.",
+                "enforced_by": "review",
+                "probe": "ui.page"
+            },
+            {
+                "id": "ui.no-own-colours",
+                "kind": "must_not",
+                "text": "Give a page its own colours. A page's own rules go after the shared ones and use the colour tokens (--surface, --line, --pass and so on).",
+                "enforced_by": "review",
+                "probe": "ui.page"
+            },
+            {
+                "id": "ui.one-format",
+                "kind": "must",
+                "text": "Write the times, amounts and durations a page shows with when, shortWhen, timeLeft, money and duration, not hand-built strings.",
+                "enforced_by": "review",
+                "probe": "ui.formats"
+            }
+        ],
+        "examples": [
+            {
+                "id": "ui.example.page",
+                "title": "A page with one folding card",
+                "lang": "ts",
+                "code": "import { workbenchEnv } from '@mccaskie-labs/workbench-config'\nimport { card, pill, shell, shortWhen, topBar } from '@mccaskie-labs/workbench-ui'\n\nconst html = shell({\n  title: 'Orders',\n  site: 'my-app',\n  top: topBar({ name: 'my-app', href: '/', env: workbenchEnv(env), links: [['History', '/history']] }),\n  body: card('Last order', `<div class=\"body\">${pill('pass', 'Sent')} ${shortWhen(order.sent_at)}</div>`, {\n    id: 'last-order',\n    about: 'The most recent order and when it went out.',\n    collapsible: true,\n  }),\n})",
+                "probe": "ui.page"
+            }
+        ],
+        "probes": [
+            {
+                "id": "ui.page",
+                "half": "runtime",
+                "expect": "pass",
+                "smoke": true,
+                "cost_hint_usd": 0,
+                "note": "In the Worker itself: builds one page with shell, topBar, jumpNav, a folding card and a pill, and checks the shared stylesheet is there with its colour tokens, the environment tag is shown, the pill carries its tone, the jump pill points at the card, and markup in a plain-text title and in text passed through escape both come out escaped"
+            },
+            {
+                "id": "ui.formats",
+                "half": "runtime",
+                "expect": "pass",
+                "smoke": true,
+                "cost_hint_usd": 0,
+                "note": "In the Worker itself: compares money (US$0.0042, US$12.50, and an en dash for nothing), duration (640 ms, 2.35 s, 3 min 5 s) and timeLeft against a fixed now (42 minutes left) with the expected text, and checks when and shortWhen write one fixed moment as its Manila day and hour with UTC beside it"
+            }
+        ]
     }
 };

package/dist/capability-schema.d.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-export declare const COMPONENTS: readonly ["gateway", "ai", "images", "image-search", "config", "email", "email-inbound", "email-sending", "database", "workers", "domains", "dns", "analytics", "country", "pdf", "access", "r2", "kv", "github", "strings"];
+export declare const COMPONENTS: readonly ["gateway", "ai", "images", "image-search", "config", "email", "email-inbound", "email-sending", "database", "workers", "domains", "dns", "analytics", "country", "pdf", "access", "r2", "kv", "github", "strings", "ui"];
 export type Component = (typeof COMPONENTS)[number];
 export declare const allowedSchemas: {
     gateway: z.ZodObject<{
@@ -111,6 +111,7 @@ export declare const capabilitySchema: z.ZodObject<{
         pdf: "pdf";
         r2: "r2";
         strings: "strings";
+        ui: "ui";
         workers: "workers";
     }>;
     title: z.ZodString;

package/dist/capability-schema.js

@@ -23,6 +23,7 @@ export const COMPONENTS = [
     "kv",
     "github",
     "strings",
+    "ui",
 ];
 const id = z.string().regex(/^[a-z0-9][a-z0-9.-]*$/, "lower case, digits, dots and hyphens");
 const code = z.string().regex(/^[a-z][a-z0-9_]*$/, "a snake_case error code");

package/dist/index.d.ts

@@ -6,4 +6,5 @@ export { capabilitySchema, checkManifests, allowedSchemas, COMPONENTS, type Capa
 export { capabilities, MANIFEST_VERSION, type Alias, type GatewayScope } from "./capabilities.gen.ts";
 export { compareDevVars, parseDevVarNames } from "./dev-vars.ts";
 export { brandSchema, defineBrand, BRAND_FILE, resolveBrand, BRAND_DEFAULTS, type Brand, type ResolvedBrand } from "./brand.ts";
+export { BrandAssetError, checkLogo, colourForId, initials, LOGO_CONTENT_TYPES, LOGO_PATHS, MAX_LOGO_BYTES, parseColour, placeholderLogo, shownSize, whiteContrast, type BrandAssetErrorCode, type CheckedLogo, type LogoExt, } from "./brand-assets.ts";
 export { VENDOR_SETTINGS, VENDOR_SETTINGS_FILE, SEND_EMAIL_HOOK, SEND_EMAIL_HOOK_PATH, SEND_EMAIL_HOOK_SECRET, vendorSettingsFileSchema, resolveVendorSettings, type VendorSetting, type VendorSettingEnv, type VendorSettingsFile, type ResolvedVendorSetting, } from "./vendor-settings.ts";

package/dist/index.js

@@ -6,4 +6,5 @@ export { capabilitySchema, checkManifests, allowedSchemas, COMPONENTS, } from ".
 export { capabilities, MANIFEST_VERSION } from "./capabilities.gen.js";
 export { compareDevVars, parseDevVarNames } from "./dev-vars.js";
 export { brandSchema, defineBrand, BRAND_FILE, resolveBrand, BRAND_DEFAULTS } from "./brand.js";
+export { BrandAssetError, checkLogo, colourForId, initials, LOGO_CONTENT_TYPES, LOGO_PATHS, MAX_LOGO_BYTES, parseColour, placeholderLogo, shownSize, whiteContrast, } from "./brand-assets.js";
 export { VENDOR_SETTINGS, VENDOR_SETTINGS_FILE, SEND_EMAIL_HOOK, SEND_EMAIL_HOOK_PATH, SEND_EMAIL_HOOK_SECRET, vendorSettingsFileSchema, resolveVendorSettings, } from "./vendor-settings.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mccaskie-labs/workbench-config",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "description": "Workbench app configuration: WORKBENCH_ENV, typed variables that fail by name, secrets that are never printed, and the capabilities manifest.",
   "license": "UNLICENSED",
   "type": "module",