@godot-scene-web/html 0.1.0

package/dist/runtime.d.ts

@@ -0,0 +1,225 @@
+import { L as StaticImageSwapCounters, a as parseParticleSpecConfig, b as GodotHtmlRuntimeOptions, c as ParticleRuntimeStats, i as normalizeParticleSpecConfig, l as createParticleRuntime, nt as GodotEffectRenderInfo, o as ParticleProfile, r as ParticleSpecConfig, s as ParticleRuntime, u as WebgpuFallbackReason, y as GodotHtmlMountOptions } from "./extents-R8RIim2S.js";
+import { GodotBlendMode } from "@godot-scene-web/effects/shaders";
+
+//#region src/webgl/runtime.d.ts
+/** OPT-IN per-frame cost attribution for ONE shader runtime (`effectsProfiling`, see `../types`),
+ *  read from `stats().profile`; NULL when the option is off. The particle runtime's `ParticleProfile`
+ *  with the two CPU buckets removed — a shader frame has no simulation and no instance buffer, so
+ *  everything a shader tick does on the main thread is submit + blit. */
+interface ShaderProfile {
+  /** Loop ticks that rendered at least one binding. A tick deferred by the FPS cap (`capDeferrals`)
+   *  or one where every binding was clean/parked/suspended books none. */
+  ticks: number;
+  /** Bindings the tick handed to `renderNode`, summed across those ticks — static-frame cache hits
+   *  included, whether they blit or simply confirm their canvas already presents the keyed frame.
+   *  Clean, parked and suspended bindings are skipped by the loop before this and never counted. */
+  bindings: number;
+  /** GL SUBMIT: `renderNode`'s viewport/clear/program preamble, its texture binds and uniform
+   *  writes, and the `drawArrays`. SUBMIT ONLY — the GPU runs asynchronously, so this never contains
+   *  GPU execution time. Deliberately EXCLUDES the throttled SCREEN_TEXTURE capture (a 2D composite
+   *  of the DOM plus an upload, on its own ~300 ms cadence), which would otherwise spike this bucket
+   *  on the frames that happen to refresh it. */
+  glMs: number;
+  /** GL→2D BLIT: the node canvas's `clearRect` + the `drawImage` copying the shared GL canvas onto
+   *  it — and a cross-canvas static-frame cache-hit blit, which is the cost that cache trades the GL draw for.
+   *  Fill cost, so it scales with backing-store area (`renderScale` × devicePixelRatio), not with
+   *  shader complexity. */
+  blitMs: number;
+}
+/** Live, monotonically-increasing counters for ONE shader runtime (see `WebglShaderRuntime.stats`).
+ *  Plain fields bumped with `++` on the hot paths — no allocation, no behavior change; a probe
+ *  snapshots the object and diffs across a gesture window. Never reset for the runtime's lifetime. */
+interface WebglShaderRuntimeStats extends StaticImageSwapCounters {
+  /** Actual GL draws of a shader frame (`renderNode` reaching `gl.drawArrays`). */
+  draws: number;
+  /** Frozen-mode static-frame cache hits: the GL draw was skipped and a cached frame was handled. */
+  cacheHits: number;
+  /** Cache hits whose target canvas already held the named frame, so the 2D clear/blit was skipped.
+   *  `onBindingRendered` still fires: the binding presented/handled its current frame even though no
+   *  pixels changed. */
+  blitSkips: number;
+  /** SEAM — 0 today: static re-renders skipped because the quantized frame key was unchanged.
+   *  Future consumer: the `staticDirtyByFrameKey` dirty gating (Fix B) in `updateBinding`. */
+  dirtySkips: number;
+  /** Ticks pushed past the fps-cap boundary (the `!pacer.isDue` re-arm in `tick`). Today only capped
+   *  ANIMATED loops take this path — frozen mode bypasses the cap entirely (`capRemaining` returns 0),
+   *  so this stays 0 in static mode until `capStaticRerenders` (Fix A) routes static dirty re-renders
+   *  through the cap too. */
+  capDeferrals: number;
+  /** Node-canvas backing-store reallocations: `syncCanvasSize` calls that actually re-assigned
+   *  `canvas.width`/`height` (one event per call, however many dimensions moved). */
+  canvasReallocs: number;
+  /** Synchronous out-of-loop renders (`renderBindingNow`): the uv-window/realloc anti-flicker path
+   *  that draws immediately instead of waiting for the next tick. */
+  syncRenders: number;
+  /** `syncCanvasSize` calls that sized a binding at the PINNED static ratio
+   *  (`staticShaderPixelRatio`) instead of `devicePixelRatio × renderScale`. A device probe reads
+   *  this to confirm the pin is actually in force — it stays 0 when the option is unset OR the
+   *  runtime never entered frozen mode, which `canvasReallocs` alone cannot distinguish (that
+   *  counter is about the OPPOSITE thing: how much re-sizing churn is still happening). */
+  pinnedCanvasSyncs: number;
+  /** Per-frame cost attribution (see `ShaderProfile`), or NULL when `effectsProfiling` is off — the
+   *  default, and the no-op handle always. NULL rather than a zeroed object ON PURPOSE: "not
+   *  measured" must never read as "measured, cost nothing". The same object every `stats()` call. */
+  profile: ShaderProfile | null;
+  /** GAUGE — which renderer NEW bindings of this runtime are created on RIGHT NOW, re-derived on
+   *  each `stats()` read (a runtime can change backend mid-life, in one direction: a WebGPU device
+   *  that is lost is rebuilt on WebGL).
+   *
+   *  `"pending"` is a real state: with `effectsRenderer: "auto"`/`"webgpu"` on a browser that HAS
+   *  `navigator.gpu`, the device arrives from a promise, and until it does no binding is created at
+   *  all — every opted-in node simply keeps its CSS/SVG paint, exactly as it does while its shader
+   *  source is still being fetched. `"none"` is the no-op handle (no WebGL2, or no shader resolver).
+   *
+   *  It is the RUNTIME's answer, not a binding's: individual bindings can be on WebGL under a
+   *  `"webgpu"` runtime (see `webgpuBindingFallbacks`). */
+  renderer: "pending" | "webgpu" | "webgl" | "none";
+  /** COUNTER. Times this runtime adopted WebGL after being asked for `"auto"`/`"webgpu"` — the
+   *  SYNCHRONOUS "this browser has no navigator.gpu" decline included, which is the common case and
+   *  the reason a plain WebGL page reports 1 here rather than 0. Stays 0 for `effectsRenderer:
+   *  "webgl"` (nothing was ever asked for) and for a runtime that adopted WebGPU and kept it. */
+  webgpuFallbacks: number;
+  /** COUNTER — bindings that took the WebGL backend under a runtime whose renderer is WebGPU,
+   *  because THEIR shader cannot run there: it samples SCREEN_TEXTURE, its WGSL transpile refused a
+   *  construct, or its module/pipeline failed to build. This is the counter that says the
+   *  per-binding fallback is doing its job — one screen-reading shader must not veto N WebGPU
+   *  canvases, and without this the only symptom would be a node that is quietly slower. */
+  webgpuBindingFallbacks: number;
+  /** The FIRST reason this runtime declined WebGPU (later ones cannot un-explain it), or null while
+   *  it never has. THE diagnostic for a silent fallback: `renderer: "webgl"` under
+   *  `effectsRenderer: "webgpu"` says something went wrong, and only this says what. */
+  webgpuFallbackReason: WebgpuFallbackReason | null;
+  /** COUNTER — `queue.submit` calls this runtime's WebGPU backend has made, sampled on read. ONE per
+   *  tick that drew anything, whatever the binding count: that batching is the measured win (S7), so
+   *  a probe that finds it climbing with N nodes has found the win being given back. 0 on WebGL,
+   *  where the question is meaningless. */
+  webgpuSubmits: number;
+  /** GAUGE — `device.lost` resolutions seen by the page-wide device (see `../webgpu/device`). A lost
+   *  device stops producing frames, so a non-zero value here next to `renderer: "webgl"` is the
+   *  device-loss rebuild having happened. */
+  webgpuDeviceLosses: number;
+  /** GAUGE — `uncapturederror` events on the page-wide device. Non-zero means a frame was silently
+   *  WRONG: WebGPU reports most command-level mistakes this way and nothing else says so. */
+  webgpuErrors: number;
+}
+/**
+ * One shader to compile AHEAD of the node that will need it. See {@link WebglShaderRuntime.warmPrograms}.
+ *
+ * The same three values the create path derives from a node's `data-godot-shader-*` attributes, so a caller that
+ * knows its scene's shader set can name them without a node existing yet.
+ */
+interface WebglWarmSpec {
+  /** The shader id — the `programCache` key, and what `resolveShaderSource` is ultimately asked about. */
+  shaderKey: string;
+  /** Resource path passed to `resolveShaderSource`. Omit when the consumer resolves by uid alone. */
+  path?: string;
+  /** Resource uid passed to `resolveShaderSource`. */
+  uid?: string;
+}
+/** A persistent WebGL shader runtime for a mounted scene root (see createWebglShaderRuntime). */
+interface WebglShaderRuntime {
+  /** Diff the live `[data-godot-shader-webgl]` set against the bindings: keep+update
+   *  unchanged nodes (no forced layout), create new ones, dispose gone ones. */
+  reconcile(): void;
+  /** Live retune the backing-store resolution (devicePixelRatio × clamped `scale`) without a
+   *  dispose+recreate — for an adaptive-quality consumer that lowers fill cost under load. While a
+   *  pin is in force (see `setStaticShaderPixelRatio`) AND the runtime is in frozen mode this
+   *  re-sizes nothing: the frozen backing stores (and their cached frames) are deliberately held
+   *  still. The new scale still takes effect for live bindings the moment frozen mode is left. */
+  setRenderScale(scale: number): void;
+  /** Live set/clear the pinned FROZEN backing-store ratio (see `staticShaderPixelRatio`). Pass
+   *  `undefined` (or a non-positive value) to un-pin, restoring `devicePixelRatio × renderScale`
+   *  sizing for frozen bindings too. Only frozen bindings are affected — a live binding is never
+   *  sized by the pin. */
+  setStaticShaderPixelRatio(ratio: number | undefined): void;
+  /** Live retune the animated re-render FPS cap (0 = uncapped). */
+  setFps(fps: number): void;
+  /** Live toggle frozen-TIME (single-shot) mode: render each shader ONCE at a pinned TIME and stop the loop
+   *  (true), or resume per-frame animation (false). The low-end fallback that renders a correct still frame
+   *  instead of a per-frame loop — see the `staticShaders` option. */
+  setStaticShaders(value: boolean): void;
+  /** Live toggle of the frozen-surface image swap (see the `staticShaderImages` option and
+   *  `../surface-image-swap`). Turning it OFF reverts every live swap immediately and revokes its
+   *  object URLs — the kill switch, safe to throw at any time. Turning it back ON re-arms the
+   *  runtime's CONFIGURED policy (a boolean here never replaces it) and every binding re-earns. */
+  setStaticShaderImages(value: boolean): void;
+  /** HOST-DRIVEN revert of the surface image swap, WITHOUT blocking: with no argument every swapped
+   *  surface is handed back to its canvas; with a node list, only the bindings at (or under) those
+   *  elements. Each affected surface restarts its gate and re-earns the swap on its own. This is how
+   *  a host that knows something the runtime cannot see — it is about to re-parent a subtree, it
+   *  just re-themed, its own occlusion pass changed its mind — un-shadows a stale stand-in
+   *  immediately instead of waiting for a watchdog window. */
+  invalidateStaticSurfaces(nodes?: Iterable<HTMLElement>): void;
+  /** The runtime's live counters (see `WebglShaderRuntimeStats`). Returns the SAME live object every
+   *  call — read-only by convention; snapshot (spread) it to diff. All-zero on the no-op handle.
+   *  `.profile` carries the opt-in per-frame cost attribution (`effectsProfiling`) and is NULL
+   *  whenever it was not measured, the no-op handle included. */
+  stats(): WebglShaderRuntimeStats;
+  /**
+   * TEST / DIAGNOSTIC HOOK: the binding at (or under) `node` re-rendered into an offscreen texture
+   * and read back as tightly-packed RGBA (PREMULTIPLIED, top-down, at the canvas's BACKING-STORE
+   * size), or null when there is nothing to read — no binding there, a zero-sized canvas, or a
+   * binding rendering on WebGL.
+   *
+   * WEBGL RETURNS NULL ON PURPOSE, and it is not a gap: that canvas holds readable 2D pixels, so a
+   * caller who wants them uses `getImageData` on it. This exists because a WebGPU canvas has no such
+   * path — `drawImage`/`toDataURL` from one are blank under headless Chrome and pathological on
+   * Android (docs/perf-harness.md S7) — so the frame has to be produced a SECOND time, into a
+   * texture that `copyTextureToBuffer` can reach (`../webgpu/readback`). It renders the binding's
+   * CURRENT state at the runtime's current TIME, which for a frozen binding is exactly the frame on
+   * screen.
+   *
+   * This is the WebGL↔WebGPU image-parity harness's capture path.
+   */
+  captureNodePixels?(node: HTMLElement): Promise<Uint8Array | null>;
+  /**
+   * Resolve, transpile and LINK these shaders now, so the node that eventually wants one finds it cached.
+   * Resolves to how many of `specs` ended with a usable program (cached ones included).
+   *
+   * WHY THIS EXISTS. `compileProgramAsync` yields to the driver before asking a blocking question, which on a
+   * device with `KHR_parallel_shader_compile` makes a cold link nearly free. WITHOUT that extension — and it is
+   * absent on real Android hardware; a Moto G86 answers null for it — `ready()` reports true immediately and
+   * `finish()` then blocks on `LINK_STATUS` for as long as the driver needs. One measured link cost 90.3 ms of
+   * main thread, and it landed mid-combat because that was the first frame a node asked for that shader.
+   *
+   * THIS CANNOT MAKE THE LINK FREE, and does not pretend to: the driver's work is the driver's work. It only
+   * lets a consumer choose WHEN to pay — behind a loading screen, where 90 ms is invisible, instead of on the
+   * frame a card is played. That is the whole claim, and it is the one to verify.
+   *
+   * PURELY ADDITIVE. Nothing about the lazy create path changes; this only populates the cache it already
+   * consults. A spec whose source will not resolve, or will not compile, is counted as a miss and leaves that
+   * shader exactly where it was — the node that needs it later keeps its CSS/SVG paint, as it does today. Safe
+   * to call more than once and safe to ignore the result.
+   */
+  warmPrograms(specs: Iterable<WebglWarmSpec>): Promise<number>;
+  /** Tear everything down (cancel the rAF loop, disconnect observers, remove canvases). */
+  dispose(): void;
+}
+/**
+ * Create a PERSISTENT WebGL runtime for a mounted scene root. Unlike a teardown+reattach
+ * per render, the caller keeps this handle and calls `reconcile()` on each re-render:
+ * unchanged shader nodes KEEP their binding (a cheap attribute-only update — no
+ * `syncCanvasSize`/`clientWidth` forced layout), new nodes are created, gone nodes
+ * disposed. One shared rAF loop renders the live binding set. A no-op handle when WebGL2
+ * is unavailable or no shader resolver is configured.
+ */
+declare function createWebglShaderRuntime(root: HTMLElement, options: GodotHtmlRuntimeOptions): WebglShaderRuntime;
+//#endregion
+//#region src/runtime.d.ts
+/** Per-family overrides let an external host tune one binding without restarting the other. */
+interface HtmlEffectsHostOptions extends GodotHtmlRuntimeOptions {
+  shaderOptions?: GodotHtmlRuntimeOptions;
+  particleOptions?: GodotHtmlRuntimeOptions;
+}
+/** One DOM binding owner; the canvas renderer has its own stage/frame lifecycle. */
+interface HtmlEffectsHost {
+  readonly shaders: WebglShaderRuntime | null;
+  readonly particles: ParticleRuntime | null;
+  reconcile(): void;
+  updateOptions(options: HtmlEffectsHostOptions): void;
+  dispose(): void;
+}
+declare function createHtmlEffectsHost(stage: HTMLElement, initialOptions?: HtmlEffectsHostOptions): HtmlEffectsHost;
+//#endregion
+export { type GodotEffectRenderInfo, type GodotHtmlMountOptions, type GodotHtmlRuntimeOptions, HtmlEffectsHost, HtmlEffectsHostOptions, type ParticleProfile, type ParticleRuntime, type ParticleRuntimeStats, type ParticleSpecConfig, type WebglShaderRuntime, type WebglShaderRuntimeStats, type WebglWarmSpec, createHtmlEffectsHost, createParticleRuntime, createWebglShaderRuntime, normalizeParticleSpecConfig, parseParticleSpecConfig };
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","names":[],"sources":["../src/webgl/runtime.ts","../src/runtime.ts"],"mappings":";;;;;;;;UAknBiB,aAAA;;;EAGf,KAAA;;;;EAIA,QAAA;;;;;;EAMA,IAAA;;;;;EAKA,MAAA;AAAA;;;;UAYe,uBAAA,SAAgC,uBAAA;;EAE/C,KAAA;;EAEA,SAAA;;;;EAIA,SAAA;;;EAGA,UAAA;;;;;EAKA,YAAA;;;EAGA,cAAA;;;EAGA,WAAA;;;;;;EAMA,iBAAA;;;;EAIA,OAAA,EAAS,aAAA;;;;;;;;;;;;EAYT,QAAA;;;;;EAKA,eAAA;;;;;;EAMA,sBAAA;;;;EAIA,oBAAA,EAAsB,oBAAA;;;;;EAKtB,aAAA;;;;EAIA,kBAAA;;;EAGA,YAAA;AAAA;;;;;;;UAiDe,aAAA;;EAEf,SAAA;;EAEA,IAAA;;EAEA,GAAA;AAAA;;UAIe,kBAAA;;;EAGf,SAAA;;;;;;EAMA,cAAA,CAAe,KAAA;;;;;EAKf,yBAAA,CAA0B,KAAA;;EAE1B,MAAA,CAAO,GAAA;;;;EAIP,gBAAA,CAAiB,KAAA;;;;;EAKjB,qBAAA,CAAsB,KAAA;;;;;;;EAOtB,wBAAA,CAAyB,KAAA,GAAQ,QAAA,CAAS,WAAA;;;;;EAK1C,KAAA,IAAS,uBAAA;;;;;;;;;;;;;;;;;EAiBT,iBAAA,EAAmB,IAAA,EAAM,WAAA,GAAc,OAAA,CAAQ,UAAA;;;;;;;;;;;;;;;;;;;;EAoB/C,YAAA,CAAa,KAAA,EAAO,QAAA,CAAS,aAAA,IAAiB,OAAA;;EAE9C,OAAA;AAAA;;;;;;;;;iBAWc,wBAAA,CACd,IAAA,EAAM,WAAA,EACN,OAAA,EAAS,uBAAA,GACR,kBAAA;;;;UC50Bc,sBAAA,SAA+B,uBAAA;EAC9C,aAAA,GAAgB,uBAAA;EAChB,eAAA,GAAkB,uBAAA;AAAA;AD8mBpB;AAAA,UC1mBiB,eAAA;EAAA,SACN,OAAA,EAAS,kBAAA;EAAA,SACT,SAAA,EAAW,eAAA;EACpB,SAAA;EACA,aAAA,CAAc,OAAA,EAAS,sBAAA;EACvB,OAAA;AAAA;AAAA,iBAGc,qBAAA,CACd,KAAA,EAAO,WAAA,EACP,cAAA,GAAgB,sBAAA,GACf,eAAA"}

