@superpanel-sdk/runtime 0.2.3 → 0.7.0

package/dist/core/page/sandbox.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Runs one company script (a page script, or an action's `run`) in a fresh QuickJS context, with
+ * async host calls (15 §10.9).
+ *
+ * The script calls `__host(fn, args)` and gets a promise. Calls made while one slice of script runs
+ * are queued; when the slice yields (every pending job done, the script waiting on a host call),
+ * the queued calls go to `dispatch` together — this is where `Promise.all` and N+1 reads get merged
+ * (15 §10.3). Their results resolve the promises and the next slice runs.
+ *
+ * Limits: every slice has its own deadline (`sliceMs`; time spent waiting on `dispatch` is not
+ * counted against it, nor loading the code before its function is called), the whole run has `totalMs`
+ * of wall clock, loading included, plus a memory limit and a cap on host calls.
+ */
+export type SandboxLimits = {
+    /** CPU budget of one slice: the first run, and each resume after a host call. */
+    sliceMs: number;
+    /** Wall clock of the whole run, host calls included. */
+    totalMs: number;
+    memoryBytes: number;
+    maxStackBytes: number;
+    /** Host calls over the whole run. */
+    maxHostCalls: number;
+};
+export declare const DEFAULT_SANDBOX_LIMITS: SandboxLimits;
+/** `console` in the sandbox: its methods, each the company log level of the same name (`log` is `info`). */
+export declare const CONSOLE_METHODS: readonly ['log', 'info', 'warn', 'error', 'debug'];
+export type ConsoleMethod = (typeof CONSOLE_METHODS)[number];
+export type ConsoleLevel = 'debug' | 'info' | 'warn' | 'error';
+/** Where a run's `console` lines go: the company's logs, by the caller (it knows the sequence and the case). */
+export type ConsoleSink = (level: ConsoleLevel, text: string) => void;
+/** One `console` line keeps this many characters; the rest is cut and counted. */
+export declare const CONSOLE_LINE_MAX_CHARS = 2000;
+/** A run (a render, a start, an action) writes this many `console` lines; the rest are counted, then said in one line. */
+export declare const CONSOLE_LINES_PER_RUN = 50;
+export type HostCall = {
+    fn: string;
+    args: unknown[];
+};
+/** A host call's answer; a refused one may say why in `code` (a read: `invalid_read` / `limit_exceeded`). */
+export type HostResult = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    error: string;
+    code?: string;
+};
+export type SandboxInput = {
+    /** A JS expression evaluating to the entry function: `(arg) => value | Promise<value>`. */
+    code: string;
+    /** Code run before `code`, in the same context (e.g. the page module's helpers). */
+    prelude?: string;
+    /** JSON-serialisable argument passed to the entry function. */
+    arg: unknown;
+    /** Runs the calls one slice queued; returns one result per call, in order. */
+    dispatch: (calls: HostCall[]) => Promise<HostResult[]>;
+    limits?: Partial<SandboxLimits>;
+    /** Label for error messages. */
+    label?: string;
+    /** The name the script's stack frames give `code` (`fn/<sequence>/contextPage.js`, its `functionKey`): what its source map is found by. */
+    file?: string;
+    /** Where the script's `console` lines go; without it they go nowhere (the script still has `console`). */
+    console?: ConsoleSink;
+};
+export type SandboxStats = {
+    slices: number;
+    hostCalls: number;
+    hostBatches: number;
+    elapsedMs: number;
+};
+export type SandboxOutput = {
+    value: unknown;
+    stats: SandboxStats;
+};
+export type SandboxErrorKind = 'compile' | 'threw' | 'slice-timeout' | 'total-timeout' | 'memory' | 'host-calls' | 'stalled' | 'output';
+export declare class SandboxError extends Error {
+    readonly kind: SandboxErrorKind;
+    /** Where in the script it was thrown (25 §11): the script's own stack, kept for the logs and page tests. */
+    readonly scriptStack: string | null;
+    constructor(kind: SandboxErrorKind, message: string, 
+    /** Where in the script it was thrown (25 §11): the script's own stack, kept for the logs and page tests. */
+    scriptStack?: string | null);
+}
+export declare function runInSandbox(input: SandboxInput): Promise<SandboxOutput>;
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/core/page/sandbox.js

