tempestweb 0.1.0__py3-none-any.whl

tempestweb/__init__.py

@@ -0,0 +1,7 @@
+"""tempestweb — build web apps in typed Python (WASM + server modes)."""
+
+from __future__ import annotations
+
+# The root package re-exports nothing directly; import from the subpackages
+# (tempestweb.native, tempestweb.runtime, tempestweb.transports, ...) instead.
+__all__: list[str] = []

tempestweb/_client/constants.js

@@ -0,0 +1,17 @@
+// constants.js — shared client-side constants (tunables used across modules).
+//
+// Module-private values stay in their module; this file holds the few constants
+// that are shared or are worth naming/tuning in one place: gesture-recognition
+// thresholds and the virtualization stylesheet id.
+
+/** Minimum pointer travel (px) for a drag to count as a swipe. */
+export const SWIPE_MIN_PX = 30;
+
+/** Hold time (ms, with little travel) for a press to count as a long press. */
+export const LONG_PRESS_MS = 500;
+
+/** Widget type tag that opts into gesture events (tap/swipe/long_press). */
+export const GESTURE_TYPE = "GestureDetector";
+
+/** Id of the injected stylesheet that carries virtualized-list spacer heights. */
+export const VIRT_STYLE_ID = "tw-virt-styles";

tempestweb/_client/dom.js

