feat(browser): provide packaged engine startup defaults

[tamashi095]

Browser consumers can call createEngine({ document }) using the SDK’s packaged scratch Worker, host and AudioContext defaults. Existing factory and URL overrides remain supported, and injected contexts retain their actual TypeScript capabilities. Scratch jobs terminate on completion or failure; running native contexts suspend before host startup.

The scratch Worker ships as a standalone browser module. Strict packed DOM consumers, focused lifecycle tests, headless tests and real packed Vite/Chromium startup pass for default and forwarding Worker factories. The six generated engine artifacts and PCM feed bytes are unchanged. Dedicated Astra medium review PASS after the typed-refusal correction; issue #428 is closed.

Stacked on #398. Adapter consumption is tracked separately in engine-web-adapter#24; app integration uses exact reviewed vendored archives. No npm publication is claimed.

Related: #428.

[tamashi095]

Dedicated Astra medium review — SDK #428

FAIL at 56bbd518. Independent review; no production, spec, generated artifact, or checkout edits. The package-owned default boot works in the retained real packed browser gate, but one product contract and one explicit resource discriminator remain unmet.

Findings

1. P1 — the default scratch path erases typed engine refusals. sdk/src/browser/scratch-worker.ts:30 serializes every failure to only name and message; sdk/src/browser/scratch.ts:86 reconstructs a plain Error. The frozen contract says existing engine refusals and MisoUsageError pass through unchanged. I used the approved real Wasm with document {}: direct scratchBootInWorker rejects with an actual MisoEngineError, phase: "boot", code: "refusedDocument", result: 1, and diagnostics. Routing that same request through the actual Worker entry and actual one-shot helper produces a plain Error whose name is MisoEngineError, with no phase/code/result/diagnostics and failed instanceof MisoEngineError. Callers cannot translate or inspect the refusal using the SDK's established contract. Preserve the supported typed refusal payload and reconstruct its SDK error type at the boundary, without parsing a message string. The focused worker rejection test currently uses a generic invented Failure and cannot catch this. Reproducer and exact output: /private/tmp/dx428-review-refusal.mjs, /private/tmp/dx428-review-refusal.log.

2. P2 — the mandatory timer-cleanup proof does not discriminate a leak. sdk/test/browser-defaults-evals.mjs:14 asserts only worker termination and active worker listeners; it never checks timers or AbortSignal listeners. In an isolated source copy I removed only the actual clearTimeout(timer) in scratchBootWithWorker's final finish path (sdk/src/browser/scratch.ts:58). All 17/17 focused tests still PASS. The leaked default timer keeps the mutant process alive for roughly five seconds, so this is an observable surviving resource, not merely an untested stylistic preference. Gate 2 explicitly requires no surviving timer/listener. Add compact local resource accounting and require this exact mutant to turn red. The advertised late deliveries at test lines 28/43 also iterate the already-empty active listener sets; they do not invoke retained historical callbacks. Capture the actual removed callbacks for that promised stale-event check rather than emitting through an empty set. Baseline and mutation copies/logs: /private/tmp/dx428-review-mutants/green/, /private/tmp/dx428-review-mutants/leaked-timer/, and sibling .log files. The baseline exits 0 and the leak mutant also exits 0.

Independently passing evidence

• bash scripts/check-sdk-types.sh: PASS with unchanged ES2022/WebWorker libs; /private/tmp/dx428-review-types.log.
• node --test sdk/test/browser-defaults-evals.mjs: PASS, 17 tests; /private/tmp/dx428-review-focused.log.
• bash scripts/check-sdk-generated.sh: PASS; /private/tmp/dx428-review-generated.log.
• bash scripts/check-sdk-headless.sh /private/tmp/dx-393-current-artifacts: PASS, 154 passed / 1 existing skip (155 total), incorporating the two later suspension regressions; /private/tmp/dx428-review-headless.log.
• MISO_ENGINE_SDK_BROWSER_TOOLS=/private/tmp/miso-dx-app/node_modules bash scripts/sdk-package.sh check /private/tmp/dx-393-current-artifacts: PASS, including strict packed DOM consumer, thin injected-context negative checks, tarball policy/standalone Worker graph and actual Vite/Chromium boot. Both default and ordinary forwarding factories produce 48000 Hz / 128 frames, status result 0, and final context state closed; forwarding receives exactly the public exported Worker URL and module option. No failed request or HTTP error was observed. Log: /private/tmp/dx428-review-package-browser.log.
• Direct byte comparison of all six staged generated artifacts with the approved artifact directory and all six manifest lengths/digests: PASS. Staged PCM feed equals unchanged source; generated source and PCM have no diff from baseline a0493021. /private/tmp/dx428-review-artifacts.log.