@@ -0,0 +1,357 @@
+import { getQuickJS } from 'quickjs-emscripten';
+export const DEFAULT_SANDBOX_LIMITS = {
+    sliceMs: 50,
+    totalMs: 2_000,
+    memoryBytes: 16 * 1024 * 1024,
+    maxStackBytes: 256 * 1024,
+    maxHostCalls: 200,
+};
+/** `console` in the sandbox: its methods, each the company log level of the same name (`log` is `info`). */
+export const CONSOLE_METHODS = ['log', 'info', 'warn', 'error', 'debug'];
+/** One `console` line keeps this many characters; the rest is cut and counted. */
+export const CONSOLE_LINE_MAX_CHARS = 2_000;
+/** A run (a render, a start, an action) writes this many `console` lines; the rest are counted, then said in one line. */
+export const CONSOLE_LINES_PER_RUN = 50;
+export class SandboxError extends Error {
+    kind;
+    scriptStack;
+    constructor(kind, message, 
+    /** Where in the script it was thrown (25 §11): the script's own stack, kept for the logs and page tests. */
+    scriptStack = null) {
+        super(message);
+        this.kind = kind;
+        this.scriptStack = scriptStack;
+        this.name = 'SandboxError';
+        if (scriptStack)
+            this.stack = `${this.name}: ${message}\n${scriptStack}`;
+    }
+}
+/**
+ * A process's first run in QuickJS compiles the engine's code as it goes (about 20ms on an idle machine,
+ * several times that on a busy one), which would count against that run's first slice and could fail a
+ * script well within its limits. So the first run waits for one untimed run of the same paths: entry,
+ * host call, console, JSON.
+ */
+let warmedUp = null;
+function warmUp() {
+    warmedUp ??= runScript({
+        code: `async (arg) => { const got = await __host('warm-up', [arg]); console.log('warm-up'); return JSON.parse(JSON.stringify({ got, list: [1, 'a', null] })); }`,
+        arg: { n: 1 },
+        dispatch: async (calls) => calls.map(() => ({ ok: true, value: 1 })),
+        limits: { sliceMs: 60_000, totalMs: 60_000 },
+        label: 'warm-up',
+    }).then(() => undefined, () => undefined);
+    return warmedUp;
+}
+export async function runInSandbox(input) {
+    await warmUp();
+    return runScript(input);
+}
+async function runScript(input) {
+    const limits = { ...DEFAULT_SANDBOX_LIMITS, ...input.limits };
+    const label = input.label ?? 'script';
+    const QuickJS = await getQuickJS();
+    const startedAt = Date.now();
+    const totalDeadline = startedAt + limits.totalMs;
+    let sliceDeadline = 0;
+    let interruptedBy = null;
+    const runtime = QuickJS.newRuntime();
+    runtime.setMemoryLimit(limits.memoryBytes);
+    runtime.setMaxStackSize(limits.maxStackBytes);
+    runtime.setInterruptHandler(() => {
+        const now = Date.now();
+        if (now > totalDeadline)
+            interruptedBy = 'total-timeout';
+        else if (now > sliceDeadline)
+            interruptedBy = 'slice-timeout';
+        else
+            return false;
+        return true;
+    });
+    const ctx = runtime.newContext();
+    const stats = { slices: 0, hostCalls: 0, hostBatches: 0, elapsedMs: 0 };
+    const queued = [];
+    let hostCallError = null;
+    const consoleLines = consoleWriter(input.console);
+    const startSlice = () => {
+        sliceDeadline = Date.now() + limits.sliceMs;
+        interruptedBy = null;
+        stats.slices += 1;
+    };
+    /** Turns a QuickJS error into a SandboxError, preferring what the interrupt handler saw. */
+    const fail = (fallback, errorHandle) => {
+        const dumped = ctx.dump(errorHandle);
+        errorHandle.dispose();
+        const message = errorMessage(dumped);
+        if (interruptedBy) {
+            return new SandboxError(interruptedBy, interruptedBy === 'slice-timeout'
+                ? `${label}: one slice ran over ${limits.sliceMs}ms`
+                : `${label}: ran over ${limits.totalMs}ms`);
+        }
+        if (/out of memory|stack overflow/i.test(message))
+            return new SandboxError('memory', `${label}: ${message}`);
+        return new SandboxError(fallback, `${label}: ${message}`, scriptStackOf(dumped));
+    };
+    try {
+        // `__host(fn, argsJson)`: queues a host call, returns a promise of its result. Args cross as
+        // JSON so nothing but plain data leaves the sandbox.
+        const hostFn = ctx.newFunction('__host', (fnHandle, argsHandle) => {
+            if (stats.hostCalls >= limits.maxHostCalls) {
+                hostCallError = new SandboxError('host-calls', `${label}: more than ${limits.maxHostCalls} host calls`);
+                return { error: ctx.newError(hostCallError.message) };
+            }
+            stats.hostCalls += 1;
+            const fn = ctx.getString(fnHandle);
+            const args = JSON.parse(ctx.getString(argsHandle));
+            const deferred = ctx.newPromise();
+            queued.push({ call: { fn, args }, deferred });
+            // The VM takes ownership of the returned handle; the deferred keeps its own.
+            return deferred.handle.dup();
+        });
+        ctx.setProp(ctx.global, '__hostRaw', hostFn);
+        hostFn.dispose();
+        // `__consoleRaw(method, text)`: one console line, written now (not a host call: no promise, no limit).
+        const consoleFn = ctx.newFunction('__consoleRaw', (methodHandle, textHandle) => {
+            consoleLines.write(ctx.getString(methodHandle), ctx.getString(textHandle));
+        });
+        ctx.setProp(ctx.global, '__consoleRaw', consoleFn);
+        consoleFn.dispose();
+        // Loading the code (the bootstrap, the prelude, the bundle's top level) is held to the total only: on a
+        // cold process parsing a page bundle alone can take longer than a slice. The script's slices start
+        // when its function is called.
+        sliceDeadline = totalDeadline;
+        interruptedBy = null;
+        const bootstrap = ctx.evalCode(`globalThis.__host = (fn, args) =>
+         __hostRaw(fn, JSON.stringify(args === undefined ? [] : args)).then((s) => JSON.parse(s));
+       ${CONSOLE_BOOTSTRAP}
+       ${input.prelude ?? ''}`);
+        if (bootstrap.error)
+            throw fail('compile', bootstrap.error);
+        bootstrap.value.dispose();
+        // Wrapped on one line: the compiled code starts on its second line, so no frame of it shifts.
+        const entryEval = input.file ? ctx.evalCode(`(${input.code})`, input.file) : ctx.evalCode(`(${input.code})`);
+        if (entryEval.error)
+            throw fail('compile', entryEval.error);
+        const entry = entryEval.value;
+        let resultHandle;
+        try {
+            const argEval = ctx.evalCode(`(${JSON.stringify(input.arg ?? null)})`);
+            if (argEval.error)
+                throw fail('compile', argEval.error);
+            const argHandle = argEval.value;
+            try {
+                startSlice();
+                const called = ctx.callFunction(entry, ctx.undefined, argHandle);
+                if (called.error)
+                    throw fail('threw', called.error);
+                resultHandle = called.value;
+            }
+            finally {
+                argHandle.dispose();
+            }
+        }
+        finally {
+            entry.dispose();
+        }
+        let settled;
+        try {
+            settled = await settle(ctx, runtime, resultHandle, {
+                startSlice,
+                fail,
+                queued,
+                dispatch: input.dispatch,
+                stats,
+                totalDeadline,
+                label,
+                limits,
+                hostCallError: () => hostCallError,
+            });
+        }
+        catch (error) {
+            if (resultHandle.alive)
+                resultHandle.dispose();
+            throw error;
+        }
+        try {
+            startSlice();
+            return { value: toJson(ctx, settled, fail), stats: { ...stats, elapsedMs: Date.now() - startedAt } };
+        }
+        finally {
+            settled.dispose();
+        }
+    }
+    finally {
+        consoleLines.end();
+        for (const { deferred } of queued)
+            deferred.dispose();
+        ctx.dispose();
+        runtime.dispose();
+    }
+}
+/**
+ * The sandbox's `console`, as Node and the editor have it: each argument a string as it is, an error as
+ * `name: message`, anything else as JSON (`String` of it when JSON has none: `undefined`, a function, a
+ * BigInt, a cycle), joined by spaces.
+ */
+const CONSOLE_BOOTSTRAP = `globalThis.console = (() => {
+  const text = (value) => {
+    if (typeof value === 'string') return value;
+    if (value instanceof Error) return value.name + ': ' + value.message;
+    try {
+      const json = JSON.stringify(value);
+      if (json !== undefined) return json;
+    } catch {}
+    return String(value);
+  };
+  const raw = __consoleRaw;
+  const out = {};
+  for (const method of ${JSON.stringify(CONSOLE_METHODS)}) out[method] = (...args) => { raw(method, args.map(text).join(' ')); };
+  return out;
+})();`;
+const CONSOLE_LEVELS = { log: 'info', info: 'info', warn: 'warn', error: 'error', debug: 'debug' };
+/**
+ * A run's `console` lines into its sink: each cut at {@link CONSOLE_LINE_MAX_CHARS}, at most
+ * {@link CONSOLE_LINES_PER_RUN} of them, and at the end one line saying how many more were dropped.
+ */
+function consoleWriter(sink) {
+    let written = 0;
+    let dropped = 0;
+    // A log line that cannot be written never fails the script.
+    const emit = (level, text) => {
+        try {
+            sink?.(level, text);
+        }
+        catch {
+            // dropped
+        }
+    };
+    return {
+        write(method, text) {
+            if (!sink)
+                return;
+            if (written >= CONSOLE_LINES_PER_RUN) {
+                dropped += 1;
+                return;
+            }
+            written += 1;
+            const line = text.length > CONSOLE_LINE_MAX_CHARS
+                ? `${text.slice(0, CONSOLE_LINE_MAX_CHARS)}… (${text.length - CONSOLE_LINE_MAX_CHARS} more characters)`
+                : text;
+            emit(CONSOLE_LEVELS[method] ?? 'info', line);
+        },
+        end() {
+            if (dropped > 0) {
+                emit('warn', `${dropped} more console ${dropped === 1 ? 'line was' : 'lines were'} dropped: a run writes at most ${CONSOLE_LINES_PER_RUN}`);
+            }
+        },
+    };
+}
+/** Pumps jobs and host calls until the entry's result is no longer a pending promise. */
+async function settle(ctx, runtime, handle, env) {
+    for (;;) {
+        const jobs = runtime.executePendingJobs();
+        if (jobs.error)
+            throw env.fail('threw', jobs.error);
+        const hostError = env.hostCallError();
+        if (hostError)
+            throw hostError;
+        const state = ctx.getPromiseState(handle);
+        if (state.type === 'fulfilled') {
+            if (state.notAPromise)
+                return handle;
+            handle.dispose();
+            return state.value;
+        }
+        if (state.type === 'rejected') {
+            handle.dispose();
+            throw env.fail('threw', state.error);
+        }
+        const batch = env.queued.splice(0);
+        if (batch.length === 0) {
+            throw new SandboxError('stalled', `${env.label}: waiting on a promise that no host call will settle`);
+        }
+        const remaining = env.totalDeadline - Date.now();
+        if (remaining <= 0) {
+            for (const { deferred } of batch)
+                deferred.dispose();
+            throw new SandboxError('total-timeout', `${env.label}: ran over ${env.limits.totalMs}ms`);
+        }
+        env.stats.hostBatches += 1;
+        let results;
+        try {
+            results = await withTimeout(env.dispatch(batch.map((q) => q.call)), remaining, () => new SandboxError('total-timeout', `${env.label}: ran over ${env.limits.totalMs}ms`));
+        }
+        catch (error) {
+            for (const { deferred } of batch)
+                deferred.dispose();
+            throw error;
+        }
+        if (results.length !== batch.length) {
+            for (const { deferred } of batch)
+                deferred.dispose();
+            throw new Error(`${env.label}: dispatch returned ${results.length} results for ${batch.length} calls`);
+        }
+        env.startSlice();
+        batch.forEach(({ deferred }, i) => {
+            const result = results[i];
+            if (result.ok) {
+                const json = ctx.newString(JSON.stringify(result.value ?? null));
+                deferred.resolve(json);
+                json.dispose();
+            }
+            else {
+                const error = ctx.newError(result.error);
+                deferred.reject(error);
+                error.dispose();
+            }
+            deferred.dispose();
+        });
+    }
+}
+/** The result as plain JSON, serialised inside the VM so cycles and BigInts fail loudly. */
+function toJson(ctx, handle, fail) {
+    const stringify = ctx.evalCode('(v) => v === undefined ? "null" : JSON.stringify(v)');
+    if (stringify.error)
+        throw fail('output', stringify.error);
+    try {
+        const out = ctx.callFunction(stringify.value, ctx.undefined, handle);
+        if (out.error)
+            throw fail('output', out.error);
+        try {
+            return JSON.parse(ctx.getString(out.value));
+        }
+        finally {
+            out.value.dispose();
+        }
+    }
+    finally {
+        stringify.value.dispose();
+    }
+}
+async function withTimeout(promise, ms, onTimeout) {
+    let timer;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(onTimeout()), ms);
+            }),
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** The script's stack of a thrown error, as QuickJS dumps it; null when it has none. */
+function scriptStackOf(dumped) {
+    const stack = dumped && typeof dumped === 'object' ? dumped.stack : undefined;
+    return typeof stack === 'string' && stack.trim() ? stack.trimEnd() : null;
+}
+function errorMessage(dumped) {
+    if (dumped && typeof dumped === 'object' && 'message' in dumped) {
+        const { name, message } = dumped;
+        return name && name !== 'Error' ? `${String(name)}: ${String(message)}` : String(message);
+    }
+    return String(dumped);
+}
+//# sourceMappingURL=sandbox.js.map

