docs: note that TypeScript applies the browser condition only on opt-in

[sroussey]

The manifest fix in #717 is complete and uniform — every condition branch now pairs its types target with the implementation beside it, and ExportTypesPairing.test.ts enforces that across all 163 branches. But a correct manifest is only half of the story.

TypeScript's condition set is ["import", "types"] under moduleResolution: "bundler" and ["node", "import", "types"] under node16/nodenext. "browser" is in neither, and TypeScript only applies it when the consumer names it in customConditions. So a plain bundler-mode consumer still bundles dist/browser.js while tsc resolves the outer "types" and type-checks it against the node declarations — no error anywhere, and symbols the browser bundle genuinely omits (_testOnly, OpenAI_ImageValidation, OpenAI_ModelSearch in @workglow/openai/ai) still autocomplete and compile, then read undefined at runtime.

The correct manifests do not fix that on their own; they move the drift from the manifest to the consumer's tsconfig. This PR says so where the rule is stated.

Changes

• docs/technical/19-build-system.md — a paragraph in Conditional Exports stating the opt-in, with the tsconfig snippet and examples/web/tsconfig.json as the in-repo example.
• docs/technical/18-multi-runtime-abstraction.md — one sentence on the same claim in the resolution-rules paragraph, linking to the section above.
• packages/test/src/test/util/ExportTypesPairing.test.ts — one assertion that examples/web sets customConditions: ["browser"]. It is the repo's only browser-bundled TypeScript project and it imports packages carrying browser conditions (@workglow/util, @workglow/indexeddb/storage, @workglow/tf-mediapipe/ai); deleting that one line silently reverts it to node declarations with nothing failing. Verified by mutation — removing the line fails the test.

Deliberately not added: a test that string-matches the doc prose. Nothing under packages/test reads docs/, and such a test breaks on rewording without catching any real defect.

Known follow-up (separate repo)

/home/user/builder's packages/app is exactly the consumer described above: tsconfig.app.json is moduleResolution: "bundler" with no customConditions, and it imports @workglow/anthropic/ai, @workglow/deepseek/ai, @workglow/openai/ai and @workglow/tf-mediapipe/ai. It (and the six other bundler-mode tsconfigs there) should gain "customConditions": ["browser"] — a separate PR in a separate repo.

Also out of scope: converging the node and browser barrels (dropping _testOnly from node barrels, exporting browser-safe modules from browser barrels). That is a public-API change across at least 8 provider packages and would obscure the manifest-correctness verification this branch already carries.

Verification

command	result
bun scripts/test.ts util vitest	50 files passed, 731 passed / 10 skipped
bunx prettier --check (18, test file)	clean
bunx prettier --check docs/technical/19-build-system.md	fails — pre-existing, verified unclean on the base commit with the change stashed; the added paragraph itself is prettier-stable
bunx eslint …/ExportTypesPairing.test.ts --max-warnings 0	clean
bunx tsc --showConfig -p examples/web/tsconfig.json	customConditions present

One deviation from the plan: tsconfig.json is JSONC (examples/web/tsconfig.json carries /* Bundler mode */ comments), so a bare JSON.parse throws. The test strips comments first via a small local helper.

---

Generated by Claude Code