Release 2026-02-09: Merge staging with profiling toggle fix

[ysdede]

Merges staging/release-2026-02-09 into release branch.

Includes:

• Merged PRs: Optimize LCS buffer allocation in merger #31, Optimize tokenizer: Pre-compute sanitized tokens #30, Optimize Incremental Mel Calculation #29, Optimize inefficient array slicing in decoding loop #28, Refactor: Derive onnxruntime-web version from runtime environment #26, feat(parakeet): implement LRU eviction for incremental decoder cache #25, Refactor IncrementalMelProcessor.clear to alias reset #23, Refactor JsPreprocessor.process to eliminate duplicate logic #22, Make performance logging conditional in transcribe #21, Refactor src/index.js dynamic imports #20, Remove redundant self.ort assignment #19, Clean up outdated TODO comment in ParakeetModel #18
• Profiling toggle fix in demos (chore/demo-profiling-toggle)

All tests passing (77 tests).

Summary by CodeRabbit

• New Features

  • Added profiling toggle control to demo applications to enable/disable performance monitoring at runtime.
  • Added cache management controls: configurable incremental cache size limit and explicit cache clearing capability.

• Bug Fixes

  • Improved WASM runtime version detection for better compatibility.
  • Enhanced tokenizer performance with optimized token decoding.

