@react-x11/components 0.1.0 → 0.2.1

package/src/media-player/index.ts

@@ -0,0 +1,378 @@
+// <MediaPlayer> — mpv or VLC, drawing into an element.
+//
+// The second XEmbed wrapper, and mechanically the same component as
+// `../terminal/`: a `<foreign>` with no `windowId` adopts whatever is put
+// inside it, the id `onReady` hands over is passed to the player as
+// `--wid=…`, and `../embed/` owns everything about starting, watching and
+// handing back the process.
+//
+// What makes it more than a surface is the control channel. mpv's JSON IPC
+// socket turns `volume`, `paused` and `seek()` into real commands and pushes
+// position back as it changes, so `src` can be swapped inside a running
+// player rather than by respawning one. `./backends.ts` is where that and
+// VLC's much narrower rc interface are reconciled.
+//
+// Registers no element: `<foreign>` is a built-in. Nothing here happens at
+// import time.
+//
+// ### Controls
+//
+// There are none drawn, on purpose. The player's window stacks above
+// everything drawn in ours — the same rule `<glarea>` has — so a transport bar
+// laid over the video cannot be a sibling `<box>`; it has to be a `<popup>`,
+// which is a placement and dismissal problem an app is better placed to solve
+// than a component is. What this exposes instead is the whole of the state a
+// transport bar needs (`onProgress`, `onPlayingChange`, the handle) plus
+// `osd` for the player's own overlay when a quick one will do.
+import React, {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import type { ReactElement, ReactNode, Ref } from 'react';
+import { useTheme } from 'react-x11';
+import type { ForeignProps } from 'react-x11';
+import type { Style } from 'react-x11/style';
+
+import {
+  BackendUnavailableError,
+  resolveBackend,
+  useEmbeddedClient,
+} from '../embed/index.js';
+import type {
+  EmbedStatus,
+  ExitInfo,
+  LaunchPlan,
+  PlanContext,
+  ProcessHost,
+} from '../embed/index.js';
+import { mediaBackendsFor } from './backends.js';
+import type { MediaBackendName, MediaLaunch } from './backends.js';
+import type { PlayerControl } from './control.js';
+import { hx } from './hx.js';
+
+export { MEDIA_BACKENDS, mediaBackendsFor, mpv, vlc } from './backends.js';
+export type {
+  MediaBackend,
+  MediaBackendName,
+  MediaLaunch,
+} from './backends.js';
+export type { PlayerControl, PlayerEvents } from './control.js';
+
+const h = React.createElement;
+
+/** `<foreign>`'s props as `hx` takes them. */
+type ForeignElementProps = Omit<ForeignProps, 'theme'>;
+
+/** Where playback is. */
+export interface MediaProgress {
+  /** Seconds from the start. */
+  position: number;
+  /** Seconds, or 0 before the player knows. */
+  duration: number;
+}
+
+/** What a `ref` on `<MediaPlayer>` gets. */
+export interface MediaPlayerHandle {
+  play(): void;
+  pause(): void;
+  /** Absolute position, in seconds. */
+  seek(seconds: number): void;
+  /** 0–1. */
+  setVolume(volume: number): void;
+  /** Stop playback without stopping the player: the window stays, idle. */
+  stop(): void;
+  /** Stop the player process and start a new one. */
+  restart(): void;
+  signal(signal?: string): boolean;
+  readonly pid: number | null;
+  readonly windowId: number | null;
+  readonly backend: string | null;
+  readonly status: EmbedStatus;
+  /** False under VLC — see `./vlc.ts`. `onProgress` never fires then. */
+  readonly reportsProgress: boolean;
+}
+
+export interface MediaPlayerProps {
+  /**
+   * A path or a URL. **Changing it does not restart the player** — the new
+   * source is loaded into the running one, so the window never blinks.
+   */
+  src?: string;
+  /** Which player. Default `'auto'`: mpv if it is installed, else VLC. */
+  backend?: MediaBackendName;
+  /** Start playing. Default true. */
+  autoPlay?: boolean;
+  /**
+   * Pause state, if you want to drive it. Leave it out and the player is
+   * uncontrolled — `autoPlay` decides how it starts and the handle's
+   * `play()`/`pause()` move it from there.
+   */
+  paused?: boolean;
+  /** 0–1. Default: the player's own. */
+  volume?: number;
+  muted?: boolean;
+  /** `'16:9'`, `'4:3'`. The player letterboxes inside the element's rect. */
+  aspectRatio?: string;
+  loop?: boolean;
+  /** The player's own on-screen controls. Off by default: they are drawn by
+   *  the player and will not match the app's theme. */
+  osd?: boolean;
+  /** Appended to the player's command line verbatim. */
+  extraArgs?: readonly string[];
+  /** Position and duration, as the player reports them. mpv only. */
+  onProgress?: (progress: MediaProgress) => void;
+  /** The file reached its end. Not fired for `stop()` or a new `src`. */
+  onEnded?: (info: { node: unknown }) => void;
+  onPlayingChange?: (playing: boolean) => void;
+  /** The player process ended. */
+  onExit?: (info: ExitInfo) => void;
+  /** Spawn failures, control-channel failures, and the
+   *  `BackendUnavailableError` for a machine with neither player installed. */
+  onError?: (err: Error) => void;
+  /** Rendered instead of the surface when no backend is installed. */
+  fallback?: ReactNode;
+  /** False holds off spawning entirely. */
+  enabled?: boolean;
+  /** Sent on unmount and restart. Default `SIGTERM`. */
+  stopSignal?: string;
+  /** Where the process runs. Defaults to this machine, through node. */
+  processes?: ProcessHost;
+  /** A video surface is not a control; default false, unlike `<Terminal>`. */
+  focusable?: boolean;
+  style?: Style | Style[];
+  ref?: Ref<MediaPlayerHandle>;
+  'data-testname'?: string;
+}
+
+/**
+ * A video surface.
+ *
+ * ```jsx
+ * <MediaPlayer
+ *   src={file}
+ *   aspectRatio="16:9"
+ *   volume={0.8}
+ *   style={{ flexGrow: 1 }}
+ *   onProgress={({ position, duration }) => setScrub(position / duration)}
+ *   onEnded={next}
+ *   fallback={<text>Install mpv to play video.</text>}
+ * />
+ * ```
+ *
+ * The player's window stacks above everything drawn in this one, so nothing 2D
+ * can overlap it — see "Controls" at the top of this file.
+ */
+export function MediaPlayer(props: MediaPlayerProps): ReactElement {
+  const {
+    backend = 'auto',
+    enabled = true,
+    focusable,
+    processes,
+    stopSignal,
+  } = props;
+  const theme = useTheme() as unknown as Record<string, unknown>;
+
+  const control = useRef<PlayerControl | null>(null);
+  // Bumped when a control channel opens or closes. The prop-syncing effects
+  // below depend on it, which is what makes "apply `volume` once there is
+  // something to apply it to" a dependency rather than a retry.
+  const [channel, setChannel] = useState(0);
+  // What the player was launched with, so a `src` that has not changed is not
+  // loaded a second time over the top of itself.
+  const loaded = useRef<string | undefined>(undefined);
+
+  // Read through a ref so that the plan's identity — which is the restart
+  // signal — depends only on the launch key below.
+  const latest = useRef(props);
+  latest.current = props;
+
+  // Only the props that cannot be changed in a running player. `src`,
+  // `volume`, `muted` and `paused` are all live commands, so they are
+  // deliberately absent: including them would respawn the process for a
+  // volume slider.
+  const key = useMemo(
+    () =>
+      JSON.stringify([
+        backend,
+        props.aspectRatio ?? null,
+        props.loop ?? false,
+        props.osd ?? false,
+        props.extraArgs ?? null,
+      ]),
+    [backend, props.aspectRatio, props.loop, props.osd, props.extraArgs],
+  );
+
+  const plan = useMemo(
+    () =>
+      async ({ windowId, host }: PlanContext): Promise<LaunchPlan> => {
+        const candidates = mediaBackendsFor(backend);
+        if (candidates.length === 0) {
+          throw new BackendUnavailableError('media player', [backend]);
+        }
+        const chosen = await resolveBackend(host, 'media player', candidates);
+        const scratch = await host.socketPath(
+          `react-x11-${chosen.backend.name}`,
+        );
+        const current = latest.current;
+        const launch: MediaLaunch = {
+          windowId,
+          controlPath: scratch.path,
+          src: current.src,
+          autoPlay: current.autoPlay ?? true,
+          volume: current.volume,
+          muted: current.muted,
+          aspectRatio: current.aspectRatio,
+          loop: current.loop,
+          osd: current.osd,
+          extraArgs: current.extraArgs,
+        };
+
+        return {
+          command: chosen.path,
+          args: chosen.backend.args(launch),
+          backend: chosen.backend.name,
+          async attach() {
+            const events = {
+              onProgress: (progress: MediaProgress) =>
+                latest.current.onProgress?.(progress),
+              onPlayingChange: (playing: boolean) =>
+                latest.current.onPlayingChange?.(playing),
+              onEnded: () => latest.current.onEnded?.({ node: null }),
+              onError: (err: Error) => latest.current.onError?.(err),
+            };
+            const opened = await chosen.backend.connect(
+              host,
+              scratch.path,
+              events,
+              launch,
+            );
+            control.current = opened;
+            loaded.current = launch.src;
+            setChannel((n) => n + 1);
+            return () => {
+              control.current = null;
+              loaded.current = undefined;
+              opened.dispose();
+              setChannel((n) => n + 1);
+            };
+          },
+          dispose: () => scratch.dispose(),
+        };
+      },
+    [backend, key],
+  );
+
+  const client = useEmbeddedClient({
+    plan,
+    host: processes,
+    enabled,
+    stopSignal,
+    onExit: props.onExit,
+    onError: props.onError,
+  });
+
+  // --- props the control channel applies to a running player ---------------
+
+  const { src, volume, muted, paused } = props;
+
+  useEffect(() => {
+    if (!control.current || src === undefined) return;
+    if (src === loaded.current) return;
+    loaded.current = src;
+    control.current.load(src);
+  }, [src, channel]);
+
+  useEffect(() => {
+    if (!control.current || volume === undefined) return;
+    control.current.setVolume(volume);
+  }, [volume, channel]);
+
+  useEffect(() => {
+    if (!control.current || muted === undefined) return;
+    control.current.setMuted(muted);
+  }, [muted, channel]);
+
+  useEffect(() => {
+    if (!control.current || paused === undefined) return;
+    control.current.setPaused(paused);
+  }, [paused, channel]);
+
+  // --- the handle ---------------------------------------------------------
+
+  const reportsProgress = useMemo(() => {
+    const [chosen] = mediaBackendsFor(backend).filter(
+      (b) => b.name === client.backend,
+    );
+    return chosen?.reportsProgress ?? false;
+  }, [backend, client.backend]);
+
+  const noop = useCallback(() => {}, []);
+
+  React.useImperativeHandle(
+    props.ref,
+    () => ({
+      play: () => control.current?.setPaused(false) ?? noop(),
+      pause: () => control.current?.setPaused(true) ?? noop(),
+      seek: (seconds: number) => control.current?.seek(seconds) ?? noop(),
+      setVolume: (value: number) => control.current?.setVolume(value) ?? noop(),
+      stop: () => control.current?.stop() ?? noop(),
+      restart: client.restart,
+      signal: client.signal,
+      get pid() {
+        return client.pid;
+      },
+      get windowId() {
+        return client.windowId;
+      },
+      get backend() {
+        return client.backend;
+      },
+      get status() {
+        return client.status;
+      },
+      get reportsProgress() {
+        return reportsProgress;
+      },
+    }),
+    [client, noop, reportsProgress],
+  );
+
+  // Black rather than the theme background: this is a video surface, and what
+  // shows around a letterboxed frame should be what a player would put there.
+  const style: Style = {
+    flexGrow: 1,
+    backgroundColor: String(theme.videoBackground ?? '#000000'),
+  };
+  const styles: Style[] = [style];
+  if (props.style) {
+    for (const extra of Array.isArray(props.style)
+      ? props.style
+      : [props.style]) {
+      styles.push(extra);
+    }
+  }
+
+  if (client.status === 'unavailable' && props.fallback !== undefined) {
+    return h(React.Fragment, null, props.fallback);
+  }
+
+  const foreign: ForeignElementProps = {
+    onReady: client.handleReady,
+    // A video surface is not something to tab to, and an embedded player that
+    // took the focus would swallow the app's own keys while the pointer is
+    // over it.
+    focusable: focusable ?? false,
+    'aria-label': 'Media player',
+    style: styles,
+  };
+
+  // See the same note in `../terminal/index.ts`: `data-testname` is a runtime
+  // convention react-x11's element declarations do not carry.
+  return hx('foreign', {
+    ...foreign,
+    'data-testname': props['data-testname'],
+  } as ForeignElementProps);
+}

package/src/media-player/mpv.ts

@@ -0,0 +1,146 @@
+// mpv's JSON IPC, which is what makes `<MediaPlayer>`'s props real control
+// rather than decoration.
+//
+// `--input-ipc-server=PATH` gives a unix socket that speaks newline-delimited
+// JSON in both directions: `{"command":[…]}` out, `{"event":…}` and
+// `{"request_id":…}` back. Two things it buys that a command line cannot:
+//
+//  - **`observe_property`.** Position, duration, pause state and volume are
+//    pushed as they change, so `onProgress` is an event rather than a poll.
+//  - **`loadfile … replace`.** A new `src` swaps the file inside the running
+//    player, so the embedded window never blinks and the process never has to
+//    be respawned.
+//
+// The socket is created by mpv some milliseconds *after* it starts, which is
+// what `connectWhenReady` in `../embed/host.ts` is for.
+import { connectWhenReady } from '../embed/index.js';
+import type { IpcSocket, ProcessHost } from '../embed/index.js';
+import { lineReader, unitRange } from './control.js';
+import type { PlayerControl, PlayerEvents } from './control.js';
+
+/** Observation ids. mpv echoes them back on every property-change, and they
+ *  are ours to choose. */
+const OBSERVE = {
+  position: 1,
+  duration: 2,
+  pause: 3,
+} as const;
+
+/** mpv's volume is a percentage and goes above 100 (`--volume-max`); the prop
+ *  is 0–1, so this is the whole of the conversion. */
+const VOLUME_SCALE = 100;
+
+interface MpvMessage {
+  event?: string;
+  id?: number;
+  name?: string;
+  data?: unknown;
+  reason?: string;
+  error?: string;
+}
+
+export async function connectMpv(
+  host: ProcessHost,
+  socketPath: string,
+  events: PlayerEvents,
+): Promise<PlayerControl> {
+  const socket: IpcSocket = await connectWhenReady(host, socketPath);
+
+  let position = 0;
+  let duration = 0;
+  let disposed = false;
+
+  const send = (command: readonly unknown[]): void => {
+    if (disposed) return;
+    socket.write(`${JSON.stringify({ command })}\n`);
+  };
+
+  const observe = (id: number, property: string): void => {
+    send(['observe_property', id, property]);
+  };
+
+  socket.onData(
+    lineReader((line) => {
+      let message: MpvMessage;
+      try {
+        message = JSON.parse(line) as MpvMessage;
+      } catch {
+        // mpv only ever writes JSON here; a line that is not is a version
+        // saying something we do not understand, and dropping it is right.
+        return;
+      }
+
+      if (message.event === 'property-change') {
+        if (
+          message.id === OBSERVE.position &&
+          typeof message.data === 'number'
+        ) {
+          position = message.data;
+          events.onProgress?.({ position, duration });
+        } else if (
+          message.id === OBSERVE.duration &&
+          typeof message.data === 'number'
+        ) {
+          duration = message.data;
+          events.onProgress?.({ position, duration });
+        } else if (message.id === OBSERVE.pause) {
+          events.onPlayingChange?.(message.data !== true);
+        }
+        return;
+      }
+
+      // `end-file` fires for every way a file stops, including the ones a
+      // caller must not hear as "the video finished": `stop` is our own
+      // `stop()`, and `redirect` is a playlist indirection mid-load.
+      if (message.event === 'end-file') {
+        if (message.reason === 'eof') events.onEnded?.();
+        return;
+      }
+
+      if (message.event === 'start-file') {
+        position = 0;
+        duration = 0;
+      }
+    }),
+  );
+
+  socket.onClose(() => {
+    if (disposed) return;
+    disposed = true;
+    // Not an error: mpv closing its socket is mpv exiting, which the process
+    // watch in `useEmbeddedClient` reports with an exit code.
+  });
+
+  observe(OBSERVE.position, 'time-pos');
+  observe(OBSERVE.duration, 'duration');
+  observe(OBSERVE.pause, 'pause');
+
+  return {
+    reportsProgress: true,
+    load(src) {
+      // `replace` rather than `append`: the prop names what is playing, so
+      // setting it twice must not build a playlist.
+      send(['loadfile', src, 'replace']);
+    },
+    setPaused(paused) {
+      send(['set_property', 'pause', paused]);
+    },
+    seek(seconds) {
+      if (!Number.isFinite(seconds)) return;
+      send(['seek', Math.max(0, seconds), 'absolute']);
+    },
+    setVolume(volume) {
+      send(['set_property', 'volume', unitRange(volume) * VOLUME_SCALE]);
+    },
+    setMuted(muted) {
+      send(['set_property', 'mute', muted]);
+    },
+    stop() {
+      send(['stop']);
+    },
+    dispose() {
+      disposed = true;
+      socket.close();
+    },
+  };
+}

package/src/media-player/vlc.ts

@@ -0,0 +1,97 @@
+// VLC's rc interface, used write-only — and the asymmetry is the point.
+//
+// `--extraintf rc --rc-unix=PATH` gives a unix socket that accepts the same
+// console commands VLC's `rc` module has always accepted: `play`, `pause`,
+// `stop`, `seek N`, `volume N`, `add URI`. That is enough for every control
+// `<MediaPlayer>` exposes.
+//
+// What it is *not* enough for is `onProgress`. The replies to `get_time` and
+// `get_length` are bare numbers with a `>` prompt around them, in a stream
+// that also carries unsolicited status blocks and localised text — there is no
+// request id, so a reply cannot be matched to the question that asked for it
+// except by counting, and a dropped or extra line desynchronises the count
+// permanently. Rather than ship a parser that is wrong in a way nobody
+// notices until a progress bar lies, this backend declares
+// `reportsProgress: false` and the component reports position only under mpv.
+//
+// The other consequence of not reading: `pause` in the rc protocol *toggles*.
+// So the intended state is tracked here, seeded from `autoPlay`, and
+// `setPaused` sends a toggle only when the two disagree. That is exact as long
+// as nobody else is driving the same player, which is the case for a player
+// this component spawned.
+import { connectWhenReady } from '../embed/index.js';
+import type { IpcSocket, ProcessHost } from '../embed/index.js';
+import { unitRange } from './control.js';
+import type { PlayerControl, PlayerEvents } from './control.js';
+
+/** VLC's rc `volume` takes 0–256 for 0–100%. */
+const VOLUME_SCALE = 256;
+
+export interface VlcConnectOptions {
+  /** What the player was started doing, so the toggle stays in step. */
+  paused: boolean;
+}
+
+export async function connectVlc(
+  host: ProcessHost,
+  socketPath: string,
+  events: PlayerEvents,
+  options: VlcConnectOptions,
+): Promise<PlayerControl> {
+  const socket: IpcSocket = await connectWhenReady(host, socketPath);
+
+  let paused = options.paused;
+  let volume = 1;
+  let disposed = false;
+
+  const send = (line: string): void => {
+    if (disposed) return;
+    socket.write(`${line}\n`);
+  };
+
+  // Read and discard. The stream has to be consumed — an unread socket
+  // eventually stops the writer — and nothing in it is parsed, for the reason
+  // in the file comment.
+  socket.onData(() => {});
+  socket.onClose(() => {
+    disposed = true;
+  });
+
+  return {
+    reportsProgress: false,
+    load(src) {
+      send(`add ${src}`);
+      paused = false;
+      events.onPlayingChange?.(true);
+    },
+    setPaused(next) {
+      if (next === paused) return;
+      // `pause` toggles; `play` is unambiguous, so resuming uses it and only
+      // pausing needs the toggle.
+      send(next ? 'pause' : 'play');
+      paused = next;
+      events.onPlayingChange?.(!next);
+    },
+    seek(seconds) {
+      if (!Number.isFinite(seconds)) return;
+      send(`seek ${Math.max(0, Math.round(seconds))}`);
+    },
+    setVolume(next) {
+      volume = unitRange(next);
+      send(`volume ${Math.round(volume * VOLUME_SCALE)}`);
+    },
+    setMuted(muted) {
+      // rc has no mute: 0 and back is what the command set can express.
+      send(`volume ${muted ? 0 : Math.round(volume * VOLUME_SCALE)}`);
+    },
+    stop() {
+      send('stop');
+      paused = true;
+      events.onPlayingChange?.(false);
+    },
+    dispose() {
+      disposed = true;
+      socket.close();
+    },
+  };
+}

package/src/richtext/index.ts

@@ -0,0 +1,42 @@
+// Styled text that a document can select across, as a shared module: the
+// `<richtext>` element (wrapped runs, per-run decoration, and the four text
+// accessors core's selection asks for), plus the right-click menu a
+// read-only surface offers. `<Markdown>` and `<Code>` are compositions over
+// this; an app can build its own surface from the same parts.
+//
+// The selection itself is core's since react-x11#291 — a `selectable` prop
+// on the root box, and the anchor/focus, granularity, PRIMARY, Ctrl+A/Ctrl+C
+// and the one-visible-selection rule that come with it. This module used to
+// carry all of that (a `TextSelection` controller and a `useSelectionGestures`
+// hook); both are gone, and so are the `order`/`registry`/`joiner` props the
+// element took to feed them — a copy's separators now come from the layout.
+//
+// Importing this barrel registers nothing. A component that renders
+// `<richtext>` calls `registerRichText()` at its own module scope — see
+// the note in node.ts.
+import type { Ref } from 'react';
+
+import type { RichTextProps } from './node.js';
+
+// The augmentation needs its target module resolved (same note as
+// `code-editor/index.ts`): nothing in `src/` writes JSX.
+import type {} from 'react-x11/jsx-runtime';
+
+export {
+  ELEMENT as RICHTEXT_ELEMENT,
+  registerRichText,
+  RichTextNode,
+} from './node.js';
+export type { NtkApp, RichTextProps, TextLayoutLike, TextRun } from './node.js';
+export { useSelectionMenu } from './menu.js';
+export type { SelectionMenuHandlers } from './menu.js';
+export { useLinkClicks } from './links.js';
+export type { LinkHandlers } from './links.js';
+
+declare module 'react-x11/jsx-runtime' {
+  namespace JSX {
+    interface IntrinsicElements {
+      richtext: RichTextProps & { key?: string | number; ref?: Ref<unknown> };
+    }
+  }
+}