# Squander Squander is a TypeScript-first browser-game toolkit. It provides a WebGPU renderer, a game lifecycle, resource and asset ownership, 2D drawing primitives, cameras, viewports, input routing, scenes, and an optional Svelte 5 adapter. Svelte is the UI layer, while SvelteKit is the application medium for delivering routes, documentation, examples, and browser experiences. The core runtime is independent of both and is designed for composition, ECS-friendly game code, and agent-assisted development. ## Why use Squander - Keep game code focused on gameplay while Squander owns WebGPU setup and GPU resource lifetime. - Use strongly typed, functional APIs without adopting a class-heavy engine architecture. - Build browser games with deterministic lifecycle behavior, explicit handles, and verifiable rendering. - Connect a game to Svelte 5 UI without coupling the core runtime to Svelte. - Give coding agents discoverable package exports, focused examples, and clear supported and deferred behavior. Squander targets 2D browser games. WebGPU is the rendering path; a WebGL fallback is not promised. Mipmaps, swappable projections, and arbitrary GPU resource APIs remain deferred. Production frames, render targets, and constrained texture fragment effects are available. Fixed-step simulation is available as an opt-in game timing mode. ## Current goals - Build a TypeScript-first toolkit for polished 2D browser games with composition-friendly, ECS-oriented foundations. - Keep game code focused on gameplay while Squander owns WebGPU setup, frame scheduling, explicit resource lifetime, input routing, scenes, and predictable teardown. - Keep the core runtime independent of Svelte, SvelteKit, and application frameworks. - Use Svelte as the UI layer. Game code owns mutable gameplay state and business rules; a typed bridge publishes readonly state and accepts typed commands from Svelte UI. - Use SvelteKit as the delivery medium for routing, documentation, runnable examples, composition demos, and the browser/server boundary. SvelteKit delivers the surrounding experience; it does not own simulation, rendering, or core resource lifetime. - Provide strong TypeScript inference, explicit ownership, focused documentation, and separate CPU, type, coverage, browser, and real-WebGPU verification signals. - Keep current documentation and agent guidance organized around stable capabilities. Use phase terminology only for active plans, candidate backlogs, or historical records; once a capability is implemented, refer to the feature and its observable behavior. - Keep deferred capabilities contract-driven: advanced projections, broader custom shaders, and mipmaps require their own supported behavior and evidence before inclusion. - The initial ECS capability is available from `squander/ecs`: define local object-shaped component tokens, create independent worlds, run typed fluent queries, and use world-level `export()`/`import()` snapshots. The optional `create_ecs_system_pipeline` helper orders caller-owned systems but does not register them with a global scheduler. Node and trusted-local-origin browser benchmark profiles guard the supported workloads. Monotonic numeric IDs are the default; create_world(schema, { entity_policy: "generational" }) opts into packed generational handles and stale-handle checks. Archetype and typed-column optimizations remain deferred. ## Author and project - Author and maintainer: Rory Duncan - GitHub: https://github.com/manacost/squander - npm: https://www.npmjs.com/package/squander - License: MIT - Current package version in this repository: 8.4.0 ## Table of contents - [Getting started](#getting-started) - [Recommended project structure](#recommended-project-structure) - [Current goals](#current-goals) - [Use Squander in a SvelteKit project](#use-squander-in-a-sveltekit-project) - [Core concepts](#core-concepts) - [Random](#random) - [Signals and event dispatch](#signals-and-event-dispatch) - [Entity-component system](#entity-component-system) - [Game lifecycle and timing](#game-lifecycle-and-timing) - [WebGPU renderer](#webgpu-renderer) - [Assets and resources](#assets-and-resources) - [Sprites and textures](#sprites-and-textures) - [Shapes](#shapes) - [Paths and polygons](#paths-and-polygons) - [Cameras and viewports](#cameras-and-viewports) - [Input](#input) - [Scenes](#scenes) - [Text and fonts](#text-and-fonts) - [Svelte 5 game UI bridge](#svelte-5-game-ui-bridge) - [UI styles](#ui-styles) - [ECS Arena proof game](#ecs-arena-proof-game) - [Snake example](#snake-example) - [TypeScript and ownership rules](#typescript-and-ownership-rules) - [Verification](#verification) - [Repository map](#repository-map) ## Getting started Squander is ready in 60 seconds with the SvelteKit path. Squander requires Node.js 22.17 or newer for development. Install Squander, Svelte, and SvelteKit: ```sh npm install squander@latest svelte@latest @sveltejs/kit@latest ``` Create a route such as `src/routes/+page.svelte` and mount the exported `Game` component. It creates the browser-side game after mount, owns the renderer and frame loop, and disposes them when the page unmounts: ```svelte ``` The first scene clears the canvas so a successful setup is visible. WebGPU requires a secure context, such as localhost during development or HTTPS in production. Keep `Game` in a Svelte component so WebGPU creation stays browser-only; do not create a game during server-side rendering. For lower-level control, import `create_game` from the package root or continue with the [game lifecycle guide](/docs/core/game-lifecycle). Use the [playground](/docs/examples/playground) for a larger rendered example. ## Use Squander in a SvelteKit project Create a client-side game component with a canvas. WebGPU needs a secure context, such as localhost during development or HTTPS in production. Keep browser-only game creation in a component or another client-only module; do not create a WebGPU device during server-side rendering. ```svelte ``` For Svelte-driven HUDs and controls, use Svelte as the UI layer: import `GameHost` from `squander/svelte` or use `create_game_adapter` from `squander/svelte/adapter`. The bridge publishes readonly game snapshots and accepts typed commands from the UI. The host owns one game instance per mount and disposes it when unmounted. In a SvelteKit application, keep WebGPU creation in client-side lifecycle code and use SvelteKit for routing, delivery, and the surrounding experience. Use Svelte 5 runes in new application components, and keep gameplay state in the game unless it is UI state that the bridge intentionally publishes. The core runtime does not import Svelte at runtime. The Svelte integration is optional at the API level, but this package currently declares Svelte as a required peer dependency, so install Svelte even when using only the core entry points. ## Recommended project structure Keep the SvelteKit route thin and put game-owned composition under `src/lib/game`. A practical starting structure is: ```text src/ ├── lib/ │ └── game/ │ ├── components/ # ECS tokens, local schema, and data shapes │ ├── scenes/ # lifecycle boundaries and scene composition │ ├── systems/ # ordinary caller-owned ECS or game systems │ ├── ui/ # Svelte HUDs, menus, and overlays │ └── game.ts # world creation and the game entrypoint └── routes/ └── +page.svelte # mounts squander/svelte and imports game.ts ``` Keep `+page.svelte` at the application edge: ```svelte ``` Use `game.ts` as the composition root. It creates a world from the local schema, mounts the starting scene, and decides which systems run during each lifecycle phase. Systems remain ordinary functions, and scenes own ordering, assets, input, and lifecycle boundaries: ```ts import { create_world } from "squander/ecs"; import type { GameReadyContext } from "squander/svelte"; import { game_schema } from "./components"; import { movement_system } from "./systems/movement"; export const start_game = async ({ scenes }: GameReadyContext): Promise => { const world = create_world(game_schema); await scenes.mount(({ renderer }) => ({ name: "play", update: ({ delta_seconds }) => movement_system(world, delta_seconds), draw: (frame) => { frame.draw_commands([ { kind: "rectangle", draw: { rectangle: { x: 0, y: 0, width: 800, height: 450 }, color: { red: 0.05, green: 0.08, blue: 0.15, alpha: 1 } } }, ]); }, })); }; ``` The ECS does not register or schedule systems. Keep component tokens and the local schema in `components/`, transformations in `systems/`, lifecycle composition in `scenes/`, and Svelte UI in `ui/`. Gameplay state remains in the runtime; Svelte reads only the state the game intentionally publishes. ## Core concepts The package root exports the core runtime. A game owns its renderer, frame loop, input router, asset cache, resource owner, geometry owner, and scene composer. Setup runs before the frame loop starts. The `update` callback advances game state, and `draw(frame)` records frame-local commands. The runtime submits one logical frame after application and scenes have recorded their commands. ## Production frame submission Use the frame supplied to the game or scene draw callback for normal rendering. It preserves application-then-scene order, clears once, submits without readback, and accepts an empty frame. The renderer remains one public mechanism; the frame is only its recording boundary. `WebGpuRenderer.begin_frame` is available for lower-level code: ```ts const frame = renderer.begin_frame(); frame.draw_commands([ { kind: "rectangle", draw: { rectangle: { x: 0, y: 0, width: 800, height: 450 }, color: rgba(0, 0, 0, 1) } }, ]); await frame.submit(); ``` Call `frame.capture()` before `submit()` only for diagnostic pixel evidence. It requests one readback for that frame; production frames should not request capture. Existing `renderer.clear`, `draw_texture`, `draw_textures`, `draw_text`, and `draw_commands` methods remain readback-oriented compatibility methods during migration. ```ts import { create_game, type FrameScheduler } from "squander"; const canvas = document.querySelector("canvas"); if (!(canvas instanceof HTMLCanvasElement)) throw new Error("canvas is required"); const scheduler: FrameScheduler = { request_frame: (callback) => requestAnimationFrame(callback), cancel_frame: (handle) => { if (typeof handle !== "number") throw new Error("browser frame handles must be numbers"); cancelAnimationFrame(handle); }, now_seconds: () => performance.now() / 1000, }; const game = create_game({ renderer: { canvas, width: 800, height: 450 }, scheduler, setup: ({ renderer }) => { void renderer; }, update: ({ delta_seconds }) => { void delta_seconds; }, draw: () => undefined, }); await game.ready; ``` ## Signals and event dispatch Import the standalone reactive utilities from `squander/signals`. Signals carry one value type; event dispatchers map event names to payload types. Both return unsubscriber functions, support `once`, and use a stable listener snapshot so subscription changes take effect on the next emission. ```ts import { create_event_dispatcher, create_signal } from "squander/signals"; const score_changed = create_signal(); const stop_score = score_changed.subscribe((score) => console.log(score)); score_changed.emit(10); stop_score(); type Events = { score: { points: number }; reset: undefined; }; const events = create_event_dispatcher(); events.on("score", ({ points }) => console.log(points)); events.emit("score", { points: 10 }); events.emit("reset"); ``` These utilities are standalone and reusable. Game-scoped scene events add ownership, disposal, and runtime error routing through `game.scenes.events`. ## Action mapping Use `create_action_map` to translate raw router events into named gameplay actions. The map can combine keyboard, pointer, gamepad button, and analog axis bindings, with dead zones, inversion, scale, and deterministic digital edges. Call `update()` explicitly once per simulation frame; rebinding validates the complete replacement atomically. ```ts const actions = create_action_map({ router: game.input, bindings: { confirm: [{ device: "keyboard", code: "Enter" }, { device: "gamepad_button", button: 0 }], move_x: [{ device: "gamepad_axis", axis: 0, dead_zone: 0.2 }], }, }); actions.update(); if (actions.get("confirm").just_pressed) confirm(); ``` Action maps do not consume raw input, create a hidden loop, or replace the router. Text input, IME, gestures, and hit testing remain separate. ## Entity-component system The optional ECS module is independent of Svelte, scenes, rendering, and the game loop. An entity-component system (ECS) separates identity, data, and behavior: an entity is a numeric ID, components are small pieces of data such as position or health, and systems query entities with the data they need and update them. This makes it easier to process many similar game objects without putting every behavior in one large class. In Squander, define object-shaped component tokens in a local schema and create as many worlds as the application needs: For a broader introduction, see [Entity-component system on Wikiwand](https://www.wikiwand.com/en/Entity_component_system). The current implementation is benchmarked against a shared CPU workload of 1,000,000 entities in Node.js and 100,000 entities in Chromium. It measures dense and sparse queries, structural remove/add operations, snapshot import/export, and teardown. These are workload timings, not a universal frame-rate promise. ```ts // Import the world factory and component definition helper. import { create_world, define_component } from "squander/ecs"; // Describe the data stored by each position component. type Position = { x: number; y: number }; // Create a typed token that identifies the position component. const position = define_component({ name: "position" }); // Create a world whose local schema contains the position token. const world = create_world({ position }); // Allocate a cheap numeric entity ID. const entity = world.create(); // Attach the initial position data to the entity. world.add(entity, position, { x: 0, y: 0 }); // Require position before iterating matching entities. world.query().with(position).each(({ read, write }) => { // Read the current value, then write the updated x coordinate. const { y } = read(position); write(position).x += y; }); ``` Queries expose only requested component tokens at compile time. Use `toArray()` for live match views or `toSnapshots()` for detached copies. Structural match operations are deferred until the current query finishes. Monotonic IDs are the default and are never reused. Generational worlds pack a slot and generation into numeric handles, reuse slots, and reject stale handles. Version 1 snapshots preserve numeric IDs and require a matching identity policy. World-level `export()` and `import()` preserve numeric entity IDs and component values without requiring persistence codecs on each component. JSON, binary formats, migrations, and runtime-only value policies belong in an application-owned serializer. The ECS provides no ambient scheduler or system registry; callers decide whether ordinary systems expose `enter`, `update`, `draw`, or `exit`, and where to invoke those hooks. When ordered updates are useful, use the optional caller-owned pipeline: ```ts import { create_ecs_system_pipeline } from "squander/ecs"; const simulation = create_ecs_system_pipeline([ { update: ({ world, time }) => movement_system(world, time.delta_seconds) }, { enabled: debug_enabled, update: ({ world }) => debug_system(world) }, ]); simulation.run(world, time); ``` ## ECS Arena proof game The live `/scenes/ecs-arena` route is a small top-down WebGPU game built on the ECS API. The caller owns the system order: input, spawn, fire, steering, movement, combat, and cleanup. The world creates drones and projectiles, updates position and velocity components through queries, and destroys colliding entities through deferred structural operations. The HUD reports score, wave, entity count, and the system order so the ECS behavior is visible while playing. Use WASD or arrow keys to move, Space to fire, P or Escape to pause, and R to restart. The proof game is an example application, not a scheduler or a new ECS package API. It intentionally omits assets, audio, progression, and multiplayer. ## Game lifecycle and timing Use `game.ready` to await renderer creation and setup. Use `pause`, `resume`, and `set_visibility` for lifecycle control. Call `dispose` when a game leaves the page. The frame loop clamps unusually large deltas, resets timing after suspension, and does not update while paused. The runtime owns frame-submission promises: a rejection stops future frames, reports one `GameRuntimeError` with the original cause, and is not an unhandled rejection. Disposal waits for accepted frame cleanup and is safe to call more than once. ```ts await game.ready; game.pause(); game.resume(); await game.dispose(); ``` Variable-step browser-frame timing remains the default. Opt into bounded fixed updates when simulation needs stable increments: ```ts const game = create_game({ renderer, scheduler, fixed_step: { step_seconds: 1 / 60, max_steps_per_frame: 5 }, update: (time) => { simulate(time.delta_seconds); if (time.discarded_seconds > 0) report_overload(time.discarded_seconds); }, draw: (frame) => draw_game(frame), }); ``` The runtime runs a bounded update batch and draws once afterward. When the bound is reached, `UpdateTime.discarded_seconds` reports discarded catch-up time. Pause and hidden visibility do not advance the accumulator; interpolation and rollback are not included. ## WebGPU renderer The renderer creates the adapter, device, canvas context, pipelines, textures, samplers, and readback path. It requires `navigator.gpu` and a secure context. Use `create_webgpu_renderer` directly when a standalone renderer is useful; normally `create_game` creates and owns it. ```ts import { create_webgpu_renderer } from "squander/core/runtime"; declare const canvas: HTMLCanvasElement; const renderer = await create_webgpu_renderer({ canvas, width: 800, height: 450 }); const pixels = await renderer.clear({ red: 0.04, green: 0.05, blue: 0.1, alpha: 1 }); void pixels; renderer.dispose(); ``` Handle `WebGpuUnavailableError` and `GameDeviceLostError` at an application boundary. Renderer-owned targets and constrained texture fragment effects are available for offscreen composition and postprocessing; mipmaps, swappable projections, and arbitrary shader bindings remain outside the current contract. ```ts const target = renderer.create_render_target({ width: 800, height: 450 }); const frame = renderer.begin_frame(); frame.set_target(target); frame.draw_commands(scene_commands); frame.set_target(); frame.draw_commands([{ kind: "texture", draw: { texture: target } }]); target.release(); await frame.submit(); ``` Custom effects receive the sampled and tinted `color`, normalized `uv`, and up to 16 numeric values exposed as `uniforms[0]` through `uniforms[3]`. Squander owns shader bindings, pipelines, and GPU buffers. ```ts const effect = renderer.create_shader_effect({ fragment_code: "return vec4f(color.rgb * uniforms[0].x, color.a);", uniforms: [0.75], }); await renderer.draw_texture(texture, { effect }); effect.release(); ``` ## Assets and resources Load textures and fonts through the game-owned asset cache, or create dynamic textures from `Blob` and `File` values. For a bundled site asset, resolve its URL with SvelteKit's base-aware `asset` helper before fetching it; do not use a root-relative URL when the site can be deployed below the domain root. Asset loading honors cancellation. Resources returned by asset and geometry APIs are explicit handles: release them when the owner no longer needs them. Accepted draws retain a safe lease until the renderer can release the underlying resource. ```ts import { create_game } from "squander"; declare const canvas: HTMLCanvasElement; const game = create_game({ renderer: { canvas, width: 800, height: 450 }, scheduler: { request_frame: (callback) => requestAnimationFrame(callback), cancel_frame: (handle) => { if (typeof handle !== "number") throw new Error("browser frame handles must be numbers"); cancelAnimationFrame(handle); }, now_seconds: () => performance.now() / 1000, }, setup: async ({ assets, signal }) => { const texture = await assets.load_texture(new Blob(), { signal }); texture.release(); }, update: () => undefined, draw: () => undefined, }); await game.ready; ``` Use `game.resources` and `game.geometry` for resources that need a game lifetime. Do not keep or read a handle after releasing it. ## Sprites and textures Use `renderer.draw_texture` for sprites and atlas regions. A draw can specify position, size, source region, origin, scale, rotation, horizontal or vertical flip, tint, opacity, and submission order. Use `nearest` filtering for pixel-art games and `linear` filtering for smooth art. ```ts frame.draw_commands([{ kind: "texture", draw: { texture: hero.read(), options: { x: player.x, y: player.y, width: 48, height: 48, origin: { x: 0.5, y: 0.5 }, rotation: degrees(player.angle), flip_x: player.facing_left, tint: rgba(1, 0.9, 0.9, 1), opacity: player.invulnerable ? 0.5 : 1, } } }]); ``` Draw order is observable. Each draw may use `blend_mode: "normal"`, `"additive"`, or `"multiply"`; normal is the default and blend-mode changes break batching. Mipmaps, anisotropic filtering, and swappable projections are not currently exposed. ## Shapes Shapes are frame-local commands for HUDs, debug overlays, hit effects, and game geometry. Supported commands include filled and outlined rectangles, circles, and lines. Invalid geometry throws; valid zero-area geometry draws nothing. ```ts frame.draw_commands([ { kind: "rectangle", draw: { rectangle: { x: 20, y: 20, width: 180, height: 24 }, color: rgba(0.1, 0.1, 0.15, 1) }, }, { kind: "circle", draw: { circle: { x: player.x, y: player.y, radius: 18 }, color: rgba(0.2, 0.8, 0.4, 1) }, }, ]); ``` Rounded caps and joins, dashed strokes, and inside/outside stroke alignment are deferred. ## Paths and polygons Create reusable paths for curved effects, trails, and outlines. Create polygons for filled game regions and collision-like visualizations. Constructors copy caller data, and updates validate before replacing geometry. ```ts const trail = create_path([move_to(0, 0), quadratic_to(40, -30, 80, 0)]); const island = create_polygon([ { x: 0, y: 0 }, { x: 80, y: 10 }, { x: 45, y: 60 }, ]); trail.update([move_to(player.x, player.y), line_to(player.x - 80, player.y + 20)]); ``` Use the exported path, flattening, stroke, polygon, and triangulation helpers from `squander/core/runtime`. Filled curved subpaths use the explicit `filled_path` command and `even_odd` rule; nonzero winding and broader fill rules remain deferred. Path strokes use world units, butt caps, and miter joins by default. Configure `units: "screen"`, `cap: "square" | "round"`, `join: "bevel" | "round"`, and a finite `miter_limit` for selection outlines, trails, and effects. Screen units account for active camera zoom and display density. These options apply to path stroke commands; dashed strokes, inside/outside alignment, and primitive outline styles remain deferred. ```ts frame.draw_commands([{ kind: "stroke", draw: { subpaths: outline, width: 2, units: "screen", cap: "round", join: "round", color: rgba(1, 1, 0, 1), } }]); ``` ```ts const outer = flatten_path([move_to(0, 0), line_to(200, 0), line_to(200, 120), line_to(0, 120), close()], 0.5)[0]; const hole = flatten_path([move_to(40, 30), line_to(40, 90), line_to(160, 90), line_to(160, 30), close()], 0.5)[0]; frame.draw_commands([{ kind: "filled_path", draw: { subpaths: [outer, hole], fill_rule: "even_odd", color: rgba(1, 0, 0, 1) } }]); ``` ## Cameras and viewports Use a 2D camera to draw world coordinates through position, zoom, and rotation. Use viewport sizing helpers to keep logical coordinates stable as CSS size, letterboxing, device pixels, and physical canvas size change. Pass the current viewport to `create_browser_input_adapter` when pointer events should include logical coordinates and an `inside_logical_content` flag; raw host-relative coordinates remain available. ```ts const camera = create_camera({ x: player.x, y: player.y, zoom: 2, rotation: degrees(0), viewport: game.get_viewport(), }); camera.draw(() => { renderer.draw_texture(hero.read(), { x: player.x, y: player.y }); }); ``` Drawing inside a camera scope uses world space; drawing outside it uses screen space. Camera scope restoration is synchronous, including when a callback throws. Opt-in bounded render culling is available; cursor-anchored zoom and swappable projections remain deferred. ```ts const renderer = await create_webgpu_renderer({ canvas, width: 800, height: 450, cull_offscreen: true }); camera.draw(() => { frame.draw_commands([{ kind: "texture", draw: { texture }, bounds: enemy_bounds }]); }); ``` Culling is disabled by default and skips only definitely offscreen bounded commands. Visible, edge-touching, and unbounded commands remain. It never skips simulation or input. ## Random Use the random module to separate fresh browser entropy from deterministic gameplay randomness. `create_random()` uses `crypto.getRandomValues()` to create a fresh source when no seed is supplied. Passing a numeric or string seed creates the same sequence for procedural generation, tests, and replay. ```ts import { create_random } from "squander/core"; const random = create_random({ seed: "level-42" }); const spawn_x = random.next_int(0, 800); const loot = random.pick(["potion", "map", "key"]); const loot_random = random.fork("loot"); const replay_state = loot_random.snapshot(); ``` `next_float()` returns `[0, 1)`. `next_int(min_inclusive, max_exclusive)` uses an exclusive upper bound and rejection sampling to avoid modulo bias. `pick()` rejects empty collections, and `shuffle()` returns a new array without mutating its input. `fork(label)` creates a stable stream for a subsystem, and `snapshot()` preserves the full stream state and algorithm identity. The focused examples live at `/docs/utilities/random`. The module is for gameplay, procedural generation, tests, and replay support. It is not a cryptographic API, anti-cheat mechanism, or secure token generator. The current source is CPU-side; WGSL shaders need explicit seed or state buffers for GPU randomness. ## Input The game owns an input router for keyboard, pointer, and gamepad input. Route input to the active scene first, then use a global fallback for controls such as pause or opening a menu. Keep input handlers short and update game state in the game loop when ordering matters. ```ts const remove_pause_input = game.input.on_global((event) => { if (event.type === "key" && event.phase === "down" && event.code === "Escape") { game.pause(); return "consume"; } return "pass"; }); ``` Call `remove_pause_input` when the game no longer needs the global handler. The exact event types and registration methods are exported from `squander/core/runtime`; prefer those types over browser events when writing game systems. ## Scenes Scenes are game-owned lifecycle objects. Mount, replace, and remove scenes asynchronously. Active scenes update and draw from the bottom of the stack to the top, making overlays and menus natural composition units. Scene factories can declare typed asset dependencies and use the game-owned event bus. ```ts const menu = await game.scenes.mount(({ events }) => ({ name: "pause menu", init: () => events.on("resume", () => void game.scenes.remove(menu)), update: () => {}, draw: () => draw_pause_menu(), })); game.scenes.events.emit("resume", undefined); ``` Scene removal disposes the scene permanently. Shared manifest assets remain usable while one scene leaves. Scene-owned Svelte UI is available through the optional `Game` host and remains outside the core runtime: ```svelte { scenes.switch(scenes.create(({ create_ui }) => ({ name: "hud", enter: () => create_ui(Hud, { score: 0 }), }))); }} /> ``` Use `GameHost` or `create_game_adapter` for the lower-level typed state bridge. ## Text and fonts Load a bundled font through the font-loading API, prepare its glyphs, and draw changing game labels or HUD text with the renderer. Font atlas textures follow the same ownership and filtering rules as other textures. ```ts import { asset } from "$app/paths"; const font_url = `url("${asset("fonts/example.ttf")}")`; const font = await assets.load_font(font_url, { filter: "nearest" }); renderer.draw_text(font.read(), "SCORE 1200", { x: 24, y: 24, size: 24 }); font.release(); ``` Use the text example in the documentation site as the current end-to-end reference. When the site loads a font from its `static/` directory, use SvelteKit's `asset("fonts/example.ttf")` helper when building the CSS font source so the configured deployment base is preserved. Rich text layout and advanced font shaping are outside the current runtime scope. ## Svelte 5 game UI bridge Use `GameHost` for the common state/command bridge, `Game` for scene-owned Svelte UI, or `create_game_adapter` for a custom host. Svelte owns the UI presentation; the game publishes readonly state snapshots, and the UI calls typed commands. The command object preserves synchronous and asynchronous return types. SvelteKit can deliver this UI through routes and browser experiences without becoming a dependency of the core runtime. ```svelte {#snippet children(view)} {view.state.score} {/snippet} ``` The adapter is Node-safe and does not make the core runtime import Svelte. A host owns its subscriptions and game and disposes both on unmount. Svelte remains a required package peer until the package boundary changes. ## UI styles Squander ships two independent, opt-in CSS entry points for game-facing HTML UI. Import `squander/styles/reset.css` for a global normalized baseline and `squander/styles/ui.css` for the dark-only quiet utility theme. The theme does not import the reset, so consumers can choose either layer or both: ```css @import "squander/styles/reset.css"; @import "squander/styles/ui.css"; ``` The theme styles semantic HTML such as headings, links, buttons, form controls, dialogs, menus, fieldsets, tables, details, progress, and status outputs. It uses `--squander-*` custom properties for colors, typography, control sizing, focus treatment, and radius. Its heading sizes use a shallow 2px step scale so game UI hierarchy comes from grouping, placement, contrast, and state instead of document-style title jumps. Forms use compact aligned rows, and buttons use a flat lower ledge rather than a full border. Controls default to a deep berry surface (`#741c3b`). The rules are in a low-priority CSS layer so an application can override them. It does not style the WebGPU canvas, create layout components, add runtime behavior, or provide a light palette. ## Snake example The Snake example at `/docs/examples/snake` is a complete 50×50 arcade game built into the documentation site. It keeps the simulation in an example-local state machine and uses `GameHost` for menus, score, pause state, and touch controls. WebGPU shape commands draw the near-black board, readable snake segments, and randomly colored fruit. The example supports arrow keys, WASD, and an accessible touch D-pad. Starting, resuming, restarting, or changing direction through the D-pad returns keyboard focus to the board, so arrow keys stay with the game instead of scrolling the documentation page. Wall and self collisions end a run; fruit increases the score and gradually increases movement speed. The example does not add package exports, gamepad support, persistent scores, audio, or network play. ```ts type SnakeState = Readonly<{ status: "start" | "playing" | "paused" | "game-over"; snake: readonly GridPoint[]; fruit: GridPoint | null; score: number; }>; ``` Use the live page as the end-to-end reference for combining a pure game model, `create_game`, renderer shape commands, browser input routing, and a typed `GameHost` bridge. ## TypeScript and ownership rules - Import public types from the package exports instead of reaching into source files. - Prefer the package root for normal game code and `squander/ecs` for ECS code. - Use `squander/core` only when you need the compatibility core barrel. - Use `squander/core/runtime` for lower-level runtime types and helpers. - Keep the core runtime Svelte-independent; use the Svelte adapter only at the application boundary. - Treat asset, resource, geometry, and scene handles as owned values and release them through their documented owner. - Do not use a released handle or pass a resource between games. - Use runtime narrowing and typed helpers rather than TypeScript assertions in production game code. ## Verification Repository documentation uses specs/ for current capability contracts, specifications/decisions.md for durable rationale, specifications/history/ for audit evidence, and the phase candidate logs for future work. The gitignored .codex/plans/ directory contains only active temporary execution state; it does not define current behavior. For a repository checkout, run focused CPU tests with `npm run test:unit`, type checks with `npm run test:type`, and Svelte diagnostics with `npm run check`. Run `npm run test:integration` for browser flows and `npm run test:benchmark:ecs` plus `npm run test:benchmark:ecs:browser` for the Node and trusted-local-origin ECS benchmark profiles. Run `npm run test:webgpu` for real WebGPU rendering. Run `npm run test:coverage` before `npm run check:coverage`; the strict greater-than-90% source gate covers executable TypeScript under `src/lib/core/`. Verify Svelte lifecycle and documentation presentation through browser tests. Run `npm run test:benchmark:renderer:browser:guard` to compare renderer timing and retained-resource measurements with the matching recorded WebGPU profile. CI has two lanes. Pull requests use standard GitHub-hosted runners for portable CPU, type, package, documentation, browser, ECS, and advisory benchmark checks. Real WebGPU verification runs separately on protected `main` pushes or manual dispatch using a trusted Linux GPU runner. Do not send untrusted pull-request code to a persistent self-hosted GPU runner. The hardware lane records browser, OS, adapter, backend, DPR, viewport, and fixture metadata as artifacts. Real WebGPU verification must use trusted local HTTP or HTTPS, assert secure context, adapter creation, and device creation, and verify deterministic pixel or buffer readback. A missing `navigator.gpu` or adapter is a failed verification environment, not a passing skip. ## Repository map - `src/lib/core/runtime/` — lifecycle, assets, geometry, camera, text, input, scenes, and WebGPU runtime. - `src/lib/svelte/` — optional Svelte 5 adapter and `GameHost`. - `src/routes/(docs)/docs/core/` — focused runtime guides. - `src/routes/(docs)/docs/examples/` — runnable feature and composition demos. - `src/routes/(game)/scenes/ecs-arena/` — the ECS Arena proof game and its deterministic model tests. - `src/routes/(docs)/docs/examples/snake/` — the complete Snake arcade example and its simulation tests. - `tests/` — Playwright integration and real WebGPU fixtures. - `specifications/` — capability contracts, decisions, and evidence. Read the focused documentation and source exports together when an API detail matters. The documentation site is at https://github.com/manacost/squander.