package/dist/runtime.js

@@ -0,0 +1,2 @@
+import { a as parseParticleSpecConfig, i as normalizeParticleSpecConfig, n as createWebglShaderRuntime, r as createParticleRuntime, t as createHtmlEffectsHost } from "./runtime-BkfFs_eO.js";
+export { createHtmlEffectsHost, createParticleRuntime, createWebglShaderRuntime, normalizeParticleSpecConfig, parseParticleSpecConfig };

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@godot-scene-web/html",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "description": "Godot scene layout and effects renderer for DOM and CSS.",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tfoxy/godot-scene-web.git"
+  },
+  "homepage": "https://github.com/tfoxy/godot-scene-web#readme",
+  "bugs": {
+    "url": "https://github.com/tfoxy/godot-scene-web/issues"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./runtime": {
+      "development": "./src/runtime.ts",
+      "types": "./dist/runtime.d.ts",
+      "import": "./dist/runtime.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "vendor",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@godot-scene-web/layout": "0.1.0",
+    "@godot-scene-web/scene-graph": "0.1.0",
+    "@godot-scene-web/core": "0.1.0",
+    "@godot-scene-web/effects": "0.1.0",
+    "@godot-scene-web/canvas-effects": "0.1.0"
+  },
+  "devDependencies": {
+    "@godot-scene-web/tscn-parser": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "cd ../.. && vitest run --config vitest.config.ts packages/html/test"
+  }
+}