@@ -0,0 +1,373 @@
+// dom.js — build a DOM tree from the Node IR and apply patch batches to it. W1.
+//
+// buildElement(node) turns one serialized Node into a live DOM element (recursing
+// into children); applyPatches(root, patches) mutates a tree in place. Given the
+// DOM built from node_initial.json, applying patches_all_kinds.json yields the
+// expected DOM. Patch kinds are distinguished by key presence (see transport.js):
+//   - set_props present       -> Update
+//   - node + index present     -> Insert
+//   - index only               -> Remove
+//   - order present            -> Reorder
+//   - node without index       -> Replace
+//
+// Every element carries `data-tw-key` when its Node has a key, so events.js can
+// read the originating widget key via event delegation. Verify against
+// ../tests/fixtures/ in tests/client/ (jsdom). No framework.
+
+import { styleToCss } from "./style.js";
+
+/** Attribute holding a widget's stable reconciliation key. */
+export const KEY_ATTR = "data-tw-key";
+/** Attribute holding a widget's IR type (so patches can re-key/inspect it). */
+export const TYPE_ATTR = "data-tw-type";
+
+// Each widget type maps to one HTML tag. Container-like widgets are <div>; Text is
+// an inline <span>; Button is a real <button>. Unknown types fall back to <div> so
+// a new core widget renders (as a generic box) rather than throwing.
+const TAG_BY_TYPE = Object.freeze({
+  Column: "div",
+  Row: "div",
+  Container: "div",
+  Stack: "div",
+  Text: "span",
+  Button: "button",
+  Input: "input",
+  Checkbox: "input",
+  Image: "img",
+});
+
+/**
+ * Resolve the HTML tag name for an IR widget type.
+ * @param {string} type  The widget type ("Column", "Text", "Button", ...).
+ * @returns {string}     The HTML tag name (defaults to "div").
+ */
+function tagForType(type) {
+  return TAG_BY_TYPE[type] ?? "div";
+}
+
+/**
+ * Apply a node's props to an element: style, key/type attributes and text.
+ *
+ * `content` (Text) and `label` (Button) become the element's text. The `style`
+ * prop is translated by {@link styleToCss} into the inline `style` attribute. The
+ * widget `key` and `type` are mirrored onto data attributes for event delegation.
+ *
+ * @param {HTMLElement} el      The target element.
+ * @param {string} type         The widget type.
+ * @param {?string} key         The widget key, or null.
+ * @param {Object} props        The widget props (may include `style`).
+ * @returns {void}
+ */
+function applyNodeShape(el, type, key, props) {
+  el.setAttribute(TYPE_ATTR, type);
+  if (key != null) {
+    el.setAttribute(KEY_ATTR, key);
+  } else {
+    el.removeAttribute(KEY_ATTR);
+  }
+  applyProps(el, props ?? {});
+}
+
+/**
+ * Apply a bag of props onto an element (style + text-bearing props).
+ *
+ * Used both when first building an element and by Update patches. `style` is
+ * (re)translated to CSS; `content`/`label` set the text. Other keys are widget
+ * metadata the DOM does not render and are ignored.
+ *
+ * @param {HTMLElement} el     The target element.
+ * @param {Object} props       The props to apply.
+ * @returns {void}
+ */
+function applyProps(el, props) {
+  if ("style" in props) {
+    const css = styleToCss(props.style);
+    if (css) {
+      el.style.cssText = css;
+    } else {
+      el.removeAttribute("style");
+    }
+  }
+  const type = el.getAttribute(TYPE_ATTR);
+  // Text-bearing props. A Checkbox is an <input> and cannot hold text, so its
+  // label rides as an accessible name instead of textContent.
+  if ("content" in props) {
+    el.textContent = props.content == null ? "" : String(props.content);
+  }
+  if ("label" in props) {
+    if (type === "Checkbox") {
+      el.setAttribute("aria-label", props.label == null ? "" : String(props.label));
+    } else {
+      el.textContent = props.label == null ? "" : String(props.label);
+    }
+  }
+  applyControlProps(el, type, props);
+  applyA11yProps(el, props);
+  applyLazyProps(el, type, props);
+}
+
+/**
+ * Apply accessibility props (semantics + focus) onto an element.
+ *
+ * Maps the core's renderer-agnostic a11y model to ARIA/DOM: ``semantics.label``
+ * → ``aria-label``, ``semantics.role`` → ``role``, ``semantics.hint`` →
+ * ``aria-description``; ``focus_order`` sets an explicit ``tabindex`` and
+ * ``focusable`` toggles a default one (``0`` to include, ``-1`` to exclude).
+ *
+ * @param {HTMLElement} el     The target element.
+ * @param {Object} props       The props to apply.
+ * @returns {void}
+ */
+function applyA11yProps(el, props) {
+  const sem = props.semantics;
+  if (sem != null && typeof sem === "object") {
+    if (sem.label != null) {
+      el.setAttribute("aria-label", String(sem.label));
+    }
+    if (sem.role != null) {
+      el.setAttribute("role", String(sem.role));
+    }
+    if (sem.hint != null) {
+      el.setAttribute("aria-description", String(sem.hint));
+    }
+  }
+  if (props.focus_order != null) {
+    el.setAttribute("tabindex", String(props.focus_order));
+  } else if (props.focusable === true) {
+    el.setAttribute("tabindex", "0");
+  } else if (props.focusable === false) {
+    el.setAttribute("tabindex", "-1");
+  }
+}
+
+/**
+ * Apply form-control / media props (Input, Checkbox, Image) onto an element.
+ *
+ * Maps the widget's typed props onto the right DOM property/attribute so the
+ * control is actually interactive (a real <input> holding `value`, a checkbox
+ * reflecting `checked`, an <img> pointing at `src`). No-ops for other types.
+ *
+ * @param {HTMLElement} el     The target element.
+ * @param {?string} type       The widget type (from the data-tw-type attribute).
+ * @param {Object} props       The props to apply.
+ * @returns {void}
+ */
+// Virtualized list widgets: rendered as scroll viewports whose visible window
+// the runtime slides in response to scroll events (see client/virtualize.js).
+const LAZY_TYPES = Object.freeze(["LazyColumn", "LazyRow", "LazyGrid"]);
+
+/**
+ * Mark a virtualized list element and mirror its windowing metadata to data
+ * attributes so the scroll controller can compute the visible window.
+ *
+ * @param {HTMLElement} el     The target element.
+ * @param {?string} type       The widget type.
+ * @param {Object} props       The props to apply.
+ * @returns {void}
+ */
+function applyLazyProps(el, type, props) {
+  if (type == null || !LAZY_TYPES.includes(type)) {
+    return;
+  }
+  const horizontal = type === "LazyRow";
+  // A bounded, scrollable viewport: the app's Style sets the extent (e.g.
+  // height); overflow scrolls the materialized window, and scrolling past the
+  // edge slides the window (see client/virtualize.js). min-height:0 stops a flex
+  // parent from growing the viewport to fit its content instead of scrolling.
+  el.style.overflowY = horizontal ? "hidden" : "auto";
+  el.style.overflowX = horizontal ? "auto" : "hidden";
+  el.style.minHeight = "0";
+  if ("item_count" in props && props.item_count != null) {
+    el.setAttribute("data-tw-item-count", String(props.item_count));
+  }
+  if ("window_size" in props && props.window_size != null) {
+    el.setAttribute("data-tw-window-size", String(props.window_size));
+  }
+  // window is [start, end) when slid, or null (start at 0).
+  const start = Array.isArray(props.window) ? props.window[0] : 0;
+  el.setAttribute("data-tw-window-start", String(start ?? 0));
+}
+
+function applyControlProps(el, type, props) {
+  if (type === "Input") {
+    el.setAttribute("type", props.secure ? "password" : "text");
+    if ("value" in props) {
+      el.value = props.value == null ? "" : String(props.value);
+    }
+    if ("placeholder" in props && props.placeholder != null) {
+      el.setAttribute("placeholder", String(props.placeholder));
+    }
+    if (props.max_length != null) {
+      el.setAttribute("maxlength", String(props.max_length));
+    }
+  } else if (type === "Checkbox") {
+    el.setAttribute("type", "checkbox");
+    if ("checked" in props) {
+      el.checked = Boolean(props.checked);
+    }
+  } else if (type === "Image") {
+    if ("src" in props && props.src != null) {
+      el.setAttribute("src", String(props.src));
+    }
+    if ("alt" in props && props.alt != null) {
+      el.setAttribute("alt", String(props.alt));
+    }
+  }
+}
+
+/**
+ * Build a DOM element from an IR node (recursing into its children).
+ * @param {import("./transport.js").Node} node  The serialized node.
+ * @returns {HTMLElement}                        The constructed element subtree.
+ */
+export function buildElement(node) {
+  const el = document.createElement(tagForType(node.type));
+  applyNodeShape(el, node.type, node.key ?? null, node.props ?? {});
+  for (const child of node.children ?? []) {
+    el.appendChild(buildElement(child));
+  }
+  return el;
+}
+
+/**
+ * Walk a path of child indices from `root` down to the target element.
+ * @param {HTMLElement} root      The root element.
+ * @param {number[]} path         Child indices from the root ([] = root).
+ * @returns {HTMLElement}         The element at `path`.
+ * @throws {RangeError}           If an index does not resolve to an element.
+ */
+function resolvePath(root, path) {
+  /** @type {HTMLElement} */
+  let el = root;
+  for (const index of path) {
+    const next = el.children[index];
+    if (next == null) {
+      throw new RangeError(`tempestweb: patch path out of range at index ${index}`);
+    }
+    el = /** @type {HTMLElement} */ (next);
+  }
+  return el;
+}
+
+/**
+ * Apply a single Update patch: set/unset props on the node at `path`.
+ * @param {HTMLElement} root  The root element.
+ * @param {{path:number[], set_props?:Object, unset_props?:string[]}} patch  The patch.
+ * @returns {void}
+ */
+function applyUpdate(root, patch) {
+  const el = resolvePath(root, patch.path);
+  if (patch.set_props) {
+    applyProps(el, patch.set_props);
+  }
+  for (const key of patch.unset_props ?? []) {
+    if (key === "style") {
+      el.removeAttribute("style");
+    } else if (key === "content" || key === "label") {
+      el.textContent = "";
+    }
+  }
+}
+
+/**
+ * Apply a single Insert patch: insert a new child at `index` under `path`.
+ * @param {HTMLElement} root  The root element.
+ * @param {{path:number[], index:number, node:import("./transport.js").Node}} patch
+ * @returns {void}
+ */
+function applyInsert(root, patch) {
+  const parent = resolvePath(root, patch.path);
+  const child = buildElement(patch.node);
+  const ref = parent.children[patch.index] ?? null;
+  parent.insertBefore(child, ref);
+}
+
+/**
+ * Apply a single Remove patch: remove the child at `index` under `path`.
+ * @param {HTMLElement} root  The root element.
+ * @param {{path:number[], index:number}} patch  The patch.
+ * @returns {void}
+ */
+function applyRemove(root, patch) {
+  const parent = resolvePath(root, patch.path);
+  const child = parent.children[patch.index];
+  if (child != null) {
+    parent.removeChild(child);
+  }
+}
+
+/**
+ * Apply a single Reorder patch: new child `i` = old child `order[i]`.
+ *
+ * Snapshots the current children first so indices in `order` refer to the
+ * pre-reorder positions, then re-appends them in the requested order.
+ *
+ * @param {HTMLElement} root  The root element.
+ * @param {{path:number[], order:number[]}} patch  The patch.
+ * @returns {void}
+ */
+function applyReorder(root, patch) {
+  const parent = resolvePath(root, patch.path);
+  const before = Array.from(parent.children);
+  for (const index of patch.order) {
+    const child = before[index];
+    if (child != null) {
+      parent.appendChild(child);
+    }
+  }
+}
+
+/**
+ * Apply a single Replace patch: swap the element at `path` for a fresh subtree.
+ * @param {HTMLElement} root  The root element.
+ * @param {{path:number[], node:import("./transport.js").Node}} patch  The patch.
+ * @returns {void}
+ */
+function applyReplace(root, patch) {
+  const old = resolvePath(root, patch.path);
+  const fresh = buildElement(patch.node);
+  if (old.parentNode) {
+    old.parentNode.replaceChild(fresh, old);
+  }
+}
+
+/**
+ * Classify a patch by key presence and dispatch it to the right applier.
+ * @param {HTMLElement} root                   The root element.
+ * @param {import("./transport.js").Patch} patch  The patch to apply.
+ * @returns {void}
+ * @throws {TypeError}                          If the patch shape is unrecognized.
+ */
+function applyPatch(root, patch) {
+  if ("set_props" in patch || "unset_props" in patch) {
+    applyUpdate(root, /** @type {any} */ (patch));
+  } else if ("order" in patch) {
+    applyReorder(root, /** @type {any} */ (patch));
+  } else if ("node" in patch && "index" in patch) {
+    applyInsert(root, /** @type {any} */ (patch));
+  } else if ("node" in patch) {
+    applyReplace(root, /** @type {any} */ (patch));
+  } else if ("index" in patch) {
+    applyRemove(root, /** @type {any} */ (patch));
+  } else {
+    throw new TypeError(`tempestweb: unrecognized patch shape ${JSON.stringify(patch)}`);
+  }
+}
+
+/**
+ * Apply a coalesced batch of patches to the DOM tree rooted at `root`.
+ *
+ * The reconciler coalesces a tick's mutations into one ordered list; the whole
+ * list is applied before the next frame. Patches are applied in array order — the
+ * order the core emitted them — so index-relative ops (insert/remove/reorder)
+ * stay consistent.
+ *
+ * @param {HTMLElement} root                       The mounted root element.
+ * @param {import("./transport.js").Patch[]} patches  The tick's patch batch.
+ * @returns {void}
+ */
+export function applyPatches(root, patches) {
+  for (const patch of patches) {
+    applyPatch(root, patch);
+  }
+}

