mokosh/globals.d.ts

// globals.d.ts — Plan 01-11 ambient declarations for Vite `define`
// text-replacement tokens.
//
// `__MOKOSH_UAT__` is a build-time boolean token replaced by Vite's
// `define` config (vite.config.ts sets it `false`, vite.test.config.ts
// overrides it to `true`). The token gates the test-hook dynamic
// imports in src/background/index.ts + src/offscreen/recorder.ts;
// production builds tree-shake the entire `if (__MOKOSH_UAT__)` block
// because Rollup recognizes `if (false)` as a static dead branch.
//
// Declaring the symbol here keeps the src/ tree type-clean under
// `npx tsc --noEmit` without spreading per-file ambient declarations.
//
// References:
//   - Vite define: https://vite.dev/config/shared-options.html#define
//   - TypeScript ambient declarations:
//     https://www.typescriptlang.org/docs/handbook/declaration-files/templates/global-modifying-module-d-ts.html

declare const __MOKOSH_UAT__: boolean;

// Plan 01-10 must_have #9 path-A swap-in (landed 2026-05-20):
// ambient declaration for Vite `?url` asset imports. The `?url`
// suffix instructs Vite to emit the asset to `dist/assets/<hash>.<ext>`
// and replace the import with the hashed asset URL as a string at
// build time. We declare the wildcard module so TypeScript accepts
// the import without spreading per-file `vite/client` triple-slash
// directives.
//
// References:
//   - Vite explicit URL imports:
//     https://vite.dev/guide/assets.html#explicit-url-imports
//   - TypeScript ambient module declarations:
//     https://www.typescriptlang.org/docs/handbook/modules/reference.html#ambient-modules
declare module '*.svg?url' {
  const url: string;
  export default url;
}

// Plan 04-06 — Vite `?raw` import for SVG-as-string. The `?raw` query
// suffix instructs Vite to bundle the resolved module's CONTENTS verbatim
// as a UTF-8 string at build time (not a hashed asset URL). Used by
// src/welcome/welcome.ts populateMark to inline-inject the canonical
// mokosh-mark.svg via DOMParser + replaceChildren — required by the
// UI-SPEC dark-logo `currentColor` strategy (Option A), because
// `currentColor` only inherits the parent CSS `color` cascade when the
// <svg> lives in the host document's DOM (an <img>-rendered SVG runs in
// an isolated SVG document context where the parent cascade does not
// reach it; W3C SVG2 §13.3). Mirrors the existing `*.svg?url` ambient
// decl above; both forms can coexist for different consumers.
//
// References:
//   - https://vite.dev/guide/assets.html#importing-asset-as-string
//   - .planning/phases/04-harden-clean-up-optional/04-UI-SPEC.md
//     §"Implementation amendment"
declare module '*.svg?raw' {
  const raw: string;
  export default raw;
}

// Plan 04-08 — Vite `?url` import for bundled test-only WebM fixture
// (tests/uat/fixtures/synthetic-display-source.webm). Mirrors the
// Plan 01-10 mokosh-mark.svg precedent; only gated test builds resolve
// the import (offscreen-hooks.ts is tree-shaken in production per
// `__MOKOSH_UAT__`). The hashed asset path emitted into
// `dist-test/assets/<hash>.webm` is authorized for chrome-extension://
// scheme access via the explicit `assets/*.webm` web_accessible_resources
// entry in manifest.json (also a Plan 04-08 addition).
declare module '*.webm?url' {
  const url: string;
  export default url;
}