@solidtv/renderer 1.6.1 → 1.6.3

package/src/core/text-rendering/tests/FontPrefetch.test.ts

@@ -0,0 +1,341 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+  prefetchFont,
+  clearFontPrefetch,
+  takeSdfPrefetch,
+  takeCanvasPrefetch,
+} from '../FontPrefetch.js';
+import { loadFont as loadSdfFont, isFontLoaded } from '../SdfFontHandler.js';
+import {
+  loadFont as loadCanvasFont,
+  isFontLoaded as isCanvasFontLoaded,
+} from '../CanvasFontHandler.js';
+import { EventEmitter } from '../../../common/EventEmitter.js';
+import type { Stage } from '../../Stage.js';
+import type { ImageTextureProps } from '../../textures/ImageTexture.js';
+
+const VALID_FONT_DATA = {
+  chars: [{}],
+  kernings: [],
+  lightningMetrics: {
+    ascender: 800,
+    descender: -200,
+    lineGap: 200,
+    unitsPerEm: 1000,
+  },
+};
+
+// Records every request so tests can assert what was fetched, when, and in
+// what order. Responses are keyed by URL and delivered on demand, letting a
+// test hold a request open to observe concurrency.
+class RecordingXHR {
+  static requests: RecordingXHR[] = [];
+  static responses: Record<string, unknown> = {};
+
+  status = 200;
+  response: unknown = null;
+  responseType = '';
+  url = '';
+  onload: (() => void) | null = null;
+  onerror: (() => void) | null = null;
+  onreadystatechange: (() => void) | null = null;
+  readyState = 0;
+
+  open(_method: string, url: string): void {
+    this.url = url;
+  }
+
+  send(): void {
+    RecordingXHR.requests.push(this);
+  }
+
+  /** Deliver the configured response for this request's URL. */
+  respond(status = 200): void {
+    this.status = status;
+    this.response = RecordingXHR.responses[this.url] ?? null;
+    this.readyState = 4;
+    if (this.onreadystatechange !== null) this.onreadystatechange();
+    if (this.onload !== null) this.onload();
+  }
+
+  /** Deliver every outstanding request. */
+  static respondAll(): void {
+    RecordingXHR.requests.forEach((r) => r.respond());
+  }
+
+  static reset(): void {
+    RecordingXHR.requests = [];
+    RecordingXHR.responses = {};
+  }
+}
+
+// `XMLHttpRequest.DONE` is read by fetchJson; the class stand-in must carry it.
+(RecordingXHR as unknown as { DONE: number }).DONE = 4;
+
+function makeFakeTexture() {
+  const tex = new EventEmitter() as unknown as EventEmitter & {
+    state: string;
+    preventCleanup: boolean;
+    setRenderableOwner: (owner: string, val: boolean) => void;
+  };
+  tex.state = 'loading';
+  tex.preventCleanup = false;
+  tex.setRenderableOwner = () => {};
+  return tex;
+}
+
+type FakeTexture = ReturnType<typeof makeFakeTexture>;
+
+// Stage stub that records the props each atlas texture was created with, so
+// tests can assert whether the prefetched blob (or the URL) was used.
+function makeStage(): {
+  stage: Stage;
+  textures: FakeTexture[];
+  textureProps: ImageTextureProps[];
+} {
+  const textures: FakeTexture[] = [];
+  const textureProps: ImageTextureProps[] = [];
+  const stage = {
+    txManager: {
+      createTexture: (_type: string, props: ImageTextureProps) => {
+        textureProps.push(props);
+        const t = makeFakeTexture();
+        textures.push(t);
+        return t;
+      },
+      removeTextureFromCache: () => {},
+    },
+  } as unknown as Stage;
+  return { stage, textures, textureProps };
+}
+
+const flush = (): Promise<void> => new Promise((r) => setTimeout(r, 0));
+
+const sdfOpts = (fontFamily: string) => ({
+  fontFamily,
+  atlasUrl: `${fontFamily}.png`,
+  atlasDataUrl: `${fontFamily}.json`,
+});
+
+describe('FontPrefetch — SDF', () => {
+  let originalXHR: unknown;
+  let originalBlob: unknown;
+
+  beforeEach(() => {
+    originalXHR = (globalThis as unknown as { XMLHttpRequest: unknown })
+      .XMLHttpRequest;
+    (globalThis as unknown as { XMLHttpRequest: unknown }).XMLHttpRequest =
+      RecordingXHR;
+    // jsdom provides Blob; guard for environments that do not.
+    originalBlob = (globalThis as unknown as { Blob: unknown }).Blob;
+    RecordingXHR.reset();
+    clearFontPrefetch();
+  });
+
+  afterEach(() => {
+    (globalThis as unknown as { XMLHttpRequest: unknown }).XMLHttpRequest =
+      originalXHR;
+    (globalThis as unknown as { Blob: unknown }).Blob = originalBlob;
+    clearFontPrefetch();
+  });
+
+  it('requests the atlas description and the atlas image concurrently', () => {
+    prefetchFont(sdfOpts('ConcurrentFont'));
+
+    // Both are in flight before either has responded — the handler's own path
+    // only starts the image fetch after the JSON resolves.
+    expect(RecordingXHR.requests.map((r) => r.url).sort()).toEqual([
+      'ConcurrentFont.json',
+      'ConcurrentFont.png',
+    ]);
+  });
+
+  it('starts no request for a font it has already prefetched', () => {
+    prefetchFont(sdfOpts('DedupeFont'));
+    expect(RecordingXHR.requests.length).toBe(2);
+
+    prefetchFont(sdfOpts('DedupeFont'));
+    expect(RecordingXHR.requests.length).toBe(2);
+  });
+
+  it('hands the prefetched payload to loadFont instead of refetching', async () => {
+    const font = sdfOpts('PrefetchHit');
+    const blob = new Blob(['atlas-bytes']);
+    RecordingXHR.responses['PrefetchHit.json'] = VALID_FONT_DATA;
+    RecordingXHR.responses['PrefetchHit.png'] = blob;
+
+    prefetchFont(font);
+    RecordingXHR.respondAll();
+    const prefetchRequestCount = RecordingXHR.requests.length;
+
+    const { stage, textures, textureProps } = makeStage();
+    const promise = loadSdfFont(
+      stage,
+      font as Parameters<typeof loadSdfFont>[1],
+    );
+    await flush();
+    textures[0]!.emit('loaded');
+    await promise;
+
+    // No second trip to the network for either resource.
+    expect(RecordingXHR.requests.length).toBe(prefetchRequestCount);
+    // The atlas texture was built from the prefetched bytes...
+    expect(textureProps[0]!.src).toBe(blob);
+    // ...while still keying the texture cache by URL, so the blob path and the
+    // URL path resolve to the same cache entry.
+    expect(textureProps[0]!.key).toBe('PrefetchHit.png');
+    expect(isFontLoaded('PrefetchHit')).toBe(true);
+  });
+
+  it('falls back to fetching when the prefetch failed', async () => {
+    const font = sdfOpts('PrefetchFail');
+    // No responses registered -> fetchJson resolves null -> unusable prefetch.
+    prefetchFont(font);
+    RecordingXHR.respondAll();
+    RecordingXHR.reset();
+
+    RecordingXHR.responses['PrefetchFail.json'] = VALID_FONT_DATA;
+
+    const { stage, textures, textureProps } = makeStage();
+    const promise = loadSdfFont(
+      stage,
+      font as Parameters<typeof loadSdfFont>[1],
+    );
+    // The handler runs its own XHR for the atlas description.
+    await flush();
+    RecordingXHR.respondAll();
+    await flush();
+    textures[0]!.emit('loaded');
+    await promise;
+
+    expect(RecordingXHR.requests.map((r) => r.url)).toEqual([
+      'PrefetchFail.json',
+    ]);
+    // Atlas falls back to the URL rather than a blob.
+    expect(textureProps[0]!.src).toBe('PrefetchFail.png');
+    expect(isFontLoaded('PrefetchFail')).toBe(true);
+  });
+
+  it('rejects a malformed atlas description rather than loading it', async () => {
+    RecordingXHR.responses['Malformed.json'] = { not: 'font data' };
+    prefetchFont(sdfOpts('Malformed'));
+    RecordingXHR.respondAll();
+
+    await expect(takeSdfPrefetch('Malformed')!.data).resolves.toBe(null);
+  });
+
+  it('parses an atlas description that arrives as a string', async () => {
+    RecordingXHR.responses['StringJson.json'] = JSON.stringify(VALID_FONT_DATA);
+    prefetchFont(sdfOpts('StringJson'));
+    RecordingXHR.respondAll();
+
+    await expect(takeSdfPrefetch('StringJson')!.data).resolves.toMatchObject({
+      chars: [{}],
+    });
+  });
+
+  it('claims a prefetch only once', () => {
+    prefetchFont(sdfOpts('OnceOnly'));
+
+    expect(takeSdfPrefetch('OnceOnly')).not.toBe(undefined);
+    expect(takeSdfPrefetch('OnceOnly')).toBe(undefined);
+  });
+
+  it('ignores a canvas-typed descriptor even when it carries atlas urls', () => {
+    prefetchFont({ ...sdfOpts('CanvasTyped'), type: 'canvas' });
+
+    expect(takeSdfPrefetch('CanvasTyped')).toBe(undefined);
+  });
+});
+
+describe('FontPrefetch — web fonts', () => {
+  class FakeFontFace {
+    static created: FakeFontFace[] = [];
+    constructor(public family: string, public source: string) {
+      FakeFontFace.created.push(this);
+    }
+    load(): Promise<FakeFontFace> {
+      return Promise.resolve(this);
+    }
+  }
+
+  let originalFontFace: unknown;
+
+  beforeEach(() => {
+    originalFontFace = (globalThis as unknown as { FontFace: unknown })
+      .FontFace;
+    (globalThis as unknown as { FontFace: unknown }).FontFace = FakeFontFace;
+    FakeFontFace.created = [];
+    clearFontPrefetch();
+  });
+
+  afterEach(() => {
+    (globalThis as unknown as { FontFace: unknown }).FontFace =
+      originalFontFace;
+    clearFontPrefetch();
+  });
+
+  it('starts the download for every registered name', async () => {
+    prefetchFont({
+      fontFamily: ['WebPrimary', 'WebAlias'],
+      fontUrl: 'web.woff2',
+    });
+
+    expect(FakeFontFace.created.map((f) => f.family)).toEqual([
+      'WebPrimary',
+      'WebAlias',
+    ]);
+    await expect(takeCanvasPrefetch('WebPrimary')).resolves.toHaveLength(2);
+  });
+
+  it('resolves to null when the download fails, so the handler can retry', async () => {
+    vi.spyOn(FakeFontFace.prototype, 'load').mockRejectedValueOnce(
+      new Error('network'),
+    );
+    prefetchFont({ fontFamily: 'WebFail', fontUrl: 'web.woff2' });
+
+    await expect(takeCanvasPrefetch('WebFail')).resolves.toBe(null);
+  });
+
+  it('does nothing when the engine has no FontFace', () => {
+    (globalThis as unknown as { FontFace: unknown }).FontFace = undefined;
+    prefetchFont({ fontFamily: 'NoFontFace', fontUrl: 'web.woff2' });
+
+    expect(takeCanvasPrefetch('NoFontFace')).toBe(undefined);
+  });
+
+  it('registers prefetched faces with the platform without reloading them', async () => {
+    prefetchFont({ fontFamily: 'CanvasHit', fontUrl: 'web.woff2' });
+    const createdByPrefetch = FakeFontFace.created.length;
+
+    const added: FakeFontFace[] = [];
+    const stage = {
+      platform: { addFont: (f: FakeFontFace) => added.push(f) },
+    } as unknown as Stage;
+
+    await loadCanvasFont(stage, {
+      fontFamily: 'CanvasHit',
+      fontUrl: 'web.woff2',
+    });
+
+    // No extra FontFace was constructed — the prefetched one was used.
+    expect(FakeFontFace.created.length).toBe(createdByPrefetch);
+    expect(added).toEqual(FakeFontFace.created);
+    expect(isCanvasFontLoaded('CanvasHit')).toBe(true);
+  });
+
+  it('loads normally when there is no prefetch to claim', async () => {
+    const added: FakeFontFace[] = [];
+    const stage = {
+      platform: { addFont: (f: FakeFontFace) => added.push(f) },
+    } as unknown as Stage;
+
+    await loadCanvasFont(stage, {
+      fontFamily: 'CanvasMiss',
+      fontUrl: 'web.woff2',
+    });
+
+    expect(FakeFontFace.created.map((f) => f.family)).toEqual(['CanvasMiss']);
+    expect(isCanvasFontLoaded('CanvasMiss')).toBe(true);
+  });
+});