package/vendor/LICENSE-OpenSans

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/vendor/VENDOR.md

@@ -0,0 +1,51 @@
+# Godot default-theme font
+
+`OpenSans_SemiBold.woff2` is a committed third-party binary, not a build
+output. Godot 4.5.1 embeds these exact bytes as its default GUI theme font
+(`scene/theme/default_theme.cpp` calls `set_data_ptr(_font_OpenSans_SemiBold,
+...)`). The HTML renderer embeds the same bytes as a data URL so it works both
+for source consumers and for a packed package without a host-specific asset
+copy rule.
+
+| file | bytes | sha256 |
+| --- | ---: | --- |
+| `OpenSans_SemiBold.woff2` | 46 392 | `661e2d9975d3029aeb32bf37b1b963c31c7c3ce08ac1bab2c8ebe27e135c4ec2` |
+
+## Provenance
+
+- Source: Godot Engine 4.5.1-stable,
+  `thirdparty/fonts/OpenSans_SemiBold.woff2`, copied byte-for-byte.
+- Godot records its upstream as [Google Fonts: Open Sans](https://fonts.google.com/specimen/Open+Sans),
+  version 1.10, downloaded February 2021, under Apache License 2.0
+  (`thirdparty/README.md`).
+- The file was converted by Godot from the unhinted TTF source using
+  [google/woff2](https://github.com/google/woff2), as recorded in that same
+  Godot third-party manifest.
+
+## Packaging
+
+`scripts/inline-default-font.mjs` regenerates
+`src/default-font-data.ts` from this binary. That module is imported by the
+renderer, so tsdown carries the data URL into `dist` and Vite source consumers
+need neither a special URL resolver nor a copied font asset. The vendor binary
+and this provenance file remain in the npm package for auditability.
+
+## Default bold role
+
+Godot does not select a separate Open Sans Bold file for `[b]`: its default
+theme constructs a `FontVariation` over this SemiBold face with
+`variation_embolden = 1.2` (`scene/theme/default_theme.cpp`). In
+`TextServerAdvanced`, the variation contributes
+`embolden * (font_size * 64) / 4096` to every glyph advance: 0.3 px at the
+default 16 px. Browser `font-synthesis` changes glyph ink but does not make
+`Range` geometry include that advance. The renderer therefore uses a 0.5 px
+tracking emulation for the *implicit* default bold role: 0.3 px from Godot's
+formula plus the measured cross-shaper/hinting rounding gap. It is deliberately
+not applied when an explicit bold FontFile/FontVariation resolves, and it
+resets a normal FontVariation's `spacing_glyph` instead of inheriting it.
+
+## License
+
+Godot declares this historical Open Sans 1.10 binary Apache License 2.0. The
+verbatim license text is in `LICENSE-OpenSans`; retain it with every copy of
+the binary.