tempestweb/_client/events.js

@@ -0,0 +1,205 @@
+// events.js — capture DOM events and route them through a transport.  PHASE W3.
+//
+// bindEvents(root, transport) installs delegated listeners on `root` so that a
+// click on a keyed element (e.g. a Button) calls
+//   transport.sendEvent({ type: "click", key, payload })
+// reading the widget key from the `data-tw-key` attribute set by dom.js. It maps
+// the DOM events click/input/change/submit onto the TWEvent shape in transport.js.
+// Delegation means a single listener per event type survives patch churn (children
+// are added/removed/replaced without rebinding).
+//
+// Verify in tests/client/ with a mock transport (jsdom dispatchEvent).
+
+import { GESTURE_TYPE, LONG_PRESS_MS, SWIPE_MIN_PX } from "./constants.js";
+import { KEY_ATTR, TYPE_ATTR } from "./dom.js";
+
+// The DOM event names captured and their corresponding TWEvent `type`. Identity
+// here, but kept explicit so the captured set is the contract, not "whatever fires".
+const EVENT_TYPES = Object.freeze({
+  click: "click",
+  input: "input",
+  change: "change",
+  submit: "submit",
+});
+
+/**
+ * Find the nearest ancestor-or-self element carrying a widget key.
+ *
+ * Delegation fires on the deepest target; the keyed widget may be that element or
+ * an ancestor (e.g. a click lands on text inside a keyed Button). Walks up until a
+ * `data-tw-key` is found or the delegation root is passed.
+ *
+ * @param {EventTarget|null} target  The event's target node.
+ * @param {HTMLElement} root         The delegation root (search stops above it).
+ * @returns {?string}                The widget key, or null when none is keyed.
+ */
+function keyedAncestor(target, root) {
+  let node = /** @type {Node|null} */ (target);
+  while (node != null && node.nodeType !== 1) {
+    node = node.parentNode;
+  }
+  let el = /** @type {HTMLElement|null} */ (node);
+  while (el != null) {
+    if (el.hasAttribute && el.hasAttribute(KEY_ATTR)) {
+      return el.getAttribute(KEY_ATTR);
+    }
+    if (el === root) {
+      break;
+    }
+    el = el.parentElement;
+  }
+  return null;
+}
+
+/**
+ * Find the nearest ancestor-or-self GestureDetector element (keyed + typed).
+ *
+ * @param {EventTarget|null} target  The event's target node.
+ * @param {HTMLElement} root         The delegation root.
+ * @returns {?string}                The gesture widget's key, or null.
+ */
+function gestureAncestor(target, root) {
+  let node = /** @type {Node|null} */ (target);
+  while (node != null && node.nodeType !== 1) {
+    node = node.parentNode;
+  }
+  let el = /** @type {HTMLElement|null} */ (node);
+  while (el != null) {
+    if (
+      el.getAttribute &&
+      el.getAttribute(TYPE_ATTR) === GESTURE_TYPE &&
+      el.hasAttribute(KEY_ATTR)
+    ) {
+      return el.getAttribute(KEY_ATTR);
+    }
+    if (el === root) {
+      break;
+    }
+    el = el.parentElement;
+  }
+  return null;
+}
+
+/**
+ * Classify a completed pointer interaction into a gesture TWEvent.
+ *
+ * Swipe wins when travel crosses `SWIPE_MIN_PX` (direction from the dominant
+ * axis); otherwise a hold past `LONG_PRESS_MS` is a long press, and a quick
+ * release is a tap. Coordinates are the press origin.
+ *
+ * @param {{x:number, y:number, t:number}} start  The pointerdown origin.
+ * @param {{x:number, y:number, t:number}} end    The pointerup point.
+ * @returns {{type:string, payload:Object}}        The gesture type + payload.
+ */
+function classifyGesture(start, end) {
+  const dx = Math.round(end.x - start.x);
+  const dy = Math.round(end.y - start.y);
+  const dist = Math.hypot(dx, dy);
+  if (dist >= SWIPE_MIN_PX) {
+    const horizontal = Math.abs(dx) >= Math.abs(dy);
+    const direction = horizontal
+      ? dx > 0
+        ? "right"
+        : "left"
+      : dy > 0
+        ? "down"
+        : "up";
+    return { type: "swipe", payload: { direction, dx, dy } };
+  }
+  if (end.t - start.t >= LONG_PRESS_MS) {
+    return { type: "long_press", payload: { x: Math.round(start.x), y: Math.round(start.y) } };
+  }
+  return { type: "tap", payload: { x: Math.round(start.x), y: Math.round(start.y) } };
+}
+
+/**
+ * Build the TWEvent payload for a captured DOM event.
+ *
+ * `input`/`change` carry the control's current `value`; other event types carry an
+ * empty payload (the key alone identifies the action server-side).
+ *
+ * @param {string} domType   The DOM event type ("click", "input", ...).
+ * @param {EventTarget|null} target  The event target.
+ * @returns {{value?: string}}  The TWEvent `payload` ({ value } for input/change, else {}).
+ */
+function payloadFor(domType, target) {
+  if (domType === "input" || domType === "change") {
+    const value = target && "value" in target ? target.value : undefined;
+    if (value !== undefined) {
+      return { value };
+    }
+  }
+  return {};
+}
+
+/**
+ * Bind delegated DOM event listeners on `root` that forward to the transport.
+ *
+ * One listener per captured event type is attached to `root`; each resolves the
+ * originating widget key by walking up to the nearest `data-tw-key`, and — when a
+ * keyed widget owns the event — calls `transport.sendEvent` with the TWEvent.
+ * Events on unkeyed elements are ignored (no key = nothing for Python to resolve).
+ *
+ * @param {HTMLElement} root  The mounted root element to delegate from.
+ * @param {import("./transport.js").Transport} transport  The event sink.
+ * @returns {() => void}      An unbind function that removes every listener.
+ */
+export function bindEvents(root, transport) {
+  /** @type {Array<[string, (event: Event) => void]>} */
+  const bound = [];
+  for (const domType of Object.keys(EVENT_TYPES)) {
+    /** @param {Event} event */
+    const handler = (event) => {
+      const key = keyedAncestor(event.target, root);
+      if (key == null) {
+        return;
+      }
+      transport.sendEvent({
+        type: EVENT_TYPES[domType],
+        key,
+        payload: payloadFor(domType, event.target),
+      });
+    };
+    root.addEventListener(domType, handler);
+    bound.push([domType, handler]);
+  }
+
+  // Gesture recognition: pair a pointerdown over a GestureDetector with its
+  // pointerup to emit tap / swipe / long_press. Tracked per pointerId so
+  // overlapping pointers don't clobber each other.
+  /** @type {Map<number, {key: string, x: number, y: number, t: number}>} */
+  const pending = new Map();
+  const now = () => (globalThis.performance?.now?.() ?? 0);
+
+  /** @param {PointerEvent} event */
+  const onPointerDown = (event) => {
+    const key = gestureAncestor(event.target, root);
+    if (key == null) {
+      return;
+    }
+    pending.set(event.pointerId, { key, x: event.clientX, y: event.clientY, t: now() });
+  };
+  /** @param {PointerEvent} event */
+  const onPointerUp = (event) => {
+    const start = pending.get(event.pointerId);
+    if (start === undefined) {
+      return;
+    }
+    pending.delete(event.pointerId);
+    const { type, payload } = classifyGesture(start, {
+      x: event.clientX,
+      y: event.clientY,
+      t: now(),
+    });
+    transport.sendEvent({ type, key: start.key, payload });
+  };
+  root.addEventListener("pointerdown", onPointerDown);
+  root.addEventListener("pointerup", onPointerUp);
+  bound.push(["pointerdown", onPointerDown], ["pointerup", onPointerUp]);
+
+  return () => {
+    for (const [domType, handler] of bound) {
+      root.removeEventListener(domType, handler);
+    }
+  };
+}