package/src/core/text-rendering/tests/SdfFontHandler.test.ts

@@ -3,11 +3,14 @@ import {
   loadFont,
   waitingForFont,
   isFontLoaded,
+  getFontData,
+  canRenderFont,
   MAX_FONT_LOAD_RETRIES,
 } from '../SdfFontHandler.js';
 import { EventEmitter } from '../../../common/EventEmitter.js';
 import { TextureError, TextureErrorCode } from '../../TextureError.js';
 import type { Stage } from '../../Stage.js';
+import type { TrProps } from '../TextRenderer.js';
 
 // Minimal XHR stand-in: synchronously delivers valid SDF font JSON so loadFont
 // proceeds to create the atlas texture and attach its event listeners.
@@ -71,7 +74,7 @@ function makeStage(): { stage: Stage; textures: FakeTexture[] } {
   return { stage, textures };
 }
 
-const opts = (fontFamily: string) =>
+const opts = (fontFamily: string | string[]) =>
   ({
     fontFamily,
     atlasUrl: 'atlas.png',
@@ -256,3 +259,107 @@ describe('SdfFontHandler loadFont — automatic retry', () => {
     expect(node.setUpdateType).toHaveBeenCalledTimes(1);
   });
 });
+
+describe('SdfFontHandler loadFont — multiple names for one font', () => {
+  let originalXHR: unknown;
+
+  beforeEach(() => {
+    originalXHR = (globalThis as unknown as { XMLHttpRequest: unknown })
+      .XMLHttpRequest;
+    (globalThis as unknown as { XMLHttpRequest: unknown }).XMLHttpRequest =
+      FakeXHR;
+  });
+
+  afterEach(() => {
+    (globalThis as unknown as { XMLHttpRequest: unknown }).XMLHttpRequest =
+      originalXHR;
+  });
+
+  it('fetches once and registers every name against the same font data', async () => {
+    const { stage, textures } = makeStage();
+    const names = ['Roboto', 'Roboto500', 'RobotoMedium'];
+
+    const promise = loadFont(stage, opts(names));
+    await flush();
+    textures[0]!.emit('loaded');
+    await promise;
+
+    // A single atlas texture was created for all three names.
+    expect(textures.length).toBe(1);
+
+    // Every name reports loaded and resolves to the identical cache entry.
+    const primaryData = getFontData(names[0]!);
+    expect(primaryData).not.toBe(undefined);
+    for (let i = 0; i < names.length; i++) {
+      expect(isFontLoaded(names[i]!)).toBe(true);
+      expect(getFontData(names[i]!)).toBe(primaryData);
+    }
+  });
+
+  it('reports every name as renderable while the font is still loading', async () => {
+    const { stage, textures } = makeStage();
+    const names = ['MidLoadPrimary', 'MidLoadAlias'];
+
+    const promise = loadFont(stage, opts(names));
+
+    // Mid-load: nothing is in fontCache yet, so this is answered purely by the
+    // in-flight markers. An alias that answers `false` here makes the stage
+    // resolve a *different* text renderer for the node — silently substituting
+    // a Canvas face, or throwing "No compatible text renderer found" when SDF
+    // is the only engine. Both names must answer the same.
+    for (let i = 0; i < names.length; i++) {
+      expect(canRenderFont({ fontFamily: names[i]! } as TrProps)).toBe(true);
+    }
+    expect(isFontLoaded(names[1]!)).toBe(false);
+
+    await flush();
+    textures[0]!.emit('loaded');
+    await promise;
+
+    for (let i = 0; i < names.length; i++) {
+      expect(canRenderFont({ fontFamily: names[i]! } as TrProps)).toBe(true);
+      expect(isFontLoaded(names[i]!)).toBe(true);
+    }
+  });
+
+  it('dedupes a load requested under an alias onto the in-flight load', async () => {
+    const { stage, textures } = makeStage();
+
+    const first = loadFont(stage, opts(['DedupePrimary', 'DedupeAlias']));
+    const second = loadFont(stage, opts('DedupeAlias'));
+
+    expect(second).toBe(first);
+
+    await flush();
+    // A single atlas fetch served both calls.
+    expect(textures.length).toBe(1);
+    textures[0]!.emit('loaded');
+    await first;
+  });
+
+  it('wakes nodes parked under an alias, not just the primary name', async () => {
+    const { stage, textures } = makeStage();
+    const names = ['MultiWakePrimary', 'MultiWakeAlias'];
+
+    const promise = loadFont(stage, opts(names));
+
+    // Park one node under the primary name and one under the alias.
+    const primaryNode = { id: 1, setUpdateType: vi.fn() };
+    const aliasNode = { id: 2, setUpdateType: vi.fn() };
+    waitingForFont(
+      names[0]!,
+      primaryNode as unknown as Parameters<typeof waitingForFont>[1],
+    );
+    waitingForFont(
+      names[1]!,
+      aliasNode as unknown as Parameters<typeof waitingForFont>[1],
+    );
+
+    await flush();
+    textures[0]!.emit('loaded');
+    await promise;
+
+    expect(primaryNode.setUpdateType).toHaveBeenCalledTimes(1);
+    expect(aliasNode.setUpdateType).toHaveBeenCalledTimes(1);
+  });
+});

