react-x11 2.49.0 → 2.51.0

package/src/cli/dev.js

@@ -27,12 +27,26 @@
 //    missing, names them with the versions the loader is written against, and
 //    installs them with the project's own package manager when the developer
 //    says yes. Without a terminal to ask on it prints the command instead.
+//  - **It turns click-to-component on.** Alt+Click (Option+Click on macOS)
+//    opens the JSX line an element came from (docs/click-to-component.md):
+//    a development tool, and this is the command a developer runs, so it is
+//    on unless REACT_X11_CLICK_TO_COMPONENT=0 says otherwise. Set here, in
+//    the environment, because that is where the renderer reads it when the
+//    first root is made — and where a toolchain restart inherits it from.
+//  - **It connects to React DevTools** whenever `npx react-devtools` is
+//    running, before or after the app started, the way a browser with the
+//    extension does: on by default where react-devtools-core is installed,
+//    unless REACT_X11_DEVTOOLS=0. Where it is not, and a DevTools UI is
+//    listening at start, it says what to install. Prepared before React
+//    Refresh loads, because Refresh installs a stub hook where it finds none,
+//    and the backend installs none where it finds one.
 //  - **It runs the project's react-x11.** A second copy of the renderer is a
 //    second React root nobody refreshes, so a global or npx-cached
 //    `react-x11` hands over to the copy the file itself imports.
 import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import * as nodeModule from 'node:module';
+import { connect } from 'node:net';
 import { basename, dirname, extname, join, relative, resolve } from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -122,10 +136,22 @@ export async function runDev(file, options = {}) {
     return null;
   }
 
+  process.env.REACT_X11_CLICK_TO_COMPONENT ??= '1';
+  if (process.env.REACT_X11_DEVTOOLS === undefined) {
+    if (resolves('react-devtools-core')) {
+      process.env.REACT_X11_DEVTOOLS = '1';
+    } else {
+      suggestDevTools({ projectDir, log });
+    }
+  }
+  if (envFlag(process.env.REACT_X11_DEVTOOLS)) {
+    await (await import('../DevToolsIntegration.js')).prepare();
+  }
+
   // Before anything below loads: a module's source maps are read when it
   // loads, and only once this is on.
   process.setSourceMapsEnabled(true);
-  const { registerRefresh } = await import('../refresh/loader.js');
+  const { onTransform, registerRefresh } = await import('../refresh/loader.js');
   await registerRefresh();
   // The runtime patches React DevTools' global hook and then hands the
   // renderer to it, which has to happen before the first root commits.
