@react-x11/components 0.8.0 → 0.9.0

package/src/embed/client.ts

@@ -12,8 +12,12 @@
 // `onReady` — because core's `<foreign>` already owns the protocol
 // (react-x11#269, ntk#246): the reparent, the save set, `_XEMBED_INFO`, the
 // synthetic ConfigureNotify, and handing the client back on unmount without
-// ever destroying it.
+// ever destroying it. The one thing asked of the connection directly is
+// whether it has that protocol at all (`canHostXEmbed`), because on a backend
+// that does not, `onReady` is no evidence either way: the Cocoa backend's
+// `<foreign>` still calls it, with `windowId: undefined`.
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useApp } from 'react-x11';
 
 import { nodeProcessHost } from './host.js';
 import type { ExitInfo, ProcessHost, SpawnedProcess } from './host.js';
@@ -25,7 +29,9 @@ import type { ExitInfo, ProcessHost, SpawnedProcess } from './host.js';
  * with no terminal emulator installed, or no mpv, is an ordinary machine.
  * Both components render their `fallback` on it, the way
  * `useDesktopCalendarEvents` reports "no bus, no ical.js" rather than
- * throwing.
+ * throwing. So is an app on a react-x11 backend that cannot embed another
+ * program's window at all — the native macOS one — and `error` says which of
+ * the two it is: a `BackendUnavailableError` or an `EmbedUnsupportedError`.
  */
 export type EmbedStatus =
   'idle' | 'starting' | 'running' | 'exited' | 'unavailable';
@@ -51,6 +57,65 @@ export class BackendUnavailableError extends Error {
   }
 }
 
