@flighthq/textshaper 0.1.0

package/dist/textShaperRun.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"textShaperRun.js","sourceRoot":"","sources":["../src/textShaperRun.ts"],"names":[],"mappings":"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"}

package/dist/textShaperSignals.d.ts

@@ -0,0 +1,5 @@
+import type { TextShaperSignals } from '@flighthq/types';
+export declare function disposeTextShaperSignals(): void;
+export declare function enableTextShaperSignals(): TextShaperSignals;
+export declare function getTextShaperSignals(): TextShaperSignals | null;
+//# sourceMappingURL=textShaperSignals.d.ts.map

package/dist/textShaperSignals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"textShaperSignals.d.ts","sourceRoot":"","sources":["../src/textShaperSignals.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAqB,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAI5E,wBAAgB,wBAAwB,IAAI,IAAI,CAK/C;AAED,wBAAgB,uBAAuB,IAAI,iBAAiB,CAW3D;AAED,wBAAgB,oBAAoB,IAAI,iBAAiB,GAAG,IAAI,CAE/D"}

package/dist/textShaperSignals.js

@@ -0,0 +1,27 @@
+import { clearSignal, createSignal } from '@flighthq/signals';
+import { _setTextShaperBackendHook } from './_textShaperHooks';
+export function disposeTextShaperSignals() {
+    if (_signals === null)
+        return;
+    clearSignal(_signals.onBackendChanged);
+    _signals = null;
+    _setTextShaperBackendHook(null);
+}
+export function enableTextShaperSignals() {
+    if (_signals !== null)
+        return _signals;
+    _signals = {
+        onBackendChanged: createSignal(),
+    };
+    _setTextShaperBackendHook((backend) => {
+        if (_signals !== null) {
+            _signals.onBackendChanged.emit(backend);
+        }
+    });
+    return _signals;
+}
+export function getTextShaperSignals() {
+    return _signals;
+}
+let _signals = null;
+//# sourceMappingURL=textShaperSignals.js.map

package/dist/textShaperSignals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"textShaperSignals.js","sourceRoot":"","sources":["../src/textShaperSignals.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAG9D,OAAO,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAE/D,MAAM,UAAU,wBAAwB;IACtC,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO;IAC9B,WAAW,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAC;IACvC,QAAQ,GAAG,IAAI,CAAC;IAChB,yBAAyB,CAAC,IAAI,CAAC,CAAC;AAClC,CAAC;AAED,MAAM,UAAU,uBAAuB;IACrC,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO,QAAQ,CAAC;IACvC,QAAQ,GAAG;QACT,gBAAgB,EAAE,YAAY,EAA+C;KAC9E,CAAC;IACF,yBAAyB,CAAC,CAAC,OAAO,EAAE,EAAE;QACpC,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;YACtB,QAAQ,CAAC,gBAAgB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC1C,CAAC;IACH,CAAC,CAAC,CAAC;IACH,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,oBAAoB;IAClC,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,IAAI,QAAQ,GAA6B,IAAI,CAAC"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@flighthq/textshaper",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.test.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts.map"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --watch --config vitest.config.ts",
+    "prepack": "npm run clean && npm run clean:dist && npm run build",
+    "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
+  },
+  "dependencies": {
+    "@flighthq/signals": "0.1.0",
+    "@flighthq/types": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "Text-shaping seam: measure/shape text into advances over a swappable backend (canvas default, HarfBuzz future)",
+  "sideEffects": false
+}

package/src/_textShaperHooks.test.ts

