@react-x11/components 0.8.0 → 0.9.0

package/src/maps/types.ts

@@ -27,6 +27,28 @@ export type {
   Zoomed,
 } from './style.js';
 
+/** Which renderer draws a map — see `<Map renderer>`. */
+export type MapRenderer = 'gl' | 'retained';
+
+/**
+ * What `<Map renderer>` asks for: one of the two renderers, or `'auto'` —
+ * GL wherever this connection has direct GL, and the retained renderer
+ * everywhere else.
+ */
+export type MapRendererRequest = 'auto' | MapRenderer;
+
+/** Why a map is drawn with the renderer it is, when that is not what it
+ *  asked for. */
+export type MapRendererReason =
+  /** The connection has no direct GL — indirect GLX, or none at all —
+   *  so `useSupports('shaders')` is false. */
+  | 'no-direct-gl'
+  /** GL failed at run time: no surface, a context that would not create, a
+   *  shader that would not compile, a throw from a frame. */
+  | 'gl-failed'
+  /** `REACT_X11_MAP_RENDERER` chose it. */
+  | 'forced';
+
 /** Where a pointer event happened, in every space that could be wanted. */
 export interface MapPointerEvent {
   /** Geographic. */
@@ -45,18 +67,28 @@ export interface MapPointerEvent {
   button: number;
 }
 
-/** What one frame cost — for a performance HUD, and what
- *  `scripts/bench/maps.ts` reads. */
+/**
+ * What one frame cost — for a performance HUD, and what the benches read.
+ *
+ * The fields both renderers have are named the same; the ones only one of
+ * them has are optional, and present on that renderer's frames.
+ */
 export interface MapFrameStats {
+  /** Which renderer drew the frame. */
+  renderer: MapRenderer;
   /** Milliseconds spent rasterizing tiles into their surfaces this frame.
-   *  Bounded by `rasterBudgetMs` except for the one run that crossed it. */
+   *  Bounded by `rasterBudgetMs` except for the one run that crossed it.
+   *  Always `0` on the GL renderer, which rasterizes nothing. */
   rasterMs: number;
-  /** …and compositing them, drawing the labels, overlays and markers. */
+  /** The rest of the frame on this thread: compositing tiles and drawing
+   *  the labels, overlays and markers (retained), or issuing the frame's GL
+   *  calls and placing its labels (GL — the GPU's own time is not in it). */
   drawMs: number;
   /** Tiles the cover asked for. */
   tiles: number;
-  /** …of which were composited from their own finished surface. Under
-   *  `progressive` this also counts the half-drawn ones. */
+  /** …of which were drawn from their own data: a finished surface
+   *  (retained; under `progressive` the half-drawn ones too) or their own
+   *  geometry (GL). */
   ready: number;
   /** …and how many were drawn from a coarser ancestor instead, scaled up.
    *  What covers a hole while zooming *in*. */
@@ -64,9 +96,19 @@ export interface MapFrameStats {
   /** …and how many from their finer descendants, scaled down. What covers
    *  a hole while zooming *out*, where there is no ancestor to borrow. */
   fromDescendant: number;
-  /** Tiles still to rasterize — non-zero means the map is still sharpening
-   *  and another frame is already scheduled. */
+  /** Tiles still to rasterize (retained) or to build (GL) — non-zero means
+   *  the map is still sharpening and another frame is already scheduled. */
   pending: number;
+  /**
+   * Whether what is on screen is the previous style.
+   *
+   * True from a `mapStyle` change or `refresh()` until the swap: the new
+   * style is drawn behind the old picture — tiles, background and labels —
+   * and replaces all of it in one frame, so the map never shows the two at
+   * once. The first frame it is false again is the one that swapped. Never
+   * true under `progressive`, which shows the repaint as it happens.
+   */
+  restyling: boolean;
   /** Labels placed, and labels drawn. */
   labels: number;
   /**
@@ -77,10 +119,12 @@ export interface MapFrameStats {
    * difference is not something a user can see.
    */
   errors: number;
-  /** Bytes of rendered surfaces the cache is holding. */
+  /** Bytes of rendered surfaces the cache is holding. `0` on the GL
+   *  renderer, whose tiles are geometry — its bytes are `gl.gpuBytes`. */
   surfaceBytes: number;
   /**
-   * What this pass repainted, in device pixels, or `null` for a full one.
+   * What this pass repainted, in device pixels, or `null` for a full one —
+   * which every GL frame is.
    *
    * The number to watch when a map looks busy: a frame that is only
    * continuing a rasterization should claim almost nothing, because the
@@ -90,7 +134,8 @@ export interface MapFrameStats {
    * many frames a second reads as flashing.
    */
   damage: { x: number; y: number; width: number; height: number } | null;
-  /** What the rasterizer did, summed over the tiles drawn this frame. */
+  /** What the rasterizer did, summed over the tiles drawn this frame. All
+   *  zeros on the GL renderer. */
   draw: {
     features: number;
     vertices: number;
@@ -98,6 +143,57 @@ export interface MapFrameStats {
     culled: number;
     batches: number;
   };
+  /** GL only: what the frame cost on the GPU's side of the thread. */
+  gl?: MapGlFrameStats;
+}
+
+/** What a GL frame cost, beyond what both renderers report. */
+export interface MapGlFrameStats {
+  /** Milliseconds since the frame before — what a frame rate is made of. */
+  interval: number;
+  /** Milliseconds this thread spent issuing the frame's GL calls. */
+  cpuMs: number;
+  /** …building tiles' geometry, when the builds are on this thread. */
+  buildMs: number;
+  /** Tiles loaded and waiting for a build, and tiles still loading. */
+  building: number;
+  loading: number;
+  /** Bytes of tile geometry on the GPU. */
+  gpuBytes: number;
+  /** Segment instances drawn, every pass counted — the frame's work. */
+  instances: number;
+  drawCalls: number;
+  /** Tiles uploaded to the GPU this frame, and their bytes. */
+  uploads: number;
+  uploadBytes: number;
+  /** Whether the frame was drawn through an offscreen framebuffer — which
+   *  a surface with no stencil buffer of its own needs. */
+  offscreen: boolean;
+  /** The pyramid level the view is drawn from, and the one fully shown:
+   *  they differ while a level fades in (`levelFade`). */
+  level: number;
+  shownLevel: number;
+  /** How much of the arriving level was faded in; `0` with no fade. */
+  fade: number;
+  /** The adaptive-quality rung the frame was drawn at: `0` is everything,
+   *  higher leaves more out (`adaptive`). */
+  quality: number;
+  /** What adaptive quality predicted a moving frame would cost, in ms, or
+   *  `0` for a frame it did not price. */
+  predictedMs: number;
+  /** A settled frame's own time, drained and finished — what the cost
+   *  model learns from — or `0`. Moving frames are never timed. */
+  measuredMs: number;
+  /** Whether the camera moved within the settle window. */
+  moving: boolean;
+  /** Label anchors considered, and labels placed, this frame. */
+  labelCandidates: number;
+  labelsPlaced: number;
+  /** Milliseconds this thread spent on labels: placing them, and measuring
+   *  strings it had not measured before. */
+  labelMs: number;
+  /** Label text still waiting to be rasterized. */
+  textPending: boolean;
 }
 
 /** Options for framing a box. */
@@ -140,6 +236,11 @@ export interface MapViewProps {
    * Where tiles come from, drawn in order — a basemap, then an overlay
    * pyramid over it. Empty draws the style's background and nothing else,
    * which is what a map with only markers on it wants.
+   *
+   * Tiles are cached per source **object**, whatever its `id`: switching
+   * to another source shows only its tiles, and switching back finds the
+   * first one's still cached. So keep each source stable across renders —
+   * one made anew every render fetches every tile again every render.
    */
   sources?: readonly MapSource[];
   /** How to draw them. Defaults to {@link shortbreadStyle} in the theme's
@@ -187,11 +288,15 @@ export interface MapViewProps {
    * road casings, then roads, across a dozen frames — which is honest about
    * what the renderer is doing and does not look like a map.
    *
-   * The one thing the default costs is a transition that invalidates every
-   * surface at once: a `mapStyle` change, `refresh()`, or a display-scale
-   * change leaves no finished tile *and* no finished ancestor, so the map
-   * drops to its background colour until the new tiles land. `true` shows
-   * it repainting instead.
+   * The difference is widest at a `mapStyle` change or `refresh()`, which
+   * redraws every tile at once. By default the previous style stays on
+   * screen whole — tiles, background and labels — while the new one is
+   * drawn behind it, and the view swaps in one frame once every tile in it
+   * that has data is redrawn; a tile still loading does not hold the swap.
+   * If the view keeps moving meanwhile, the wait is bounded, and a tile not
+   * redrawn by then shows the background until it is. `true` shows the
+   * repaint instead: the new background and labels at once, and each tile
+   * as it is redrawn.
    */
   progressive?: boolean;
   /**
@@ -249,12 +354,75 @@ export interface MapViewProps {
   ref?: Ref<unknown>;
 }
 
+/**
+ * What only the GL renderer reads. Accepted by the retained renderer and
+ * ignored there, as the retained renderer's own — `progressive`,
+ * `rasterBudgetMs`, `rasterScale`, `surfaceBudget`, `batchVertices` — are
+ * ignored by GL: switching renderer is never a type error or a rewrite.
+ */
+export interface MapGlProps {
+  /**
+   * Cross-fade between pyramid levels over this many milliseconds, instead
+   * of switching to the new level's geometry in one frame. `0` (the
+   * default) switches. While a level fades in the frame is drawn twice —
+   * the level leaving, and the level arriving over it.
+   */
+  levelFade?: number;
+  /**
+   * Trade detail for frame rate while the camera moves. `true` holds each
+   * moving frame to 12 ms; `{ budgetMs }` to another budget. When the camera
+   * settles the next frame draws everything again.
+   */
+  adaptive?: boolean | { budgetMs?: number };
+  /** Build tiles' geometry on this many worker threads, so no frame pays
+   *  for a tile arriving. `0` (the default) builds on this thread, a few
+   *  milliseconds a frame. */
+  buildWorkers?: number;
+  /** Antialias polygon edges with a half-pixel line. `true` by default; the
+   *  surfaces have no multisampling, so without it an edge is a staircase. */
+  antialias?: boolean;
+  /** `'nonzero'` (the default, and the retained renderer's rule) or
+   *  `'evenodd'`, one stencil pass cheaper and wrong wherever two features
+   *  of one layer overlap. */
+  fillRule?: 'nonzero' | 'evenodd';
+  /**
+   * Raw GL after the map has drawn and before the swap, with the frame's
+   * framebuffer bound. What a test or a screenshot reads a frame back
+   * through: a capture of the window from outside does not see a GL surface
+   * on either backend.
+   */
+  onAfterDraw?: (gl: unknown, info: { width: number; height: number }) => void;
+}
+
 /** What `<Map>` takes. */
-export interface MapProps extends Omit<MapViewProps, 'ref'> {
+export interface MapProps extends Omit<MapViewProps, 'ref'>, MapGlProps {
   ref?: Ref<MapHandle>;
+  /**
+   * Which renderer draws the map: `'retained'` composites rasterized tile
+   * pictures and runs anywhere; `'gl'` draws every frame from the vector
+   * data on the GPU, and needs direct GL; `'auto'`, the default, takes GL
+   * where the connection has it and the retained renderer everywhere else.
+   * `REACT_X11_MAP_RENDERER` overrides it for every map. See the docs page's
+   * "Renderers".
+   */
+  renderer?: MapRendererRequest;
+  /** The map is drawn with a renderer other than the one it asked for, or
+   *  changed renderer: `'auto'` finding no direct GL, or GL failing at run
+   *  time. The camera and the handle carry over. */
+  onRendererChange?: (renderer: MapRenderer, reason: MapRendererReason) => void;
+  /**
+   * GL failed, on a map that asked for it by name (`renderer="gl"`). Such a
+   * map never falls back — an application that asked for GL wants to know it
+   * did not get it — so this is where it finds out; under `'auto'` a failure
+   * moves the map to the retained renderer and says so through
+   * `onRendererChange` instead.
+   */
+  onError?: (error: Error) => void;
   /** Anything absolutely positioned over the map — a legend, a control
-   *  panel. Laid out as siblings of the drawn pane rather than inside it,
-   *  because a registered element paints its children *before* its own
-   *  drawing and anything inside would be painted over. */
+   *  panel. On the retained renderer they are siblings of the drawn pane
+   *  rather than inside it, because a registered element paints its
+   *  children *before* its own drawing and anything inside would be painted
+   *  over; on GL they go inside the surface, whose children core draws
+   *  above it — opaquely on X11, so give a legend a background of its own. */
   children?: ReactNode;
 }

package/src/markdown/expressions.ts

@@ -15,7 +15,11 @@
 // in as few words as they can: do not pass `scope` alongside a document you
 // did not write.
 
-import type { BlockNode, Document, InlineNode } from './ast.js';
+import type {
+  BlockNode,
+  Document,
+  InlineNode,
+} from '../internal/markdown/ast.js';
 
 /** A compiled expression, or null if it would not compile at all. */
 type Compiled = ((...args: unknown[]) => unknown) | null;

package/src/markdown/index.ts

@@ -10,8 +10,10 @@
 // pipeline is remark → rehype → DOM with Tailwind classes — an HTML pass
 // and a DOM renderer, neither of which exists here. What was worth taking
 // was taken: its `remend` package's unterminated-markdown behaviour is
-// implemented natively by `parse.ts`, as parser tolerance rather than a
-// repair pre-pass (one pass instead of repair-then-reparse).
+// implemented natively by `src/internal/markdown/parse.ts`, as parser
+// tolerance rather than a repair pre-pass (one pass instead of
+// repair-then-reparse). The parser is shared with `<RichTextEditor>`, which
+// reads and writes the same markdown this renders.
 //
 // So: `parse.ts` → AST → this file renders `<box>` structure with one
 // `<richtext>` per run of inline text, inside one `selectable` root. During
@@ -51,7 +53,7 @@ import type {
   InlineNode,
   ListBlock,
   TableBlock,
-} from './ast.js';
+} from '../internal/markdown/ast.js';
 import {
   registerRichText,
   RICHTEXT_ELEMENT,
@@ -67,10 +69,10 @@ import {
 import type { CodeBlockLook } from '../codeblock/index.js';
 import type { Language } from '../code-language/index.js';
 
-import { parse } from './parse.js';
+import { parse } from '../internal/markdown/parse.js';
 import { evaluator, resolveExpressions } from './expressions.js';
 import type { Evaluate } from './expressions.js';
-import { SPREAD_PREFIX } from './ast.js';
+import { SPREAD_PREFIX } from '../internal/markdown/ast.js';
 import { runsOf, plainTextOf } from './spans.js';
 import type { InlineStyles } from './spans.js';
 import { useLinkClicks } from '../richtext/index.js';
@@ -85,11 +87,11 @@ export type {
   InlineNode,
   Document as MarkdownDocument,
   ParseOptions,
-} from './ast.js';
-export { SPREAD_PREFIX } from './ast.js';
-export { scanTag } from './tags.js';
-export type { ScannedTag, ScanResult } from './tags.js';
-export { parse, parseInline } from './parse.js';
+} from '../internal/markdown/ast.js';
+export { SPREAD_PREFIX } from '../internal/markdown/ast.js';
+export { scanTag } from '../internal/markdown/tags.js';
+export type { ScannedTag, ScanResult } from '../internal/markdown/tags.js';
+export { parse, parseInline } from '../internal/markdown/parse.js';
 
 const h = React.createElement;
 
@@ -190,7 +192,8 @@ export interface MarkdownProps {
    * usual case.
    *
    * Block position only: a tag on its own line(s) is a component, and one in
-   * the middle of a sentence is still text. See `ComponentInline` in ast.ts.
+   * the middle of a sentence is still text. See `ComponentInline` in
+   * src/internal/markdown/ast.ts.
    *
    * Give the map a stable identity — a new object per render defeats the
    * block cache, the same way a new `fences` map does.

package/src/markdown/spans.ts

@@ -1,7 +1,7 @@
 // Inline AST → the styled runs `<richtext>` renders. Pure: all the colour
 // and font decisions arrive in `InlineStyles`, which `index.ts` derives
 // from the theme once per render.
-import type { InlineNode } from './ast.js';
+import type { InlineNode } from '../internal/markdown/ast.js';
 import type { TextRun } from '../richtext/node.js';
 
 /** The resolved look of inline text, for one block. */

package/src/media-player/index.ts

@@ -32,12 +32,13 @@ import React, {
   useState,
 } from 'react';
 import type { ReactElement, ReactNode, Ref } from 'react';
-import { useTheme } from 'react-x11';
+import { useApp, useTheme } from 'react-x11';
 import type { ForeignProps } from 'react-x11';
 import type { Style } from 'react-x11/style';
 
 import {
   BackendUnavailableError,
+  canHostXEmbed,
   resolveBackend,
   useEmbeddedClient,
 } from '../embed/index.js';
@@ -129,10 +130,13 @@ export interface MediaPlayerProps {
   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. */
+  /** Spawn failures, control-channel failures, the `BackendUnavailableError`
+   *  for a machine with neither player installed, and the
+   *  `EmbedUnsupportedError` for a react-x11 backend that cannot embed a
+   *  player's window at all. */
   onError?: (err: Error) => void;
-  /** Rendered instead of the surface when no backend is installed. */
+  /** Rendered instead of the surface when no player is available — none
+   *  installed, or none can be embedded on this react-x11 backend. */
   fallback?: ReactNode;
   /** False holds off spawning entirely. */
   enabled?: boolean;
@@ -164,6 +168,11 @@ export interface MediaPlayerProps {
  *
  * 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.
+ *
+ * **X11 only.** Both players are embedded by window id, which is XEmbed's
+ * mechanism; on a react-x11 backend with none — the native macOS one — the
+ * player is `'unavailable'` from the first render and `fallback` shows,
+ * rather than a player spawned at a window id that does not exist.
  */
 export function MediaPlayer(props: MediaPlayerProps): ReactElement {
   const {
@@ -174,6 +183,7 @@ export function MediaPlayer(props: MediaPlayerProps): ReactElement {
     stopSignal,
   } = props;
   const theme = useTheme() as unknown as Record<string, unknown>;
+  const embeddable = canHostXEmbed(useApp());
 
   const control = useRef<PlayerControl | null>(null);
   // Bumped when a control channel opens or closes. The prop-syncing effects
@@ -358,6 +368,10 @@ export function MediaPlayer(props: MediaPlayerProps): ReactElement {
   if (client.status === 'unavailable' && props.fallback !== undefined) {
     return h(React.Fragment, null, props.fallback);
   }
+  // No XEmbed on this app, and no `fallback`: an empty box holds the layout
+  // rather than a `<foreign>` with no socket to be — see the same branch in
+  // `../terminal/index.ts`.
+  if (!embeddable) return hx('box', { style: styles });
 
   const foreign: ForeignElementProps = {
     onReady: client.handleReady,