Code inspection confirms independent injected function/URL selection, raw document treatment, retained source refusal/context retry/quantum ordering, suspension before default host construction, and host-before-context idempotent close including dispose rejection. The approved esbuild development-only bundling change keeps the public Worker import-complete without changing generated artifacts. No Rust rebuild, artifact repin, browser matrix, or product/spec changes were made during this review.

The successful packed path is real evidence; it does not waive the two failed frozen requirements. A bounded revision to typed scratch failure transport and the existing focused resource fixture is required before PASS. This verdict makes no npm publication or downstream adapter/app integration claim.

[tamashi095]

Dedicated Astra medium review — SDK #428 attempt 2: PASS

Reviewed clean pushed 9ab79d13 in /private/tmp/miso-dx-sdk-boot, including source correction 2da95d23 and final evidence, against the frozen #428 contract and the two findings in /private/tmp/dx-428-astra-medium-review.md. This is one independent attempt-two verdict. No production, spec or artifact edits were made.

Both reported blockers are corrected. No release-blocking defect found in this bounded revision.

Typed refusal preservation

The actual Worker entry now identifies supported engine/usage failures explicitly. Engine replies carry phase, code, numeric result and diagnostics; the client reconstructs the actual SDK error class and restores the existing message without parsing or formatting it twice. Usage replies reconstruct MisoUsageError. Other Worker errors retain their generic fallback, while caller abort reasons still follow the existing direct path.

I independently reran the previous real-Wasm reproduction with the approved module and document {}. The direct primitive and actual entry/client path both produce instanceof MisoEngineError, phase: "boot", code: "refusedDocument", result: 1 and the same diagnostic rows. Log: /private/tmp/dx428-review-attempt2-refusal.log.

The committed focused regression executes the actual scratchBootInWorker and Worker entry, structured-clones both message directions, and compares class identity, name, complete message, phase/code/result, diagnostics and diagnostic getters against the direct error. It also executes usage-error reconstruction through the entry/client and checks frozen diagnostics. These assertions run in the passing headless gate below.

Resource discriminator

The new compact fixture tracks live timers and AbortSignal subscriptions, retains the actual removed Worker/abort/timer callbacks, and invokes them after success, abort and error settlement. It asserts zero surviving timers/listeners, one request, one observed settlement and one termination. Historical ready/result/error/messageerror callbacks are now actually invoked; they are not emitted through empty active listener sets.

I compared the isolated timer mutant at /private/tmp/dx428-attempt2-timer-9uffw4ye with the current checkout. Its test file is byte-identical; its sole scratch change removes clearTimeout(timer) from finish. Independently rerunning its 19 focused tests exits 1 with 18 pass / 1 fail, at no scratch deadline survives settlement (actual 1, expected 0). Log: /private/tmp/dx428-review-attempt2-timer-mutant.log. The formerly undetected resource leak is now detected by the committed assertion.

Independent gates

• bash scripts/check-sdk-types.sh: PASS; /private/tmp/dx428-review-attempt2-types.log.
• bash scripts/check-sdk-headless.sh /private/tmp/dx-393-current-artifacts: PASS, 156 pass / 1 existing skip / 0 fail, including all 19 default/scratch tests and the real-Wasm typed refusal; /private/tmp/dx428-review-attempt2-headless.log.
• MISO_ENGINE_SDK_BROWSER_TOOLS=/private/tmp/miso-dx-app/node_modules bash scripts/sdk-package.sh check /private/tmp/dx-393-current-artifacts: PASS with localhost/browser permission; generated-surface, strict packed DOM/structural types, standalone Worker graph and real Vite/Chromium consumer all pass. Both default and ordinary forwarding Worker factories boot at 48000 Hz / 128 frames, return status result 0, and close their contexts. Forwarding receives exactly the exported asset URL and module option; observed requests are HTTP 200. Log: /private/tmp/dx428-review-attempt2-package-browser.log.
• Direct comparison confirms all six staged generated artifacts equal the approved input bytes, and every manifest length/digest agrees. Staged PCM prelude equals unchanged source. Log: /private/tmp/dx428-review-attempt2-artifacts.log.
• git diff --check 56bbd518..9ab79d13: PASS. Revision changes only scratch client, scratch Worker, the existing focused eval and issue evidence. Checkout remains clean.

The prior accepted default-host/context/override scope was not broadened or reimplemented. This PASS qualifies the final package-owned SDK boot slice; root still owns the upstream issue-state synchronization and downstream adapter/app integration. It does not claim npm publication or a broader browser/device matrix.