feat(fs-http)!: remove DOM coupling from download/preview (0.3.0) — closes #59

[Goosterhof]

Summary

Closes #59. fs-http should be HTTP transport, not browser download UX. This PR strips all DOM coupling from downloadRequest/previewRequest and moves the <a>-click-revoke dance to @script-development/fs-helpers as triggerDownload(blob, filename). fs-http's tests no longer stub Blob, document, or window.URL.

Why

Per #59, three territories (kendo, ublgenie, emmie) independently discovered that vi.stubGlobal patterns for Blob/document/window.URL are fragile under formatters and require vitest 4 class-based mocks. The right fix isn't a class-mock recipe in every consumer; it's removing the coupling at the source. fs-http no longer touches the DOM in download/preview paths.

Branch base

Rebased onto main after PR #60 (timeout) and PR #61 (content-type narrowing) merged. PR #61's asString helper is dead code under the new API and was dropped in the rebase resolution along with its two defensive tests.

Merge order: this PR → consumer migration campaign.

Changes

fs-http (BREAKING — 0.2.0 → 0.3.0)

• downloadRequest(endpoint, documentName, type?) → AxiosResponse becomes
  downloadRequest(endpoint, options?) → AxiosResponse<Blob>. No DOM side effects.
• previewRequest(endpoint) → string (object URL) becomes
  previewRequest(endpoint, options?) → AxiosResponse<Blob>. Caller manages URL lifecycle.
• Removed HEADERS_TO_TYPE map. The one-entry OOXML lookup did not earn its place in transport code; consumers can supply their own if needed.
• CHANGELOG entry with full migration recipe.

fs-helpers (additive — 0.1.1 → 0.1.2)

• New triggerDownload(blob, filename) export — the <a>-click-revoke dance with the same comment about why click() captures its own ref before revoke.
• happy-dom added to devDependencies (test environment for the new utility).

Cascade widening (workspace coordination, not behavior change)

• fs-adapter-store 0.1.5 → 0.1.6: fs-http peer ^0.1.0 || ^0.2.0 → ^0.1.0 || ^0.2.0 || ^0.3.0.
• fs-loading 0.1.1 → 0.1.2: same widening.

Both packages keep working unchanged — they don't call download/preview. The peer widening is required so the lock resolves fs-http to the workspace 0.3.0 instead of pulling a registry copy of 0.2.0 into nested node_modules/.

Migration recipe (for consumer territories — separate post-publish campaign)

// before (fs-http 0.2.x)
await http.downloadRequest('/files/123/download', 'report.pdf');

// after (fs-http 0.3.x + fs-helpers 0.1.2+)
import {triggerDownload} from '@script-development/fs-helpers';
const {data} = await http.downloadRequest('/files/123/download');
triggerDownload(data, 'report.pdf');

// before (fs-http 0.2.x)
const blobUrl = await http.previewRequest('/files/123/preview');

// after (fs-http 0.3.x)
const {data} = await http.previewRequest('/files/123/preview');
const blobUrl = URL.createObjectURL(data);
// remember to revoke on cleanup: URL.revokeObjectURL(blobUrl)