@@ -0,0 +1,69 @@
+import type { TextShaperBackend } from '@flighthq/types';
+
+import { _setTextShaperBackendHook, _textShaperBackendHook } from './_textShaperHooks';
+import { setTextShaperBackend } from './textShaper';
+
+const _testBackend: TextShaperBackend = {
+  measureText: (text) => text.length,
+};
+
+afterEach(() => {
+  // Restore module state so an installed hook does not leak across tests.
+  _setTextShaperBackendHook(null);
+  setTextShaperBackend(null);
+});
+
+describe('_setTextShaperBackendHook', () => {
+  it('installs the hook so setTextShaperBackend invokes it with the new backend', () => {
+    let received: TextShaperBackend | null = _testBackend;
+    let calls = 0;
+    _setTextShaperBackendHook((backend) => {
+      received = backend;
+      calls++;
+    });
+    setTextShaperBackend(_testBackend);
+    expect(calls).toBe(1);
+    expect(received).toBe(_testBackend);
+  });
+
+  it('passes null through to the hook when the backend is cleared', () => {
+    let received: TextShaperBackend | null = _testBackend;
+    _setTextShaperBackendHook((backend) => {
+      received = backend;
+    });
+    setTextShaperBackend(null);
+    expect(received).toBeNull();
+  });
+
+  it('exposes the installed hook on the _textShaperBackendHook slot', () => {
+    expect(_textShaperBackendHook).toBeNull();
+    const hook = (): void => {};
+    _setTextShaperBackendHook(hook);
+    expect(_textShaperBackendHook).toBe(hook);
+  });
+
+  it('clears the hook when passed null so setTextShaperBackend no longer dispatches', () => {
+    let calls = 0;
+    _setTextShaperBackendHook(() => {
+      calls++;
+    });
+    _setTextShaperBackendHook(null);
+    expect(_textShaperBackendHook).toBeNull();
+    setTextShaperBackend(_testBackend);
+    expect(calls).toBe(0);
+  });
+
+  it('replaces a previously installed hook (last write wins)', () => {
+    let firstCalls = 0;
+    let secondCalls = 0;
+    _setTextShaperBackendHook(() => {
+      firstCalls++;
+    });
+    _setTextShaperBackendHook(() => {
+      secondCalls++;
+    });
+    setTextShaperBackend(_testBackend);
+    expect(firstCalls).toBe(0);
+    expect(secondCalls).toBe(1);
+  });
+});

package/src/textShaper.test.ts

@@ -0,0 +1,42 @@
+import type { TextShaperBackend } from '@flighthq/types';
+
+import { getTextShaperBackend, measureText, setTextShaperBackend } from './textShaper';
+
+afterEach(() => {
+  setTextShaperBackend(null);
+});
+
+describe('getTextShaperBackend', () => {
+  it('returns null before a backend is set', () => {
+    expect(getTextShaperBackend()).toBeNull();
+  });
+});
+
+describe('measureText', () => {
+  it('returns -1 when no backend is registered', () => {
+    expect(measureText('hello', {})).toBe(-1);
+  });
+
+  it('delegates to the active backend', () => {
+    setTextShaperBackend({ measureText: (text) => text.length * 7 });
+    expect(measureText('abc', {})).toBe(21);
+  });
+});
+
+describe('setTextShaperBackend', () => {
+  it('stores the backend and clears it with null', () => {
+    const backend: TextShaperBackend = { measureText: (text) => text.length };
+    setTextShaperBackend(backend);
+    expect(getTextShaperBackend()).toBe(backend);
+    setTextShaperBackend(null);
+    expect(getTextShaperBackend()).toBeNull();
+  });
+
+  it('replaces an existing backend (last write wins, no throw)', () => {
+    const first: TextShaperBackend = { measureText: () => 1 };
+    const second: TextShaperBackend = { measureText: () => 2 };
+    setTextShaperBackend(first);
+    setTextShaperBackend(second);
+    expect(getTextShaperBackend()).toBe(second);
+  });
+});

package/src/textShaperCache.test.ts

