wehub-resource-sync
695 lines
31 KiB
TypeScript
695 lines
31 KiB
TypeScript
// @native-sdk/core — the SDK module an app core imports. The subset program
|
|
// maps the "@native-sdk/core" specifier onto this file, so stock tsc types
|
|
// it; the transpiler lowers references to it onto the rt kernel and never
|
|
// emits this module's own code.
|
|
//
|
|
// `Cmd` is the typed-effects surface (spec section 2): `update` (and, since
|
|
// v2, `initialModel`) may return `[model, cmd]`, where the cmd is INERT DATA
|
|
// describing effects for the runtime to perform after the returned model
|
|
// commits. Commands are built only from these factories, and only in that
|
|
// return path (NS1017) — they never live in the Model, in a Msg, in a local,
|
|
// or in a helper.
|
|
//
|
|
// The v2 command set:
|
|
//
|
|
// Cmd.none no effects (what a bare `return model` means)
|
|
// Cmd.persist() ask the host to persist the committed model
|
|
// Cmd.now("tick") request a timestamp; the runtime dispatches
|
|
// the named Msg arm with the time (ms) as its
|
|
// single number payload field
|
|
// Cmd.host(name, ...args) a host command by name with scalar args —
|
|
// the host interprets the name
|
|
// Cmd.host(name, payload) the same, carrying one bytes payload — a
|
|
// Uint8Array, or a flat record of number /
|
|
// boolean / Uint8Array fields that lowers to
|
|
// bytes (hostRecordBytes below)
|
|
// Cmd.request(name, payload, a routed host command: the host performs it
|
|
// { key?, ok, err }) and dispatches the `ok` Msg arm with the
|
|
// result bytes, or the `err` arm with the error
|
|
// bytes — each arm carries exactly one
|
|
// Uint8Array payload field, checked by tsc. The
|
|
// optional `key` names the in-flight effect:
|
|
// re-issuing a live key replaces it, and
|
|
// Cmd.cancel(key) drops it.
|
|
// Cmd.cancel(key) drop the in-flight keyed effect — request,
|
|
// readFile/writeFile/fetch/clipboardRead, or
|
|
// delay — SILENTLY (no terminal arm dispatch).
|
|
// Aimed at a live spawn it stays LOUD: the
|
|
// child dies and the err arm runs with
|
|
// "cancelled" — killing a process is an
|
|
// observable event
|
|
// Cmd.batch([a, b, ...]) several commands from one dispatch
|
|
//
|
|
// The named engine ops (each maps onto the host's effect engine directly;
|
|
// routing follows the request rules — string-literal arm names, tsc-checked
|
|
// arm shapes):
|
|
//
|
|
// Cmd.readFile(path, { key?, ok, err })
|
|
// whole-file read; ok arm carries the bytes
|
|
// (one Uint8Array field), err arm the reason
|
|
// bytes ("not_found", "io_failed", "truncated",
|
|
// "rejected")
|
|
// Cmd.writeFile(path, bytes, { key?, ok, err })
|
|
// whole-file write (parents created, replaced
|
|
// whole); ok arm carries NOTHING (an arm with
|
|
// no payload fields), err arm the reason bytes
|
|
// Cmd.fetch({ url, method?, headers?, body?, timeoutMs? }, { key?, ok, err })
|
|
// buffered HTTP(S) exchange; ok arm carries a
|
|
// two-field record — one number field (the real
|
|
// HTTP status, non-2xx included) and one
|
|
// Uint8Array field (the whole body) — err arm
|
|
// the reason bytes ("connect_failed",
|
|
// "tls_failed", "protocol_failed", "timed_out",
|
|
// "rejected", "truncated")
|
|
// Cmd.clipboardWrite(bytes) fire-and-forget clipboard write
|
|
// Cmd.clipboardRead({ key?, ok, err })
|
|
// clipboard read; ok arm carries the text bytes,
|
|
// err arm the reason bytes ("failed",
|
|
// "rejected")
|
|
// Cmd.delay(key, ms, "fired") a keyed ONE-SHOT timer: dispatches the named
|
|
// arm once after `ms`, with the fire time (ms)
|
|
// as its single number payload; re-issuing a
|
|
// live key re-arms from now (debounce), and
|
|
// Cmd.cancel(key) drops it silently
|
|
//
|
|
// The streaming ops (one issue, MANY result Msgs across dispatches, a keyed
|
|
// lifecycle the app drives):
|
|
//
|
|
// Cmd.spawn(argv, { key?, stdin?, line?, exit, err })
|
|
// Cmd.spawn(argv, { key?, stdin?, collect: true, exit, err })
|
|
// run a subprocess. Line mode streams each
|
|
// stdout line to the `line` arm (one Uint8Array
|
|
// field; omit `line` to drop lines); collect
|
|
// mode buffers whole stdout instead. Exactly one
|
|
// terminal follows: a clean exit dispatches
|
|
// `exit` — line mode: one number field (the exit
|
|
// code); collect mode: a two-field record, one
|
|
// number (the code) and one Uint8Array (the
|
|
// collected stdout), matched by type — and every
|
|
// other end dispatches `err` with the reason
|
|
// bytes ("signaled", "cancelled", "rejected",
|
|
// "spawn_failed", "truncated"). Cmd.cancel(key)
|
|
// ends the child mid-stream (err arm
|
|
// "cancelled" — never silent).
|
|
// Cmd.audioPlay(key, { path?, url?, cachePath?, expectedBytes? }, { event })
|
|
// open (or replace — one player is the whole
|
|
// surface) the audio event stream: every
|
|
// playback event dispatches the `event` arm (the
|
|
// six-field record below) until Cmd.audioStop
|
|
// closes the stream.
|
|
// Cmd.audioPause(key) / audioResume(key) / audioStop(key)
|
|
// Cmd.audioSeek(key, ms) / Cmd.audioSetVolume(key, volume)
|
|
// drive the open stream in place — fire-and-
|
|
// forget control verbs whose consequences arrive
|
|
// on the event stream; aimed at a key with no
|
|
// open stream they no-op.
|
|
//
|
|
// The keyed-effect discipline is ONE rule: a keyed effect REPLACES its live
|
|
// predecessor (the superseded effect's result is dropped — no message), and
|
|
// Cmd.cancel drops it silently. That holds for request, readFile, writeFile,
|
|
// fetch, clipboardRead, and delay alike. The ONE exception is a live spawn
|
|
// key: a duplicate REJECTS the new spawn (err arm "rejected") — a running
|
|
// subprocess is never killed implicitly; cancel it first. And spawn's cancel
|
|
// stays loud (err arm "cancelled"): killing a process is an observable event.
|
|
//
|
|
// `Sub` is the recurring-effects surface: an app may export
|
|
// `subscriptions(model): Sub<Msg>` returning declarative descriptors the
|
|
// host reconciles after every commit (Sub.timer fires the named arm with the
|
|
// current time on each interval). Like Cmd, Sub values are inert data, legal
|
|
// only in that function's return path (NS1025). Sub and the streaming Cmds
|
|
// are different animals on purpose: a Sub is DECLARED from the model (the
|
|
// host starts/stops it by reconciliation; the app never opens one), while
|
|
// spawn/audioPlay streams are Cmd-INITIATED — imperative opens with a keyed
|
|
// lifecycle the app drives and cancels.
|
|
//
|
|
// The factories return plain frozen-shape objects so the same core runs
|
|
// under node: a dev harness can interpret the `op` tags directly.
|
|
|
|
// The byte-text method surface (s.toUpperCase(), s.split(sep), ... on
|
|
// Uint8Array): the transpiler adds the ambient file to every core's program
|
|
// itself; this reference carries the same surface into EDITORS of apps that
|
|
// import "@native-sdk/core", so tsc-in-the-editor and `native check` agree.
|
|
/// <reference path="./bytes_text_methods.d.ts" />
|
|
|
|
/// The text intrinsic: turn a string literal or template into bytes. The
|
|
/// transpiler recognizes calls BY IDENTITY (this import, renames honored)
|
|
/// and folds them at compile time — a literal argument becomes rodata, a
|
|
/// template becomes frame-arena bytes via bufPrint — so no string ever
|
|
/// exists at native runtime. Under node this body runs as-is, byte for
|
|
/// byte the same result. Arguments must be literals or templates; dynamic
|
|
/// text lives in the model as Uint8Array from the start.
|
|
export function asciiBytes(s: string): Uint8Array {
|
|
const out = new Uint8Array(s.length);
|
|
for (let i = 0; i < s.length; i++) out[i] = s.charCodeAt(i);
|
|
return out;
|
|
}
|
|
|
|
/// Every app Msg is a discriminated union on a string `kind` tag.
|
|
export type Msgish = { readonly kind: string };
|
|
|
|
/// The Msg arms `Cmd.now` may target: arms whose payload is exactly one
|
|
/// number-typed field (the runtime dispatches the arm with the timestamp in
|
|
/// that field). Anything else is unrepresentable — the runtime has only a
|
|
/// number to give back.
|
|
export type TimestampKind<M extends Msgish> = M extends Msgish
|
|
? {
|
|
[K in Exclude<keyof M, "kind">]-?: M[K] extends number
|
|
? [Exclude<keyof M, "kind">] extends [K]
|
|
? M["kind"]
|
|
: never
|
|
: never;
|
|
}[Exclude<keyof M, "kind">]
|
|
: never;
|
|
|
|
/// The Msg arms a routed host result may target: arms whose payload is
|
|
/// exactly one Uint8Array-typed field (the runtime dispatches the arm with
|
|
/// the result/error bytes in that field).
|
|
export type BytesKind<M extends Msgish> = M extends Msgish
|
|
? {
|
|
[K in Exclude<keyof M, "kind">]-?: M[K] extends Uint8Array
|
|
? [Exclude<keyof M, "kind">] extends [K]
|
|
? M["kind"]
|
|
: never
|
|
: never;
|
|
}[Exclude<keyof M, "kind">]
|
|
: never;
|
|
|
|
/// The Msg arms a payload-less routed result may target: arms with no
|
|
/// payload fields at all (`Cmd.writeFile`'s ok route — a successful write
|
|
/// has nothing to report beyond success).
|
|
export type EmptyKind<M extends Msgish> = M extends Msgish
|
|
? [Exclude<keyof M, "kind">] extends [never]
|
|
? M["kind"]
|
|
: never
|
|
: never;
|
|
|
|
/// The Msg arms a buffered fetch response may target: arms whose payload is
|
|
/// exactly two fields — one number (the HTTP status) and one Uint8Array (the
|
|
/// body). The runtime matches the fields by TYPE, so their names are yours.
|
|
export type FetchedKind<M extends Msgish> = M extends Msgish
|
|
? {
|
|
[K in Exclude<keyof M, "kind">]-?: M[K] extends Uint8Array
|
|
? Exclude<keyof M, "kind" | K> extends infer O
|
|
? O extends keyof M
|
|
? M[O] extends number
|
|
? [Exclude<keyof M, "kind" | K | O>] extends [never]
|
|
? M["kind"]
|
|
: never
|
|
: never
|
|
: never
|
|
: never
|
|
: never;
|
|
}[Exclude<keyof M, "kind">]
|
|
: never;
|
|
|
|
// ------------------------------------------------- wiring channel shapes
|
|
// The generated wiring's opt-in host-event channels: export the channel
|
|
// and it is wired (`commandMsg(name: string): Msg | null` is the same
|
|
// family — menus, shortcuts, chrome tabs — and predates these). Event
|
|
// RECORD shapes (`frameMsg`'s FrameEvent, `keyMsg`'s KeyEvent, the
|
|
// appearanceMsg/chromeMsg arm payloads) are DECLARED IN YOUR CORE and
|
|
// matched by field name, the TextInputEvent rule — they must emit as your
|
|
// module's own records, so an SDK interface cannot stand in for them.
|
|
|
|
/// One `envMsgs` entry: `export const envMsgs = [{ env: "NAME", msg:
|
|
/// "<arm>" }] as const` — each named environment variable present at launch
|
|
/// dispatches its value through the arm (exactly one `Uint8Array` field) as
|
|
/// an ordinary journaled Msg right after the boot command. The core itself
|
|
/// never reads the environment (NS1005); replay carries the recorded values.
|
|
export interface EnvMsg<M extends Msgish> {
|
|
readonly env: string;
|
|
readonly msg: BytesKind<M>;
|
|
}
|
|
|
|
/// The audio event states, mirroring the engine's event vocabulary: `loaded`
|
|
/// acknowledges a successful load with the player's duration estimate;
|
|
/// `position` ticks at the platform's honest cadence (~500ms) while playing;
|
|
/// `completed` fires exactly once at the natural end; `failed` reports a
|
|
/// load/decode/device failure; `rejected` a command the effects layer refused
|
|
/// (an empty or over-long source); `spectrum` carries a band-magnitude
|
|
/// analysis frame from hosts that analyze their playback.
|
|
export type AudioState = "loaded" | "position" | "completed" | "failed" | "rejected" | "spectrum";
|
|
|
|
/// The payload shape of an audio event arm — six fields, matched by NAME (the
|
|
/// one SDK-fixed record shape, so the host can build it from your union).
|
|
/// `state` must be a named string-literal-union alias carrying exactly the
|
|
/// six AudioState members (any declaration order — the host matches members
|
|
/// by name). `positionMs`/`durationMs` are milliseconds; `playing` is the
|
|
/// player's transport state; `buffering` is true while a streamed source is
|
|
/// stalled waiting for network bytes; `bands` is the 32 spectrum band
|
|
/// magnitudes (0..255 each, all zeros outside "spectrum" events).
|
|
export type AudioEventArm = {
|
|
readonly state: AudioState;
|
|
readonly positionMs: number;
|
|
readonly durationMs: number;
|
|
readonly playing: boolean;
|
|
readonly buffering: boolean;
|
|
readonly bands: Uint8Array;
|
|
};
|
|
|
|
/// The Msg arms an audio event stream may target: arms whose payload is
|
|
/// exactly the six AudioEventArm fields.
|
|
export type AudioEventKind<M extends Msgish> = M extends Msgish
|
|
? [Exclude<keyof M, "kind">] extends [keyof AudioEventArm]
|
|
? [keyof AudioEventArm] extends [Exclude<keyof M, "kind">]
|
|
? M extends Msgish & AudioEventArm
|
|
? M["kind"]
|
|
: never
|
|
: never
|
|
: never
|
|
: never;
|
|
|
|
/// One field of a host record payload; see hostRecordBytes for the encoding.
|
|
export type HostScalar = number | boolean | Uint8Array;
|
|
|
|
/// A structured host payload: a flat record of scalar/bytes fields, lowered
|
|
/// to one bytes payload at build time (natively) and by hostRecordBytes
|
|
/// (under node) — the same bytes either way.
|
|
export type HostRecord = { readonly [field: string]: HostScalar };
|
|
|
|
/// How a `Cmd.request` result comes back: the host dispatches the `ok` arm
|
|
/// with the result bytes on success, or the `err` arm with the error bytes.
|
|
/// Arm names are string literals — the routing is data, never a callback.
|
|
/// `key` (optional) names the in-flight effect for replace/cancel semantics.
|
|
export interface RequestRoute<M extends Msgish> {
|
|
readonly key?: string;
|
|
readonly ok: BytesKind<M>;
|
|
readonly err: BytesKind<M>;
|
|
}
|
|
|
|
/// `Cmd.writeFile` routing: the ok arm carries no payload (success has
|
|
/// nothing to report); the err arm carries the reason bytes.
|
|
export interface WriteRoute<M extends Msgish> {
|
|
readonly key?: string;
|
|
readonly ok: EmptyKind<M>;
|
|
readonly err: BytesKind<M>;
|
|
}
|
|
|
|
/// `Cmd.fetch` routing: the ok arm carries `{ status, body }` (one number
|
|
/// field, one bytes field — matched by type); the err arm the reason bytes.
|
|
export interface FetchRoute<M extends Msgish> {
|
|
readonly key?: string;
|
|
readonly ok: FetchedKind<M>;
|
|
readonly err: BytesKind<M>;
|
|
}
|
|
|
|
/// `Cmd.spawn` routing, line mode: each stdout line dispatches the optional
|
|
/// `line` arm (one bytes field; omitted = lines dropped), a clean exit the
|
|
/// `exit` arm (one number field — the exit code), every other end the `err`
|
|
/// arm with the reason bytes.
|
|
export interface SpawnRoute<M extends Msgish> {
|
|
readonly key?: string;
|
|
readonly stdin?: Uint8Array;
|
|
readonly line?: BytesKind<M>;
|
|
readonly exit: TimestampKind<M>;
|
|
readonly err: BytesKind<M>;
|
|
}
|
|
|
|
/// `Cmd.spawn` routing, collect mode: whole stdout buffers until the exit,
|
|
/// which dispatches the `exit` arm as a two-field record — one number field
|
|
/// (the exit code) and one bytes field (the collected stdout), matched by
|
|
/// type so the names are yours. No line arm: there is no line framing.
|
|
export interface SpawnCollectRoute<M extends Msgish> {
|
|
readonly key?: string;
|
|
readonly stdin?: Uint8Array;
|
|
readonly collect: true;
|
|
readonly exit: FetchedKind<M>;
|
|
readonly err: BytesKind<M>;
|
|
}
|
|
|
|
/// A `Cmd.audioPlay` source: the resolution cascade of the engine underneath.
|
|
/// The local `path` is tried first; a missing file falls through to `url`
|
|
/// (streamed progressively, cached at `cachePath` when given and verified
|
|
/// against `expectedBytes` — 0/omitted means unknown size, existence alone
|
|
/// qualifies a cache entry). At least one of path/url must be present.
|
|
export interface AudioSource {
|
|
readonly path?: Uint8Array;
|
|
readonly url?: Uint8Array;
|
|
readonly cachePath?: Uint8Array;
|
|
readonly expectedBytes?: number;
|
|
}
|
|
|
|
/// `Cmd.audioPlay` routing: every playback event dispatches the `event` arm
|
|
/// (the six-field AudioEventArm record, matched by field name).
|
|
export interface AudioRoute<M extends Msgish> {
|
|
readonly event: AudioEventKind<M>;
|
|
}
|
|
|
|
/// The closed HTTP verb set of `Cmd.fetch` (wire value = declaration order).
|
|
export type FetchMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD";
|
|
|
|
/// A `Cmd.fetch` request. `url` is bytes (asciiBytes for literals); headers
|
|
/// are a flat record whose NAMES are compile-time text and whose VALUES are
|
|
/// string literals or runtime bytes (`Uint8Array` — how a launch-supplied
|
|
/// credential rides an `Authorization` header); `timeoutMs` omitted means
|
|
/// the host engine's default.
|
|
export interface FetchSpec {
|
|
readonly url: Uint8Array;
|
|
readonly method?: FetchMethod;
|
|
readonly headers?: { readonly [name: string]: string | Uint8Array };
|
|
readonly body?: Uint8Array;
|
|
readonly timeoutMs?: number;
|
|
}
|
|
|
|
/// An inert command value, parameterized by the app's Msg union so the
|
|
/// factories can validate message targets. Opaque to app code: build with
|
|
/// the `Cmd.*` factories, return from `update`/`initialModel`, never inspect
|
|
/// or store.
|
|
export type Cmd<M extends Msgish> =
|
|
| { readonly op: "none" }
|
|
| { readonly op: "persist" }
|
|
| { readonly op: "now"; readonly msgKind: string }
|
|
| { readonly op: "host"; readonly name: string; readonly args: readonly number[] }
|
|
| { readonly op: "host_bytes"; readonly name: string; readonly payload: Uint8Array }
|
|
| {
|
|
readonly op: "request";
|
|
readonly name: string;
|
|
readonly key: string;
|
|
readonly okKind: string;
|
|
readonly errKind: string;
|
|
readonly payload: Uint8Array;
|
|
}
|
|
| { readonly op: "cancel"; readonly key: string }
|
|
| {
|
|
readonly op: "read_file";
|
|
readonly key: string;
|
|
readonly okKind: string;
|
|
readonly errKind: string;
|
|
readonly path: Uint8Array;
|
|
}
|
|
| {
|
|
readonly op: "write_file";
|
|
readonly key: string;
|
|
readonly okKind: string;
|
|
readonly errKind: string;
|
|
readonly path: Uint8Array;
|
|
readonly bytes: Uint8Array;
|
|
}
|
|
| {
|
|
readonly op: "fetch";
|
|
readonly key: string;
|
|
readonly okKind: string;
|
|
readonly errKind: string;
|
|
readonly method: FetchMethod;
|
|
readonly timeoutMs: number;
|
|
readonly url: Uint8Array;
|
|
/// Header pairs, already in TS-field-name (code-unit) sort order.
|
|
/// A string value is compile-time text; a Uint8Array value is
|
|
/// runtime bytes (both encode as the record's length-prefixed
|
|
/// value field).
|
|
readonly headers: readonly { readonly name: string; readonly value: string | Uint8Array }[];
|
|
readonly body: Uint8Array;
|
|
}
|
|
| { readonly op: "clip_write"; readonly bytes: Uint8Array }
|
|
| { readonly op: "clip_read"; readonly key: string; readonly okKind: string; readonly errKind: string }
|
|
| { readonly op: "delay"; readonly key: string; readonly afterMs: number; readonly msgKind: string }
|
|
| {
|
|
readonly op: "spawn";
|
|
readonly key: string;
|
|
/// "" = no line routing (collect mode, or a line spawn that only
|
|
/// cares about the exit).
|
|
readonly lineKind: string;
|
|
readonly exitKind: string;
|
|
readonly errKind: string;
|
|
readonly collect: boolean;
|
|
readonly argv: readonly Uint8Array[];
|
|
readonly stdin: Uint8Array;
|
|
}
|
|
| {
|
|
readonly op: "audio_play";
|
|
readonly key: string;
|
|
readonly eventKind: string;
|
|
readonly path: Uint8Array;
|
|
readonly url: Uint8Array;
|
|
readonly cachePath: Uint8Array;
|
|
readonly expectedBytes: number;
|
|
}
|
|
| {
|
|
readonly op: "audio_ctl";
|
|
readonly key: string;
|
|
readonly verb: "pause" | "resume" | "stop" | "seek" | "volume";
|
|
/// Seek position (ms) / volume (0..1); 0 for the value-less verbs.
|
|
readonly value: number;
|
|
}
|
|
| { readonly op: "batch"; readonly cmds: readonly Cmd<M>[] };
|
|
|
|
/// The wire encoding of a host record payload, byte-identical to what the
|
|
/// transpiler derives from the record's TS shape at build time: fields
|
|
/// sorted by name (code-unit order), concatenated with no field headers —
|
|
/// number -> f64 little-endian (8 bytes), boolean -> one 0/1 byte,
|
|
/// Uint8Array -> u32 little-endian length + bytes.
|
|
export function hostRecordBytes(payload: HostRecord): Uint8Array {
|
|
const names = Object.keys(payload).sort();
|
|
let len = 0;
|
|
for (const n of names) {
|
|
const v = payload[n];
|
|
if (typeof v === "number") len += 8;
|
|
else if (typeof v === "boolean") len += 1;
|
|
else len += 4 + v.length;
|
|
}
|
|
const out = new Uint8Array(len);
|
|
const dv = new DataView(out.buffer);
|
|
let off = 0;
|
|
for (const n of names) {
|
|
const v = payload[n];
|
|
if (typeof v === "number") {
|
|
dv.setFloat64(off, v, true);
|
|
off += 8;
|
|
} else if (typeof v === "boolean") {
|
|
out[off] = v ? 1 : 0;
|
|
off += 1;
|
|
} else {
|
|
dv.setUint32(off, v.length, true);
|
|
off += 4;
|
|
out.set(v, off);
|
|
off += v.length;
|
|
}
|
|
}
|
|
return out;
|
|
}
|
|
|
|
function lowerHostPayload(payload: Uint8Array | HostRecord): Uint8Array {
|
|
return payload instanceof Uint8Array ? payload : hostRecordBytes(payload);
|
|
}
|
|
|
|
/// A host command by name; the host decides what the name means. The name is
|
|
/// a string literal. Args are scalar numbers, or exactly one bytes payload
|
|
/// (a Uint8Array, or a flat record that lowers to bytes).
|
|
function hostCmd(name: string, payload: Uint8Array | HostRecord): Cmd<never>;
|
|
function hostCmd(name: string, ...args: readonly number[]): Cmd<never>;
|
|
function hostCmd(name: string, ...rest: readonly (number | Uint8Array | HostRecord)[]): Cmd<never> {
|
|
const first = rest[0];
|
|
if (rest.length === 1 && typeof first === "object" && first !== null) {
|
|
return { op: "host_bytes", name, payload: lowerHostPayload(first) };
|
|
}
|
|
return { op: "host", name, args: rest as readonly number[] };
|
|
}
|
|
|
|
export const Cmd = {
|
|
/// No effects. `return model` is sugar for `return [model, Cmd.none]`.
|
|
none: { op: "none" } as Cmd<never>,
|
|
|
|
/// Ask the host to persist the committed model.
|
|
persist(): Cmd<never> {
|
|
return { op: "persist" };
|
|
},
|
|
|
|
/// Request the current time. The runtime dispatches the named Msg arm with
|
|
/// the timestamp (milliseconds, a plain number) as its single payload field.
|
|
now<M extends Msgish>(msgKind: TimestampKind<M>): Cmd<M> {
|
|
return { op: "now", msgKind };
|
|
},
|
|
|
|
host: hostCmd,
|
|
|
|
/// A routed host command: the host performs `name` with the payload and
|
|
/// dispatches exactly one result Msg back — the `ok` arm with the result
|
|
/// bytes, or the `err` arm with the error bytes. Both arms must carry
|
|
/// exactly one Uint8Array payload field (tsc checks that). An optional
|
|
/// `key` names the in-flight effect: re-issuing a live key replaces it,
|
|
/// and Cmd.cancel(key) drops it.
|
|
request<M extends Msgish>(
|
|
name: string,
|
|
payload: Uint8Array | HostRecord,
|
|
route: RequestRoute<M>,
|
|
): Cmd<M> {
|
|
return {
|
|
op: "request",
|
|
name,
|
|
key: route.key ?? "",
|
|
okKind: route.ok,
|
|
errKind: route.err,
|
|
payload: lowerHostPayload(payload),
|
|
};
|
|
},
|
|
|
|
/// Drop the in-flight keyed effect — request, named engine op, or delay —
|
|
/// with this key, if any, SILENTLY (neither routing arm is dispatched for
|
|
/// it). The exception is a live spawn: cancel ends the child and its err
|
|
/// arm runs with "cancelled" — killing a process is an observable event.
|
|
cancel(key: string): Cmd<never> {
|
|
return { op: "cancel", key };
|
|
},
|
|
|
|
/// Read a whole file. Exactly one terminal Msg: the `ok` arm with the
|
|
/// content bytes (one Uint8Array field), or the `err` arm with the reason
|
|
/// bytes ("not_found", "io_failed", "truncated", "rejected").
|
|
readFile<M extends Msgish>(path: Uint8Array, route: RequestRoute<M>): Cmd<M> {
|
|
return { op: "read_file", key: route.key ?? "", okKind: route.ok, errKind: route.err, path };
|
|
},
|
|
|
|
/// Write a whole file (parent directories created, an existing file
|
|
/// replaced whole). Exactly one terminal Msg: the `ok` arm — which carries
|
|
/// no payload — or the `err` arm with the reason bytes.
|
|
writeFile<M extends Msgish>(path: Uint8Array, bytes: Uint8Array, route: WriteRoute<M>): Cmd<M> {
|
|
return { op: "write_file", key: route.key ?? "", okKind: route.ok, errKind: route.err, path, bytes };
|
|
},
|
|
|
|
/// A buffered HTTP(S) exchange. Exactly one terminal Msg: the `ok` arm
|
|
/// with `{ status, body }` (one number field, one bytes field — a non-2xx
|
|
/// status is still ok: an HTTP-level error is a delivered response), or
|
|
/// the `err` arm with the reason bytes.
|
|
fetch<M extends Msgish>(spec: FetchSpec, route: FetchRoute<M>): Cmd<M> {
|
|
const names = Object.keys(spec.headers ?? {}).sort();
|
|
return {
|
|
op: "fetch",
|
|
key: route.key ?? "",
|
|
okKind: route.ok,
|
|
errKind: route.err,
|
|
method: spec.method ?? "GET",
|
|
timeoutMs: spec.timeoutMs ?? 0,
|
|
url: spec.url,
|
|
headers: names.map((n) => ({ name: n, value: spec.headers![n] })),
|
|
body: spec.body ?? new Uint8Array(0),
|
|
};
|
|
},
|
|
|
|
/// Put bytes on the system clipboard, fire-and-forget (an over-bound or
|
|
/// refused write is dropped — there is no route to report on).
|
|
clipboardWrite(bytes: Uint8Array): Cmd<never> {
|
|
return { op: "clip_write", bytes };
|
|
},
|
|
|
|
/// Read the system clipboard. Exactly one terminal Msg: the `ok` arm with
|
|
/// the text bytes, or the `err` arm with the reason bytes ("failed",
|
|
/// "rejected").
|
|
clipboardRead<M extends Msgish>(route: RequestRoute<M>): Cmd<M> {
|
|
return { op: "clip_read", key: route.key ?? "", okKind: route.ok, errKind: route.err };
|
|
},
|
|
|
|
/// A keyed one-shot delay: dispatch the named Msg arm once, `ms` from now,
|
|
/// with the fire time (milliseconds) as its single number payload field.
|
|
/// Re-issuing a live key re-arms it from now (the debounce discipline);
|
|
/// `Cmd.cancel(key)` drops it silently.
|
|
delay<M extends Msgish>(key: string, ms: number, msgKind: TimestampKind<M>): Cmd<M> {
|
|
return { op: "delay", key, afterMs: ms, msgKind };
|
|
},
|
|
|
|
/// Run a subprocess as a STREAM: each stdout line dispatches the `line`
|
|
/// arm as it arrives (line mode), or whole stdout buffers to the exit
|
|
/// (`collect: true`); exactly one terminal follows — the `exit` arm on a
|
|
/// clean exit, the `err` arm with the reason bytes on every other end.
|
|
/// The key stays live for the whole stream: `Cmd.cancel(key)` ends the
|
|
/// child mid-stream (err arm "cancelled" — loud on purpose: killing a
|
|
/// process is an observable event), and a spawn whose key is already
|
|
/// streaming is rejected, never replaced — a running subprocess is never
|
|
/// killed implicitly; cancel it first.
|
|
spawn<M extends Msgish>(
|
|
argv: readonly Uint8Array[],
|
|
route: SpawnRoute<M> | SpawnCollectRoute<M>,
|
|
): Cmd<M> {
|
|
const collect = "collect" in route && route.collect === true;
|
|
return {
|
|
op: "spawn",
|
|
key: route.key ?? "",
|
|
lineKind: collect ? "" : ((route as SpawnRoute<M>).line ?? ""),
|
|
exitKind: route.exit,
|
|
errKind: route.err,
|
|
collect,
|
|
argv,
|
|
stdin: route.stdin ?? new Uint8Array(0),
|
|
};
|
|
},
|
|
|
|
/// Open (or replace — one player is the whole surface) the keyed audio
|
|
/// event stream: resolve the source cascade (local path, then url, cached
|
|
/// and integrity-gated) and start playback. Every playback event
|
|
/// dispatches the `event` arm until `Cmd.audioStop(key)` closes the
|
|
/// stream. Failure is never silent: an unplayable source arrives as a
|
|
/// "failed" event, a refused command as "rejected".
|
|
audioPlay<M extends Msgish>(key: string, source: AudioSource, route: AudioRoute<M>): Cmd<M> {
|
|
return {
|
|
op: "audio_play",
|
|
key,
|
|
eventKind: route.event,
|
|
path: source.path ?? new Uint8Array(0),
|
|
url: source.url ?? new Uint8Array(0),
|
|
cachePath: source.cachePath ?? new Uint8Array(0),
|
|
expectedBytes: source.expectedBytes ?? 0,
|
|
};
|
|
},
|
|
|
|
/// Pause the keyed playback in place (no event echo — the caller
|
|
/// commanded it). A key with no open stream no-ops.
|
|
audioPause(key: string): Cmd<never> {
|
|
return { op: "audio_ctl", key, verb: "pause", value: 0 };
|
|
},
|
|
|
|
/// Resume the keyed playback. A player that can no longer resume reports
|
|
/// one "failed" event on the stream instead of silence.
|
|
audioResume(key: string): Cmd<never> {
|
|
return { op: "audio_ctl", key, verb: "resume", value: 0 };
|
|
},
|
|
|
|
/// Stop the keyed playback and CLOSE its event stream: no events for the
|
|
/// key after this. Stop is the audio stream's cancel.
|
|
audioStop(key: string): Cmd<never> {
|
|
return { op: "audio_ctl", key, verb: "stop", value: 0 };
|
|
},
|
|
|
|
/// Jump the keyed playback to `ms` (the platform clamps to the duration).
|
|
/// No event echo — the next position tick reports from there.
|
|
audioSeek(key: string, ms: number): Cmd<never> {
|
|
return { op: "audio_ctl", key, verb: "seek", value: ms };
|
|
},
|
|
|
|
/// Set playback volume, clamped to 0..1 and remembered across tracks: the
|
|
/// next audioPlay re-applies it.
|
|
audioSetVolume(key: string, volume: number): Cmd<never> {
|
|
return { op: "audio_ctl", key, verb: "volume", value: volume };
|
|
},
|
|
|
|
/// Several commands from one dispatch, performed in order.
|
|
batch<M extends Msgish>(cmds: readonly Cmd<M>[]): Cmd<M> {
|
|
return { op: "batch", cmds };
|
|
},
|
|
};
|
|
|
|
/// An inert subscription descriptor: recurring effects declared FROM the
|
|
/// model. An app that needs them exports `subscriptions(model): Sub<Msg>`;
|
|
/// after every commit the host reconciles the returned set against its
|
|
/// active timers by key (new key or changed interval re-arms; a missing key
|
|
/// cancels). Like Cmd, Sub values are data, legal only in that function's
|
|
/// return path (NS1025).
|
|
export type Sub<M extends Msgish> =
|
|
| { readonly op: "none" }
|
|
| { readonly op: "timer"; readonly key: string; readonly everyMs: number; readonly msgKind: string }
|
|
| { readonly op: "batch"; readonly subs: readonly Sub<M>[] };
|
|
|
|
export const Sub = {
|
|
/// No subscriptions (e.g. everything paused).
|
|
none: { op: "none" } as Sub<never>,
|
|
|
|
/// A repeating timer named by `key`, firing every `everyMs` milliseconds.
|
|
/// Each fire dispatches the named Msg arm with the current time (ms) as
|
|
/// its single number payload field.
|
|
timer<M extends Msgish>(key: string, everyMs: number, msgKind: TimestampKind<M>): Sub<M> {
|
|
return { op: "timer", key, everyMs, msgKind };
|
|
},
|
|
|
|
/// Several subscriptions at once.
|
|
batch<M extends Msgish>(subs: readonly Sub<M>[]): Sub<M> {
|
|
return { op: "batch", subs };
|
|
},
|
|
};
|