@@ -135,6 +161,7 @@ export async function runDev(file, options = {}) {
   const ReactX11 = await import('../index.js');
   const { NOT_IN_WINDOW } = await import('../errors.js');
   const { liveApps } = await import('../trace-registry.js');
+  const { ErrorWindow, describeError } = await import('./errorwindow.js');
 
   // What `node file.jsx …args` would hand the app.
   process.argv = [process.argv[0], path, ...args];
@@ -210,19 +237,55 @@ export async function runDev(file, options = {}) {
   const title = `${basename(path)} — react-x11 dev`;
   let wrapped = false;
   let mixedNoted = false;
+  // What the error window shows: a render error took the app's tree down,
+  // and the app stays down until the next reload tries it again; a compile
+  // error is a save that did not compile, beside an app still running the
+  // module's last version. Both at once shows the compile error, which is
+  // the newer news.
+  let renderFailure = null;
+  let compileFailure = null;
+  // Set when a reload starts while a render error is showing: that reload is
+  // the one to try the app again on. Not the reload that threw — react-refresh
+  // calls the reload listeners in the same batch as the render that failed,
+  // and retrying there would only throw it a second time.
+  let retry = false;
   let root = null;
+  // Two children, always in these places: an error window opening or
+  // closing beside the app is then a sibling coming and going, and the app's
+  // state is untouched by it.
   const tree = () => {
     const app = React.createElement(App);
-    return wrapped
-      ? React.createElement('window', { ...DEV_WINDOW, title }, app)
-      : app;
+    const failure = compileFailure ?? renderFailure;
+    return React.createElement(
+      React.Fragment,
+      null,
+      renderFailure
+        ? null
+        : wrapped
+          ? React.createElement('window', { ...DEV_WINDOW, title }, app)
+          : app,
+      failure
+        ? React.createElement(ErrorWindow, {
+            failure,
+            title: `${basename(failure.filename ?? path)} — error`,
+            // Beside a running app it is a second window, whose closing is
+            // ours to answer: it goes until the next error. Standing in for
+            // the app it is the only one, and closing it ends the app.
+            onCloseRequest: renderFailure
+              ? undefined
+              : () => {
+                  compileFailure = null;
+                  render();
+                },
+          })
+        : null,
+    );
   };
   const render = () => root.render(tree());
-  const mounted = () => (root.app._rootChildren ?? []).length > 0;
 
   root = await (createRoot ?? ReactX11.createRoot)({
     onUncaughtError(error, info) {
-      if (error?.code === NOT_IN_WINDOW && !wrapped) {
+      if (error?.code === NOT_IN_WINDOW && !wrapped && !renderFailure) {
         wrapped = true;
         log(
           `${name} renders no <window>, so it is shown in one of react-x11 ` +
@@ -241,27 +304,65 @@ export async function runDev(file, options = {}) {
         );
         return;
       }
-      console.error(
-        'react-x11 dev: uncaught error' + (info?.componentStack ?? ''),
+      console.error(error);
+      const chain = describeError({
+        kind: 'render',
         error,
+        componentStack: info?.componentStack,
+      }).components;
+      // Already showing one: this came out of the error window itself, or
+      // the tree failed again before a reload — the terminal has it, and a
+      // window answering its own failure by mounting itself again would
+      // never stop.
+      if (renderFailure) return;
+      log(
+        (chain.length > 0 ? `thrown rendering ${chain.join(' › ')}. ` : '') +
+          `Fix it and save: ${name} is mounted again on the next reload.`,
       );
-      setImmediate(() => {
-        if (!mounted()) {
-          log(`fix it and save: ${name} is mounted again on the next reload.`);
-        }
-      });
+      renderFailure = {
+        kind: 'render',
+        error,
+        componentStack: info?.componentStack,
+      };
+      setImmediate(render);
     },
   });
 
-  // After a reload has re-rendered the edited components: take the dev
+  // A save that does not compile: the reload library prints it and keeps the
+  // module's last version, so this is the only place it can be shown. Before
+  // the mount, the import of the file itself throws, and the bin prints it.
+  //
+  // Every reload compiles at least the module it stops at, so this is also
+  // where a reload is first seen.
+  onTransform(({ filename, error }) => {
+    if (error) {
+      compileFailure = { kind: 'compile', error, filename };
+      setImmediate(render);
+      return;
+    }
+    if (renderFailure) retry = true;
+    if (compileFailure?.filename === filename) {
+      compileFailure = null;
+      setImmediate(render);
+    }
+  });
+
+  // After a reload: try an app an error took down again, and take the dev
   // window away from a tree that now brings its own. The other direction
   // needs nothing here — a tree that lost its window throws NOT_IN_WINDOW,
-  // and the handler above wraps it — and neither does a tree an error took
-  // down: react-refresh keeps the roots that failed, and renders them again
-  // on the next reload itself.
+  // and the handler above wraps it.
   const settle = () => {
-    if (!wrapped || !mounted()) return;
-    const { windows, drawn } = rootContent(root.app._rootChildren[0]);
+    if (renderFailure) {
+      if (!retry) return;
+      retry = false;
+      renderFailure = null;
+      render();
+      return;
+    }
+    if (!wrapped) return;
+    const devWindow = (root.app._rootChildren ?? [])[0];
+    if (!devWindow) return;
+    const { windows, drawn } = rootContent(devWindow);
     if (windows > 0 && drawn === 0) {
       wrapped = false;
       mixedNoted = false;
@@ -311,6 +412,48 @@ function rootContent(node) {
   return { windows, drawn };
 }
 
+/** Whether `specifier` resolves from react-x11, which is where it is
+ * imported from. */
+function resolves(specifier) {
+  try {
+    import.meta.resolve(specifier);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** The renderer's rule for a switch: set, and not `0`. */
+function envFlag(value) {
+  return Boolean(value) && value !== '0';
+}
+
+/**
+ * Where react-devtools-core is missing: if a DevTools UI is listening (one
+ * TCP connect, in the background, never holding the process), say what to
+ * install for the app to show up in it. Silent otherwise — no DevTools
+ * running is the usual case, not one to print about.
+ */
+function suggestDevTools({ projectDir, log }) {
+  const host = process.env.REACT_X11_DEVTOOLS_HOST || 'localhost';
+  const port = Number(process.env.REACT_X11_DEVTOOLS_PORT) || 8097;
+  const socket = connect({ host, port });
+  socket.unref();
+  socket.setTimeout(1000, () => socket.destroy());
+  socket.on('error', () => {});
+  socket.on('connect', () => {
+    socket.destroy();
+    const line = shellLine(
+      installCommand(packageManagerFor(projectDir), ['react-devtools-core']),
+    );
+    log(
+      `React DevTools is listening on ${host}:${port}, and this project ` +
+        'cannot connect to it without react-devtools-core. Install it, and ' +
+        `the next run shows up there:\n\n  ${line}\n`,
+    );
+  });
+}
+
 /** The react-x11 package `path` imports, or null when it imports none. */
 export function reactX11For(path) {
   let entry;

package/src/cli/errorwindow.js

@@ -0,0 +1,368 @@
+// The window `react-x11 dev` shows an error in: what was thrown, the source
+// around where, and the frames of the stack, each of which opens its line in
+// the editor (src/editor.js, the one click-to-component uses).
+//
+// Two kinds of error reach it. A **render** error takes the app's tree down —
+// React unmounts a root whose render threw and nothing caught — so this
+// window stands in for the app until the next save mounts it again. A
+// **compile** error is a save that did not compile: the app keeps running the
+// module's last version, and this window opens beside it until a save
+// compiles.
+//
+// Everything the window says comes out of `describeError`, which is pure, so
+// the tests can read it without rendering anything.
+import { readFileSync } from 'node:fs';
+import { relative } from 'node:path';
+import React from 'react';
+import { editorName, openInEditor, stackFrames } from '../editor.js';
+
+const h = React.createElement;
+
+/** Lines of source shown above and below the one that threw. */
+const CONTEXT_ABOVE = 3;
+const CONTEXT_BELOW = 2;
+
+function firstLine(text) {
+  const at = text.indexOf('\n');
+  return at === -1 ? text : text.slice(0, at);
+}
+
+/**
+ * The source lines around `line` (1-based) of `file`: `{ number, text, at }`
+ * each, `at` marking the one that threw. Null when the file cannot be read.
+ */
+function excerptOf(file, line) {
+  let source;
+  try {
+    source = readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+  const lines = source.split('\n');
+  if (line < 1 || line > lines.length) return null;
+  const from = Math.max(1, line - CONTEXT_ABOVE);
+  const to = Math.min(lines.length, line + CONTEXT_BELOW);
+  const excerpt = [];
+  for (let number = from; number <= to; number++) {
+    excerpt.push({
+      number,
+      // a tab is as wide as its font says, and two spaces is what an editor
+      // with a two-space indent shows
+      text: lines[number - 1].replace(/\t/g, '  ').replace(/\r$/, ''),
+      at: number === line,
+    });
+  }
+  return excerpt;
+}
+
+/**
+ * Everything the window says about one failure, as data.
+ *
+ * `failure` is `{ kind, error, filename?, componentStack? }`: `kind` is
+ * `'render'` or `'compile'`, `filename` the module that did not compile, and
+ * `componentStack` what React handed `onUncaughtError`.
+ */
+export function describeError(failure, cwd = process.cwd()) {
+  const { kind, error, filename = null, componentStack = '' } = failure;
+  const rel = (file) => relative(cwd, file) || file;
+  const message = String(error?.message ?? error);
+  const name = error?.name && error.name !== 'Error' ? error.name : 'Error';
+
+  let heading;
+  let detail = '';
+  let location = null;
+  if (kind === 'compile') {
+    // babel says `<file>: <what> (<line>:<column>)` and then draws a frame;
+    // the window draws its own from `loc`, when there is one
+    let what = firstLine(message);
+    if (filename && what.startsWith(`${filename}: `)) {
+      what = what.slice(filename.length + 2);
+    }
+    what = what.replace(/ \(\d+:\d+\)$/, '');
+    heading = `${name}: ${what}`;
+    if (filename && error?.loc?.line) {
+      location = {
+        file: filename,
+        line: error.loc.line,
+        column: (error.loc.column ?? 0) + 1,
+      };
+    } else {
+      detail = message.slice(firstLine(message).length).replace(/^\n+/, '');
+    }
+  } else {
+    heading = `${name}: ${firstLine(message)}`;
+    detail = message.slice(firstLine(message).length).replace(/^\n+/, '');
+  }
+
+  // A compile error's stack is the compiler's: where in babel the parse
+  // gave up, which says nothing about the app.
+  const all = kind === 'compile' ? [] : stackFrames(error?.stack);
+  const shown = all.filter((frame) => !frame.internal);
+  if (!location) {
+    const own = shown.find((frame) => !frame.installed) ?? shown[0];
+    if (own) {
+      location = { file: own.file, line: own.line, column: own.column };
+    }
+  }
+
+  // React's component stack, innermost first: `at Broken (…)`. Host
+  // elements are in it too; the breadcrumb is the components.
+  const components = [];
+  for (const text of String(componentStack).split('\n')) {
+    const match = text.match(/^\s*at ([A-Z][\w$.]*)/);
+    if (match) components.push(match[1]);
+  }
+
+  return {
+    kind,
+    heading,
+    detail,
+    location: location && {
+      ...location,
+      where: `${rel(location.file)}:${location.line}:${location.column}`,
+    },
+    excerpt: location ? excerptOf(location.file, location.line) : null,
+    frames: shown.map((frame) => ({
+      label: frame.functionName ?? '(anonymous)',
+      where: `${rel(frame.file)}:${frame.line}:${frame.column}`,
+      file: frame.file,
+      line: frame.line,
+      column: frame.column,
+      own: !frame.installed,
+    })),
+    hidden: all.length - shown.length,
+    components: components.reverse(),
+  };
+}
+
+const mono = { fontFamily: '$monoFamily', fontSize: 12 };
+
+/**
+ * A row that opens a source line: drawn pressed on the press and hovered
+ * under the pointer, because a click that opens another application takes a
+ * moment to show anything of its own.
+ */
+function SourceLink({ target, children }) {
+  const open = () => openInEditor(target);
+  return h(
+    'box',
+    {
+      focusable: true,
+      role: 'link',
+      onClick: open,
+      onKeyDown: (ev) => {
+        if (ev.key === 'Enter') open();
+      },
+      style: {
+        flexDirection: 'row',
+        gap: 10,
+        paddingTop: 3,
+        paddingBottom: 3,
+        paddingStart: 6,
+        paddingEnd: 6,
+        borderRadius: '$radiusSmall',
+        cursor: 'pointer',
+        ':hover': { backgroundColor: '$surfaceHover' },
+        ':active': { backgroundColor: '$surfaceActive' },
+      },
+    },
+    children,
+  );
+}
+
+function Excerpt({ excerpt, column }) {
+  const width = String(excerpt[excerpt.length - 1].number).length;
+  const rows = [];
+  for (const { number, text, at } of excerpt) {
+    rows.push(
+      h(
+        'box',
+        { key: number, style: { flexDirection: 'row' } },
+        h(
+          'text',
+          {
+            style: {
+              ...mono,
+              color: at ? '$danger' : '$textMuted',
+              textWrap: 'nowrap',
+            },
+          },
+          `${at ? '>' : ' '} ${String(number).padStart(width)} │ `,
+        ),
+        h(
+          'text',
+          {
+            style: {
+              ...mono,
+              color: at ? '$text' : '$textMuted',
+              textWrap: 'nowrap',
+              flexShrink: 1,
+            },
+          },
+          text || ' ',
+        ),
+      ),
+    );
+    if (at && column > 0) {
+      rows.push(
+        h(
+          'text',
+          {
+            key: 'caret',
+            style: { ...mono, color: '$danger', textWrap: 'nowrap' },
+          },
+          `${' '.repeat(width + 5 + column - 1)}^`,
+        ),
+      );
+    }
+  }
+  return h(
+    'box',
+    {
+      style: {
+        backgroundColor: '$surfaceHover',
+        borderRadius: '$radius',
+        paddingTop: 10,
+        paddingBottom: 10,
+        paddingStart: 12,
+        paddingEnd: 12,
+        overflow: 'hidden',
+      },
+    },
+    rows,
+  );
+}
+
+/**
+ * The window itself. `onCloseRequest` is the host's to give: without one,
+ * closing the only window there is ends the app, as closing an app's primary
+ * window does.
+ */
+export function ErrorWindow({ failure, title, onCloseRequest }) {
+  const info = describeError(failure);
+  const muted = { color: '$textMuted', fontSize: 12 };
+  const editor = editorName();
+  const children = [
+    h(
+      'text',
+      { key: 'kind', style: { ...muted, fontWeight: 600 } },
+      info.kind === 'compile'
+        ? 'This save did not compile. The app keeps running the last version that did.'
+        : 'The app threw while rendering, and React took its tree down.',
+    ),
+    h(
+      'text',
+      {
+        key: 'heading',
+        style: { color: '$danger', fontSize: 16, fontWeight: 600 },
+      },
+      info.heading,
+    ),
+  ];
+  if (info.components.length > 0) {
+    children.push(
+      h(
+        'text',
+        { key: 'components', style: muted },
+        info.components.join(' › '),
+      ),
+    );
+  }
+  if (info.detail) {
+    children.push(
+      h(
+        'text',
+        { key: 'detail', style: { ...mono, color: '$text' } },
+        info.detail,
+      ),
+    );
+  }
+  if (info.location) {
+    children.push(
+      h(
+        'box',
+        { key: 'source', style: { gap: 6 } },
+        h(
+          SourceLink,
+          { target: info.location },
+          h(
+            'text',
+            { style: { ...mono, color: '$link' } },
+            info.location.where,
+          ),
+        ),
+        info.excerpt
+          ? h(Excerpt, { excerpt: info.excerpt, column: info.location.column })
+          : null,
+      ),
+    );
+  }
+  if (info.frames.length > 0) {
+    children.push(
+      h(
+        'box',
+        { key: 'frames', style: { gap: 1 } },
+        h(
+          'text',
+          { style: { ...muted, fontWeight: 600, marginBottom: 4 } },
+          'Stack',
+        ),
+        info.frames.map((frame, i) =>
+          h(
+            SourceLink,
+            { key: i, target: frame },
+            h(
+              'text',
+              {
+                style: {
+                  ...mono,
+                  color: frame.own ? '$text' : '$textMuted',
+                  fontWeight: frame.own ? 600 : 400,
+                },
+              },
+              frame.label,
+            ),
+            h(
+              'text',
+              { style: { ...mono, color: '$textMuted', flexShrink: 1 } },
+              frame.where,
+            ),
+          ),
+        ),
+        info.hidden > 0
+          ? h(
+              'text',
+              { style: { ...muted, marginTop: 4, marginLeft: 6 } },
+              `${info.hidden} more ${info.hidden === 1 ? 'frame' : 'frames'} in React, Node and react-x11, not shown.`,
+            )
+          : null,
+      ),
+    );
+  }
+  children.push(
+    h(
+      'text',
+      { key: 'footer', style: { ...muted, marginTop: 4 } },
+      (info.kind === 'compile'
+        ? 'Fix it and save: this window goes once the file compiles. '
+        : 'Fix it and save: the app is mounted again on the next reload. ') +
+        `Click a line to open it in ${editor}` +
+        (process.env.REACT_X11_EDITOR
+          ? '.'
+          : '; REACT_X11_EDITOR names another editor.'),
+    ),
+  );
+
+  return h(
+    'window',
+    { title, width: 760, minHeight: 240, onCloseRequest },
+    h(
+      'box',
+      {
+        selectable: true,
+        style: { flexGrow: 1, padding: 20, gap: 14, overflow: 'scroll' },
+      },
+      children,
+    ),
+  );
+}

package/src/cli/index.js

@@ -17,6 +17,10 @@ Commands:
                  export is mounted, inside a window of its own when it
                  renders none; a file that mounts its own root runs as it is.
                  Arguments after the file are the app's.
+                 Alt+Click (Option+Click on macOS) an element to open its
+                 source; REACT_X11_CLICK_TO_COMPONENT=0 turns that off.
+                 Connects to React DevTools (npx react-devtools) whenever
+                 it runs; REACT_X11_DEVTOOLS=0 turns that off.
 
 Options:
   -h, --help     Show this help.

package/src/cocoa/app.js

@@ -1447,6 +1447,9 @@ export class CocoaApp {
         return this._animationEnds.get(ev.id)?.(ev);
       case 'window-live-resize':
         return this._routeLiveResize(ev);
+      case 'window-fullscreen':
+      case 'window-miniaturize':
+        return this._routeWindowState(ev);
       case 'window-created':
         // a worker's window, made on the UI thread after the call that
         // answered its handle
@@ -1611,6 +1614,8 @@ export class CocoaApp {
     // this is the only thing the bridge says about it (`_recheckScreens`).
     this._recheckScreens();
     wnd._nativeResized(ev);
+    // AppKit says nothing of a zoom but the resize it makes
+    if (ev.type === 'window-resize') wnd._refreshStates();
     wnd.emit('resize', {
       width: wnd.width,
       height: wnd.height,
@@ -1676,6 +1681,22 @@ export class CocoaApp {
     wnd.emit('liveresize', { live: wnd.liveResizing });
   }
 
+  /**
+   * `window-fullscreen { fullscreen, phase }` and `window-miniaturize`
+   * (@windowkit/appkit 0.30.0): the title bar's green button, the Dock, and
+   * the same asked for through `setWmState`. The bridge has published the
+   * state already — a full-screen transition's target from its `begin`,
+   * before the animation, which is the moment an app takes its chrome away
+   * — so the window reads it back and says `statechange` if it moved. A
+   * user's own act, so it is input: its render goes out like a click's.
+   */
+  _routeWindowState(ev) {
+    const wnd = this._window(ev);
+    if (!wnd || wnd.destroyed) return;
+    wnd._refreshStates();
+    this._afterInput();
+  }
+
   /**
    * `surface-released`: a worker's frame took an IOSurface off a layer and
    * the frame that replaced it has committed (windowkit/appkit#52). The
@@ -1759,6 +1780,7 @@ export class CocoaApp {
     const wnd = this._window(ev);
     if (!wnd) return;
     if (name === 'focus') this._lastKeyWindow = wnd;
+    wnd._refreshStates();
     wnd.emit(name, { buttons: 0, time: ev.time });
     this._afterInput();
   }

package/src/cocoa/presenter.js

@@ -502,7 +502,9 @@ export function propBoxProps(node, app, scale, parentOrigin, order) {
   const style = node.style ?? {};
   const border = typeof style.borderWidth === 'number' ? style.borderWidth : 0;
   const colour = (value) =>
-    value ? (app._parseColor(String(value)) ?? [0, 0, 0, 0]) : [0, 0, 0, 0];
+    value
+      ? (app._parseColor(String(node.resolveColor(value))) ?? [0, 0, 0, 0])
+      : [0, 0, 0, 0];
   return {
     frame: [
       (abs.x - parentOrigin.x) / scale,