@@ -0,0 +1,161 @@
+import type { ShapedRun, TextShaperBackend } from '@flighthq/types';
+
+import { setTextShaperBackend } from './textShaper';
+import {
+  clearTextShaperCache,
+  createTextShaperCache,
+  disposeTextShaperCache,
+  shapeTextRunCached,
+} from './textShaperCache';
+
+const _stubRun: ShapedRun = {
+  advanceWidth: 15,
+  direction: 'LeftToRight',
+  font: null,
+  glyphCount: 2,
+  glyphs: [],
+  script: 'Latn',
+};
+
+function _makeCountingBackend(): { backend: TextShaperBackend; readonly calls: number } {
+  let calls = 0;
+  return {
+    backend: {
+      measureText: () => 0,
+      shapeRun: () => {
+        calls++;
+        return { ..._stubRun };
+      },
+    },
+    get calls() {
+      return calls;
+    },
+  };
+}
+
+afterEach(() => {
+  setTextShaperBackend(null);
+});
+
+describe('clearTextShaperCache', () => {
+  it('removes all cached entries', () => {
+    const { backend } = _makeCountingBackend();
+    setTextShaperBackend(backend);
+    const cache = createTextShaperCache();
+    shapeTextRunCached(cache, 'hi', {});
+    expect(cache._entries.size).toBe(1);
+    clearTextShaperCache(cache);
+    expect(cache._entries.size).toBe(0);
+  });
+
+  it('cache remains usable after clearing', () => {
+    const { backend } = _makeCountingBackend();
+    setTextShaperBackend(backend);
+    const cache = createTextShaperCache();
+    shapeTextRunCached(cache, 'hi', {});
+    clearTextShaperCache(cache);
+    shapeTextRunCached(cache, 'hi', {});
+    expect(cache._entries.size).toBe(1);
+  });
+});
+
+describe('createTextShaperCache', () => {
+  it('returns an empty cache', () => {
+    const cache = createTextShaperCache();
+    expect(cache._entries.size).toBe(0);
+  });
+
+  it('allocates a new cache on each call', () => {
+    expect(createTextShaperCache()).not.toBe(createTextShaperCache());
+  });
+});
+
+describe('disposeTextShaperCache', () => {
+  it('clears all entries', () => {
+    const { backend } = _makeCountingBackend();
+    setTextShaperBackend(backend);
+    const cache = createTextShaperCache();
+    shapeTextRunCached(cache, 'hi', {});
+    disposeTextShaperCache(cache);
+    expect(cache._entries.size).toBe(0);
+  });
+});
+
+describe('shapeTextRunCached', () => {
+  it('returns null when no backend is set', () => {
+    const cache = createTextShaperCache();
+    expect(shapeTextRunCached(cache, 'hi', {})).toBeNull();
+  });
+
+  it('returns null when the backend is advances-only', () => {
+    setTextShaperBackend({ measureText: (t) => t.length });
+    const cache = createTextShaperCache();
+    expect(shapeTextRunCached(cache, 'hi', {})).toBeNull();
+  });
+
+  it('returns a ShapedRun on success', () => {
+    const { backend } = _makeCountingBackend();
+    setTextShaperBackend(backend);
+    const cache = createTextShaperCache();
+    const run = shapeTextRunCached(cache, 'hi', {});
+    expect(run).not.toBeNull();
+    expect(run!.glyphCount).toBe(2);
+  });
+
+  it('returns the same object on the second call (cache hit)', () => {
+    const { backend } = _makeCountingBackend();
+    setTextShaperBackend(backend);
+    const cache = createTextShaperCache();
+    const r1 = shapeTextRunCached(cache, 'hi', {});
+    const r2 = shapeTextRunCached(cache, 'hi', {});
+    expect(r1).toBe(r2);
+  });
+
+  it('calls the backend once for repeated identical inputs', () => {
+    const tracker = _makeCountingBackend();
+    setTextShaperBackend(tracker.backend);
+    const cache = createTextShaperCache();
+    shapeTextRunCached(cache, 'hi', {});
+    shapeTextRunCached(cache, 'hi', {});
+    expect(tracker.calls).toBe(1);
+  });
+
+  it('calls the backend again for different text', () => {
+    const tracker = _makeCountingBackend();
+    setTextShaperBackend(tracker.backend);
+    const cache = createTextShaperCache();
+    shapeTextRunCached(cache, 'hi', {});
+    shapeTextRunCached(cache, 'bye', {});
+    expect(tracker.calls).toBe(2);
+  });
+
+  it('calls the backend again for different format', () => {
+    const tracker = _makeCountingBackend();
+    setTextShaperBackend(tracker.backend);
+    const cache = createTextShaperCache();
+    shapeTextRunCached(cache, 'hi', { size: 12 });
+    shapeTextRunCached(cache, 'hi', { size: 16 });
+    expect(tracker.calls).toBe(2);
+  });
+
+  it('calls the backend again for different options direction', () => {
+    const tracker = _makeCountingBackend();
+    setTextShaperBackend(tracker.backend);
+    const cache = createTextShaperCache();
+    shapeTextRunCached(cache, 'hi', {}, { direction: 'LeftToRight' });
+    shapeTextRunCached(cache, 'hi', {}, { direction: 'RightToLeft' });
+    expect(tracker.calls).toBe(2);
+  });
+
+  it('does not cache null results (no backend)', () => {
+    const cache = createTextShaperCache();
+    // First call: no backend, returns null, should not be cached.
+    expect(shapeTextRunCached(cache, 'hi', {})).toBeNull();
+    expect(cache._entries.size).toBe(0);
+    // Install a backend; now the same call should succeed.
+    const { backend } = _makeCountingBackend();
+    setTextShaperBackend(backend);
+    expect(shapeTextRunCached(cache, 'hi', {})).not.toBeNull();
+    expect(cache._entries.size).toBe(1);
+  });
+});

