@tilewise/workbench-client 0.0.0-stage → 0.1.0

package/dist/define/defineBlock.d.ts

@@ -0,0 +1,12 @@
+import type { Control, Declared } from '../controls/types.js';
+import { type Part } from './part.js';
+/**
+ * Declares a block's controls, beside its component. They show in a section
+ * of their own, headed by `label`, on any screen while the block is drawn there.
+ */
+export declare function defineBlock<const C extends readonly Control[]>(declaration: {
+    /** The block's component name. */
+    block: string;
+    label: string;
+    controls: C & NoInfer<Declared<C>>;
+}): Part<C>;

package/dist/define/defineBlock.js

@@ -0,0 +1,10 @@
+import { checkDefaults } from './checkDefaults.js';
+import { makePart } from './part.js';
+/**
+ * Declares a block's controls, beside its component. They show in a section
+ * of their own, headed by `label`, on any screen while the block is drawn there.
+ */
+export function defineBlock(declaration) {
+    checkDefaults(declaration.controls, `block "${declaration.block}"`);
+    return makePart({ level: 'block', block: declaration.block }, declaration.controls, declaration.label);
+}

package/dist/define/defineScreen.d.ts

@@ -0,0 +1,11 @@
+import type { Control, Declared } from '../controls/types.js';
+import { type Part } from './part.js';
+/**
+ * Declares a screen's controls, beside its component. They show in the form
+ * on that screen, in the order given.
+ */
+export declare function defineScreen<const C extends readonly Control[]>(declaration: {
+    /** A screen id from the app's screens. */
+    screen: string;
+    controls: C & NoInfer<Declared<C>>;
+}): Part<C>;

package/dist/define/defineScreen.js

@@ -0,0 +1,10 @@
+import { checkDefaults } from './checkDefaults.js';
+import { makePart } from './part.js';
+/**
+ * Declares a screen's controls, beside its component. They show in the form
+ * on that screen, in the order given.
+ */
+export function defineScreen(declaration) {
+    checkDefaults(declaration.controls, `screen "${declaration.screen}"`);
+    return makePart({ level: 'screen', screen: declaration.screen }, declaration.controls);
+}

package/dist/define/part.d.ts

@@ -0,0 +1,23 @@
+import type { Control, Handle, Place } from '../controls/types.js';
+/** Marks a part, so `defineApp` finds it among a module's exports. */
+export declare const PART: unique symbol;
+export interface PartInfo {
+    place: Place;
+    /** A block's heading in the form. */
+    label?: string;
+    controls: readonly Control[];
+    handles: readonly Handle[];
+}
+/**
+ * One `.workbench.ts` file's controls: the app's, a screen's or a block's.
+ * It holds one handle per control, under its id: `home.homepage`.
+ */
+export type Part<C extends readonly Control[] = readonly Control[]> = {
+    readonly [K in C[number] as K['id']]: Handle<K>;
+} & {
+    readonly [PART]: PartInfo;
+};
+export declare function makePart<C extends readonly Control[]>(place: Place, controls: C, label?: string): Part<C>;
+export declare function isPart(value: unknown): value is Part;
+/** Where a part sits, in words, for the messages the start-up checks throw. */
+export declare function nameOf(info: PartInfo): string;

package/dist/define/part.js

@@ -0,0 +1,22 @@
+/** Marks a part, so `defineApp` finds it among a module's exports. */
+export const PART = Symbol.for('@tilewise/workbench-client/part');
+export function makePart(place, controls, label) {
+    const handles = controls.map((control) => ({ id: control.id, control, place }));
+    const info = { place, controls, handles, ...(label !== undefined && { label }) };
+    const byId = Object.fromEntries(handles.map((handle) => [handle.id, handle]));
+    return Object.assign(byId, { [PART]: info });
+}
+export function isPart(value) {
+    return typeof value === 'object' && value !== null && PART in value;
+}
+/** Where a part sits, in words, for the messages the start-up checks throw. */
+export function nameOf(info) {
+    switch (info.place.level) {
+        case 'global':
+            return 'the app';
+        case 'screen':
+            return `screen "${info.place.screen}"`;
+        case 'block':
+            return `block "${info.place.block}"`;
+    }
+}

package/dist/define/registeredApp.d.ts