Audit of production call sites (corrected after @jasperboerhof's review): 5 = 4 in kendo + 1 in ublgenie. Emmie's downloads use its internal vue-services/http workspace package, not @script-development/fs-http, so they are out of scope for this PR's migration. BIO and entreezuil have no production call sites — only mock-server stubs that need a one-line signature update when the version bump lands. Test mocks update to match the new return shape.

Out of scope

• streamRequest's document.cookie XSRF read. This is the only remaining DOM touch in fs-http after this PR. Cleanup would require either a required xsrfHeader option or a cookie-reader middleware shipped alongside — both bigger migrations than fs-http: invert Blob/document-global coupling in downloadRequest for testability #59 asks for. File a separate issue if/when prioritized.
• Consumer territory upgrades. Same pattern as PR feat(fs-http): timeout option with 30000ms default (Doctrine #8 library-author extension) #60: ship fs-http only, migration is a post-publish campaign.
• Switch to workspace:* protocol for internal deps. Would eliminate the cascade-widening tax on every fs-http minor bump. Worth a separate ADR.

CI gates

All 8 gates green locally:

• audit (0 vulnerabilities)
• format:check (oxfmt clean across 133 files)
• lint (oxlint, 0 errors / 0 warnings on 83 files)
• build (tsdown ESM + CJS for all 10 packages)
• typecheck (tsc --noEmit, all packages clean)
• lint:pkg (publint + attw on all 10 packages, 0 problems)
• test:coverage — 430/430 tests across 19 files (was 18/430; +2 in fs-helpers dom-download.spec, net -2 in fs-http after dropping obsolete DOM-orchestration tests). 100% coverage maintained on fs-http and fs-helpers per their thresholds.
• test:mutation — fs-http 97.30% (up from 95.74% pre-refactor — less surface to mutate, fewer survivors); fs-helpers 100% (including the new dom-download.ts)

Test plan

• fs-http unit tests — 45/45 (transport-shape only, no DOM stubs)
• fs-helpers unit tests — triggerDownload covers anchor creation, click, revocation order
• fs-helpers mutation 100%, fs-http mutation 97.30% (≥ 90 threshold)
• Full workspace npm run test:coverage 430/430
• After merge: post-publish campaign — code migration in kendo (4 sites) and ublgenie (1 site); version bump only in BIO + entreezuil (mock-server stub signatures); emmie uses its own vue-services/http, not affected.

Refs

• Issue: fs-http: invert Blob/document-global coupling in downloadRequest for testability #59
• Doctrine memory (war room): feedback_oxfmt_constructor_mocks.md — captures the unsafe-collapse pitfall and class-mock mitigation that motivated the issue.
• Campaign report (war room): campaigns/ublgenie/2026-04-29-oxfmt-prettier-migration.md — narrative of how this surfaced.
• Predecessor PR (this branch is based on): feat(fs-http): timeout option with 30000ms default (Doctrine #8 library-author extension) #60 (fs-http timeout default, 0.1.3 → 0.2.0)

[cloudflare-workers-and-pages]

Deploying fs-packages with    Cloudflare Pages

Latest commit:	a2a167a
Status:	✅  Deploy successful!
Preview URL:	https://0ebafaee.fs-packages.pages.dev
Branch Preview URL:	https://feat-fs-http-remove-dom-coup.fs-packages.pages.dev

View logs

[jasperboerhof]

A few notes from the kendo side after auditing how this lands for us:

1. Call-site count — audit may be off

The PR body says "Audit of production call sites: 5 across kendo/ublgenie/emmie." For kendo alone I count 4:

• frontend/src/apps/tenant/domains/projects/relations/attachments/composables/useAttachmentActions.ts:17 — downloadRequest
• frontend/src/apps/tenant/domains/projects/relations/issues/relations/timeEntries/pages/AllEntries.vue:327 — downloadRequest
• frontend/src/apps/tenant/domains/projects/relations/attachments/components/AttachmentPreviewModal.vue:95 — previewRequest
• frontend/src/apps/tenant/domains/projects/relations/attachments/components/AttachmentThumbnail.vue:148 — previewRequest

That leaves only 1 between ublgenie + emmie combined, which feels low. Worth re-running the audit before the post-publish campaign so a consumer file doesn't slip through.

2. Make downloadRequest's 2nd-arg footgun a hard TS error

The old downloadRequest(endpoint, documentName, type?) and the new downloadRequest(endpoint, options?) have overlapping arity, so a non-migrated call like downloadRequest(url, 'report.pdf') could silently typecheck if options is loose ({} / unknown / an index signature).

Could the RequestOptions type be narrow enough — explicit { timeout?: number; ... } with no string-assignable shape — that the old usage produces a clear "string is not assignable to RequestOptions" error? That's the difference between a 5-minute mechanical migration and a "why are downloads silently broken in prod" debugging session.

3. Heads-up: consumer mocks won't surface the regression

For whoever sweeps consumers: kendo's apps/tenant/services/__mocks__/http.ts already returns AxiosResponse-shaped objects for both downloadRequest and previewRequest, so the mock side will look more correct after 0.3.0, not less. Unit tests stay green even when production call sites are broken.

Migration sweeps should grep production code for previewRequest / downloadRequest directly — don't rely on a red test suite to flag the work.

The merge-base changed after approval.

[Goosterhof]

Thanks @jasperboerhof — addressed all three.

1. Audit count

You're right, my count was wrong. Re-ran the audit and the geography is 4 in kendo + 1 in ublgenie, not three territories. Emmie's downloads call its internal vue-services/http workspace package, not @script-development/fs-http, so they're out of scope for this PR. BIO and entreezuil have only mock-server stubs in test infrastructure — no production sites. PR body now reflects this. The single ublgenie site is resources/js/domains/invoices/pages/Show.vue:215.

2. Old-call-signature → hard TS error

Already structurally satisfied. The new signature is downloadRequest(endpoint: string, options?: AxiosRequestConfig). AxiosRequestConfig is a structural object type (all properties optional, no string-assignable shape), so a non-migrated call like downloadRequest(url, 'report.pdf') produces:

Argument of type 'string' is not assignable to parameter of type 'AxiosRequestConfig<any>'

Verified against the rebased branch's dist/index.d.mts. Mechanical 5-minute migrations, not silent prod breakage.

3. Consumer mocks won't surface the regression

Captured for the post-publish migration brief — will lead with this. Also worth noting: kendo's __mocks__/http.ts will get more correct after 0.3.0, not less, because the new downloadRequest/previewRequest shapes match an AxiosResponse<Blob> mock more cleanly than the old DOM-side-effecting versions. Migration will grep production paths directly (grep -rn "downloadRequest\|previewRequest" src/ --include='*.vue' --include='*.ts'), not rely on test failures.

---

Branch rebased onto current main (PR #60 + #61 already merged); PR #61's asString helper was dead code under the new API and was dropped in the resolution. All 8 gates green locally: 430/430 tests, fs-http mutation 97.30%, fs-helpers 100%, format/lint/typecheck/lint:pkg clean.