react-x11 2.15.3 → 2.16.0

package/src/icontheme.js

@@ -0,0 +1,240 @@
+// The freedesktop icon theme: an icon found by name the way the Icon Theme
+// Specification finds it, for a symbol drawn inside a window on Linux (#591).
+//
+// A theme is a directory of the same name under any of the base directories
+// — `~/.icons`, `$XDG_DATA_HOME/icons`, each `$XDG_DATA_DIRS/icons` — with an
+// `index.theme` saying which of its subdirectories hold which sizes and which
+// themes it inherits from. A lookup tries the user's theme, then everything
+// it inherits, then `hicolor`, the theme every other one falls back on, and
+// last the loose files in `/usr/share/pixmaps`. Inside a theme it takes the
+// first directory whose size matches, and failing that the closest one.
+//
+// The directories are listed rather than probed file by file: one `readdir`
+// per directory, once, answers every name looked up there afterwards, where
+// a `stat` per name per directory per theme is thousands of calls for a
+// toolbar. Both run synchronously, since a layout pass cannot wait — the
+// first lookup in a theme pays for the listing, and later ones are a `Map`.
+
+import * as nodeFs from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/** The formats a lookup answers with, in the specification's order. XPM is
+ *  left out: nothing here decodes it. */
+const EXTENSIONS = ['png', 'svg'];
+
+/** Every base directory the specification searches, in its order. */
+export function iconBaseDirs(env = process.env, home = homedir()) {
+  const dataHome = env.XDG_DATA_HOME || join(home, '.local', 'share');
+  const dataDirs = (env.XDG_DATA_DIRS || '/usr/local/share:/usr/share')
+    .split(':')
+    .filter(Boolean);
+  return [
+    join(home, '.icons'),
+    join(dataHome, 'icons'),
+    ...dataDirs.map((dir) => join(dir, 'icons')),
+  ];
+}
+
+/** Where loose icons with no theme live, searched last. */
+export const PIXMAP_DIRS = ['/usr/share/pixmaps'];
+
+/**
+ * `index.theme`'s keys, section by section — the desktop-entry format, which
+ * is an INI file with `#` comments. Values stay strings.
+ */
+export function parseIndexTheme(text) {
+  const sections = new Map();
+  let current = null;
+  for (const raw of String(text).split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#')) continue;
+    const header = /^\[(.+)\]$/.exec(line);
+    if (header) {
+      current = new Map();
+      sections.set(header[1], current);
+      continue;
+    }
+    const eq = line.indexOf('=');
+    if (current && eq > 0) {
+      current.set(line.slice(0, eq).trim(), line.slice(eq + 1).trim());
+    }
+  }
+  return sections;
+}
+
+const list = (value) =>
+  (value ?? '')
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+
+const int = (value, fallback) => {
+  const n = Number.parseInt(value, 10);
+  return Number.isFinite(n) ? n : fallback;
+};
+
+/** One subdirectory's size rules, with the specification's defaults. */
+function directoryRules(keys) {
+  const size = int(keys?.get('Size'), 0);
+  return {
+    size,
+    scale: int(keys?.get('Scale'), 1),
+    type: keys?.get('Type') ?? 'Threshold',
+    minSize: int(keys?.get('MinSize'), size),
+    maxSize: int(keys?.get('MaxSize'), size),
+    threshold: int(keys?.get('Threshold'), 2),
+  };
+}
+
+/** The specification's DirectoryMatchesSize. */
+function matchesSize(dir, size, scale) {
+  if (dir.scale !== scale) return false;
+  if (dir.type === 'Fixed') return dir.size === size;
+  if (dir.type === 'Scalable')
+    return dir.minSize <= size && size <= dir.maxSize;
+  return dir.size - dir.threshold <= size && size <= dir.size + dir.threshold;
+}
+
+/** The specification's DirectorySizeDistance, with its Threshold branch's
+ *  typos read as what they mean: the threshold's bounds, times the scale. */
+function sizeDistance(dir, size, scale) {
+  const want = size * scale;
+  if (dir.type === 'Fixed') return Math.abs(dir.size * dir.scale - want);
+  const low = dir.type === 'Scalable' ? dir.minSize : dir.size - dir.threshold;
+  const high = dir.type === 'Scalable' ? dir.maxSize : dir.size + dir.threshold;
+  if (want < low * dir.scale) return low * dir.scale - want;
+  if (want > high * dir.scale) return want - high * dir.scale;
+  return 0;
+}
+
+/**
+ * Icon lookup in one theme and everything under it. `find(name, size,
+ * scale)` answers an absolute path, or null.
+ */
+export class IconTheme {
+  constructor({
+    theme = 'hicolor',
+    baseDirs = iconBaseDirs(),
+    pixmapDirs = PIXMAP_DIRS,
+    fs = nodeFs,
+  } = {}) {
+    this.theme = theme;
+    this.baseDirs = baseDirs;
+    this.pixmapDirs = pixmapDirs;
+    this.fs = fs;
+    this._themes = new Map(); // name -> { dirs, inherits } | null
+    this._listings = new Map(); // absolute dir -> Set of file names | null
+    this._found = new Map(); // name|size|scale -> path | null
+  }
+
+  find(name, size, scale = 1) {
+    const key = `${name}\u0000${size}\u0000${scale}`;
+    if (this._found.has(key)) return this._found.get(key);
+    const path =
+      this._inTheme(name, size, scale, this.theme, new Set()) ??
+      (this.theme === 'hicolor'
+        ? null
+        : this._inTheme(name, size, scale, 'hicolor', new Set())) ??
+      this._loose(name);
+    this._found.set(key, path);
+    return path;
+  }
+
+  /** FindIconHelper: this theme, then the ones it inherits, depth first. */
+  _inTheme(name, size, scale, theme, seen) {
+    if (seen.has(theme)) return null;
+    seen.add(theme);
+    const index = this._index(theme);
+    if (!index) return null;
+    const found = this._lookup(name, size, scale, theme, index);
+    if (found) return found;
+    for (const parent of index.inherits) {
+      const inherited = this._inTheme(name, size, scale, parent, seen);
+      if (inherited) return inherited;
+    }
+    return null;
+  }
+
+  /** LookupIcon: a directory of the right size, else the closest one. */
+  _lookup(name, size, scale, theme, index) {
+    let closest = null;
+    let distance = Infinity;
+    for (const dir of index.dirs) {
+      const fits = matchesSize(dir.rules, size, scale);
+      const d = fits ? 0 : sizeDistance(dir.rules, size, scale);
+      if (!fits && d >= distance) continue;
+      for (const base of this.baseDirs) {
+        const at = join(base, theme, dir.path);
+        const file = this._fileIn(at, name);
+        if (!file) continue;
+        if (fits) return file;
+        closest = file;
+        distance = d;
+        break;
+      }
+    }
+    return closest;
+  }
+
+  /** The loose files: an icon with no theme at all. */
+  _loose(name) {
+    for (const dir of this.pixmapDirs) {
+      const file = this._fileIn(dir, name);
+      if (file) return file;
+    }
+    return null;
+  }
+
+  _fileIn(dir, name) {
+    const names = this._listing(dir);
+    if (!names) return null;
+    for (const ext of EXTENSIONS) {
+      const file = `${name}.${ext}`;
+      if (names.has(file)) return join(dir, file);
+    }
+    return null;
+  }
+
+  _listing(dir) {
+    if (this._listings.has(dir)) return this._listings.get(dir);
+    let names = null;
+    try {
+      names = new Set(this.fs.readdirSync(dir));
+    } catch {
+      // not there, which is most directories in most base directories
+    }
+    this._listings.set(dir, names);
+    return names;
+  }
+
+  /** A theme's `index.theme`, from the first base directory that has one. */
+  _index(theme) {
+    if (this._themes.has(theme)) return this._themes.get(theme);
+    let index = null;
+    for (const base of this.baseDirs) {
+      let text;
+      try {
+        text = this.fs.readFileSync(join(base, theme, 'index.theme'), 'utf8');
+      } catch {
+        continue;
+      }
+      const sections = parseIndexTheme(text);
+      const head = sections.get('Icon Theme');
+      const names = [
+        ...list(head?.get('Directories')),
+        ...list(head?.get('ScaledDirectories')),
+      ];
+      index = {
+        inherits: list(head?.get('Inherits')),
+        dirs: [...new Set(names)].map((path) => ({
+          path,
+          rules: directoryRules(sections.get(path)),
+        })),
+      };
+      break;
+    }
+    this._themes.set(theme, index);
+    return index;
+  }
+}