package/src/textShaperCluster.test.ts

@@ -0,0 +1,113 @@
+import type { ShapedRun } from '@flighthq/types';
+
+import { getCaretPositionsForRun, getClusterForIndex, getIndexRangeForCluster } from './textShaperCluster';
+
+function _makeRun(glyphs: ReadonlyArray<{ cluster: number; xAdvance: number }>): ShapedRun {
+  return {
+    advanceWidth: glyphs.reduce((s, g) => s + g.xAdvance, 0),
+    direction: 'LeftToRight',
+    font: null,
+    glyphCount: glyphs.length,
+    glyphs: glyphs.map((g) => ({
+      cluster: g.cluster,
+      glyphId: g.cluster,
+      xAdvance: g.xAdvance,
+      xOffset: 0,
+      yAdvance: 0,
+      yOffset: 0,
+    })),
+    script: 'Latn',
+  };
+}
+
+describe('getCaretPositionsForRun', () => {
+  it('returns [0] for an empty run', () => {
+    const run = _makeRun([]);
+    expect(getCaretPositionsForRun(run)).toEqual([0]);
+  });
+
+  it('returns glyphCount + 1 positions starting at 0', () => {
+    const run = _makeRun([
+      { cluster: 0, xAdvance: 8 },
+      { cluster: 1, xAdvance: 7 },
+      { cluster: 2, xAdvance: 9 },
+    ]);
+    const pos = getCaretPositionsForRun(run);
+    expect(pos).toHaveLength(4);
+    expect(pos[0]).toBe(0);
+    expect(pos[1]).toBe(8);
+    expect(pos[2]).toBe(15);
+    expect(pos[3]).toBe(24);
+  });
+
+  it('last position equals the run advance width', () => {
+    const run = _makeRun([
+      { cluster: 0, xAdvance: 5 },
+      { cluster: 1, xAdvance: 3 },
+    ]);
+    const pos = getCaretPositionsForRun(run);
+    expect(pos[pos.length - 1]).toBe(run.advanceWidth);
+  });
+});
+
+describe('getClusterForIndex', () => {
+  it('returns -1 for an empty run', () => {
+    expect(getClusterForIndex(_makeRun([]), 0)).toBe(-1);
+  });
+
+  it('returns -1 for a negative string index', () => {
+    const run = _makeRun([{ cluster: 0, xAdvance: 8 }]);
+    expect(getClusterForIndex(run, -1)).toBe(-1);
+  });
+
+  it('returns the cluster of the glyph covering the string index', () => {
+    const run = _makeRun([
+      { cluster: 0, xAdvance: 8 },
+      { cluster: 2, xAdvance: 7 },
+      { cluster: 4, xAdvance: 9 },
+    ]);
+    expect(getClusterForIndex(run, 0)).toBe(0);
+    expect(getClusterForIndex(run, 1)).toBe(0);
+    expect(getClusterForIndex(run, 2)).toBe(2);
+    expect(getClusterForIndex(run, 3)).toBe(2);
+    expect(getClusterForIndex(run, 4)).toBe(4);
+    expect(getClusterForIndex(run, 10)).toBe(4);
+  });
+});
+
+describe('getIndexRangeForCluster', () => {
+  it('returns null for an empty run', () => {
+    expect(getIndexRangeForCluster(_makeRun([]), 0)).toBeNull();
+  });
+
+  it('returns null for a cluster not present in the run', () => {
+    const run = _makeRun([{ cluster: 0, xAdvance: 8 }]);
+    expect(getIndexRangeForCluster(run, 5)).toBeNull();
+  });
+
+  it('returns [cluster, nextCluster) for a non-final cluster', () => {
+    const run = _makeRun([
+      { cluster: 0, xAdvance: 8 },
+      { cluster: 2, xAdvance: 7 },
+      { cluster: 4, xAdvance: 9 },
+    ]);
+    expect(getIndexRangeForCluster(run, 0)).toEqual([0, 2]);
+    expect(getIndexRangeForCluster(run, 2)).toEqual([2, 4]);
+  });
+
+  it('uses stringLength for the final cluster end when provided', () => {
+    const run = _makeRun([
+      { cluster: 0, xAdvance: 8 },
+      { cluster: 2, xAdvance: 7 },
+    ]);
+    expect(getIndexRangeForCluster(run, 2, 6)).toEqual([2, 6]);
+  });
+
+  it('estimates final cluster end as cluster + 1 when stringLength is absent', () => {
+    const run = _makeRun([
+      { cluster: 0, xAdvance: 8 },
+      { cluster: 2, xAdvance: 7 },
+    ]);
+    expect(getIndexRangeForCluster(run, 2)).toEqual([2, 3]);
+  });
+});