package/dist/core/page/time-format.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Times as people read them, in a time zone (25 §11). The page's sandbox has no `Intl` (a date's
+ * `toLocaleString` ignores the zone there), so a page formats through the platform (`ctx.time.format`),
+ * which runs this; a function, on the Worker, calls it as it is (`ctx.time.format`).
+ */
+/** How much of the time to show: `'datetime'` (default) "Tue, Nov 3, 3:00 PM EST", `'date'` "Tue, Nov 3, 2026", `'time'` "3:00 PM EST". */
+export type TimeStyle = 'datetime' | 'date' | 'time';
+export type FormatTimeOptions = {
+    timeZone: string;
+    style?: TimeStyle;
+};
+/** `at` (ISO 8601, or epoch ms) in `timeZone`, in US English. Throws on a time or zone it cannot read. */
+export declare function formatTime(at: string | number, options: FormatTimeOptions): string;
+/**
+ * The calendar day (`YYYY-MM-DD`) at `at` in `timeZone`: `ctx.time.day` (25 §11), to compare days or
+ * key a rule by date. Throws on a time or zone it cannot read.
+ */
+export declare function dayIn(at: string | number | Date, timeZone: string): string;
+/**
+ * A moment as it reads on a clock in a time zone (74 §4.7): `ctx.time.parts`. `weekday` is ISO: 1 Monday …
+ * 7 Sunday; `offset` the zone's offset from UTC then (`-05:00`).
+ */
+export type TimeParts = {
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    second: number;
+    weekday: 1 | 2 | 3 | 4 | 5 | 6 | 7;
+    /** `YYYY-MM-DD`. */
+    date: string;
+    /** `HH:mm`, 24-hour. */
+    time: string;
+    offset: string;
+};
+/** `at` on a clock in `timeZone`: `ctx.time.parts` (74 §4.7). Throws on a time or zone it cannot read. */
+export declare function timeParts(at: string | number | Date, timeZone: string): TimeParts;
+/**
+ * The exact moment (ISO 8601, UTC) a clock in `timeZone` shows `date` (`YYYY-MM-DD`) at `time` (`HH:mm` or
+ * `HH:mm:ss`): `ctx.time.at` (74 §4.7), "the day before delivery at 17:00 in the customer's zone". A time the
+ * clocks skip (spring forward) is the moment just after the gap, as the clock shows it then; a time they show
+ * twice (fall back), the first. Throws on a date, time or zone it cannot read.
+ */
+export declare function timeAt(date: string, time: string, timeZone: string): string;
+//# sourceMappingURL=time-format.d.ts.map

