@mccaskie-labs/workbench-config 0.1.21 → 0.1.22

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @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

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/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/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.21",
+  "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",