tempestweb/_client/livereload.js

@@ -0,0 +1,29 @@
+// livereload.js — dev-only auto-reload over Server-Sent Events.
+//
+// Injected into the served index.html by the dev server (`tempestweb dev`) and
+// NEVER bundled into a production build. It opens an EventSource to the dev
+// server's `/__livereload` endpoint; when a watched file changes the server
+// rebuilds the artifact and emits a `reload` event, and this reloads the tab so
+// the fresh bundle (Mode A) or fresh app (Mode B) takes effect.
+//
+// JSDoc-typed, pure JS, no build step — same conventions as the rest of client/.
+
+/**
+ * Connect to the dev server's livereload stream and reload on each `reload`
+ * event. The browser's EventSource reconnects automatically if the dev server
+ * restarts, so a server bounce just resumes the stream.
+ *
+ * @param {string} [url]  The SSE endpoint. Defaults to "/__livereload".
+ * @returns {EventSource}  The open EventSource (so callers can close it in tests).
+ */
+export function connectLiveReload(url = "/__livereload") {
+  const source = new EventSource(url);
+  source.addEventListener("reload", () => {
+    // A rebuild completed server-side before this event fired; reload to pick it
+    // up. location.reload() re-fetches index.html and every (cache-busted) asset.
+    globalThis.location.reload();
+  });
+  return source;
+}
+
+connectLiveReload();