package/dist/core/page/time-format.js

@@ -0,0 +1,125 @@
+/**
+ * Times as people read them, in a time zone (25 §11). The page's sandbox has no `Intl` (a date's
+ * `toLocaleString` ignores the zone there), so a page formats through the platform (`ctx.time.format`),
+ * which runs this; a function, on the Worker, calls it as it is (`ctx.time.format`).
+ */
+const STYLES = {
+    datetime: { weekday: 'short', month: 'short', day: 'numeric', hour: 'numeric', minute: '2-digit', timeZoneName: 'short' },
+    date: { weekday: 'short', month: 'short', day: 'numeric', year: 'numeric' },
+    time: { hour: 'numeric', minute: '2-digit', timeZoneName: 'short' },
+};
+/** `at` (ISO 8601, or epoch ms) in `timeZone`, in US English. Throws on a time or zone it cannot read. */
+export function formatTime(at, options) {
+    const date = new Date(at);
+    if (Number.isNaN(date.getTime()))
+        throw new Error(`time.format: ${String(at)} is not a time`);
+    const style = options.style ?? 'datetime';
+    if (!(style in STYLES))
+        throw new Error(`time.format: style is 'datetime', 'date' or 'time'`);
+    try {
+        return new Intl.DateTimeFormat('en-US', { ...STYLES[style], timeZone: options.timeZone }).format(date);
+    }
+    catch {
+        throw new Error(`time.format: ${options.timeZone} is not a time zone`);
+    }
+}
+/**
+ * The calendar day (`YYYY-MM-DD`) at `at` in `timeZone`: `ctx.time.day` (25 §11), to compare days or
+ * key a rule by date. Throws on a time or zone it cannot read.
+ */
+export function dayIn(at, timeZone) {
+    const date = new Date(at);
+    if (Number.isNaN(date.getTime()))
+        throw new Error(`time.day: ${String(at)} is not a time`);
+    try {
+        return new Intl.DateTimeFormat('en-CA', { timeZone, year: 'numeric', month: '2-digit', day: '2-digit' }).format(date);
+    }
+    catch {
+        throw new Error(`time.day: ${timeZone} is not a time zone`);
+    }
+}
+const WEEKDAYS = { Mon: 1, Tue: 2, Wed: 3, Thu: 4, Fri: 5, Sat: 6, Sun: 7 };
+function clockIn(ms, timeZone, what) {
+    let parts;
+    try {
+        parts = new Intl.DateTimeFormat('en-US', {
+            timeZone,
+            hourCycle: 'h23',
+            year: 'numeric',
+            month: 'numeric',
+            day: 'numeric',
+            hour: 'numeric',
+            minute: 'numeric',
+            second: 'numeric',
+            weekday: 'short',
+        }).formatToParts(new Date(ms));
+    }
+    catch {
+        throw new Error(`${what}: ${timeZone} is not a time zone`);
+    }
+    const part = (type) => parts.find((p) => p.type === type)?.value ?? '';
+    return {
+        year: Number(part('year')),
+        month: Number(part('month')),
+        day: Number(part('day')),
+        hour: Number(part('hour')),
+        minute: Number(part('minute')),
+        second: Number(part('second')),
+        weekday: WEEKDAYS[part('weekday')] ?? 1,
+    };
+}
+/** The zone's offset from UTC at `ms`, in minutes (New York in winter: -300). */
+function offsetMinutes(ms, timeZone, what) {
+    const c = clockIn(ms, timeZone, what);
+    const asUtc = Date.UTC(c.year, c.month - 1, c.day, c.hour, c.minute, c.second);
+    return Math.round((asUtc - Math.floor(ms / 1000) * 1000) / 60_000);
+}
+const pad = (n, width = 2) => String(Math.abs(n)).padStart(width, '0');
+function offsetText(minutes) {
+    return `${minutes < 0 ? '-' : '+'}${pad(Math.floor(Math.abs(minutes) / 60))}:${pad(Math.abs(minutes) % 60)}`;
+}
+/** `at` on a clock in `timeZone`: `ctx.time.parts` (74 §4.7). Throws on a time or zone it cannot read. */
+export function timeParts(at, timeZone) {
+    const ms = new Date(at).getTime();
+    if (Number.isNaN(ms))
+        throw new Error(`time.parts: ${String(at)} is not a time`);
+    const c = clockIn(ms, timeZone, 'time.parts');
+    return {
+        ...c,
+        date: `${pad(c.year, 4)}-${pad(c.month)}-${pad(c.day)}`,
+        time: `${pad(c.hour)}:${pad(c.minute)}`,
+        offset: offsetText(offsetMinutes(ms, timeZone, 'time.parts')),
+    };
+}
+/**
+ * The exact moment (ISO 8601, UTC) a clock in `timeZone` shows `date` (`YYYY-MM-DD`) at `time` (`HH:mm` or
+ * `HH:mm:ss`): `ctx.time.at` (74 §4.7), "the day before delivery at 17:00 in the customer's zone". A time the
+ * clocks skip (spring forward) is the moment just after the gap, as the clock shows it then; a time they show
+ * twice (fall back), the first. Throws on a date, time or zone it cannot read.
+ */
+export function timeAt(date, time, timeZone) {
+    const d = /^(\d{4})-(\d{2})-(\d{2})$/.exec(date);
+    const t = /^(\d{2}):(\d{2})(?::(\d{2}))?$/.exec(time);
+    if (!d)
+        throw new Error(`time.at: ${date} is not a date (YYYY-MM-DD)`);
+    if (!t)
+        throw new Error(`time.at: ${time} is not a time (HH:mm)`);
+    const [year, month, day] = [Number(d[1]), Number(d[2]), Number(d[3])];
+    const [hour, minute, second] = [Number(t[1]), Number(t[2]), Number(t[3] ?? 0)];
+    const wall = Date.UTC(year, month - 1, day, hour, minute, second);
+    const check = new Date(wall);
+    if (check.getUTCMonth() !== month - 1 || check.getUTCDate() !== day || hour > 23 || minute > 59 || second > 59) {
+        throw new Error(`time.at: ${date} ${time} is no date and time`);
+    }
+    // The offsets on either side of the moment: the earlier one first, so a time shown twice is its first.
+    const before = offsetMinutes(wall - 24 * 3_600_000, timeZone, 'time.at');
+    const after = offsetMinutes(wall + 24 * 3_600_000, timeZone, 'time.at');
+    for (const offset of [before, after]) {
+        const ms = wall - offset * 60_000;
+        if (offsetMinutes(ms, timeZone, 'time.at') === offset)
+            return new Date(ms).toISOString();
+    }
+    // In the gap the clocks skip: read with the offset before it, it lands as far past the gap.
+    return new Date(wall - before * 60_000).toISOString();
+}
+//# sourceMappingURL=time-format.js.map