package/src/imagesource.js

@@ -44,6 +44,73 @@ export function isPathImageSource(src) {
 export const toLoadablePath = (src) =>
   typeof src === 'string' || src instanceof URL ? src : new URL(src.href);
 
+/**
+ * A symbol by name: `{ symbol, weight?, scale?, variableValue? }` — the
+ * platform's own icons, drawn in the text colour (#591, src/symbols.js). Not
+ * pixels at all, so none of the decoding or caching below applies: the node
+ * asks the platform to draw the name at paint.
+ */
+export function isSymbolImageSource(src) {
+  return (
+    src != null &&
+    typeof src === 'object' &&
+    !(src instanceof Uint8Array) &&
+    'symbol' in src
+  );
+}
+
+const SYMBOL_SCALES = new Set(['small', 'medium', 'large']);
+
+function validateSymbolSource(src) {
+  const at = `react-x11: <image src={{ symbol: ${JSON.stringify(src.symbol)} }}>`;
+  if (typeof src.symbol !== 'string' || src.symbol === '') {
+    throw new Error(
+      `${at} needs a name: an SF Symbol on macOS, like 'speaker.wave.3.fill', ` +
+        "or an icon theme's name on Linux, like 'audio-volume-high'.",
+    );
+  }
+  const { weight, scale, variableValue } = src;
+  if (
+    weight !== undefined &&
+    !(
+      weight === 'normal' ||
+      weight === 'bold' ||
+      (typeof weight === 'number' && weight >= 1 && weight <= 1000)
+    )
+  ) {
+    throw new Error(
+      `${at} has weight ${JSON.stringify(weight)}, expected what fontWeight ` +
+        "takes — 'normal', 'bold' or a number from 1 to 1000.",
+    );
+  }
+  if (scale !== undefined && !SYMBOL_SCALES.has(scale)) {
+    throw new Error(
+      `${at} has scale ${JSON.stringify(scale)}, expected 'small', 'medium' ` +
+        "or 'large'.",
+    );
+  }
+  if (
+    variableValue !== undefined &&
+    !(
+      typeof variableValue === 'number' &&
+      variableValue >= 0 &&
+      variableValue <= 1
+    )
+  ) {
+    throw new Error(
+      `${at} has variableValue ${JSON.stringify(variableValue)}, expected a ` +
+        'number from 0 to 1.',
+    );
+  }
+}
+
+/** Two symbol sources naming the same drawing, however fresh the objects. */
+const sameSymbol = (a, b) =>
+  a.symbol === b.symbol &&
+  a.weight === b.weight &&
+  a.scale === b.scale &&
+  a.variableValue === b.variableValue;
+
 /** Raw straight-RGBA pixels: `{ width, height, data }` — the shape
  * `getImageData` hands back. (A `Buffer` of encoded bytes is a `Uint8Array`
  * subclass, so the two byte forms are one check elsewhere.) */
@@ -54,6 +121,7 @@ export function isRawImageSource(src) {
     !(src instanceof Uint8Array) &&
     !isPathImageSource(src) &&
     !isDirectImageSource(src) &&
+    !isSymbolImageSource(src) &&
     'data' in src
   );
 }