tempestweb/_client/native/audio.js

@@ -0,0 +1,58 @@
+// native/audio.js — browser HTMLAudioElement glue for the N1 audio capability.
+//
+// One Audio element per channel; a new sound on a channel replaces the previous.
+// Browsers block autoplay until the first user gesture — a blocked play resolves
+// `{ played:false, blocked:true }` instead of throwing (graceful degradation).
+
+import { CapabilityError } from "./index.js";
+
+/** @type {Map<string, HTMLAudioElement>} per-channel players. */
+const players = new Map();
+
+/**
+ * Play a short sound on a channel.
+ * @param {{src:string,volume:number,channel:string}} args
+ * @param {import("./index.js").NativeDeps} deps
+ * @returns {Promise<{played:boolean,blocked:boolean,channel:string}>}
+ */
+export async function audioPlay(args, deps) {
+  const channel = args.channel || "default";
+  const AudioCtor = deps.Audio || /** @type {any} */ (globalThis).Audio;
+  if (!AudioCtor) throw new CapabilityError("unavailable", "Audio is not available");
+
+  const previous = players.get(channel);
+  if (previous) {
+    previous.pause();
+  }
+  const el = new AudioCtor(args.src);
+  el.volume = typeof args.volume === "number" ? args.volume : 1.0;
+  players.set(channel, el);
+
+  try {
+    const maybe = el.play();
+    if (maybe && typeof maybe.then === "function") await maybe;
+    return { played: true, blocked: false, channel };
+  } catch {
+    // NotAllowedError (autoplay blocked) is normal before a user gesture.
+    return { played: false, blocked: true, channel };
+  }
+}
+
+/**
+ * Stop and reset playback on a channel.
+ * @param {{channel:string}} args
+ * @returns {Promise<Object>}
+ */
+export async function audioStop(args) {
+  const channel = args.channel || "default";
+  const el = players.get(channel);
+  if (el) {
+    el.pause();
+    try {
+      el.currentTime = 0;
+    } catch {
+      // jsdom Audio may not implement currentTime; ignore.
+    }
+  }
+  return {};
+}