package/dist/core/page/timeline.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The case's timeline (20 §3, 21 §11.6): everything that happened on one instance, merged and in time
+ * order — messages, calls, the AI's runs and what they did, field changes, scheduled contacts, the
+ * Orchestrator. One shape for every source, so a page, the web and a prompt read it the same way.
+ */
+export type TimelineKind = 'message' | 'call' | 'run' | 'action' | 'write' | 'scheduled' | 'orchestrator';
+export declare const TIMELINE_KINDS: readonly TimelineKind[];
+export type TimelineEntry = {
+    /** The source row's id. */
+    id: string;
+    kind: TimelineKind;
+    /** ISO time it happened (a message's time, a call's start, a run's start, a write). */
+    at: string;
+    channel: 'call' | 'sms' | 'email' | 'event' | null;
+    direction?: 'inbound' | 'outbound';
+    contactId: string | null;
+    /** One line: what happened, as a person would read it. */
+    text: string;
+    /** A message's body. */
+    body?: string;
+    subject?: string | null;
+    status?: string;
+    /** The text or email run it belongs to (a message it answered, an action it ran). */
+    runId?: string | null;
+    /** Where this entry is in the order: pass it as `before` for what comes before it (the next page). */
+    cursor: string;
+};
+/**
+ * What a timeline read may narrow to. `before`: an entry's `cursor` — the entries after it in the order
+ * (older, or as old and further along), so equal times are never skipped or read twice; or an ISO time.
+ */
+export type TimelineWhere = {
+    kinds?: TimelineKind[];
+    channel?: 'call' | 'sms' | 'email';
+    contactId?: string;
+    before?: string;
+    /** Default 50, at most 200. */
+    limit?: number;
+};
+//# sourceMappingURL=timeline.d.ts.map

package/dist/core/page/timeline.js

@@ -0,0 +1,2 @@
+export const TIMELINE_KINDS = ['message', 'call', 'run', 'action', 'write', 'scheduled', 'orchestrator'];
+//# sourceMappingURL=timeline.js.map