package/src/textShaperItemize.test.ts

@@ -0,0 +1,114 @@
+import type { ShapedRun, ShapeRunOptions, TextFormat } from '@flighthq/types';
+
+import { setTextShaperBackend } from './textShaper';
+import { itemizeText, shapeTextRuns } from './textShaperItemize';
+
+const _emptyRun: ShapedRun = {
+  advanceWidth: 0,
+  direction: 'LeftToRight',
+  font: null,
+  glyphCount: 0,
+  glyphs: [],
+  script: 'Latn',
+};
+
+function _makeShapingBackend() {
+  return {
+    measureText: (t: string) => t.length * 8,
+    shapeRun: (_t: string, _f: Readonly<TextFormat>, opts?: Readonly<ShapeRunOptions>): ShapedRun => ({
+      ..._emptyRun,
+      direction: opts?.direction ?? 'LeftToRight',
+      script: opts?.script ?? 'Latn',
+    }),
+  };
+}
+
+afterEach(() => {
+  setTextShaperBackend(null);
+});
+
+describe('itemizeText', () => {
+  it('returns empty array for empty string', () => {
+    expect(itemizeText('', {})).toEqual([]);
+  });
+  it('returns a single run for a pure Latin string', () => {
+    const items = itemizeText('Hello', {});
+    expect(items).toHaveLength(1);
+    expect(items[0].start).toBe(0);
+    expect(items[0].end).toBe(5);
+    expect(items[0].script).toBe('Latn');
+    expect(items[0].direction).toBe('LeftToRight');
+  });
+  it('splits Arabic from Latin', () => {
+    // ASCII 'AB' (LTR/Latin) followed by Arabic 'سلام' (U+0633 U+0644 U+0627 U+0645, RTL/Arab)
+    const arabic = 'سلام';
+    const mixed = 'AB' + arabic;
+    const items = itemizeText(mixed, {});
+    expect(items).toHaveLength(2);
+    expect(items[0].direction).toBe('LeftToRight');
+    expect(items[0].script).toBe('Latn');
+    expect(items[1].direction).toBe('RightToLeft');
+    expect(items[1].script).toBe('Arab');
+  });
+  it('treats neutral characters (space) as belonging to the current run', () => {
+    const items = itemizeText('Hello World', {});
+    // Space is neutral; it should be absorbed into the Latin run, not create a boundary.
+    expect(items).toHaveLength(1);
+    expect(items[0].start).toBe(0);
+    expect(items[0].end).toBe(11);
+  });
+  it('respects explicit direction override from options', () => {
+    const items = itemizeText('Hello', {}, { direction: 'RightToLeft' });
+    // Latin characters are LTR strong; the explicit direction in options sets the base but
+    // strong LTR chars override.
+    expect(items).toHaveLength(1);
+    expect(items[0].direction).toBe('LeftToRight');
+  });
+  it('covers entire string (no gaps between items)', () => {
+    const arabic = 'سلام';
+    const text = 'Hi ' + arabic + ' end';
+    const items = itemizeText(text, {});
+    const covered = items.reduce((s, item) => s + (item.end - item.start), 0);
+    expect(covered).toBe(text.length);
+    // Verify contiguous coverage
+    for (let i = 1; i < items.length; i++) {
+      expect(items[i].start).toBe(items[i - 1].end);
+    }
+  });
+});
+
+describe('shapeTextRuns', () => {
+  it('returns empty array for empty string', () => {
+    expect(shapeTextRuns('', {})).toEqual([]);
+  });
+  it('returns empty array when no backend is set', () => {
+    expect(shapeTextRuns('Hello', {})).toEqual([]);
+  });
+  it('returns empty array when backend is advances-only', () => {
+    setTextShaperBackend({ measureText: (t: string) => t.length });
+    expect(shapeTextRuns('Hello', {})).toEqual([]);
+  });
+  it('returns one ShapedRun per item for a mixed-script string', () => {
+    setTextShaperBackend(_makeShapingBackend());
+    const arabic = 'سلام';
+    const runs = shapeTextRuns('AB' + arabic, {});
+    expect(runs).toHaveLength(2);
+    expect(runs[0].direction).toBe('LeftToRight');
+    expect(runs[1].direction).toBe('RightToLeft');
+  });
+  it('passes per-item direction and script to shapeRun', () => {
+    const captured: { direction?: string; script?: string }[] = [];
+    setTextShaperBackend({
+      measureText: () => 0,
+      shapeRun: (_t: string, _f: Readonly<TextFormat>, opts?: Readonly<ShapeRunOptions>): ShapedRun => {
+        captured.push({ direction: opts?.direction, script: opts?.script });
+        return { ..._emptyRun };
+      },
+    });
+    const arabic = 'سلام';
+    shapeTextRuns('AB' + arabic, {});
+    expect(captured[0].direction).toBe('LeftToRight');
+    expect(captured[1].direction).toBe('RightToLeft');
+    expect(captured[1].script).toBe('Arab');
+  });
+});