@@ -0,0 +1,12 @@
+import type { At, Manifest } from '../protocol/types.js';
+/** The app `defineApp` declared, as the bridge needs it. */
+export interface RegisteredApp {
+    manifest: Manifest;
+    /** The app's navigation, going by state id: false for a state it doesn't have. */
+    useNavigation: () => {
+        at: At;
+        go: (state: string) => boolean;
+    };
+}
+export declare function registerApp(app: RegisteredApp): void;
+export declare const registeredApp: () => RegisteredApp | null;

package/dist/define/registeredApp.js

@@ -0,0 +1,5 @@
+let registered = null;
+export function registerApp(app) {
+    registered = app;
+}
+export const registeredApp = () => registered;

package/dist/draw/boolean.d.ts

@@ -0,0 +1,6 @@
+import { type Case } from './choose.js';
+/** What to draw for a boolean's value: `on` and `off`, both required. */
+export declare function boolean<R>(value: boolean, cases: {
+    on: Case<true, R>;
+    off: Case<false, R>;
+}): R;

package/dist/draw/boolean.js

@@ -0,0 +1,5 @@
+import { choose } from './choose.js';
+/** What to draw for a boolean's value: `on` and `off`, both required. */
+export function boolean(value, cases) {
+    return value ? choose(cases.on, true) : choose(cases.off, false);
+}

package/dist/draw/choose.d.ts

@@ -0,0 +1,4 @@
+/** A case: something to draw, or a function that gets the value and returns it. */
+export type Case<V, R> = R | ((value: V) => R);
+/** The case's result for a value. */
+export declare function choose<V, R>(found: Case<V, R> | undefined, value: V): R;

package/dist/draw/choose.js

@@ -0,0 +1,4 @@
+/** The case's result for a value. */
+export function choose(found, value) {
+    return typeof found === 'function' ? found(value) : found;
+}

package/dist/draw/color.d.ts

@@ -0,0 +1,2 @@
+/** A color's token as a CSS value, for a `style`: `color('lime')` is `'var(--lime)'`. */
+export declare function color<T extends string>(token: T): `var(--${T})`;

package/dist/draw/color.js

@@ -0,0 +1,4 @@
+/** A color's token as a CSS value, for a `style`: `color('lime')` is `'var(--lime)'`. */
+export function color(token) {
+    return `var(--${token})`;
+}

package/dist/draw/number.d.ts

@@ -0,0 +1,5 @@
+import { type Case } from './choose.js';
+/** What to draw for a number: any exact numbers, and `other`, required, for the rest. */
+export declare function number<R>(value: number, cases: Readonly<Record<number, Case<number, R>>> & {
+    other: Case<number, R>;
+}): R;

package/dist/draw/number.js

@@ -0,0 +1,5 @@
+import { choose } from './choose.js';
+/** What to draw for a number: any exact numbers, and `other`, required, for the rest. */
+export function number(value, cases) {
+    return choose(Object.hasOwn(cases, String(value)) ? cases[value] : cases.other, value);
+}

package/dist/draw/text.d.ts

@@ -0,0 +1,5 @@
+import { type Case } from './choose.js';
+/** What to draw for a line of text: any exact lines, and `other`, required, for the rest. */
+export declare function text<R>(value: string, cases: Readonly<Record<string, Case<string, R>>> & {
+    other: Case<string, R>;
+}): R;

package/dist/draw/text.js

@@ -0,0 +1,5 @@
+import { choose } from './choose.js';
+/** What to draw for a line of text: any exact lines, and `other`, required, for the rest. */
+export function text(value, cases) {
+    return choose(value !== 'other' && Object.hasOwn(cases, value) ? cases[value] : cases.other, value);
+}

package/dist/draw/variant.d.ts

@@ -0,0 +1,17 @@
+import { type Case } from './choose.js';
+type EveryCase<V extends string, R> = {
+    [K in V]: Case<K, R>;
+};
+/** Some options, and `other` for the rest: its function gets them without the ones listed. */
+type SomeCases<V extends string, L extends string, R> = {
+    [K in L]: K extends 'other' ? Case<Exclude<V, L>, R> : Case<K, R>;
+} & {
+    other: unknown;
+};
+/**
+ * What to draw for a variant's value. A call without `other` lists every
+ * option, so a new option is a type error until every such call handles it.
+ */
+export declare function variant<V extends string, R>(value: V, cases: EveryCase<V, R>): R;
+export declare function variant<V extends string, L extends V | 'other', R>(value: V, cases: SomeCases<V, L, R>): R;
+export {};