• Performance

  • Optimized incremental mel processor with incremental computation support.
  • Reduced memory allocations in cache operations.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@tests/transcribe_perf.test.mjs`:
- Around line 22-24: The mock encoder output shape doesn't match how parakeet.js
extracts the tensor: parakeet code does enc = encOut['outputs'] ??
Object.values(encOut)[0] and then uses enc.dims, so update the test's
mockEncoderSession.run to resolve to a tensor-like object (i.e., the resolved
value should be an object whose top-level properties are dims and data) or
ensure the 'outputs' key itself is the tensor-like object; modify
mockEncoderSession.run.mockResolvedValue accordingly so it returns either {
dims: [1,64,10], data: new Float32Array(640) } or { outputs: { dims: [...],
data: ... } } to match how enc is consumed in parakeet.js (referencing
mockEncoderSession.run, encOut and enc).

🧹 Nitpick comments (2)

tests/index.test.mjs (2)

31-51: Consider adding test coverage for model key resolution.

The fromHub function resolves model keys via MODELS[repoIdOrModelKey]?.repoId (see src/index.js line 33), but this test only covers the pass-through case where the input is not a known model key. Consider adding a test case that verifies the model key resolution path:

it('fromHub should resolve model key to repo ID', async () => {
  // You'd need to mock MODELS or use an actual key from MODELS
  // to verify that the resolved repoId is passed to getParakeetModel
});

---

24-52: Add mock cleanup between tests.

If additional tests are added later, mock state from previous tests could leak and cause flaky behavior. Consider adding:

 describe('index.js', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
   it('fromUrls should call ParakeetModel.fromUrls', async () => {

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Mock encoder output format may not match actual usage.

The mock returns { outputs: { dims: [...], data: ... } }, but in parakeet.js line 543, the code does enc = encOut['outputs'] ?? Object.values(encOut)[0], then later accesses enc.dims. This means enc should be a tensor-like object directly, not a wrapper with dims inside.

Proposed fix for mock format

 const mockEncoderSession = {
-  run: vi.fn().mockResolvedValue({ outputs: { dims: [1, 64, 10], data: new Float32Array(640) } }),
+  run: vi.fn().mockResolvedValue({
+    outputs: new mockOrt.Tensor('float32', new Float32Array(640), [1, 64, 10])
+  }),
 };

🤖 Prompt for AI Agents

In `@tests/transcribe_perf.test.mjs` around lines 22 - 24, The mock encoder output
shape doesn't match how parakeet.js extracts the tensor: parakeet code does enc
= encOut['outputs'] ?? Object.values(encOut)[0] and then uses enc.dims, so
update the test's mockEncoderSession.run to resolve to a tensor-like object
(i.e., the resolved value should be an object whose top-level properties are
dims and data) or ensure the 'outputs' key itself is the tensor-like object;
modify mockEncoderSession.run.mockResolvedValue accordingly so it returns either
{ dims: [1,64,10], data: new Float32Array(640) } or { outputs: { dims: [...],
data: ... } } to match how enc is consumed in parakeet.js (referencing
mockEncoderSession.run, encOut and enc).

[ysdede]

Post-merge review of all PRs included in this staging branch

All PRs in this branch (#18-#31) were created by Google Jules (coding agent). I reviewed every diff for correctness, backward compatibility, and potential risks. Below is the full assessment.

---

Safe -- No Issues Found

PR	Change	Verdict
#18	Remove outdated TODO comment	Harmless cleanup, zero risk
#19	Remove redundant self.ort assignment	Harmless cleanup, zero risk
#23	clear() becomes alias for reset()	Trivial DRY improvement, test updated
#22	Refactor JsPreprocessor.process to reuse computeRawMel + normalizeFeatures	Good refactor, eliminates 97 lines of duplication
#30	Pre-compute sanitized tokens in tokenizer constructor	Clean hot-path optimization, measurable speedup
#29	Optimize incremental mel with startFrame parameter	Best of 3 competing mel PRs, correct and well-tested
#31	Reuse LCS buffer in merger	Correct typed-array reuse, reduces GC pressure

---

Needs Attention -- Issues Filed

#28 - slice() to subarray() in decoding loop (Low-Medium risk)
subarray() returns a view into the original buffer, not a copy. Currently safe (read-only use), but if anyone later mutates tokenLogits or durLogits in-place (temperature scaling, softmax, etc.), they will silently corrupt the joiner output buffer. Needs a safety comment at the call site.

• Issue: Add safety comment for subarray view in decoding loop #37

#20 - Dynamic imports replaced with static imports (Medium risk)
The original dynamic import() calls enabled lazy loading / code-splitting. Static top-level imports mean all modules load eagerly. Fine for bundlers with tree-shaking, but loses code-splitting for non-bundled ESM, CDN usage, or serverless. The agent did not acknowledge this trade-off.

• Issue: Evaluate static vs dynamic imports trade-off in index.js #38

#21 - Performance logging made conditional (Medium-High risk, handled by @ysdede)
perfEnabled changed from true (always) to debug || enableProfiling (off by default). This is a breaking API change: result.metrics is now null by default. Any code reading result.metrics.total_ms without a null check will crash. Fixed separately via the chore/demo-profiling-toggle branch merged into this staging.

#25 - LRU eviction for incremental decoder cache (Medium risk)
Good fix for unbounded memory growth, but eviction is completely silent. No log or warning when entries are dropped. For multi-stream apps, this can cause invisible performance degradation as the incremental path falls back to full recomputation. Default of 50 may also need tuning guidance.

• Issue: Add eviction logging and docs for incremental decoder LRU cache #35

#26 - Derive ort version from runtime (Medium-High risk)
Replaces hardcoded version with ort.env.versions?.common. If that property doesn't exist (older ort versions, custom builds), the code throws, completely blocking initialization. The old hardcoded value always worked. Needs a fallback + warning instead of a hard throw.

• Issue: Add fallback for ort version detection in backend.js #36

---

Excluded PRs (correct decisions)

PR	Reason
#33	CodeRabbit auto-generated tests -- tests were failing
#24	Superseded by #29 (same mel optimization, less complete)
#27	Superseded by #29 (same mel optimization, less complete)

---

Overall Assessment

The agent produced reasonable, well-tested changes. Most are genuinely useful (mel optimization, tokenizer speedup, LRU cache, deduplication). However, it was too eager to "improve" things without considering backward compatibility:

• Two changes introduce potential runtime failures for existing users (Make performance logging conditional in transcribe #21, Refactor: Derive onnxruntime-web version from runtime environment #26)
• One removes a code-splitting boundary without acknowledging the trade-off (Refactor src/index.js dynamic imports #20)
• One introduces a fragile invariant without documentation (Optimize inefficient array slicing in decoding loop #28)
• One adds useful functionality but with zero observability (feat(parakeet): implement LRU eviction for incremental decoder cache #25)

Recommendation: Address issues #35, #36, #37, #38 before merging this staging branch into release. #36 (ort version fallback) is the highest priority since it can cause hard failures.