+/**
+ * This app cannot host another program's window at all.
+ *
+ * Embedding is XEmbed, and XEmbed is X protocol — a reparent into a
+ * container, the save set, ClientMessages — which only react-x11's X11
+ * backend has. The native macOS backend has no cross-process window
+ * embedding (react-x11 `docs/macos.md`, "What this is, and is not"), so there
+ * is no window to hand a program and nothing to spawn.
+ *
+ * `useEmbeddedClient` reports it as `status: 'unavailable'`, the status a
+ * `BackendUnavailableError` gets, and for the same reason: it is an ordinary
+ * state of a healthy app, and the component renders its `fallback`. The class
+ * is what tells the two apart, because "install xterm" is the wrong advice
+ * here.
+ */
+export class EmbedUnsupportedError extends Error {
+  constructor() {
+    super(
+      '@react-x11/components: this react-x11 backend cannot embed another ' +
+        "program's window — XEmbed needs the X11 backend, and the native " +
+        'macOS one has no cross-process window embedding at all. Pass ' +
+        '`fallback` to render something else.',
+    );
+    this.name = 'EmbedUnsupportedError';
+  }
+}
+
+/** The slice of the app `canHostXEmbed` reads. `useApp()` is the escape
+ *  hatch, so the shape is written out rather than imported — the call
+ *  `../tray-host/manager.ts` makes for the slice it needs. */
+interface XEmbedHostApp {
+  X?: { SetSelectionOwner?: unknown; ReparentWindow?: unknown } | null;
+}
+
+/**
+ * Can this app host another program's window?
+ *
+ * Asked of the connection, because `<foreign>` cannot be the one to say: on
+ * react-x11's Cocoa backend it still calls `onReady`, with an undefined
+ * `windowId`, and on the headless mock mounting one throws from the commit.
+ * The test is `<TrayHost>`'s — its
+ * manager reports `'unavailable'` when `app.X` has no `SetSelectionOwner`,
+ * which is what core's Cocoa `X` lacks (react-x11 `src/cocoa/app.js`: a stub
+ * carrying only the few requests core makes there) and what the headless
+ * mock's `X` lacks too. `ReparentWindow` is asked as well, because it is the
+ * request an embed is actually made of.
+ *
+ * Takes the app rather than calling `useApp()`, so it can be asked off the
+ * render path — of `createRoot()`'s result, before there is a tree.
+ */
+export function canHostXEmbed(app: unknown): boolean {
+  const X = (app as XEmbedHostApp | null | undefined)?.X;
+  return (
+    !!X &&
+    typeof X.SetSelectionOwner === 'function' &&
+    typeof X.ReparentWindow === 'function'
+  );
+}
+
 /** What to run, and what to do with it once it is running. */
 export interface LaunchPlan {
   /** Absolute path or a name on `PATH`. */
@@ -101,13 +166,15 @@ export interface UseEmbeddedClientOptions {
   stopSignal?: string;
   onStart?: (info: { process: SpawnedProcess; backend?: string }) => void;
   onExit?: (info: ExitInfo) => void;
-  /** Spawn failures and missing backends alike. */
+  /** Spawn failures, missing backends, and an app that cannot host an
+   *  embedded window at all (`EmbedUnsupportedError`). */
   onError?: (err: Error) => void;
 }
 
 export interface EmbeddedClient {
   status: EmbedStatus;
-  /** The last failure, including a `BackendUnavailableError`. */
+  /** The last failure, including a `BackendUnavailableError` or an
+   *  `EmbedUnsupportedError`. */
   error: Error | null;
   pid: number | null;
   /** The container window, once `<foreign>` has one. */
@@ -134,12 +201,21 @@ export interface EmbeddedClient {
  * element's props — style, focus, the `onEmbedded`/`onClientGone` handlers a
  * component may want to compose with — belong to the component, not to the
  * lifecycle.
+ *
+ * **On an app that cannot host XEmbed** (`canHostXEmbed` is false — the
+ * native macOS backend), `status` is `'unavailable'` from the first render,
+ * `error` is an `EmbedUnsupportedError`, and nothing is probed or spawned.
+ * The caller should render no `<foreign>` there either: it has no socket to
+ * be.
  */
 export function useEmbeddedClient(
   options: UseEmbeddedClientOptions,
 ): EmbeddedClient {
   const { plan, enabled = true, stopSignal = 'SIGTERM' } = options;
   const host = useMemo(() => options.host ?? nodeProcessHost(), [options.host]);
+  // Asked every render: two property reads, and an app does not change
+  // backend under a mounted tree.
+  const embeddable = canHostXEmbed(useApp());
 
   const [windowId, setWindowId] = useState<number | null>(null);
   const [status, setStatus] = useState<EmbedStatus>('idle');
@@ -158,6 +234,24 @@ export function useEmbeddedClient(
   const handlers = useRef(options);
   handlers.current = options;
 
+  // No XEmbed on this connection means no window for a program to draw into,
+  // whatever `<foreign>` reports: the Cocoa backend's calls `onReady` with an
+  // undefined `windowId`, which slipped past a `windowId === null` guard and
+  // spawned `xterm -into undefined`. So the app decides, and the lifecycle
+  // below starts nothing without it. Decided while rendering rather than in
+  // an effect, so the first commit can already be the `fallback`, and
+  // reported from an effect keyed on the error itself, so `onError` hears it
+  // once rather than once per plan. `enabled` false still means "hold off": a
+  // pane nobody can see yet reports nothing.
+  const unsupported = enabled && !embeddable;
+  const unsupportedError = useMemo(
+    () => (unsupported ? new EmbedUnsupportedError() : null),
+    [unsupported],
+  );
+  useEffect(() => {
+    if (unsupportedError) handlers.current.onError?.(unsupportedError);
+  }, [unsupportedError]);
+
   const handleReady = useCallback((info: { windowId: number }) => {
     setWindowId(info.windowId);
   }, []);
@@ -170,7 +264,7 @@ export function useEmbeddedClient(
   }, []);
 
   useEffect(() => {
-    if (!enabled || windowId === null) {
+    if (!enabled || !embeddable || windowId === null) {
       setStatus('idle');
       return undefined;
     }
@@ -271,11 +365,11 @@ export function useEmbeddedClient(
       void planned?.dispose?.();
     };
     // `plan` is the restart signal — see the note on the option.
-  }, [enabled, windowId, plan, host, stopSignal, generation]);
+  }, [enabled, embeddable, windowId, plan, host, stopSignal, generation]);
 
   return {
-    status,
-    error,
+    status: unsupported ? 'unavailable' : status,
+    error: unsupportedError ?? error,
     pid,
     windowId,
     backend,

package/src/embed/index.ts

@@ -10,6 +10,8 @@
 // other `-into WID` program should not have to copy this file to exist.
 export {
   BackendUnavailableError,
+  EmbedUnsupportedError,
+  canHostXEmbed,
   resolveBackend,
   useEmbeddedClient,
 } from './client.js';

package/src/html/node.ts

@@ -138,7 +138,9 @@ export class HtmlViewNode extends Node {
   private _cascade: Cascade | null = null;
   private _tree: BoxTree | null = null;
   private _stale: Stale = Stale.Everything;
-  private _laidOutAt = -1;
+  /** The width the document was last laid out at. Not `_laidOutAt`: core's
+   *  `Node` has a method of that name, which a field would hide. */
+  private _laidOutWidth = -1;
   private _mediaBand = -1;
   private _documentHeight = 0;
   private _documentWidth = 0;
@@ -369,7 +371,7 @@ export class HtmlViewNode extends Node {
       this._sweep();
       if (this._stale < Stale.Style) this._stale = Stale.Style;
     }
-    if (this._stale === Stale.Nothing && this._laidOutAt === target) return;
+    if (this._stale === Stale.Nothing && this._laidOutWidth === target) return;
 
     if (this._stale >= Stale.Style || !this._cascade) {
       this._restyle(target);
@@ -398,12 +400,12 @@ export class HtmlViewNode extends Node {
       });
       this._textPoints = null;
       this._pointsAreUnits = null;
-      this._laidOutAt = -1;
+      this._laidOutWidth = -1;
     }
 
     if (
       this._tree &&
-      (this._laidOutAt !== target || this._stale >= Stale.Layout)
+      (this._laidOutWidth !== target || this._stale >= Stale.Layout)
     ) {
       const result = layoutDocument(
         this._tree,
@@ -413,7 +415,7 @@ export class HtmlViewNode extends Node {
       );
       this._documentWidth = result.width;
       this._documentHeight = result.height;
-      this._laidOutAt = target;
+      this._laidOutWidth = target;
       this._reportControls();
     }
     this._stale = Stale.Nothing;

package/src/index.ts

@@ -655,7 +655,9 @@ export type {
 // a third `-into WID` wrapper should not have to reimplement it.
 export {
   BackendUnavailableError,
+  EmbedUnsupportedError,
   IpcConnectError,
+  canHostXEmbed,
   connectWhenReady,
   nodeProcessHost,
   resolveBackend,

package/src/{markdown → internal/markdown}/ast.ts

@@ -1,10 +1,15 @@
-// The markdown AST `parse.ts` produces and `index.ts` renders. Deliberately
-// small: it is the GFM constructs this component draws, not a general
-// mdast — but it is shaped so that growing it stays additive. In particular
-// `component` is the MDX direction: `ComponentBlock` is parsed and rendered
-// (docs/prd-mdx.md, M1), and `ComponentInline` is still reserved — see the
-// note on it for why the inline half needs machinery `<richtext>` does not
-// have yet.
+// The markdown AST `parse.ts` produces, `<Markdown>` renders and
+// `<RichTextEditor>` edits (it converts to and from ProseMirror nodes, and
+// `stringify.ts` writes the result back out). Deliberately small: it is the
+// GFM constructs the two components draw, not a general mdast — but it is
+// shaped so that growing it stays additive. In particular `component` is the
+// MDX direction: `ComponentBlock` is parsed and rendered (docs/prd-mdx.md,
+// M1), and `ComponentInline` is still reserved — see the note on it for why
+// the inline half needs machinery `<richtext>` does not have yet.
+//
+// It lives in `src/internal/` because two components read it: shared code no
+// app needs on its own yet, per AGENTS.md's "half-step below a shared
+// module". `<Markdown>` still re-exports the parser and the types.
 
 /** Inline content, inside a paragraph, heading, list item or table cell. */
 export type InlineNode =
@@ -56,6 +61,11 @@ export interface LinkInline {
   /** True when this was `![alt](src)` — the href is the image source. */
   image: boolean;
   children: InlineNode[];
+  /**
+   * `[text](href "title")`'s title, when there was one. `<Markdown>` renders
+   * none; the editor keeps it, so a document it saves still has it.
+   */
+  title?: string;
 }
 
 /** A hard line break (two trailing spaces, or a trailing backslash). */
@@ -144,6 +154,13 @@ export interface CodeBlock {
   type: 'code';
   /** First word of the info string, lowercased — `''` when absent. */
   lang: string;
+  /**
+   * The whole info string, trimmed — present only when it says more than
+   * `lang` does (```` ```ts title="a.ts" ````, or a language not written in
+   * lowercase), so a fence that is just a language parses to the AST it
+   * always did. The editor keeps it through a round trip.
+   */
+  info?: string;
   text: string;
   /**
    * False when the closing fence has not arrived. During streaming that is

package/src/{markdown → internal/markdown}/parse.ts

@@ -1,5 +1,8 @@
-// Markdown → AST, written for this component rather than adapted from a
-// DOM-shaped pipeline. GFM-flavoured CommonMark: headings (ATX and setext),
+// Markdown → AST, written for this package rather than adapted from a
+// DOM-shaped pipeline — shared, from `src/internal/`, because two components
+// read it: `<Markdown>` renders what it produces and `<RichTextEditor>` edits
+// it, writing it back out through `./stringify.ts`. GFM-flavoured
+// CommonMark: headings (ATX and setext),
 // paragraphs, fenced and indented code, blockquotes with lazy continuation,
 // nested ordered/bullet/task lists with the tight/loose distinction, tables,
 // thematic breaks; inline emphasis with the real flanking and rule-of-three
@@ -317,7 +320,8 @@ function parseBlocks(
       const start = i;
       const fenceIndent = fence[1].length;
       const marker = fence[2];
-      const lang = (fence[3].trim().split(/[ \t]/, 1)[0] ?? '').toLowerCase();
+      const info = fence[3].trim();
+      const lang = (info.split(/[ \t]/, 1)[0] ?? '').toLowerCase();
       const body: string[] = [];
       let closed = false;
       i += 1;
@@ -342,7 +346,19 @@ function parseBlocks(
         );
         i += 1;
       }
-      commit({ type: 'code', lang, text: body.join('\n'), closed }, start, i);
+      commit(
+        {
+          type: 'code',
+          lang,
+          // only when it says more than the language does, so a plain
+          // ```js fence parses to the AST it always did
+          ...(info !== lang ? { info } : null),
+          text: body.join('\n'),
+          closed,
+        },
+        start,
+        i,
+      );
       continue;
     }
 
@@ -607,11 +623,27 @@ function parseList(
     const contentIndent = indent + m[2].length + pad;
 
     const inner: string[] = [rest];
+    // The fence open in the item's own content, if one is. A blank line
+    // inside a fence is the code's rather than the list's: it neither ends
+    // the item nor makes the list loose — and a snippet with an empty line
+    // in it, under a numbered step, is the ordinary case.
+    // (a task item's box comes off first: `- [ ] ```js` opens a fence too)
+    let fence = fenceAfter(null, rest.replace(RE_TASK, ''));
     i += 1;
     let pendingBlanks = 0;
     while (i < n) {
       const l = lines[i];
       if (RE_BLANK.test(l)) {
+        if (fence !== null && pendingBlanks === 0) {
+          // …as long as the item goes on after it: an unclosed fence must
+          // not swallow the paragraph the list is followed by
+          let k = i + 1;
+          while (k < n && RE_BLANK.test(lines[k])) k += 1;
+          if (k < n && indentOf(lines[k]) >= contentIndent) {
+            for (; i < k; i += 1) inner.push('');
+            continue;
+          }
+        }
         pendingBlanks += 1;
         if (pendingBlanks > 1) break;
         i += 1;
@@ -623,7 +655,9 @@ function parseList(
           loose = true;
           pendingBlanks = 0;
         }
-        inner.push(l.slice(contentIndent));
+        const content = l.slice(contentIndent);
+        inner.push(content);
+        fence = fenceAfter(fence, content);
         i += 1;
         continue;
       }
@@ -666,6 +700,23 @@ function parseList(
   };
 }
 
+/**
+ * The fence still open after `line`, given the one open before it — the
+ * opening run (```` ``` ````, `~~~~`) or null. Indentation is ignored, so a
+ * fence in a list nested inside this item is seen too.
+ */
+function fenceAfter(open: string | null, line: string): string | null {
+  const m = RE_FENCE_OPEN.exec(line.trimStart());
+  if (open === null) {
+    if (!m || (m[2][0] === '`' && m[3].includes('`'))) return null;
+    return m[2];
+  }
+  if (m && m[2][0] === open[0] && m[2].length >= open.length && m[3] === '') {
+    return null;
+  }
+  return open;
+}
+
 // --- tables ----------------------------------------------------------------
 
 /** Split a row on unescaped pipes; `\|` stays literal in the cell. */
@@ -763,19 +814,45 @@ const NAMED_ENTITIES: Record<string, string> = {
   middot: '·',
 };
 
+/** The same pattern, anchored — for reading one reference at a position. */
+const RE_ENTITY_AT = new RegExp(RE_ENTITY.source, 'y');
+
+function entityText(
+  whole: string,
+  dec?: string,
+  hex?: string,
+  named?: string,
+): string {
+  if (dec) {
+    const cp = parseInt(dec, 10);
+    return cp > 0 && cp <= 0x10ffff ? String.fromCodePoint(cp) : '�';
+  }
+  if (hex) {
+    const cp = parseInt(hex, 16);
+    return cp > 0 && cp <= 0x10ffff ? String.fromCodePoint(cp) : '�';
+  }
+  return (named && NAMED_ENTITIES[named]) ?? whole;
+}
+
 function decodeEntities(text: string): string {
   if (!text.includes('&')) return text;
-  return text.replace(RE_ENTITY, (whole, dec, hex, named) => {
-    if (dec) {
-      const cp = parseInt(dec, 10);
-      return cp > 0 && cp <= 0x10ffff ? String.fromCodePoint(cp) : '�';
-    }
-    if (hex) {
-      const cp = parseInt(hex, 16);
-      return cp > 0 && cp <= 0x10ffff ? String.fromCodePoint(cp) : '�';
-    }
-    return NAMED_ENTITIES[named] ?? whole;
-  });
+  return text.replace(RE_ENTITY, entityText);
+}
+
+/** The whole character ending at `i`, surrogate pair and all — an emoji is
+ *  a symbol, and half of one is not. */
+function charBefore(text: string, i: number): string | undefined {
+  if (i <= 0) return undefined;
+  const unit = text.charCodeAt(i - 1);
+  return unit >= 0xdc00 && unit <= 0xdfff && i >= 2
+    ? text.slice(i - 2, i)
+    : text[i - 1];
+}
+
+/** The whole character starting at `i`. */
+function charAt(text: string, i: number): string | undefined {
+  const cp = text.codePointAt(i);
+  return cp === undefined ? undefined : String.fromCodePoint(cp);
 }
 
 function classify(ch: string | undefined): 'ws' | 'punct' | 'other' {
@@ -797,11 +874,14 @@ export function parseInline(
   const items: Item[] = [];
   let buf = '';
 
+  // References are decoded where they are read (below), not on the flushed
+  // buffer: `\&amp;` is an escaped ampersand followed by `amp;`, and
+  // decoding afterwards turned it back into `&`.
   const flushText = (): void => {
     if (buf.length === 0) return;
     items.push({
       kind: 'node',
-      node: { type: 'text', text: decodeEntities(buf) },
+      node: { type: 'text', text: buf },
     });
     buf = '';
   };
@@ -957,7 +1037,7 @@ export function parseInline(
       const suffix = parseLinkSuffix(text, i + 1);
       if (suffix) {
         flushText();
-        closeLink(items, openIdx, suffix.href);
+        closeLink(items, openIdx, suffix.href, suffix.title);
         i = suffix.end;
         continue;
       }
@@ -988,8 +1068,8 @@ export function parseInline(
     if (ch === '*' || ch === '_' || ch === '~') {
       let run = 1;
       while (text[i + run] === ch) run += 1;
-      const before = classify(text[i - 1]);
-      const after = classify(text[i + run]);
+      const before = classify(charBefore(text, i));
+      const after = classify(charAt(text, i + run));
       const leftFlank =
         after !== 'ws' && (after !== 'punct' || before !== 'other');
       const rightFlank =
@@ -1023,6 +1103,16 @@ export function parseInline(
       continue;
     }
 
+    if (ch === '&') {
+      RE_ENTITY_AT.lastIndex = i;
+      const ref = RE_ENTITY_AT.exec(text);
+      if (ref) {
+        buf += entityText(ref[0], ref[1], ref[2], ref[3]);
+        i += ref[0].length;
+        continue;
+      }
+    }
+
     buf += ch;
     i += 1;
   }
@@ -1072,10 +1162,12 @@ function lastBracket(items: Item[]): number {
 interface LinkSuffix {
   href: string;
   end: number;
+  title?: string;
 }
 
 /** `](dest "title")` — destination in `<>` or bare with balanced parens.
- *  The title is tolerated and dropped: nothing here renders one. */
+ *  The title is kept on the node — nothing renders one, but the editor
+ *  writes it back out. */
 function parseLinkSuffix(text: string, from: number): LinkSuffix | null {
   if (text[from] !== '(') return null;
   let i = from + 1;
@@ -1110,22 +1202,33 @@ function parseLinkSuffix(text: string, from: number): LinkSuffix | null {
   while (i < len && (text[i] === ' ' || text[i] === '\n' || text[i] === '\t'))
     i += 1;
   // an optional title in any of the three quote styles
+  let title: string | undefined;
   const q = text[i];
   if (q === '"' || q === "'" || q === '(') {
     const closer = q === '(' ? ')' : q;
     let j = i + 1;
     while (j < len && text[j] !== closer) j += 1;
     if (j >= len) return null;
+    title = decodeEntities(text.slice(i + 1, j));
     i = j + 1;
     while (i < len && (text[i] === ' ' || text[i] === '\n' || text[i] === '\t'))
       i += 1;
   }
   if (text[i] !== ')') return null;
-  return { href: decodeEntities(href), end: i + 1 };
+  return {
+    href: decodeEntities(href),
+    end: i + 1,
+    ...(title !== undefined ? { title } : null),
+  };
 }
 
 /** Fold everything after the bracket opener at `openIdx` into a link node. */
-function closeLink(items: Item[], openIdx: number, href: string | null): void {
+function closeLink(
+  items: Item[],
+  openIdx: number,
+  href: string | null,
+  title?: string,
+): void {
   const bracket = items[openIdx] as { kind: 'bracket'; image: boolean };
   const inner = items.splice(openIdx);
   inner.shift();
@@ -1133,7 +1236,14 @@ function closeLink(items: Item[], openIdx: number, href: string | null): void {
   processEmphasis(inner, href === null);
   items.push({
     kind: 'node',
-    node: { type: 'link', href, image: bracket.image, children: finish(inner) },
+    node: {
+      type: 'link',
+      href,
+      image: bracket.image,
+      children: finish(inner),
+      // only when written, so a link without one keeps its old shape
+      ...(title !== undefined ? { title } : null),
+    },
   });
 }