package/dist/draw/variant.js

@@ -0,0 +1,4 @@
+import { choose } from './choose.js';
+export function variant(value, cases) {
+    return choose(Object.hasOwn(cases, value) ? cases[value] : cases['other'], value);
+}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+export { ScreenScope } from './blocks/ScreenScope.js';
+export { Bridge } from './bridge/Bridge.js';
+export { resetControl } from './controls/resetControl.js';
+export { setControl } from './controls/setControl.js';
+export type { BooleanControl, ColorControl, ColorOption, Control, Handle, Level, NumberControl, Option, Place, TextControl, Value, ValueOf, VariantControl, } from './controls/types.js';
+export { useControl } from './controls/useControl.js';
+export { defineApp } from './define/defineApp.js';
+export { defineBlock } from './define/defineBlock.js';
+export { defineScreen } from './define/defineScreen.js';
+export type { Part } from './define/part.js';
+export { boolean } from './draw/boolean.js';
+export type { Case } from './draw/choose.js';
+export { color } from './draw/color.js';
+export { number } from './draw/number.js';
+export { text } from './draw/text.js';
+export { variant } from './draw/variant.js';
+export { PROTOCOL } from './protocol/protocol.js';
+export type { AppMessage, AppSays, At, DeviceMessage, Manifest, ManifestBlock, ManifestControl, Navigation, Screen, State, StateKind, Tone, ViewerMessage, ViewerSays, } from './protocol/types.js';

package/dist/index.js

@@ -0,0 +1,14 @@
+export { ScreenScope } from './blocks/ScreenScope.js';
+export { Bridge } from './bridge/Bridge.js';
+export { resetControl } from './controls/resetControl.js';
+export { setControl } from './controls/setControl.js';
+export { useControl } from './controls/useControl.js';
+export { defineApp } from './define/defineApp.js';
+export { defineBlock } from './define/defineBlock.js';
+export { defineScreen } from './define/defineScreen.js';
+export { boolean } from './draw/boolean.js';
+export { color } from './draw/color.js';
+export { number } from './draw/number.js';
+export { text } from './draw/text.js';
+export { variant } from './draw/variant.js';
+export { PROTOCOL } from './protocol/protocol.js';

package/dist/protocol/protocol.d.ts

@@ -0,0 +1,8 @@
+/** The protocol this package speaks. */
+export declare const PROTOCOL = 3;
+/**
+ * Every message carries `source`, for every app, as builds from before the
+ * package send them. Each side ignores any message without the other's tag.
+ */
+export declare const FROM_APP = "aitems";
+export declare const FROM_VIEWER = "aitems-workbench";

package/dist/protocol/protocol.js

@@ -0,0 +1,8 @@
+/** The protocol this package speaks. */
+export const PROTOCOL = 3;
+/**
+ * Every message carries `source`, for every app, as builds from before the
+ * package send them. Each side ignores any message without the other's tag.
+ */
+export const FROM_APP = 'aitems';
+export const FROM_VIEWER = 'aitems-workbench';

package/dist/protocol/types.d.ts

