@kumikijs/runtime 0.1.0

package/README.md

@@ -0,0 +1,20 @@
+# @kumikijs/runtime
+
+Kumiki DOM runtime — mounts compiled Kumiki apps, dispatches effects, and manages the signal graph. Part of [Kumiki](https://github.com/kage1020/Kumiki).
+
+You normally do not import this directly: the compiler embeds the runtime into generated apps. It is published so generated apps and tooling can resolve it.
+
+## Install
+
+```sh
+npm i @kumikijs/runtime
+```
+
+## Exports
+
+- `@kumikijs/runtime` — the runtime API (`mount`, `runScenario`, `smoke`, …).
+- `@kumikijs/runtime/bundle` — the prebuilt, self-contained runtime bundle as a single file, embedded verbatim into generated apps.
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,363 @@
+//#region src/scenario.d.ts
+/** One thing to do to the app. Exactly one field should be set. */
+type Action = {
+  dispatch: string;
+  payload?: Record<string, unknown>;
+} | {
+  clickText: string;
+} | {
+  click: string;
+} | {
+  fill: string;
+  value: string;
+} | {
+  choose: string;
+  value: string;
+} | {
+  navigate: string;
+};
+/** Assertions evaluated against the snapshot taken after a step. */
+type Expect = {
+  /** No runtime errors since the previous step. */noErrors?: boolean; /** Partial match against the slot state (slot name → expected value). */
+  state?: Record<string, unknown>; /** Substrings that must appear in the rendered text. */
+  domIncludes?: string[]; /** Substrings that must NOT appear in the rendered text. */
+  domExcludes?: string[];
+};
+type ScenarioStep = {
+  label?: string;
+  do?: Action;
+  expect?: Expect;
+};
+/** A scripted effect outcome, returned in order each time the effect fires. */
+type EffectScript = {
+  outcome: "ok" | "err";
+  value?: unknown;
+};
+type Scenario = {
+  steps: ScenarioStep[]; /** Per-effect queues of scripted results (keeps the loop hermetic). */
+  effects?: Record<string, EffectScript[]>; /** Default result for effects with no script. Default: { outcome: "ok", value: null }. */
+  defaultEffect?: EffectScript;
+};
+type StepResult = {
+  label?: string;
+  action?: string;
+  errors: string[];
+  emits: {
+    effect: string;
+    args: unknown[];
+  }[];
+  state: Record<string, unknown>;
+  domText: string;
+  failures: string[];
+};
+type ScenarioReport = {
+  ok: boolean;
+  steps: StepResult[];
+};
+declare function runScenario(app: AppShape, root: HTMLElement, scenario: Scenario, opts?: {
+  settleMs?: number;
+}): Promise<ScenarioReport>;
+//#endregion
+//#region src/smoke.d.ts
+type SmokePhase = "mount" | "initial-render" | "interaction" | "async";
+type SmokeIssue = {
+  phase: SmokePhase;
+  message: string; /** What triggered it, e.g. "click button[0] (\"Create issue\")". */
+  trigger?: string | undefined;
+};
+type SmokeReport = {
+  ok: boolean;
+  mounted: boolean;
+  rendered: boolean;
+  interactions: number;
+  issues: SmokeIssue[];
+};
+type SmokeOptions = {
+  /** Drive interactive elements after the initial render. Default: true. */interact?: boolean; /** Max interactive elements to exercise. Default: 40. */
+  maxInteractions?: number; /** Milliseconds to let async effects/timers settle after each step. Default: 30. */
+  settleMs?: number;
+};
+/**
+ * Mount `app` into `root`, drive its UI, and report runtime failures.
+ * Runs in any DOM environment (jsdom for CI, a real browser for the playground).
+ */
+declare function smoke(app: AppShape, root: HTMLElement, opts?: SmokeOptions): Promise<SmokeReport>;
+//#endregion
+//#region src/index.d.ts
+type RefinementCheck = (v: unknown) => boolean;
+type EventHandler = (el: Record<string, unknown>) => void;
+type TileNode = {
+  kind: "page" | "column" | "row" | "card" | "box";
+  children: TileNode[];
+  props?: TileProps;
+} | {
+  kind: "heading" | "text";
+  text: string;
+  props?: TileProps;
+} | {
+  kind: "button";
+  text: string;
+  props?: TileProps;
+  loading?: boolean;
+  disabled?: boolean;
+} | {
+  kind: "input";
+  props?: TileProps;
+  bind?: string;
+  bindPath?: string[];
+  value?: string;
+  type?: string;
+  placeholder?: string;
+  required?: boolean;
+  autoFocus?: boolean;
+  id?: string;
+} | {
+  kind: "textarea";
+  props?: TileProps;
+  bind?: string;
+  bindPath?: string[];
+  value?: string;
+  rows?: number;
+  placeholder?: string;
+  id?: string;
+} | {
+  kind: "check";
+  checked: boolean;
+  props?: TileProps;
+} | {
+  kind: "spinner";
+  props?: TileProps;
+} | {
+  kind: "skeleton";
+  props?: TileProps;
+} | {
+  kind: "form";
+  children: TileNode[];
+  props?: TileProps;
+} | {
+  kind: "label";
+  text: string;
+  props?: TileProps;
+} | {
+  kind: "link";
+  text: string;
+  to: string;
+  props?: TileProps;
+} | {
+  kind: "markdown";
+  text: string;
+  props?: TileProps;
+} | {
+  kind: "image";
+  src: string;
+  props?: TileProps;
+} | {
+  kind: "icon";
+  name: string;
+  props?: TileProps;
+} | {
+  kind: "select";
+  props?: TileProps;
+  bind?: string;
+  bindPath?: string[];
+  value?: unknown;
+  options?: Array<{
+    label: unknown;
+    value: unknown;
+  }>;
+  placeholder?: string;
+} | {
+  kind: "radio";
+  props?: TileProps;
+  group?: string;
+  value?: unknown;
+  selected?: boolean;
+} | {
+  kind: "grid" | "stack" | "region" | "scroll" | "panel" | "fieldset";
+  children: TileNode[];
+  props?: TileProps;
+} | {
+  kind: "divider";
+  props?: TileProps;
+};
+type TileProps = Record<string, unknown> & {
+  onClick?: EventHandler;
+  onSubmit?: EventHandler;
+  onChange?: EventHandler;
+  onInput?: EventHandler;
+  el?: Record<string, unknown>;
+};
+type SlotMeta = {
+  value: unknown;
+  refine?: RefinementCheck;
+  volatile?: boolean;
+};
+type ReducerSpec = {
+  name: string;
+  selector?: {
+    tile: string;
+    id?: string;
+  };
+  event: {
+    kind: "ui";
+    ev: "click" | "submit" | "change" | "input";
+  } | {
+    kind: "effect";
+    effect: string;
+    outcome: "ok" | "err";
+  } | {
+    kind: "timer";
+    intervalMs: number;
+  } | {
+    kind: "lifecycle";
+    name: string;
+  };
+  apply: (slots: Record<string, unknown>, payload: Record<string, unknown>) => {
+    slots: Record<string, unknown>;
+    emits: EmitSpec[];
+  };
+};
+type EmitSpec = {
+  effect: string;
+  args: unknown[];
+};
+type EffectSpec = {
+  name: string;
+  cap: string;
+  policy?: {
+    kind: "latest";
+  } | {
+    kind: "latest-per-key";
+    keyOf: (input: unknown) => string;
+  } | {
+    kind: "queue";
+  } | {
+    kind: "debounce";
+    ms: number;
+  } | {
+    kind: "throttle";
+    ms: number;
+  } | {
+    kind: "once";
+  };
+  invoke: (input: unknown, caps: CapabilityRegistry) => Promise<EffectResult>;
+};
+type EffectResult = {
+  kind: "ok";
+  value: unknown;
+} | {
+  kind: "err";
+  value: unknown;
+};
+type CapabilityRegistry = {
+  has(cap: string): boolean;
+};
+type RouteEntry = {
+  pattern: string; /** Returns the TileNode for this route given the current state. */
+  tile: () => TileNode;
+};
+type RedirectEntry = {
+  pattern: string;
+  redirectTo: string;
+};
+type ThemeValue = string | number | {
+  [k: string]: ThemeValue;
+};
+type Theme = {
+  [k: string]: ThemeValue;
+};
+type AppShape = {
+  slots: Record<string, SlotMeta>;
+  caps: string[];
+  reducers: ReducerSpec[];
+  effects: Record<string, EffectSpec>;
+  init: EmitSpec[];
+  routes?: Array<RouteEntry | RedirectEntry>;
+  http?: {
+    baseUrl?: string;
+    headers?: () => Record<string, string>;
+    on401?: string;
+    timeout?: number;
+  }; /** Phase 4: registered themes by name. */
+  themes?: Record<string, Theme>; /** Phase 4: selected theme name. */
+  themeName?: string | null;
+  root?: () => TileNode;
+  live?: Record<string, unknown>;
+  _rerender?: () => void;
+};
+declare function mount(app: AppShape, target: HTMLElement): {
+  dispose: () => void;
+};
+declare const _stdlib: {
+  mapSize(m: unknown): number;
+  mapKeys(m: Record<string, unknown> | undefined | null): string[];
+  mapValues(m: Record<string, unknown> | undefined | null): unknown[];
+  mapEntries(m: Record<string, unknown> | undefined | null): unknown[];
+  mapGet(m: Record<string, unknown> | undefined | null, k: string): unknown; /** Polymorphic `.get-or(default)` for Option-like values. */
+  getOr(v: unknown, fallback: unknown): unknown;
+  mapGetOr(m: Record<string, unknown> | undefined | null, k: string, def: unknown): unknown;
+  mapInsert(m: Record<string, unknown>, k: string, v: unknown): Record<string, unknown>;
+  mapRemove(m: Record<string, unknown>, k: string): Record<string, unknown>;
+  mapFilter(m: Record<string, unknown>, pred: (k: string, v: unknown) => boolean): Record<string, unknown>;
+  /**
+   * Polymorphic `.filter` dispatch — used by codegen when the receiver type
+   * isn't statically known (e.g. `m.keys.filter(...)` vs `m.filter(...)`).
+   * Arrays go through Array.prototype.filter; objects (Maps in Kumiki) fall
+   * back to the (k, v) → boolean predicate of mapFilter.
+   */
+  filter(coll: unknown, pred: (...args: unknown[]) => boolean): unknown;
+  listSize(xs: unknown[]): number;
+  listFilter<T>(xs: T[], pred: (x: T) => boolean): T[];
+  listMap<T, U>(xs: T[], fn: (x: T) => U): U[]; /** Polymorphic `.map`: over List elements, or over Option/Result Some/Ok. */
+  mapOver(coll: unknown, fn: (x: unknown) => unknown): unknown; /** Option(T).flat-map(f): Some(v) -> f(v), None -> None. f returns an Option. */
+  flatMapOption(opt: unknown, fn: (x: unknown) => unknown): unknown;
+  listSortBy<T>(xs: T[], keyOf: (x: T) => number): T[]; /** List(T).fold(init, expr): left fold with $1=acc, $2=elem. */
+  listFold<T, A>(xs: T[], init: A, fn: (acc: A, x: T) => A): A;
+  setHas(s: Record<string, true> | undefined, x: unknown): boolean;
+  setToggle(s: Record<string, true> | undefined, x: unknown): Record<string, true>;
+  add(a: unknown, b: unknown): unknown;
+  show(v: unknown): string;
+  eq(a: unknown, b: unknown): boolean;
+  freshId(): string;
+  now(): number;
+  recordCopy(rec: Record<string, unknown>, patch: Record<string, unknown>): Record<string, unknown>;
+  unwrap(opt: unknown): unknown;
+  optionGetOr(opt: unknown, def: unknown): unknown;
+  Some(v: unknown): {
+    _tag: "Some";
+    _0: unknown;
+  };
+  None: {
+    _tag: "None";
+  };
+  Ok(v: unknown): {
+    _tag: "Ok";
+    _0: unknown;
+  };
+  Err(v: unknown): {
+    _tag: "Err";
+    _0: unknown;
+  };
+  variant(tag: string, ...args: unknown[]): {
+    _tag: string;
+    [k: string]: unknown;
+  };
+  variantIs(v: unknown, tag: string): boolean; /** List(T).chunk(n) → List(List(T)). The last chunk may be shorter. */
+  listChunk(xs: unknown[] | undefined | null, n: number): unknown[]; /** List(T).zip(other) → List(Tuple(T, U)); truncates to the shorter list. */
+  listZip(a: unknown[] | undefined | null, b: unknown[] | undefined | null): unknown[]; /** Map(K,V).update(k, fn): apply fn to the current value of k, no-op if absent. */
+  mapUpdate(m: Record<string, unknown> | undefined | null, k: string, fn: (v: unknown) => unknown): Record<string, unknown>; /** Set(T).add(x). Sets are stored as `{ [String(x)]: true }`. */
+  setAdd(s: Record<string, true> | undefined | null, x: unknown): Record<string, true>; /** Set(T).union(other). */
+  setUnion(a: Record<string, true> | undefined | null, b: Record<string, true> | undefined | null): Record<string, true>; /** Set(T).intersect(other) — keys present in both. */
+  setIntersect(a: Record<string, true> | undefined | null, b: Record<string, true> | undefined | null): Record<string, true>; /** Set(T).diff(other) — keys in a not in b. */
+  setDiff(a: Record<string, true> | undefined | null, b: Record<string, true> | undefined | null): Record<string, true>; /** Option(T).or / Result(T,E).or — receiver when Some/Ok, else `other`. */
+  or(v: unknown, other: unknown): unknown; /** Result(T,E).map-err(fn) — maps the Err payload, passes Ok through unchanged. */
+  mapErr(r: unknown, fn: (e: unknown) => unknown): unknown; /** Polymorphic `.diff`: numeric magnitude (Time/Duration) or Set difference. */
+  diff(a: unknown, b: unknown): unknown;
+};
+declare const builtinEffects: {
+  storageRead(input: unknown): Promise<EffectResult>;
+  storageWrite(input: unknown): Promise<EffectResult>;
+  httpFetch(method: string, input: unknown, baseUrl: string): Promise<EffectResult>;
+};
+//#endregion
+export { type Action, AppShape, CapabilityRegistry, EffectResult, type EffectScript, EffectSpec, EmitSpec, EventHandler, type Expect, RedirectEntry, ReducerSpec, RefinementCheck, RouteEntry, type Scenario, type ScenarioReport, type ScenarioStep, SlotMeta, type SmokeIssue, type SmokeOptions, type SmokePhase, type SmokeReport, type StepResult, Theme, ThemeValue, TileNode, TileProps, _stdlib, builtinEffects, mount, runScenario, smoke };