@flighthq/textshaper 0.3.0-next.906.07cea63 → 0.3.0

package/dist/contract.d.ts

@@ -1,3 +1,4 @@
+export * from './enableTextShaperGuards';
 export * from './textShaper';
 export * from './textShaperCache';
 export * from './textShaperCluster';

package/dist/contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC"}

package/dist/contract.js

@@ -1,3 +1,4 @@
+export * from './enableTextShaperGuards';
 export * from './textShaper';
 export * from './textShaperCache';
 export * from './textShaperCluster';

package/dist/contract.js.map

@@ -1 +1 @@
-{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC"}

package/dist/enableTextShaperGuards.d.ts

@@ -0,0 +1,13 @@
+/** Uninstalls the guard installed by `enableTextShaperGuards`. */
+export declare function disableTextShaperGuards(): void;
+/**
+ * Installs the caller-facing shaped-run pool guard (opt-in, dev-only). `acquireShapedRun` and
+ * `releaseShapedRun` are paired brackets: each acquired run must be released exactly once and must not
+ * be used afterwards. Core already ignores a repeated release to preserve the pool invariant, but that
+ * silent recovery otherwise hides the caller bug that unbalanced the bracket.
+ *
+ * The guard warns once through `@flighthq/log`. Not importing this module costs production nothing: the
+ * message and logging dependency live only here, while the pool keeps a null callback by default.
+ */
+export declare function enableTextShaperGuards(): void;
+//# sourceMappingURL=enableTextShaperGuards.d.ts.map

package/dist/enableTextShaperGuards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enableTextShaperGuards.d.ts","sourceRoot":"","sources":["../src/enableTextShaperGuards.ts"],"names":[],"mappings":"AAMA,kEAAkE;AAClE,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C"}

package/dist/enableTextShaperGuards.js

@@ -0,0 +1,25 @@
+import { logOnce } from '@flighthq/log/contract';
+import { LogLevel } from '@flighthq/types/contract';
+import { setShapedRunReleaseGuard } from './textShaperPool';
+/** Uninstalls the guard installed by `enableTextShaperGuards`. */
+export function disableTextShaperGuards() {
+    setShapedRunReleaseGuard(null);
+}
+/**
+ * Installs the caller-facing shaped-run pool guard (opt-in, dev-only). `acquireShapedRun` and
+ * `releaseShapedRun` are paired brackets: each acquired run must be released exactly once and must not
+ * be used afterwards. Core already ignores a repeated release to preserve the pool invariant, but that
+ * silent recovery otherwise hides the caller bug that unbalanced the bracket.
+ *
+ * The guard warns once through `@flighthq/log`. Not importing this module costs production nothing: the
+ * message and logging dependency live only here, while the pool keeps a null callback by default.
+ */
+export function enableTextShaperGuards() {
+    setShapedRunReleaseGuard(warnOnDoubleRelease);
+}
+function warnOnDoubleRelease(_run) {
+    logOnce('textshaper:double-release', LogLevel.Warn, {
+        message: 'releaseShapedRun: this run is already in the pool, so it is being released twice. The repeated release was ignored to preserve the pool, but it indicates an unbalanced bracket. Every acquireShapedRun call must pair with exactly one releaseShapedRun call, and the run must not be used after release.',
+    }, 'textshaper');
+}
+//# sourceMappingURL=enableTextShaperGuards.js.map

package/dist/enableTextShaperGuards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enableTextShaperGuards.js","sourceRoot":"","sources":["../src/enableTextShaperGuards.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAEjD,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAEpD,OAAO,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAE5D,kEAAkE;AAClE,MAAM,UAAU,uBAAuB;IACrC,wBAAwB,CAAC,IAAI,CAAC,CAAC;AACjC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,sBAAsB;IACpC,wBAAwB,CAAC,mBAAmB,CAAC,CAAC;AAChD,CAAC;AAED,SAAS,mBAAmB,CAAC,IAAyB;IACpD,OAAO,CACL,2BAA2B,EAC3B,QAAQ,CAAC,IAAI,EACb;QACE,OAAO,EACL,4SAA4S;KAC/S,EACD,YAAY,CACb,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { acquireShapedRun, clearShapedRun, clearTextShaperCache, createShapedRun, createTextShaperCache, disposeTextShaperCache, disposeTextShaperSignals, enableTextShaperSignals, getCaretPositionsForRun, getClusterForIndex, getCodePointForGlyph, getFontMetrics, getFontMetricsInto, getFontUnitScale, getGlyphExtents, getGlyphExtentsBatch, getGlyphExtentsInto, getGlyphIndexForCodePoint, getGlyphName, getIndexRangeForCluster, getTextShaperSignals, itemizeText, measureText, releaseShapedRun, shapeTextRun, shapeTextRunCached, shapeTextRunInto, shapeTextRuns, } from './contract';
+export { acquireShapedRun, clearShapedRun, clearTextShaperCache, createShapedRun, createTextShaperCache, disposeTextShaperCache, disposeTextShaperSignals, disableTextShaperGuards, enableTextShaperGuards, enableTextShaperSignals, getCaretPositionsForRun, getClusterForIndex, getCodePointForGlyph, getFontMetrics, getFontMetricsInto, getFontUnitScale, getGlyphExtents, getGlyphExtentsBatch, getGlyphExtentsInto, getGlyphIndexForCodePoint, getGlyphName, getIndexRangeForCluster, getTextShaperSignals, itemizeText, measureText, releaseShapedRun, shapeTextRun, shapeTextRunCached, shapeTextRunInto, shapeTextRuns, } from './contract';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,oBAAoB,EACpB,eAAe,EACf,qBAAqB,EACrB,sBAAsB,EACtB,wBAAwB,EACxB,uBAAuB,EACvB,uBAAuB,EACvB,kBAAkB,EAClB,oBAAoB,EACpB,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACnB,yBAAyB,EACzB,YAAY,EACZ,uBAAuB,EACvB,oBAAoB,EACpB,WAAW,EACX,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,GACd,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,oBAAoB,EACpB,eAAe,EACf,qBAAqB,EACrB,sBAAsB,EACtB,wBAAwB,EACxB,uBAAuB,EACvB,sBAAsB,EACtB,uBAAuB,EACvB,uBAAuB,EACvB,kBAAkB,EAClB,oBAAoB,EACpB,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACnB,yBAAyB,EACzB,YAAY,EACZ,uBAAuB,EACvB,oBAAoB,EACpB,WAAW,EACX,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,GACd,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,2 +1,2 @@
-export { acquireShapedRun, clearShapedRun, clearTextShaperCache, createShapedRun, createTextShaperCache, disposeTextShaperCache, disposeTextShaperSignals, enableTextShaperSignals, getCaretPositionsForRun, getClusterForIndex, getCodePointForGlyph, getFontMetrics, getFontMetricsInto, getFontUnitScale, getGlyphExtents, getGlyphExtentsBatch, getGlyphExtentsInto, getGlyphIndexForCodePoint, getGlyphName, getIndexRangeForCluster, getTextShaperSignals, itemizeText, measureText, releaseShapedRun, shapeTextRun, shapeTextRunCached, shapeTextRunInto, shapeTextRuns, } from './contract';
+export { acquireShapedRun, clearShapedRun, clearTextShaperCache, createShapedRun, createTextShaperCache, disposeTextShaperCache, disposeTextShaperSignals, disableTextShaperGuards, enableTextShaperGuards, enableTextShaperSignals, getCaretPositionsForRun, getClusterForIndex, getCodePointForGlyph, getFontMetrics, getFontMetricsInto, getFontUnitScale, getGlyphExtents, getGlyphExtentsBatch, getGlyphExtentsInto, getGlyphIndexForCodePoint, getGlyphName, getIndexRangeForCluster, getTextShaperSignals, itemizeText, measureText, releaseShapedRun, shapeTextRun, shapeTextRunCached, shapeTextRunInto, shapeTextRuns, } from './contract';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,oBAAoB,EACpB,eAAe,EACf,qBAAqB,EACrB,sBAAsB,EACtB,wBAAwB,EACxB,uBAAuB,EACvB,uBAAuB,EACvB,kBAAkB,EAClB,oBAAoB,EACpB,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACnB,yBAAyB,EACzB,YAAY,EACZ,uBAAuB,EACvB,oBAAoB,EACpB,WAAW,EACX,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,GACd,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,oBAAoB,EACpB,eAAe,EACf,qBAAqB,EACrB,sBAAsB,EACtB,wBAAwB,EACxB,uBAAuB,EACvB,sBAAsB,EACtB,uBAAuB,EACvB,uBAAuB,EACvB,kBAAkB,EAClB,oBAAoB,EACpB,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACnB,yBAAyB,EACzB,YAAY,EACZ,uBAAuB,EACvB,oBAAoB,EACpB,WAAW,EACX,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,GACd,MAAM,YAAY,CAAC"}

package/dist/textShaperPool.d.ts

@@ -1,4 +1,8 @@
 import type { ShapedRun } from '@flighthq/types/contract';
 export declare function acquireShapedRun(): ShapedRun;
 export declare function releaseShapedRun(run: ShapedRun): void;
+/** Installs the shaped-run release guard, or clears it with `null`. The seam keeps warning text and the
+ *  `@flighthq/log` dependency in the separately importable guard module. Use `enableTextShaperGuards`
+ *  rather than installing a callback directly in application code. */
+export declare function setShapedRunReleaseGuard(guard: ((run: Readonly<ShapedRun>) => void) | null): void;
 //# sourceMappingURL=textShaperPool.d.ts.map

package/dist/textShaperPool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"textShaperPool.d.ts","sourceRoot":"","sources":["../src/textShaperPool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAU1D,wBAAgB,gBAAgB,IAAI,SAAS,CAG5C;AAID,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,SAAS,GAAG,IAAI,CAIrD"}
+{"version":3,"file":"textShaperPool.d.ts","sourceRoot":"","sources":["../src/textShaperPool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAU1D,wBAAgB,gBAAgB,IAAI,SAAS,CAK5C;AASD,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,SAAS,GAAG,IAAI,CASrD;AAED;;sEAEsE;AACtE,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,CAAC,CAAC,GAAG,EAAE,QAAQ,CAAC,SAAS,CAAC,KAAK,IAAI,CAAC,GAAG,IAAI,GAAG,IAAI,CAEjG"}

package/dist/textShaperPool.js

@@ -6,19 +6,41 @@ import { createShapedRun } from './textShaperRun';
 // The returned run is in an unspecified state — always populate it before use (e.g. via
 // `shapeTextRunInto`).
 export function acquireShapedRun() {
-    if (_pool.length > 0)
-        return _pool.pop();
-    return createShapedRun();
+    const pooled = _pool.pop();
+    if (pooled === undefined)
+        return createShapedRun();
+    _pooled.delete(pooled);
+    return pooled;
 }
 // Returns a ShapedRun to the pool. The run must not be used after release. Pairs with
 // `acquireShapedRun`. Runs released beyond the pool capacity are silently discarded (GC-collected).
+//
+// Releasing a run that is already pooled is ignored rather than honoured. Without that check the run
+// sits in the pool twice, and the next two acquires hand the same object to two callers who then shape
+// into one buffer -- corruption that surfaces as wrong glyphs far from its cause. Ignoring keeps the
+// pool invariant (an entry appears at most once) intact whatever the caller does.
 export function releaseShapedRun(run) {
+    if (_pooled.has(run)) {
+        _releaseGuard?.(run);
+        return;
+    }
     if (_pool.length < _POOL_MAX_SIZE) {
         _pool.push(run);
+        _pooled.add(run);
     }
 }
+/** Installs the shaped-run release guard, or clears it with `null`. The seam keeps warning text and the
+ *  `@flighthq/log` dependency in the separately importable guard module. Use `enableTextShaperGuards`
+ *  rather than installing a callback directly in application code. */
+export function setShapedRunReleaseGuard(guard) {
+    _releaseGuard = guard;
+}
 // Maximum number of ShapedRuns to retain in the pool before discarding on release. Keeps
 // memory bounded in cases where burst shaping produces many runs.
 const _POOL_MAX_SIZE = 64;
 const _pool = [];
+// Membership mirror for `_pool`, so the double-release check is O(1) rather than scanning the pool on
+// every release. Weak so a run dropped past capacity stays collectable.
+const _pooled = new WeakSet();
+let _releaseGuard = null;
 //# sourceMappingURL=textShaperPool.js.map

package/dist/textShaperPool.js.map

@@ -1 +1 @@
-{"version":3,"file":"textShaperPool.js","sourceRoot":"","sources":["../src/textShaperPool.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAElD,mFAAmF;AACnF,oFAAoF;AACpF,0FAA0F;AAC1F,EAAE;AACF,wFAAwF;AACxF,uBAAuB;AACvB,MAAM,UAAU,gBAAgB;IAC9B,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,EAAG,CAAC;IAC1C,OAAO,eAAe,EAAE,CAAC;AAC3B,CAAC;AAED,sFAAsF;AACtF,oGAAoG;AACpG,MAAM,UAAU,gBAAgB,CAAC,GAAc;IAC7C,IAAI,KAAK,CAAC,MAAM,GAAG,cAAc,EAAE,CAAC;QAClC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAClB,CAAC;AACH,CAAC;AAED,yFAAyF;AACzF,kEAAkE;AAClE,MAAM,cAAc,GAAG,EAAE,CAAC;AAC1B,MAAM,KAAK,GAAgB,EAAE,CAAC"}
+{"version":3,"file":"textShaperPool.js","sourceRoot":"","sources":["../src/textShaperPool.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAElD,mFAAmF;AACnF,oFAAoF;AACpF,0FAA0F;AAC1F,EAAE;AACF,wFAAwF;AACxF,uBAAuB;AACvB,MAAM,UAAU,gBAAgB;IAC9B,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,EAAE,CAAC;IAC3B,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,eAAe,EAAE,CAAC;IACnD,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACvB,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,sFAAsF;AACtF,oGAAoG;AACpG,EAAE;AACF,qGAAqG;AACrG,uGAAuG;AACvG,qGAAqG;AACrG,kFAAkF;AAClF,MAAM,UAAU,gBAAgB,CAAC,GAAc;IAC7C,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;QACrB,aAAa,EAAE,CAAC,GAAG,CAAC,CAAC;QACrB,OAAO;IACT,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,GAAG,cAAc,EAAE,CAAC;QAClC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAChB,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;sEAEsE;AACtE,MAAM,UAAU,wBAAwB,CAAC,KAAkD;IACzF,aAAa,GAAG,KAAK,CAAC;AACxB,CAAC;AAED,yFAAyF;AACzF,kEAAkE;AAClE,MAAM,cAAc,GAAG,EAAE,CAAC;AAC1B,MAAM,KAAK,GAAgB,EAAE,CAAC;AAC9B,sGAAsG;AACtG,wEAAwE;AACxE,MAAM,OAAO,GAAG,IAAI,OAAO,EAAa,CAAC;AACzC,IAAI,aAAa,GAAgD,IAAI,CAAC"}

package/package.json

@@ -1,6 +1,8 @@
 {
   "name": "@flighthq/textshaper",
-  "version": "0.3.0-next.906.07cea63",
+  "version": "0.3.0",
+  "author": "Joshua Granick and other contributors",
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/flighthq/flight.git",
@@ -36,8 +38,9 @@
     "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
   },
   "dependencies": {
-    "@flighthq/signals": "0.3.0-next.906.07cea63",
-    "@flighthq/types": "0.3.0-next.906.07cea63"
+    "@flighthq/log": "0.3.0",
+    "@flighthq/signals": "0.3.0",
+    "@flighthq/types": "0.3.0"
   },
   "devDependencies": {
     "typescript": "^5.3.0"

package/src/enableTextShaperGuards.test.ts

@@ -0,0 +1,62 @@
+import { addLogSink, createMemoryLogSink, getMemoryLogSinkEntries, removeLogSink } from '@flighthq/log/contract';
+import type { LogEntry } from '@flighthq/types/contract';
+import { describe, expect, it } from 'vitest';
+
+import { disableTextShaperGuards, enableTextShaperGuards } from './enableTextShaperGuards';
+import { acquireShapedRun, releaseShapedRun } from './textShaperPool';
+
+function captureLog(run: () => void): readonly LogEntry[] {
+  const sink = createMemoryLogSink(8);
+  addLogSink(sink.sink);
+  try {
+    run();
+    return getMemoryLogSinkEntries(sink);
+  } finally {
+    removeLogSink(sink.sink);
+  }
+}
+
+describe('disableTextShaperGuards', () => {
+  it('stops repeated releases from reporting', () => {
+    const entries = captureLog(() => {
+      enableTextShaperGuards();
+      disableTextShaperGuards();
+      const run = acquireShapedRun();
+      releaseShapedRun(run);
+      releaseShapedRun(run);
+    });
+    expect(entries).toEqual([]);
+  });
+});
+
+describe('enableTextShaperGuards', () => {
+  it('warns when one acquired run is released twice', () => {
+    const entries = captureLog(() => {
+      enableTextShaperGuards();
+      try {
+        const run = acquireShapedRun();
+        releaseShapedRun(run);
+        releaseShapedRun(run);
+      } finally {
+        disableTextShaperGuards();
+      }
+    });
+    expect(entries).toHaveLength(1);
+    const data = entries[0].data;
+    expect(typeof data === 'string' ? data : String(data.message)).toContain('released twice');
+  });
+
+  it('stays silent for correctly paired acquire and release calls', () => {
+    const entries = captureLog(() => {
+      enableTextShaperGuards();
+      try {
+        const run = acquireShapedRun();
+        releaseShapedRun(run);
+        releaseShapedRun(acquireShapedRun());
+      } finally {
+        disableTextShaperGuards();
+      }
+    });
+    expect(entries).toEqual([]);
+  });
+});

package/src/textShaperPool.test.ts

@@ -1,4 +1,4 @@
-import { acquireShapedRun, releaseShapedRun } from './textShaperPool';
+import { acquireShapedRun, releaseShapedRun, setShapedRunReleaseGuard } from './textShaperPool';
 
 describe('acquireShapedRun', () => {
   it('returns a ShapedRun with the expected shape', () => {
@@ -33,4 +33,72 @@ describe('releaseShapedRun', () => {
     const run = acquireShapedRun();
     expect(() => releaseShapedRun(run)).not.toThrow();
   });
+
+  // A pool entry must appear at most once. Honouring a second release put the run in twice, so the
+  // next two acquires handed one object to two callers who then shaped into the same buffer -- the
+  // failure shows up as wrong glyphs somewhere else entirely.
+  it('ignores a second release of the same run, so two acquires stay distinct', () => {
+    const run = acquireShapedRun();
+    releaseShapedRun(run);
+    releaseShapedRun(run);
+
+    const first = acquireShapedRun();
+    const second = acquireShapedRun();
+
+    expect(first).not.toBe(second);
+  });
+
+  // The membership record has to be cleared on the way out, or a run legitimately re-released after a
+  // later acquire is mistaken for a double release and silently dropped from the pool.
+  it('accepts a release again after the run has been re-acquired', () => {
+    const run = acquireShapedRun();
+    releaseShapedRun(run);
+    const reacquired = acquireShapedRun();
+    expect(reacquired).toBe(run);
+
+    releaseShapedRun(reacquired);
+    expect(acquireShapedRun()).toBe(run);
+  });
+
+  it('keeps distinct runs distinct through an acquire-release cycle', () => {
+    const first = acquireShapedRun();
+    const second = acquireShapedRun();
+    releaseShapedRun(first);
+    releaseShapedRun(second);
+
+    const a = acquireShapedRun();
+    const b = acquireShapedRun();
+
+    expect(a).not.toBe(b);
+  });
+});
+
+describe('setShapedRunReleaseGuard', () => {
+  it('reports a repeated release after core detects it', () => {
+    const seen: unknown[] = [];
+    const run = acquireShapedRun();
+    setShapedRunReleaseGuard((released) => seen.push(released));
+    try {
+      releaseShapedRun(run);
+      releaseShapedRun(run);
+      expect(seen).toEqual([run]);
+    } finally {
+      setShapedRunReleaseGuard(null);
+      releaseShapedRun(acquireShapedRun());
+    }
+  });
+
+  it('stays silent for paired reuse and after being cleared', () => {
+    const seen: unknown[] = [];
+    const run = acquireShapedRun();
+    setShapedRunReleaseGuard((released) => seen.push(released));
+    releaseShapedRun(run);
+    const reacquired = acquireShapedRun();
+    releaseShapedRun(reacquired);
+    expect(seen).toEqual([]);
+
+    setShapedRunReleaseGuard(null);
+    releaseShapedRun(reacquired);
+    expect(seen).toEqual([]);
+  });
 });