@@ -0,0 +1,133 @@
+import type { Control, Value } from '../controls/types.js';
+/**
+ * Protocol 3: what the app and the viewer say to each other through
+ * `postMessage`, between the frame and the page around it. Any change to a
+ * message or to the manifest bumps the protocol, so the viewer can still read
+ * older builds.
+ */
+export type StateKind = 'state' | 'sheet' | 'overlay';
+/** One place on a screen. The app knows how to get there; the viewer only names it. */
+export interface State {
+    /** Unique across the app, and never renamed. */
+    id: string;
+    label: string;
+    kind?: StateKind;
+    note?: string;
+    /** Only while the screen's `statesBy` control has one of these values. */
+    when?: readonly string[];
+}
+export interface Screen<S extends State = State> {
+    id: string;
+    label: string;
+    /** Two letters, for narrow lists. */
+    short: string;
+    /** The screen it sits under in the route tree. */
+    parent?: string;
+    /** The tab-bar tab it is the root of. */
+    tab?: string;
+    /** A heading that holds screens, with no states of its own. */
+    group?: boolean;
+    /** A page pushed from several screens. */
+    page?: boolean;
+    /** Where it opens from, in words. */
+    where?: string;
+    /** A control id: which states it has depends on that value. */
+    statesBy?: string;
+    /** The source files that draw it; a folder ends in `/`. */
+    files?: readonly string[];
+    states: readonly S[];
+}
+/** A control as declared, with where it sits. */
+export type ManifestControl = Control & ({
+    level: 'global';
+} | {
+    level: 'screen';
+    screen: string;
+} | {
+    level: 'block';
+    block: string;
+});
+export interface ManifestBlock {
+    /** The component's name. */
+    id: string;
+    /** Its section's heading in the form. */
+    label: string;
+    /** Its controls' ids, in order. */
+    controls: string[];
+}
+/** Everything the app has, sent once with `hello`. A state goes without its jump. */
+export interface Manifest {
+    /** Whose build this is, such as `aitems`. */
+    app: string;
+    screens: Screen[];
+    controls: ManifestControl[];
+    blocks: ManifestBlock[];
+}
+export type Tone = 'light' | 'dark';
+/** What the app says. */
+export type AppSays = {
+    type: 'hello';
+    protocol: 3;
+    manifest: Manifest;
+} | {
+    type: 'at';
+    screen: string;
+    state: string | null;
+} | {
+    type: 'blocks';
+    screen: string;
+    blocks: string[];
+} | {
+    type: 'values';
+    values: Record<string, Value>;
+} | {
+    type: 'tone';
+    top: Tone;
+} | {
+    type: 'height';
+    height: number;
+};
+/** What the app says, as sent: tagged `source: 'aitems'`. */
+export type AppMessage = {
+    source: 'aitems';
+} & AppSays;
+export interface DeviceMessage {
+    type: 'device';
+    /** What the status bar and the home indicator take, in px. */
+    insets: {
+        top: number;
+        bottom: number;
+    };
+    platform: 'ios' | 'android' | null;
+    /** Full page: no device, and the frame as tall as the open screen. */
+    whole: boolean;
+}
+/** What the viewer says. */
+export type ViewerSays = {
+    type: 'hello';
+} | DeviceMessage | {
+    type: 'go';
+    state: string;
+} | {
+    type: 'set';
+    id: string;
+    value: Value;
+} | {
+    type: 'reset';
+    id?: string;
+};
+/** What the viewer says, as sent: tagged `source: 'aitems-workbench'`. */
+export type ViewerMessage = {
+    source: 'aitems-workbench';
+} & ViewerSays;
+/** Where the app is now. */
+export interface At {
+    screen: string;
+    state: string | null;
+}
+/** How the package moves the app, and learns where it is. */
+export interface Navigation<S extends State = State> {
+    /** Make the jump the state describes. */
+    go: (state: S) => void;
+    at: At;
+}

package/dist/protocol/types.js

@@ -0,0 +1 @@
+export {};

package/dist/vite/builds.d.ts

@@ -0,0 +1,29 @@
+import type { Git } from './git.js';
+export interface Build {
+    state: 'none' | 'queued' | 'building' | 'built' | 'failed';
+    /** What it is doing now, while building. */
+    step?: string;
+    /** 1 for a commit whose app talks to the viewer; 0 for one from before. Its hello says which protocol. */
+    protocol?: number;
+    /** The end of the log, when it failed. */
+    error?: string;
+}
+/** A tree's lockfile and the package manager it belongs to: pnpm, or npm for a commit from before a switch. */
+export declare function lockOf(dir: string): Promise<{
+    manager: string;
+    text: string | null;
+}>;
+/**
+ * Builds any commit of the app, one at a time, in a git worktree under
+ * `.builds/work/`, into `.builds/<sha>/`, served under `/__workbench/b/<sha>/`.
+ * The checkout and its uncommitted changes are never touched.
+ */
+export declare function createBuilds(options: {
+    root: () => string;
+    git: Git;
+}): {
+    buildOf: (sha: string) => Promise<Build>;
+    requestBuild: (sha: string, retry?: boolean) => Promise<Build>;
+    settled: () => Promise<void>;
+    folder: () => string;
+};