@@ -70,7 +138,8 @@ const describe = (value) =>
 /** Stated once, so every error lists the same set of accepted forms. */
 const SRC_FORMS =
   'a file path or file URL (PNG/JPEG), encoded PNG/JPEG bytes (Buffer or ' +
-  'Uint8Array), raw RGBA ({ width, height, data }), or an ntk Image/Surface';
+  'Uint8Array), raw RGBA ({ width, height, data }), an ntk Image/Surface, ' +
+  "or a symbol by name ({ symbol: 'speaker.wave.3.fill' })";
 
 function validateServerSource(kind, desc) {
   const shape =
@@ -163,6 +232,16 @@ export function validateImageProps(props) {
   if (props.drawable != null) validateServerSource('drawable', props.drawable);
   const src = props.src;
   if (src == null) return;
+  if (isSymbolImageSource(src)) {
+    if (props.cacheKey != null) {
+      throw new Error(
+        'react-x11: <image cacheKey> names decoded pixels, and a symbol is ' +
+          'drawn by name, not decoded — there is nothing to cache. Drop the ' +
+          'cacheKey.',
+      );
+    }
+    return validateSymbolSource(src);
+  }
   if (isPathImageSource(src)) return;
   if (src instanceof Uint8Array) return;
   if (isDirectImageSource(src)) return;
@@ -207,6 +286,9 @@ export function imageSourceChanged(next, prev) {
   if (next.cacheKey !== prev.cacheKey) return true;
   if (next.src === prev.src) return false;
   if ((next.src == null) !== (prev.src == null)) return true;
+  if (isSymbolImageSource(next.src) && isSymbolImageSource(prev.src)) {
+    return !sameSymbol(next.src, prev.src);
+  }
   if (isDirectImageSource(next.src) || isDirectImageSource(prev.src))
     return true;
   return next.cacheKey == null;

package/src/index.js

@@ -93,6 +93,8 @@ export { useKeyboardState } from './keyboardstatehooks.js';
 export { matchesShortcut } from './accelerators.js';
 export { useAccelerator } from './acceleratorhooks.js';
 export { useDesktopSettings } from './desktopsettingshooks.js';
+// what the app itself remembers between launches (#592)
+export { createSettings } from './settings.js';
 export { loadFont, openFont } from './fonts.js';
 export { useFont } from './fonthooks.js';
 export { systemLocale } from './locale.js';
@@ -127,6 +129,7 @@ export {
   useAnchorTracking,
   anchorArea,
   anchorRect,
+  anchorScreenRect,
   centerRect,
   screenRect,
 } from './components/index.js';

package/src/node.d.ts

@@ -236,6 +236,13 @@ export interface TextStyle {
   variations: Record<string, number> | undefined;
   textRendering: TextRendering | undefined;
   color: string;
+  /** `letterSpacing`, in device pixels like `size` — undefined unless a
+   * style or the cascade above it named one. */
+  letterSpacing: number | undefined;
+  /** The OpenType features `fontVariantNumeric` and `fontFeatureSettings`
+   * resolve to, tag → 1 on, 0 off or an alternate — undefined unless either
+   * was named. The same object for the same pair of values. */
+  features: Readonly<Record<string, number>> | undefined;
 }
 
 /**

package/src/nodes/animation.js

@@ -40,36 +40,6 @@ const gridContainerMoved = (was, now) =>
 const gridItemMoved = (was, now) =>
   GRID_ITEM_PROPS.some((prop) => was[prop] !== now[prop]);
 
-/**
- * The node whose bounds cover where an animating node will be next frame, or
- * `null` when that cannot be known and the frame has to repaint everything.
- *
- * Three cases, and the middle one is the interesting one:
- *
- *  - **paint-only** (a colour, an opacity): the node stays put, so its own
- *    bounds are the damage.
- *  - **a layout property on an out-of-flow node** (`position: absolute`, the
- *    arrangement a sliding thumb uses): the node moves, so its own bounds
- *    cover where it is going but not where it has been. Its *parent* covers
- *    both — an absolute child is laid out inside its parent and, being out of
- *    flow, moves nothing else when it shifts. This is what keeps a `Switch`
- *    from repainting the window on every frame of its 120ms slide.
- *  - **a layout property in flow**: a reflow can move any node in the tree,
- *    including ones that leave stale pixels outside every bound we could name
- *    here. Nothing to do but repaint in full.
- */
-function damageForAnimation(node) {
-  let movesInLayout = false;
-  for (const prop of node._anim?.keys() ?? []) {
-    if (isLayoutProp(prop)) movesInLayout = true;
-  }
-  if (!movesInLayout) return node;
-  if (node.style?.position !== 'absolute') return null;
-  // A window parent bounds nothing useful — its own rect is the whole surface.
-  const parent = node.parent;
-  return parent && !parent.isWindow ? parent : null;
-}
-
 // Frame timestamps for transitions. Indirected so tests can drive the clock
 // instead of sleeping through real animations.
 export let now = () => Date.now();
@@ -129,7 +99,7 @@ export class NodeAnimation {
         // such presenter, the window's frame clock runs it as it always has.
         if (this._offload(prop, entry)) {
           entry.offloaded = true;
-          this.root?.invalidate(false, damageForAnimation(this), 'animation');
+          this.root?.invalidate(false, this, 'animation');
         } else {
           // …and one the presenter had must not keep running underneath the
           // values the clock is about to write
@@ -342,7 +312,7 @@ export class NodeAnimation {
       }
     }
     this.root?._animating.delete(this);
-    this.root?.invalidate(false, damageForAnimation(this), 'animation');
+    this.root?.invalidate(false, this, 'animation');
   }
 
   /**
@@ -608,7 +578,7 @@ export class WindowAnimation {
     // invalidate anyway, but a React prop change does not — and a transition
     // no one schedules only runs when something else dirties the window,
     // by which time its start is stale and it snaps to the end.
-    this.invalidate(false, damageForAnimation(node), 'animation');
+    this.invalidate(false, node, 'animation');
   }
 
   /**
@@ -618,27 +588,27 @@ export class WindowAnimation {
    */
   _advanceAnimations(now) {
     if (this._animating.size === 0) return;
-    const claims = [];
     for (const node of [...this._animating]) {
       if (node.destroyed) {
         this._animating.delete(node);
         continue;
       }
-      // Decided *before* the tick, deliberately: a tick that finishes deletes
-      // the property from `_anim`, and after that there is no way to tell a
-      // layout animation from a paint-only one — the node's own bounds would
-      // be claimed for something that just moved, leaving a trail behind it.
-      claims.push(damageForAnimation(node));
+      // The node where it stands, which is where it *was*: nothing has been
+      // laid out yet, so its rect is the one the last pass gave it. Where it
+      // goes is the layout pass's to claim. A tick on a layout property asks
+      // for one, and that pass claims the old and new rect of every node it
+      // moves (`_assignAbs`) — this one, and whatever this one pushed, in
+      // flow or out of it. A paint-only property moves nothing, and this
+      // claim is the whole frame.
+      //
+      // Claimed rather than left unbounded because an animation repaints
+      // every frame for as long as it runs: eight height loops in a menu-bar
+      // popover were a full-window repaint per frame at 120Hz (#603). A node
+      // that *finishes* on this tick is claimed too — it just landed on its
+      // final value, and this last frame still has to paint it there.
+      this.invalidate(false, node, 'animation');
       if (!node._tickAnimations(now)) this._animating.delete(node);
     }
     this.needsPaint = true;
-    // Claim a region rather than leaving the frame unbounded: an animation is
-    // a repaint every frame for its whole duration, so this is the difference
-    // between a 120ms transition costing eight full-window repaints and eight
-    // repaints of the thing that moved. Nodes that *finished* on this tick are
-    // claimed too — one just landed on its final value and that last frame
-    // still has to paint it, which is why every transition used to end with a
-    // full-window repaint.
-    for (const claim of claims) this.invalidate(false, claim, 'animation');
   }
 }

package/src/nodes/cascade.js

@@ -190,10 +190,20 @@ export class NodeCascade {
    * A detached node has no ancestors yet and so cannot see a provider two
    * levels up; it still resolves, against the base, and `_themeChanged()` on
    * attach re-resolves it against the real one.
+   *
+   * A window can take its palette from somewhere other than its parent: a
+   * `<ThemeProvider>` above it at the root, which is not its parent because a
+   * top-level window has none, or one directly inside the window it is
+   * nested in, which passed it on to that window. Either is `_scope`, and it
+   * comes first (nodes/scope.js).
    */
   get theme() {
     if (this._theme !== undefined) return this._theme;
-    const inherited = this.parent ? this.parent.theme : baseTheme();
+    const inherited = this._scope
+      ? this._scope.theme
+      : this.parent
+        ? this.parent.theme
+        : baseTheme();
     const own = this.props.theme;
     this._theme = own ? { ...inherited, ...own } : inherited;
     return this._theme;
@@ -312,7 +322,12 @@ export class NodeCascade {
       const size = (inherited.size * to) / from;
       const cached = this._textScaled;
       if (cached?.from !== inherited || cached.style.size !== size) {
-        this._textScaled = { from: inherited, style: { ...inherited, size } };
+        const style = { ...inherited, size };
+        // the other length that travels, re-expressed the same way
+        if (inherited.letterSpacing) {
+          style.letterSpacing = (inherited.letterSpacing * to) / from;
+        }
+        this._textScaled = { from: inherited, style };
       }
       return this._textScaled.style;
     }

package/src/nodes/image.js

@@ -11,6 +11,7 @@ import {
   isDirectImageSource,
   isPathImageSource,
   isRawImageSource,
+  isSymbolImageSource,
   releaseImageSource,
   toLoadablePath,
   validateImageProps,
@@ -20,6 +21,7 @@ import {
 // is a *load-time* SyntaxError, which would take the renderer down rather
 // than the one feature that needs it.
 import * as ntk from 'ntk';
+import { symbolWeight, symbolsFor, warnOnce } from '../symbols.js';
 import { intrinsicSize } from './layout.js';
 import { Node } from './node.js';
 import { DEV } from './util.js';
@@ -42,6 +44,8 @@ export class ImageNode extends Node {
     this._ownedImage = null;
     /** PictureSource/DrawableSource, when the source is server-side */
     this._serverSource = null;
+    /** `{ symbol, … }`, when the source is a name the platform draws */
+    this._symbol = null;
     // Resolution waits for the first layout/paint: the constructor runs in
     // the render phase, which React may discard, and resolving here would
     // start file reads and take cache holds nothing would ever release.
@@ -67,6 +71,25 @@ export class ImageNode extends Node {
   measureContent(constraints) {
     this._ensureSource();
     const s = this.scale;
+    if (this._symbol) {
+      const name = this._symbol.symbol;
+      const size = symbolsFor(this.app).size(name, this._symbolOptions());
+      // A name this desktop does not have takes no room and draws nothing,
+      // which is right for an app that runs on both and wrong for a typo —
+      // development tells the two apart for it.
+      if (!size) {
+        warnOnce(
+          `react-x11: <image src={{ symbol: ${JSON.stringify(name)} }}> is ` +
+            'not a symbol this desktop has, so it takes no room and draws ' +
+            'nothing. SF Symbols are the names on macOS, and the icon ' +
+            "theme's names, like 'audio-volume-high', elsewhere.",
+        );
+      }
+      return intrinsicSize(
+        { width: (size?.width ?? 0) * s, height: (size?.height ?? 0) * s },
+        constraints,
+      );
+    }
     return intrinsicSize(
       {
         width: (this.image?.width ?? 0) * s,
@@ -96,6 +119,12 @@ export class ImageNode extends Node {
       return;
     }
     if (src == null) return;
+    if (isSymbolImageSource(src)) {
+      // nothing to load: the platform draws the name at paint, which is also
+      // when the text colour it is drawn in is known
+      this._symbol = src;
+      return;
+    }
     if (isDirectImageSource(src)) {
       // the caller's object — its upload cache is the dedupe, and it is
       // never destroyed here
@@ -223,9 +252,29 @@ export class ImageNode extends Node {
       this._serverSource.destroy?.();
       this._serverSource = null;
     }
+    this._symbol = null;
     this.image = null;
   }
 
+  /**
+   * How a symbol is drawn beside the text around it: at that text's size and
+   * weight unless the source says otherwise — what SF Symbols are designed
+   * for, and what lets a toolbar of them follow a theme's `fontSize` — in its
+   * colour, which is `currentColor` for an `<svg>` too. Sizes are logical.
+   */
+  _symbolOptions() {
+    const text = this.resolvedTextStyle();
+    const src = this._symbol;
+    return {
+      pointSize: text.size / this.scale,
+      weight: symbolWeight(src.weight ?? text.weight),
+      scale: src.scale,
+      variableValue: src.variableValue,
+      displayScale: this.scale,
+      color: text.color,
+    };
+  }
+
   applyProps(newProps, oldProps) {
     const before = oldProps ?? this.props;
     const sourceChanged = imageSourceChanged(newProps, before);
@@ -234,12 +283,16 @@ export class ImageNode extends Node {
     super.applyProps(newProps, oldProps);
     if (!sourceChanged) return;
     const prev = this.image;
+    const wasSymbol = this._symbol;
     this._releaseSource();
     this._sourceDirty = false;
     this._resolveSource();
     // paintChanged already claimed this node's box through super; only a
-    // new intrinsic size needs more than that
+    // new intrinsic size needs more than that — and a symbol's size is the
+    // platform's to say, so any change to one is measured again
     if (
+      wasSymbol ||
+      this._symbol ||
       (prev?.width ?? 0) !== (this.image?.width ?? 0) ||
       (prev?.height ?? 0) !== (this.image?.height ?? 0)
     ) {
@@ -254,6 +307,15 @@ export class ImageNode extends Node {
 
   paintContent(ctx) {
     this._ensureSource();
+    if (this._symbol) {
+      symbolsFor(this.app).draw(
+        ctx,
+        this._symbol.symbol,
+        this.contentBox(),
+        this._symbolOptions(),
+      );
+      return;
+    }
     if (!this.image) return;
     const content = this.contentBox();
     ctx.drawImage(

package/src/nodes/kinds.js

@@ -29,3 +29,15 @@ export const CUSTOM_SEMANTIC_NAMES = new Map();
  * arrangement as above, for the other declaration a scene-drawing element
  * makes (issue #301). */
 export const CUSTOM_SELF_DAMAGED = new Map();
+
+/**
+ * The element `<ThemeProvider>` renders to carry its palette into the node
+ * tree. Not one of `HOST_TYPES` and not documented as an element: the
+ * provider is the API. What node it becomes depends on where it is written
+ * (`createInstance`): inside a window it is a `<box>` that fills its parent —
+ * directly inside one, a `ThemeBoxNode` that also hands nested windows on to
+ * it — and at the root of the tree, above the windows, where nothing drawn
+ * may be, a `ThemeScopeNode` that draws nothing and hands the palette to the
+ * windows under it (nodes/scope.js).
+ */
+export const THEME_SCOPE = 'themescope';

package/src/nodes/layout.js

@@ -284,7 +284,11 @@ export class NodeLayout {
     // cached unions all the way up with it
     this._clearHitBounds();
     if (layoutDiff.sink) {
-      const grow = this._outlineExtent() + DAMAGE_SLOP;
+      // the reach `_ownPaintBounds` names, ring and shadow alike: a card
+      // pushed down by a row above it leaves its old shadow on the surface
+      // unless the claim for where it was covers that shadow too
+      const grow =
+        Math.max(this._outlineExtent(), this._shadowExtent()) + DAMAGE_SLOP;
       const shift = layoutDiff.shift;
       const had = old.width > 0 && old.height > 0;
       if (shift) {