Build JS bridge from source

[leehack]

Summary

Closes #14.

• Split editable bridge wrapper sources into js/src/ and generate checked-in browser assets under js/.
• Add an esbuild/TypeScript JS build pipeline (npm run check:js) that type-checks source, regenerates readable ESM outputs, copies declarations, and syntax-checks generated files.
• Wire CI, publish, and native bridge builds to validate generated JS/DTS assets and publish the declaration file.
• Tighten developer docs and guardrails around generated outputs, exact JS tool pins, publish CDN URLs, and local validation.

Deep review cleanups included

• Preserve lazy BigInt(...) initialization for streamed FS writes so non-BigInt paths keep prior behavior.
• Expand public .d.ts coverage for real config keys, token callback semantics, state load return types, and supportsSafariAdaptiveGpu.
• Add source-specific generated-file banners for bridge, worker, and declaration outputs.
• Pin JS dev dependencies exactly and make build_bridge.sh use npm ci --include=dev --ignore-scripts when bootstrapping.
• Check full native prerequisites before build_bridge.sh auto-installs JS dependencies.

Validation

• npm run check:js
• npm ci --include=dev --ignore-scripts --dry-run
• python3 -m py_compile scripts/verify_state_persistence_api.py scripts/verify_ci_reliability.py scripts/state_persistence_browser_smoke.py
• python3 scripts/verify_state_persistence_api.py
• python3 scripts/verify_ci_reliability.py
• ./scripts/build_bridge.sh --help smoke
• git diff --check
• Delegated deep reviews for build/CI/publish, JS runtime compatibility, docs/DX, plus final regression review: no blockers found.

Review follow-up

Addressed Copilot's comments in cd95f70:

• Disable worker mode for any provided coreModuleFactory, including promised factories.
• Check cmake before build_bridge.sh can auto-install JS dependencies.
• Include js/src/**/*.d.ts in the TypeScript validation gate so declaration syntax/types are parsed before publishing.
• Resolved the handled review threads after local verification.

Downstream llamadart validation

Validated the successful PR artifact from CI run 25941537878 against /opt/UnitySrc/personal/llama/llamadart:

• Downloaded webgpu-bridge-dist for head cd95f7053264e7f17b0dce8592e45e4fe0b37c9f and verified it contains bridge JS, worker JS, .d.ts, wasm32, and wasm64 assets.
• Ran tool/testing/playwright_bridge_smoke.py against the PR artifact JS served under /webgpu_bridge/.
• Ran dart analyze lib/src/backends/webgpu test/integration/backends/webgpu.
• Ran dart test -p chrome test/integration/backends/webgpu/webgpu_engine_multimodal_browser_integration_test.dart.
• Copied the PR artifact into llamadart/example/chat_app/web/webgpu_bridge/, built the Flutter web chat app with flutter build web --base-href=/example/chat_app/build/web/, and ran tool/testing/playwright_chat_app_real_model_smoke.py against Qwen3.5-0.8B-Q4_K_M GGUF; observed response: 2+2 equals 4.

Local llamadart bridge assets were restored after the smoke; no downstream repo changes were left behind.

Notes

• Full wasm/browser smoke is left to CI because this branch primarily changes the JS source/build/publish pipeline and docs.
• Local npm emits machine-specific always-auth deprecation warnings from user npm config; the commands still pass.

[Copilot]

Pull request overview

This PR adds a JavaScript build pipeline for the WebGPU bridge so editable bridge sources live under js/src/ while checked-in browser assets remain under js/ for downstream/CDN compatibility.

Changes:

• Adds npm/esbuild/TypeScript tooling and generated JS/DTS bridge assets.
• Updates CI, publish, and native build scripts to validate and ship generated bridge outputs.
• Updates docs and static verification scripts for the new JS build workflow.

Reviewed changes

Copilot reviewed 13 out of 19 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
.github/workflows/ci.yml	Adds Node setup and JS bridge validation to CI.
.github/workflows/publish_assets.yml	Validates JS assets and publishes the new declaration file.
.gitignore	Ignores local npm dependencies.
AGENTS.md	Updates agent validation guidance for the JS build gate.
CONTRIBUTING.md	Documents JS build prerequisites and validation commands.
README.md	Documents source/generated bridge layout, build steps, and CDN assets.
package.json	Defines JS build, typecheck, syntax-check scripts and dev dependencies.
package-lock.json	Locks JS build tooling dependencies.
tsconfig.bridge.json	Adds TypeScript checkJs configuration for bridge source.
scripts/build_js_bridge.mjs	Generates bundled bridge assets and copies declarations.
scripts/build_bridge.sh	Runs JS validation and copies .d.ts into dist.
scripts/verify_ci_reliability.py	Extends static workflow/build contract checks for JS assets.
scripts/verify_state_persistence_api.py	Points state-persistence checks at bridge source.
js/src/llama_webgpu_bridge.js	Adds editable bridge runtime source.
js/src/llama_webgpu_bridge.d.ts	Adds editable public declaration source.
js/src/llama_webgpu_bridge_worker.js	Adds editable worker entry source.
js/llama_webgpu_bridge.js	Generated browser ESM bridge bundle.
js/llama_webgpu_bridge.d.ts	Generated public declaration asset.
js/llama_webgpu_bridge_worker.js	Generated worker entry asset.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.