package/dist/vite/builds.js

@@ -0,0 +1,196 @@
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { appendFile, lstat, mkdir, readdir, readFile, rename, rm, rmdir, symlink, unlink, writeFile, } from 'node:fs/promises';
+import { join } from 'node:path';
+import { buildEnvironment } from './environment.js';
+/** A tree's lockfile and the package manager it belongs to: pnpm, or npm for a commit from before a switch. */
+export async function lockOf(dir) {
+    const pnpm = await readFile(join(dir, 'pnpm-lock.yaml'), 'utf8').catch(() => null);
+    if (pnpm !== null) {
+        return { manager: 'pnpm', text: pnpm };
+    }
+    return {
+        manager: 'npm',
+        text: await readFile(join(dir, 'package-lock.json'), 'utf8').catch(() => null),
+    };
+}
+/**
+ * Builds any commit of the app, one at a time, in a git worktree under
+ * `.builds/work/`, into `.builds/<sha>/`, served under `/__workbench/b/<sha>/`.
+ * The checkout and its uncommitted changes are never touched.
+ */
+export function createBuilds(options) {
+    const states = new Map();
+    const queue = [];
+    let busy = false;
+    const folder = () => join(options.root(), '.builds');
+    async function buildOf(sha) {
+        const live = states.get(sha);
+        if (live) {
+            return live;
+        }
+        try {
+            const meta = JSON.parse(await readFile(join(folder(), sha, 'meta.json'), 'utf8'));
+            const build = meta.ok
+                ? { state: 'built', protocol: meta.protocol ?? 0 }
+                : { state: 'failed', ...(meta.error !== undefined && { error: meta.error }) };
+            states.set(sha, build);
+            return build;
+        }
+        catch {
+            return { state: 'none' };
+        }
+    }
+    async function requestBuild(sha, retry = false) {
+        const build = await buildOf(sha);
+        if (build.state === 'failed' && retry) {
+            states.delete(sha);
+            await rm(join(folder(), sha), { recursive: true, force: true });
+        }
+        else if (build.state !== 'none') {
+            return build;
+        }
+        const queued = { state: 'queued' };
+        states.set(sha, queued);
+        queue.push(sha);
+        void drain();
+        return queued;
+    }
+    /** Waits for the queue to empty, for the tests. */
+    async function settled() {
+        while (busy || queue.length > 0) {
+            await new Promise((resolve) => setTimeout(resolve, 20));
+        }
+    }
+    async function drain() {
+        if (busy) {
+            return;
+        }
+        busy = true;
+        try {
+            for (let sha = queue.shift(); sha; sha = queue.shift()) {
+                await build(sha);
+            }
+        }
+        finally {
+            busy = false;
+        }
+    }
+    /** Runs a command into the build's log, failing on a non-zero exit. */
+    const step = (sha, log, command, args, cwd, name) => {
+        return new Promise((resolve, reject) => {
+            // pnpm and npm are .cmd files on Windows, which only a shell starts; the arguments are ours.
+            const shell = process.platform === 'win32' && (command === 'pnpm' || command === 'npm');
+            const child = spawn(command, args, { cwd, shell, env: buildEnvironment() });
+            const write = (chunk) => {
+                void appendFile(log, chunk);
+            };
+            child.stdout.on('data', write);
+            child.stderr.on('data', write);
+            child.on('error', reject);
+            child.on('close', (code) => {
+                if (code === 0) {
+                    resolve();
+                }
+                else {
+                    reject(new Error(`${name} exited with ${code}`));
+                }
+            });
+            states.set(sha, { state: 'building', step: name });
+        });
+    };
+    async function build(sha) {
+        const root = options.root();
+        const work = join(folder(), 'work', sha);
+        const out = join(folder(), sha);
+        const log = join(folder(), `${sha}.log`);
+        await mkdir(join(folder(), 'work'), { recursive: true });
+        await writeFile(log, `Building ${sha}\n`);
+        states.set(sha, { state: 'building', step: 'checking out' });
+        try {
+            await dropWork(work);
+            await options.git('worktree', 'prune');
+            await options.git('worktree', 'add', '--detach', work, sha);
+            await addBasePath(work);
+            // The same lockfile as the checkout: borrow its node_modules. Otherwise the
+            // commit installs its own, with the package manager its lockfile belongs to.
+            const ours = await lockOf(root);
+            const theirs = await lockOf(work);
+            if (theirs.text !== null &&
+                theirs.text === ours.text &&
+                existsSync(join(root, 'node_modules'))) {
+                await symlink(join(root, 'node_modules'), join(work, 'node_modules'), 'junction');
+            }
+            else if (theirs.manager === 'pnpm') {
+                await step(sha, log, 'pnpm', ['install', '--frozen-lockfile'], work, 'pnpm install');
+            }
+            else {
+                await step(sha, log, 'npm', ['ci', '--no-audit', '--no-fund', '--loglevel=error'], work, 'npm ci');
+            }
+            const temporary = `${out}.tmp`;
+            await rm(temporary, { recursive: true, force: true });
+            const vite = join(work, 'node_modules', 'vite', 'bin', 'vite.js');
+            const args = [
+                vite,
+                'build',
+                '--base',
+                `/__workbench/b/${sha}/`,
+                '--outDir',
+                temporary,
+                '--emptyOutDir',
+            ];
+            await step(sha, log, process.execPath, args, work, 'vite build');
+            const protocol = (await bundleText(temporary)).includes('aitems-workbench') ? 1 : 0;
+            await writeFile(join(temporary, 'meta.json'), JSON.stringify({ sha, ok: true, protocol, builtAt: new Date().toISOString() }));
+            await rm(out, { recursive: true, force: true });
+            await rename(temporary, out);
+            states.set(sha, { state: 'built', protocol });
+        }
+        catch (failure) {
+            const tail = (await readFile(log, 'utf8').catch(() => '')).split('\n').slice(-40).join('\n');
+            const error = `${failure.message}\n${tail}`.trim();
+            await mkdir(out, { recursive: true });
+            await writeFile(join(out, 'meta.json'), JSON.stringify({ sha, ok: false, error, builtAt: new Date().toISOString() }));
+            states.set(sha, { state: 'failed', error });
+        }
+        finally {
+            await dropWork(work);
+        }
+    }
+    /**
+     * Removes a build's worktree. Its node_modules may be a link to the
+     * checkout's: that link goes first, on its own, because removing the
+     * worktree with it in place follows it and empties the checkout's packages.
+     */
+    async function dropWork(work) {
+        const modules = join(work, 'node_modules');
+        if ((await lstat(modules).catch(() => null))?.isSymbolicLink()) {
+            await unlink(modules).catch(() => rmdir(modules));
+        }
+        await options
+            .git('worktree', 'remove', '--force', work)
+            .catch(() => rm(work, { recursive: true, force: true }));
+    }
+    return { buildOf, requestBuild, settled, folder };
+}
+/**
+ * A router made before the app was served under a base path matches nothing
+ * there; such a commit's TanStack router is given `import.meta.env.BASE_URL`.
+ */
+async function addBasePath(work) {
+    const main = join(work, 'src', 'main.tsx');
+    if (!existsSync(main)) {
+        return;
+    }
+    const source = await readFile(main, 'utf8');
+    if (source.includes('createRouter({ routeTree })')) {
+        await writeFile(main, source.replace('createRouter({ routeTree })', 'createRouter({ routeTree, basepath: import.meta.env.BASE_URL })'));
+    }
+}
+async function bundleText(dir) {
+    const assets = join(dir, 'assets');
+    const files = existsSync(assets)
+        ? (await readdir(assets)).filter((file) => file.endsWith('.js'))
+        : [];
+    return (await Promise.all(files.map((file) => readFile(join(assets, file), 'utf8')))).join('\n');
+}

package/dist/vite/checkout.d.ts

@@ -0,0 +1,11 @@
+import type { Git } from './git.js';
+interface Answer {
+    status: number;
+    body: Record<string, unknown>;
+}
+/**
+ * Checks a branch out, refused while anything is uncommitted. When the
+ * lockfile changes, installs and restarts the dev server.
+ */
+export declare function checkout(git: Git, root: string, branch: string, restart: () => void): Promise<Answer>;
+export {};