@flighthq/textshaper 0.3.0-next.1315.1d4eb64 → 0.3.0-next.1392.f0bd0cc

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,CAK5C;AASD,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,SAAS,GAAG,IAAI,CAMrD"}
+{"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

@@ -20,13 +20,21 @@ export function acquireShapedRun() {
 // 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))
+    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;
@@ -34,4 +42,5 @@ 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,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;QAAE,OAAO;IAC7B,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,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"}
+{"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,6 @@
 {
   "name": "@flighthq/textshaper",
-  "version": "0.3.0-next.1315.1d4eb64",
+  "version": "0.3.0-next.1392.f0bd0cc",
   "repository": {
     "type": "git",
     "url": "https://github.com/flighthq/flight.git",
@@ -36,8 +36,9 @@
     "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
   },
   "dependencies": {
-    "@flighthq/signals": "0.3.0-next.1315.1d4eb64",
-    "@flighthq/types": "0.3.0-next.1315.1d4eb64"
+    "@flighthq/log": "0.3.0-next.1392.f0bd0cc",
+    "@flighthq/signals": "0.3.0-next.1392.f0bd0cc",
+    "@flighthq/types": "0.3.0-next.1392.f0bd0cc"
   },
   "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', () => {
@@ -72,3 +72,33 @@ describe('releaseShapedRun', () => {
     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([]);
+  });
+});