package/src/textShaperPool.test.ts

@@ -0,0 +1,36 @@
+import { acquireShapedRun, releaseShapedRun } from './textShaperPool';
+
+describe('acquireShapedRun', () => {
+  it('returns a ShapedRun with the expected shape', () => {
+    const run = acquireShapedRun();
+    expect(typeof run.advanceWidth).toBe('number');
+    expect(Array.isArray(run.glyphs)).toBe(true);
+    releaseShapedRun(run);
+  });
+
+  it('returns a previously released run from the pool', () => {
+    const run = acquireShapedRun();
+    releaseShapedRun(run);
+    const reacquired = acquireShapedRun();
+    // The same object reference should come back when the pool had one entry.
+    expect(reacquired).toBe(run);
+    releaseShapedRun(reacquired);
+  });
+
+  it('allocates a new run when the pool is empty', () => {
+    // Drain any pooled entry.
+    const r1 = acquireShapedRun();
+    const r2 = acquireShapedRun();
+    // Both are valid ShapedRuns.
+    expect(r1).not.toBe(r2);
+    releaseShapedRun(r1);
+    releaseShapedRun(r2);
+  });
+});
+
+describe('releaseShapedRun', () => {
+  it('accepts a run without throwing', () => {
+    const run = acquireShapedRun();
+    expect(() => releaseShapedRun(run)).not.toThrow();
+  });
+});