package/src/core/textures/ImageTexture.test.ts

@@ -2,26 +2,70 @@ import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { ImageTexture } from './ImageTexture.js';
 import type { CoreTextureManager } from '../CoreTextureManager.js';
 
+const makeTxManager = (
+  imageBitmapSupported: {
+    basic: boolean;
+    options: boolean;
+    full: boolean;
+    premultiplyHonored: boolean | null;
+  },
+  createImageBitmapMock: () => Promise<unknown>,
+) =>
+  ({
+    imageBitmapSupported,
+    platform: {
+      createImageBitmap: createImageBitmapMock,
+    },
+  } as unknown as CoreTextureManager);
+
 describe('ImageTexture.createImageBitmap', () => {
   beforeEach(() => {
     vi.stubGlobal('ImageBitmap', class {});
   });
 
-  it('passes options to createImageBitmap when no crop is requested and options/full are supported', async () => {
+  it('requests a premultiplied bitmap when options are supported and the option is honored', async () => {
+    const createImageBitmapMock = vi.fn(() =>
+      Promise.resolve({ close: () => {} }),
+    );
+    const txManager = makeTxManager(
+      { basic: true, options: true, full: true, premultiplyHonored: true },
+      createImageBitmapMock,
+    );
+
+    const props = ImageTexture.resolveDefaults({
+      src: 'test.png',
+      premultiplyAlpha: true,
+    });
+    const texture = new ImageTexture(txManager, props);
+
+    const blob = new Blob([], { type: 'image/png' });
+    const result = await texture.createImageBitmap(
+      blob,
+      true,
+      null,
+      null,
+      null,
+      null,
+    );
+
+    expect(createImageBitmapMock).toHaveBeenCalledWith(blob, {
+      premultiplyAlpha: 'premultiply',
+      colorSpaceConversion: 'none',
+      imageOrientation: 'none',
+    });
+
+    // The bitmap is already premultiplied; WebGL must not premultiply again
+    expect(result.premultiplyAlpha).toBe(false);
+  });
+
+  it('requests a straight bitmap and defers premultiply to WebGL when the option is not honored', async () => {
     const createImageBitmapMock = vi.fn(() =>
       Promise.resolve({ close: () => {} }),
     );
-    const txManager = {
-      imageBitmapSupported: {
-        basic: true,
-        options: true,
-        full: true,
-        premultiplyHonored: false,
-      },
-      platform: {
-        createImageBitmap: createImageBitmapMock,
-      },
-    } as unknown as CoreTextureManager;
+    const txManager = makeTxManager(
+      { basic: true, options: true, full: true, premultiplyHonored: false },
+      createImageBitmapMock,
+    );
 
     const props = ImageTexture.resolveDefaults({
       src: 'test.png',
@@ -39,14 +83,13 @@ describe('ImageTexture.createImageBitmap', () => {
       null,
     );
 
-    // It should have called createImageBitmap with the options object
     expect(createImageBitmapMock).toHaveBeenCalledWith(blob, {
       premultiplyAlpha: 'none',
       colorSpaceConversion: 'none',
       imageOrientation: 'none',
     });
 
-    // Since premultiplyHonored is false, useGlPremultiply should be true
+    // Since premultiplyHonored is false, WebGL premultiplies on upload
     expect(result.premultiplyAlpha).toBe(true);
   });
 
@@ -54,17 +97,10 @@ describe('ImageTexture.createImageBitmap', () => {
     const createImageBitmapMock = vi.fn(() =>
       Promise.resolve({ close: () => {} }),
     );
-    const txManager = {
-      imageBitmapSupported: {
-        basic: true,
-        options: false,
-        full: false,
-        premultiplyHonored: null,
-      },
-      platform: {
-        createImageBitmap: createImageBitmapMock,
-      },
-    } as unknown as CoreTextureManager;
+    const txManager = makeTxManager(
+      { basic: true, options: false, full: false, premultiplyHonored: null },
+      createImageBitmapMock,
+    );
 
     const props = ImageTexture.resolveDefaults({
       src: 'test.png',
@@ -85,7 +121,39 @@ describe('ImageTexture.createImageBitmap', () => {
     // It should have called basic createImageBitmap without options
     expect(createImageBitmapMock).toHaveBeenCalledWith(blob);
 
-    // And premultiplyAlpha should be false (browser default is assumed to premultiply)
+    // The browser default is assumed to premultiply; WebGL must not premultiply again
     expect(result.premultiplyAlpha).toBe(false);
   });
+
+  it('defers premultiply to WebGL on basic-only devices when premultiplyAlphaHonored is false', async () => {
+    const createImageBitmapMock = vi.fn(() =>
+      Promise.resolve({ close: () => {} }),
+    );
+    const txManager = makeTxManager(
+      { basic: true, options: false, full: false, premultiplyHonored: false },
+      createImageBitmapMock,
+    );
+
+    const props = ImageTexture.resolveDefaults({
+      src: 'test.png',
+      premultiplyAlpha: true,
+    });
+    const texture = new ImageTexture(txManager, props);
+
+    const blob = new Blob([], { type: 'image/png' });
+    const result = await texture.createImageBitmap(
+      blob,
+      true,
+      null,
+      null,
+      null,
+      null,
+    );
+
+    // Still the basic call — no options are supported on these devices
+    expect(createImageBitmapMock).toHaveBeenCalledWith(blob);
+
+    // Device default returns straight alpha; WebGL premultiplies on upload
+    expect(result.premultiplyAlpha).toBe(true);
+  });
 });

package/src/core/textures/ImageTexture.ts

@@ -225,10 +225,12 @@ export class ImageTexture extends Texture {
     ) {
       // basic createImageBitmap without options or crop
       // this is supported for Chrome v50 to v52/54 that doesn't support options.
-      // The browser default premultiplies, so WebGL must not premultiply again.
+      // The browser default premultiplies, so WebGL must not premultiply again —
+      // except on devices whose default returns straight alpha
+      // (premultiplyAlphaHonored: false); there WebGL premultiplies on upload.
       return {
         data: await this.platform.createImageBitmap(blob),
-        premultiplyAlpha: false,
+        premultiplyAlpha: useGlPremultiply,
       };
     }
 

package/src/main-api/Renderer.ts

@@ -654,10 +654,14 @@ export type RendererMainSettings = RendererRuntimeSettings & {
    * ignore it, returning straight (non-premultiplied) alpha. This causes edge
    * "ghosting" on images with transparency.
    *
-   * Set to `'auto'` to detect via a cheap startup probe (one 1×1 texture
-   * upload + framebuffer readback). Set to a boolean to force the value. Leave
-   * unset to assume the option is honored — the default, which preserves
-   * existing behavior with no probe overhead.
+   * Set to `'auto'` to detect via a cheap startup probe (one 1×1 PNG decode +
+   * texture upload + framebuffer readback). On devices that honor the option —
+   * the vast majority — the probe returns `true` and behavior is identical to
+   * assuming it honored; only devices that actually ignore it (e.g. the
+   * Movistar STB) switch to the WebGL-side premultiply fallback. Set to a
+   * boolean to force the value (`false` forces the GL-premultiply fallback;
+   * `true` skips it). Leave unset to assume the option is honored — the
+   * default, which preserves existing behavior with no probe overhead.
    *
    * @defaultValue `true` (assume honored; no probe)
    */