# Almanach — SceneryStack Knowledge Base

> A file-based knowledge base of SceneryStack knowledge: API guides, software patterns, styling, and accessibility conventions for building interactive simulations. Every page is plain Markdown with structured frontmatter.

This file contains the full text of all 423 pages. Each page begins with a "===" separator line.


========================================================================
Page: Deploying a Simulation to GitHub Pages
URL: https://veillette.github.io/Almanach/getting-started/deploying-to-github-pages
Source: docs/getting-started/deploying-to-github-pages.md
Category: Getting Started | Tags: deployment, github-pages, build, ci | Status: verified
========================================================================

# Deploying a Simulation to GitHub Pages

A production build of a SceneryStack simulation is exactly what GitHub Pages wants: a folder of static HTML, JS, CSS, and media, with no server-side runtime. This page walks through turning `npm run build`'s output into a live `https://<user>.github.io/<repo>/` URL, both by hand (pushing to a `gh-pages` branch) and with a GitHub Actions workflow that rebuilds on every push.

::: warning Set the base path before you build, not after
GitHub Pages serves a project site from a subpath (`/<repo>/`), not the domain root. If your bundler config assumes root-relative asset paths (the default for most Vite/Webpack/Esbuild scaffolds), the deployed page loads with every script and asset 404ing, because the browser requests `/main.js` instead of `/<repo>/main.js`. Set the base path in the bundler config *before* running the production build — see below — not by editing the built output afterward.
:::

## What you're deploying

As covered in [Running and Building a Simulation](/getting-started/running-and-building-a-simulation), `npm run build` runs whichever bundler you picked during `npm create scenerystack@latest` in production mode and emits a static bundle — `dist/` for Vite/Esbuild, `build/` for some Webpack configs. That output is entirely self-contained: every `scenerystack/*` import, image, and sound file the bundler could resolve is already inlined or copied alongside the built JS. There is nothing GitHub Pages-specific about the build itself; the only thing you need to get right is *where the built files expect to be served from*.

## Setting the base path

Tell the bundler the site will live under `/<repo>/` rather than at the domain root. For a Vite-scaffolded project, this is the `base` option in `vite.config.ts`:

```ts
// vite.config.ts
import { defineConfig } from 'vite';

export default defineConfig( {
  base: '/my-simulation-repo/'
} );
```

For a Webpack-scaffolded project, the equivalent is `output.publicPath`:

```js
// webpack.config.js
module.exports = {
  output: {
    publicPath: '/my-simulation-repo/'
  }
};
```

If you're deploying to a *user or organization* Pages site (`https://<user>.github.io/`, not a project subpath), the base path is `/` and you can skip this step — that's the one case where the default root-relative config already matches.

## Option 1: publish the built output to a `gh-pages` branch

The simplest path for a one-off or infrequent deploy: build locally, then push the output directory to a `gh-pages` branch, which GitHub Pages serves from directly (configure this once in the repo's Settings → Pages → "Deploy from a branch").

```bash
npm run build
npx gh-pages -d dist
```

[`gh-pages`](https://www.npmjs.com/package/gh-pages) (add it with `npm install --save-dev gh-pages`) commits the contents of `dist/` to a `gh-pages` branch and force-pushes it, without disturbing your `main` branch's history. Repeat the two commands above whenever you want to publish a new version — nothing about this workflow is SceneryStack-specific, it's the standard static-site-on-Pages pattern applied to your build output.

## Option 2: a GitHub Actions workflow (recommended for anything shared)

Committing built artifacts to `gh-pages` by hand works, but it's easy to forget to rebuild before publishing, or to publish a build made with local, uncommitted changes. A workflow that builds from source on every push to `main` avoids both problems:

```yaml
# .github/workflows/deploy.yml
name: Deploy to GitHub Pages

on:
  push:
    branches: [main]

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - run: npm ci
      - run: npm run build

      - uses: actions/upload-pages-artifact@v3
        with:
          path: dist

      - id: deployment
        uses: actions/deploy-pages@v4
```

This uses GitHub's own `actions/deploy-pages` flow rather than a `gh-pages` branch — enable it once in Settings → Pages → Source → "GitHub Actions". Every push to `main` re-runs `npm ci && npm run build` in a clean environment, so what's published always matches what's committed; there's no local build step to remember, and no chance of publishing a build made against a dirty working tree.

| Piece | Why it's there |
| --- | --- |
| `npm ci` | Installs exactly the versions in `package-lock.json` — reproducible across CI runs, unlike `npm install` |
| `node-version: 20` | Match whatever Node version you develop against; see [Troubleshooting Common Setup Errors](/getting-started/troubleshooting-common-setup-errors) for why version drift causes build failures |
| `upload-pages-artifact` / `deploy-pages` | GitHub's official Pages-deployment actions — no third-party `gh-pages` dependency needed in the CI path |

## Verifying the deployed build

Once the workflow finishes (or the `gh-pages` push lands), visit `https://<user>.github.io/<repo>/`. Two failure modes are specific to this deployment shape rather than the simulation code itself:

- **Blank page, 404s in the console for JS/CSS/image files** — the base path wasn't set (or was set to `/` when the site actually lives at `/<repo>/`). Fix the bundler's `base`/`publicPath` and rebuild.
- **Page loads but sounds/images are missing** — usually a case-sensitivity mismatch between an import path and the actual filename; GitHub Pages' file server is case-sensitive even if your local OS filesystem isn't, so this can build and run locally while 404ing once deployed.

Also worth doing before you push: `npm run build`'s output has SceneryStack's runtime assertions compiled away (see [Running and Building a Simulation](/getting-started/running-and-building-a-simulation)), so bugs that assertions would have caught in dev can surface only in the deployed build. Serve `dist/` locally with a static file server (`npx serve dist`, or your bundler's `preview` command) and click through the sim before pushing to Pages, rather than discovering a production-only bug for the first time in front of users.

## Where to go next

- [Running and Building a Simulation](/getting-started/running-and-building-a-simulation) — the dev/build workflow this page's build step assumes
- [Troubleshooting Common Setup Errors](/getting-started/troubleshooting-common-setup-errors) — Node version and dependency issues that most often break a CI build
- [Supported Browsers](/getting-started/supported-browsers) — the platform matrix to verify against once deployed


========================================================================
Page: Installation and Setup
URL: https://veillette.github.io/Almanach/getting-started/installation-and-setup
Source: docs/getting-started/installation-and-setup.md
Category: Getting Started | Tags: setup, installation, tooling, typescript | Status: verified
========================================================================

# Installation and Setup

SceneryStack is a TypeScript framework, published as a single npm package. Before writing any code you need Node.js, npm, and (for cloning the underlying libraries) Git — everything else is standard JavaScript tooling.

## Prerequisites

| Tool | Why you need it |
| --- | --- |
| A command line (Terminal, PowerShell, etc.) | Running `npm`/`npx` commands |
| [Git](https://git-scm.com/downloads) | Checking out PhET's source repositories if you ever need to patch a library — see [Modifying SceneryStack](/guides/modifying-scenerystack) |
| [Node.js and npm](https://nodejs.org/) | Installing dependencies and running the dev server/build |

SceneryStack **is a TypeScript library**: it can be consumed from plain JavaScript, but its options objects rely entirely on compile-time types rather than runtime checks, so TypeScript is strongly recommended. Any editor with good TypeScript support works well — [VS Code](https://code.visualstudio.com/) and [WebStorm](https://www.jetbrains.com/webstorm/) are the two most commonly used by SceneryStack maintainers.

## Scaffolding a new project (recommended)

The fastest way to start a new simulation or application is the official scaffolding tool:

```bash
npm create scenerystack@latest
```

This walks you through:

- naming the project (it creates a directory with that name)
- choosing a bundler — [Vite](https://vite.dev/), [Webpack](https://webpack.js.org/), [Esbuild](https://esbuild.github.io/), or [Parcel](https://parceljs.org/)
- whether to set up [ESLint](https://eslint.org/) and [Prettier](https://prettier.io/)

...and prints the exact commands to install dependencies and open the running project in your browser. See [Your First Simulation](/getting-started/your-first-simulation) for what the generated code looks like, and [Running and Building a Simulation](/getting-started/running-and-building-a-simulation) for the dev-server/build workflow it wires up.

## Adding SceneryStack to an existing project

If you already have a bundler-based project and just want the library:

```bash
npm install scenerystack
```

Then import from the subpath for whichever library you need — `scenerystack` is not meant to be imported from its bare package root:

```ts
import { Node, Text } from 'scenerystack/scenery';
import { Property } from 'scenerystack/axon';
```

::: tip Import from subpaths, not the package root
Every SceneryStack library — `axon`, `dot`, `kite`, `scenery`, `sun`, `scenery-phet`, `joist`, `sim`, `tandem`, `phetcommon`, and others — is its own subpath export (`scenerystack/<library>`). There is no flat `scenerystack` import; see [What is SceneryStack?](/getting-started/what-is-scenerystack) for the full library table.
:::

## Where to go next

- [Your First Simulation](/getting-started/your-first-simulation) — build a minimal one-screen `Sim`
- [Scenery Application vs. Standalone Library](/getting-started/scenery-application-vs-standalone-library) — decide whether you even need `Sim`
- [Project Structure Conventions](/getting-started/project-structure-conventions) — how a SceneryStack repo is usually laid out
- [Supported Browsers](/getting-started/supported-browsers) — the platform support matrix to design against


========================================================================
Page: Project Structure Conventions
URL: https://veillette.github.io/Almanach/getting-started/project-structure-conventions
Source: docs/getting-started/project-structure-conventions.md
Category: Getting Started | Tags: conventions, project-structure, repo-layout | Status: verified
========================================================================

# Project Structure Conventions

`npm create scenerystack@latest` scaffolds a project, but it doesn't force a folder layout on your simulation-specific code — the conventions below are the ones PhET's own simulations (and most SceneryStack projects) converge on, because they keep [model-view separation](/patterns/model-view-separation) visible in the filesystem, not just in the code.

## A typical layout

```
my-simulation/
├── js/
│   ├── my-simulation-main.ts        # entry point: builds Screens and the Sim
│   ├── my-screen/
│   │   ├── model/
│   │   │   └── MyScreenModel.ts
│   │   └── view/
│   │       ├── MyScreenView.ts
│   │       └── MyThingNode.ts
│   └── common/                      # code shared by more than one screen
│       ├── model/
│       └── view/
├── images/                           # source art (SVG/PNG), one file per asset
├── sounds/                           # audio cues, if the sim uses scenery-phet sound
├── my-simulation-strings_en.json     # translatable strings, see Translation and Localization
├── package.json
├── tsconfig.json
└── index.html
```

The top-level split that matters most: **one folder per screen**, each with its own `model/` and `view/` subfolders, plus a `common/` folder for anything shared across screens. This mirrors the `Screen`/`ScreenView` pairing described in [Your First Simulation](/getting-started/your-first-simulation) — if your sim only has one screen, the per-screen folder is still worth keeping separate from `common/` so a second screen has somewhere obvious to go later.

## Where things live

| Path | Contents |
| --- | --- |
| `js/<screen-name>/model/` | Plain TypeScript classes holding `Property`/`Emitter` state — no `scenery` imports |
| `js/<screen-name>/view/` | `ScreenView` subclass plus any `Node` subclasses specific to that screen |
| `js/common/` | Model or view code shared by two or more screens |
| `images/` | Source images referenced via generated image modules (PNG, SVG, JPG) |
| `sounds/` | Audio files referenced the same way, for `scenery-phet`/`tambo` sound generators |
| `<sim-name>-strings_en.json` | The English source-of-truth strings file — see [Translation and Localization](/guides/translation-and-localization) |
| `<sim-name>-main.ts` | The only file that imports `Sim`/`Screen` and calls `onReadyToLaunch` |

::: tip Keep `model/` free of scenery imports
The fastest way to lose model-view separation over time is a stray `import { Node } from 'scenerystack/scenery'` inside a model file "just this once." If a model file ever needs to import from `scenerystack/scenery`, `sun`, or `scenery-phet`, that's a signal the code belongs in `view/` instead.
:::

## Where to go next

- [Running and Building a Simulation](/getting-started/running-and-building-a-simulation) — what the dev server and production build do with this layout
- [Model-View Separation](/patterns/model-view-separation) — the architectural rule this layout exists to reinforce
- [Translation and Localization](/guides/translation-and-localization) — how the strings file at the repo root becomes runtime `StringProperty` instances


========================================================================
Page: Running and Building a Simulation
URL: https://veillette.github.io/Almanach/getting-started/running-and-building-a-simulation
Source: docs/getting-started/running-and-building-a-simulation.md
Category: Getting Started | Tags: build, tooling, dev-server | Status: verified
========================================================================

# Running and Building a Simulation

A SceneryStack project is a normal bundler-based TypeScript web app: there's no SceneryStack-specific dev server or build tool, just the bundler you picked when scaffolding — [Vite](https://vite.dev/), [Webpack](https://webpack.js.org/), [Esbuild](https://esbuild.github.io/), or [Parcel](https://parceljs.org/) — configured to serve and bundle a page that imports `scenerystack/sim`.

## Development

`npm create scenerystack@latest` wires an npm script (conventionally `npm run dev` or `npm start`, depending on the bundler chosen) that starts the bundler's dev server:

```bash
npm run dev
```

This serves the sim with live reload at a `localhost` URL. Because a `Sim` fills the browser window and reads query parameters at startup (see [Preferences and Feature Flags](/guides/preferences-and-feature-flags)), the dev server URL is where you append query parameters while iterating, e.g. `http://localhost:5173/?ea` to enable assertions.

::: tip Enable assertions during development
Append `?ea` to the dev URL to turn on SceneryStack's runtime assertions. They catch invalid option values and API misuse immediately instead of failing silently or much later — always develop with `?ea` on, and rely on production builds (which strip it) for the assertion-free path users get.
:::

## Production build

The scaffolded build script runs the bundler in production mode:

```bash
npm run build
```

This produces a single self-contained bundle (plus any referenced assets) under the bundler's default output directory (`dist/` for Vite/Esbuild, `build/` for some Webpack configs). The output is static HTML/JS/CSS/media — it can be hosted from any static file server or CDN with no server-side runtime.

Two things distinguish a SceneryStack production build from a generic web app build:

| Aspect | Effect |
| --- | --- |
| Assertions stripped | Runtime `assert && assert(...)` checks used throughout SceneryStack compile away, so production is both smaller and faster than a dev build |
| Asset inlining | Images, sounds, and generated string modules referenced via `scenerystack/*` imports get bundled the same way any other module import does — no separate asset pipeline to configure |

## Where to go next

- [Supported Browsers](/getting-started/supported-browsers) — the platform matrix a production build should target
- [Preferences and Feature Flags](/guides/preferences-and-feature-flags) — query parameters available at both dev and production URLs
- [Project Structure Conventions](/getting-started/project-structure-conventions) — the source layout the bundler consumes


========================================================================
Page: Scenery Application vs. Standalone Library
URL: https://veillette.github.io/Almanach/getting-started/scenery-application-vs-standalone-library
Source: docs/getting-started/scenery-application-vs-standalone-library.md
Category: Getting Started | Tags: joist, scenery, standalone, architecture | Status: verified
========================================================================

# Scenery Application vs. Standalone Library

SceneryStack can be used two very different ways, and picking the right one up front saves you from unpicking a `Sim` later. The rule of thumb: **if you need multiple screens, a navigation bar, a home screen, PhET-iO instrumentation, or the Preferences dialog, use a `Sim` application. If you just need an interactive scene graph inside a page you already control, use `scenery` standalone.**

## Full application: `Sim` + `Screen` + `ScreenView`

This is the shape of every PhET simulation: a `Sim` owns one or more `Screen`s, each with a `ScreenView`, and `joist`/`sim` supplies the navigation bar, home screen, keyboard help, and Preferences dialog for free. See [Your First Simulation](/getting-started/your-first-simulation) for the full wiring — you don't manage a `Display` yourself, `Sim` does it internally via `SimDisplay`.

Reach for this when your project is a self-contained, full-window interactive experience — especially if you want the accessibility, internationalization, and PhET-iO scaffolding that come with `joist` "for free."

## Standalone: `scenery` without `joist`

If you only need a scene graph embedded in a larger page (a widget, a figure, an existing web app), skip `Sim`/`Screen` entirely and drive a `Display` yourself:

```html
<div id="app" style="width: 600px; height: 400px;"></div>
```

```ts
import { Display, Node, Rectangle, Text } from 'scenerystack/scenery';

const container = document.getElementById( 'app' )!;

const rootNode = new Node();
const display = new Display( rootNode, {
  width: container.clientWidth,
  height: container.clientHeight
} );
container.appendChild( display.domElement );

// Example content
const rotatingRectangle = new Rectangle( -150, -20, 300, 40, { fill: '#ccc' } );
const contentText = new Text( 'Content goes here', { font: '24px sans-serif' } );
rootNode.children = [ rotatingRectangle, contentText ];

contentText.center = display.bounds.center;
rotatingRectangle.translation = display.bounds.center;

display.initializeEvents(); // enable pointer/touch input
display.updateOnRequestAnimationFrame( dt => {
  rotatingRectangle.rotation += 2 * dt; // radians per second
} );
```

Key differences from a `Sim`:

| | Full application (`Sim`) | Standalone (`scenery` only) |
| --- | --- | --- |
| Owns the `Display` | Yes, internally (`SimDisplay`) | You create and size it |
| Multi-screen / navigation bar / home screen | Built in | Not applicable — build your own UI |
| Preferences dialog, PhET-iO | Built in | Opt in manually if needed |
| Sizing | Fills the browser window | You size the container and `Display` |
| Render/animation loop | Managed by `Sim` | You call `display.updateOnRequestAnimationFrame(...)` |
| Input events | Enabled automatically | You call `display.initializeEvents()` |

::: tip Both ways to get the npm package are the same
`npm create scenerystack@latest` scaffolds either shape — it asks what kind of project you want. For an existing project, `npm install scenerystack` and importing `scenerystack/scenery` directly works identically whether you build a `Sim` or go standalone; the two paths diverge in application code, not installation.
:::

## Where to go next

- [Scenery Basics](/guides/scenery-basics) — the Node tree, coordinate frames, and Display fundamentals used by both approaches
- [Your First Simulation](/getting-started/your-first-simulation) — the full-application path in detail
- [Scenery Layout](/guides/scenery-layout) — laying out content inside either a `ScreenView` or a standalone root `Node`


========================================================================
Page: Supported Browsers
URL: https://veillette.github.io/Almanach/getting-started/supported-browsers
Source: docs/getting-started/supported-browsers.md
Category: Getting Started | Tags: browsers, compatibility, deployment | Status: verified
========================================================================

# Supported Browsers

SceneryStack simulations target modern evergreen browsers on desktop and mobile — the same browsers PhET's own published sims support. Because `scenery` renders through Canvas, SVG, and WebGL rather than a single fixed technology, most compatibility differences are handled by scenery's renderer selection rather than by your application code.

## The platform matrix

| Platform | Support |
| --- | --- |
| Chrome / Chromium (desktop & Android) | Fully supported |
| Firefox (desktop & Android) | Fully supported |
| Safari (desktop & iOS/iPadOS) | Fully supported, including `mobileSafari` |
| Edge (Chromium-based) | Fully supported |
| Internet Explorer | Not supported |

`phet-core`'s `platform` object gives you runtime feature/browser detection when you need to special-case something (a workaround for a specific engine quirk, not a support gate):

```ts
import { platform } from 'scenerystack/phet-core';

if ( platform.safari ) {
  // e.g. work around a Safari-specific rendering quirk
}
```

| Property | Detects |
| --- | --- |
| `platform.safari` | Any Safari, including mobile (`platform.mobileSafari`) |
| `platform.firefox` | Firefox, desktop or mobile |
| `platform.chromium` | Chrome/Chromium-based browsers (excludes Edge) |
| `platform.edge` | Chromium-based Edge |
| `platform.android` | Android's WebView/browser |
| `platform.ie` | Internet Explorer (present for detection only — not a supported target) |

## Graceful degradation via renderer fallback

Every `Node` has a `renderer` option — `'svg' | 'canvas' | 'webgl' | 'dom' | null` — that scenery uses as a hint, not a hard requirement. Leaving it `null` (the default) lets scenery pick the best available backend per-subtree and fall back automatically if, say, WebGL isn't available:

```ts
import { Node } from 'scenerystack/scenery';

const heavyNode = new Node( {
  renderer: 'webgl' // hint only; scenery falls back to canvas/svg if WebGL is unavailable
} );
```

::: tip Don't force a renderer unless you've measured a problem
The historical `platform.firefox` example in scenery's own source (`if (platform.firefox) { node.renderer = 'canvas'; }`) is a workaround for a specific old performance issue, not a general pattern. Leave `renderer` unset by default; only pin it after profiling shows a specific subtree needs a specific backend.
:::

## Where to go next

- [Scenery Basics](/guides/scenery-basics) — how the Node tree maps to Canvas/SVG/WebGL output
- [Running and Building a Simulation](/getting-started/running-and-building-a-simulation) — the build step that ships to these browsers


========================================================================
Page: Troubleshooting Common Setup Errors
URL: https://veillette.github.io/Almanach/getting-started/troubleshooting-common-setup-errors
Source: docs/getting-started/troubleshooting-common-setup-errors.md
Category: Getting Started | Tags: troubleshooting, setup, typescript, tooling | Status: verified
========================================================================

# Troubleshooting Common Setup Errors

Most setup problems with a new SceneryStack project fall into a handful of recurring shapes: a Node version too old for the tooling, an import written against the package root instead of a subpath, a peer dependency the scaffolder assumed but didn't install, or a `tsconfig.json` module-resolution setting that doesn't understand package subpath exports. This page walks through each, with the error text you'll actually see and the fix.

## "Cannot find module 'scenerystack'" or "'scenerystack/scenery' has no exported member"

This is almost always an import written against the wrong place. SceneryStack does not export anything usable from its bare package root — every library is its own subpath:

```ts
// Wrong: nothing useful lives at the package root
import { Node } from 'scenerystack';

// Right: import from the subpath for the library you need
import { Node } from 'scenerystack/scenery';
import { Property } from 'scenerystack/axon';
```

If you're getting the "no exported member" flavor of this error rather than "cannot find module," double check you're importing the *class* from the *library* that actually exports it — a common slip is assuming `Sim`/`Screen`/`ScreenView` live in `scenerystack/joist` (the underlying repository's name) when the published package actually exports them from `scenerystack/sim`; `scenerystack/joist` exists but only exports supporting pieces. See [What is SceneryStack?](/getting-started/what-is-scenerystack) for the full library-to-subpath table.

## "SyntaxError: Unexpected token 'export'" or the dev server won't start

This is usually a Node version too old for the scaffolded tooling. SceneryStack's published package and its scaffolder (`npm create scenerystack@latest`) target current Node LTS releases; an old Node binary can fail confusingly rather than with a clear version error, especially inside a bundler's own dependency chain. Check your version and, if it's old, use a version manager to get current LTS:

```bash
node --version
# if it's below the current LTS line, e.g. Node 16 or 18:
nvm install --lts
nvm use --lts
```

Delete `node_modules` and reinstall after switching Node versions — native/binary dependencies (esbuild, some Vite optionals) are compiled per Node ABI version and a stale install can produce obscure runtime errors that look unrelated to Node at all:

```bash
rm -rf node_modules package-lock.json
npm install
```

## TypeScript can't resolve `scenerystack/*` subpaths

If plain imports work at runtime (the bundler resolves them fine) but the TypeScript language server or `tsc` reports `Cannot find module 'scenerystack/scenery' or its corresponding type declarations`, the project's `tsconfig.json` is using a `moduleResolution` mode that predates Node's package `exports` map support. SceneryStack's package.json declares its subpaths via `exports`, which requires one of the newer resolution modes:

```json
// tsconfig.json
{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "module": "ESNext",
    "target": "ES2022"
  }
}
```

`"moduleResolution": "node"` (the old default in many hand-written configs) only understands the legacy `main`/`module` fields, not subpath `exports`, and will fail to find types for anything under `scenerystack/*` even though the JavaScript resolves fine at bundle time. `"bundler"` (introduced in TypeScript 5.0) or `"node16"`/`"nodenext"` both understand `exports` maps correctly; `"bundler"` is what the official scaffolder generates and is the safer default if you're hand-writing a `tsconfig.json` for an existing project instead of scaffolding a new one.

## Missing peer dependency warnings after `npm install scenerystack`

Adding SceneryStack to an existing project (rather than scaffolding fresh) means you're responsible for the bundler and dev tooling yourself — `scenerystack` itself has no bundler as a dependency, so `npm install scenerystack` alone gets you the library but not something that can serve or build it. If you see the app fail to start with errors pointing at a missing bundler binary or config file, you likely skipped setting up Vite/Webpack/Esbuild/Parcel:

```bash
npm install scenerystack
npm install --save-dev vite   # or webpack, esbuild, parcel — whichever you're standardizing on
```

If you're not sure which bundler to use, `npm create scenerystack@latest` in a throwaway directory and copying its generated config is the fastest way to get a known-working baseline rather than assembling one from scratch — see [Installation and Setup](/getting-started/installation-and-setup).

## Assertions silently doing nothing

If invalid option values or misuse of the SceneryStack API aren't producing the errors you'd expect, check whether you're running with assertions enabled. Assertions are opt-in via a query parameter at dev time and compiled away entirely in production builds — a dev server URL without `?ea` behaves like a production build with respect to error-catching, which can make a real bug look like it "just doesn't happen" until it does, at a less convenient time:

```
http://localhost:5173/?ea
```

## Blank page with no console errors at all

If the page loads (no 404s, no thrown errors) but nothing renders, check that you're constructing the `Sim` inside `onReadyToLaunch`, not at module scope. SceneryStack's asset loader (fonts, images, generated strings) is asynchronous; a `Sim` constructed before it resolves can fail to paint without throwing, because the loader itself hasn't errored — it just hasn't finished. See [Your First Simulation](/getting-started/your-first-simulation) for the correct `onReadyToLaunch` wiring.

::: tip When in doubt, isolate with a fresh scaffold
If an error doesn't match anything above, scaffold a brand-new project with `npm create scenerystack@latest` in a scratch directory and reproduce the minimal failing case there. It rules out an entire category of causes — a stale lockfile, an accidentally hand-edited config, a Node/npm version mismatch specific to the broken project — in one step, and gives you a known-good baseline to diff your actual project's config against.
:::

## Where to go next

- [Installation and Setup](/getting-started/installation-and-setup) — the scaffolding and manual-install paths these errors most often stem from
- [Supported Browsers](/getting-started/supported-browsers) — platform-level compatibility issues, as distinct from local build/setup issues
- [Running and Building a Simulation](/getting-started/running-and-building-a-simulation) — the dev-server/build workflow referenced throughout this page


========================================================================
Page: What is SceneryStack?
URL: https://veillette.github.io/Almanach/getting-started/what-is-scenerystack
Source: docs/getting-started/what-is-scenerystack.md
Category: Getting Started | Tags: overview, installation, scenery, axon, dot, sun, joist | Status: verified
========================================================================

# What is SceneryStack?

SceneryStack is the open-source TypeScript framework behind [PhET Interactive Simulations](https://phet.colorado.edu). It provides everything needed to build accessible, multi-modal, interactive HTML5 applications: a scene graph renderer, a reactive state system, math utilities, UI components, and an application shell.

It is published as a single npm package, [`scenerystack`](https://www.npmjs.com/package/scenerystack), with each library exposed as a subpath export.

## The libraries

| Library | Import path | Purpose |
| --- | --- | --- |
| **axon** | `scenerystack/axon` | Reactive state: `Property`, `DerivedProperty`, `Emitter`, `Multilink` |
| **dot** | `scenerystack/dot` | Math: `Vector2`, `Bounds2`, `Matrix3`, `Range`, `Utils` |
| **kite** | `scenerystack/kite` | Geometric shapes and boolean operations: `Shape`, `LineStyles` |
| **scenery** | `scenerystack/scenery` | Scene graph: `Node`, `Path`, `Text`, input listeners, accessibility (PDOM) |
| **sun** | `scenerystack/sun` | UI components: buttons, sliders, checkboxes, combo boxes |
| **scenery-phet** | `scenerystack/scenery-phet` | Simulation-specific reusable components: arrows, thermometers, `PhetFont` |
| **twixt** | `scenerystack/twixt` | Animation and easing |
| **joist** | `scenerystack/sim` (app shell classes) / `scenerystack/joist` (preferences panels, locale utilities) | Application shell: `Sim`, `Screen`, `ScreenView`, navigation bar — see [Troubleshooting](/getting-started/troubleshooting-common-setup-errors) for why the import subpath differs from the library name |
| **tandem** | `scenerystack/tandem` | PhET-iO instrumentation and serialization |
| **phetcommon** | `scenerystack/phetcommon` | Shared utilities, notably `ModelViewTransform2` |

## Installation

```bash
npm install scenerystack
```

## A minimal example

```ts
import { Property } from 'scenerystack/axon';
import { Circle, Node } from 'scenerystack/scenery';
import { Vector2 } from 'scenerystack/dot';

// Model: reactive state, no view knowledge
const positionProperty = new Property( new Vector2( 0, 0 ) );

// View: a scenery Node that observes the model
const ball = new Circle( 20, { fill: 'crimson' } );
positionProperty.link( position => {
  ball.translation = position;
} );
```

This model/view split is the foundational pattern of every SceneryStack application — see [Model-View Separation](/patterns/model-view-separation).

## Where to go next

- [Model-View Separation](/patterns/model-view-separation) — the architecture every page in Almanach assumes
- [ModelViewTransform2](/api/phetcommon/model-view-transform) — mapping between model and view coordinates
- [Drag Listeners](/patterns/drag-listeners) — making nodes interactive
- [The Parallel DOM (PDOM)](/accessibility/pdom) — building accessible simulations


========================================================================
Page: Your First Simulation
URL: https://veillette.github.io/Almanach/getting-started/your-first-simulation
Source: docs/getting-started/your-first-simulation.md
Category: Getting Started | Tags: joist, sim, screen, tutorial | Status: verified
========================================================================

# Your First Simulation

A SceneryStack simulation is a `Sim` containing one or more `Screen`s, each pairing a plain model class with a `ScreenView`. This page walks through the smallest possible one-screen simulation, wired together by hand so you can see every piece that `npm create scenerystack@latest` normally generates for you.

::: warning `Sim`, `Screen`, and `ScreenView` live in `scenerystack/sim`, not `scenerystack/joist`
It's easy to assume the application shell classes are exported from `scenerystack/joist` since the underlying repository is named `joist`. In the published package they are actually exported from the **`scenerystack/sim`** subpath. `scenerystack/joist` exists too, but only exports supporting pieces (preferences panels, `CreditsNode`, locale utilities, and similar) — not `Sim`, `Screen`, or `ScreenView` themselves.
:::

## The model

Every screen's model just needs a `reset()` method (and, optionally, a `step(dt)` method if it animates):

```ts
class MyModel {
  public reset(): void {
    // reset any Properties here
  }

  public step( dt: number ): void {
    // advance the model by dt seconds, if needed
  }
}
```

## The view

A `ScreenView` is a `Node` with a `layoutBounds` describing its design-time coordinate frame:

```ts
import { ScreenView, type ScreenViewOptions } from 'scenerystack/sim';
import { Text } from 'scenerystack/scenery';

class MyScreenView extends ScreenView {
  public constructor( model: MyModel, providedOptions: ScreenViewOptions ) {
    super( providedOptions );

    const greetingText = new Text( 'Hello, SceneryStack!', {
      font: '24px sans-serif'
    } );
    greetingText.center = this.layoutBounds.center;
    this.addChild( greetingText );
  }
}
```

## Wiring up the Screen and Sim

```ts
import { Sim, Screen, onReadyToLaunch } from 'scenerystack/sim';
import { Tandem } from 'scenerystack/tandem';
import { Property } from 'scenerystack/axon';

const screenTandem = Tandem.ROOT.createTandem( 'myScreen' );

const myScreen = new Screen(
  () => new MyModel(),
  model => new MyScreenView( model, { tandem: screenTandem.createTandem( 'view' ) } ),
  {
    name: new Property( 'My Screen' ),
    backgroundColorProperty: new Property( 'white' ),
    tandem: screenTandem
  }
);

onReadyToLaunch( () => {
  const sim = new Sim( new Property( 'My First Simulation' ), [ myScreen ] );
  sim.start();
} );
```

A few things worth noting:

| Piece | Why it's there |
| --- | --- |
| `onReadyToLaunch` | Waits for SceneryStack's asynchronous asset loader (fonts, images, strings) before constructing the `Sim`. Always launch this way, never call `new Sim(...)` directly at module scope. |
| `Tandem` | PhET-iO's instrumentation identifier. Every `Screen` requires one, even if you never enable instrumentation — see [PhET-iO and Instrumentation](/guides/phet-io-and-instrumentation). |
| `name` | A `TReadOnlyProperty<string>`, not a plain string — this is what lets the sim title be translated. See [Translation and Localization](/guides/translation-and-localization). |

Since a single-screen sim has no home screen or navigation-bar screen icons, `homeScreenIcon`/`navigationBarIcon` can be omitted; they become required in practice once you add a second screen (see [Building Your First Screen](/guides/building-your-first-screen)).

## Where to go next

- [Building Your First Screen](/guides/building-your-first-screen) — adding a second screen and the model/view split in more depth
- [Model-View Separation](/patterns/model-view-separation) — the architecture this example already follows
- [Scenery Basics](/guides/scenery-basics) — everything you can put inside a `ScreenView`
- [PhET-iO and Instrumentation](/guides/phet-io-and-instrumentation) — what `Tandem` actually buys you


========================================================================
Page: Accessible Interaction Tutorial
URL: https://veillette.github.io/Almanach/guides/accessible-interaction-tutorial
Source: docs/guides/accessible-interaction-tutorial.md
Category: Guides | Tags: accessibility, tutorial, pdom, keyboard | Status: verified
========================================================================

# Accessible Interaction Tutorial

This walks through making one custom interaction — a draggable "planet" — fully accessible: operable with a mouse, a touchscreen, and a keyboard alone, and correctly announced by a screen reader. Each step below is necessary; skipping any one of them leaves a subset of users unable to use the interaction.

## Step 0: the model and view, unaccessible

Start from an ordinary [model-view separation](/patterns/model-view-separation) setup — a `positionProperty` and a `Circle` observing it:

```ts
import { Property } from 'scenerystack/axon';
import { Vector2 } from 'scenerystack/dot';
import { Circle } from 'scenerystack/scenery';

const positionProperty = new Property( new Vector2( 0, 0 ) );

const planetNode = new Circle( 20, { fill: 'steelblue', cursor: 'pointer' } );
positionProperty.link( position => {
  planetNode.translation = position;
} );
```

At this point nothing is accessible: there's no pointer interaction yet, and the Node doesn't exist in the [Parallel DOM](/accessibility/pdom) at all.

## Step 1: pointer + keyboard dragging together

Use `RichDragListener` so pointer and keyboard dragging are wired from one declaration instead of two separately-maintained listeners:

```ts
import { RichDragListener } from 'scenerystack/scenery';
import { Bounds2 } from 'scenerystack/dot';

planetNode.addInputListener( new RichDragListener( {
  positionProperty: positionProperty,
  dragBoundsProperty: new Property( new Bounds2( -200, -200, 200, 200 ) ),
  keyboardDragListenerOptions: {
    dragSpeed: 150,      // model units/second while a key is held
    shiftDragSpeed: 50   // finer control with Shift held
  }
} ) );
```

`RichDragListener`'s keyboard half only works once the Node is actually focusable — that's the next step.

## Step 2: joining the Parallel DOM

Give the Node a `tagName` (placing it in the PDOM at all) and make it `focusable`:

```ts
planetNode.tagName = 'div';
planetNode.focusable = true;
```

Without this, `RichDragListener`'s pointer half still works, but there is nothing in the tab order for a keyboard user to reach — the keyboard half of the listener never fires because the Node can never receive focus.

## Step 3: an accessible name and help text

A focusable, unnamed element is barely better than an unfocusable one — a screen reader announces it as "group" or similar, with no indication of what it is or does:

```ts
planetNode.accessibleName = 'Planet';
planetNode.accessibleHelpText = 'Move with arrow keys. Drag with a mouse or touch.';
```

`accessibleName` is what's announced when focus lands on the element; `accessibleHelpText` is supplementary guidance announced alongside it — keep the name short (a noun phrase) and put instructions in the help text, not the name.

## Step 4: focus order

If this Node isn't naturally reached in a sensible order via scene-graph traversal (e.g. it's added before some controls that should logically come first), set `pdomOrder` explicitly on its `ScreenView`:

```ts
screenView.pdomOrder = [
  massControlPanel,
  planetNode,
  resetAllButton
];
```

## Putting it together

```ts
import { Property } from 'scenerystack/axon';
import { Vector2, Bounds2 } from 'scenerystack/dot';
import { Circle, RichDragListener } from 'scenerystack/scenery';

const positionProperty = new Property( new Vector2( 0, 0 ) );

const planetNode = new Circle( 20, {
  fill: 'steelblue',
  cursor: 'pointer',

  // Parallel DOM
  tagName: 'div',
  focusable: true,
  accessibleName: 'Planet',
  accessibleHelpText: 'Move with arrow keys. Drag with a mouse or touch.'
} );

positionProperty.link( position => {
  planetNode.translation = position;
} );

planetNode.addInputListener( new RichDragListener( {
  positionProperty: positionProperty,
  dragBoundsProperty: new Property( new Bounds2( -200, -200, 200, 200 ) ),
  keyboardDragListenerOptions: { dragSpeed: 150, shiftDragSpeed: 50 }
} ) );
```

Scenery draws a visible focus highlight around focusable Nodes automatically once they're focused; override it with the `focusHighlight` option only if the default rectangle is visually wrong for your shape (e.g. a highlight that should hug a circular Node more tightly).

::: tip Verify with a keyboard, not just by reading the code
Unplug your mouse and tab to the Node: it should receive a visible focus highlight, be operable with arrow keys (and Shift for fine control), and a screen reader (or the browser's accessibility inspector) should announce the `accessibleName`/`accessibleHelpText` you set. Each of Steps 1–3 above is independently testable and independently easy to forget — verify all three, not just that dragging "works" with a mouse.
:::

## Where to go next

- [The Parallel DOM (PDOM)](/accessibility/pdom) — the full accessibility-option reference this tutorial draws from
- [Drag Listeners](/patterns/drag-listeners) — `DragListener`/`KeyboardDragListener`/`RichDragListener` in more depth
- [Scenery Input](/guides/scenery-input) — the lower-level pointer/event model these listeners are built on


========================================================================
Page: Advanced Layout Techniques
URL: https://veillette.github.io/Almanach/guides/advanced-layout-techniques
Source: docs/guides/advanced-layout-techniques.md
Category: Guides | Tags: scenery, layout, manual-constraint, align-group | Status: verified
========================================================================

# Advanced Layout Techniques

[Scenery Layout](/guides/scenery-layout) covers `FlowBox`, `GridBox`, and `AlignBox` as if each layout problem needs exactly one container. Real screens usually need containers nested inside each other, the occasional position that no container option quite expresses, and content in *separate* containers that still needs to agree on a common size. This page covers the three techniques that come up once you're past the basics: nesting `FlowBox`/`GridBox`, dropping to `ManualConstraint` for the cases layout containers don't model, and `AlignGroup` for cross-container sizing.

## Nesting FlowBox and GridBox

A `FlowBox` or `GridBox` doesn't care whether its children are leaf Nodes or other layout containers — nesting is just composition. This is how you build a two-axis layout out of two one-axis containers, or a toolbar-with-groups shape where each group has its own internal spacing:

```ts
import { HBox, VBox, Text, Rectangle } from 'scenerystack/scenery';

const colorSwatch = ( color: string ) => new Rectangle( 0, 0, 16, 16, { fill: color } );

// A row of "swatch + label" pairs, each pair itself laid out as a small HBox.
const legendRow = ( color: string, label: string ) => new HBox( {
  spacing: 6,
  children: [ colorSwatch( color ), new Text( label, { font: '14px sans-serif' } ) ]
} );

// The rows stack vertically as a VBox, each row internally an HBox.
const legend = new VBox( {
  spacing: 4,
  align: 'left',
  children: [
    legendRow( 'crimson', 'Reactant' ),
    legendRow( 'royalblue', 'Product' ),
    legendRow( 'gray', 'Catalyst' )
  ]
} );
```

Each inner `HBox` reports its own computed bounds up to the outer `VBox` exactly as any other child would — the outer container has no idea it's laying out other layout containers rather than leaf Nodes. This is the main tool for building anything more structured than "one row" or "one column": decompose the screen into the smallest one-axis pieces, then compose them.

The one thing to watch when nesting is that both levels are trying to manage size. If an inner `HBox` has `stretch: true` children but the outer `VBox` never gives it a `preferredWidth` to stretch into (because, say, the outer container's own `align` is `'left'` rather than `'stretch'`), the inner stretch option silently has nothing to do. Match `align`/`stretch` intentionally through the nesting rather than copying it reflexively at every level.

## ManualConstraint: escaping to imperative positioning without losing reactivity

`FlowBox`/`GridBox`/`AlignBox` cover flow and grid relationships, but not every layout is a flow or a grid — sometimes you need "this label's left edge is 5 pixels right of that icon's right edge, regardless of either one's size," expressed once and kept correct as either Node's bounds change. That's what `ManualConstraint` is for: it re-runs an arbitrary positioning callback you write, every time any of the Nodes it watches changes bounds, using `LayoutProxy` objects that behave like the positional getters/setters on `Node` (`left`, `right`, `centerY`, etc.) but work correctly even across a shared ancestor rather than requiring a direct parent-child relationship.

```ts
import { ManualConstraint, Node, Circle, Text } from 'scenerystack/scenery';

const root = new Node();
const icon = new Circle( 12, { fill: 'orange' } );
const label = new Text( 'Temperature', { font: '16px sans-serif' } );
root.children = [ icon, label ];

new ManualConstraint( root, [ icon, label ], ( iconProxy, labelProxy ) => {
  labelProxy.left = iconProxy.right + 5;
  labelProxy.centerY = iconProxy.centerY;
} );
```

The first argument is the common ancestor Node whose coordinate frame the constraint reasons in — it doesn't need to be the direct parent of either watched Node, only an ancestor of both. The constraint re-runs the callback automatically whenever `icon` or `label`'s bounds change (a translated string swapping in a longer label, an icon resizing), so `labelProxy.left`/`centerY` stay correct without you re-wiring a bounds listener by hand. It's tempting to solve this same problem with `node.boundsProperty.link(...)` and manual `x`/`y` math instead — `ManualConstraint` is that same idea, generalized and already handling the cross-coordinate-frame case correctly, so prefer it over a bespoke listener unless you have a reason its callback shape genuinely can't express.

## AlignGroup: matching sizes across independent containers

`AlignBox` (covered briefly in [Scenery Layout](/guides/scenery-layout)) wraps one child and reserves alignment space for it — but the interesting behavior shows up when several `AlignBox`es share one `AlignGroup`. Every box in the group reports the same size to whatever lays *it* out: the largest content among them, recomputed as any member's content changes. This is exactly the case where a set of sibling panels (say, one per element in a periodic-table-style grid, or one per row of a settings panel) need to occupy equal-sized cells even though their actual content — a short label versus a long one — doesn't.

```ts
import { AlignGroup, AlignBox, HBox, Text, Panel } from 'scenerystack/scenery';

const group = new AlignGroup( { matchHorizontal: true, matchVertical: true } );

const makePanel = ( labelText: string ) =>
  new Panel( group.createBox( new Text( labelText, { font: '16px sans-serif' } ), {
    xAlign: 'left',
    xMargin: 10
  } ) );

const panels = new HBox( {
  spacing: 8,
  children: [
    makePanel( 'On' ),
    makePanel( 'A much longer setting label' ),
    makePanel( 'Off' )
  ]
} );
```

`group.createBox(...)` is the same as constructing an `AlignBox` directly with `{ group }` passed in its options — it's a convenience for the common case of "make a box in this group." All three panels above end up exactly as wide and tall as the longest/tallest one needs, even though each is built independently and doesn't know about its siblings. `matchHorizontal`/`matchVertical` (both default `true`) control which axis participates in the shared sizing — set one to `false` if you only want, say, matching height with each box free to be its natural width.

Because `AlignGroup` recomputes its shared size whenever *any* member's content changes, order matters when content is populated dynamically: per the class's own guidance, if a group is populated incrementally and a UI component doesn't support resizing its own contents after the fact (some `sun` components), populate the group largest-content-first so the shared size is correct from the start rather than growing after initial layout.

::: warning AlignGroup sizing can lag one layout pass behind a bounds change
The class doc for `AlignGroup` calls out that resizes may not take effect immediately — they can be deferred until the next bounds computation for a member box's content, though anything already connected to a `Display` picks this up automatically on `Display.updateDisplay()`. If you need the recomputed size synchronously (rare — usually only relevant in tests or before the group's boxes are attached to a Display), call `group.updateLayout()` explicitly rather than assuming the size is current the instant you swap a member's content.
:::

## Where to go next

- [Scenery Layout](/guides/scenery-layout) — `FlowBox`/`GridBox`/`AlignBox` fundamentals this page builds on
- [Scenery Basics](/guides/scenery-basics) — the `bounds`/`localBounds` distinction that all of these layout mechanisms depend on
- [AlignBox](/api/scenery/align-box) — the per-child container `AlignGroup` coordinates across


========================================================================
Page: Building Your First Screen
URL: https://veillette.github.io/Almanach/guides/building-your-first-screen
Source: docs/guides/building-your-first-screen.md
Category: Guides | Tags: screen, tutorial, joist | Status: verified
========================================================================

# Building Your First Screen

[Your First Simulation](/getting-started/your-first-simulation) builds a single screen with no home screen. Adding a **second** screen changes two things: `homeScreenIcon`/`navigationBarIcon` become effectively required (there's now a home screen to show them on), and each screen's model/view pair needs to be self-contained enough to run independently, since users can jump between screens freely.

## 1. The model

Keep the model free of any `scenery`/`sun` imports — see [Model-View Separation](/patterns/model-view-separation):

```ts
// model/BounceScreenModel.ts
import { NumberProperty, Property } from 'scenerystack/axon';
import { Vector2 } from 'scenerystack/dot';

export default class BounceScreenModel {
  public readonly positionProperty = new Property( new Vector2( 0, 0 ) );
  public readonly speedProperty = new NumberProperty( 5 ); // m/s

  public step( dt: number ): void {
    // advance position by speed * dt, bounce off walls, etc.
  }

  public reset(): void {
    this.positionProperty.reset();
    this.speedProperty.reset();
  }
}
```

## 2. The view

A `ScreenView` composes your custom `Node`s plus the shared components every screen needs — commonly a `ResetAllButton` wired to the [Reset-All Pattern](/patterns/reset-all-pattern):

```ts
// view/BounceScreenView.ts
import { ScreenView, type ScreenViewOptions } from 'scenerystack/sim';
import { Circle } from 'scenerystack/scenery';
import { ResetAllButton } from 'scenerystack/scenery-phet';
import type BounceScreenModel from '../model/BounceScreenModel.js';

export default class BounceScreenView extends ScreenView {
  public constructor( model: BounceScreenModel, providedOptions: ScreenViewOptions ) {
    super( providedOptions );

    const ball = new Circle( 15, { fill: 'crimson' } );
    model.positionProperty.link( position => {
      ball.translation = position; // through a ModelViewTransform2 in a real sim with non-1:1 scale
    } );

    const resetAllButton = new ResetAllButton( {
      listener: () => model.reset(),
      right: this.layoutBounds.maxX - 20,
      bottom: this.layoutBounds.maxY - 20
    } );

    this.children = [ ball, resetAllButton ];
  }

  public step( dt: number ): void {
    // view-only animation, if any; model stepping happens via Screen's own step wiring
  }
}
```

Use [`FlowBox`/`GridBox`](/guides/scenery-layout) instead of hand-placed `Circle`s once a screen has more than a couple of controls.

## 3. Icons for the home screen and navigation bar

With more than one screen, each `Screen` needs a `ScreenIcon` — a small preview shown on the home screen and (scaled down) in the navigation bar:

```ts
import { ScreenIcon } from 'scenerystack/sim';
import { Rectangle } from 'scenerystack/scenery';

const bounceScreenIcon = new ScreenIcon( new Rectangle( 0, 0, 100, 100, { fill: 'crimson' } ), {
  maxIconWidthProportion: 0.85,
  maxIconHeightProportion: 0.85,
  fill: 'white' // background behind the icon content
} );
```

If `navigationBarIcon` is omitted, it defaults to `homeScreenIcon`, scaled down — supply a distinct one only if the default is illegible at navigation-bar size.

## 4. Wiring the Screen

```ts
// bounce-screen-main.ts
import { Screen } from 'scenerystack/sim';
import { Tandem } from 'scenerystack/tandem';
import { Property } from 'scenerystack/axon';
import BounceScreenModel from './model/BounceScreenModel.js';
import BounceScreenView from './view/BounceScreenView.js';

const screenTandem = Tandem.ROOT.createTandem( 'bounceScreen' );

export const bounceScreen = new Screen(
  () => new BounceScreenModel(),
  model => new BounceScreenView( model, { tandem: screenTandem.createTandem( 'view' ) } ),
  {
    name: new Property( 'Bounce' ),
    backgroundColorProperty: new Property( 'white' ),
    homeScreenIcon: bounceScreenIcon,
    tandem: screenTandem
  }
);
```

## 5. Adding it to the Sim

Pass every screen's exported `Screen` instance to `Sim` in array order — that order becomes both the home screen layout and the navigation bar order:

```ts
import { Sim, onReadyToLaunch } from 'scenerystack/sim';
import { Property } from 'scenerystack/axon';
import { firstScreen } from './first-screen-main.js';
import { bounceScreen } from './bounce-screen-main.js';

onReadyToLaunch( () => {
  const sim = new Sim( new Property( 'My Simulation' ), [ firstScreen, bounceScreen ] );
  sim.start();
} );
```

::: tip Each screen's model/view pair should assume nothing about other screens
Since `Screen`'s `createModel`/`createView` factories run lazily and users can switch screens at any point, a screen's model and view must be constructible and steppable in isolation — don't reach into another screen's model directly. Share state across screens (if genuinely needed) via a model object constructed once in the main file and passed to both screens' factories, not via one screen importing another's internals.
:::

## Where to go next

- [PhET-iO and Instrumentation](/guides/phet-io-and-instrumentation) — what the `tandem` wiring above actually enables
- [Scenery Layout](/guides/scenery-layout) — arranging a screen's controls with `FlowBox`/`GridBox` instead of manual positions
- [The Reset-All Pattern](/patterns/reset-all-pattern) — the full contract for `model.reset()` and `ResetAllButton`


========================================================================
Page: Chart and Data Visualization with Bamboo
URL: https://veillette.github.io/Almanach/guides/chart-and-data-visualization-with-bamboo
Source: docs/guides/chart-and-data-visualization-with-bamboo.md
Category: Guides | Tags: bamboo, chart, data-visualization, ChartTransform | Status: complete
========================================================================

# Chart and Data Visualization with Bamboo

`bamboo` (`scenerystack/bamboo`) is SceneryStack's charting library — it renders datasets as line/bar/scatter/area plots, draws axes and gridlines, and does it all through one shared coordinate object every piece of a chart is built around. This page is a subsystem-level tour of how the pieces fit together; each linked API page documents one class in depth.

## ChartTransform: the object everything else is built on

Every bamboo Node — every plot type, every axis, every gridline set — takes a [`ChartTransform`](/api/bamboo/chart-transform) in its constructor and rebuilds itself whenever that transform's `changedEmitter` fires. `ChartTransform` is not itself a `Node` — it's a plain object holding the chart's model-coordinate ranges (`modelXRange`, `modelYRange`) and view-coordinate size (`viewWidth`, `viewHeight`), plus the conversion math between the two:

```ts
import { ChartTransform, ChartRectangle, LinePlot, AxisArrowNode } from 'scenerystack/bamboo';
import { Orientation } from 'scenerystack/phet-core';
import { Range, Vector2 } from 'scenerystack/dot';

const chartTransform = new ChartTransform( {
  viewWidth: 400,
  viewHeight: 200,
  modelXRange: new Range( 0, 10 ),
  modelYRange: new Range( -1, 1 )
} );

const chartRectangle = new ChartRectangle( chartTransform, { stroke: 'gray' } );
const xAxis = new AxisArrowNode( chartTransform, Orientation.HORIZONTAL );

const dataSet: ( Vector2 | null )[] = [];
for ( let x = 0; x <= 10; x += 0.1 ) {
  dataSet.push( new Vector2( x, Math.sin( x ) ) );
}
const linePlot = new LinePlot( chartTransform, dataSet, { stroke: 'blue' } );

// A resize (or panning/zooming the chart) is one call, and every attached Node redraws together.
chartTransform.setViewWidth( 600 );
```

This is the single most important thing to internalize about bamboo: **a chart is a loose collection of independent Nodes that happen to share one `ChartTransform`**, not one monolithic "Chart" class you configure. Adding a second plot type to the same chart is just constructing another Node against the same `chartTransform` — there's no chart-level API to register plots with.

## The plot Node family

Each plot type is a distinct `Node` subclass specialized for one data shape — pick based on what the dataset actually represents, not by look alone:

| Plot | Dataset shape | Use it for |
| --- | --- | --- |
| [`LinePlot`](/api/bamboo/line-plot) | `(Vector2 \| null)[]`, connected by straight segments | A sampled continuous function or time series; `null` entries create gaps for missing/discontinuous data |
| [`AreaPlot`](/api/bamboo/area-plot) | Same shape as `LinePlot` | The same kind of data as `LinePlot`, shaded down to a baseline — cumulative quantities, or emphasizing magnitude rather than just the curve's shape |
| [`BarPlot`](/api/bamboo/bar-plot) | `Vector2[]`, one bar per point, numeric x only | Discrete quantities at discrete x-values, growing from a shared baseline |
| [`ScatterPlot`](/api/bamboo/scatter-plot) | `Vector2[]`, one circle per point | Unconnected discrete data points — measurements, samples — where connecting them with lines would imply a relationship that isn't there |
| [`LinearEquationPlot`](/api/bamboo/linear-equation-plot) | A slope `m` and intercept `b`, no dataset at all | A reference/threshold/best-fit line spanning the chart's entire model range, not a curve through sampled points |

All five extend either `scenery`'s `Path` or `Node` and rebuild their drawn geometry in an internal `update()`, called on construction and whenever `chartTransform.changedEmitter` fires — so once a plot is constructed against a transform, updating the transform (a resize, a pan) or calling the plot's own `setDataSet()` is all that's needed to keep it visually correct; nothing needs to be manually re-laid-out.

## Axes and gridlines: decoration, not structure

[`AxisLine`/`AxisArrowNode`](/api/bamboo/axis-nodes) draw the x/y axis lines themselves (plain or arrow-tipped), and [`GridLineSet`, `TickMarkSet`, and `TickLabelSet`](/api/bamboo/gridlines-and-tick-marks) draw the repeating reference lines, tick marks, and numeric tick labels behind or alongside the data, all at a fixed model-coordinate spacing. All of these are, like the plots, independent Nodes constructed against the same `ChartTransform` — a chart with no axis or gridline Nodes at all is still a perfectly valid, if sparse, bamboo chart; they're additive decoration, not something a plot depends on to render correctly.

## Composing a full chart

A typical bamboo chart is a `Node` (or the `ScreenView` itself) with several bamboo Nodes as children, all built from one `ChartTransform`, layered in the usual scenery stacking order — background/gridlines first, data plots in the middle, axes and labels on top:

```ts
import { GridLineSet } from 'scenerystack/bamboo';

const verticalGridLines = new GridLineSet( chartTransform, Orientation.VERTICAL, 1, {
  stroke: 'lightGray'
} );

const chartNode = new Node( {
  children: [
    chartRectangle,       // background + border
    verticalGridLines,    // reference gridlines, behind the data
    linePlot,             // the data itself
    xAxis                 // axis line/arrow on top
  ]
} );
```

Panning or zooming the whole chart is then a single `chartTransform.setModelXRange( newRange )` (or `setViewWidth`/`setViewHeight` for a resize) — every child Node listening to `changedEmitter` redraws itself in response, with no coordination code needed between them.

## Large datasets: CanvasLinePlot instead of LinePlot

Every plot type above extends an ordinary scenery `Path`/`Node`, which means a dataset large enough (many thousands of points, redrawn every frame) can start to show up as real overhead — one scenery drawable's bookkeeping cost, multiplied by every point. [`CanvasLinePlot`](/api/bamboo/canvas-line-plot) is bamboo's answer for that specific case: it paints the same kind of `(Vector2 | null)[]` dataset as `LinePlot`, but directly to a `CanvasRenderingContext2D` via a shared `ChartCanvasNode`, rather than building a scenery `Shape`. Reach for it only once profiling (see [Performance and Profiling](/guides/performance-and-profiling)) actually shows `LinePlot`'s per-point overhead as the bottleneck — for anything smaller, `LinePlot`'s automatic redraw wiring and ordinary `Path` semantics (hit-testing, easy composition with other Nodes) are simpler to work with.

::: tip Dispose a chart's Nodes the same as any dynamically-created view
Every bamboo Node holds a listener on its `ChartTransform`'s `changedEmitter`, which its own `dispose()` removes — but if a chart itself is created and destroyed dynamically (not for the sim's lifetime), the usual [Dispose and Memory Management](/patterns/dispose-and-memory-management) discipline still applies: dispose each plot/axis Node (and the `ChartTransform` itself, via its own `dispose()`) when the chart is torn down, the same as any other transient view.
:::

## Where to go next

- [ChartTransform](/api/bamboo/chart-transform) — the full API for the shared coordinate object this page is built around
- [LinePlot](/api/bamboo/line-plot), [BarPlot](/api/bamboo/bar-plot), [ScatterPlot](/api/bamboo/scatter-plot), [AreaPlot](/api/bamboo/area-plot), [LinearEquationPlot](/api/bamboo/linear-equation-plot) — the individual plot types
- [AxisLine and AxisArrowNode](/api/bamboo/axis-nodes) — axis decoration
- [GridLineSet, TickMarkSet, and TickLabelSet](/api/bamboo/gridlines-and-tick-marks) — gridline/tick decoration
- [CanvasLinePlot](/api/bamboo/canvas-line-plot) — the Canvas-painted variant for very large datasets


========================================================================
Page: Continuous Integration for SceneryStack Projects
URL: https://veillette.github.io/Almanach/guides/continuous-integration-for-scenerystack-projects
Source: docs/guides/continuous-integration-for-scenerystack-projects.md
Category: Guides | Tags: ci, testing, build, tooling, quality | Status: complete
========================================================================

# Continuous Integration for SceneryStack Projects

A SceneryStack simulation is a normal bundler-based TypeScript web app (see [Running and Building a Simulation](/getting-started/running-and-building-a-simulation)), so its CI pipeline looks like any other TypeScript project's — the checks below aren't SceneryStack-specific machinery, they're the standard set applied to a project that happens to be a simulation. What *is* worth calling out is the order and the specific failure modes each check is aimed at, since a sim repo has a couple of failure modes (assertion-only bugs, fuzz-crashes) a generic web app CI checklist wouldn't otherwise think to include.

## What a pipeline typically checks, in order

| Check | Catches | Roughly maps to |
| --- | --- | --- |
| Type-check (`tsc --noEmit`, or the bundler's own type-check step) | Type errors that would only surface at runtime otherwise | Fastest, cheapest check — run first so a trivial mistake fails in seconds |
| Lint (ESLint, or whatever the project scaffolded) | Style/consistency issues, common bug patterns (unused variables, missing `dispose()` overrides caught by custom rules, etc.) | Also fast, independent of the other checks |
| Unit tests | Model logic regressions | [Testing Model Logic Headlessly](/patterns/testing-model-logic-headlessly) — runs in plain Node.js, no browser needed |
| Production build (`npm run build`) | Bundler configuration errors, missing assets, import errors that only show up once the whole dependency graph is resolved | [Running and Building a Simulation](/getting-started/running-and-building-a-simulation) |
| Automated fuzz-testing (optional but recommended) | Crashes from input sequences no test author thought to write by hand | [Fuzz-Testing a Simulation Locally](/cookbook/fuzz-testing-a-simulation-locally), run headlessly against a built or served sim |

Ordering matters mostly for feedback speed: type-checking and linting fail in seconds and don't require installing a browser or building anything, so they should fail first and fast, before a slower build or fuzz step ever starts. A CI configuration that runs the production build before the type-check just means a contributor waits longer to find out about a typo.

## Why the production build itself is a check, not just an artifact

`npm run build` catches a category of bug that neither the type-checker nor unit tests can see: a bundler misconfiguration (a wrong base path, an unresolvable asset import, a circular dependency the dev server tolerated but the production bundler doesn't) only surfaces when the whole project is actually bundled for production. Running `npm run build` in CI — even if nothing downstream of it deploys the result — is what guarantees "it built on my machine" isn't the first time a break in the build is discovered.

## Automated fuzzing in CI

Once a sim can be served (locally, or from the CI job's own build output), running it under `?fuzz` for a fixed duration and failing the job on any uncaught exception (see [Fuzz-Testing a Simulation Locally](/cookbook/fuzz-testing-a-simulation-locally)) extends the "does this crash" question from "did a human happen to try this sequence of clicks" to "did we throw a few thousand randomized ones at it." This is the one check in the table that needs an actual browser (typically headless, via Playwright/Puppeteer or similar) rather than just Node.js — budget it as a separate, slower CI job if the rest of the pipeline is otherwise browser-free.

## A concrete illustration: Almanach's own CI

This documentation site isn't a simulation, but its own CI pipeline (`.github/workflows/ci.yml` in this repository) follows the same shape at a smaller scale, and is a real, inspectable example of the pattern: checkout, install with `npm ci` (not `npm install` — reproducible against the lockfile), then two validation steps (`npm run generate`, which fails loudly on frontmatter/link errors, and `npx vitepress build docs`, the production build) — both gating whether a pull request can merge. A separate workflow (`.github/workflows/deploy.yml`) only runs the production build and publishes it, on pushes to `main`, after those checks would already have passed on the corresponding PR. The same two-workflow split — one that verifies on every change, one that builds-and-publishes only on `main` — is a reasonable default for a sim repo too: run type-check/lint/tests/build/fuzz on every PR, and reserve the publish step (see [Deploying a Simulation to GitHub Pages](/getting-started/deploying-to-github-pages)) for a separate workflow gated on the first one passing.

::: tip Use `npm ci`, not `npm install`, in every CI job
`npm ci` installs exactly the versions recorded in `package-lock.json` and fails outright if the lockfile and `package.json` are out of sync, rather than silently resolving new versions the way `npm install` can. A CI pipeline's entire value proposition — "if it's green, it works the same way it will everywhere else" — depends on every run installing identical dependencies, not whatever happened to be newest that day.
:::

## Where to go next

- [Testing and QA Strategy Overview](/guides/testing-and-qa-strategy-overview) — how CI's automated checks fit alongside manual QA passes
- [Running and Building a Simulation](/getting-started/running-and-building-a-simulation) — the build step CI is verifying
- [Fuzz-Testing a Simulation Locally](/cookbook/fuzz-testing-a-simulation-locally) — the recipe a fuzz-testing CI job automates


========================================================================
Page: Debugging Common Scenery Rendering Issues
URL: https://veillette.github.io/Almanach/guides/debugging-common-scenery-rendering-issues
Source: docs/guides/debugging-common-scenery-rendering-issues.md
Category: Guides | Tags: scenery, debugging, rendering, layout, troubleshooting | Status: complete
========================================================================

# Debugging Common Scenery Rendering Issues

Most "why isn't this showing up" or "why is this in the wrong place" bugs in a scenery scene graph fall into a small number of recurring shapes. This page walks through the three most common ones and the specific thing to check for each, before reaching for a debugger or filing a bug against scenery itself — the overwhelming majority of these turn out to be one property on one Node.

## "My Node isn't visible"

Work through these in order — each is more specific than the last, and any one of them alone is enough to make otherwise-correct content invisible:

| Check | Why it hides content |
| --- | --- |
| `node.visible` / `node.visibleProperty.value` | `false` removes the Node from painting (and, by default, from input) while leaving it in the tree — this is the most common cause, especially when visibility is driven by a `DerivedProperty` that isn't computing what you expect |
| `node.opacity` | `0` paints nothing even though the Node is technically `visible`; easy to leave at `0` after a fade-out animation that never reset it |
| `node.bounds` / `node.localBounds` | A Node with empty or `NaN` bounds (e.g. a `Path` built from an empty `Shape`, or geometry computed from a not-yet-loaded value) often silently draws nothing rather than throwing — check `bounds` in the console for `NaN` or a zero-size rectangle |
| Ancestor visibility | `visible`/`opacity` on this Node don't matter if an **ancestor** in the tree is invisible or fully transparent — walk up the parent chain, not just the Node itself, when a whole region is missing |
| Being added at all | A Node constructed but never `addChild`-ed anywhere in the displayed tree is, correctly, never painted — confirm the Node is actually reachable from the `Display`'s root, not just that it exists |
| `pickable` (a distinct but related symptom) | `pickable = false` doesn't hide anything visually, but if the *symptom* you're chasing is actually "clicks pass through" rather than "nothing draws," this — not `visible` — is the property to check; see [Hit-Testing and Picking](/api/scenery/hit-testing-and-picking) |

## "My layout isn't updating"

Layout bugs are usually a mismatch between what you changed and what the layout container actually watches:

- **Check `preferredWidth`/`preferredHeight` are actually being set on the container that should resize.** Scenery's [`Sizable`](/guides/scenery-layout) trait-based Nodes (`FlowBox`, `GridBox`, and anything opting into `WidthSizable`/`HeightSizable`) resize their content in response to their own `preferredWidth`/`preferredHeight` being set by *something* — usually a parent layout container, or the `ScreenView`'s `visibleBoundsProperty` for top-level content. If nothing ever sets a preferred dimension on a Sizable Node, it stays at its content's natural size no matter how much surrounding space is available.
- **Check you're not fighting the container by setting `x`/`y`/`translation` directly.** As [Scenery Layout](/guides/scenery-layout#margins-shared-across-containers) points out, once a Node is a child of a `FlowBox`/`GridBox`, the container sets its position every layout pass — any `translation` you set afterward is silently overwritten on the next pass, which reads exactly like "layout isn't updating" when the actual cause is "layout keeps winning."
- **Check `layoutOptions` are on the child, not the container**, for per-child overrides (`grow`, per-child margins). A `layoutOptions` object set on the wrong Node — the container instead of the child, or vice versa — is silently ignored rather than erroring.
- **Confirm the thing that changed size is actually observed.** If a child's own content changed (a `Text` Node's string got longer after a translated-string update), its `bounds` change automatically and its parent `FlowBox`/`GridBox` re-lays-out on the next frame — but a manually-managed layout (Nodes positioned by hand, not inside a layout container) has no such mechanism and needs its position recomputed explicitly wherever the content change is handled.

## "Things are drawn in the wrong stacking order"

Scenery has no z-index — stacking order is purely the order of entries in each Node's `children` array, drawn first-to-last (see [Scenery Basics](/guides/scenery-basics#the-node-tree)). A Node "behind" something it should be in front of (or vice versa) is a `children` ordering bug, not a separate property to set:

- `node.addChild( child )` always appends to the *end* — the topmost stacking position — regardless of the child's position in space. If a new Node needs to render underneath existing siblings, use `insertChild( 0, child )` (or the appropriate index) instead of `addChild`.
- Reordering existing children (moving one to the front without removing/re-adding it) is `node.moveChildToFront( child )` / `moveChildToBack( child )`, not a style property.
- Remember this is a **per-parent** ordering: two Nodes with no common parent don't have a meaningful relative stacking order to reason about — if two subtrees visually overlap and need a deterministic order, they need a common ancestor whose `children` array you control.

## Tools beyond eyeballing the tree

Once the checks above don't turn up the cause, [Performance and Profiling](/guides/performance-and-profiling#finding-the-bottleneck-built-in-profiling-query-parameters) documents several built-in debug query parameters that also help narrow down rendering (not just performance) problems — `?showPointerAreas` and `?showHitAreas` for input-region mismatches, `?showCanvasNodeBounds` for a `CanvasNode` drawing outside its declared bounds, and `?dev` for a broader bundle of developer-facing overlays. For content painted through the non-standard renderer escape hatches, see [`WebGLNode`, `CanvasNode`, and `DOM`](/api/scenery/rendering-backends) — bugs in a `CanvasNode`'s `paintCanvas` or a `WebGLNode`'s painter are ordinary drawing-code bugs in your own callback, not scenery issues, and are usually easiest to isolate by temporarily swapping the custom Node for a plain `Rectangle` at the same bounds to confirm the surrounding layout/visibility is correct first.

::: tip Bisect with a plain Rectangle
When it's unclear whether a missing/misplaced Node is a visibility, layout, or stacking-order bug, temporarily replace the suspect Node's content with a brightly-colored plain `Rectangle` sized to its expected `bounds`. If the rectangle shows up correctly, the problem is specific to the original Node's own content/geometry; if the rectangle is also missing or misplaced, the problem is upstream — visibility, layout, or an ancestor — and you've eliminated an entire category without reading more code.
:::

## Where to go next

- [Scenery Basics](/guides/scenery-basics) — the Node tree, coordinate frames, and children-order stacking model this page assumes
- [Scenery Layout](/guides/scenery-layout) — the layout containers and options referenced above
- [Performance and Profiling](/guides/performance-and-profiling) — the built-in debug query parameters, applied to slowness rather than incorrectness
- [Display](/api/scenery/display) — the object that actually paints the tree these bugs live in
- [Hit-Testing and Picking](/api/scenery/hit-testing-and-picking) — the full `pickable`/`mouseArea`/`touchArea` model referenced above


========================================================================
Page: Haptics and Alternative Feedback Channels
URL: https://veillette.github.io/Almanach/guides/haptics-and-alternative-feedback-channels
Source: docs/guides/haptics-and-alternative-feedback-channels.md
Category: Guides | Tags: tambo, tappi, sound, vibration, haptics, accessibility | Status: verified
========================================================================

# Haptics and Alternative Feedback Channels

Everything covered in [Scenery Basics](/guides/scenery-basics) is visual — Nodes, painted pixels, a `Display`. Not every user perceives a simulation that way, and even for users who do, a purely visual interaction misses feedback channels that a physical object would naturally provide. SceneryStack has two built-in, non-visual feedback channels: sound, via `tambo`, and vibration, via `tappi`. Both exist for the same underlying reason — giving a user information about what just happened without requiring them to be looking at (or looking closely at) the screen — but they suit different situations and hardware.

## Sound: tambo

`tambo` (`scenerystack/tambo`) is the more broadly applicable of the two — it works on essentially any device with audio output, requires no special hardware, and is useful for both sighted and low-vision/blind users. [Working with Sound](/guides/working-with-sound) covers the subsystem in full: a central `soundManager` that mixes together individually-registered **sound generators** (`SoundClip` for recorded assets, `PitchedPopGenerator` for pitch-continuous synthesized feedback, and others), grouped into categories a user can enable/disable independently.

Two distinct reasons a sim reaches for sound:

- **Confirmation and delight** — a click, a chime on success, an ambient hum while something is running — feedback that enhances the experience for every user, sighted or not, the same way physical toys and instruments make sound as a byproduct of interaction.
- **Accessibility (sonification)** — using the same tambo machinery specifically so a non-visual user (or a sighted user not looking at the screen) can perceive continuous state or discrete events that would otherwise be visual-only. [Sound Design](/accessibility/sound-design) covers this application specifically, including the `sharedSoundPlayers` registry that keeps common interactions (checkbox toggles, button presses, reset) sounding consistent across every sim without each one authoring its own.

## Vibration: tappi

`tappi`'s `vibrationManager` (`scenerystack/tappi`) is the haptic equivalent of `soundManager` — a central point that drives the device's vibration hardware in response to simulation events, using vibration "patterns" (a sequence of on/off durations and intensities) rather than raw single buzzes. See [vibrationManager and Vibration Patterns](/api/tappi/vibration-manager-and-patterns) for the API itself.

Vibration is a narrower tool than sound for a simple hardware reason: it requires a device with a vibration motor the browser can actually drive (most phones/tablets; effectively no desktop browsers), so it's necessarily a *supplementary* channel layered on top of visual and/or sound feedback, never the only way an interaction communicates something. Where it earns its place is touch-first interactions where the device itself is already in the user's hand — confirming a drag has snapped into place, signaling a boundary has been reached, or reinforcing a discrete event (a collision, a successful match) with a physical pulse that doesn't require audio output at all (useful in shared/classroom settings where sound might be muted or inappropriate).

## Choosing a channel

| Channel | Requires | Reaches | Typical use |
| --- | --- | --- | --- |
| Visual (scenery) | Any display | Every user by default | The primary channel; everything else is supplementary |
| Sound (tambo) | Audio output, not muted | Sighted and non-sighted users alike | Confirmation/delight, and sonification for low-vision/blind users |
| Vibration (tappi) | A device with a vibration motor (mobile/touch) | Users on supported touch hardware, sound-independent | Reinforcing a touch interaction physically, especially where audio may be muted or unavailable |

None of these are exclusive — a well-designed touch interaction on mobile might pair a visual snap-into-place animation, a short confirmation sound, and a vibration pulse for the same event, so the feedback reaches the user regardless of which channel they happen to be attending to (or which channels their device/settings support) at that moment.

::: tip Non-visual channels are additive, not a replacement for the PDOM
Sound and vibration are useful accessibility *supplements*, but neither substitutes for the structured, navigable accessibility tree the [PDOM](/accessibility/pdom) provides for screen-reader users, or for [Voicing](/accessibility/voicing)'s spoken descriptions. A collision sound tells a user *something* happened; it doesn't tell them *what* the current state is in a way a screen reader can query on demand. Treat tambo/tappi feedback as reinforcement layered on top of a genuinely accessible PDOM structure, not a shortcut around building one.
:::

## Where to go next

- [Working with Sound](/guides/working-with-sound) — the full tambo subsystem tour
- [Sound Design](/accessibility/sound-design) — sound specifically as an accessibility channel
- [vibrationManager and Vibration Patterns](/api/tappi/vibration-manager-and-patterns) — the tappi API this page summarizes


========================================================================
Page: Internationalization Deep Dive
URL: https://veillette.github.io/Almanach/guides/internationalization-deep-dive
Source: docs/guides/internationalization-deep-dive.md
Category: Guides | Tags: localization, i18n, rtl, strings | Status: verified
========================================================================

# Internationalization Deep Dive

[Translation and Localization](/guides/translation-and-localization) covers the core idea — every displayed string is a `Property<string>`, never a literal — and the pipeline that turns per-locale JSON files into those Properties at build/runtime. This page goes one level deeper into three things that pipeline alone doesn't handle: how the *active* locale is actually determined and switched, what changes about layout once a right-to-left language is involved, and how to build translated strings that need pluralization or multiple placeholders correctly, rather than by string concatenation.

## Runtime locale: where it comes from, and whether it can change

`localeProperty` (from `scenerystack/joist`) is the single source of truth for the sim's active locale — every generated `StringProperty` reflects the string data for whatever locale this Property currently holds:

```ts
import { localeProperty } from 'scenerystack/joist';

console.log( localeProperty.value ); // e.g. 'en', 'fr', 'es', 'zh_CN'
```

It's initialized once at startup from the `?locale=` query parameter (falling back to the browser's own locale, then to `'en'`), which is why [Translation and Localization](/guides/translation-and-localization) describes it as "normally set once at startup" rather than something application code changes mid-session. `localeProperty` is a real, settable `Property<Locale>` — nothing in the type system stops you from writing to it after startup — but production PhET simulations don't do this as a live "language switcher" feature; a full reload with a different `?locale=` value is the supported path for changing languages, since a substantial amount of layout (see below) is easiest to get right when it's computed fresh rather than live-relaid mid-session.

If you do need to read the list of locales a specific build actually has string data for (rather than assuming every locale is available), that's exposed alongside `localeProperty` rather than hardcoded — check the actual runtime value rather than assuming a fixed list, since which locales are available for a given build is a locale-file/build-time concern (see [Project Structure Conventions](/getting-started/project-structure-conventions)), not something this API layer fixes at compile time.

## Right-to-left languages

Some locales (Arabic, Hebrew, and others) lay out text right-to-left rather than left-to-right, and a simulation whose layout was only ever built and tested against English can end up with UI that's technically translated but reads backwards. `isLeftToRightProperty` (also from `scenerystack/joist`) is a derived boolean tracking the current locale's writing direction, recomputed automatically whenever `localeProperty` changes:

```ts
import { isLeftToRightProperty } from 'scenerystack/joist';

isLeftToRightProperty.link( isLTR => {
  // true for locales like 'en', 'fr'; false for RTL locales like 'ar', 'he'
} );
```

`RichText` and the rest of scenery's text-rendering Nodes already handle bidirectional *text* rendering correctly (Arabic/Hebrew characters shape and flow right-to-left within a `Text`/`RichText` Node on their own). What `isLeftToRightProperty` is for is *layout structure* that your own code built assuming left-to-right — a row of icon-then-label pairs, a "Play" button placed at the visual left of a control strip, a `FlowBox` whose `justify` was chosen assuming reading order flows left to right. For content where left/right placement carries meaning (not just text shaping), branch on this Property rather than assuming your layout is direction-agnostic by default:

```ts
import { HBox } from 'scenerystack/scenery';

const controlBox = new HBox( {
  spacing: 8,
  // FlowBox's own layout math doesn't auto-mirror; reverse the children order for RTL locales
  children: isLeftToRightProperty.value ? [ icon, label ] : [ label, icon ]
} );
```

::: warning Test with a real RTL locale, not just a mirrored screenshot
It's tempting to "check RTL support" by visually flipping a screenshot. Actually running with `?locale=ar` (or whichever RTL locale the sim ships strings for) surfaces the cases a mirrored screenshot can't: text truncation from different average string lengths, numerals that stay left-to-right even inside RTL text, and layout containers that were never told to reverse their child order.
:::

## Pluralization and multiple placeholders: PatternStringProperty

[Translation and Localization](/guides/translation-and-localization) shows `StringUtils.fillIn` for one-off placeholder substitution. For a *reactive* translated string — one that needs to update automatically as the values feeding it change, without you re-calling `fillIn` by hand on every change — [`PatternStringProperty`](/api/axon/pattern-string-property) is the idiomatic tool, and it's also where pluralization-style patterns are handled correctly across languages:

```ts
import { PatternStringProperty, NumberProperty } from 'scenerystack/axon';

const countProperty = new NumberProperty( 1 );

// patternProperty is itself a translated StringProperty, e.g. '{{count}} particles remaining'
const remainingMessageProperty = new PatternStringProperty( patternProperty, {
  count: countProperty
} );
```

The reason this matters beyond convenience: word order and pluralization rules vary across languages in ways that a single hardcoded English sentence shape can't represent. A translator working from `'{{count}} particles remaining'` can reorder or restructure the pattern entirely for a language with different pluralization/word-order rules — the *placeholder* is what's fixed, not the surrounding sentence structure — whereas code that concatenates `count + ' particles remaining'` gives translators nothing to restructure. `PatternStringProperty` also supports `decimalPlaces` (rounding numeric values consistently at substitution time) and a `maps` option (transforming a value before substitution, e.g. converting grams to kilograms) — see [`PatternStringProperty`](/api/axon/pattern-string-property) for the full option set.

Because `PatternStringProperty` is a `DerivedProperty` under the hood, treat it the same way: it can't be set directly, it lazily links to every dependency Property you pass in, and any instance you create dynamically (per list item, per dynamically-created model element) needs `dispose()` — see [Dispose and Memory Management](/patterns/dispose-and-memory-management).

## Where to go next

- [Translation and Localization](/guides/translation-and-localization) — the `StringProperty` foundation and the translation pipeline this page assumes
- [`PatternStringProperty`](/api/axon/pattern-string-property) — full constructor/options reference for pattern substitution
- [`StringProperty`](/api/axon/string-property) — the base Property type every translated string, plural or not, is built on


========================================================================
Page: Modifying SceneryStack
URL: https://veillette.github.io/Almanach/guides/modifying-scenerystack
Source: docs/guides/modifying-scenerystack.md
Category: Guides | Tags: contributing, open-source, workflow | Status: verified
========================================================================

# Modifying SceneryStack

The `scenerystack` npm package is a **built artifact**: its `dist/` bundles and `src/` barrel files are compiled from dozens of separate PhET repositories (`scenery`, `axon`, `joist`, `sun`, `scenery-phet`, and more, all under [github.com/phetsims](https://github.com/phetsims)). If you ever need to patch a bug in one of those libraries — not just work around it in your own code — you check out the source repositories and rebuild the package locally, rather than editing files inside `node_modules`.

::: warning Never hand-edit `node_modules/scenerystack`
Any change made directly inside `node_modules` is silently lost the next time anything runs `npm install`. If you need to change SceneryStack's own code, follow the checkout/build workflow below in a separate directory and point your project at the result — don't patch the installed copy in place.
:::

## Checking out the source repositories

In an empty directory (not your project's `node_modules`):

```bash
mkdir scenerystack-src && cd scenerystack-src
npx scenerystack checkout
```

This clones every underlying repository (`scenery`, `axon`, `joist`, `sun`, `scenery-phet`, `dot`, `kite`, `tandem`, `phetcommon`, and the rest) into the current directory. Running it again later pulls newer sources into the same checkout.

To pin a specific released version instead of the latest sources:

```bash
npx scenerystack checkout 0.0.14
```

## Making your change

Edit the relevant file in whichever cloned repository owns it — e.g. a `scenery` drag-interaction bug lives under `scenery/js/listeners/`, a `sun` component bug under `sun/js/`. Since these are real git checkouts of the PhET repositories, normal git workflow applies: branch, commit, and (if you intend to contribute upstream) open a pull request against the corresponding `phetsims/<repo>` repository.

## Rebuilding the package

From the same directory:

```bash
npx scenerystack build
```

This builds the entire stack — including your modified repository — into a local `scenerystack` package output.

## Pointing your project at the local build

In the project that needs the patched behavior, replace the registry dependency with a file reference in `package.json`:

```json
{
  "dependencies": {
    "scenerystack": "file:../scenerystack-src/scenerystack"
  }
}
```

Then reinstall so npm picks up the local copy:

```bash
npm install
```

Your project now imports the patched code through the exact same `scenerystack/<library>` subpaths as before — nothing about your application code changes, only where the package resolves from.

## Where to go next

- [Installation and Setup](/getting-started/installation-and-setup) — the normal (registry) installation path this workflow diverges from
- [What is SceneryStack?](/getting-started/what-is-scenerystack) — the full list of libraries bundled into the package


========================================================================
Page: Performance and Profiling
URL: https://veillette.github.io/Almanach/guides/performance-and-profiling
Source: docs/guides/performance-and-profiling.md
Category: Guides | Tags: scenery, performance, profiling, rendering | Status: verified
========================================================================

# Performance and Profiling

A slow SceneryStack simulation is almost never slow because scenery itself is slow — it's slow because the scene graph is doing more repaint/relayout work than the visible result needs, or because the model's `step`/listener graph is doing more computation per frame than the animation actually requires. This page covers how to *see* where the time goes before guessing, and the handful of causes that account for most real slowdowns: Node count and structure, `Property`/listener overhead, and choosing the wrong renderer for a subtree.

::: warning Profile before you optimize
Every technique below (picking a `renderer`, flattening Node structure, batching `Property` updates) has a real cost in code complexity or flexibility. Applied to a subtree that was never the bottleneck, it's pure overhead with no payoff. Use the query parameters in the next section to find the actual slow part first — guessing which Node or Property is "probably expensive" reliably wastes effort on the wrong thing.
:::

## Finding the bottleneck: built-in profiling query parameters

Every SceneryStack simulation ships with debug instrumentation reachable via query parameters — no extra setup required, since these are wired into the shared `joist`/`chipper` initialization every `Sim` goes through:

| Query parameter | Shows |
| --- | --- |
| `?profiler` | An FPS/ms-per-frame histogram in the corner of the screen, updated every 60 frames — the first thing to check for "is it actually slow, and when" |
| `?showPointerAreas` | Each Node's `mouseArea`/`touchArea`, useful for confirming input regions rather than raw render cost |
| `?showHitAreas` | Actual hit-testing regions being used for pointer input |
| `?showCanvasNodeBounds` | Bounds overlays for `CanvasNode` subtrees specifically |
| `?showFittedBlockBounds` | The boundaries of scenery's internal rendering "blocks" — useful for seeing how much of the tree got batched into one Canvas/SVG/WebGL block versus split into many |
| `?dev` | A bundle of internal developer-facing overlays and checks, useful when narrowing down where in the tree a problem lives |

Start with `?profiler`. If frame time is consistently high rather than spiking occasionally, you're CPU- or GPU-bound on steady-state work (too many Nodes repainting, too much `step`/listener computation per frame). If it's fine most frames but spikes occasionally, that's usually garbage collection pressure from allocating in a hot path (a `step` function or `Property` listener that creates new objects every frame) rather than a rendering problem at all — the profiler's own doc calls this out explicitly, which is why it reports a full histogram rather than just an average.

## Node count and tree shape

Scenery batches adjacent, renderer-compatible Nodes into as few underlying Canvas/SVG/WebGL surfaces as it can (see [Scenery Basics](/guides/scenery-basics#render-layers-canvas-svg-and-webgl)), but every Node still costs *something* — a bounds computation, a transform, participation in hit-testing. A few thousand simple Nodes rarely matters; tens of thousands, or a few thousand Nodes each with complex `Shape`-based geometry, starts to show up in the profiler.

The usual fix is reducing Node count for content that doesn't need to be individually addressable:

- **Static decorative content** that never changes and never needs independent input handling is a candidate for a single `Path`/`Image` rather than many small Nodes assembled at runtime.
- **Large repeated structures** (a grid of many small identical icons, for instance) are a good candidate for `CanvasNode` with hand-written `paintCanvas` logic instead of one scenery `Node` per repeated element — trading scenery's automatic per-Node input/bounds handling for one manual draw routine, in exchange for far fewer objects for scenery to track.
- **Visibility toggling** should use `visible`, not adding/removing children repeatedly — `node.visible = false` keeps the Node in the tree (and its subtree structure intact) while skipping paint and, if `pickable` is also affected, input; repeated `addChild`/`removeChild` churn is more expensive than toggling a flag.

## Property and listener overhead

`Property.set()`/`.value =` notifies every registered listener synchronously, in registration order. That's usually cheap — but two patterns turn it into a real cost:

- **A `DerivedProperty` (or manual listener) that does expensive work on every dependency change**, when the dependency changes far more often than the derived result actually needs to update. If a derived value only matters once per animation frame, deriving it from `stepTimer`/an explicit per-frame recompute rather than from a rapidly-changing input Property (e.g. a raw pointer-position Property firing many times per frame) avoids redundant recomputation between frames nobody observes.
- **Registering listeners you never remove.** A `Property` (or `Emitter`) that accumulates listeners across the sim's lifetime — because a transient object linked to it but never called `unlink`/`dispose` — both leaks memory and means every future `.set()` does more work than it should. See [Dispose and Memory Management](/patterns/dispose-and-memory-management) for the disposal convention that prevents this.

```ts
import { DerivedProperty } from 'scenerystack/axon';

// Expensive: recomputes on every change to either dependency, even many times per frame.
const derivedProperty = new DerivedProperty(
  [ rawPointerPositionProperty, zoomLevelProperty ],
  ( position, zoom ) => expensiveLayoutComputation( position, zoom )
);
```

If `rawPointerPositionProperty` updates on every pointer-move event rather than once per frame, `expensiveLayoutComputation` runs far more often than the screen actually repaints. Debouncing to a per-frame recompute (driven from the model's own `step(dt)`, reading the latest pointer position without re-deriving on every intermediate update) is the usual fix once profiling actually shows this Property's listeners as the hot path.

## Canvas, SVG, and WebGL: matching the renderer to the content

Every `Node` has a `renderer` option (`'svg' | 'canvas' | 'webgl' | 'dom' | null`), normally left `null` so scenery picks automatically (see [Supported Browsers](/getting-started/supported-browsers#graceful-degradation-via-renderer-fallback)). The tradeoffs, for the rare case profiling shows you need to pin one:

| Renderer | Best for | Cost |
| --- | --- | --- |
| SVG (scenery's default for most vector content) | Crisp vector shapes/text at any zoom, resolution-independent | Each distinct element is a real DOM node; very large numbers of separately-styled SVG elements get expensive to keep in sync |
| Canvas | Many similar elements painted together, or custom per-pixel drawing (`CanvasNode`) | Cheaper per-element than SVG at scale, but loses SVG's automatic hit-testing/accessibility hooks — you draw pixels, not addressable elements |
| WebGL | Large numbers of simple shapes needing GPU-accelerated compositing (particle-like effects, many identical sprites) | Highest ceiling for raw throughput, but the least forgiving to author for and not guaranteed available (falls back automatically per [Supported Browsers](/getting-started/supported-browsers)) |

The practical rule: leave `renderer` unset until `?profiler` and Node-count investigation point at a *specific* subtree, then reach for `CanvasNode` (for many similar small elements) or a pinned `renderer: 'canvas'`/`'webgl'` hint (for scenery-managed Nodes that would benefit from being batched onto a different surface than their neighbors) only for that subtree — not the whole sim.

## Where to go next

- [Scenery Basics](/guides/scenery-basics) — the Node tree and render-layer model this page assumes
- [Dispose and Memory Management](/patterns/dispose-and-memory-management) — the disposal convention that prevents listener/Property leaks from becoming a performance problem over a long-running sim
- [Supported Browsers](/getting-started/supported-browsers) — renderer fallback behavior across platforms


========================================================================
Page: PhET-iO and Instrumentation
URL: https://veillette.github.io/Almanach/guides/phet-io-and-instrumentation
Source: docs/guides/phet-io-and-instrumentation.md
Category: Guides | Tags: phet-io, tandem, instrumentation | Status: verified
========================================================================

# PhET-iO and Instrumentation

::: tip When to read the related pages
This page is the **conceptual entry point** — what PhET-iO buys you and how `Tandem` fits in. For runtime dynamic elements and custom `IOType`s, read [PhET-iO Deep Dive](/guides/phet-io-deep-dive). For day-to-day wiring conventions (what to instrument, how to structure tandems), read [PhET-iO Instrumentation Pattern](/patterns/phet-io-instrumentation-pattern).
:::

PhET-iO is the layer that turns a running simulation into something an external program can inspect, record, and control: every instrumented object's state can be serialized, saved, restored, and set remotely — the same mechanism that powers PhET's state-saving, data-collection, and interoperability features. **Instrumentation is opt-in and additive**: an uninstrumented simulation runs identically, just without that external surface.

## Tandem: the instrumentation identifier

Every instrumentable object — `Property`, `Node`, `Screen`, `Emitter`, and the PhET-iO base class `PhetioObject` they build on — takes a `tandem` option. A `Tandem` is a hierarchical path name (mirroring where the object lives conceptually, not necessarily in the scene graph) that becomes that object's stable identifier in the PhET-iO API:

```ts
import { Tandem } from 'scenerystack/tandem';
import { NumberProperty } from 'scenerystack/axon';

const screenTandem = Tandem.ROOT.createTandem( 'myScreen' );
const modelTandem = screenTandem.createTandem( 'model' );

const massProperty = new NumberProperty( 5, {
  tandem: modelTandem.createTandem( 'massProperty' ),
  phetioDocumentation: 'the mass of the object, in kilograms'
} );
```

| Tandem | Meaning |
| --- | --- |
| `Tandem.ROOT` | The root of the tandem tree for the whole simulation |
| `Tandem.REQUIRED` | Placeholder meaning "this tandem must be supplied by the caller" — used in components designed to always be instrumented |
| `Tandem.OPTIONAL` | Placeholder meaning "instrumentation is optional here" |
| `someTandem.createTandem( name )` | Creates a child tandem, extending the hierarchical path |

Every `Screen` requires a `tandem`, even in a simulation that never enables PhET-iO — see [Your First Simulation](/getting-started/your-first-simulation). Uninstrumented (`tandem: Tandem.OPTIONAL`, unsupplied) objects simply don't appear in the PhET-iO API; nothing breaks by omitting instrumentation, but nothing is inspectable/settable externally either.

## What instrumentation buys you

| Capability | How |
| --- | --- |
| Save/restore full simulation state | Every instrumented `Property`'s value is captured and can be reapplied later |
| External control | Another program can set an instrumented `Property`'s value directly, driving the sim the same as a user interaction would |
| A documented, stable API | `phetioDocumentation` and the tandem hierarchy together describe the sim's state surface for tooling and other consumers |
| Data collection / logging | Instrumented `Emitter`s and state changes can be observed externally without modifying simulation code |

## IOType: describing serialization

Plain `Property<number>`/`Property<string>` instances serialize with the built-in `NumberIO`/`StringIO` `IOType`s automatically. Custom classes that extend `PhetioObject` (rather than composing existing instrumented Properties) describe their own serialization with an `IOType`:

```ts
import { IOType, NumberIO } from 'scenerystack/tandem';

type MyThingState = { x: number; y: number };

const MyThingIO = new IOType<MyThing, MyThingState>( 'MyThingIO', {
  valueType: MyThing,
  documentation: 'Serializes the position of a MyThing.',
  toStateObject: myThing => ( { x: myThing.x, y: myThing.y } ),
  applyState: ( myThing, state ) => {
    myThing.x = state.x;
    myThing.y = state.y;
  },
  stateSchema: {
    x: NumberIO,
    y: NumberIO
  }
} );
```

Most simulations never need to author a custom `IOType` directly — composing already-instrumented `Property`s (each with its own built-in `IOType`) inside a plain model class covers the overwhelming majority of cases, consistent with the [model-view separation](/patterns/model-view-separation) pattern where all state lives in `Property` instances.

::: tip Instrument by default, even before you need PhET-iO
Adding `tandem`/`phetioDocumentation` after the fact to a model that already has dozens of Properties is far more tedious than threading tandems through from the start. Most PhET simulations instrument their full model tree from day one, whether or not a given release actually ships PhET-iO features — the incremental cost per `Property` is one option.
:::

## Where to go next

- [Building Your First Screen](/guides/building-your-first-screen) — threading tandems through a new screen's model and view
- [Model-View Separation](/patterns/model-view-separation) — why instrumentable state lives in `Property` instances, not scattered fields
- [Your First Simulation](/getting-started/your-first-simulation) — the minimum tandem wiring every `Screen` requires


========================================================================
Page: PhET-iO Deep Dive
URL: https://veillette.github.io/Almanach/guides/phet-io-deep-dive
Source: docs/guides/phet-io-deep-dive.md
Category: Guides | Tags: phet-io, tandem, instrumentation, phetio-group, phetio-capsule | Status: verified
========================================================================

# PhET-iO Deep Dive

[PhET-iO and Instrumentation](/guides/phet-io-and-instrumentation) covers the basics: every instrumentable object takes a `Tandem`, and instrumentation is opt-in and additive. That page's model is *static* — a fixed set of `Property`s and `Node`s, each with a tandem assigned once at construction. This page covers what happens once your model creates and destroys elements at runtime (particles, graph points, anything with a variable count), how to describe serialization for a class that isn't just composed `Property`s, and what "state save/restore" is actually doing under the hood.

## The problem with dynamic elements

A `Tandem` is a fixed, hierarchical path assigned once. That works fine for a model with a fixed shape — one `massProperty`, one `positionProperty` — but breaks down the moment the model creates elements at runtime: if a user can add particles to a simulation, each particle needs *some* tandem, but you don't know at construction time how many there will be or what to name them. `PhetioGroup` and `PhetioCapsule` (both from `scenerystack/tandem`) solve this by taking over both creation *and* tandem-naming for exactly this case.

## PhetioGroup: a homogeneous, growable collection

`PhetioGroup` manages a runtime-created array of `PhetioObject`s, generating each one's tandem automatically:

```ts
import { PhetioGroup, Tandem } from 'scenerystack/tandem';
import { NumberProperty } from 'scenerystack/axon';

class Particle extends PhetioObject {
  public readonly massProperty: NumberProperty;

  public constructor( tandem: Tandem, initialMass: number ) {
    super( { tandem, phetioType: Particle.ParticleIO } );
    this.massProperty = new NumberProperty( initialMass, {
      tandem: tandem.createTandem( 'massProperty' )
    } );
  }

  public static ParticleIO = /* an IOType, see below */ null!;
}

const particleGroup = new PhetioGroup(
  ( tandem: Tandem, initialMass: number ) => new Particle( tandem, initialMass ),
  [ 1 ], // default arguments, used to build the group's "archetype" — see below
  {
    tandem: someParentTandem.createTandem( 'particleGroup' )
  }
);

const newParticle = particleGroup.createNextElement( 2.5 );
```

A few things are worth understanding, not just copying:

- **`createElement` never wires up listeners itself** — the constructor function's only job is building the element and giving it its tandem. If code elsewhere needs to react whenever a new element is created (adding a view Node for each new particle, for instance), listen to the group's own creation notifications rather than adding side effects inside `createElement` — mixing "create the object" and "wire up its effects" into one function is a documented anti-pattern for `PhetioGroup`, because the PhET-iO state engine re-invokes `createElement` when *restoring* saved state, and any side effect baked into it fires again on every restore, not just on genuine user-driven creation.
- **The tandem name must end in the container's suffix** (`'Group'` by default) — `particleGroup`'s own tandem name ends in `Group`, and each created element's base tandem name is that group name with the suffix stripped, followed by an index (`particle_0`, `particle_1`, ...). This is why the naming isn't arbitrary: it's what lets the PhET-iO API tooling recognize "this whole namespace is one dynamic group" rather than treating each element as an unrelated fixed object.
- **`defaultArguments` build the group's archetype** — an extra, always-present instance created from those defaults purely so the PhET-iO API has a static example of what elements in this group look like (their nested Properties, their `IOType`), even though the group might have zero real elements at a given moment. You don't interact with the archetype directly; it exists for API generation and validation.
- **`countProperty`** is a built-in, read-only `NumberProperty` tracking how many elements currently exist — useful for a view layer (or a PhET-iO client) to observe the group's size without walking the array itself.

## PhetioCapsule: a single, replaceable dynamic element

`PhetioCapsule` is `PhetioGroup`'s sibling for the "exactly zero or one" case rather than "many": a dialog that's created lazily on first open, or a single dynamically-swapped model element, rather than an array of many. Its shape mirrors `PhetioGroup` closely — same `createElement`/`defaultArguments`/`options` constructor — but instead of `createNextElement` appending to an array, `create(...)` (re-)creates the single managed instance:

```ts
import { PhetioCapsule } from 'scenerystack/tandem';

const dialogCapsule = new PhetioCapsule(
  ( tandem: Tandem ) => new MyDialog( { tandem } ),
  [],
  { tandem: someParentTandem.createTandem( 'dialogCapsule' ) }
);

const dialog = dialogCapsule.create( [] );
```

Reach for `PhetioCapsule` when "at most one instance exists, created on demand" is the actual shape of the problem (a modal dialog, a singleton sub-panel) and `PhetioGroup` when the real shape is "an arbitrary, growing/shrinking collection" (particles, graph series, anything list-like).

## Authoring a custom IOType

[PhET-iO and Instrumentation](/guides/phet-io-and-instrumentation#iotype-describing-serialization) shows the shape of an `IOType`: `toStateObject`/`applyState` plus a `stateSchema`. The one thing worth adding here is **when to reach for `ReferenceIO`** instead of writing full state serialization yourself. If your class's meaningful state already lives entirely in child `PhetioObject`s (nested `Property`s, for instance), those children already know how to serialize themselves — your `IOType`'s job is just to describe *which* children matter, via `stateSchema`, rather than manually re-implementing their serialization:

```ts
import { IOType, NumberIO, ReferenceIO } from 'scenerystack/tandem';

const ParticleIO = new IOType<Particle, unknown>( 'ParticleIO', {
  valueType: Particle,
  stateSchema: {
    massProperty: NumberIO // delegates entirely to NumberProperty's own IOType
  }
} );
```

`ReferenceIO` (also from `scenerystack/tandem`) is for the opposite situation: a field that points *at* another already-instrumented `PhetioObject` elsewhere in the tree, rather than owning its own copy of that state. Serializing that field as a reference (its `phetioID`) rather than embedding the referenced object's full state avoids duplicating state that's already captured once, at the referenced object's own tandem path.

## How state save/restore actually works

Every instrumented object's `IOType` (built-in or custom) contributes one entry to the sim's overall state object when a save is triggered — essentially a big `phetioID -> stateObject` map, built by calling `toStateObject` on every instrumented `PhetioObject` in the tree. Restoring reverses this: for each entry, the corresponding object's `applyState` is called with the saved value.

The part that trips people up is dynamic elements: restoring state for a `PhetioGroup`/`PhetioCapsule` doesn't just call `applyState` on existing elements — the group first has to *re-create* the right number of elements (by re-invoking `createElement`, the same function used for ordinary runtime creation) before `applyState` has anything to apply state to. This is precisely why `createElement` must be a pure "build the object" function: it runs during ordinary interactive use *and* during every state restore, and `isSettingPhetioStateProperty` (readable, though not normally something application code needs to check directly) is `true` for the duration of a restore specifically so framework code — like the assertion inside `PhetioGroup` guarding its `countProperty` — can distinguish "state is being restored" from "the user is doing this interactively" when the distinction matters.

::: tip Most simulations never author a custom IOType or a PhetioGroup
As [PhET-iO and Instrumentation](/guides/phet-io-and-instrumentation) notes, composing already-instrumented `Property`s inside plain model classes covers most simulations without a custom `IOType` at all. `PhetioGroup`/`PhetioCapsule` specifically are for the subset of sims whose model genuinely creates/destroys elements at runtime — reach for them because the model shape requires it, not as a default pattern to apply everywhere.
:::

## Where to go next

- [PhET-iO and Instrumentation](/guides/phet-io-and-instrumentation) — `Tandem` fundamentals and the basic `IOType` shape this page builds on
- [PhET-iO Instrumentation Pattern](/patterns/phet-io-instrumentation-pattern) — deciding what to instrument in the first place
- [`Tandem`](/api/tandem/tandem) — the naming primitive both `PhetioGroup` and `PhetioCapsule` build on


========================================================================
Page: Preferences and Feature Flags
URL: https://veillette.github.io/Almanach/guides/preferences-and-feature-flags
Source: docs/guides/preferences-and-feature-flags.md
Category: Guides | Tags: preferences, query-parameters, joist | Status: verified
========================================================================

# Preferences and Feature Flags

SceneryStack simulations expose two different mechanisms for configuring behavior that aren't part of the core interaction: the **Preferences dialog**, a user-facing settings panel built into every `Sim`, and **query parameters**, developer/deployment-facing flags read once at startup. Both exist so features like localization, sound, and accessibility options don't need bespoke UI in every simulation.

## The Preferences dialog

Every `Sim` gets a Preferences button in its navigation bar automatically; what appears inside it is configured by a `PreferencesModel` passed to `Sim`:

```ts
import { Sim, onReadyToLaunch, PreferencesModel } from 'scenerystack/sim';
import { Property } from 'scenerystack/axon';

const preferencesModel = new PreferencesModel( {
  visualOptions: {
    supportsProjectorMode: true // adds a high-contrast "projector mode" toggle
  },
  audioOptions: {
    supportsSound: true,
    supportsExtraSound: true
  }
} );

onReadyToLaunch( () => {
  const sim = new Sim( new Property( 'My Simulation' ), [ /* screens */ ], {
    preferencesModel
  } );
  sim.start();
} );
```

| `PreferencesModel` section | Surfaces |
| --- | --- |
| `simulationOptions` | Sim-specific custom preferences you supply yourself |
| `visualOptions` | Projector/high-contrast mode, interactive highlights |
| `audioOptions` | Sound on/off, extra sound, voicing (speech output) |
| `inputOptions` | Alternative input customization (e.g. gesture control settings) |
| `localizationOptions` | Locale switching, region-and-culture selection |

If none of these `Options` are supplied, the corresponding Preferences tab simply doesn't appear — the dialog only shows tabs relevant to what the simulation actually supports, so passing an empty `new PreferencesModel()` (the `Sim` default) yields a minimal dialog.

## Query parameters

Query parameters are read once, at launch, from the page URL — they're the mechanism for developer tooling and deployment configuration, not for anything a shipped simulation should let end users toggle from within the running page. Two you'll use constantly during development:

| Query parameter | Effect |
| --- | --- |
| `?ea` | Enables assertions (`assert && assert(...)` checks throughout SceneryStack) — see [Running and Building a Simulation](/getting-started/running-and-building-a-simulation) |
| `?locale=fr` | Launches directly in a given locale, bypassing the Preferences dialog's language picker |
| `?screens=1,2` | Restricts which screens are available, by 1-based index — useful for testing one screen in isolation |

Simulation-specific flags follow the same pattern using `QueryStringMachine` (from `scenerystack/query-string-machine`), the schema-validated query parameter parser SceneryStack itself uses internally:

```ts
import { QueryStringMachine } from 'scenerystack/query-string-machine';

const myQueryParameters = QueryStringMachine.getAll( {
  // ?showAnswers=true
  showAnswers: {
    type: 'flag'
  },

  // ?initialSpeed=2.5
  initialSpeed: {
    type: 'number',
    defaultValue: 1
  }
} );

if ( myQueryParameters.showAnswers ) {
  // reveal debug-only content
}
```

`QueryStringMachine.getAll` validates every parameter against its declared `type`/`defaultValue` at startup, so a malformed URL fails fast with a clear error rather than silently misconfiguring the sim.

::: warning Query parameters are a developer/QA surface, not an end-user settings UI
It's tempting to add a query parameter as a quick way to make a feature "configurable" and stop there. If end users are meant to change the setting, it belongs in the **Preferences dialog** (or in-sim UI) instead — query parameters aren't discoverable, aren't documented in-product, and are easy to lose (e.g. on a bookmarked or shared URL that omits them). Reserve query parameters for developer flags, QA/testing switches, and deployment-time configuration.
:::

## Where to go next

- [Translation and Localization](/guides/translation-and-localization) — how `?locale=` interacts with the string pipeline
- [Running and Building a Simulation](/getting-started/running-and-building-a-simulation) — where query parameters get appended during development
- [Your First Simulation](/getting-started/your-first-simulation) — the minimal `Sim` this guide's `preferencesModel` option extends


========================================================================
Page: Publishing and Distributing a Simulation
URL: https://veillette.github.io/Almanach/guides/publishing-and-distributing-a-simulation
Source: docs/guides/publishing-and-distributing-a-simulation.md
Category: Guides | Tags: deployment, build, hosting, distribution | Status: complete
========================================================================

# Publishing and Distributing a Simulation

Once a simulation is built, "publishing" it is entirely a static-hosting problem — there is no SceneryStack-specific server, database, or runtime to stand up. This page covers what a production build actually is, and the tradeoffs between the handful of common places to put it.

## What you're distributing

As covered in [Running and Building a Simulation](/getting-started/running-and-building-a-simulation), `npm run build` runs the project's bundler in production mode and produces a self-contained folder of static HTML, JS, CSS, and media (`dist/` for Vite/Esbuild, `build/` for some Webpack configs). Every `scenerystack/*` import, image, and sound file the bundler could resolve is already inlined or copied alongside the built JS, and runtime assertions are stripped. That folder is the entire artifact — there is nothing else to package, containerize, or configure server-side before a browser can load it.

This has one direct consequence for distribution: **anything that can serve static files can host a SceneryStack simulation.** The choice of where to host isn't a technical constraint on the sim itself, it's a question of audience, update frequency, and who's already paying for what infrastructure.

## Where a built sim can live

| Option | Good fit when | Tradeoff |
| --- | --- | --- |
| [GitHub Pages](/getting-started/deploying-to-github-pages) | The project is already on GitHub, wants free hosting, and doesn't need a custom domain or server-side logic | Static only, and (for project sites) served from a `/repo-name/` subpath — the build's base path must match, see the linked page |
| A generic static host (Netlify, Vercel, Cloudflare Pages, an S3 bucket + CDN, etc.) | You want a custom domain, preview deployments per branch/PR, or hosting independent of a specific git forge | Slightly more setup than GitHub Pages, but usually still just "point it at the build output folder" |
| Your own web server (nginx, Apache, or any static file server) | The sim needs to live alongside other institutional content, behind an existing domain/auth layer, or fully under your own infrastructure control | You own the uptime, TLS certificates, and cache headers yourself instead of a managed provider handling them |
| Opening `dist/index.html` directly from disk, or a local static server (`npx serve dist`) | Local testing, or distributing to a single person/classroom without any hosting at all | No shareable URL; some browsers restrict `file://`-loaded assets (module imports, in particular) more than an actual HTTP server would |

None of these change what gets built — the same `dist/` folder from `npm run build` is what you'd push to a `gh-pages` branch, upload to Netlify, or `scp` onto your own server. The only per-target adjustment is usually the bundler's base-path/`publicPath` setting (see the GitHub Pages page for the concrete example), which needs to match wherever the files will actually be served from.

## Versioning what you distribute

A sim distributed publicly will eventually need more than one version live at once — a "current" version and an archived prior release someone has bookmarked or cited. Since a build is just a static folder, the simplest version scheme is directory-based: publish each release to its own path (`/my-sim/1.2.0/`, `/my-sim/1.1.0/`) rather than overwriting the same location on every release, and point a `/my-sim/latest/` alias (a redirect, or a copy of the newest build) at whichever one is current. This costs nothing extra at build time — it's purely a decision about *where* each build's output is uploaded — and it means an old link never silently starts serving different content than what was originally shared.

::: tip Verify the deployed build before announcing it, not after
Every distribution target strips runtime assertions the same way (see [Running and Building a Simulation](/getting-started/running-and-building-a-simulation)) and serves case-sensitive file paths even if your local development machine doesn't enforce that. Serve the built output locally (`npx serve dist` or your bundler's `preview` command) and click through the sim once before publishing, rather than discovering a production-only bug for the first time in front of the sim's actual audience — see the verification checklist in [Deploying a Simulation to GitHub Pages](/getting-started/deploying-to-github-pages) for the specific failure modes to check.
:::

## Where to go next

- [Running and Building a Simulation](/getting-started/running-and-building-a-simulation) — how the artifact this page distributes gets built
- [Deploying a Simulation to GitHub Pages](/getting-started/deploying-to-github-pages) — the concrete, step-by-step path for one specific (free, common) hosting target
- [Supported Browsers](/getting-started/supported-browsers) — the platform matrix to verify a distributed build against


========================================================================
Page: Scenery Basics
URL: https://veillette.github.io/Almanach/guides/scenery-basics
Source: docs/guides/scenery-basics.md
Category: Guides | Tags: scenery, scene-graph, rendering | Status: verified
========================================================================

# Scenery Basics

`scenery` is a retained-mode scene graph: instead of issuing draw calls yourself, you build a tree of `Node` instances describing *what* to show, and a `Display` figures out how to paint it (via Canvas, SVG, or WebGL) and keeps the painting in sync as the tree changes. Every visual element in a SceneryStack application — shapes, text, images, and every UI component from `sun`/`scenery-phet` — is a `Node`.

## The Node tree

```ts
import { Node, Rectangle, Circle, Text } from 'scenerystack/scenery';

const root = new Node();

const background = new Rectangle( 0, 0, 400, 300, { fill: '#eef' } );
const ball = new Circle( 20, { fill: 'crimson', center: background.center } );
const label = new Text( 'Scene graph demo', { font: '18px sans-serif', top: 10, left: 10 } );

root.children = [ background, ball, label ];
```

A `Node` with no visual content of its own (like `root` above) is a plain container — its only job is grouping children so you can move, hide, or style them together. `children` is drawn in array order: **later entries paint on top of earlier ones**, exactly like DOM stacking order or z-index by declaration order.

| Way to change children | Effect |
| --- | --- |
| `node.children = [ a, b, c ]` | Replaces the entire children array |
| `node.addChild( child )` | Appends one Node to the end (drawn on top) |
| `node.insertChild( index, child )` | Inserts at a specific stacking position |
| `node.removeChild( child )` | Removes one Node |

A `Node` can have multiple parents (it's a DAG, not strictly a tree) — the same `Node` instance can appear in two different places in the graph and both stay in sync, though this is an advanced technique most simulations don't need.

## Render layers: Canvas, SVG, and WebGL

Scenery doesn't require you to pick a rendering technology per element. Each `Node` has a `renderer` option (`'svg' | 'canvas' | 'webgl' | 'dom' | null`) that's normally left `null`, letting scenery choose — and internally batch adjacent compatible Nodes into as few underlying Canvas/SVG/WebGL "layers" as it can, to minimize the number of separate surfaces the browser has to composite. You rarely think about layers directly; the practical knobs you do use are `visible`, `opacity`, and `pickable`:

```ts
ball.visible = false;   // removed from painting and from input, but stays in the tree
ball.opacity = 0.5;     // still painted, semi-transparent
ball.pickable = false;  // still painted, but input events pass through it
```

See [Supported Browsers](/getting-started/supported-browsers) for how renderer fallback behaves across platforms.

## Coordinate frames

Every `Node` has its own **local coordinate frame** — the one its constructor arguments and internal geometry are expressed in — and a transform (translation, rotation, scale) that places it within its **parent's** coordinate frame:

```ts
ball.translation = ball.translation.plusXY( 50, 0 ); // move 50 units right, in the parent's frame
ball.rotation = Math.PI / 4;                          // rotate 45 degrees about its own origin
ball.scale( 1.5 );                                    // scale about its own origin
```

| Property | Meaning |
| --- | --- |
| `x` / `y` / `translation` | Position of this Node's origin in its parent's coordinate frame |
| `rotation` | Rotation in radians about the local origin |
| `localBounds` | Bounding box of this Node's own content, in its own local frame |
| `bounds` | Bounding box of this Node *and all its children*, in the parent's frame |

Converting a point between frames uses the Node's transform chain directly:

```ts
const parentPoint = ball.localToParentPoint( someLocalPoint );
const globalPoint = ball.localToGlobalPoint( someLocalPoint ); // all the way to the Display's root frame
```

::: tip `bounds` is not the same as `localBounds`
`localBounds` is one Node's own content, unaffected by its children. `bounds` includes every descendant, already transformed into the parent's frame — it's what determines layout and hit-testing for anything that treats this Node as a single unit (see [Scenery Layout](/guides/scenery-layout)).
:::

## Where to go next

- [Scenery Layout](/guides/scenery-layout) — arranging children automatically instead of setting `x`/`y` by hand
- [Scenery Input](/guides/scenery-input) — pointers, listeners, and how events traverse this same tree
- [Scenery Application vs. Standalone Library](/getting-started/scenery-application-vs-standalone-library) — putting a Node tree in a page via `Display`


========================================================================
Page: Scenery Input
URL: https://veillette.github.io/Almanach/guides/scenery-input
Source: docs/guides/scenery-input.md
Category: Guides | Tags: scenery, input, pointers, listeners | Status: verified
========================================================================

# Scenery Input

Scenery unifies mouse, touch, and pen input behind one event model: every physical input source becomes a `Pointer` (a `Mouse`, `Touch`, or `Pen` instance), every DOM event becomes a `SceneryEvent` carrying the `Trail` of Nodes it hit, and any `Node` can attach listeners that react to it — no direct DOM event handling required.

## Attaching a listener

```ts
import { Node, Circle } from 'scenerystack/scenery';

const ball = new Circle( 20, { fill: 'crimson', cursor: 'pointer' } );

ball.addInputListener( {
  down: event => console.log( 'pressed', event.pointer.point ),
  up: event => console.log( 'released' ),
  over: event => { ball.fill = 'orange'; },
  out: event => { ball.fill = 'crimson'; }
} );
```

An input listener is a plain object (or class instance) whose keys are event names. Scenery calls the matching key when that event reaches a Node the listener is attached to.

| Event | Fires on |
| --- | --- |
| `down` / `up` / `cancel` | Pointer press, release, or interrupted press (any pointer type) |
| `move` | Pointer moved while over this Node |
| `enter` / `exit` | Pointer entered/left this Node's subtree (fires once per subtree, unlike `over`/`out`) |
| `over` / `out` | Pointer entered/left this specific Node |
| `click` | A full press-and-release on the same target |
| `focus` / `blur` | Keyboard/PDOM focus gained or lost |
| `keydown` / `keyup` | Key events while this Node has focus |

Type-specific variants (`mousedown`, `touchdown`, `pendown`, ...) exist for every generic event when you need to branch on pointer type without inspecting `event.pointer.type` yourself.

## SceneryEvent and the hit trail

The object passed to a listener is a `SceneryEvent`, carrying everything about *this* dispatch:

```ts
ball.addInputListener( {
  down: event => {
    event.pointer;        // the Pointer (Mouse | Touch | Pen) that triggered this
    event.trail;           // Trail: ordered list of Nodes from the Display's root to the leaf hit
    event.target;          // the leaf-most (deepest) Node in the trail
    event.currentTarget;   // the Node this particular listener is attached to
    event.domEvent;        // the underlying raw MouseEvent/TouchEvent/PointerEvent, or null
  }
} );
```

Events bubble: a listener on a parent `Node` still receives events that were hit-tested against one of its descendants, with `currentTarget` reflecting which ancestor the listener is actually attached to and `target`/`trail` reflecting where the pointer actually hit. Call `event.handled = true` inside a listener to stop the event bubbling to ancestors, or `event.abort()` to stop it from reaching any further listeners at all.

## Pointer areas and pickability

Two Node options control *whether* and *where* a Node can be hit at all:

```ts
import { Shape } from 'scenerystack/kite';

ball.touchArea = ball.localBounds.dilated( 10 ); // easier to tap on touchscreens than the visual bounds
ball.mouseArea = ball.localBounds;               // mouse hit area, independently of touch
ball.pickable = false;                            // excluded from hit-testing (still painted, if visible)
ball.inputEnabled = false;                        // subtree stops responding to input, without changing pickable
```

`touchArea`/`mouseArea` accept a `kite` `Shape` or a `Bounds2` and are commonly dilated beyond the visual bounds, since touch targets smaller than ~44px are hard to hit reliably.

## Structured listeners: PressListener, FireListener, DragListener

Handling `down`/`up`/`cancel` manually gets repetitive and easy to get subtly wrong (interrupted presses, multitouch). The `scenery` listener classes wrap the raw events into higher-level behavior:

```ts
import { FireListener, PressListener, DragListener } from 'scenerystack/scenery';

button.addInputListener( new FireListener( {
  fire: () => console.log( 'fired!' ) // press-and-release, handles interruption for you
} ) );

someNode.addInputListener( new PressListener( {
  press: event => { /* pressed down */ },
  release: event => { /* released, still over the node */ }
} ) );
```

`DragListener` (and its keyboard-accessible counterpart `KeyboardDragListener`) is the most common of these — see [Drag Listeners](/patterns/drag-listeners) for the full pattern of wiring a listener to a model `positionProperty` through a `ModelViewTransform2`.

::: tip Pointer input alone is never accessible
Every listener shown above only responds to mouse/touch/pen. Keyboard users and screen reader users interact through the [Parallel DOM](/accessibility/pdom) instead — a fully accessible custom interaction needs a `tagName`, `focusable: true`, and a keyboard-driven listener (`KeyboardListener` or `KeyboardDragListener`) in addition to any pointer listener. See the [Accessible Interaction Tutorial](/guides/accessible-interaction-tutorial) for a worked example.
:::

## Where to go next

- [Drag Listeners](/patterns/drag-listeners) — the standard pattern for draggable model-bound Nodes
- [The Parallel DOM (PDOM)](/accessibility/pdom) — the accessible half of input handling
- [Accessible Interaction Tutorial](/guides/accessible-interaction-tutorial) — pointer and keyboard input on the same custom Node


========================================================================
Page: Scenery Layout
URL: https://veillette.github.io/Almanach/guides/scenery-layout
Source: docs/guides/scenery-layout.md
Category: Guides | Tags: scenery, layout, flow-box, grid-box | Status: verified
========================================================================

# Scenery Layout

Setting every child's `x`/`y` by hand works for a handful of Nodes but falls apart once content changes size dynamically (translated strings, resizable panels). Scenery's layout containers — `FlowBox`, `GridBox`, and `AlignBox` — solve this the way CSS flexbox/grid do: you describe *relationships* between children, and the container keeps positions correct as content changes.

## FlowBox: one-dimensional flow (like flexbox)

`FlowBox` lays children out in a single row or column, in `children` array order:

```ts
import { FlowBox, Rectangle, Text } from 'scenerystack/scenery';

const row = new FlowBox( {
  orientation: 'horizontal',
  spacing: 8,
  align: 'center',
  children: [
    new Rectangle( 0, 0, 20, 20, { fill: 'red' } ),
    new Text( 'Label', { font: '16px sans-serif' } ),
    new Rectangle( 0, 0, 20, 20, { fill: 'blue' } )
  ]
} );
```

| Option | Effect |
| --- | --- |
| `orientation` | `'horizontal'` or `'vertical'` — which axis children flow along |
| `spacing` | Gap between adjacent children |
| `align` | Cross-axis alignment: `'start'` / `'center'` / `'end'` / `'stretch'`, etc. |
| `justify` | Main-axis distribution: `'left'`/`'top'`, `'center'`, `'right'`/`'bottom'`, `'spaceBetween'`, `'spaceAround'`, `'spaceEvenly'` |
| `wrap` | Whether children wrap to a new line when they overflow the preferred size |
| `stretch` | Whether children stretch to fill the cross-axis by default |

`HBox` and `VBox` are `FlowBox` with `orientation` fixed to `'horizontal'`/`'vertical'` — reach for them when you never need to change orientation dynamically:

```ts
import { VBox } from 'scenerystack/scenery';

const column = new VBox( { spacing: 4, children: [ /* ... */ ] } );
```

A child can override its own contribution via `layoutOptions`, without the `FlowBox` needing to know about it:

```ts
someChild.layoutOptions = { grow: 1 }; // this child expands to absorb extra space
```

## GridBox: two-dimensional layout

`GridBox` positions children in a grid, either by nested `rows`/`columns` arrays or by giving each child explicit `layoutOptions`:

```ts
import { GridBox, Text } from 'scenerystack/scenery';

const grid = new GridBox( {
  xSpacing: 10,
  ySpacing: 6,
  rows: [
    [ new Text( 'Name' ), new Text( 'Value' ) ],
    [ new Text( 'Mass' ), new Text( '5 kg' ) ]
  ]
} );
```

| Option | Effect |
| --- | --- |
| `rows` | `Node[][]`, outer array is rows, inner array is that row's columns |
| `columns` | `Node[][]`, outer array is columns instead — use one or the other, not both |
| `xSpacing` / `ySpacing` | Gaps between columns / rows |
| `autoRows` / `autoColumns` | Auto-place a flat `children` array into a grid with a fixed number of rows/columns, instead of positioning explicitly |

## AlignBox: aligning within reserved space

`AlignBox` wraps a single child and gives it a fixed alignment inside a bounding box — commonly used to keep same-size content aligned across several sibling panels:

```ts
import { AlignBox, AlignGroup, Text } from 'scenerystack/scenery';

const group = new AlignGroup(); // shares one common size across boxes

const leftLabel = new AlignBox( new Text( 'Short' ), { group, xAlign: 'left' } );
const rightLabel = new AlignBox( new Text( 'A much longer label' ), { group, xAlign: 'left' } );
// Both AlignBoxes now report the same (largest) size to whatever lays them out.
```

| Option | Effect |
| --- | --- |
| `xAlign` / `yAlign` | `'left'\|'center'\|'right'\|'stretch'` and `'top'\|'center'\|'bottom'\|'stretch'` |
| `xMargin` / `yMargin` | Padding around the content inside the alignment box |
| `group` | An `AlignGroup` shared by multiple `AlignBox`es so they all report a common (max) size |

## Margins, shared across containers

`FlowBox` and `GridBox` cells both support per-child margin options — `xMargin`, `yMargin`, `leftMargin`, `rightMargin`, `topMargin`, `bottomMargin`, `minContentWidth`/`minContentHeight` — set either on the container (as a default) or per-child via `layoutOptions`.

::: tip Layout containers manage their children's transform — don't fight them
Once a `Node` is a child of a `FlowBox`/`GridBox`, that container sets its `x`/`y` every layout pass. Setting `translation` on the child directly afterwards is overwritten on the next layout update; adjust `spacing`, `align`, `layoutOptions`, or wrap the child in its own `Node` if you need an offset the container doesn't already model.
:::

## Where to go next

- [Building Your First Screen](/guides/building-your-first-screen) — laying out a `ScreenView`'s content with these containers
- [Scenery Basics](/guides/scenery-basics) — the Node tree and coordinate frames layout containers operate on
- [UI Components Overview](/guides/ui-components-overview) — `sun` components that are commonly composed inside `FlowBox`/`GridBox`


========================================================================
Page: Sim Lifecycle and Startup Sequence
URL: https://veillette.github.io/Almanach/guides/sim-lifecycle-and-startup-sequence
Source: docs/guides/sim-lifecycle-and-startup-sequence.md
Category: Guides | Tags: joist, Sim, Screen, lifecycle, animation-loop | Status: complete
========================================================================

# Sim Lifecycle and Startup Sequence

Every SceneryStack simulation goes through the same handful of phases between the page loading and the animation loop running steadily at 60fps. Knowing the real order — not just "it starts" — matters for questions like "why isn't my model constructed yet" or "why did this listener fire before the thing it depends on existed."

## Phase 1: asset loading, via `onReadyToLaunch`

A simulation never constructs its `Sim` directly at module scope — it wraps construction in `onReadyToLaunch` (from `scenerystack/sim`), which waits for SceneryStack's asynchronous asset loader (fonts, images, translated string files) to finish before the callback runs:

```ts
import { Sim, Screen, onReadyToLaunch } from 'scenerystack/sim';

onReadyToLaunch( () => {
  const sim = new Sim( /* ... */ );
  sim.start();
} );
```

Nothing in the scene graph is safe to build before this callback fires — a `Text` Node created too early could measure its bounds against a font that hasn't finished loading, and a string Property could briefly hold an untranslated fallback. This is why every [`Screen`](/api/joist/screen)'s model/view factories are deferred functions rather than eagerly-run code: they're only invoked once `Sim` decides a screen is actually needed, which is always after this phase has completed.

## Phase 2: `new Sim(...)` construction

Constructing `Sim` itself does relatively little work: it records the list of `Screen`s, builds a `HomeScreen` and navigation bar if there's more than one, and sets up its own top-level Properties (`selectedScreenProperty`, `activeProperty`, `dimensionProperty`) — see [`Sim`](/api/joist/sim) for the full option/member list. Crucially, **no individual screen's `createModel`/`createView` factory has run yet** at this point; `Screen` only holds those factories, it doesn't call them.

## Phase 3: `sim.start()` — screen initialization

Calling `start()` is what actually triggers construction. `Sim` initializes screens (by default, every screen eagerly rather than only the one first shown — see [`detachInactiveScreenViews`](/api/joist/sim) for the option that keeps inactive screens' views out of the scene graph once built), calling each `Screen`'s `createModel()` and then `createView( model )` in turn. `Sim.isConstructionCompleteProperty` becomes `true` once this has finished for every screen — code that needs to know "has everything actually been built yet" (some PhET-iO tooling, in particular) waits on that Property rather than assuming construction is synchronous with `start()` returning.

Once construction finishes, `start()` begins the `requestAnimationFrame` loop described below. `selectedScreenProperty` is set (to the `HomeScreen` for a fresh multi-screen sim, or the single screen for a one-screen sim, unless a query parameter like `?screens=2` requests a specific starting screen) as part of this same phase.

## Phase 4: the running animation loop

Once started, a `Sim` drives one `requestAnimationFrame`-based loop for the lifetime of the page. Each frame:

1. The browser calls the loop's callback with an elapsed time; `Sim` computes `dt` (elapsed seconds, capped per-screen by that `Screen`'s `maxDT` option to avoid a huge jump after e.g. a backgrounded tab resumes).
2. `Sim` steps the currently-selected screen's model (if it has a `step( dt )` method) and then its [`ScreenView`](/api/joist/screen-view)'s own `step( dt )` — only the active screen steps; a screen the user isn't looking at does no per-frame work.
3. `stepTimer` (from `scenerystack/axon`) emits `dt`, firing anything scheduled via `stepTimer.setTimeout`/`setInterval` whose accumulated time has elapsed — see [Timer, animationFrameTimer, and stepTimer](/api/axon/timer) for how this differs from `animationFrameTimer`, which fires every frame independent of which screen (or whether any screen) is active.
4. The [`Display`](/api/scenery/display) underlying the sim repaints, syncing any Node whose visual state changed as a result of the above back to actual pixels — this is the same `updateDisplay()`/`updateOnRequestAnimationFrame()` mechanism described in [Scenery Basics](/guides/scenery-basics), just already wired up for you by `Sim` rather than something you drive yourself.

Model and view `step` functions are the only place per-frame model mutation should happen — a `Property` set directly from an input listener (a drag, a slider) is fine and expected, but time-based motion (an object coasting, an animation easing toward a target) belongs in `step(dt)`, driven by the loop above, not in a `setInterval` or a listener that assumes a fixed frame rate.

::: tip `activeProperty` pauses the loop's effects, not the loop itself
Setting `sim.activeProperty = false` doesn't stop `requestAnimationFrame` from firing — `Sim` keeps receiving frames, but skips stepping the model/view while inactive, which is what "pausing" a sim actually means at this layer. This is distinct from `browserTabVisibleProperty`, which reflects whether the browser tab itself is visible and is one of the inputs `Sim` uses to decide whether to set `activeProperty` automatically.
:::

## Where to go next

- [Sim](/api/joist/sim) — the full constructor/option/member reference for the class this page walks through
- [Screen](/api/joist/screen) — the lazy model/view factory pattern `start()` invokes
- [Timer, animationFrameTimer, and stepTimer](/api/axon/timer) — the two timer singletons driven by (or independent of) this loop
- [Scenery Basics](/guides/scenery-basics) — the `Display`/repaint mechanism the loop drives each frame


========================================================================
Page: Testing and QA Strategy Overview
URL: https://veillette.github.io/Almanach/guides/testing-and-qa-strategy-overview
Source: docs/guides/testing-and-qa-strategy-overview.md
Category: Guides | Tags: testing, qa, fuzz-testing, qunit, quality | Status: complete
========================================================================

# Testing and QA Strategy Overview

No single kind of test catches every class of bug in a SceneryStack simulation. A model's physics can be perfectly correct while a control panel silently fails to render on a narrow window; a screen can look flawless while an aggressive sequence of clicks and drags crashes it after ninety seconds. This page is a map of the three complementary layers a healthy sim project relies on — headless unit tests, manual QA passes, and automated fuzz-testing — and what each one is (and isn't) good for.

## The three layers

| Layer | Catches | Cost | Runs |
| --- | --- | --- | --- |
| Unit-testing model logic headlessly | Physics/logic bugs, regressions in `step()`, incorrect `reset()` | Cheapest — no browser, milliseconds per test | Every commit, in CI |
| Manual QA passes | Visual bugs, UX confusion, accessibility gaps, "does this feel right" | Most expensive — a person's time | Before a release, after major feature work |
| Automated fuzz-testing (`?fuzz`) | Crashes and exceptions from unexpected/rapid input sequences no one thought to test by hand | Cheap to run, requires a browser | Regularly in CI or ahead of a release |

None of the three substitutes for the others: a model can be exhaustively unit-tested and still crash the moment a real user drags two things at once during a screen transition, and a sim can survive an hour of fuzzing without a single exception while still being confusing or ugly. Treat them as different nets, each catching what falls through the others.

## Layer 1: unit-testing model logic headlessly

The cheapest and fastest layer is also the one to lean on hardest. Because [Model-View Separation](/patterns/model-view-separation) keeps model classes free of `scenery`/`sun` imports, model logic can be constructed, stepped, and asserted against in plain Node.js — see [Testing Model Logic Headlessly](/patterns/testing-model-logic-headlessly) for the full pattern and a worked `QUnit` example. This is where the bulk of a project's automated test coverage should live: it's fast enough to run on every commit and precise enough that a failure points at the actual broken logic, not a rendering symptom.

## Layer 2: manual QA passes

Some things can only be judged by a person looking at (or listening to, or navigating with a keyboard through) the running sim: does this layout hold up at an unusual window size, is this control's purpose obvious without a caption, does this sound cue feel right paired with this animation. PhET's own process for this is a structured manual QA pass — a checklist walked by a human across every screen, every supported browser/platform combination, and every accessibility mode (keyboard-only, screen reader) before a release. A project without dedicated QA staff can still get most of the value by treating "click through every screen with `?stringTest=double` and a screen reader on" as a release-blocking checklist item, not an afterthought.

## Layer 3: automated fuzz-testing

Between "the model is unit-tested" and "a human clicked through it once" is a large space of input sequences nobody thought to try by hand: rapid clicking during a screen transition, dragging while a reset is in progress, opening a dialog and immediately switching screens. SceneryStack simulations have a built-in tool for probing that space automatically — appending `?fuzz` to the sim's URL drives a stream of randomized pointer and keyboard events at the running sim and reports the first uncaught exception (typically paired with `?ea` so assertions catch problems as early as possible rather than corrupting state silently). See [Fuzz-Testing a Simulation Locally](/cookbook/fuzz-testing-a-simulation-locally) for the concrete recipe — running it locally for a few minutes, and reading query-parameter-driven fuzzing in general as one more application of the [Query Parameters Pattern](/patterns/query-parameters-pattern).

Fuzzing is a crash-finder, not a correctness-checker: it tells you the sim *didn't throw*, not that the physics is right or the UI makes sense — that's still the job of layers 1 and 2. Its value is coverage breadth at near-zero authoring cost: once wired into a CI job (see [Continuous Integration for SceneryStack Projects](/guides/continuous-integration-for-scenerystack-projects)), it runs the same randomized stress test on every push without anyone having to imagine the failing sequence in advance.

::: tip Layer the checks so the cheapest one runs most often
Run headless model tests on every commit, fuzz-testing on a schedule or before merging significant changes, and reserve full manual QA passes for pre-release milestones. Trying to run a full manual pass on every commit is too slow to sustain; relying only on fuzzing and unit tests risks shipping something technically crash-free but confusing or visually broken.
:::

## Where to go next

- [Testing Model Logic Headlessly](/patterns/testing-model-logic-headlessly) — the concrete pattern for layer 1
- [Fuzz-Testing a Simulation Locally](/cookbook/fuzz-testing-a-simulation-locally) — the concrete recipe for layer 3
- [Continuous Integration for SceneryStack Projects](/guides/continuous-integration-for-scenerystack-projects) — wiring these layers into a pipeline that runs automatically


========================================================================
Page: Translation and Localization
URL: https://veillette.github.io/Almanach/guides/translation-and-localization
Source: docs/guides/translation-and-localization.md
Category: Guides | Tags: localization, i18n, strings | Status: verified
========================================================================

# Translation and Localization

Every piece of user-visible text in a SceneryStack simulation is a [`StringProperty`](/api/axon/string-property) (or a `TReadOnlyProperty<string>` derived from one), never a plain string baked into a `Text` node. That single decision is what makes translation possible: swapping the *value* underneath an existing `Property` re-renders anywhere that string is displayed, with no manual re-rendering step.

## Strings live in Properties, not literals

```ts
import { Text } from 'scenerystack/scenery';
import { StringProperty } from 'scenerystack/axon';

const greetingProperty = new StringProperty( 'Hello!' );

const greetingText = new Text( greetingProperty, { font: '20px sans-serif' } );

// Changing the underlying value updates every Node displaying it automatically.
greetingProperty.value = 'Bonjour !';
```

`Text` and `RichText` both accept a `TReadOnlyProperty<string>` directly wherever they'd otherwise take a plain string, so passing a `StringProperty` (or a `DerivedProperty`/`PatternStringProperty` built from one) is idiomatic, not a special case.

## The PhET translation pipeline (conceptual)

In a full PhET-style project, you don't hand-construct every `StringProperty` yourself. The workflow is:

1. Author English strings once, in a JSON file at the project root (conventionally `<sim-name>-strings_en.json`) — see [Project Structure Conventions](/getting-started/project-structure-conventions).
2. A build-time step generates a strongly-typed strings module from that file, exposing one `StringProperty` per key.
3. Translators submit additional per-locale JSON files (`<sim-name>-strings_fr.json`, etc.) through PhET's translation tooling, without touching any TypeScript.
4. At runtime, the active locale determines which JSON file's values populate the generated `StringProperty` instances — the application code that consumes them (`Text`, `RichText`, any `TReadOnlyProperty<string>` consumer) never changes.

The exact generation step is part of the PhET build tooling and out of scope for simulation-author-facing code in Almanach, but the contract you write against is stable regardless: **every generated string is a `Property<string>`**, with the same `.value`/`.link()` API described in [`StringProperty`](/api/axon/string-property) and [`Property`](/api/axon/property).

## Interpolating values into translated strings

Never build a translated string with template literals or concatenation — word order and pluralization vary across languages, so a fixed English sentence shape breaks translation. Use `StringUtils.fillIn` (or the axon `PatternStringProperty`, which wraps the same mechanism as a reactive `Property`) with named placeholders instead:

```ts
import { StringUtils } from 'scenerystack/phetcommon';

// pattern (usually itself a translated StringProperty's value): '{{name}} scored {{points}} points'
const message = StringUtils.fillIn( messagePatternProperty.value, {
  name: 'Ada',
  points: 42
} );
```

```ts
import { PatternStringProperty } from 'scenerystack/axon';

// Reactive version: recomputes whenever the pattern or values change.
const scoreMessageProperty = new PatternStringProperty( messagePatternProperty, {
  name: playerNameProperty,
  points: pointsProperty
} );
```

## Runtime locale

`localeProperty` (from `scenerystack/joist`) reflects the simulation's active locale and is normally set once at startup from the `?locale=` query parameter, not changed mid-session by application code:

```ts
import { localeProperty } from 'scenerystack/joist';

console.log( 'current locale:', localeProperty.value ); // e.g. 'en', 'fr', 'es'
```

::: tip Don't hand-roll a second translation mechanism
It's tempting to reach for `Intl` or a homegrown lookup table for "just this one string." Keeping every displayed string on the `StringProperty` pipeline — even ones you're sure will never need translation — means the whole simulation's localization surface stays discoverable and translatable in one pass, rather than some strings quietly falling outside the pipeline.
:::

## Where to go next

- [`StringProperty`](/api/axon/string-property) — the Property type every translated string is built on
- [Preferences and Feature Flags](/guides/preferences-and-feature-flags) — where locale and other runtime settings are surfaced to users
- [Project Structure Conventions](/getting-started/project-structure-conventions) — where the source strings JSON file lives in a repo


========================================================================
Page: UI Components Overview
URL: https://veillette.github.io/Almanach/guides/ui-components-overview
Source: docs/guides/ui-components-overview.md
Category: Guides | Tags: sun, scenery-phet, ui-components | Status: verified
========================================================================

# UI Components Overview

SceneryStack splits reusable, pre-built `Node`s across two libraries with different scopes: `sun` provides generic, domain-agnostic controls (the things any application needs — buttons, sliders, checkboxes), while `scenery-phet` provides PhET-simulation-specific visualizations and controls built on top of `sun` and `scenery`. Knowing which library a component lives in tells you how broadly reusable it's meant to be.

## `sun`: generic UI controls

Everything in `sun` is bound to an axon `Property` and otherwise has no domain knowledge — a `Checkbox` doesn't know or care whether it's toggling gravity or sound.

```ts
import { Checkbox, HSlider, RectangularPushButton, ComboBox, AccordionBox, Panel } from 'scenerystack/sun';
```

| Component | Use it for |
| --- | --- |
| [`Checkbox`](/api/sun/checkbox) | A single boolean toggle with a label Node |
| [`HSlider`](/api/sun/hslider) / `VSlider` | Continuous numeric input bound to a `NumberProperty` and `Range` |
| [`RectangularPushButton`](/api/sun/rectangular-push-button) / `TextPushButton` | A momentary action button |
| `RectangularRadioButtonGroup` / [`RadioButtonGroup`](/api/sun/radio-button-group) | Mutually-exclusive selection from a small fixed set of options |
| [`ComboBox`](/api/sun/combo-box) | Mutually-exclusive selection from a longer list, in a dropdown |
| [`Panel`](/api/sun/panel) | Bordered/background container that auto-sizes to its content |
| [`AccordionBox`](/api/sun/accordion-box) | Collapsible titled container, e.g. an optional "advanced controls" section |
| `ABSwitch` / `ToggleSwitch` | A labeled two-state switch, an alternative to `Checkbox` for some layouts |

## Live demos

These controls have interactive embeds on their API pages. Try them here, then follow the links for full option tables.

### `sun`

<SceneryDemo demo="checkbox" />

[Checkbox API](/api/sun/checkbox)

<SceneryDemo demo="hslider" />

[HSlider API](/api/sun/hslider)

<SceneryDemo demo="rectangular-push-button" />

[RectangularPushButton API](/api/sun/rectangular-push-button)

### `scenery-phet`

<SceneryDemo demo="number-control" />

[NumberControl API](/api/scenery-phet/number-control)

<SceneryDemo demo="reset-all-button" />

[ResetAllButton API](/api/scenery-phet/reset-all-button)

Compose these with [`FlowBox`/`GridBox`](/guides/scenery-layout) rather than positioning each one by hand:

```ts
import { VBox } from 'scenerystack/scenery';
import { Checkbox, HSlider } from 'scenerystack/sun';
import { Text } from 'scenerystack/scenery';

const controlPanel = new VBox( {
  spacing: 8,
  align: 'left',
  children: [
    new Checkbox( gravityEnabledProperty, new Text( 'Gravity' ) ),
    new HSlider( massProperty, massProperty.range! )
  ]
} );
```

## `scenery-phet`: simulation-specific visualizations

`scenery-phet` builds on `sun` and `scenery` to provide components that show up across many PhET simulations but aren't generic enough for `sun` — visual metaphors for physical quantities, and the handful of controls every sim needs regardless of subject matter.

```ts
import { ResetAllButton, NumberControl, ThermometerNode, ArrowNode, PhetFont } from 'scenerystack/scenery-phet';
```

| Component | Use it for |
| --- | --- |
| [`ResetAllButton`](/api/scenery-phet/reset-all-button) | The standard "reset the whole screen" button — see the [Reset-All Pattern](/patterns/reset-all-pattern) |
| [`NumberControl`](/api/scenery-phet/number-control) | A labeled slider plus numeric readout plus increment/decrement, bundled together |
| [`ThermometerNode`](/api/scenery-phet/thermometer-node) | A fluid-level thermometer bound to a temperature `Property` |
| [`ArrowNode`](/api/scenery-phet/arrow-node) | A vector/force-style arrow, sized and rotated from model data |
| `FaceNode` | A smiley/frowny face, common in game-style feedback |
| `HeaterCoolerNode` | The heater/cooler control used across thermodynamics sims |
| [`PhetFont`](/api/scenery-phet/phet-font) | The standard PhET typeface — use it instead of ad hoc `font` strings for visual consistency |

## Choosing between them

::: tip If it doesn't mention a physical quantity, it probably belongs in `sun`
A rule of thumb: if you can describe a component without referencing anything domain-specific ("a checkbox," "a slider," "a bordered panel"), it's `sun`. If describing it requires a physical concept ("a thermometer," "a force arrow," "a heater/cooler"), it's `scenery-phet`. When you need something novel to your sim's domain that isn't in either library, build it as a plain `Node`/`Path` composition in your own `view/` folder rather than trying to force-fit an existing component — see [Project Structure Conventions](/getting-started/project-structure-conventions).
:::

## Where to go next

- [Scenery Layout](/guides/scenery-layout) — arranging these components with `FlowBox`/`GridBox`/`AlignBox`
- [The Reset-All Pattern](/patterns/reset-all-pattern) — the standard use of `ResetAllButton`
- [Building Your First Screen](/guides/building-your-first-screen) — assembling these into a full `ScreenView`


========================================================================
Page: Working with Model-View Transforms
URL: https://veillette.github.io/Almanach/guides/working-with-model-view-transforms
Source: docs/guides/working-with-model-view-transforms.md
Category: Guides | Tags: phetcommon, dot, coordinates, transform, ModelViewTransform2 | Status: complete
========================================================================

# Working with Model-View Transforms

[`ModelViewTransform2`](/api/phetcommon/model-view-transform) is a small, specific class — a handful of factory methods and `modelToView*`/`viewToModel*` conversions. This guide is the broader "why," and a tour of where a single transform instance actually shows up across a screen's model and view code, once you've adopted the convention.

## Why separate model coordinates from view pixels at all

[Model-View Separation](/patterns/model-view-separation) already establishes that a model's state should be plain data with no scenery imports. Coordinates are where that principle is easiest to violate by accident: it's tempting for a model's `positionProperty` to just hold "pixels from the top-left," since that's ultimately what gets drawn. Two things go wrong once you do that:

- **The model becomes coupled to one specific view size.** A `positionProperty` holding view pixels has no meaning independent of how large the `Display` happens to be — resizing the browser window, or reusing the model in a different layout, means the model's own numbers stop making physical sense.
- **Physics stops reading like physics.** A projectile's launch angle, a planet's orbital radius, a chemical concentration — these have natural units (degrees, meters, moles) with real-world magnitudes and, often, a "up is positive" convention. Scenery pixels are y-down and have no inherent unit; forcing model state into that frame means every physics formula in the model has to fight the coordinate system instead of expressing the physics directly.

Keeping the model in physical, y-up units and doing every pixel conversion at the view boundary — through exactly one `ModelViewTransform2` instance per screen — means the model reads like the physics it represents, and the *only* place "pixels" and "y-down" enter the codebase at all is the small set of view classes that call the transform.

## Where one transform instance travels

A screen typically constructs exactly one `ModelViewTransform2` (in the `ScreenView`'s constructor, sized against `this.layoutBounds`) and threads that same instance to everywhere it's needed — it's not recreated per view Node:

```ts
import { ModelViewTransform2 } from 'scenerystack/phetcommon';
import { Vector2 } from 'scenerystack/dot';
import { ScreenView, type ScreenViewOptions } from 'scenerystack/sim';

class ProjectileScreenView extends ScreenView {
  public constructor( model: ProjectileModel, providedOptions: ScreenViewOptions ) {
    super( providedOptions );

    const modelViewTransform = ModelViewTransform2.createSinglePointScaleInvertedYMapping(
      Vector2.ZERO,
      new Vector2( this.layoutBounds.centerX, this.layoutBounds.maxY - 100 ),
      50
    );

    // The same instance flows to every view class that needs to convert coordinates.
    const projectileNode = new ProjectileBodyNode( model, modelViewTransform );
    // ...and to any drag listener moving a model Property through pointer input.
  }
}
```

The three places it typically shows up:

| Consumer | What it converts |
| --- | --- |
| A view `Node`'s constructor, linking `model.positionProperty` | Model position → `translation`, via `modelToViewPosition` (see [Model-View Separation](/patterns/model-view-separation)) |
| A [drag listener](/patterns/drag-listeners)'s `transform` option | Pointer motion in view pixels → the model `Property` it writes, automatically, in both directions |
| Anything sizing a Node from a model quantity (a radius, a velocity vector) | Model-space *deltas* → view-space deltas, via `modelToViewDeltaX`/`modelToViewDelta` — never the position methods, which also apply translation |

Passing the transform down as a constructor argument (rather than each view class constructing its own) is what guarantees every Node in a screen agrees on the same mapping — two Nodes built from different transform instances would each convert correctly in isolation but disagree with each other about where the same model point belongs on screen.

## Choosing y-inverted vs. not

Most physics-flavored simulations want `createSinglePointScaleInvertedYMapping` — model y increases upward (matching how most physics is taught and written), view y increases downward (matching scenery/CSS/canvas convention), and the transform's job is exactly to reconcile that mismatch once, in one place. A simulation whose "model" is itself already screen-like (a diagram editor, something with no physical y-up convention to preserve) can reach for the non-inverted `createSinglePointScaleMapping` instead — the choice is about whether the model's own y-axis has an inherent "up" direction worth preserving, not a default to apply unconditionally.

::: tip One transform per screen is the common case, not a strict rule
A screen with multiple independent visual regions at different scales (a small inset chart alongside a large main view, for instance) may legitimately need more than one `ModelViewTransform2` — one per region, each mapping the same underlying model quantity to that region's own view scale. What doesn't scale is constructing a *new* transform per Node for the same region — that reintroduces exactly the risk (Nodes disagreeing about the mapping) the shared-instance convention exists to prevent.
:::

## Where to go next

- [ModelViewTransform2](/api/phetcommon/model-view-transform) — the class reference: constructors, methods, and the positions-vs-deltas distinction in full
- [Drag Listeners](/patterns/drag-listeners) — the `transform` option that lets a `DragListener` convert pointer motion automatically
- [Model-View Separation](/patterns/model-view-separation) — the broader architecture this coordinate convention is one instance of


========================================================================
Page: Working with Sound (tambo Overview)
URL: https://veillette.github.io/Almanach/guides/working-with-sound
Source: docs/guides/working-with-sound.md
Category: Guides | Tags: tambo, sound, audio | Status: verified
========================================================================

# Working with Sound (tambo Overview)

`tambo` (`scenerystack/tambo`) is SceneryStack's sound-generation library: instead of every part of a simulation calling into the Web Audio API directly, each sound-producing thing in the sim is a small **sound generator** object, and a single global **`soundManager`** owns the actual audio graph — enabling/disabling sound globally, mixing generators together, applying per-category gain, and connecting the result to the browser's audio output. This page is a subsystem-level tour of that architecture; for using sound specifically as an accessibility channel (sonification alongside Voicing and the PDOM), see [Sound Design](/accessibility/sound-design).

## soundManager: the mixer

`soundManager` is a singleton — you don't construct it, you register generators with it. Conceptually it's the mixing desk: every sound generator you create gets `add`ed to it once, and from then on `soundManager` controls whether it's audible, how loud, and through which category-level gain it's routed:

```ts
import { soundManager } from 'scenerystack/tambo';
import { SoundClip } from 'scenerystack/tambo';
import popSound_mp3 from './sounds/popSound_mp3.js';

const popSoundClip = new SoundClip( popSound_mp3 );

soundManager.addSoundGenerator( popSoundClip, {
  categoryName: 'sim-specific'
} );
```

A generator that's never added to `soundManager` never produces audible output — construction alone doesn't connect it to anything. `removeSoundGenerator` reverses this, and should be called as part of disposing whatever owns the generator (see [Dispose and Memory Management](/patterns/dispose-and-memory-management)) so a long-running sim doesn't accumulate generators nothing plays through anymore.

`soundManager` also exposes `setOutputLevelForCategory( categoryName, outputLevel )`, letting you (or a Preferences panel) turn a whole category up or down together — the standard categories are `'sim-specific'` and `'user-interface'`, so a user can, for instance, mute UI click sounds while keeping model-driven sonification audible.

## The sound generator hierarchy

Every concrete generator (`SoundClip`, `PitchedPopGenerator`, `OscillatorSoundGenerator`, and others) extends a common `SoundGenerator` base class, which is what `soundManager.addSoundGenerator` actually expects. That shared base is what lets `soundManager` treat "play a recorded clip" and "synthesize a tone" identically for the purposes of enabling, disabling, and mixing — the differences between generator types are only in *how* each produces its waveform, not in how it's registered or controlled.

| Generator | Produces | Typical use |
| --- | --- | --- |
| `SoundClip` | Plays a decoded audio asset, one-shot or looping | The default choice for any pre-recorded sound effect |
| `SoundClipPlayer` | A thin wrapper managing a pool of `SoundClip`-like players for rapid repeated triggering | Sounds fired often enough that overlapping playback needs pooling rather than one clip instance |
| `PitchedPopGenerator` | A synthesized "pop" with a controllable pitch, no audio asset needed | Feedback tied to a continuous value (a slider position, a count) where discrete recorded pitches would be impractical |
| `OscillatorSoundGenerator` | A raw oscillator tone | Low-level procedural sound, rarely used directly outside other generators built on it |
| `NoiseGenerator` | Synthesized noise (not a recorded sample) | Ambient/textural sound rather than a discrete event |
| `CompositeSoundClip` | Plays several `SoundClip`s together as one logical unit | Layering (e.g. a base hit sound plus a variable layer) without hand-managing multiple independent clips |

## Playing a recorded sound: SoundClip

`SoundClip` is the generator you reach for most: it wraps a single decoded audio asset (imported the same way an image asset would be) and exposes `play()`/`stop()`:

```ts
import { SoundClip, soundManager } from 'scenerystack/tambo';
import collisionSound_mp3 from './sounds/collisionSound_mp3.js';

const collisionSoundClip = new SoundClip( collisionSound_mp3, {
  loop: false,
  initialPlaybackRate: 1
} );

soundManager.addSoundGenerator( collisionSoundClip );

model.collisionEmitter.addListener( () => collisionSoundClip.play() );
```

`play( delay )` and `stop( delay )` both accept an optional delay in seconds — useful for lining a sound up with an animation rather than triggering it the instant the model event fires. Setting `loop: true` turns the same class into a continuous ambient sound (a running motor, an idle hum) instead of a one-shot effect; a looping clip is started once and left playing (or its `initialOutputLevel`/gain adjusted) rather than re-triggered per event.

## Synthesized feedback: PitchedPopGenerator

Not every sound corresponds to a discrete recorded asset — feedback tied to a continuously varying value (dragging a slider, a running count) is often better served by a synthesized tone whose pitch tracks the value than by trying to pre-record enough discrete pitches to sound smooth. `PitchedPopGenerator` is tambo's built-in example of this pattern: it produces a short "pop" whose pitch you control per-call, pooling a small number of oscillator/gain pairs internally so rapid successive calls don't cut each other off:

```ts
import { PitchedPopGenerator, soundManager } from 'scenerystack/tambo';
import { Range } from 'scenerystack/dot';

const popGenerator = new PitchedPopGenerator( {
  pitchRange: new Range( 220, 660 )
} );

soundManager.addSoundGenerator( popGenerator );

// relativePitch is 0-1; 0 maps to pitchRange.min, 1 to pitchRange.max
countProperty.link( count => {
  const relativePitch = countProperty.range!.getNormalizedValue( count );
  popGenerator.playPop( relativePitch );
} );
```

This is the general shape for any procedurally-driven feedback: construct one generator, register it once with `soundManager`, then call its play method repeatedly as the underlying value changes, rather than constructing a new sound generator per event.

## Where to go next

- [Sound Design](/accessibility/sound-design) — using `soundManager`/`SoundClip`/shared sound players specifically as an accessibility (sonification) channel, and the `sharedSoundPlayers` registry for common UI sounds
- [Dispose and Memory Management](/patterns/dispose-and-memory-management) — why generators need `removeSoundGenerator` on disposal, same as any other listener-holding object
- [Scenery Basics](/guides/scenery-basics) — the Node tree that sound-triggering interactions (drag, press, model events) live alongside


========================================================================
Page: BooleanProperty
URL: https://veillette.github.io/Almanach/api/axon/boolean-property
Source: docs/api/axon/boolean-property.md
Category: API | Tags: axon, BooleanProperty | Status: verified
========================================================================

# BooleanProperty

`BooleanProperty` (from `scenerystack/axon`) is a [`Property`](/api/axon/property) whose value is constrained to `boolean` — truthy/falsy non-boolean values are rejected by its built-in validator, not silently coerced. It's the standard type for simulation flags like "is the sim paused," "is this checkbox checked," or "is this Node visible."

```ts
import { BooleanProperty } from 'scenerystack/axon';

const isPlayingProperty = new BooleanProperty( true );

isPlayingProperty.link( isPlaying => {
  console.log( isPlaying ? 'playing' : 'paused' );
} );

isPlayingProperty.toggle(); // logs "paused"
```

## Methods

`BooleanProperty` adds exactly one method beyond what it inherits from [`Property`](/api/axon/property):

| Method | Effect |
| --- | --- |
| `toggle()` | Sets `value = !value` |

Everything else — `value`, `link`, `lazyLink`, `reset`, `dispose`, and so on — comes from `Property<boolean>`; see the [Property reference](/api/axon/property) for the full list.

## Options

`BooleanPropertyOptions` is `PropertyOptions<boolean>` with `isValidValue`, `valueType`, and `phetioValueType` removed — `BooleanProperty` sets `valueType: 'boolean'` and the PhET-iO `BooleanIO` type internally, so you cannot override them.

```ts
const isVisibleProperty = new BooleanProperty( false, {
  // any remaining PropertyOptions, e.g.:
  reentrant: false
} );
```

::: tip Combining booleans
To derive a boolean from other Properties (`a && b`, `a || b`, `!a`), don't write your own listener — use [`DerivedProperty.and`](/api/axon/derived-property), `.or`, and `.not`, which return a read-only `TReadOnlyProperty<boolean>` kept automatically in sync.
:::


========================================================================
Page: DerivedProperty
URL: https://veillette.github.io/Almanach/api/axon/derived-property
Source: docs/api/axon/derived-property.md
Category: API | Tags: axon, DerivedProperty | Status: verified
========================================================================

# DerivedProperty

`DerivedProperty<T, ...>` (from `scenerystack/axon`) is a read-only Property whose value is automatically recomputed whenever any of its dependency Properties change. It extends the same `ReadOnlyProperty` base as [`Property`](/api/axon/property), so it supports `.value`, `.link()`, `.lazyLink()`, etc. — but calling `.value = ...` on it is a programming error; the value can only change via the derivation function.

```ts
import { DerivedProperty, NumberProperty } from 'scenerystack/axon';

const widthProperty = new NumberProperty( 4 );
const heightProperty = new NumberProperty( 3 );

const areaProperty = new DerivedProperty(
  [ widthProperty, heightProperty ],
  ( width, height ) => width * height
);

areaProperty.link( area => console.log( 'area:', area ) ); // logs "area: 12" immediately
widthProperty.value = 5;                                    // logs "area: 15"
```

The derivation function receives the current `.value` of each dependency, in the same order as the `dependencies` array, and its return type determines `T`.

## Constructor

```ts
new DerivedProperty( dependencies, derivation, providedOptions? )
```

`dependencies` is an array of up to 15 `TReadOnlyProperty<...>` instances (any Property, including another `DerivedProperty`); overloads pick the matching arity so `derivation`'s parameter types line up automatically.

## Members

| Member | Effect |
| --- | --- |
| `recomputeDerivation()` | Force a recompute — useful when a non-Property event (an [`Emitter`](/api/axon/emitter), an observable array's `elementAddedEmitter`) should also trigger recomputation |
| `hasDependency( dependency )` | Whether a given Property is one of this DerivedProperty's dependencies |
| `dispose()` | Unlinks from every dependency; always dispose a `DerivedProperty` you own once it's no longer needed |

## Static factories

Rather than writing a derivation by hand for common cases, `DerivedProperty` offers static helpers that return a `TReadOnlyProperty`:

| Static method | Produces |
| --- | --- |
| `DerivedProperty.and( properties )` | `true` iff every boolean-valued Property is `true` |
| `DerivedProperty.or( properties )` | `true` iff any boolean-valued Property is `true` |
| `DerivedProperty.not( property )` | The logical inverse of a boolean Property |
| `DerivedProperty.valueEquals( a, b )` | `true` iff `a.value === b.value` |
| `DerivedProperty.valueNotEquals( a, b )` | `true` iff `a.value !== b.value` |
| `DerivedProperty.valueEqualsConstant( a, value )` | `true` iff `a.value === value` |
| `DerivedProperty.add( properties )` / `.multiply( properties )` | Sum / product of number-valued Properties |
| `DerivedProperty.toFixedProperty( numberProperty, decimalPlaces )` | A `string` Property formatting the number to a fixed number of decimals |
| `DerivedProperty.fromRecord( key, record )` | Looks up `record[key.value]`, following through if the record's value is itself a Property |
| `DerivedProperty.deriveAny( dependencies, derivation )` | Escape hatch for more than 15 dependencies or a dynamically-sized dependency array |

```ts
import { BooleanProperty } from 'scenerystack/axon';

const isRunningProperty = new BooleanProperty( true );
const isEnabledProperty = new BooleanProperty( true );

const isActiveProperty = DerivedProperty.and( [ isRunningProperty, isEnabledProperty ] );
```

::: warning Read-only — and remember to dispose
`DerivedProperty` overrides `set`/`value=` to throw; it's read-only by design (`phetioReadOnly: true` internally). It also `lazyLink`s to every dependency in its constructor, so an undisposed `DerivedProperty` keeps its dependencies alive — always call `.dispose()` when the derived value is no longer needed, symmetric with any Property you construct yourself.
:::

If you need to react to several Properties without producing a *new* Property value — just running a side-effecting callback — use [`Multilink`](/api/axon/multilink) instead.


========================================================================
Page: DerivedStringProperty
URL: https://veillette.github.io/Almanach/api/axon/derived-string-property
Source: docs/api/axon/derived-string-property.md
Category: API | Tags: axon, DerivedStringProperty, DerivedProperty, PatternStringProperty, i18n, strings | Status: complete
========================================================================

# DerivedStringProperty

`DerivedStringProperty<T extends string, ...>` (from `scenerystack/axon`) is a thin subclass of [`DerivedProperty`](/api/axon/derived-property) whose derivation is constrained to return a `string`. It exists so that string-valued derived Properties — typically built from a translated `StringProperty` and other dependencies — carry the right PhET-iO metadata by default and are easy to spot in code as "this is a derived, translated-or-formatted string," rather than a generic `DerivedProperty<string, ...>`.

```ts
import { DerivedStringProperty, NumberProperty } from 'scenerystack/axon';

const countProperty = new NumberProperty( 3 );

const summaryStringProperty = new DerivedStringProperty(
  [ countProperty ],
  count => `${count} item${count === 1 ? '' : 's'} remaining`
);

summaryStringProperty.value; // '3 items remaining'
countProperty.value = 1;
summaryStringProperty.value; // '1 item remaining'
```

Structurally, `DerivedStringProperty` takes the exact same `dependencies` and `derivation` constructor arguments as `DerivedProperty` — it's `DerivedProperty` with `T` pinned to a string subtype, plus two default options applied for you:

| Default | Value | Why |
| --- | --- | --- |
| `phetioValueType` | `StringIO` | So you don't have to specify it yourself every time |
| `phetioFeatured` | `true` | Translated/derived strings are treated as PhET-iO-featured by default (override if this is an internal, non-featured string) |

## When to reach for this vs. `PatternStringProperty`

If your derivation is "substitute values into a translated pattern string with `{{placeholder}}` tokens," use [`PatternStringProperty`](/api/axon/pattern-string-property) instead — it's *itself* a `DerivedStringProperty` under the hood, and handles the placeholder-filling, `maps`, and `decimalPlaces` machinery for you. Reach for `DerivedStringProperty` directly when your string logic is closer to a one-off formatting function than a pattern substitution — for example, choosing between several already-translated strings based on a state Property, or building a plain (non-pattern) string from numeric data.

::: tip Constrain `T` to the string literals you actually produce
Because `DerivedStringProperty<T extends string, ...>` is generic in `T`, you can (and often should) narrow it to a union of literal strings your derivation actually returns, e.g. `DerivedStringProperty<'small' | 'medium' | 'large', ...>`, rather than letting it widen to the bare `string` type. This gives downstream code (and Storybook-style PhET-iO tooling) a much more useful type than "any string."
:::


========================================================================
Page: DynamicProperty
URL: https://veillette.github.io/Almanach/api/axon/dynamic-property
Source: docs/api/axon/dynamic-property.md
Category: API | Tags: axon, DynamicProperty, Property, MappedProperty | Status: verified
========================================================================

# DynamicProperty

`DynamicProperty<ThisValueType, InnerValueType, OuterValueType>` (from `scenerystack/axon`) solves a specific problem [`DerivedProperty`](/api/axon/derived-property) can't: following a Property *of* Properties. Given a `Property<Property<Color>>` — for example a `currentSceneProperty` whose value is itself a scene's `backgroundColorProperty` — `DynamicProperty` produces a plain `Property<Color>` that automatically re-subscribes to whichever inner Property is current, so consumers never have to unlink from the old scene and relink to the new one by hand.

```ts
import { DynamicProperty, Property } from 'scenerystack/axon';

const firstProperty = new Property( 'red' );
const secondProperty = new Property( 'blue' );
const currentProperty = new Property( firstProperty ); // Property<Property<string>>

const colorProperty = new DynamicProperty( currentProperty );
colorProperty.value; // 'red' — currentProperty.value is firstProperty

firstProperty.value = 'yellow';
colorProperty.value; // 'yellow' — still following firstProperty

currentProperty.value = secondProperty; // switch which Property is active
colorProperty.value; // 'blue'
```

If `currentProperty.value` is ever `null`, `DynamicProperty` falls back to its `defaultValue` option rather than throwing.

## Constructor

```ts
new DynamicProperty( valuePropertyProperty, providedOptions? )
```

`valuePropertyProperty` is the outer, "Property of Properties" source; its value may be `null` to mean "disconnected."

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `derive` | identity | A function `(outerValue) => TReadOnlyProperty<InnerValueType>`, or a string key, for reaching an inner Property that's nested inside the outer value (e.g. `derive: 'backgroundColorProperty'` when the outer Property holds a `Scene` object rather than a Property directly) |
| `defaultValue` | `null` | The `InnerValueType` used (before `map`) when `valuePropertyProperty.value` is `null` |
| `map` | identity | Maps the inner Property's value to `ThisValueType` — lets `DynamicProperty` change type, not just source |
| `inverseMap` | identity | Required alongside `map` only if `bidirectional: true` and the mapping isn't its own inverse |
| `bidirectional` | `false` | If `true`, setting `dynamicProperty.value` writes back through `inverseMap` into the currently-active inner Property, instead of throwing |

```ts
// Bidirectional example, plus a map that changes the exposed type
const dynamicProperty = new DynamicProperty( currentProperty, {
  bidirectional: true,
  map: ( n: number ) => `${n}`,
  inverseMap: ( s: string ) => Number.parseFloat( s )
} );
```

## Methods

| Method | Effect |
| --- | --- |
| `reset()` | Resets whichever inner Property is currently active (asserts if not `bidirectional`) |
| `dispose()` | Unlinks from both the outer Property and the currently-active inner Property |

::: tip MappedProperty is DynamicProperty with the wrapping done for you
[`UnitConversionProperty`](/api/axon/unit-conversion-property) and the general-purpose `MappedProperty` are both literally `DynamicProperty` subclasses that wrap a single source Property in a `TinyProperty` internally, so you get `map`/`inverseMap`/`bidirectional` without needing an outer "Property of Properties." Reach for `DynamicProperty` directly only when the thing you're following can actually change — a `currentSceneProperty`-style source — not just when you want to transform one Property's value into another.
:::


========================================================================
Page: Emitter
URL: https://veillette.github.io/Almanach/api/axon/emitter
Source: docs/api/axon/emitter.md
Category: API | Tags: axon, Emitter, events | Status: verified
========================================================================

# Emitter

`Emitter<T>` (from `scenerystack/axon`) is a typed event bus for discrete occurrences that carry no persistent state — a reset button being pressed, a collision happening, a level being completed. Unlike [`Property`](/api/axon/property), an `Emitter` has no "current value": a newly-added listener does *not* get called back with anything, it only hears about events that happen after it subscribes.

```ts
import { Emitter } from 'scenerystack/axon';

const resetEmitter = new Emitter();

resetEmitter.addListener( () => console.log( 'sim was reset' ) );
resetEmitter.emit(); // logs "sim was reset"
```

## Typed parameters

`Emitter<T extends TEmitterParameter[] = []>` is generic over the tuple of arguments passed to `emit()`. Declare the parameter types as a tuple:

```ts
const scoredEmitter = new Emitter<[ points: number, isBonus: boolean ]>();

scoredEmitter.addListener( ( points, isBonus ) => {
  console.log( `scored ${points} points${isBonus ? ' (bonus!)' : ''}` );
} );

scoredEmitter.emit( 10, false );
```

## Methods

| Method | Effect |
| --- | --- |
| `emit( ...args )` | Calls every listener synchronously with `args` |
| `addListener( listener )` | Registers a listener to be called on `emit()` |
| `removeListener( listener )` | Removes a specific listener |
| `removeAllListeners()` | Removes every listener |
| `hasListener( listener )` | Checks whether a listener is registered |
| `hasListeners()` | Whether any listener is registered |
| `getListenerCount()` | Number of registered listeners |
| `dispose()` | Removes all listeners; call this when the Emitter's owner is disposed |

## Options

`EmitterOptions` is mostly PhET-iO metadata (`tandem`, `phetioDocumentation`, `parameters` describing each argument for the data stream) plus two low-level tuning knobs inherited from `TinyEmitter`:

| Option | Effect |
| --- | --- |
| `reentrantNotificationStrategy` | `'stack'` (default) or `'queue'` — controls ordering when a listener triggers another `emit()` of the same Emitter while still notifying |
| `disableListenerLimit` | Disables the dev-mode assertion that catches an unbounded number of listeners (a common memory-leak symptom) |

```ts
const explodedEmitter = new Emitter( {
  reentrantNotificationStrategy: 'queue'
} );
```

::: tip Emitter vs. Property
If what you're modeling has a "current value" that late-arriving listeners should immediately see — visibility, a numeric setting, a mode — use [`Property`](/api/axon/property) (or a typed subclass). Reach for `Emitter` only for momentary occurrences with no meaningful "current state." See [Emitter vs. Property](/patterns/emitter-vs-property) for more on making this call. [`createObservableArray`](/api/axon/observable-array) uses `Emitter`s internally (`elementAddedEmitter`, `elementRemovedEmitter`) as a good worked example of the distinction — the array's contents are state (its `lengthProperty`), but each add/remove is a discrete event.
:::


========================================================================
Page: EnabledComponent and EnabledProperty
URL: https://veillette.github.io/Almanach/api/axon/enabled-component
Source: docs/api/axon/enabled-component.md
Category: API | Tags: axon, EnabledComponent, EnabledProperty, BooleanProperty, Disposable | Status: complete
========================================================================

# EnabledComponent and EnabledProperty

`EnabledProperty` (from `scenerystack/axon`) is a thin `BooleanProperty` subclass that standardizes what an "enabled" Property looks like: it defaults `tandem` name-checking (it asserts, if instrumented, that its tandem is named `enabledProperty`), sets `phetioFeatured: true`, and supplies default `phetioDocumentation`. `EnabledComponent` is a small base class built on top of it — extend `EnabledComponent` (instead of hand-rolling `public readonly enabledProperty = new BooleanProperty( true )`) to get a consistent `enabledProperty`, `enabled` getter/setter, and disposal wired up automatically, with the same PhET-iO conventions every other `EnabledComponent` subclass follows.

```ts
import { EnabledComponent } from 'scenerystack/axon';

class Thruster extends EnabledComponent {
  public constructor() {
    super( { enabled: true } );
  }

  public fire(): void {
    if ( this.isEnabled() ) {
      // ... apply thrust
    }
  }
}

const thruster = new Thruster();
thruster.enabled = false;
thruster.isEnabled(); // false
```

## `EnabledComponent` options

| Option | Default | Effect |
| --- | --- | --- |
| `enabledProperty` | `null` | Supply your own `TReadOnlyProperty<boolean>` instead of letting `EnabledComponent` create one (useful to share/derive enabled-ness from elsewhere); if provided, `EnabledComponent` does not own or dispose it |
| `enabled` | `true` | Initial value of the auto-created `enabledProperty`; ignored if `enabledProperty` is supplied |
| `enabledPropertyOptions` | `null` | Options forwarded to the auto-created `EnabledProperty` (e.g. `phetioDocumentation`); ignored if `enabledProperty` is supplied |
| `phetioEnabledPropertyInstrumented` | `true` | Whether the auto-created `enabledProperty` gets a PhET-iO tandem (`options.tandem.createTandem( 'enabledProperty' )`) or `Tandem.OPT_OUT` |
| `tandem` | — | Standard PhET-iO tandem, used to namespace the auto-created `enabledProperty` |

## Public API

| Member | Effect |
| --- | --- |
| `enabledProperty` | The underlying `TProperty<boolean>` — either the one you supplied or an auto-created `EnabledProperty` |
| `enabled` (getter/setter) | Convenience accessor for `enabledProperty.value` |
| `isEnabled()` | Same as reading `.enabled` |
| `dispose()` | Disposes the auto-created `enabledProperty` (only if `EnabledComponent` created it — a caller-supplied `enabledProperty` is left alone) |

## `GatedEnabledProperty` and friends

If you need an `enabledProperty` whose value combines an internal ("self") flag with an external, PhET-iO-controllable gate, see `GatedEnabledProperty` (and the parallel `GatedBooleanProperty`/`GatedVisibleProperty`) — also exported from `scenerystack/axon`. Public fields exposing a gated result should be typed [`ReadOnlyProperty<boolean>`](/api/axon/read-only-property), matching the general rule that anything not meant to be set directly from outside advertises `ReadOnlyProperty`, not `Property`.

::: tip Passing your own `enabledProperty` opts you out of ownership
If you supply `enabledProperty` yourself (rather than letting `EnabledComponent` construct one), `EnabledComponent` will neither instrument nor dispose it — that Property's lifecycle is entirely your responsibility. This is the usual way to make several related objects share one `enabledProperty`, but forgetting to dispose the shared Property yourself is a common leak.
:::


========================================================================
Page: EnumerationProperty
URL: https://veillette.github.io/Almanach/api/axon/enumeration-property
Source: docs/api/axon/enumeration-property.md
Category: API | Tags: axon, EnumerationProperty | Status: verified
========================================================================

# EnumerationProperty

`EnumerationProperty<T>` (from `scenerystack/axon`) is a [`Property`](/api/axon/property) whose value is restricted to the instances of a rich [`EnumerationValue`](https://www.npmjs.com/package/scenerystack) subclass, PhET's typed alternative to string-union "enums." It automatically fills in `validValues` from the enumeration and wires up the matching PhET-iO `EnumerationIO`.

```ts
import { EnumerationProperty } from 'scenerystack/axon';
import { Enumeration, EnumerationValue } from 'scenerystack/phet-core';

class SimSpeed extends EnumerationValue {
  public static readonly NORMAL = new SimSpeed();
  public static readonly SLOW = new SimSpeed();

  // Must be declared last, once all values above exist.
  public static readonly enumeration = new Enumeration( SimSpeed );
}

const simSpeedProperty = new EnumerationProperty( SimSpeed.NORMAL );

simSpeedProperty.link( speed => console.log( 'speed:', speed.toString() ) );
simSpeedProperty.value = SimSpeed.SLOW;
```

The PhET enumeration pattern (from `EnumerationValue`'s own documentation): declare each value as a `static readonly` instance of the class, then declare `static readonly enumeration = new Enumeration( MyClass )` last, after every value exists. `EnumerationValue` seals the class at that point — you can no longer construct new instances of it directly (subclassing is still allowed).

## Options

`EnumerationPropertyOptions<T>` extends [`PropertyOptions<T>`](/api/axon/property) (minus `phetioValueType`, which `EnumerationProperty` fills in for you) with one addition:

| Option | Effect |
| --- | --- |
| `enumeration` | The `Enumeration<T>` to validate against. Defaults to `value.enumeration` (read off the initial value); provide it explicitly only if you're subtyping an enumeration and need to pin the subtype's enumeration |

```ts
const speedProperty = new EnumerationProperty( SimSpeed.NORMAL, {
  enumeration: SimSpeed.enumeration // usually unnecessary — inferred from `value`
} );
```

::: tip Exhaustiveness over string unions
Prefer `EnumerationProperty` over a [`StringProperty`](/api/axon/string-property) with `validValues` whenever the value represents a closed set of named states. TypeScript can exhaustively check `switch` statements over `EnumerationValue` instances, and the enumeration's `.values` array (`SimSpeed.enumeration.values`) is available at runtime for building UI like radio button groups.
:::


========================================================================
Page: Multilink
URL: https://veillette.github.io/Almanach/api/axon/multilink
Source: docs/api/axon/multilink.md
Category: API | Tags: axon, Multilink | Status: verified
========================================================================

# Multilink

`Multilink` (from `scenerystack/axon`) links a callback to multiple Properties at once, calling it whenever any of them change. It's the callback-only sibling of [`DerivedProperty`](/api/axon/derived-property): use it when you need a side effect (repositioning a Node, playing a sound, logging) rather than a new derived value.

```ts
import { Multilink, NumberProperty } from 'scenerystack/axon';

const xProperty = new NumberProperty( 0 );
const yProperty = new NumberProperty( 0 );

Multilink.multilink( [ xProperty, yProperty ], ( x, y ) => {
  console.log( `position: (${x}, ${y})` );
} ); // logs "position: (0, 0)" immediately

xProperty.value = 5; // logs "position: (5, 0)"
```

## Static convenience methods (preferred)

The static factories are preferred over `new Multilink(...)` directly, both because they read better and because a bare `new Multilink(...)` with no captured reference trips lint rules for side-effect-only construction:

| Method | Behavior |
| --- | --- |
| `Multilink.multilink( dependencies, callback )` | Links and calls `callback` immediately with current values |
| `Multilink.lazyMultilink( dependencies, callback )` | Links without an immediate callback |
| `Multilink.multilinkAny( dependencies, callback )` | Same as `multilink`, but for a dynamically-sized array of dependencies (callback takes no arguments) |
| `Multilink.lazyMultilinkAny( dependencies, callback )` | Lazy version of `multilinkAny` |
| `Multilink.unmultilink( multilink )` | Disposes a Multilink instance — equivalent to calling `.dispose()` on it |

```ts
const multilinkHandle = Multilink.multilink(
  [ xProperty, yProperty ],
  ( x, y ) => console.log( x, y )
);

// later
Multilink.unmultilink( multilinkHandle );
```

## Constructor

```ts
new Multilink( dependencies, callback, lazy? )
```

Up to 15 dependencies are supported via overloads (like [`DerivedProperty`](/api/axon/derived-property)), with `callback`'s parameter types inferred from the dependency array. Pass `lazy: true` as the third argument to suppress the initial callback.

## Members

| Member | Effect |
| --- | --- |
| `dispose()` | Unlinks the callback from every dependency. Calling `dispose()` twice throws an assertion error |

::: tip Multilink vs. DerivedProperty
Reach for [`DerivedProperty`](/api/axon/derived-property) when the combination of dependencies *is* a value other code should read and link to (e.g. an `areaProperty` other Nodes bind their size to). Reach for `Multilink` when you only need to *run something* when several Properties change together and there's no resulting value worth exposing as its own Property.
:::


========================================================================
Page: NumberProperty
URL: https://veillette.github.io/Almanach/api/axon/number-property
Source: docs/api/axon/number-property.md
Category: API | Tags: axon, NumberProperty, range | Status: verified
========================================================================

# NumberProperty

`NumberProperty` (from `scenerystack/axon`) is a [`Property`](/api/axon/property) whose value must be a number, with an optional `range` that both validates the value and is exposed to UI components (like sliders) that need to know the legal bounds. The range itself is stored as its own nested `rangeProperty`, so range and value can each be observed independently.

```ts
import { NumberProperty } from 'scenerystack/axon';
import { Range } from 'scenerystack/dot';

const volumeProperty = new NumberProperty( 0.5, {
  range: new Range( 0, 1 )
} );

volumeProperty.link( volume => console.log( 'volume:', volume ) );

volumeProperty.value = 1.5; // throws an assertion error in dev builds: outside rangeProperty's range
```

## Options

| Option | Effect |
| --- | --- |
| `range` | A `Range` (or a `Property<Range>` for a dynamic range) that values are validated against |
| `numberType` | `'FloatingPoint'` (default) or `'Integer'` — `'Integer'` adds a validator requiring `value % 1 === 0` |
| `rangePropertyOptions` | Options forwarded to the internally-created `rangeProperty`, ignored if you passed a `Property<Range>` for `range` |

All other [`PropertyOptions`](/api/axon/property) (e.g. `units`, `reentrant`) are supported too; `valueType` and `phetioValueType` are fixed to `'number'` / `NumberIO` internally.

## Members and methods

| Member | Effect |
| --- | --- |
| `range` (getter/setter) | Reads or replaces the current `Range` value (shorthand for `rangeProperty.value`) |
| `rangeProperty` | The underlying `Property<Range>` — link to it directly if a UI element needs to react to range changes |
| `setValueAndRange( value, range )` | Atomically sets both value and range so an intermediate state never fails validation |
| `resetValueAndRange()` | Resets both `value` and `range` back to their initial values together |
| `reset()` | Overridden to reset value and range atomically, then defer to `Property.reset()` |

```ts
const angleProperty = new NumberProperty( 0, { range: new Range( 0, 90 ) } );

// Grow the range and set an out-of-old-range value without a transient validation error:
angleProperty.setValueAndRange( 120, new Range( 0, 180 ) );
```

::: warning Range changes are validated immediately
Setting `.range = ...` directly re-validates the *current* value against the new range right away. If the new range wouldn't contain the current value, use `setValueAndRange()` (or `setDeferred`) to change both together — otherwise you'll trip an assertion in dev builds.
:::


========================================================================
Page: Observable Array
URL: https://veillette.github.io/Almanach/api/axon/observable-array
Source: docs/api/axon/observable-array.md
Category: API | Tags: axon, observable-array, collections | Status: verified
========================================================================

# Observable Array (createObservableArray)

`createObservableArray<T>` (from `scenerystack/axon`) builds an object with the exact same API as a native JavaScript `Array<T>` — you can `push`, `pop`, `splice`, index with `[i]`, iterate, etc. — but that also notifies listeners whenever its contents change. Internally it wraps a real array in a `Proxy` and exposes an [`Emitter`](/api/axon/emitter) for additions, an `Emitter` for removals, and a [`NumberProperty`](/api/axon/number-property) tracking the length.

```ts
import { createObservableArray } from 'scenerystack/axon';

const particles = createObservableArray<{ id: number }>();

particles.elementAddedEmitter.addListener( particle => console.log( 'added', particle.id ) );
particles.elementRemovedEmitter.addListener( particle => console.log( 'removed', particle.id ) );
particles.lengthProperty.link( length => console.log( 'count:', length ) );

particles.push( { id: 1 } ); // logs "added 1", then "count: 1"
particles.pop();             // logs "removed 1", then "count: 0"
```

`lengthProperty` always updates *before* the corresponding `elementAddedEmitter`/`elementRemovedEmitter` fires, so a listener on either emitter can safely read the up-to-date `lengthProperty.value`.

## Observable members

| Member | Type | Notes |
| --- | --- | --- |
| `elementAddedEmitter` | `TEmitter<[T]>` | Fires once per element added (`push`, `unshift`, `splice` insertions, index assignment, etc.) |
| `elementRemovedEmitter` | `TEmitter<[T]>` | Fires once per element removed |
| `lengthProperty` | `NumberProperty` | Mirrors `.length`; read-only in practice — don't set it directly |

## Array-like and convenience methods

All standard `Array<T>` methods work as expected (`push`, `pop`, `shift`, `unshift`, `splice`, `map`, `filter`, `forEach`, indexing, `for...of`, ...). `createObservableArray` also layers on PhET-specific convenience methods:

| Method | Effect |
| --- | --- |
| `add( element )` | Alias for `push( element )` |
| `addAll( elements )` | Pushes every element in `elements` |
| `remove( element )` | Removes the first matching element |
| `removeAll( elements )` | Removes every matching element in `elements` |
| `clear()` | Empties the array (pops until empty, so removal notifications still fire) |
| `count( predicate )` | Number of elements matching `predicate` |
| `find( predicate, fromIndex? )` | First matching element, or `undefined` |
| `get( index )` | Same as `array[index]` |
| `getArrayCopy()` | A plain (non-observable) `T[]` snapshot |
| `shuffle( random )` | Reorders in place via a `{ shuffle }`-shaped random source, without firing add/remove notifications |
| `addItemAddedListener` / `removeItemAddedListener` | Legacy aliases for `elementAddedEmitter.addListener` / `removeListener` |
| `addItemRemovedListener` / `removeItemRemovedListener` | Legacy aliases for `elementRemovedEmitter.addListener` / `removeListener` |
| `reset()` | Restores the array to the `elements`/`length` it was constructed with |
| `dispose()` | Disposes `elementAddedEmitter`, `elementRemovedEmitter`, and `lengthProperty` |

## Options

```ts
const readingsArray = createObservableArray<number>( {
  elements: [ 0, 0, 0 ]
} );
```

| Option | Effect |
| --- | --- |
| `elements` | Initial contents (mutually exclusive with `length`) |
| `length` | Initial length, filled with `undefined` (mutually exclusive with `elements`) |
| `elementAddedEmitterOptions` | Options forwarded to the internal `elementAddedEmitter` |
| `elementRemovedEmitterOptions` | Options forwarded to the internal `elementRemovedEmitter` |
| `lengthPropertyOptions` | Options forwarded to the internal `lengthProperty` |

::: tip It's a function, not a class
There is no `ObservableArray` constructor to `new` up — call `createObservableArray<T>(options?)` and you get back a value that satisfies both `T[]` and the observable API table above. The exported `ObservableArray<T>` name from `scenerystack/axon` is a *type*, useful for annotating a field or parameter, not a runtime class.
:::

::: warning Prefer this over an array of Properties for "add/remove" collections
If you find yourself keeping a plain `T[]` alongside a manually-maintained `Emitter` for adds and another for removes, that's exactly what `createObservableArray` already does — and it keeps `lengthProperty` in sync for you, which is easy to get wrong by hand. See [DerivedProperty](/api/axon/derived-property) if you need a *value* computed from the array's contents (e.g. a sum), by pairing `DerivedProperty.deriveAny` with `lengthProperty` or `recomputeDerivation()` triggered from `elementAddedEmitter`/`elementRemovedEmitter`.
:::


========================================================================
Page: PatternStringProperty
URL: https://veillette.github.io/Almanach/api/axon/pattern-string-property
Source: docs/api/axon/pattern-string-property.md
Category: API | Tags: axon, PatternStringProperty, DerivedProperty, i18n, strings | Status: verified
========================================================================

# PatternStringProperty

`PatternStringProperty<Values>` (from `scenerystack/axon`) is a specialized [`DerivedProperty`](/api/axon/derived-property) (technically, a `DerivedStringProperty`) that fills `{{placeholder}}` tokens in a translated pattern string with values pulled from other Properties, automatically re-deriving whenever the pattern string or any value Property changes. This is the standard way to build a translated, dynamic UI string like "Score: {{score}}" or "{{count}} particles remaining" without hand-rolling a `DerivedProperty` and a `StringUtils.fillIn` call yourself.

```ts
import { PatternStringProperty, NumberProperty, TinyProperty } from 'scenerystack/axon';

const scoreProperty = new NumberProperty( 0 );
const patternProperty = new TinyProperty( '{{score}} points' ); // typically a translated StringProperty

const scoreStringProperty = new PatternStringProperty( patternProperty, {
  score: scoreProperty
} );

scoreStringProperty.value; // '0 points'
scoreProperty.value = 12;
scoreStringProperty.value; // '12 points'
```

Values may be plain strings/numbers or Properties of strings/numbers — both work in the `values` record, and only the Property ones become dependencies that trigger re-derivation.

## Constructor

```ts
new PatternStringProperty( patternProperty, values, providedOptions? )
```

| Parameter | Effect |
| --- | --- |
| `patternProperty` | A `TReadOnlyProperty<string>` holding the pattern, e.g. a localized `...StringProperty` with `{{name}}`-style placeholders |
| `values` | A record mapping each placeholder name to a `string \| number \| TReadOnlyProperty<string \| number>` (or, with a `maps` entry, any other Property type) |
| `providedOptions` | See below |

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `maps` | `{}` | Per-key functions converting a value to `string \| number` before substitution — **required** for any key whose value isn't already `string`, `number`, or a Property of those |
| `decimalPlaces` | `null` | Rounds numeric values (after any `map`) to a fixed number of decimals; either one number applied to every numeric value, or a per-key record |
| `formatNames` | `[]` | Back-compat shim for patterns written for `StringUtils.format`'s `{0}`/`{1}` style — lists the placeholder names those positional indices map to |

```ts
const gramsProperty = new NumberProperty( 2143 );

const kilogramsStringProperty = new PatternStringProperty(
  new TinyProperty( '{{kilograms}} kg' ),
  { kilograms: gramsProperty },
  {
    maps: { kilograms: ( grams: number ) => grams / 1000 },
    decimalPlaces: 2
  }
);

kilogramsStringProperty.value; // '2.14 kg'
```

::: tip It's a DerivedProperty — dispose it
Because `PatternStringProperty` is built on `DerivedProperty`, it lazy-links to `patternProperty` and every value Property passed in, and its value can't be set directly. Always `dispose()` a `PatternStringProperty` you create dynamically (e.g. per list item), the same as any other `DerivedProperty`.
:::


========================================================================
Page: Property
URL: https://veillette.github.io/Almanach/api/axon/property
Source: docs/api/axon/property.md
Category: API | Tags: axon, Property, reactive | Status: verified
========================================================================

# Property

`Property<T>` (from `scenerystack/axon`) is the base observable value wrapper that all reactive state in a SceneryStack simulation is built on. It holds a single current value, notifies listeners when that value changes, and remembers its initial value so it can be `reset()`. Almost every other axon class — [`BooleanProperty`](/api/axon/boolean-property), [`NumberProperty`](/api/axon/number-property), [`StringProperty`](/api/axon/string-property), [`EnumerationProperty`](/api/axon/enumeration-property) — is a thin, typed subclass of `Property`, and [`DerivedProperty`](/api/axon/derived-property) is a read-only sibling built on the same base (`ReadOnlyProperty`).

```ts
import { Property } from 'scenerystack/axon';

const isPausedProperty = new Property<boolean>( false );

isPausedProperty.link( isPaused => {
  console.log( 'paused:', isPaused );
} );

isPausedProperty.value = true; // logs "paused: true"
```

## Reading and writing

`value` is the idiomatic get/set (there are also `get()`/`set()` methods that do the same thing, useful in hot inner loops):

```ts
const speedProperty = new Property( 1 );

speedProperty.value = 2;        // triggers listeners if the value actually changed
console.log( speedProperty.value ); // 2

speedProperty.reset();          // back to the initial value (1)
```

## Listening for changes

| Method | Behavior |
| --- | --- |
| `link( listener )` | Adds a listener and immediately calls it once with `( value, null, this )` |
| `lazyLink( listener )` | Adds a listener without an immediate callback |
| `unlink( listener )` | Removes a specific listener |
| `unlinkAll()` | Removes every listener |
| `hasListener( listener )` | Checks whether a listener is registered |
| `linkAttribute( object, attributeName )` | Convenience: sets `object[attributeName] = value` whenever the Property changes |

```ts
const listener = ( newValue: number, oldValue: number | null ) => {
  console.log( `${oldValue} -> ${newValue}` );
};

speedProperty.link( listener );     // fires immediately with (1, null)
speedProperty.lazyLink( listener ); // does not fire immediately
speedProperty.unlink( listener );
```

## Other members

| Member | Effect |
| --- | --- |
| `initialValue` (getter) | The value the Property was constructed with |
| `getInitialValue()` / `setInitialValue( value )` | Explicit accessors for the initial value; use `setInitialValue` sparingly, only when the "reset" value isn't known until after construction |
| `reset()` | Sets the value back to `initialValue` |
| `isSettable()` | Returns `true` for `Property` (subclasses like `DerivedProperty` override this to `false`) |
| `dispose()` | Removes all listeners and marks the Property as disposed |
| `isValueValid( value )` / `getValidationError( value )` | Check a candidate value against the Property's validator without setting it |

## Options

`Property` accepts a `PropertyOptions<T>` object as its second constructor argument. The most commonly used options for simulation code:

| Option | Effect |
| --- | --- |
| `valueType` | A validator shorthand, e.g. `'boolean'`, `'number'`, or a constructor, checked on every `set()` |
| `validValues` | Restrict the value to a fixed array of allowed values |
| `isValidValue` | A custom `( value ) => boolean` predicate |
| `units` | Physical units string for PhET-iO/documentation purposes |
| `reentrant` | Allow a listener to set the Property's own value again while notifications are in progress (default `false`) |

::: tip Prefer a typed subclass
Reach for `Property<T>` directly only when there isn't a more specific subclass. For booleans, numbers, strings, and enum values, use [`BooleanProperty`](/api/axon/boolean-property), [`NumberProperty`](/api/axon/number-property), [`StringProperty`](/api/axon/string-property), or [`EnumerationProperty`](/api/axon/enumeration-property) instead — they bake in the right validators and PhET-iO serialization automatically.
:::

::: warning Property vs. Emitter
A `Property` always has a *current value* that new listeners immediately receive on `link()`. If you need to broadcast a discrete occurrence that has no persistent state — a "button pressed" or "collision happened" moment — use [`Emitter`](/api/axon/emitter) instead. See [Emitter vs. Property](/patterns/emitter-vs-property) for the full guidance.
:::


========================================================================
Page: ReadOnlyProperty
URL: https://veillette.github.io/Almanach/api/axon/read-only-property
Source: docs/api/axon/read-only-property.md
Category: API | Tags: axon, ReadOnlyProperty, Property, DerivedProperty, reactive | Status: complete
========================================================================

# ReadOnlyProperty

`ReadOnlyProperty<T>` (from `scenerystack/axon`) is the base class that [`Property`](/api/axon/property) extends. It implements everything about an observable value — `.value`/`.get()`, `link()`, `lazyLink()`, `unlink()`, `dispose()`, PhET-iO serialization — except the ability to *set* the value from outside: its `set()`/`value=` accessors are `protected`, and its constructor is `protected` too, so you never instantiate `ReadOnlyProperty` directly. Subclasses fall into two families: `Property` (and its typed siblings `BooleanProperty`, `NumberProperty`, ...) re-expose `set`/`value=` as `public`, making the value externally settable; [`DerivedProperty`](/api/axon/derived-property) and [`DynamicProperty`](/api/axon/dynamic-property) leave them protected, so the only way their value changes is through their own internal logic.

```ts
import { ReadOnlyProperty, DerivedProperty, NumberProperty } from 'scenerystack/axon';

const widthProperty = new NumberProperty( 4 );
const heightProperty = new NumberProperty( 3 );

const areaProperty: ReadOnlyProperty<number> = new DerivedProperty(
  [ widthProperty, heightProperty ],
  ( width, height ) => width * height
);

areaProperty.isSettable(); // false - DerivedProperty never overrides this
// areaProperty.value = 100; // compile error: 'value' is protected on ReadOnlyProperty
```

## Why public APIs say `ReadOnlyProperty<T>`, not `Property<T>`

When a class exposes a derived or gated value — `isValidProperty`, `areaProperty`, anything built with `DerivedProperty` or `DynamicProperty` — its public field should be typed `ReadOnlyProperty<T>` (or the narrower `TReadOnlyProperty<T>` interface), never `Property<T>`. Typing it as `Property<T>` would be a lie: it advertises a settable `.value=` that either doesn't exist at runtime (TypeScript would happily compile `areaProperty.value = 5`, since `Property` widens the type) or, worse, silently succeeds and desyncs from the derivation. Reserve the `Property<T>` type annotation for fields you actually construct as a plain, externally-settable `Property` (or subclass).

## Public API

`ReadOnlyProperty` provides the full read side of the Property API; only `set`/`value=` are missing (protected) compared to `Property`:

| Member | Effect |
| --- | --- |
| `value` (getter) / `get()` | The current value |
| `link( listener )` / `lazyLink( listener )` | Subscribe to changes, with or without an immediate callback |
| `unlink( listener )` / `unlinkAll()` | Remove one or all listeners |
| `hasListener( listener )` / `hasListeners()` | Inspect subscriptions |
| `isSettable()` | Returns `false` on `ReadOnlyProperty` and any subclass that doesn't override it (e.g. `DerivedProperty`); `Property` overrides it to `true` |
| `isValueValid( value )` / `getValidationError( value )` | Check a candidate value against the Property's validator without setting it |
| `linkAttribute( object, attributeName )` | Convenience: sets `object[attributeName] = value` on every change |
| `toString()` / `debug( name )` | Console-debugging helpers |
| `dispose()` | Removes all listeners and marks the instance disposed |

::: tip Use `isSettable()` to branch on capability at runtime
Because both `Property` and `ReadOnlyProperty` share this same base type, `isSettable()` is the correct runtime check when code receives a `TReadOnlyProperty<T>` and needs to know whether it's safe to attempt a cast-and-set (some PhET-iO and Studio tooling does exactly this). Don't rely on `instanceof Property` for this — prefer the method, since it's what the class itself uses internally to guard `PhetioStateEngine` value-setting.
:::


========================================================================
Page: StringProperty
URL: https://veillette.github.io/Almanach/api/axon/string-property
Source: docs/api/axon/string-property.md
Category: API | Tags: axon, StringProperty, localization | Status: verified
========================================================================

# StringProperty

`StringProperty` (from `scenerystack/axon`) is a [`Property`](/api/axon/property) whose value must be a `string`. It adds no methods beyond `Property<string>` — its entire job is fixing `valueType: 'string'` and the PhET-iO `StringIO` type so every string-valued piece of simulation state validates and serializes consistently.

```ts
import { StringProperty } from 'scenerystack/axon';

const labelProperty = new StringProperty( 'Start' );

labelProperty.link( label => console.log( 'button label:', label ) );
labelProperty.value = 'Resume';
```

## Options

`StringPropertyOptions` is `PropertyOptions<string>` with `valueType` and `phetioValueType` removed, since `StringProperty` sets both internally (`'string'` and `StringIO`, respectively). All other [`PropertyOptions`](/api/axon/property) — `validValues`, `isValidValue`, `units`, `reentrant`, etc. — pass through normally:

```ts
const modeProperty = new StringProperty( 'idle', {
  validValues: [ 'idle', 'running', 'paused' ]
} );
```

## Role in localization

Displayed, translatable UI text in SceneryStack simulations is generally exposed through generated `StringProperty` instances (from the sim's `-strings_en.json` and Fluent-based string modules), not through this constructor directly — but the underlying contract is the same `Property<string>` API described here and on the [Property](/api/axon/property) page: `.value`, `.link()`, `.dispose()`. Any `scenery` Node that displays text (e.g. `Text`, `RichText`) accepts a `TReadOnlyProperty<string>` for its `string`/`stringProperty` option, so a plain `StringProperty` is a fine stand-in during development before the translated strings pipeline is wired up.

::: tip Restricting to a fixed set of strings
If a string Property should only ever hold one of a small, fixed set of values (e.g. `'idle' | 'running' | 'paused'`), consider whether an [`EnumerationProperty`](/api/axon/enumeration-property) backed by an `EnumerationValue` subclass is a better fit than a raw `StringProperty` with `validValues` — the enumeration gives you compile-time exhaustiveness checks that a string union does not.
:::


========================================================================
Page: StringUnionProperty
URL: https://veillette.github.io/Almanach/api/axon/string-union-property
Source: docs/api/axon/string-union-property.md
Category: API | Tags: axon, StringUnionProperty, Property, enumeration, TypeScript | Status: verified
========================================================================

# StringUnionProperty

`StringUnionProperty<T extends string>` (from `scenerystack/axon`) is a thin [`Property`](/api/axon/property) subclass for the common TypeScript idiom of using a string literal union (`'small' | 'medium' | 'large'`) as a lightweight enumeration, instead of an [`EnumerationProperty`](/api/axon/enumeration-property) backed by a `Rich Enumeration` class. It requires `validValues` at construction (there's no way to construct one without it) and derives the PhET-iO `phetioValueType` from that list automatically via `StringUnionIO`.

```ts
import { StringUnionProperty } from 'scenerystack/axon';

type SizeChoice = 'small' | 'medium' | 'large';

const sizeProperty = new StringUnionProperty<SizeChoice>( 'medium', {
  validValues: [ 'small', 'medium', 'large' ]
} );

sizeProperty.value = 'large'; // fine
// sizeProperty.value = 'huge'; // would throw an assertion error — not in validValues
```

## Constructor

```ts
new StringUnionProperty<T extends string>( value: T, providedOptions: StringEnumerationPropertyOptions<T> )
```

Unlike plain `Property`, the options argument is **required** — `validValues` has no default and must be supplied.

## Options

`StringUnionProperty` accepts the same [`PropertyOptions<T>`](/api/axon/property) as `Property`, with two differences:

| Option | Effect |
| --- | --- |
| `validValues` | **Required.** The full list of legal string literal values — also used to build the `phetioValueType` |
| `phetioValueType` | Not settable — `StringUnionProperty` always computes it from `validValues` via `StringUnionIO` |

Everything else (`tandem`, `units`, `reentrant`, …) works exactly as it does on `Property`.

::: tip When to reach for this instead of EnumerationProperty
Use `StringUnionProperty` when the set of choices is small, has no associated behavior/data beyond the label itself, and is naturally expressed as a TypeScript string literal union already used elsewhere in your model's types. Use [`EnumerationProperty`](/api/axon/enumeration-property) instead when the values need to carry additional data or methods (a full PhET "Rich Enumeration" class) — see the [Enumeration Pattern](/patterns/enumeration-pattern) for the tradeoffs between the two approaches.
:::


========================================================================
Page: Timer, animationFrameTimer, and stepTimer
URL: https://veillette.github.io/Almanach/api/axon/timer
Source: docs/api/axon/timer.md
Category: API | Tags: axon, Timer, animationFrameTimer, stepTimer, scheduling | Status: complete
========================================================================

# Timer, animationFrameTimer, and stepTimer

`Timer` (from `scenerystack/axon`) is a small `TinyEmitter<[ number ]>` subclass that adds `setTimeout`/`clearTimeout` and `setInterval`/`clearInterval`-style scheduling on top of a simple `dt`-driven `emit`. Rather than construct your own, simulation code almost always reaches for one of the two ready-made singleton instances axon exports: `animationFrameTimer` and `stepTimer`. Both are plain `Timer` instances; they differ only in *who calls `emit()` on them and when*.

```ts
import { stepTimer, animationFrameTimer } from 'scenerystack/axon';

// Fires once, ~500ms of sim time after this call, driven by the sim's step loop:
const timeoutListener = stepTimer.setTimeout( () => {
  console.log( 'sim has stepped for 500ms' );
}, 500 );

// Fires every frame, whether or not the sim is currently active/running:
animationFrameTimer.addListener( dt => {
  // dt is in seconds
} );
```

## `stepTimer` vs. `animationFrameTimer`

| | `stepTimer` | `animationFrameTimer` |
| --- | --- | --- |
| Driven by | The running `Sim`'s `stepSimulation` call (also ticks in accessibility tests and bare `Display` animation loops) | The browser's `requestAnimationFrame` loop directly, independent of whether a `Sim` is active |
| Ticks while paused / inactive | No — tied to the active screen's step | Yes — keeps firing even when the sim is paused or backgrounded |
| Typical use | Model-time scheduling: "wait 400ms of sim time," debounced UI updates tied to simulation stepping | Animation/UI effects that must keep running regardless of play/pause state (e.g. a `stepTimer`-independent visual pulse) |

Both are global, screen-independent singletons — a `setTimeout` registered on `stepTimer` from one screen will still fire even if the user has navigated to a different screen, as long as the sim keeps stepping at all.

## `Timer`'s public API

| Member | Effect |
| --- | --- |
| `setTimeout( listener, timeout )` | Calls `listener()` once, after `timeout` milliseconds of accumulated `dt` have elapsed; returns an internal callback handle |
| `clearTimeout( handle )` | Cancels a pending `setTimeout`, using the handle it returned |
| `setInterval( listener, interval )` | Calls `listener()` repeatedly every `interval` milliseconds of accumulated `dt`; returns a handle |
| `clearInterval( handle )` | Cancels a running `setInterval` |
| `runOnNextTick( listener )` | Convenience for `setTimeout( listener, 0 )` |
| `addListener( listener )` / `removeListener( listener )` | Inherited from `TinyEmitter` — the low-level `( dt: number ) => void` hook that `setTimeout`/`setInterval` are themselves built on |

`CallbackTimer` (also exported from `scenerystack/axon`) is a related but distinct higher-level utility built on top of `stepTimer`: it models "press-and-hold" style repeated firing (an initial `delay`, then continuous firing at `interval`), the same pattern used by `sun`'s press-and-hold buttons.

::: warning `timeout`/`interval` are in milliseconds; `dt` is in seconds
`setTimeout`/`setInterval`'s duration arguments are milliseconds (matching the browser APIs they mimic), but the underlying `emit( dt )` — and any listener you add directly via `addListener` — receives `dt` in **seconds**, matching the rest of axon/scenery's simulation-time conventions. Mixing up the units is a common source of "my timeout fires 1000x too fast/slow" bugs.
:::


========================================================================
Page: TinyEmitter
URL: https://veillette.github.io/Almanach/api/axon/tiny-emitter
Source: docs/api/axon/tiny-emitter.md
Category: API | Tags: axon, TinyEmitter, Emitter, events, performance | Status: verified
========================================================================

# TinyEmitter

`TinyEmitter<T>` (from `scenerystack/axon`) is the same discrete-event abstraction as [`Emitter`](/api/axon/emitter) — `addListener`, `removeListener`, `emit`, `dispose` — but without the PhET-iO instrumentation, tandem, or `parameters` metadata layered on top. `Emitter` actually *is* a thin `TinyEmitter` wrapper internally; reach for `TinyEmitter` directly when you're writing axon-internal or high-frequency code (per-frame or per-listener-call overhead matters) and don't need PhET-iO data-stream support.

```ts
import { TinyEmitter } from 'scenerystack/axon';

const resizeEmitter = new TinyEmitter<[ width: number, height: number ]>();

resizeEmitter.addListener( ( width, height ) => {
  console.log( `resized to ${width}x${height}` );
} );

resizeEmitter.emit( 800, 600 );
```

## Constructor

Unlike `Emitter`'s single config-object constructor, `TinyEmitter` takes up to four positional arguments (any of which may be omitted or passed as `null`) instead of an options object — this avoids allocating an options object on hot construction paths:

```ts
new TinyEmitter<T>(
  onBeforeNotify?: TEmitterListener<T> | null,
  hasListenerOrderDependencies?: boolean | null,
  reentrantNotificationStrategy?: 'stack' | 'queue' | null,
  disableListenerLimit?: boolean | null
)
```

| Parameter | Default | Effect |
| --- | --- | --- |
| `onBeforeNotify` | `undefined` | Called with the same arguments as `emit()`, just before listeners are notified |
| `hasListenerOrderDependencies` | `undefined` | Set `true` to assert that listener order must stay fixed (relevant only under the `?listenerOrder` debug query parameter) |
| `reentrantNotificationStrategy` | `'stack'` | `'stack'`: a nested `emit()` call (triggered from within a listener) fully resolves before the outer `emit()` continues notifying. `'queue'`: nested `emit()` calls are queued and notified breadth-first, after the current round finishes |
| `disableListenerLimit` | `undefined` | Skips the dev-mode assertion that flags runaway listener counts |

## Methods

| Method | Effect |
| --- | --- |
| `emit( ...args )` | Calls every listener synchronously with `args` |
| `addListener( listener )` | Registers a listener; asserts if the same listener is already registered |
| `removeListener( listener )` | Removes a specific listener |
| `removeAllListeners()` | Removes every listener |
| `hasListener( listener )` | Checks whether a listener is registered |
| `hasListeners()` | Whether any listener is registered |
| `getListenerCount()` | Number of registered listeners |
| `forEachListener( callback )` | Invokes `callback` once per listener — used internally by [`TinyProperty`](/api/axon/tiny-property) |
| `dispose()` | Removes all listeners |

::: tip TinyEmitter is what Emitter is built from
`Emitter` is a `TinyEmitter` plus PhET-iO `tandem`/`parameters` options and `phetioReadOnly` bookkeeping — the actual `emit()`/`addListener()` mechanics (including the `'stack'` vs. `'queue'` reentrancy handling) live entirely in `TinyEmitter`. Use `Emitter` for anything that needs a `tandem` for the data stream or PhET-iO API docs; use `TinyEmitter` for internal plumbing (as [`TinyProperty`](/api/axon/tiny-property), `TinyForwardingProperty`, and `TinyStaticProperty` all do) where allocating that metadata on every instance would be wasted memory.
:::


========================================================================
Page: TinyProperty
URL: https://veillette.github.io/Almanach/api/axon/tiny-property
Source: docs/api/axon/tiny-property.md
Category: API | Tags: axon, TinyProperty, Property, performance | Status: verified
========================================================================

# TinyProperty

`TinyProperty<T>` (from `scenerystack/axon`) is a lightweight observable value wrapper that implements enough of the `Property` interface (`.value`, `.get()`/`.set()`, `link()`/`lazyLink()`/`unlink()`) to be used interchangeably in many places, but without [`Property`](/api/axon/property)'s validation, PhET-iO instrumentation, or `reset()`/`initialValue` bookkeeping. It directly extends [`TinyEmitter`](/api/axon/tiny-emitter) rather than composing one, specifically to save memory — scenery uses a `TinyProperty` for every Node's dozens of internal state values (`opacityProperty`, `visibleProperty`'s underlying storage, `pickableProperty`, etc.), so the per-instance overhead matters at that scale.

```ts
import { TinyProperty } from 'scenerystack/axon';

const opacityProperty = new TinyProperty( 1 );

opacityProperty.link( opacity => console.log( 'opacity:', opacity ) ); // logs "opacity: 1"
opacityProperty.value = 0.5;                                          // logs "opacity: 0.5"
```

## Constructor

```ts
new TinyProperty<T>(
  value: T,
  onBeforeNotify?: TinyEmitterOptions<...>['onBeforeNotify'] | null,
  hasListenerOrderDependencies?: boolean | null,
  reentrantNotificationStrategy?: 'stack' | 'queue' | null,
  disableListenerLimit?: boolean | null
)
```

The trailing four parameters are forwarded straight to the underlying [`TinyEmitter`](/api/axon/tiny-emitter) — `TinyProperty` itself only adds the first `value` argument. Unlike plain `TinyEmitter` (which defaults to `'stack'`), `TinyProperty` defaults `reentrantNotificationStrategy` to `'queue'`, so that if a listener changes the value again while still notifying (a → b, and a listener sets b → c), all listeners see the a→b change in order before any b→c notification begins.

## Methods and members

| Member | Effect |
| --- | --- |
| `value` (getter/setter) | Reads or writes the current value; setting is a no-op if the new value `areValuesEqual` the old one |
| `get()` / `set( value )` | Same as `.value`, provided as explicit methods for hot inner loops |
| `link( listener )` | Adds a listener and immediately calls it with `( value, null, this )` |
| `lazyLink( listener )` | Adds a listener without an immediate callback |
| `unlink( listener )` / `unlinkAll()` | Removes one or all listeners |
| `linkAttribute( object, attributeName )` | Sets `object[attributeName] = value` whenever the value changes |
| `valueComparisonStrategy` | Get/set the equality strategy (defaults to `'reference'`) used by `areValuesEqual` to decide whether to notify |
| `isSettable()` | Always returns `true` for `TinyProperty` |
| `dispose()` | Unlinks all listeners, then disposes the underlying `TinyEmitter` |

::: warning Not validated, not instrumented, no reset
`TinyProperty` has no `validValues`/`valueType`/`isValidValue` checking, no `tandem`, and no `initialValue`/`reset()` — assigning any value of the declared type always succeeds silently. It exists purely as a memory-lean building block for framework internals (scenery Node state, [`DynamicProperty`](/api/axon/dynamic-property)'s internal wrapping, [`MappedProperty`](/api/axon/unit-conversion-property)). For simulation model state that simulation-author code creates directly, use [`Property`](/api/axon/property) (or a typed subclass) instead — the safety and PhET-iO support are almost always worth the extra bytes.
:::


========================================================================
Page: UnitConversionProperty
URL: https://veillette.github.io/Almanach/api/axon/unit-conversion-property
Source: docs/api/axon/unit-conversion-property.md
Category: API | Tags: axon, UnitConversionProperty, MappedProperty, Property, units | Status: verified
========================================================================

# UnitConversionProperty

`UnitConversionProperty` (from `scenerystack/axon`) is a `MappedProperty<number, number>` (itself built on [`DynamicProperty`](/api/axon/dynamic-property)) specialized for the single most common numeric-derivation need: showing the same underlying quantity in different units. Give it a source Property and a `factor`, and it produces a new `number` Property that stays in sync in both directions — including tracking the source's `Range`, if it has one.

```ts
import { UnitConversionProperty, NumberProperty } from 'scenerystack/axon';
import { Range } from 'scenerystack/dot';

const metersProperty = new NumberProperty( 0.5, { range: new Range( 0, 1 ) } );
const centimetersProperty = new UnitConversionProperty( metersProperty, { factor: 100 } );

centimetersProperty.value; // 50
centimetersProperty.range; // Range( 0, 100 ) — derived from metersProperty's range

metersProperty.value = 0.25;
centimetersProperty.value; // 25 — one-way sync happens automatically

centimetersProperty.value = 100; // bidirectional by default
metersProperty.value; // 1
```

## Constructor

```ts
new UnitConversionProperty( property: TReadOnlyProperty<number> | TRangedProperty, providedOptions: UnitConversionPropertyOptions )
```

`property` may be any numeric Property, or specifically a ranged one (like [`NumberProperty`](/api/axon/number-property)) to get automatic range conversion.

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `factor` | — | **Required.** The multiplicative factor from the source's units to this Property's units — `this.value === factor * property.value` |
| `bidirectional` | `true` | Unlike the general `MappedProperty`/`DynamicProperty` (which default to one-way), `UnitConversionProperty` defaults to two-way sync, since `map`/`inverseMap` are always derivable from `factor` |
| `map` / `inverseMap` | derived from `factor` | Overridable, but normally left alone — `UnitConversionProperty` builds `value => value * factor` and `value => value / factor` for you |

## Members

| Member | Effect |
| --- | --- |
| `range` (getter/setter) | The converted `Range`, tracked automatically from the source Property's `rangeProperty` if it has one (otherwise a default unbounded range) |
| `rangeProperty` | The underlying `Property<Range>` backing `.range` |

::: warning Setting `.range` directly is not yet bidirectional
The doc comment on the source is explicit about this: assigning `centimetersProperty.range = ...` updates this Property's own `rangeProperty` but does **not** push a converted range back onto the source Property's range. Range synchronization only flows from the source outward; only the `.value` sync is bidirectional.
:::


========================================================================
Page: Validation and validate
URL: https://veillette.github.io/Almanach/api/axon/validation
Source: docs/api/axon/validation.md
Category: API | Tags: axon, Validation, validate, Property | Status: complete
========================================================================

# Validation and validate

`Validation` (from `scenerystack/axon`) is a static-methods-only class defining the shared "validator" object schema — `{ valueType, validValues, isValidValue, phetioType, valueComparisonStrategy, validators }` — that [`Property`](/api/axon/property) accepts directly as construction options, and that is reused verbatim by `Emitter`'s parameter validation. `validate()` is a small assertion-only wrapper around `Validation.getValidationError()`: with assertions enabled it throws when a value doesn't satisfy a validator, and is a no-op otherwise. You'll rarely call either directly — mostly you pass `valueType`/`validValues`/`isValidValue` straight into a `Property` constructor — but understanding this layer explains exactly what those options accept and how they combine.

```ts
import { Validation } from 'scenerystack/axon';

const validator = { valueType: 'number', isValidValue: ( n: number ) => n >= 0 };

Validation.isValueValid( 5, validator );     // true
Validation.isValueValid( -1, validator );    // false
Validation.getValidationError( -1, validator ); // 'value failed isValidValue: -1'
```

## The `Validator<T>` shape

This is the same object shape accepted by `Property`'s second constructor argument (see [Property's options](/api/axon/property#options)):

| Key | Effect |
| --- | --- |
| `valueType` | A primitive type string (`'number'`, `'string'`, `'boolean'`, `'function'`), a constructor (checked via `instanceof`), `null`, or an array of any of those (value must match at least one) |
| `validValues` | A fixed array of allowed values; membership is checked according to `valueComparisonStrategy` |
| `valueComparisonStrategy` | How `validValues` membership (and Property change-detection) compares values: `'reference'` (default, `===`), `'equalsFunction'` (calls `.equals()` on both sides), `'lodashDeep'` (`_.isEqual`), or a custom `(a, b) => boolean` |
| `isValidValue` | A custom `( value ) => boolean` predicate, checked in addition to any `valueType`/`validValues` |
| `phetioType` | An `IOType` whose own `.validator` is checked as well — lets PhET-iO type definitions double as value validators |
| `validators` | An array of nested `Validator` objects, all of which must pass |

A validator object must specify at least one of these keys — `Validation.getValidatorValidationError()` (which `Validation.validateValidator()` asserts against) rejects an empty `{}`.

## Static API

| Method | Effect |
| --- | --- |
| `Validation.isValueValid( value, validator, options? )` | `true`/`false` — whether `value` satisfies `validator` |
| `Validation.getValidationError( value, validator, options? )` | `null` if valid, otherwise a human-readable string describing the failure |
| `Validation.validateValidator( validator )` | Asserts that the *validator object itself* is well-formed (not that a value matches it) |
| `Validation.containsValidatorKey( obj )` | Whether `obj` has at least one recognized validator key — used internally to detect "was a validator even supplied" |
| `Validation.equalsForValidationStrategy( a, b, strategy )` | The comparison primitive backing `valueComparisonStrategy`, usable standalone |
| `Validation.VALIDATOR_KEYS` | The list of recognized keys, e.g. for `_.pick`-ing a validator out of a larger options object (this is exactly how `ReadOnlyProperty` extracts its `valueValidator` from constructor options) |
| `validate( value, validator, options? )` | Assertion-only convenience: throws (with assertions enabled) if `value` fails `validator`; otherwise a no-op |

::: warning `validate()` is deprecated in favor of calling `Validation` directly
The source marks `validate()` `@deprecated`, recommending a direct assertion using `Validation.getValidationError()` instead — e.g. `assert && assert( Validation.isValueValid( value, validator ) )`. New code documenting or building on this layer should prefer `Validation`'s static methods; `validate()` remains only for existing call sites.
:::


========================================================================
Page: AreaPlot
URL: https://veillette.github.io/Almanach/api/bamboo/area-plot
Source: docs/api/bamboo/area-plot.md
Category: API | Tags: bamboo, AreaPlot, chart, plot | Status: complete
========================================================================

# AreaPlot

`AreaPlot` (from `scenerystack/bamboo`) combines the look of a [`LinePlot`](/api/bamboo/line-plot) with the shading of a [`BarPlot`](/api/bamboo/bar-plot): it renders a `(Vector2 | null)[]` dataset as a filled region bounded above by the line through the data and below by a horizontal `baseline` value. It extends `scenerystack/scenery`'s `Path`, rebuilding its `Shape` whenever the dataset, `baseline`, or the chart transform changes. As with `LinePlot`, a `null` entry in the dataset closes off the current shaded region and starts a new one on the next non-null point, rather than plotting a point at the origin.

```ts
import { ChartTransform, AreaPlot } from 'scenerystack/bamboo';
import { Range, Vector2 } from 'scenerystack/dot';
```

## A minimal example

```ts
const chartTransform = new ChartTransform( {
  viewWidth: 400,
  viewHeight: 200,
  modelXRange: new Range( 0, 10 ),
  modelYRange: new Range( -1, 1 )
} );

const dataSet: ( Vector2 | null )[] = [];
for ( let x = 0; x <= 10; x += 0.1 ) {
  dataSet.push( new Vector2( x, Math.sin( x ) ) );
}

const areaPlot = new AreaPlot( chartTransform, dataSet, {
  baseline: 0,
  fill: 'rgba(0,100,255,0.4)'
} );
```

## Constructor

```ts
new AreaPlot( chartTransform: ChartTransform, dataSet: ( Vector2 | null )[], providedOptions?: AreaChartOptions )
```

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `baseline` | `0` | The y-value (in model coordinates) that forms the foundation of the shaded region — each shaded run of points is closed by dropping straight down to this value at its first and last x |
| `fill` (inherited `PathOptions`) | `'black'` | Fill color of the shaded region |

## Methods

| Member | Description |
| --- | --- |
| `dataSet` | `(Vector2 \| null)[]` — public field. Safe to read directly; if you mutate it in place, you're responsible for calling `update()` yourself |
| `baseline` | `number` — public field, mirrors the `baseline` option. Same caveat as `dataSet` if mutated directly |
| `setDataSet( dataSet )` | Replaces the dataset and immediately calls `update()` |
| `setBaseline( baseline )` | Replaces the baseline and immediately calls `update()` |
| `update()` | Recomputes the shaded `Shape` from the current `dataSet` and `baseline`; called automatically on construction and whenever the `ChartTransform`'s `changedEmitter` fires |
| `dispose()` | Removes the `chartTransform.changedEmitter` listener before calling `Path.dispose()` |

::: tip Each run of non-null points closes independently at the baseline
`AreaPlot` walks the dataset and, on hitting a `null` (or the end of the array), draws a line straight down to `baseline` at the last point's x-coordinate and closes that subpath — then starts a fresh shaded region at the next non-null point. This is what makes `null` entries produce separate shaded islands rather than one continuous fill with a hole punched through the gap, and it's the same convention `LinePlot` uses for line segments, just with an extra close-to-baseline step.
:::


========================================================================
Page: AxisLine and AxisArrowNode
URL: https://veillette.github.io/Almanach/api/bamboo/axis-nodes
Source: docs/api/bamboo/axis-nodes.md
Category: API | Tags: bamboo, AxisLine, AxisArrowNode, chart, axis | Status: verified
========================================================================

# AxisLine and AxisArrowNode

Bamboo has no single `AxisNode` — instead, `scenerystack/bamboo` exports two interchangeable axis-drawing Nodes, both driven by a `ChartTransform` plus an `Orientation` (`scenerystack/phet-core`) saying which axis they represent:

- **`AxisLine`** extends `scenerystack/scenery`'s `Line` — a plain stroked line, no arrowheads.
- **`AxisArrowNode`** extends `scenerystack/scenery-phet`'s `ArrowNode` — the same idea, but double-headed by default, for charts that want to emphasize the axis extending indefinitely.

Both reposition themselves whenever the chart transform changes, and both auto-hide (`setVisible( false )`) when their position would fall outside the transform's current view bounds — so an axis pinned at, say, `x = 0` disappears cleanly if the visible model range pans away from zero.

```ts
import { ChartTransform, AxisLine, AxisArrowNode, ChartRectangle } from 'scenerystack/bamboo';
import { Orientation } from 'scenerystack/phet-core';
import { Range } from 'scenerystack/dot';
```

## A minimal example

```ts
const chartTransform = new ChartTransform( {
  viewWidth: 400,
  viewHeight: 200,
  modelXRange: new Range( -5, 5 ),
  modelYRange: new Range( -1, 1 )
} );

const chartRectangle = new ChartRectangle( chartTransform, { stroke: 'gray' } );

// A vertical AxisLine (the "y axis"), positioned at model x = 0.
const yAxis = new AxisLine( chartTransform, Orientation.VERTICAL, {
  value: 0
} );

// A horizontal AxisArrowNode (the "x axis"), positioned at model y = 0.
const xAxis = new AxisArrowNode( chartTransform, Orientation.HORIZONTAL, {
  value: 0
} );
```

## Constructors

```ts
new AxisLine( chartTransform: ChartTransform, axisOrientation: Orientation, providedOptions?: AxisLineOptions )
new AxisArrowNode( chartTransform: ChartTransform, axisOrientation: Orientation, providedOptions?: AxisArrowNodeOptions )
```

## Options

| Option | `AxisLine` default | `AxisArrowNode` default | Effect |
| --- | --- | --- | --- |
| `value` | `0` | `0` | The position of the axis, in model coordinates **on the opposite axis** from `axisOrientation` (see tip below) |
| `extension` | `0` | `20` | How far past the `ChartRectangle`'s edge (in view coordinates) the line/arrow is drawn |
| `stroke` / `lineWidth` (`AxisLine`, from `LineOptions`) | `'black'` / `2` | — | Line styling |
| `doubleHead` / `headHeight` / `headWidth` / `tailWidth` (`AxisArrowNode`, from `ArrowNodeOptions`) | — | `true` / `10` / `10` / `2` | Arrowhead styling |

## Methods

Both classes share the same shape: they recompute their geometry in a private `update()` (called on construction and on every `chartTransform.changedEmitter` firing), and expose only:

| Member | Description |
| --- | --- |
| `dispose()` | Removes the `chartTransform.changedEmitter` listener before calling the superclass's `dispose()` |

::: tip `value` is a coordinate on the *opposite* axis
For a `VERTICAL` `AxisLine`/`AxisArrowNode` (a vertical line representing the "y axis"), `value` is an **x** model coordinate — it's where that vertical line crosses the horizontal axis. Symmetrically, a `HORIZONTAL` axis's `value` is a **y** model coordinate. This is why the default `value: 0` conventionally draws each axis through the origin, and why changing `value` moves the axis sideways/vertically rather than stretching it.
:::


========================================================================
Page: BarPlot
URL: https://veillette.github.io/Almanach/api/bamboo/bar-plot
Source: docs/api/bamboo/bar-plot.md
Category: API | Tags: bamboo, BarPlot, chart, plot | Status: verified
========================================================================

# BarPlot

`BarPlot` (from `scenerystack/bamboo`) shows numerical data (an x-value plus a height) as one `Rectangle` per point, extending `scenerystack/scenery`'s `Node` rather than `Path` since it manages a pool of child `Rectangle`s instead of a single `Shape`. Each bar's tail sits at a shared `barTailValue` (the baseline, e.g. `y = 0`) and its tip is the data point itself, so bars can grow up or down from the baseline. It only supports numeric x-values — not categorical data.

```ts
import { ChartTransform, BarPlot } from 'scenerystack/bamboo';
import { Range, Vector2 } from 'scenerystack/dot';
```

## A minimal example

```ts
const chartTransform = new ChartTransform( {
  viewWidth: 300,
  viewHeight: 200,
  modelXRange: new Range( 0, 5 ),
  modelYRange: new Range( 0, 10 )
} );

const dataSet = [
  new Vector2( 0, 3 ),
  new Vector2( 1, 7 ),
  new Vector2( 2, 5 ),
  new Vector2( 3, 9 ),
  new Vector2( 4, 2 )
];

const barPlot = new BarPlot( chartTransform, dataSet, {
  barWidth: 20,
  pointToPaintableFields: point => ( { fill: point.y > 5 ? 'orange' : 'gray' } )
} );
```

## Constructor

```ts
new BarPlot( chartTransform: ChartTransform, dataSet: Vector2[], providedOptions?: BarPlotOptions )
```

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `barWidth` | `10` | Width of each bar, in view coordinates |
| `barTailValue` | `0` | The model-coordinate baseline each bar's tail is drawn from |
| `pointToPaintableFields` | `() => ({ fill: 'black' })` | Maps a data point to `PaintableOptions` (e.g. `{ fill, stroke }`) applied to that bar's `Rectangle` |

## Methods

| Member | Description |
| --- | --- |
| `dataSet` | `Vector2[]` — public field. Mutate in place only if you also call `update()` yourself |
| `rectangles` | `Rectangle[]` — the current child rectangles, one per data point, kept in sync by `update()` |
| `setDataSet( dataSet )` | Replaces the dataset and calls `update()` |
| `update()` | Adds/removes `Rectangle` children to match `dataSet.length`, repositions/resizes each one from the chart transform, and re-applies `pointToPaintableFields` |
| `dispose()` | Removes the `chartTransform.changedEmitter` listener before calling `Node.dispose()` |

::: warning `pointToPaintableFields` is restricted to paintable keys
`update()` asserts that every key returned by `pointToPaintableFields` is one of the `Rectangle`'s default paintable options (`fill`, `stroke`, and similar) before calling `.mutate()` with it — this guards against accidentally passing an option (like `children` or a layout option) that would be unsafe to `mutate()` onto an internally-managed `Rectangle`. Stick to fill/stroke-style fields.
:::


========================================================================
Page: CanvasLinePlot
URL: https://veillette.github.io/Almanach/api/bamboo/canvas-line-plot
Source: docs/api/bamboo/canvas-line-plot.md
Category: API | Tags: bamboo, CanvasLinePlot, ChartCanvasNode, chart, plot, canvas, performance | Status: complete
========================================================================

# CanvasLinePlot

`CanvasLinePlot` (from `scenerystack/bamboo`) draws the same kind of `(Vector2 | null)[]` dataset as [`LinePlot`](/api/bamboo/line-plot) — straight segments between consecutive points, with `null` entries creating gaps — but paints directly to a `CanvasRenderingContext2D` instead of building a scenery `Shape`/`Path`. It is **not** a `Node` itself: `CanvasLinePlot` extends the abstract `CanvasPainter` base class, and one or more painters are handed to a `ChartCanvasNode` (which *is* the actual scenery `Node`, extending `CanvasNode`) that iterates its `painters` array and calls each one's `paintCanvas()` on every repaint.

```ts
import { ChartTransform, ChartCanvasNode, CanvasLinePlot } from 'scenerystack/bamboo';
import { Range, Vector2 } from 'scenerystack/dot';
```

## A minimal example

```ts
const chartTransform = new ChartTransform( {
  viewWidth: 400,
  viewHeight: 200,
  modelXRange: new Range( 0, 1000 ),
  modelYRange: new Range( -1, 1 )
} );

// 10,000 points -- too many for per-point scenery Nodes to stay responsive.
const dataSet: ( Vector2 | null )[] = [];
for ( let x = 0; x <= 1000; x += 0.1 ) {
  dataSet.push( new Vector2( x, Math.sin( x ) ) );
}

const canvasLinePlot = new CanvasLinePlot( chartTransform, dataSet, {
  stroke: 'blue',
  lineWidth: 1
} );

// The ChartCanvasNode is what actually gets added to the scene graph.
const chartCanvasNode = new ChartCanvasNode( chartTransform, [ canvasLinePlot ] );
```

## Constructor

```ts
new CanvasLinePlot( chartTransform: ChartTransform, dataSet: ( Vector2 | null )[], providedOptions?: CanvasLinePlotOptions )
```

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `stroke` | `'black'` | CSS color string or `Color`; validated with `Color.isCSSColorString()` when assertions are enabled |
| `lineWidth` | `1` | Stroke width in view (pixel) coordinates |
| `lineDash` | `[]` (solid) | Passed straight through to `context.setLineDash()` |

## Methods

| Member | Description |
| --- | --- |
| `dataSet` | `(Vector2 \| null)[]` — public field, read directly by `paintCanvas()`. Mutating it (or calling `setDataSet()`/`setStroke()`) does **not** trigger a repaint by itself |
| `setDataSet( dataSet )` | Replaces the dataset |
| `setStroke( stroke )` / `stroke` (setter) | Replaces the stroke |
| `paintCanvas( context )` | Called by the owning `ChartCanvasNode` on every repaint; walks `dataSet`, moving to the next point after each `null` and line-ing to it otherwise |
| `dispose()` | Marks the painter disposed; asserts if called twice |

::: warning You must call `update()` on the `ChartCanvasNode` yourself
Unlike `LinePlot`, which listens to `chartTransform.changedEmitter` and rebuilds its own `Shape` automatically, `CanvasLinePlot` has no such wiring — it's a passive painter, not a `Node`. `ChartCanvasNode` is the one that listens to `changedEmitter` and calls `this.invalidatePaint()` for *its own* size/transform changes, but if you mutate a painter's `dataSet`, `lineWidth`, `lineDash`, or call `setStroke()` after construction, you must call `update()` on the owning `ChartCanvasNode` yourself (or `setPainters()`, if you're also changing which painters it holds) — nothing does it for you.
:::

Reach for `CanvasLinePlot` (plus `ChartCanvasNode`) only once profiling shows a `LinePlot`'s per-point scenery drawable overhead is the bottleneck — typically datasets in the thousands-of-points range redrawn every frame. For anything smaller, `LinePlot`'s automatic redraw wiring and ordinary scenery `Path` semantics (hit testing, easy composition with other Nodes) are simpler to work with.


========================================================================
Page: ChartTransform
URL: https://veillette.github.io/Almanach/api/bamboo/chart-transform
Source: docs/api/bamboo/chart-transform.md
Category: API | Tags: bamboo, ChartTransform, coordinates, chart | Status: verified
========================================================================

# ChartTransform

`ChartTransform` (from `scenerystack/bamboo`) is a plain (non-`Node`) object that defines a chart's model-coordinate ranges (`modelXRange`, `modelYRange`) and view-coordinate size (`viewWidth`, `viewHeight`), and converts between the two. Every bamboo rendering primitive — `LinePlot`, `BarPlot`, `ScatterPlot`, `ChartRectangle`, `AxisLine`/`AxisArrowNode`, grid and tick sets — takes a `ChartTransform` in its constructor and listens to its `changedEmitter` so the whole chart redraws together when the transform changes (e.g. on a resize or a pan/zoom).

```ts
import { ChartTransform, ChartRectangle, LinePlot } from 'scenerystack/bamboo';
import { Range, Vector2 } from 'scenerystack/dot';
```

## A minimal example

```ts
const chartTransform = new ChartTransform( {
  viewWidth: 400,
  viewHeight: 200,
  modelXRange: new Range( 0, 10 ),
  modelYRange: new Range( -1, 1 )
} );

// ChartRectangle gives the chart a visible background/border sized to the transform.
const chartRectangle = new ChartRectangle( chartTransform, {
  fill: 'white',
  stroke: 'black'
} );

const dataSet = [];
for ( let x = 0; x <= 10; x += 0.1 ) {
  dataSet.push( new Vector2( x, Math.sin( x ) ) );
}
const linePlot = new LinePlot( chartTransform, dataSet, { stroke: 'blue' } );

// Later, e.g. on a layout resize:
chartTransform.setViewWidth( 600 );
// -> chartRectangle and linePlot both redraw automatically via changedEmitter.
```

## Constructor

```ts
new ChartTransform( providedOptions?: ChartTransformOptions )
```

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `viewWidth` | `100` | Width of the chart in view (pixel) coordinates |
| `viewHeight` | `100` | Height of the chart in view (pixel) coordinates |
| `modelXRange` | `new Range( -1, 1 )` | Range of the x axis, in model coordinates |
| `modelYRange` | `new Range( -1, 1 )` | Range of the y axis, in model coordinates |
| `modelXRangeInverted` | `false` | Flips which view edge corresponds to `modelXRange.min` |
| `modelYRangeInverted` | `false` | Flips which view edge corresponds to `modelYRange.min` |
| `xTransform` | identity `Transform1` | Nonlinear model-to-view scaling function for x (e.g. for a log axis), applied before the linear view-range mapping |
| `yTransform` | identity `Transform1` | Nonlinear model-to-view scaling function for y |

## Methods

| Member | Description |
| --- | --- |
| `modelToView( orientation, value )` / `modelToViewX/Y( value )` | Converts a scalar model coordinate to a view coordinate along the given `Orientation` (`scenerystack/phet-core`) |
| `modelToViewXY( x, y )` / `modelToViewPosition( Vector2 )` | Converts a model point to a view `Vector2` |
| `modelToViewDelta/DeltaX/DeltaY/DeltaXY` | Converts a model-space *delta* (not an absolute position) to view space |
| `viewToModel*` | The inverse of each `modelToView*` method |
| `setViewWidth( w )` / `setViewHeight( h )` | Updates the view size and fires `changedEmitter` if it actually changed |
| `setModelXRange( range )` / `setModelYRange( range )` | Updates a model range and fires `changedEmitter` if it actually changed |
| `setXTransform( transform )` / `setYTransform( transform )` | Swaps the nonlinear scaling function for an axis |
| `getModelRange( orientation )` | Returns `modelXRange` or `modelYRange` for the given orientation |
| `forEachSpacing( orientation, spacing, origin, clippingType, callback )` | Iterates evenly-spaced model/view coordinate pairs across a range — what `TickMarkSet`/`GridLineSet` use internally |
| `changedEmitter` | `TEmitter` — fires whenever any dimension, range, or transform changes; plots/axes/grids listen to this to know when to redraw |
| `dispose()` | Disposes `changedEmitter` |

::: warning Mutate through the setters, not the public fields
`viewWidth`, `modelXRange`, etc. are public fields (readable directly, e.g. by a plot's `update()`), but they are also directly *writable* — assigning `chartTransform.viewWidth = 600` will **not** fire `changedEmitter`, so nothing downstream redraws. Always go through `setViewWidth()`, `setModelXRange()`, `setXTransform()`, and friends when changing a `ChartTransform` after construction.
:::


========================================================================
Page: GridLineSet, TickMarkSet, and TickLabelSet
URL: https://veillette.github.io/Almanach/api/bamboo/gridlines-and-tick-marks
Source: docs/api/bamboo/gridlines-and-tick-marks.md
Category: API | Tags: bamboo, GridLineSet, TickMarkSet, TickLabelSet, chart, axis | Status: complete
========================================================================

# GridLineSet, TickMarkSet, and TickLabelSet

`GridLineSet`, `TickMarkSet`, and `TickLabelSet` (all from `scenerystack/bamboo`) are the three repeating-decoration primitives every bamboo chart uses alongside [`ChartTransform`](/api/bamboo/chart-transform) and the [axis Nodes](/api/bamboo/axis-nodes): they draw evenly-spaced lines, tick marks, and tick labels respectively, all driven by the same `(chartTransform, axisOrientation, spacing)` triple. Internally, each one calls `chartTransform.forEachSpacing()` to walk the model/view coordinate pairs at that spacing and clipping behavior, then builds its `Shape` (or, for `TickLabelSet`, its `Text` children) from those pairs. All three listen to `changedEmitter` and redraw automatically.

```ts
import { ChartTransform, GridLineSet, TickMarkSet, TickLabelSet } from 'scenerystack/bamboo';
import { Orientation } from 'scenerystack/phet-core';
import { Range } from 'scenerystack/dot';
```

## A minimal example

```ts
const chartTransform = new ChartTransform( {
  viewWidth: 400,
  viewHeight: 200,
  modelXRange: new Range( 0, 10 ),
  modelYRange: new Range( -1, 1 )
} );

// Vertical lines every 1 model unit along x.
const verticalGridLines = new GridLineSet( chartTransform, Orientation.VERTICAL, 1, {
  stroke: 'lightGray'
} );

// Tick marks along the x axis (at model y = 0), every 1 unit.
const xTickMarks = new TickMarkSet( chartTransform, Orientation.HORIZONTAL, 1, {
  edge: 'min'
} );

// Numeric labels below the x tick marks.
const xTickLabels = new TickLabelSet( chartTransform, Orientation.HORIZONTAL, 1, {
  edge: 'min'
} );
```

All three constructors share the same shape:

```ts
new GridLineSet( chartTransform: ChartTransform, axisOrientation: Orientation, spacing: number, providedOptions?: GridLineSetOptions )
new TickMarkSet( chartTransform: ChartTransform, axisOrientation: Orientation, spacing: number, providedOptions?: TickMarkSetOptions )
new TickLabelSet( chartTransform: ChartTransform, axisOrientation: Orientation, spacing: number, providedOptions?: TickLabelSetOptions )
```

`axisOrientation` is the axis the ticks/gridlines *progress along* — a `HORIZONTAL` set has ticks marching along x (at x=0,1,2,…), producing vertical gridlines; a `VERTICAL` set marches along y and produces horizontal gridlines. `spacing` is in model coordinates.

## Options

| Option | Applies to | Default | Effect |
| --- | --- | --- | --- |
| `value` | all three | `0` | Model coordinate on the *opposite* axis where the ticks/gridlines are positioned (mutually exclusive with `edge`) |
| `edge` | all three | `null` | `'min'` or `'max'` pins the ticks/gridlines to that edge of the chart instead of a `value` |
| `origin` | all three | `0` | Model-coordinate offset the spacing is measured from |
| `skipCoordinates` | `TickMarkSet`, `TickLabelSet` | `[]` | Model coordinates to skip — typically `[0]`, to avoid drawing a redundant tick where the axes cross |
| `extent` | `TickMarkSet`, `TickLabelSet` | `10` (`TickMarkSet.DEFAULT_EXTENT`) | Length of each tick mark in view coordinates (or, for `TickLabelSet`, the extent an implied tick would have, used only for label positioning) |
| `clippingType` | all three | `'strict'` | Rounding/clipping behavior for `ChartTransform.forEachSpacing()` — whether partially-out-of-range ticks are included |
| `createLabel` | `TickLabelSet` | `value => new Text( toFixed( value, 1 ), { fontSize: 12 } )` | Builds the label `Node` for a given model coordinate; returning `null` omits that label |
| `positionLabel` | `TickLabelSet` | positions below (`HORIZONTAL`) or to the left (`VERTICAL`) of the tick | Positions a created label relative to its tick's bounds |

## Methods

| Member | Description |
| --- | --- |
| `setSpacing( spacing )` / `getSpacing()` | Replaces the spacing (a no-op if unchanged) and recomputes; shared across all three |
| `getSpacingBorders()` | Returns the `Range` of model coordinates the current spacing/origin/clippingType actually produces ticks for; shared across all three |
| `setCreateLabel( createLabel )` | `TickLabelSet` only — swaps the label-creation function and calls `invalidateTickLabelSet()` |
| `invalidateTickLabelSet()` | `TickLabelSet` only — disposes every cached label and rebuilds, needed if `createLabel`'s *output* for an already-seen value should change (e.g. switching from numeric to symbolic labels) |
| `dispose()` | Removes the `chartTransform.changedEmitter` listener before calling the superclass's `dispose()` |

::: tip `TickLabelSet` caches label Nodes by model coordinate
`TickLabelSet` keeps a `Map` from model coordinate to the `Node` last built by `createLabel`, and reuses it across `update()` calls rather than reconstructing every label on every transform change — labels are only rebuilt when a coordinate scrolls out of range and a different one scrolls in. If `createLabel`'s logic depends on external state (not just the coordinate value), call `invalidateTickLabelSet()` after that state changes, or stale labels will stick around.
:::


========================================================================
Page: LinearEquationPlot
URL: https://veillette.github.io/Almanach/api/bamboo/linear-equation-plot
Source: docs/api/bamboo/linear-equation-plot.md
Category: API | Tags: bamboo, LinearEquationPlot, chart, plot | Status: complete
========================================================================

# LinearEquationPlot

`LinearEquationPlot` (from `scenerystack/bamboo`) renders the line described by a slope `m` and y-intercept `b` — `y = mx + b` — rather than a dataset of discrete points. Unlike [`LinePlot`](/api/bamboo/line-plot), which connects an array of `(Vector2 | null)` samples, `LinearEquationPlot` only needs the two numbers describing the equation: it extends `scenerystack/scenery`'s `Line` and recomputes its endpoints to span the chart transform's full `modelXRange` (or `modelYRange`, for a vertical line) whenever `m`, `b`, or the transform changes. Passing `m: Infinity` or `m: -Infinity` draws a vertical line instead of throwing, which is the idiomatic way to represent an undefined slope.

```ts
import { ChartTransform, LinearEquationPlot } from 'scenerystack/bamboo';
import { Range } from 'scenerystack/dot';
```

## A minimal example

```ts
const chartTransform = new ChartTransform( {
  viewWidth: 400,
  viewHeight: 200,
  modelXRange: new Range( -10, 10 ),
  modelYRange: new Range( -10, 10 )
} );

// y = 2x + 1, spanning the chart's full model x-range.
const linearEquationPlot = new LinearEquationPlot( chartTransform, 2, 1, {
  stroke: 'red',
  lineWidth: 2
} );

// A vertical line at x = 3.
const verticalLine = new LinearEquationPlot( chartTransform, Infinity, 3 );
```

## Constructor

```ts
new LinearEquationPlot( chartTransform: ChartTransform, m: number, b: number, providedOptions?: LinearEquationPlotOptions )
```

`m` is the slope (`Infinity`/`-Infinity` for a vertical line), and `b` is the y-intercept. `LinearEquationPlotOptions` adds no options of its own beyond whatever it inherits from `LineOptions` (e.g. `stroke`, `lineWidth`); `stroke` defaults to `'black'` and `lineWidth` defaults to `1`.

## Methods

| Member | Description |
| --- | --- |
| `m` (getter/setter) | The slope. Setting it calls `setSlope()`, which recomputes the endpoints |
| `setSlope( m )` | Replaces the slope and redraws |
| `b` (getter/setter) | The y-intercept. Setting it calls `setYIntercept()`, which recomputes the endpoints |
| `setYIntercept( b )` | Replaces the y-intercept and redraws |
| `solve( x )` | Returns `m * x + b` — the y-value the equation predicts for a given x, without touching the rendered line |
| `dispose()` | Removes the `chartTransform.changedEmitter` listener before calling `Line.dispose()` |

::: tip Use it for reference lines and fits, not for arbitrary curves
Because `LinearEquationPlot` always spans the transform's entire model range, it's a natural fit for things a dataset would be overkill for: a best-fit line overlaid on a `ScatterPlot`, a target/threshold line, or a y = x reference line. For anything that isn't representable as a single global slope and intercept — a curve, a piecewise function, or real sampled data — reach for [`LinePlot`](/api/bamboo/line-plot) instead.
:::


========================================================================
Page: LinePlot
URL: https://veillette.github.io/Almanach/api/bamboo/line-plot
Source: docs/api/bamboo/line-plot.md
Category: API | Tags: bamboo, LinePlot, chart, plot | Status: verified
========================================================================

# LinePlot

`LinePlot` (from `scenerystack/bamboo`) renders a dataset of `(Vector2 | null)[]` by connecting consecutive points with straight line segments, using a `ChartTransform` to convert each model-space point to view coordinates. It extends `scenerystack/scenery`'s `Path`, rebuilding its `Shape` whenever the dataset or the chart transform changes. A `null` entry breaks the line: `[ (0,0), (0,1), null, (0,2), (0,3) ]` draws two separate segments instead of three connected ones.

```ts
import { ChartTransform, LinePlot } from 'scenerystack/bamboo';
import { Range, Vector2 } from 'scenerystack/dot';
```

## A minimal example

```ts
const chartTransform = new ChartTransform( {
  viewWidth: 400,
  viewHeight: 200,
  modelXRange: new Range( 0, 10 ),
  modelYRange: new Range( -1, 1 )
} );

const dataSet: ( Vector2 | null )[] = [];
for ( let x = 0; x <= 10; x += 0.1 ) {
  dataSet.push( new Vector2( x, Math.sin( x ) ) );
}

const linePlot = new LinePlot( chartTransform, dataSet, {
  stroke: 'blue',
  lineWidth: 2
} );
```

## Constructor

```ts
new LinePlot( chartTransform: ChartTransform, dataSet: ( Vector2 | null )[], providedOptions?: LinePlotOptions )
```

`LinePlotOptions` adds no options of its own beyond whatever it inherits from `PathOptions` (e.g. `stroke`, `lineWidth`, `lineDash`); `stroke` defaults to `'black'`.

## Methods

| Member | Description |
| --- | --- |
| `dataSet` | `( Vector2 \| null )[]` — public field. Safe to read directly; if you mutate it in place (rather than calling `setDataSet`), you're responsible for calling `update()` yourself |
| `setDataSet( dataSet )` | Replaces the dataset and immediately calls `update()` |
| `update()` | Recomputes the line's `Shape` from the current `dataSet`; called automatically on construction and whenever the `ChartTransform`'s `changedEmitter` fires |
| `dispose()` | Removes the `chartTransform.changedEmitter` listener before calling `Path.dispose()` |

::: tip `null` entries create gaps, not zero-value points
Each `null` in `dataSet` starts a new, disconnected subpath on the next non-null point — it does not plot a point at the origin. This is the standard way to represent missing data or a discontinuous function on a bamboo chart, and it's the main behavioral difference from `ScatterPlot`, whose `dataSet` has no such gap mechanism.
:::


========================================================================
Page: ScatterPlot
URL: https://veillette.github.io/Almanach/api/bamboo/scatter-plot
Source: docs/api/bamboo/scatter-plot.md
Category: API | Tags: bamboo, ScatterPlot, chart, plot | Status: verified
========================================================================

# ScatterPlot

`ScatterPlot` (from `scenerystack/bamboo`) renders a `Vector2[]` dataset as one filled circle per point, using a `ChartTransform` to convert each model point to a view position. It extends `scenerystack/scenery`'s `Path`, building a single `Shape` containing one `circle()` subpath per data point. Unlike `LinePlot`, its dataset has no `null`-gap convention — non-finite points (`NaN` or infinite components) are simply skipped and draw nothing.

```ts
import { ChartTransform, ScatterPlot } from 'scenerystack/bamboo';
import { Range, Vector2 } from 'scenerystack/dot';
```

## A minimal example

```ts
const chartTransform = new ChartTransform( {
  viewWidth: 300,
  viewHeight: 300,
  modelXRange: new Range( 0, 10 ),
  modelYRange: new Range( 0, 10 )
} );

const dataSet = [];
for ( let i = 0; i < 50; i++ ) {
  dataSet.push( new Vector2( Math.random() * 10, Math.random() * 10 ) );
}

const scatterPlot = new ScatterPlot( chartTransform, dataSet, {
  radius: 3,
  fill: 'purple'
} );
```

## Constructor

```ts
new ScatterPlot( chartTransform: ChartTransform, dataSet: Vector2[], providedOptions?: ScatterPlotOptions )
```

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `radius` | `2` | Radius of each plotted circle, in view coordinates |
| `fill` (inherited `PathOptions`) | `'black'` | Fill color of the circles |

## Methods

| Member | Description |
| --- | --- |
| `dataSet` | `Vector2[]` — public field. Mutate in place only if you also call `update()` yourself |
| `setDataSet( dataSet )` | Replaces the dataset and calls `update()` |
| `update()` | Recomputes the circles' `Shape` from the current `dataSet`, skipping non-finite points |
| `dispose()` | Removes the `chartTransform.changedEmitter` listener before calling `Path.dispose()` |

::: warning `fill` and `stroke` together can render incorrectly on overlapping points
Because all circles are packed into one `Shape` on a single `Path`, if you set both `fill` and `stroke` to different colors, overlapping points will not composite the way separate individually-stroked circles would (this is a known upstream limitation, not a configuration mistake). If your data can produce overlapping points and the visual difference matters, prefer a fill-only or stroke-only style, or lay out separate `Circle` nodes instead of `ScatterPlot`.
:::


========================================================================
Page: Bounds2
URL: https://veillette.github.io/Almanach/api/dot/bounds2
Source: docs/api/dot/bounds2.md
Category: API | Tags: dot, Bounds2, bounds | Status: verified
========================================================================

# Bounds2

`Bounds2` (from `scenerystack/dot`) is an axis-aligned bounding box, stored as `minX`/`minY`/`maxX`/`maxY` (not `x`/`y`/`width`/`height`, though those are available as convenience getters). It's used constantly for layout bounds, drag bounds, hit-testing, and `Node.bounds`/`localBounds`.

```ts
import { Bounds2 } from 'scenerystack/dot';

const dragBounds = new Bounds2( 0, 0, 768, 504 );

dragBounds.width;                       // 768
dragBounds.center;                      // Vector2(384, 252)
dragBounds.containsCoordinates( 800, 10 ); // false — outside on the right

const clamped = dragBounds.closestPointTo( new Vector2( 900, 10 ) ); // Vector2(768, 10)
```

## Constructing bounds

The constructor takes the four extremes directly: `new Bounds2( minX, minY, maxX, maxY )`. For the more familiar `(x, y, width, height)` rectangle shape, use the static factory instead:

```ts
const bounds = Bounds2.rect( 10, 10, 200, 100 ); // minX:10, minY:10, maxX:210, maxY:110
```

| Static | Meaning |
| --- | --- |
| `Bounds2.rect( x, y, width, height )` | Build from x/y/width/height |
| `Bounds2.point( x, y )` / `Bounds2.point( vector )` | A zero-area bounds containing exactly one point, useful as a starting point to `dilate()` |
| `Bounds2.NOTHING` | `minX = minY = +Infinity`, `maxX = maxY = -Infinity` — the identity for `union()` |
| `Bounds2.EVERYTHING` | `minX = minY = -Infinity`, `maxX = maxY = +Infinity` — the identity for `intersection()` |

## Reading properties

| Getter | Meaning |
| --- | --- |
| `width`, `height` | `maxX - minX`, `maxY - minY` |
| `x`, `y`, `left`, `top`, `right`, `bottom` | Aliases for `minX`, `minY`, `minX`, `minY`, `maxX`, `maxY` |
| `centerX`, `centerY`, `center` | Midpoints, as numbers or a `Vector2` |
| `leftTop`, `centerTop`, `rightTop`, `leftCenter`, `rightCenter`, `leftBottom`, `centerBottom`, `rightBottom` | The eight named corners/edge-midpoints as `Vector2` |
| `xRange`, `yRange` | The `[minX, maxX]` / `[minY, maxY]` extents as a [`Range`](/api/dot/range) |
| `isEmpty()` | `true` if width or height is negative (`NOTHING` is empty; a zero-area point bounds is **not**) |
| `isFinite()` | `true` unless it's `NOTHING`/`EVERYTHING`-like |

## Immutable vs. mutable methods

Like the vector types, most operations come in an immutable form (new `Bounds2`) and a mutable form (mutates `this`):

| Immutable | Mutable | Effect |
| --- | --- | --- |
| `union( bounds )` | `includeBounds( bounds )` | Smallest bounds containing both |
| `intersection( bounds )` | `constrainBounds( bounds )` | Largest bounds contained in both |
| `withPoint( point )` / `withCoordinates( x, y )` | `addPoint( point )` / `addCoordinates( x, y )` | Expand to include a point |
| `dilated( d )` / `dilatedXY( x, y )` | `dilate( d )` / `dilateXY( x, y )` | Expand on all sides |
| `eroded( d )` / `erodedXY( x, y )` | `erode( d )` / `erodeXY( x, y )` | Contract on all sides |
| `shifted( v )` / `shiftedXY( x, y )` | `shift( v )` / `shiftXY( x, y )` | Translate |
| `roundedOut()` / `roundedIn()` | `roundOut()` / `roundIn()` | Snap to integer boundaries, expanding or contracting |
| `transformed( matrix )` | `transform( matrix )` | Apply a [`Matrix3`](/api/dot/matrix3) affine transform, re-fitting to axis-alignment |
| `copy()` | `set( bounds )` / `setMinMax( ... )` | Copy / assign |

Queries: `containsCoordinates( x, y )`, `containsPoint( point )`, `containsBounds( bounds )`, `intersectsBounds( bounds )`, `closestPointTo( point )`, `getConstrainedPoint( point )` (clamp a point into the bounds), `equals`/`equalsEpsilon`, and `toString()`.

::: warning `Bounds2.NOTHING` and `Bounds2.EVERYTHING` are frozen
Both constants throw if you call a mutating method (`setMinMax`, `dilate`, `transform`, ...) on them directly — they exist purely as identity elements for `union`/`intersection` chains. Start an accumulation with `Bounds2.NOTHING.copy()` (or just `Bounds2.NOTHING.union(...)`, which returns a fresh instance) rather than mutating the shared constant.
:::

## Related

- [Vector2](/api/dot/vector2) — corners and centers of a `Bounds2` are returned as `Vector2` instances.
- [Range](/api/dot/range) — `bounds.xRange` / `bounds.yRange` expose each axis as a `Range`.
- [Matrix3](/api/dot/matrix3) — `bounds.transformed( matrix )` re-fits a bounds after an affine transform.
- [Drag Listeners](/patterns/drag-listeners) — drag bounds are typically expressed as a `Bounds2`.


========================================================================
Page: Bounds3
URL: https://veillette.github.io/Almanach/api/dot/bounds3
Source: docs/api/dot/bounds3.md
Category: API | Tags: dot, Bounds3, bounds | Status: verified
========================================================================

# Bounds3

`Bounds3` (from `scenerystack/dot`) is the 3D counterpart to [`Bounds2`](/api/dot/bounds2): an axis-aligned cuboid stored as `minX`/`minY`/`minZ`/`maxX`/`maxY`/`maxZ` (plus `width`/`height`/`depth` convenience getters). It shows up far less often than `Bounds2` — mainly in 3D-flavored simulation content alongside [`Vector3`](/api/dot/vector3) and [`Matrix4`](/api/dot/matrix4) — but shares the same shape and naming conventions.

```ts
import { Bounds3 } from 'scenerystack/dot';

const box = new Bounds3( 0, 0, 0, 10, 20, 30 );

box.width;    // 10
box.height;   // 20
box.depth;    // 30
box.volume;   // 6000
box.center;   // Vector3(5, 10, 15)
```

## Constructing bounds

The constructor takes all six extremes directly: `new Bounds3( minX, minY, minZ, maxX, maxY, maxZ )`. For the `(x, y, z, width, height, depth)` cuboid shape, use the static factory instead:

```ts
const box = Bounds3.cuboid( 0, 0, 0, 10, 20, 30 ); // same box as above
```

| Static | Meaning |
| --- | --- |
| `Bounds3.cuboid( x, y, z, width, height, depth )` | Build from x/y/z/width/height/depth |
| `Bounds3.point( x, y, z )` | A zero-volume bounds containing exactly one point |
| `Bounds3.NOTHING` | All mins `+Infinity`, all maxes `-Infinity` — the identity for `union()` |
| `Bounds3.EVERYTHING` | All mins `-Infinity`, all maxes `+Infinity` — the identity for `intersection()` |

## Reading properties

| Getter | Meaning |
| --- | --- |
| `width`, `height`, `depth` | `maxX - minX`, `maxY - minY`, `maxZ - minZ` |
| `x`, `y`, `z`, `left`, `top`, `back`, `right`, `bottom`, `front` | Aliases for `minX`, `minY`, `minZ`, `minX`, `minY`, `minZ`, `maxX`, `maxY`, `maxZ` |
| `centerX`, `centerY`, `centerZ`, `center` | Midpoints, as numbers or a [`Vector3`](/api/dot/vector3) |
| `volume` | `width * height * depth` |
| `isEmpty()` | `true` if any dimension is negative |
| `isFinite()` | `true` unless it's `NOTHING`/`EVERYTHING`-like |
| `hasNonzeroVolume()` | `true` if width, height, and depth are all strictly positive |
| `isValid()` | `!isEmpty() && isFinite()` |

## Immutable vs. mutable methods

Like `Bounds2`, most operations come in an immutable form (new `Bounds3`) and a mutable form (mutates `this`). Note that `Bounds3` doesn't have the full set of named corner getters (`leftTop`, etc.) that `Bounds2` has — the model is otherwise identical:

| Immutable | Mutable | Effect |
| --- | --- | --- |
| `union( bounds )` | `includeBounds( bounds )` | Smallest bounds containing both |
| `intersection( bounds )` | `constrainBounds( bounds )` | Largest bounds contained in both |
| `withCoordinates( x, y, z )` / `withPoint( point )` | `addCoordinates( x, y, z )` / `addPoint( point )` | Expand to include a point |
| `dilated( d )` / `dilatedXYZ( x, y, z )` | `dilate( d )` / `dilateXYZ( x, y, z )` | Expand on all sides |
| `eroded( d )` / `erodedXYZ( x, y, z )` | `erode( d )` / `erodeXYZ( x, y, z )` | Contract on all sides |
| `shifted( v )` / `shiftedXYZ( x, y, z )` | `shift( v )` / `shiftXYZ( x, y, z )` | Translate |
| `roundedOut()` / `roundedIn()` | `roundOut()` / `roundIn()` | Snap to integer boundaries, expanding or contracting |
| `transformed( matrix )` | `transform( matrix )` | Apply a [`Matrix4`](/api/dot/matrix4) affine transform, re-fitting to axis-alignment |
| `copy()` | `set( bounds )` / `setMinMax( ... )` | Copy / assign |

Queries: `containsCoordinates( x, y, z )`, `containsPoint( point )`, `containsBounds( bounds )`, `intersectsBounds( bounds )`, `equals`/`equalsEpsilon`, and `toString()`.

::: tip `transformed`/`transform` check all 8 corners
Just like `Bounds2.transformed()`, `Bounds3.transformed( matrix )` re-fits the box after an arbitrary [`Matrix4`](/api/dot/matrix4) affine transform by transforming all 8 corners and taking the min/max of the results — so it stays axis-aligned even after a rotation. Composing a transform with its inverse (`bounds.transformed( m ).transformed( m.inverted() )`) can therefore return a *larger* box than the original if `m` includes a rotation that isn't a multiple of a right angle.
:::

## Related

- [Bounds2](/api/dot/bounds2) — the 2D counterpart; same shape and naming conventions, one dimension fewer.
- [Vector3](/api/dot/vector3) — `Bounds3`'s corners and center are `Vector3` instances.
- [Matrix4](/api/dot/matrix4) — `bounds.transformed( matrix )` re-fits a `Bounds3` after an affine transform.


========================================================================
Page: Complex
URL: https://veillette.github.io/Almanach/api/dot/complex
Source: docs/api/dot/complex.md
Category: API | Tags: dot, Complex, math | Status: verified
========================================================================

# Complex

`Complex` (from `scenerystack/dot`) is a complex number with a `real` and `imaginary` part, supporting the usual arithmetic (add, subtract, multiply, divide, conjugate, powers, trig, exponentiation) plus static solvers for the roots of linear, quadratic, and cubic equations with complex coefficients. It follows the same immutable/mutable method-naming convention as dot's vector types.

```ts
import { Complex } from 'scenerystack/dot';

const a = new Complex( 3, 4 );  // 3 + 4i

a.magnitude;         // 5
a.phase();           // Math.atan2(4, 3)

const product = a.times( Complex.I ); // new Complex, a unchanged: rotates a by 90 degrees -> -4 + 3i
a.multiply( Complex.I );               // mutates a in place to -4 + 3i
```

## Constructing

The constructor takes `real` and `imaginary` directly: `new Complex( real, imaginary )`. Both are plain mutable public fields.

| Static | Meaning |
| --- | --- |
| `Complex.real( r )` | `r + 0i` |
| `Complex.imaginary( i )` | `0 + ri` |
| `Complex.createPolar( magnitude, phase )` | Builds from magnitude/phase (radians) instead of real/imaginary |
| `Complex.ZERO` / `Complex.ONE` / `Complex.I` | The constants `0`, `1`, and the imaginary unit `i` |

## Immutable vs. mutable methods

The convention matches `Vector2`/`Vector3`: the immutable form returns a new `Complex`, the mutable form changes `this` and returns it.

| Immutable (returns new `Complex`) | Mutable (changes `this`, returns `this`) | Effect |
| --- | --- | --- |
| `plus( c )` | `add( c )` | Addition |
| `minus( c )` | `subtract( c )` | Subtraction |
| `times( c )` | `multiply( c )` | Complex multiplication |
| `dividedBy( c )` | `divide( c )` | Complex division |
| `negated()` | `negate()` | Negation |
| `conjugated()` | `conjugate()` | Complex conjugate (flips the sign of `imaginary`) |
| `squared()` | `square()` | Self times self |
| `sqrtOf()` | `sqrt()` | Principal square root |
| `powerByReal( realPower )` | — (no mutable form) | Raises to a real-valued power |
| `sinOf()` / `cosOf()` | `sin()` / `cos()` | Complex sine/cosine |
| `exponentiated()` | `exponentiate()` | $e^{a+bi} = e^a(\cos b + i\sin b)$ |
| `copy()` | `set( c )` / `setRealImaginary( r, i )` / `setReal( r )` / `setImaginary( i )` / `setPolar( magnitude, phase )` | Copy / assign |

Read-only queries: `magnitude`, `magnitudeSquared`, `phase()` (alias `argument`/`getArgument()`), `equals( other )` / `equalsEpsilon( other, epsilon )`, `getCubeRoots()` (the three cube roots of this complex number), and `toString()`.

## Solving polynomial roots

`Complex` exposes static solvers that work over complex coefficients, each returning an array of roots or `null` if every value is a solution:

| Static method | Solves |
| --- | --- |
| `Complex.solveLinearRoots( a, b )` | $ax + b = 0$ |
| `Complex.solveQuadraticRoots( a, b, c )` | $ax^2 + bx + c = 0$ |
| `Complex.solveCubicRoots( a, b, c, d )` | $ax^3 + bx^2 + cx + d = 0$ |

::: tip For real-only coefficients, dot's free functions are simpler
If your coefficients and expected roots are all real numbers, `scenerystack/dot`'s free functions `solveLinearRootsReal`, `solveQuadraticRootsReal`, and `solveCubicRootsReal` (see [Utils](/api/dot/dot-utils)) skip the `Complex` wrapping entirely and return `number[] | null` directly. Reach for `Complex.solve*Roots` only when coefficients or roots may genuinely be complex (not just real values that happen to be represented as numbers).
:::

## Related

- [Utils](/api/dot/dot-utils) — the real-only root solvers (`solveQuadraticRootsReal`, etc.) that skip `Complex` when all values are real.


========================================================================
Page: ConvexHull2
URL: https://veillette.github.io/Almanach/api/dot/convex-hull2
Source: docs/api/dot/convex-hull2.md
Category: API | Tags: dot, ConvexHull2, Vector2, geometry, math | Status: complete
========================================================================

# ConvexHull2

`ConvexHull2` (from `scenerystack/dot`) is a namespace object (not a class you instantiate) with a single method, `grahamScan()`, implementing the [Graham Scan](http://en.wikipedia.org/wiki/Graham_scan) algorithm: given an arbitrary set of 2D points, it returns the ordered subset of those points that form the smallest convex polygon containing all of them.

```ts
import { ConvexHull2, Vector2 } from 'scenerystack/dot';
import { Shape } from 'scenerystack/kite';

const points = [
  new Vector2( 0, 0 ), new Vector2( 4, 0 ), new Vector2( 2, 2 ),
  new Vector2( 2, 4 ), new Vector2( 1, 1 ) // interior point - excluded from the hull
];

const hullPoints = ConvexHull2.grahamScan( points, false );
// an ordered Vector2[] tracing the outer boundary, excluding the interior point

const hullShape = Shape.polygon( hullPoints ); // draw it with kite
```

## `grahamScan( points, includeCollinear )`

| Parameter | Effect |
| --- | --- |
| `points` | The `Vector2[]` to compute a hull over |
| `includeCollinear` | If `true`, points lying exactly along a hull edge (not at a vertex) are kept in the result; if `false`, only the "true" corner vertices are kept |

Returns an ordered `Vector2[]` (counter-clockwise) tracing the hull boundary. Arrays of 2 or fewer points are returned unchanged (there's no meaningful "hull" to compute).

## When you'd reach for this

Convex hulls come up whenever you need the smallest polygon enclosing a scattered set of points — for example, drawing a boundary/highlight around a cluster of draggable objects, computing a rough bounding shape for collision purposes that's tighter than an axis-aligned [`Bounds2`](/api/dot/bounds2) but simpler than the objects' exact outlines, or building the correct arm/interaction shape for a Voronoi- or hull-based interactive diagram.

::: tip Collinear points are excluded by default
Pass `includeCollinear: false` (as most callers do) unless you specifically need every point that lies exactly on a hull edge represented in the result — the default (excluding them) gives you the minimal vertex set describing the same polygon, which is usually what you want for drawing or further geometric processing.
:::


========================================================================
Page: DampedHarmonic
URL: https://veillette.github.io/Almanach/api/dot/damped-harmonic
Source: docs/api/dot/damped-harmonic.md
Category: API | Tags: dot, DampedHarmonic, differential-equations, physics, math | Status: complete
========================================================================

# DampedHarmonic

`DampedHarmonic` (from `scenerystack/dot`) solves the general damped harmonic oscillator differential equation `a·x'' + b·x' + c·x = 0` in closed form, given initial conditions `x(0)` and `x'(0)`. This is the same equation governing a mass on a damped spring, a damped pendulum (small-angle approximation), or an RLC circuit — anywhere a sim's model has a restoring force plus a velocity-proportional damping force and needs `x(t)` evaluated analytically (no numerical integration, no accumulated per-step error) at any time `t`.

```ts
import { DampedHarmonic } from 'scenerystack/dot';

// A mass-spring-damper: mx'' + bx' + kx = 0, released from x=1 with zero velocity
const mass = 1;
const damping = 0.5;
const springConstant = 4;

const oscillator = new DampedHarmonic( mass, damping, springConstant, 1, 0 );

oscillator.getValue( 0 );    // 1 (the initial position)
oscillator.getValue( 2 );    // position at t=2 seconds
oscillator.getDerivative( 2 ); // velocity at t=2 seconds
```

## Constructor

```ts
new DampedHarmonic(
  a: number, b: number, c: number,
  initialValue: number, initialDerivative: number
)
```

| Parameter | Effect |
| --- | --- |
| `a` | Coefficient on `x''` (e.g. mass) — must be finite and non-zero |
| `b` | Coefficient on `x'` (damping) — must be finite; `a` and `b` must share the same sign, since negative damping (relative to `a`) doesn't correspond to a physical damped system this class solves |
| `c` | Coefficient on `x` (restoring force / spring constant) — must be finite and non-zero; `a` and `c` must share the same sign |
| `initialValue` | `x(0)` |
| `initialDerivative` | `x'(0)` |

Internally, the constructor normalizes to `x'' + dampingConstant·x' + angularFrequencySquared·x = 0`, computes the discriminant `dampingConstant² - 4·angularFrequencySquared`, and picks the matching closed-form solution: **over-damped** (`discriminant > 0`, two real exponential decay rates), **critically damped** (`discriminant ≈ 0`, a linear-times-exponential solution), or **under-damped** (`discriminant < 0`, an oscillating exponentially-decaying solution) — this is standard textbook damped-oscillator classification, chosen once at construction and then used by both query methods below.

## Methods

| Method | Effect |
| --- | --- |
| `getValue( t )` | The solution `x(t)` at time `t` |
| `getDerivative( t )` | The velocity `x'(t)` at time `t` |

Both are pure functions of `t` — evaluating at an arbitrary time doesn't require stepping through every intermediate time, unlike a numerically-integrated model.

::: tip This is an analytic solver, not a stepping integrator
Unlike model code that advances state with `step( dt )` on every animation frame, `DampedHarmonic` computes the exact solution at any requested `t` directly from the initial conditions — there's no accumulated integration error, and no need to call it every frame if you only need the value at a few specific times. If your model already advances other quantities with discrete `dt` steps, you can still track a single elapsed-time accumulator and call `getValue( elapsedTime )` each frame for the oscillating quantity specifically.
:::


========================================================================
Page: Dimension2
URL: https://veillette.github.io/Almanach/api/dot/dimension2
Source: docs/api/dot/dimension2.md
Category: API | Tags: dot, Dimension2, bounds | Status: verified
========================================================================

# Dimension2

`Dimension2` (from `scenerystack/dot`) is a bare `{ width, height }` pair — a size with no position, unlike [`Bounds2`](/api/dot/bounds2) which anchors its extent at specific `minX`/`minY` coordinates. Reach for it when you need to describe or pass around "how big," not "where," e.g. layout preferred sizes, image dimensions, or screen/window sizes.

```ts
import { Dimension2 } from 'scenerystack/dot';

const screenSize = new Dimension2( 1024, 768 );

screenSize.width;    // 1024
screenSize.swapped(); // Dimension2(768, 1024) — new instance, screenSize unchanged

const bounds = screenSize.toBounds(); // Bounds2(0, 0, 1024, 768)
const shifted = screenSize.toBounds( 100, 50 ); // Bounds2(100, 50, 1124, 818)
```

## Constructing

The constructor takes `width` and `height` directly: `new Dimension2( width, height )`. Both are plain mutable public fields (`dimension.width = 10`), not getter/setter pairs.

## Methods

| Method | Effect |
| --- | --- |
| `copy( dimension? )` | Returns a new `Dimension2` equal to this one, or (if `dimension` is passed) mutates `dimension` to match this one and returns it |
| `set( dimension )` | Mutates this `Dimension2` to match another, returning `this` |
| `setWidth( width )` / `setHeight( height )` | Mutable single-field setters, returning `this` |
| `swapped()` | A new `Dimension2` with `width` and `height` exchanged |
| `toBounds( x?, y? )` | A new [`Bounds2`](/api/dot/bounds2) of this size, anchored with its minimum corner at `(x, y)` (both default to `0`) |
| `equals( that )` / `equalsEpsilon( that, epsilon? )` | Comparison |
| `toString()` | Debug string, e.g. `[1024w, 768h]` |

::: tip There's no immutable/mutable method split here
Unlike `Vector2`/`Bounds2`, `Dimension2` doesn't have paired immutable+mutable variants for its operations — `width`/`height` are plain public fields you can assign directly, and `set`/`setWidth`/`setHeight` are the only mutators. `copy()` and `swapped()` are the only two methods that return a new instance; everything else either mutates in place or (like `toBounds`) is a one-way conversion.
:::

## Related

- [Bounds2](/api/dot/bounds2) — `dimension.toBounds( x, y )` builds a `Bounds2` of this size at a given position; conversely, `bounds.width`/`bounds.height` give you the size of an existing `Bounds2`.


========================================================================
Page: dotRandom
URL: https://veillette.github.io/Almanach/api/dot/dot-random
Source: docs/api/dot/dot-random.md
Category: API | Tags: dot, dotRandom, Random, seeding, phet-io | Status: complete
========================================================================

# dotRandom

`dotRandom` (from `scenerystack/dot`) is a single, shared instance of [`Random`](/api/dot/random) that every part of a SceneryStack simulation should use for pseudo-randomness, rather than calling `Math.random()` directly or constructing a private `new Random()`. It's created once, seeded from the `randomSeed` PhET-iO query parameter when running under PhET-iO (falling back to an unpredictable seed otherwise), and then reused everywhere.

```ts
import { dotRandom } from 'scenerystack/dot';

// Anywhere in model code that needs randomness:
const angle = dotRandom.nextDoubleBetween( 0, Math.PI * 2 );
const startingLane = dotRandom.nextIntBetween( 0, 3 );
const shuffledDeck = dotRandom.shuffle( cards );
```

`dotRandom` exposes the exact same API as any `Random` instance — `nextDouble()`, `nextBoolean()`, `nextIntBetween()`, `nextGaussian()`, `sample()`, `shuffle()`, `sampleProbabilities()`, and so on. See [Random](/api/dot/random) for the full method table.

## Why the shared instance matters

`Random`'s own doc comment is explicit about this: "If you are developing a PhET Simulation, you should probably use the global `DOT/dotRandom`" rather than a private instance, because `dotRandom` provides built-in support for PhET-iO seeding. When every random draw in a simulation funnels through the one shared, seedable generator, PhET-iO's state-restore and record-and-replay tooling can reproduce an identical run just by re-supplying the same seed — a `Vector2Property` moving randomly, a probabilistic model event, and a shuffled list all become deterministic together. Scattering `Math.random()` calls (or several independent `new Random()` instances) throughout a codebase breaks that guarantee: even with the same seed, the *order* in which different generators are drawn from can vary run to run, and any plain `Math.random()` call can never be seeded or reproduced at all.

::: warning Construct your own `Random` only for genuinely independent randomness
Reach for `new Random( { seed } )` instead of `dotRandom` only when you deliberately want an isolated sequence that must not perturb (or be perturbed by) the rest of the sim's random draws — for example, a self-contained unit test asserting on a specific sequence of values. For anything that runs as part of a live simulation, use `dotRandom`.
:::


========================================================================
Page: LinearFunction
URL: https://veillette.github.io/Almanach/api/dot/linear-function
Source: docs/api/dot/linear-function.md
Category: API | Tags: dot, LinearFunction, math | Status: verified
========================================================================

# LinearFunction

`LinearFunction` (from `scenerystack/dot`) packages up a linear mapping between two numeric domains — "domain a" and "domain b" — as a reusable object with both a forward (`evaluate`) and inverse (`inverse`) direction. It's the object-oriented sibling of the free function [`linear()`](/api/dot/dot-utils): where `linear()` takes all five numbers every call, `LinearFunction` remembers the two domains once and lets you call `.evaluate()`/`.inverse()` repeatedly, which reads better when the same mapping is reused (e.g. a value-to-pixel conversion applied across many data points).

```ts
import { LinearFunction } from 'scenerystack/dot';

// Maps a model domain [0, 100] to a view/pixel domain [0, 200]
const f = new LinearFunction( 0, 100, 0, 200 );

f.evaluate( 50 ); // 100 — maps a value from domain a to domain b
f.inverse( 100 ); // 50  — maps a value from domain b back to domain a
```

## Constructing

```ts
new LinearFunction( a1, a2, b1, b2, clamp = false )
```

`a1`/`a2` are two points in the first domain, `b1`/`b2` are the corresponding two points in the second domain — so `evaluate( a1 ) === b1` and `evaluate( a2 ) === b2`, with everything else linearly interpolated (or extrapolated) between them. The optional fifth argument `clamp` (default `false`), if `true`, constrains every result of `evaluate`/`inverse` to stay within `[min(b1,b2), max(b1,b2)]` or `[min(a1,a2), max(a1,a2)]` respectively, instead of extrapolating past the given endpoints.

## Methods

| Method | Effect |
| --- | --- |
| `evaluate( a3 )` | Maps a value from domain a to domain b |
| `inverse( b3 )` | Maps a value from domain b back to domain a — the literal inverse of `evaluate` |

That's the entire public surface — `LinearFunction` is intentionally minimal. Both methods respect the `clamp` flag passed to the constructor.

```ts
// A slider's model range maps to its track's pixel width, clamped so
// out-of-range model values don't push the thumb off the track.
const modelToTrackX = new LinearFunction( 0, 100, 0, 300, true );

modelToTrackX.evaluate( 150 ); // 300, not 450 — clamped to the b-domain
```

::: tip Order of arguments controls direction, not just endpoints
`evaluate` always maps *from* the `a1`/`a2` domain *to* the `b1`/`b2` domain; `inverse` always goes the other way. There's no ambiguity about which domain is "the input" at call time — it's fixed by the order of arguments to the constructor. If you find yourself calling `inverse` far more often than `evaluate`, consider swapping the constructor arguments so the more common direction is the default `evaluate` call.
:::

## Related

- [Utils](/api/dot/dot-utils) — `linear( a1, a2, b1, b2, a3 )` is the underlying free function `LinearFunction` wraps; reach for it directly for a one-off mapping that doesn't need to be reused.
- [Range](/api/dot/range) — `range.getNormalizedValue()`/`expandNormalizedValue()` cover the common special case of mapping to/from `[0, 1]`, which overlaps with what `LinearFunction` can express.


========================================================================
Page: Matrix Decompositions
URL: https://veillette.github.io/Almanach/api/dot/matrix-decompositions
Source: docs/api/dot/matrix-decompositions.md
Category: API | Tags: dot, Matrix, LUDecomposition, QRDecomposition, EigenvalueDecomposition, SingularValueDecomposition, linear-algebra | Status: complete
========================================================================

# Matrix Decompositions

`scenerystack/dot` exports a general, arbitrary-dimensional `Matrix` class (distinct from the fixed-size [`Matrix3`](/api/dot/matrix3)/`Matrix4` used for 2D/3D transforms — `Matrix` is for numerical linear algebra on `m x n` data, ported from [Jama](http://math.nist.gov/javanumerics/jama/)) plus four decomposition classes built on it: `LUDecomposition`, `QRDecomposition`, `EigenvalueDecomposition`, and `SingularValueDecomposition`. Most simulation code never needs any of these directly — they exist to support `Matrix.solve()`/`Matrix.inverse()` and any sim that does real numerical linear algebra (curve fitting, physics models expressed as linear systems, PCA-style data analysis). This page is a map of what each one is for, not a numerical-methods tutorial.

```ts
import { Matrix } from 'scenerystack/dot';

const A = new Matrix( 2, 2, [ 2, 1, 1, 3 ] ); // row-major: [[2,1],[1,3]]
const b = new Matrix( 2, 1, [ 3, 5 ] );

const x = A.solve( b ); // solves Ax = b - internally picks LU (square) or QR (non-square)
```

## `Matrix` itself

`new Matrix( m, n, filler?, fast? )` builds an `m`-row by `n`-column matrix backed by a flat, row-major `Float64Array`. Beyond basic algebra (`plus`, `minus`, `times`, `transpose`, `trace`, ...), its most-used members delegate to the decompositions below:

| Method | Delegates to |
| --- | --- |
| `solve( b )` | `LUDecomposition` if square, otherwise `QRDecomposition` (least-squares) |
| `inverse()` | `solve( Matrix.identity( ... ) )` |
| `det()` | `LUDecomposition.det()` |
| `rank()` | `SingularValueDecomposition.rank()` |
| `cond()` | `SingularValueDecomposition.cond()` |

You'll reach for a specific decomposition class directly only when you need something `Matrix`'s convenience methods don't expose — the individual `L`/`U`, `Q`/`R`, eigenvector, or singular-value matrices themselves, not just a solved system or a scalar.

## `LUDecomposition` — solving square linear systems

Factors a square matrix `A` into a lower-triangular `L` and upper-triangular `U` (with row pivoting) such that `A = L * U` (up to a permutation). This is the classical "solve `Ax = b`" workhorse for square systems, and what `Matrix.solve()`/`det()` use whenever the matrix is square.

| Member | Effect |
| --- | --- |
| `new LUDecomposition( matrix )` | Computes the factorization of a square `Matrix` |
| `isNonsingular()` | Whether the matrix is invertible (no zero pivot) |
| `getL()` / `getU()` | The lower/upper triangular factor matrices |
| `getPivot()` / `getDoublePivot()` | The row-pivot permutation applied during factorization |
| `det()` | The determinant, computed from the pivoted diagonal |
| `solve( b )` | Solves `Ax = b` for `x`, given the already-computed factorization |

A separate `LUDecompositionDecimal` export provides the same factorization using arbitrary-precision decimal arithmetic instead of floating point, for cases where floating-point rounding error in an ordinary `LUDecomposition` would matter.

## `QRDecomposition` — solving non-square (least-squares) systems

Factors any `m x n` matrix `A` (via Householder reflections) into an orthogonal `Q` and upper-triangular `R` such that `A = Q * R`. Where `LUDecomposition` requires a square matrix, `QRDecomposition` works for any shape, and `Matrix.solve()` falls back to it whenever the system is over- or under-determined, producing a least-squares solution.

| Member | Effect |
| --- | --- |
| `new QRDecomposition( matrix )` | Computes the factorization of any `Matrix` |
| `isFullRank()` | Whether `R`'s diagonal has no (near-)zero entries |
| `getQ()` / `getR()` | The orthogonal / upper-triangular factor matrices |
| `getH()` | The raw Householder vectors used internally |
| `solve( b )` | Least-squares solution to `Ax = b` |

## `EigenvalueDecomposition` — eigenvalues and eigenvectors

Computes the eigenvalues and eigenvectors of a square matrix `A`: `A = V * D * V⁻¹`, where `D` is (block-)diagonal and `V`'s columns are the eigenvectors. For symmetric `A`, `D` is purely diagonal with real eigenvalues and `V` is orthogonal; for non-symmetric `A`, complex eigenvalue pairs show up as 2x2 blocks in `D`.

| Member | Effect |
| --- | --- |
| `new EigenvalueDecomposition( matrix )` | Computes the decomposition of a square `Matrix` |
| `getV()` | The eigenvector matrix |
| `getD()` | The (block-)diagonal eigenvalue matrix |
| `getRealEigenvalues()` / `getImagEigenvalues()` | The eigenvalues' real and imaginary parts as plain number arrays |

Reach for this when a sim needs the actual eigenstructure of a system — e.g. finding the natural modes/frequencies of a coupled-oscillator model, or the principal axes of a data set.

## `SingularValueDecomposition` — rank, conditioning, and general factorization

Factors any `m x n` matrix into `A = U * S * Vᵀ`, where `S` is diagonal (the singular values) and `U`/`V` are orthogonal. This is the most numerically robust of the four — `Matrix.rank()` and `Matrix.cond()` both delegate to it — at the cost of being the most expensive to compute.

| Member | Effect |
| --- | --- |
| `new SingularValueDecomposition( matrix )` | Computes the decomposition of any `Matrix` |
| `getU()` / `getV()` | The two orthogonal factor matrices |
| `getSingularValues()` / `getS()` | The singular values as a plain array, or as the diagonal `S` matrix |
| `rank()` | The matrix's numerical rank (count of singular values above a tolerance) |
| `cond()` | The condition number (`largest / smallest` singular value) — a large value signals a numerically unstable/near-singular matrix |

::: tip Reach for `Matrix.solve()`/`.det()`/`.rank()` first
Unless you specifically need the factor matrices themselves (`L`/`U`, `Q`/`R`, eigenvectors, or `U`/`S`/`V`), use `Matrix`'s own convenience methods (`solve`, `inverse`, `det`, `rank`, `cond`) — they pick the appropriate decomposition internally. Constructing a decomposition class directly is for the minority of cases (eigenstructure analysis, needing `Q` or `L`/`U` explicitly) where the convenience methods don't expose what you need.
:::


========================================================================
Page: Matrix3
URL: https://veillette.github.io/Almanach/api/dot/matrix3
Source: docs/api/dot/matrix3.md
Category: API | Tags: dot, Matrix3, transform | Status: verified
========================================================================

# Matrix3

`Matrix3` (from `scenerystack/dot`) is a 3x3 matrix, most commonly used to represent a 2D affine transform (rotation + scale + translation, or shear) via homogeneous coordinates. It's the type behind `Node.matrix`/`Node.transform` in scenery and the machinery inside `ModelViewTransform2`, and it's the argument type for `Bounds2.transformed()` and `Shape.transformed()`.

```ts
import { Matrix3 } from 'scenerystack/dot';
import { Vector2 } from 'scenerystack/dot';

const matrix = Matrix3.translation( 100, 50 ).timesMatrix( Matrix3.rotation2( Math.PI / 4 ) );

matrix.timesVector2( new Vector2( 1, 0 ) ); // rotate then translate the point (1,0)
matrix.getTranslation();                     // Vector2(100, 50)
matrix.getRotation();                        // Math.PI / 4
```

## Constructing matrices

The bare constructor `new Matrix3()` only ever produces the identity matrix — you build real matrices with static factories, which also let dot track the matrix's `type` (`IDENTITY`, `TRANSLATION_2D`, `SCALING`, `AFFINE`, `OTHER`) for fast-path optimizations:

| Static factory | Produces |
| --- | --- |
| `Matrix3.identity()` | The identity matrix |
| `Matrix3.translation( x, y )` / `Matrix3.translationFromVector( vector )` | Pure translation |
| `Matrix3.scaling( x, y? )` (alias `Matrix3.scale`) | Pure scale (`y` defaults to `x` for uniform scale) |
| `Matrix3.rotation2( angle )` | Pure 2D rotation, radians |
| `Matrix3.rotationAround( angle, x, y )` / `Matrix3.rotationAroundPoint( angle, point )` | Rotation about an arbitrary point |
| `Matrix3.translationRotation( x, y, angle )` | Combined translate + rotate |
| `Matrix3.rotationX/Y/Z( angle )` | 3D-style axis rotations (still a 3x3, useful for the z-rotation case above) |
| `Matrix3.affine( m00, m01, m02, m10, m11, m12 )` | Arbitrary 2x3 affine part directly |
| `Matrix3.rowMajor( v00, ..., v22 )` | All nine entries, row-major |

## Reading a matrix

| Accessor | Meaning |
| --- | --- |
| `m00()`...`m22()` | Individual entries, row/column indexed |
| `translation` | `(m02, m12)` as a `Vector2` |
| `rotation` | `Math.atan2( m10, m00 )`, in radians |
| `scaleVector` | `(|column 0|, |column 1|)` as a `Vector2` |
| `determinant` | The determinant; also the signed area scale factor |
| `isIdentity()` / `isTranslation()` / `isAffine()` / `isAligned()` | Structural queries used for fast-path code |

## Applying and combining transforms

| Method | Effect |
| --- | --- |
| `timesMatrix( matrix )` | Returns `this * matrix` as a new `Matrix3` |
| `timesVector2( vector )` / `multiplyVector2( vector )` | Apply the transform to a point; `timesVector2` is immutable (new `Vector2`), `multiplyVector2` mutates the vector argument in place |
| `inverted()` | Returns the inverse transform as a new `Matrix3` |
| `transposed()` | Returns the transpose |
| `plus( matrix )` / `minus( matrix )` | Entry-wise addition/subtraction |
| `equals( matrix )` / `equalsEpsilon( matrix, epsilon )` | Comparison |

Mutating counterparts exist for the constructor-style operations too — `setToTranslation`, `setToScale`, `setToRotationZ`, `setToTranslationRotation`, and the low-level `rowMajor(...)` that all of the mutators funnel through.

::: tip Order matters: `A.timesMatrix(B)` applies B first
`A.timesMatrix( B )` computes the matrix product `A * B`. When applied to a point via homogeneous coordinates, that means **B's transform is applied first, then A's** — so `Matrix3.translation( 100, 0 ).timesMatrix( Matrix3.rotation2( angle ) )` rotates a point about the origin and *then* translates it, not the other way around. This is the same convention used to compose [`ModelViewTransform2`](/api/phetcommon/model-view-transform)-style transforms and scenery `Node` transforms.
:::

## Related

- [Vector2](/api/dot/vector2) — the point/vector type that `Matrix3` transforms.
- [Bounds2](/api/dot/bounds2) — `bounds.transformed( matrix )` re-fits an axis-aligned box after an affine transform.
- [ModelViewTransform2](/api/phetcommon/model-view-transform) — wraps a `Matrix3` (or matrix pair) to convert between model and view coordinates.


========================================================================
Page: Matrix4
URL: https://veillette.github.io/Almanach/api/dot/matrix4
Source: docs/api/dot/matrix4.md
Category: API | Tags: dot, Matrix4, transform | Status: verified
========================================================================

# Matrix4

`Matrix4` (from `scenerystack/dot`) is a 4x4 matrix, the 3D counterpart to [`Matrix3`](/api/dot/matrix3): it represents affine transforms (rotation + scale + translation) in homogeneous coordinates over `(x, y, z, w)`. It's the type used by `Bounds3.transformed()`, and is also useful directly for 3D-flavored simulation content and WebGL-adjacent math (it has a `gluPerspective` factory for building projection matrices).

```ts
import { Matrix4 } from 'scenerystack/dot';
import { Vector3 } from 'scenerystack/dot';

const matrix = Matrix4.translation( 0, 0, -10 ).timesMatrix( Matrix4.rotationY( Math.PI / 4 ) );

matrix.timesVector3( new Vector3( 1, 0, 0 ) ); // rotate then translate, as a homogeneous (x,y,z,1) point
matrix.getTranslation();                        // Vector3(0, 0, -10)
```

## Constructing matrices

The bare constructor `new Matrix4()` produces the identity matrix; passing 16 entries (row-major) builds an arbitrary matrix directly. As with `Matrix3`, static factories are the common path and let dot tag the result's `type` (`IDENTITY`, `TRANSLATION_3D`, `SCALING`, `AFFINE`, `OTHER`, all under `Matrix4.Types`) for fast-path optimizations:

| Static factory | Produces |
| --- | --- |
| `Matrix4.identity()` | The identity matrix |
| `Matrix4.translation( x, y, z )` / `Matrix4.translationFromVector( vector )` | Pure translation |
| `Matrix4.scaling( x, y?, z? )` | Pure scale (`y`/`z` default to `x` for uniform scale) |
| `Matrix4.rotationAxisAngle( axis, angle )` | Rotation about an arbitrary normalized axis |
| `Matrix4.rotationX/Y/Z( angle )` | Axis-aligned rotations, radians |
| `Matrix4.gluPerspective( fovYRadians, aspect, zNear, zFar )` | A WebGL-style perspective projection matrix |
| `Matrix4.rowMajor( v00, ..., v33, type? )` / `columnMajor( ... )` | All sixteen entries directly |

## Reading a matrix

| Accessor | Meaning |
| --- | --- |
| `m00()` ... `m33()` | Individual entries, row/column indexed |
| `translation` | `(m03, m13, m23)` as a [`Vector3`](/api/dot/vector3) |
| `scaleVector` | Per-axis scale magnitude, as a `Vector3` |
| `determinant` | The determinant |
| `isIdentity()` / `isFinite()` | Structural queries |
| `cssTransform` | A `matrix3d(...)` CSS transform string |

## Applying and combining transforms

| Method | Effect |
| --- | --- |
| `timesMatrix( matrix )` | Returns `this * matrix` as a new `Matrix4` |
| `timesVector4( v )` | Full homogeneous multiplication of a [`Vector4`](/api/dot/vector4) |
| `timesVector3( v )` | Treats `v` as `(x, y, z, 1)` — a point — and returns a `Vector3` |
| `timesRelativeVector3( v )` | Treats `v` as `(x, y, z, 0)` — a direction, ignoring translation |
| `timesTransposeVector4( v )` / `timesTransposeVector3( v )` | Multiplication by this matrix's transpose instead |
| `inverted()` | Returns the inverse as a new `Matrix4` (throws if the determinant is 0) |
| `transposed()` | Returns the transpose |
| `plus( matrix )` / `minus( matrix )` | Entry-wise addition/subtraction |
| `equals( matrix )` / `equalsEpsilon( matrix, epsilon )` | Comparison |
| `makeImmutable()` | Marks the instance so further mutation throws (used for `Matrix4.IDENTITY`) |

All of the above are immutable-returning; `Matrix4` also supports in-place mutation via `set( matrix )`, `rowMajor(...)`, and `columnMajor(...)`, which funnel through the same entry-setting path.

::: tip `timesVector3` assumes `w = 1`, not `w = 0`
`matrix.timesVector3( v )` implicitly promotes `v` to `Vector4( v.x, v.y, v.z, 1 )` before multiplying — correct for transforming a *point*, but wrong for a *direction* (like a surface normal or a velocity), where translation shouldn't apply. Use `timesRelativeVector3( v )` for directions, the same way `Transform3`/`ModelViewTransform2` distinguish "position" methods from "delta" methods in 2D.
:::

## Related

- [Matrix3](/api/dot/matrix3) — the 2D counterpart, used far more often in typical (2D) SceneryStack sims.
- [Vector3](/api/dot/vector3) — the point/vector type most `Matrix4` methods operate on.
- [Vector4](/api/dot/vector4) — the native homogeneous-coordinate operand for `timesVector4`.
- [Bounds3](/api/dot/bounds3) — `bounds.transformed( matrix )` re-fits a 3D bounding box after an affine transform.


========================================================================
Page: Permutation and Combination
URL: https://veillette.github.io/Almanach/api/dot/permutation-and-combination
Source: docs/api/dot/permutation-and-combination.md
Category: API | Tags: dot, Permutation, Combination, combinatorics, math | Status: complete
========================================================================

# Permutation and Combination

`Permutation` and `Combination` (both from `scenerystack/dot`) are small, immutable combinatorics helper classes. A `Permutation` describes one particular reordering of a list's indices; a `Combination` describes one particular yes/no inclusion of each index (a subset). Both are mostly useful for enumerating every possible reordering/subset of a small array — for example, generating every possible arrangement of a handful of draggable objects for a "try all combinations" puzzle checker, or exhaustively testing every way a small set of items can be grouped.

```ts
import { Permutation, Combination } from 'scenerystack/dot';

// Every reordering of 3 items:
const permutations = Permutation.permutations( 3 ); // 6 Permutation instances

// Apply one directly to an array:
Permutation.identity( 3 ).apply( [ 'a', 'b', 'c' ] ); // [ 'a', 'b', 'c' ]

// Every subset of a 3-element array:
Combination.combinationsOf( [ 'a', 'b', 'c' ] );
// [ [], ['c'], ['b'], ['b','c'], ['a'], ['a','c'], ['a','b'], ['a','b','c'] ]
```

## `Permutation`

A `Permutation` wraps an `indices: number[]` array such that applying it to a list produces `newList[i] = oldList[permutation.indices[i]]`.

| Member | Effect |
| --- | --- |
| `new Permutation( indices )` | Wraps an explicit indices array |
| `size()` | Number of elements this permutation rearranges |
| `apply( arrayOrInt )` | Applied to an array, returns a new reordered array; applied to a single index, returns `indices[index]` |
| `inverted()` | The permutation that undoes this one |
| `withIndicesPermuted( indices )` | All `Permutation`s obtained by additionally permuting just the given subset of index positions |
| `equals( other )` | Structural equality on `indices` |
| `Permutation.identity( size )` | The no-op permutation of a given size |
| `Permutation.permutations( size )` | Every `Permutation` of a given size (`size!` of them) |
| `Permutation.permutationsOf( array )` | Every reordering of a specific array, as plain arrays (convenience over `permutations` + `apply`) |
| `Permutation.forEachPermutation( array, callback )` | Calls `callback` once per permutation without allocating all of them up front |

## `Combination`

A `Combination` wraps an `inclusions: boolean[]` array, one entry per index, marking whether that index is included in the subset.

| Member | Effect |
| --- | --- |
| `new Combination( inclusions )` | Wraps an explicit inclusions array |
| `size()` | Number of elements this combination is defined over |
| `includes( index )` | Whether a given index is included |
| `apply( array )` | Filters `array` down to just the included elements |
| `inverted()` | The complementary combination (every included index becomes excluded, and vice versa) |
| `getIncludedIndices()` | The included indices as a plain `number[]` |
| `equals( other )` | Structural equality on `inclusions` |
| `Combination.empty( size )` / `Combination.full( size )` | The all-excluded / all-included combination of a given size |
| `Combination.combinations( size )` | Every `Combination` of a given size (`2^size` of them) |
| `Combination.combinationsOf( array )` | Every subset of a specific array, as plain arrays |
| `Combination.forEachCombination( array, callback )` | Calls `callback` once per subset without allocating all of them up front |

::: warning Both scale factorially/exponentially — don't reach for these on large arrays
`Permutation.permutations( n )` produces `n!` instances and `Combination.combinations( n )` produces `2^n` — both classes are meant for exhaustively checking small, fixed-size sets (a handful of draggable pieces, a small puzzle's pieces), not for general-purpose array shuffling (use [`dotRandom.shuffle()`](/api/dot/dot-random) for that) or for enumerating anything with more than a dozen or so elements.
:::


========================================================================
Page: Quaternion and Plane3
URL: https://veillette.github.io/Almanach/api/dot/quaternion-and-plane3
Source: docs/api/dot/quaternion-and-plane3.md
Category: API | Tags: dot, Quaternion, Plane3, Vector3, Matrix3, rotation, math | Status: complete
========================================================================

# Quaternion and Plane3

`Quaternion` and `Plane3` (both from `scenerystack/dot`) are two independent 3D-geometry primitives commonly used together in 3D-flavored code (such as mobius): `Quaternion` represents a rotation without the gimbal-lock and interpolation problems of Euler angles, while `Plane3` represents an infinite plane for ray/plane intersection tests.

## Quaternion

A `Quaternion` holds four components `{x, y, z, w}` representing a rotation — informally, `{x, y, z}` as a (scaled) rotation axis and `w` encoding the rotation angle. Unlike a rotation matrix, quaternions compose cheaply and interpolate smoothly (`slerp`), which is why they're the standard representation for smoothly animating between two orientations.

```ts
import { Quaternion, Vector3 } from 'scenerystack/dot';

const q = Quaternion.fromEulerAngles( Math.PI / 4, 0, 0 ); // 45-degree yaw
const rotated: Vector3 = q.timesVector3( new Vector3( 1, 0, 0 ) );

const matrix = q.toRotationMatrix(); // convert to a Matrix3 for use with e.g. a transform

// Smoothly blend between two orientations, t in [0, 1]:
const halfway = Quaternion.slerp( q, Quaternion.fromEulerAngles( Math.PI / 2, 0, 0 ), 0.5 );
```

| Member | Effect |
| --- | --- |
| `new Quaternion( x, y, z, w )` | Constructs from raw components (default `w = 1`, i.e. identity, if omitted) |
| `plus( quat )` / `timesScalar( s )` | Component-wise addition / scaling, returning a new `Quaternion` |
| `timesQuaternion( quat )` | Hamilton product — composes two rotations (rotate by `this`, then by `quat`) |
| `timesVector3( v )` | Rotates a [`Vector3`](/api/dot/vector3) by this quaternion, returning a new `Vector3` |
| `magnitude` / `magnitudeSquared` | The quaternion's norm |
| `normalized()` | Rescales to magnitude 1 (a valid rotation must be a unit quaternion) |
| `negated()` | The quaternion with every component negated |
| `toRotationMatrix()` | Converts to an equivalent `Matrix3` rotation matrix |
| `Quaternion.fromEulerAngles( yaw, roll, pitch )` | Builds a quaternion from Euler angles |
| `Quaternion.fromRotationMatrix( matrix )` | Converts a `Matrix3` rotation matrix back to a quaternion |
| `Quaternion.getRotationQuaternion( a, b )` | A quaternion rotating unit vector `a` onto unit vector `b` |
| `Quaternion.slerp( a, b, t )` | Spherical linear interpolation between two quaternions, `t` in `[0, 1]` |

`Quaternion` is also `Poolable` (via phet-core's `Poolable.mixInto`), so performance-sensitive code can use `Quaternion.pool.fetch()`/`.freeToPool()` instead of `new Quaternion(...)` to avoid allocation churn, the same pattern `Vector2`'s pooled `v2()` shorthand follows.

## Plane3

A `Plane3` is an infinite plane in 3D, represented by a unit `normal` vector and a signed `distance` from the origin (so that `normal.timesScalar( distance )` is a point on the plane). It's the natural counterpart to [`Ray3`](/api/dot/ray3) for ray/plane intersection.

```ts
import { Plane3, Ray3, Vector3 } from 'scenerystack/dot';

const groundPlane = Plane3.XY; // the built-in x-y plane through the origin

const ray = new Ray3( new Vector3( 0, 0, 5 ), new Vector3( 0, 0, -1 ) );
const hitPoint = groundPlane.intersectWithRay( ray ); // Vector3(0, 0, 0)
```

| Member | Effect |
| --- | --- |
| `new Plane3( normal, distance )` | `normal` must be a unit `Vector3`; `distance` is the signed distance from the origin |
| `intersectWithRay( ray )` | The `Vector3` where a [`Ray3`](/api/dot/ray3) crosses this plane |
| `getIntersection( plane )` | The `Ray3` where two planes intersect (`null` if parallel) |
| `Plane3.fromTriangle( a, b, c )` | Builds the plane through three points, normal via `(c-a) x (b-a)` (`null` if the points are collinear) |
| `Plane3.XY` / `Plane3.XZ` / `Plane3.YZ` | The three axis-aligned planes through the origin |

::: warning Both classes assert unit-length inputs, but only in development builds
`Plane3`'s constructor asserts `normal` is a unit vector, exactly like `Ray3`'s `direction` and `Ray2`'s `direction` — but this check only runs with assertions enabled. Passing a non-normalized normal (or building a `Quaternion` you forgot to `.normalized()` before treating as a rotation) will silently produce wrong geometry in a production build instead of throwing. Normalize explicitly at the boundary where you construct these objects from arbitrary input.
:::


========================================================================
Page: Random
URL: https://veillette.github.io/Almanach/api/dot/random
Source: docs/api/dot/random.md
Category: API | Tags: dot, Random, dotRandom, math | Status: verified
========================================================================

# Random

`Random` (from `scenerystack/dot`) is a seedable pseudo-random number generator (built on [seedrandom.js](https://github.com/davidbau/seedrandom)), with helpers for booleans, integers, doubles in a range, gaussian samples, array sampling/shuffling, and weighted sampling. `scenerystack/dot` also exports `dotRandom`, a shared singleton instance of `Random` — sim code should reach for `dotRandom` rather than constructing a `new Random()` or calling `Math.random()` directly.

```ts
import { dotRandom } from 'scenerystack/dot';

dotRandom.nextDouble();               // [0, 1)
dotRandom.nextIntBetween( 1, 6 );      // an integer in [1, 6], inclusive
dotRandom.nextBoolean();               // true or false
dotRandom.sample( [ 'red', 'green', 'blue' ] ); // one randomly-chosen element
```

## Constructing your own instance

```ts
new Random( { seed?: number | null } )
```

The single options object is optional; if `seed` is omitted or `null`, a random seed is generated via `Math.random()` once at construction. Passing a fixed numeric `seed` makes the entire sequence of subsequent calls deterministic and reproducible — useful for tests, or for anything that needs the same "random" sequence across runs.

## Methods

| Method | Effect |
| --- | --- |
| `nextDouble()` | Next value in `[0, 1)`, uniformly distributed |
| `nextBoolean()` | `nextDouble() >= 0.5` |
| `nextInt( n )` | Next integer in `[0, n)` |
| `nextIntBetween( min, max )` | Next integer in `[min, max]` inclusive (both must be integers) |
| `nextDoubleBetween( min, max )` | Next double in `[min, max)` |
| `nextDoubleInRange( range )` | Next double within a [`Range`](/api/dot/range)'s `[min, max)` (or exactly `min` if `min === max`) |
| `nextGaussian()` | Next gaussian-distributed sample, mean 0, standard deviation 1 |
| `nextPointInBounds( bounds )` | A random [`Vector2`](/api/dot/vector2) within a [`Bounds2`](/api/dot/bounds2), `[minX,maxX) x [minY,maxY)` |
| `sample( array )` | One randomly-chosen element from a non-empty array |
| `shuffle( array )` | A new array with the same elements in Fisher-Yates-shuffled order |
| `sampleProbabilities( weights )` | A randomly-chosen index, weighted by the (not necessarily normalized) `weights` array |
| `getSeed()` | The seed this instance was constructed (or re-seeded) with |
| `setSeed( seed )` | Re-seeds the generator; `null` picks a new random seed via `Math.random()` |
| `numberOfCalls` | Public field tracking how many times `nextDouble()` has been called — read-only by convention, not by enforcement |

::: tip Use `dotRandom`, not `Math.random()`, in simulation code
SceneryStack simulations use the shared `dotRandom` singleton (not `new Random()` and not raw `Math.random()`) so that every "random" call in the sim funnels through one seed. This is what makes PhET-iO's seeded/reproducible playback and record-and-replay features work — if a sim's randomness comes from scattered `Math.random()` calls, a replayed session can diverge from the original. Reach for `new Random()` directly only when you deliberately want an isolated, independently-seeded generator (e.g. a self-contained test).
:::

## Related

- [Vector2](/api/dot/vector2) — `nextPointInBounds()` returns a `Vector2`.
- [Bounds2](/api/dot/bounds2) — the region `nextPointInBounds()` samples from.
- [Range](/api/dot/range) — `nextDoubleInRange()` takes a `Range` directly instead of separate `min`/`max` arguments.


========================================================================
Page: Range
URL: https://veillette.github.io/Almanach/api/dot/range
Source: docs/api/dot/range.md
Category: API | Tags: dot, Range | Status: verified
========================================================================

# Range

`Range` (from `scenerystack/dot`) is a simple `[min, max]` interval. It's most commonly seen as the `range` option passed to a `NumberProperty`, which sliders and number spinners use for their bounds, but it's a general-purpose interval type used anywhere a valid numeric interval needs a name.

```ts
import { Range } from 'scenerystack/dot';

const temperatureRange = new Range( 0, 100 );

temperatureRange.contains( 37 );          // true
temperatureRange.constrainValue( 150 );   // 100 — clamps into the range
temperatureRange.getCenter();             // 50
```

## Constructing a range

The constructor takes `min` and `max` directly: `new Range( min, max )`. Both `min` and `max` are also settable properties (`range.min = 10`), with an internal assertion that `min <= max` is maintained at all times.

| Static | Meaning |
| --- | --- |
| `Range.EVERYTHING` | `(-Infinity, Infinity)` |
| `Range.NOTHING` | `(Infinity, -Infinity)` — an inverted, "empty" range |

## Methods

| Method | Effect |
| --- | --- |
| `getLength()` | `max - min` |
| `getCenter()` | `(min + max) / 2` |
| `contains( value )` | Whether `value` is within `[min, max]`, inclusive |
| `containsRange( range )` | Whether this range fully contains another range |
| `intersects( range )` / `intersectsExclusive( range )` | Whether two ranges overlap |
| `constrainValue( value )` | Clamp a value into `[min, max]` |
| `getNormalizedValue( value )` / `expandNormalizedValue( t )` | Map a value to/from `[0, 1]` within the range |
| `union( range )` / `includeRange( range )` | Smallest range containing both — immutable / mutable pair |
| `intersection( range )` / `constrainRange( range )` | Largest range contained by both — immutable / mutable pair |
| `shifted( n )` | New range with both endpoints offset by `n` |
| `times( value )` / `multiply( value )` | Scale both endpoints — immutable / mutable pair |
| `addValue( n )` | Mutable: expand min/max, if needed, to include `n` |
| `withValue( n )` | Immutable counterpart of `addValue` |
| `copy()` | Clone |
| `equals( range )` / `equalsEpsilon( range, epsilon )` | Comparison |

## Common use: NumberProperty validation

```ts
import { NumberProperty } from 'scenerystack/axon';
import { Range } from 'scenerystack/dot';

const temperatureProperty = new NumberProperty( 20, {
  range: new Range( 0, 100 )
} );
```

`NumberProperty` uses its `range` option both to validate assignments in assertion-enabled builds and to give UI components (like sliders) their bounds automatically — see [NumberProperty](/api/axon/number-property).

::: tip `defaultValue` belongs to `RangeWithValue`, not `Range`
Reaching for `range.defaultValue` on a plain `Range` throws immediately — that field only exists on the related `RangeWithValue` subclass (also exported from `scenerystack/dot`), which pairs a range with a starting value for controls that need one (e.g. a reset-able slider). If you need a default alongside min/max, reach for `RangeWithValue` instead of trying to bolt one onto `Range`.
:::

## Related

- [NumberProperty](/api/axon/number-property) — the most common consumer of `Range`, via its `range` option.
- [Bounds2](/api/dot/bounds2) — `bounds.xRange` / `bounds.yRange` expose each axis of a bounds as a `Range`.
- [Utils](/api/dot/dot-utils) — `clamp()` is the free-function equivalent of `range.constrainValue()` when you don't have a `Range` object handy.


========================================================================
Page: RangeWithValue
URL: https://veillette.github.io/Almanach/api/dot/range-with-value
Source: docs/api/dot/range-with-value.md
Category: API | Tags: dot, RangeWithValue, Range | Status: verified
========================================================================

# RangeWithValue

`RangeWithValue` (from `scenerystack/dot`) extends [`Range`](/api/dot/range), adding a required `defaultValue` that must fall within `[min, max]`. It's the type [`Range`'s own docs](/api/dot/range) point to when you need a range *plus* a starting/reset value in one object — most useful for a control (like a slider) that needs to know both its bounds and where it should reset to.

```ts
import { RangeWithValue } from 'scenerystack/dot';

const volumeRange = new RangeWithValue( 0, 11, 5 ); // min 0, max 11, defaults to 5

volumeRange.defaultValue; // 5
volumeRange.min;          // 0
volumeRange.max;          // 11
volumeRange.contains( 7 ); // true — inherited from Range
```

## Constructing

The constructor takes `min`, `max`, and `defaultValue` directly: `new RangeWithValue( min, max, defaultValue )`. An assertion throws immediately if `defaultValue` falls outside `[min, max]`.

## What's added over `Range`

`RangeWithValue` is a `Range` — it inherits every method described on the [`Range`](/api/dot/range) page (`contains`, `constrainValue`, `union`, `getCenter`, etc.) unchanged. It adds:

| Member | Meaning |
| --- | --- |
| `defaultValue` (getter) | The default value passed to the constructor; there is no public setter — it's fixed for the life of the instance |
| `equals( other )` (overridden) | Also compares `defaultValue`, and requires `other` to be a `RangeWithValue` (not a plain `Range`) |
| `toString()` (overridden) | Includes `defaultValue` in the debug string |

`setMin`, `setMax`, and `setMinMax` are also overridden to add validation: each throws (via assertion) if the change would push `defaultValue` outside the new bounds. This is the one behavioral difference from `Range` beyond the extra field — a plain `Range` lets you move `min`/`max` freely, but a `RangeWithValue` won't let you strand its own default value outside the interval.

::: tip `defaultValue` has no setter — construct a new instance to change it
Unlike `min`/`max` (settable, with the validation above), `defaultValue` is fixed at construction. If a control's reset value needs to change, create a new `RangeWithValue` rather than trying to mutate the existing one's default.
:::

## Related

- [Range](/api/dot/range) — the base `[min, max]` interval type; `RangeWithValue` is a strict superset.
- [NumberProperty](/api/axon/number-property) — takes a `Range` via its `range` option; a `RangeWithValue` satisfies that option too (since it *is* a `Range`) and additionally lets code that already has the range object read a sensible default/reset value off of it, instead of tracking that value separately.


========================================================================
Page: Ray2
URL: https://veillette.github.io/Almanach/api/dot/ray2
Source: docs/api/dot/ray2.md
Category: API | Tags: dot, Ray2, math, hit-testing | Status: verified
========================================================================

# Ray2

`Ray2` (from `scenerystack/dot`) is a minimal 2D ray: an origin `position` and a unit-length `direction`, both [`Vector2`](/api/dot/vector2) instances. It's the type [`Transform3`](/api/dot/transform3)'s `transformRay2`/`inverseRay2` carry through a transform, and the natural representation for hit-testing/intersection queries (e.g. "does this pointer ray hit that shape").

```ts
import { Ray2 } from 'scenerystack/dot';
import { Vector2 } from 'scenerystack/dot';

const ray = new Ray2( new Vector2( 0, 0 ), new Vector2( 1, 0 ) ); // origin at (0,0), pointing along +x

ray.pointAtDistance( 5 );  // Vector2(5, 0) — the point 5 units along the ray
ray.shifted( 5 );          // a new Ray2 with the same direction, origin moved to (5, 0)
```

## Constructing

```ts
new Ray2( position: Vector2, direction: Vector2 )
```

Both fields are plain public properties, not getter/setter pairs. `direction` **must** be a unit vector (magnitude 1) — an assertion in development builds checks `Math.abs( direction.magnitude - 1 ) < 0.01` and throws if it's off. Passing a non-normalized vector is a common mistake; call `.normalized()` on it first if you're not sure it's already unit length.

## Methods

| Method | Effect |
| --- | --- |
| `pointAtDistance( distance )` | Returns `position.plus( direction.timesScalar( distance ) )` as a new `Vector2` — the point reached by walking `distance` along the ray |
| `shifted( distance )` | Returns a new `Ray2` with the same `direction`, whose origin is `pointAtDistance( distance )` |
| `toString()` | Debug string showing position and direction |

That's the full public surface on `Ray2` itself — it's deliberately a thin data holder. Most of the interesting ray behavior (transforming a ray, or intersecting it against a shape) lives on the *other* object: [`Transform3.transformRay2`](/api/dot/transform3)/`inverseRay2` carry a `Ray2` through a matrix transform, and kite `Shape`s expose their own intersection methods that accept a `Ray2`.

::: warning `direction` is not automatically kept normalized
Because `position` and `direction` are plain mutable fields, nothing stops you from reassigning `ray.direction` to a non-unit vector after construction — only the constructor asserts unit length, and only in assertion-enabled (development) builds. If you mutate a ray's direction after creating it, normalize it yourself first, or construct a fresh `Ray2` instead.
:::

## Related

- [Vector2](/api/dot/vector2) — both `position` and `direction` are `Vector2` instances.
- [Transform3](/api/dot/transform3) — `transformRay2`/`inverseRay2` carry a `Ray2` through a `Matrix3`-based transform.


========================================================================
Page: Ray3
URL: https://veillette.github.io/Almanach/api/dot/ray3
Source: docs/api/dot/ray3.md
Category: API | Tags: dot, Ray3, Vector3, Plane3, math, hit-testing | Status: complete
========================================================================

# Ray3

`Ray3` (from `scenerystack/dot`) is the 3D counterpart to [`Ray2`](/api/dot/ray2): an origin `position` and a unit-length `direction`, both [`Vector3`](/api/dot/vector3) instances. It's the representation used for picking/intersection queries in 3D-flavored code — for example, mobius's 3D scenes — such as "does this mouse ray hit that sphere or plane."

```ts
import { Ray3, Vector3 } from 'scenerystack/dot';

const ray = new Ray3( new Vector3( 0, 0, 5 ), new Vector3( 0, 0, -1 ) ); // pointing toward the origin

ray.pointAtDistance( 5 );          // Vector3(0, 0, 0) — 5 units along the ray from its origin
const shifted = ray.shifted( 2 );  // a new Ray3 with the same direction, origin moved 2 units along it
```

## Constructing

```ts
new Ray3( position: Vector3, direction: Vector3 )
```

Both fields are plain public properties. `direction` **must** be a unit vector — an assertion in development builds checks `Math.abs( direction.magnitude - 1 ) < 0.01` and throws if it's off, exactly as with `Ray2`.

## Methods

| Method | Effect |
| --- | --- |
| `pointAtDistance( distance )` | `position.plus( direction.timesScalar( distance ) )` — the point reached by walking `distance` along the ray |
| `shifted( distance )` | A new `Ray3` with the same `direction`, whose origin is `pointAtDistance( distance )` |
| `distanceToPlane( plane )` | The signed distance along the ray at which it crosses a given [`Plane3`](/api/dot/quaternion-and-plane3) |
| `toString()` | Debug string showing position and direction |

## Intersecting a ray with a plane

`Ray3` itself only computes the *distance* to a plane; combine it with [`Plane3.intersectWithRay()`](/api/dot/quaternion-and-plane3) to get the actual intersection point:

```ts
import { Ray3, Plane3, Vector3 } from 'scenerystack/dot';

const ray = new Ray3( new Vector3( 0, 0, 5 ), new Vector3( 0, 0, -1 ) );

const hitPoint = Plane3.XY.intersectWithRay( ray ); // Vector3(0, 0, 0)
```

::: tip There's no `Ray3`-vs-sphere or `Ray3`-vs-triangle method on `Ray3` itself
`Ray3` is a minimal data holder, like `Ray2` — it only knows how to walk along itself and measure distance to a plane. Sphere-ray intersection lives as the standalone `sphereRayIntersection` function (also exported from `scenerystack/dot`), and triangle/mesh picking is handled by the consuming 3D code (e.g. mobius), not by `Ray3` itself.
:::


========================================================================
Page: Transform3
URL: https://veillette.github.io/Almanach/api/dot/transform3
Source: docs/api/dot/transform3.md
Category: API | Tags: dot, Transform3, transform, matrix | Status: verified
========================================================================

# Transform3

`Transform3` (from `scenerystack/dot`) wraps a single [`Matrix3`](/api/dot/matrix3) and adds three things a bare matrix doesn't have: **lazily-cached** inverse/transpose/inverse-transpose matrices (recomputed only when the primary matrix changes), a `changeEmitter` that fires whenever the matrix is replaced, and a full family of typed convenience methods (`transformPosition2`, `transformBounds2`, `transformShape`, `transformRay2`, and their `inverse*` counterparts) instead of raw matrix multiplication.

::: tip Despite the name, this is a 2D (not 3D) transform
The "3" in `Transform3` refers to the 3x3 [`Matrix3`](/api/dot/matrix3) it wraps (for 2D homogeneous coordinates), not to three spatial dimensions — it operates on [`Vector2`](/api/dot/vector2), [`Bounds2`](/api/dot/bounds2), and 2D `Shape`s. If you're looking for the sim-facing model/view coordinate converter built on similar ideas, see [`ModelViewTransform2`](/api/phetcommon/model-view-transform) — it's a different, higher-level class (not a subclass of `Transform3`) purpose-built for physical-unit-to-pixel conversion, whereas `Transform3` is the lower-level, general-purpose "matrix plus caching plus change notification" utility that generic transform math (including parts of scenery's own `Node` transform tracking) is built on.
:::

```ts
import { Transform3 } from 'scenerystack/dot';
import { Matrix3 } from 'scenerystack/dot';
import { Vector2 } from 'scenerystack/dot';

const transform = new Transform3( Matrix3.rotation2( Math.PI / 2 ) );

transform.transformPosition2( new Vector2( 1, 0 ) ); // Vector2(0, 1) (approx)
transform.inversePosition2( new Vector2( 0, 1 ) );   // Vector2(1, 0) (approx) — undoes the forward transform

transform.changeEmitter.addListener( () => console.log( 'matrix changed' ) );
transform.append( Matrix3.scaling( 2 ) ); // notifies changeEmitter
```

## Constructing and mutating

The constructor optionally takes an initial `Matrix3` (defaults to the identity): `new Transform3( matrix? )`.

| Method | Effect |
| --- | --- |
| `setMatrix( matrix )` | Replaces the primary matrix (copies values in; doesn't retain the passed-in instance), invalidates caches, notifies `changeEmitter` |
| `prepend( matrix )` | `this.matrix = matrix * this.matrix` — applies `matrix` *after* whatever this transform already does |
| `append( matrix )` | `this.matrix = this.matrix * matrix` — applies `matrix` *before* whatever this transform already does |
| `prependTranslation( x, y )` | Optimized prepend of a pure translation |
| `prependTransform( transform )` / `appendTransform( transform )` | Same as `prepend`/`append`, but taking another `Transform3`'s matrix |
| `copy()` | A new `Transform3` with the same matrix (and cached state) |

## Reading the transform

| Getter | Meaning |
| --- | --- |
| `getMatrix()` | The primary `Matrix3` |
| `getInverse()` | The inverse matrix, computed on first access after a change and cached thereafter |
| `getMatrixTransposed()` / `getInverseTransposed()` | Cached transpose / inverse-transpose |
| `isIdentity()` | Whether the primary matrix is (very likely) the identity |
| `isFinite()` | Whether all matrix entries are finite |

## Forward and inverse transform methods

Every `transform*` method has an `inverse*` counterpart that applies the inverse matrix instead — conceptually, `transform.inverseThing( transform.transformThing( x ) )` should return something equal to `x`.

| Forward | Inverse | Applies to |
| --- | --- | --- |
| `transformPosition2( v )` | `inversePosition2( v )` | A [`Vector2`](/api/dot/vector2) point (translation applied) |
| `transformDelta2( v )` | `inverseDelta2( v )` | A `Vector2` displacement (translation **not** applied) |
| `transformNormal2( v )` | `inverseNormal2( v )` | A `Vector2` surface normal (uses the transposed inverse) |
| `transformX( x )` / `transformY( y )` | `inverseX( x )` / `inverseY( y )` | A single coordinate (throws in an assertion-enabled build if the matrix has rotation/shear, since the result would depend on the other axis) |
| `transformDeltaX( x )` / `transformDeltaY( y )` | `inverseDeltaX( x )` / `inverseDeltaY( y )` | A single-axis delta |
| `transformBounds2( bounds )` | `inverseBounds2( bounds )` | A [`Bounds2`](/api/dot/bounds2), re-fit to stay axis-aligned |
| `transformShape( shape )` | `inverseShape( shape )` | A kite `Shape` |
| `transformRay2( ray )` | `inverseRay2( ray )` | A [`Ray2`](/api/dot/ray2) |
| `applyToCanvasContext( context )` | — | Calls `context.setTransform(...)` with this transform's matrix |

## Related

- [Matrix3](/api/dot/matrix3) — the underlying matrix type; `Transform3` is a caching, observable wrapper around it.
- [Vector2](/api/dot/vector2) — the point/delta type most `Transform3` methods operate on.
- [Bounds2](/api/dot/bounds2) — `transformBounds2`/`inverseBounds2` re-fit a bounds through the transform.
- [Ray2](/api/dot/ray2) — `transformRay2`/`inverseRay2` carry a ray through the transform.
- [ModelViewTransform2](/api/phetcommon/model-view-transform) — the higher-level, sim-facing model/view coordinate converter with related but distinct semantics.


========================================================================
Page: Utils
URL: https://veillette.github.io/Almanach/api/dot/dot-utils
Source: docs/api/dot/dot-utils.md
Category: API | Tags: dot, Utils, math | Status: verified
========================================================================

# Utils

dot doesn't bundle its numeric helpers into a single `Utils` namespace object — instead, `scenerystack/dot` re-exports each helper as its own named function. They're grouped here as "the dot Utils" because that's how they're typically reached for: small, dependency-free numeric functions used throughout simulation code for clamping, mapping, and rounding numbers.

```ts
import { clamp, linear, roundSymmetric, toDegrees, toRadians } from 'scenerystack/dot';

clamp( 150, 0, 100 );             // 100
linear( 0, 1, 0, 100, 0.37 );      // 37 — maps 0.37 in [0,1] to [0,100]
roundSymmetric( -2.5 );            // -3 (not -2, unlike Math.round)
toDegrees( Math.PI );              // 180
toRadians( 180 );                  // Math.PI
```

## Core helpers

| Function | Signature | Effect |
| --- | --- | --- |
| `clamp` | `clamp( value, min, max ): number` | Constrains `value` to `[min, max]` |
| `linear` | `linear( a1, a2, b1, b2, a3 ): number` | Linear map: given `f(a1) = b1` and `f(a2) = b2`, returns `f(a3)` |
| `roundSymmetric` | `roundSymmetric( value ): number` | Rounds half-away-from-zero (symmetric for `+`/`-`, unlike `Math.round`) |
| `roundToInterval` | `roundToInterval( value, interval ): number` | Rounds `value` to the nearest multiple of `interval` |
| `toFixedNumber` | `toFixedNumber( value, decimalPlaces ): number` | Like `.toFixed()`, but returns a `number` and rounds symmetrically |
| `toDegrees` / `toRadians` | `toDegrees( radians )`, `toRadians( degrees )` | Angle unit conversion |
| `equalsEpsilon` | `equalsEpsilon( a, b, epsilon ): boolean` | Whether two numbers are within `epsilon` of each other |

## Other exported free functions

`scenerystack/dot` also exports several more specialized numeric helpers directly (not methods on a class): `mod`, `gcd`, `lcm`, `cubeRoot`, `log10`, `sinh`, `cosh`, `factorial`, `numberOfDecimalPlaces`, `triangleArea`/`triangleAreaSigned`, `centroidOfPolygon`, `distToSegment`/`distToSegmentSquared`, `lineLineIntersection`, `lineSegmentIntersection`, `solveLinearRootsReal`/`solveQuadraticRootsReal`/`solveCubicRootsReal`, and `arePointsCollinear`. Import whichever you need directly from `scenerystack/dot` by name.

## Typical use: mapping a physical quantity onto a display range

```ts
import { linear, clamp } from 'scenerystack/dot';

function temperatureToHue( temperatureCelsius: number ): number {
  // Map [0, 100] C onto a hue range [240, 0] (blue to red), clamping outliers first
  const clamped = clamp( temperatureCelsius, 0, 100 );
  return linear( 0, 100, 240, 0, clamped );
}
```

::: tip `roundSymmetric`, not `Math.round`, is the sim convention
`Math.round` uses "round half up," so `Math.round( -2.5 ) === -2`. SceneryStack simulations consistently use `roundSymmetric` instead, which rounds `-2.5` to `-3` — symmetric behavior for positive and negative numbers. Reach for `roundSymmetric` (and `roundToInterval` for rounding to steps other than 1) instead of the built-in `Math.round` when displaying rounded values to users.
:::

## Related

- [Range](/api/dot/range) — `range.constrainValue()` is the `Range`-aware equivalent of `clamp()`.
- [Vector2](/api/dot/vector2) — `Vector2.roundedSymmetric()` / `roundSymmetric()` apply `roundSymmetric` component-wise.


========================================================================
Page: Vector2
URL: https://veillette.github.io/Almanach/api/dot/vector2
Source: docs/api/dot/vector2.md
Category: API | Tags: dot, Vector2, math | Status: verified
========================================================================

# Vector2

`Vector2` (from `scenerystack/dot`) is the 2-dimensional `(x, y)` vector/point class used everywhere in SceneryStack — positions, velocities, drag deltas, and node translations all pass through it. It doubles as both a "point" and a "displacement" depending on context; there is no separate point type.

```ts
import { Vector2 } from 'scenerystack/dot';

const position = new Vector2( 3, 4 );

position.magnitude;      // 5, i.e. sqrt(3^2 + 4^2)
position.angle;           // Math.atan2( 4, 3 ), in radians

const moved = position.plus( new Vector2( 1, 0 ) ); // (4, 4) — new vector, position unchanged
position.add( new Vector2( 1, 0 ) );                 // (4, 4) — mutates position in place
```

## Constructing vectors

The constructor takes `x` and `y` directly: `new Vector2( x, y )`. There's also the pooled shorthand `v2( x, y )` (exported alongside `Vector2`) which reuses pooled instances for performance-sensitive code, and static constants:

| Static | Value |
| --- | --- |
| `Vector2.ZERO` | `(0, 0)` |
| `Vector2.X_UNIT` | `(1, 0)` |
| `Vector2.Y_UNIT` | `(0, 1)` |
| `Vector2.createPolar( magnitude, angle )` | Builds a vector from magnitude/angle instead of x/y |

## Immutable vs. mutable methods

Every operation on `Vector2` comes in two forms: an **immutable** version that returns a new vector, and a **mutable** version that changes `this` and returns it for chaining. The naming convention is consistent throughout dot: the immutable form usually reads as a noun/adjective (`plus`, `minus`, `times`, `normalized`, `rotated`), and the mutable form reads as a verb (`add`, `subtract`, `multiply`, `normalize`, `rotate`).

| Immutable (returns new `Vector2`) | Mutable (changes `this`, returns `this`) | Effect |
| --- | --- | --- |
| `plus( v )` / `plusXY( x, y )` / `plusScalar( s )` | `add( v )` / `addXY( x, y )` / `addScalar( s )` | Addition |
| `minus( v )` / `minusXY( x, y )` / `minusScalar( s )` | `subtract( v )` / `subtractXY( x, y )` / `subtractScalar( s )` | Subtraction |
| `times( s )` / `timesScalar( s )` | `multiply( s )` / `multiplyScalar( s )` | Scalar multiplication |
| `componentTimes( v )` | `componentMultiply( v )` | Component-wise multiplication |
| `dividedScalar( s )` | `divideScalar( s )` | Scalar division |
| `negated()` | `negate()` | Multiply by -1 |
| `normalized()` | `normalize()` | Rescale to magnitude 1 (throws on a zero vector) |
| `withMagnitude( m )` | `setMagnitude( m )` | Rescale to magnitude `m` |
| `rotated( angle )` | `rotate( angle )` | Rotate about the origin, radians |
| `rotatedAboutXY( x, y, angle )` / `rotatedAboutPoint( p, angle )` | `rotateAboutXY( x, y, angle )` / `rotateAboutPoint( p, angle )` | Rotate about an arbitrary point |
| `roundedSymmetric()` | `roundSymmetric()` | Round both components |
| `copy()` | `set( v )` / `setXY( x, y )` / `setX( x )` / `setY( y )` | Copy / assign |

Read-only queries (no mutable counterpart, since they don't change the vector): `magnitude`, `magnitudeSquared`, `angle`, `dot( v )` / `dotXY( x, y )`, `distance( point )` / `distanceXY( x, y )`, `distanceSquared( point )`, `crossScalar( v )` (the z-component of the 3D cross product), `angleBetween( v )`, `equals( v )` / `equalsEpsilon( v, epsilon )`, `isFinite()`, `perpendicular` (rotated -π/2), `blend( v, ratio )` / `average( v )`, and `toString()`.

## Common uses

```ts
import { Vector2 } from 'scenerystack/dot';

// Position tracked in a model, updated via a drag listener
const velocity = new Vector2( 2, -1 );
const dt = 0.016;

// Immutable style: compute a new position without touching the old one
const nextPosition = position.plus( velocity.timesScalar( dt ) );

// Mutable style: update a stored vector in place (common in performance-sensitive step() loops)
position.add( velocity.timesScalar( dt ) );
```

::: warning Mutable methods change shared state
Because plain object references are passed around freely, calling a mutable method (`add`, `normalize`, `rotate`, `set...`) on a `Vector2` that's stored in a `Property` or shared elsewhere will silently change it for every holder of that reference, **without notifying listeners** (a `Vector2Property` only fires when you call `.value = newVector`, not when you mutate the existing value in place). When in doubt, prefer the immutable form (`plus`, `normalized`, `rotated`, ...) for anything backing observable state, and reserve the mutable form for local scratch vectors.
:::

## Related

- [Vector3](/api/dot/vector3) — the 3D counterpart, used for color math and 3D-flavored sims.
- [Bounds2](/api/dot/bounds2) — axis-aligned rectangles built from `Vector2` corners/centers.
- [Matrix3](/api/dot/matrix3) — transforms that map `Vector2` positions via `multiplyVector2`.
- [ModelViewTransform2](/api/phetcommon/model-view-transform) — converts `Vector2` positions between model and view coordinates.


========================================================================
Page: Vector2Property
URL: https://veillette.github.io/Almanach/api/dot/vector2-property
Source: docs/api/dot/vector2-property.md
Category: API | Tags: dot, Vector2Property, Vector2, Property, position | Status: complete
========================================================================

# Vector2Property

`Vector2Property` (from `scenerystack/dot`) is a `Property<Vector2>` subclass — the standard type for a model's `positionProperty`, a drag target's location, or any other `Vector2`-valued piece of observable state. Beyond fixing `valueType: Vector2` and wiring up `Vector2.Vector2IO` for PhET-iO, it adds two validators of its own: it always rejects a vector with a `NaN` component, and it optionally confines every value to a [`Bounds2`](/api/dot/bounds2) region via the `validBounds` option.

```ts
import { Vector2Property } from 'scenerystack/dot';
import { Vector2, Bounds2 } from 'scenerystack/dot';

const positionProperty = new Vector2Property( new Vector2( 0, 0 ), {
  validBounds: new Bounds2( -100, -100, 100, 100 )
} );

positionProperty.link( position => console.log( 'position:', position ) );
positionProperty.value = new Vector2( 50, 50 ); // fine, inside validBounds
// positionProperty.value = new Vector2( 500, 0 ); // assertion failure: outside validBounds
```

Aside from these extra validators, `Vector2Property` behaves exactly like a plain `Property<Vector2>`: `.value`, `.link()`, `.reset()`, and every other member documented on [`Property`](/api/axon/property) work the same way.

## Constructor

```ts
new Vector2Property( initialValue: Vector2, providedOptions?: Vector2PropertyOptions )
```

`Vector2PropertyOptions` is `PropertyOptions<Vector2>` (see [Property's options](/api/axon/property#options)) minus `valueType`/`phetioValueType` (which `Vector2Property` fixes for you), plus:

| Option | Effect |
| --- | --- |
| `validBounds` | If provided, every value set on the Property must satisfy `validBounds.containsPoint( value )`; enforced via an assertion-only validator, so it has no effect in production builds without assertions |

::: tip Mutating the stored `Vector2` in place bypasses validation and listeners
Because `Vector2Property`'s validators (including `validBounds`) only run inside `set()`/`value=`, calling a mutating method directly on the currently-stored vector — `positionProperty.value.add( delta )` instead of `positionProperty.value = positionProperty.value.plus( delta )` — skips both the bounds check and listener notification entirely. Always reassign `.value` with a new `Vector2` (via `plus`, `plusXY`, etc.) rather than mutating the existing one in place; see the same caveat on [Vector2](/api/dot/vector2#immutable-vs-mutable-methods).
:::


========================================================================
Page: Vector3
URL: https://veillette.github.io/Almanach/api/dot/vector3
Source: docs/api/dot/vector3.md
Category: API | Tags: dot, Vector3, math | Status: verified
========================================================================

# Vector3

`Vector3` (from `scenerystack/dot`) is the 3-dimensional `(x, y, z)` counterpart to [`Vector2`](/api/dot/vector2). It shares the same immutable/mutable method-naming convention, plus a genuine 3D cross product. It shows up less often than `Vector2` in 2D sims, but is used for color math (RGB triples) and any 3D-flavored simulation content.

```ts
import { Vector3 } from 'scenerystack/dot';

const a = new Vector3( 1, 0, 0 );
const b = new Vector3( 0, 1, 0 );

a.cross( b );      // Vector3(0, 0, 1) — new vector, a and b unchanged
a.dot( b );         // 0
a.magnitude;         // 1
```

## Constructing vectors

The constructor takes `x`, `y`, and `z` directly: `new Vector3( x, y, z )`. The pooled shorthand `v3( x, y, z )` is also exported for allocation-sensitive code, along with static constants:

| Static | Value |
| --- | --- |
| `Vector3.ZERO` | `(0, 0, 0)` |
| `Vector3.X_UNIT` | `(1, 0, 0)` |
| `Vector3.Y_UNIT` | `(0, 1, 0)` |
| `Vector3.Z_UNIT` | `(0, 0, 1)` |

## Immutable vs. mutable methods

Just like `Vector2`, every operation comes in an immutable form (returns a new `Vector3`) and a mutable form (changes `this` and returns it).

| Immutable (returns new `Vector3`) | Mutable (changes `this`, returns `this`) | Effect |
| --- | --- | --- |
| `plus( v )` / `plusXYZ( x, y, z )` / `plusScalar( s )` | `add( v )` / `addXYZ( x, y, z )` / `addScalar( s )` | Addition |
| `minus( v )` / `minusXYZ( x, y, z )` / `minusScalar( s )` | `subtract( v )` / `subtractXYZ( x, y, z )` / `subtractScalar( s )` | Subtraction |
| `times( s )` / `timesScalar( s )` | `multiply( s )` / `multiplyScalar( s )` | Scalar multiplication |
| `componentTimes( v )` | `componentMultiply( v )` | Component-wise multiplication |
| `dividedScalar( s )` | `divideScalar( s )` | Scalar division |
| `negated()` | `negate()` | Multiply by -1 |
| `normalized()` | `normalize()` | Rescale to magnitude 1 (throws on a zero vector) |
| `withMagnitude( m )` | `setMagnitude( m )` | Rescale to magnitude `m` |
| `cross( v )` | `setCross( v )` | 3D cross product |
| `roundedSymmetric()` | `roundSymmetric()` | Round all three components |
| `copy()` | `set( v )` / `setXYZ( x, y, z )` / `setX( x )` / `setY( y )` / `setZ( z )` | Copy / assign |

Read-only queries: `magnitude`, `magnitudeSquared`, `dot( v )` / `dotXYZ( x, y, z )`, `distance( point )` / `distanceXYZ( x, y, z )`, `distanceSquared( point )`, `angleBetween( v )`, `equals( v )` / `equalsEpsilon( v, epsilon )`, `isFinite()`, `blend( v, ratio )` / `average( v )`, and `toString()`. A static `Vector3.slerp( start, end, ratio )` does spherical linear interpolation between two unit vectors.

::: tip No 2D cross product here
Unlike `Vector2.crossScalar()` (which returns a single number — the z-component of the equivalent 3D cross product), `Vector3.cross()` returns a full `Vector3`, since a genuine cross product only makes sense in three (or seven) dimensions.
:::

## Related

- [Vector2](/api/dot/vector2) — the 2D counterpart used for almost all on-screen positioning.
- [Matrix3](/api/dot/matrix3) — `Matrix3.rotationAxisAngle` and `Matrix3.rotateAToB` take `Vector3` axes.


========================================================================
Page: Vector4
URL: https://veillette.github.io/Almanach/api/dot/vector4
Source: docs/api/dot/vector4.md
Category: API | Tags: dot, Vector4, math | Status: verified
========================================================================

# Vector4

`Vector4` (from `scenerystack/dot`) is the 4-dimensional `(x, y, z, w)` counterpart to [`Vector2`](/api/dot/vector2) and [`Vector3`](/api/dot/vector3). It follows the exact same immutable/mutable naming convention as its lower-dimensional siblings, but has no cross product (a 4D cross product isn't a single well-defined operation the way it is in 3D). It's used wherever a fourth homogeneous or alpha component is needed — most notably as the operand type for [`Matrix4`](/api/dot/matrix4)'s `timesVector4`.

```ts
import { Vector4 } from 'scenerystack/dot';

const homogeneous = new Vector4( 1, 2, 3, 1 ); // a 3D point (1,2,3) in homogeneous form

homogeneous.magnitude;                  // sqrt(1^2 + 2^2 + 3^2 + 1^2)
const doubled = homogeneous.plus( new Vector4( 1, 0, 0, 0 ) ); // new vector, unchanged original
homogeneous.add( new Vector4( 1, 0, 0, 0 ) );                   // mutates in place
```

## Constructing vectors

The constructor takes all four components directly: `new Vector4( x, y, z, w )`. There's also the pooled shorthand `v4( x, y, z, w )` (exported alongside `Vector4`) for allocation-sensitive code, and static constants:

| Static | Value |
| --- | --- |
| `Vector4.ZERO` | `(0, 0, 0, 0)` |
| `Vector4.X_UNIT` | `(1, 0, 0, 0)` |
| `Vector4.Y_UNIT` | `(0, 1, 0, 0)` |
| `Vector4.Z_UNIT` | `(0, 0, 1, 0)` |
| `Vector4.W_UNIT` | `(0, 0, 0, 1)` |
| `Vector4.from( vector4Like, defaultW? )` | Builds a `Vector4` from any `{x?, y?, z?, w?}`-shaped object, defaulting missing `x`/`y`/`z` to `0` and missing `w` to `1` (or the given `defaultW`) |

## Immutable vs. mutable methods

Same convention as `Vector2`/`Vector3`: the immutable form returns a new `Vector4` and reads as a noun/adjective; the mutable form changes `this` and returns it, reading as a verb.

| Immutable (returns new `Vector4`) | Mutable (changes `this`, returns `this`) | Effect |
| --- | --- | --- |
| `plus( v )` / `plusXYZW( x, y, z, w )` / `plusScalar( s )` | `add( v )` / `addXYZW( x, y, z, w )` / `addScalar( s )` | Addition |
| `minus( v )` / `minusXYZW( x, y, z, w )` / `minusScalar( s )` | `subtract( v )` / `subtractXYZW( x, y, z, w )` / `subtractScalar( s )` | Subtraction |
| `times( s )` / `timesScalar( s )` | `multiply( s )` / `multiplyScalar( s )` | Scalar multiplication |
| `componentTimes( v )` | `componentMultiply( v )` | Component-wise multiplication |
| `dividedScalar( s )` | `divideScalar( s )` | Scalar division |
| `negated()` | `negate()` | Multiply by -1 |
| `normalized()` | `normalize()` | Rescale to magnitude 1 (throws on a zero vector) |
| `withMagnitude( m )` | `setMagnitude( m )` | Rescale to magnitude `m` |
| `roundedSymmetric()` | `roundSymmetric()` | Round all four components |
| `copy()` | `set( v )` / `setXYZW( x, y, z, w )` / `setX( x )` / `setY( y )` / `setZ( z )` / `setW( w )` | Copy / assign |

Read-only queries: `magnitude`, `magnitudeSquared`, `dot( v )` / `dotXYZW( x, y, z, w )`, `distance( point )` / `distanceXYZW( x, y, z, w )`, `distanceSquared( point )`, `angleBetween( v )`, `equals( v )` / `equalsEpsilon( v, epsilon )`, `isFinite()`, `blend( v, ratio )` / `average( v )`, and `toString()`.

::: tip Mostly a `Matrix4` operand, not a general-purpose vector
Unlike `Vector2`/`Vector3`, `Vector4` doesn't show up often as application-level state in sims — it mainly exists as the natural operand for [`Matrix4`](/api/dot/matrix4)'s homogeneous 4x4 math (`timesVector4`, `timesTransposeVector4`), where `w = 1` represents a point and `w = 0` represents a direction. If you're modeling an RGBA color or a plain 4-tuple without matrix math in mind, a `Vector4` still works fine, but there's no dedicated color type here — reach for `scenerystack/scenery`'s `Color` for actual color values.
:::

## Related

- [Vector2](/api/dot/vector2) — the 2D counterpart used for almost all on-screen positioning.
- [Vector3](/api/dot/vector3) — the 3D counterpart, used for color math and 3D-flavored sims.
- [Matrix4](/api/dot/matrix4) — the 4x4 matrix type that operates on `Vector4` via `timesVector4`.


========================================================================
Page: CreditsNode
URL: https://veillette.github.io/Almanach/api/joist/credits-node
Source: docs/api/joist/credits-node.md
Category: API | Tags: joist, CreditsNode, credits, AboutDialog, Sim | Status: complete
========================================================================

# CreditsNode

`CreditsNode` (from `scenerystack/joist`) is a `VBox` that renders a fixed, ordered set of credits fields — lead design, software development, team, contributors, quality assurance, graphic arts, sound design, and a final "thanks" note — as the content of the simulation's About dialog. `Sim`'s `credits` option (a `CreditsData` object) is what you actually populate; `CreditsNode` is what turns it into a laid-out `Node`, built automatically by joist's `AboutDialog` when credits are present.

```ts
import { Sim, onReadyToLaunch } from 'scenerystack/sim';
import type { CreditsData } from 'scenerystack/joist';
import { Property } from 'scenerystack/axon';

const credits: CreditsData = {
  leadDesign: 'Alice Example',
  softwareDevelopment: 'Bob Example, Carol Example',
  team: 'Dan Example (accessibility), Erin Example (physics)',
  qualityAssurance: 'Frank Example',
  thanks: 'Thanks to the Foo Foundation for supporting this project.'
};

onReadyToLaunch( () => {
  const sim = new Sim( new Property( 'My Simulation' ), [ /* screens */ ], { credits } );
  sim.start(); // AboutDialog builds a CreditsNode from `credits` the first time it's opened
} );
```

You won't typically construct `CreditsNode` yourself — it's what `AboutDialog` builds internally from `Sim`'s `credits` option — but its shape is documented here since `CreditsData`'s fields are exactly what a sim author fills in.

## `CreditsData`

Every field is an optional string; a field only renders a line if it's provided (non-empty):

| Field | Rendered as |
| --- | --- |
| `leadDesign` | "Lead Design: ..." |
| `softwareDevelopment` | "Software Development: ..." |
| `team` | "Team: ..." |
| `contributors` | "Contributors: ..." |
| `qualityAssurance` | "Quality Assurance: ..." |
| `graphicArts` | "Graphic Arts: ..." |
| `soundDesign` | "Sound Design: ..." |
| `thanks` | Rendered last, under its own "Thanks!" heading, with extra spacing above it if any other field was present |

## Constructor

```ts
new CreditsNode( credits: CreditsData, options: CreditsNodeOptions )
```

Unlike most Node subclasses, `options` here is not optional — `AboutDialog` always passes at least a `tandem`.

## Options

`CreditsNodeOptions` extends `VBoxOptions` with:

| Option | Default | Effect |
| --- | --- | --- |
| `titleFont` | 18px bold `PhetFont` | Font for the "Credits" heading and the "Thanks!" heading |
| `textFont` | 16px `PhetFont` | Font for every credits line |

`CreditsNode` also defaults `align: 'left'`, `spacing: 1`, and `maxWidth: 550` (each line wraps via `RichText`'s `lineWrap` at that width), and sets `children` internally.

::: tip Voicing and accessible structure come for free
Each credits line is a `VoicingRichText`/`VoicingText`, and the "Credits"/"Thanks!" headings are exposed as accessible headings (`accessibleHeading`) — using `CreditsNode` (via `Sim`'s `credits` option) gets you PDOM structure and Voicing support without any extra accessibility work in sim code.
:::


========================================================================
Page: HighlightNode
URL: https://veillette.github.io/Almanach/api/joist/highlight-node
Source: docs/api/joist/highlight-node.md
Category: API | Tags: joist, HighlightNode, navigation-bar, highlight | Status: complete
========================================================================

# HighlightNode

`HighlightNode` (from `scenerystack/joist`) draws the soft highlight bar joist uses behind navigation-bar buttons (screen icons, the PhET menu button, and similar) to indicate hover/press state — two thin vertical `Rectangle`s, each filled with a `LinearGradient` that fades from transparent at the top and bottom to a solid color in the middle, separated by a gap equal to the requested width.

```ts
import { HighlightNode } from 'scenerystack/joist';

const buttonHighlight = new HighlightNode( 40, 32, {
  fill: 'white',
  highlightWidth: 2
} );

buttonHighlight.visible = false; // toggle on hover/press, as NavigationBar's own buttons do
```

## Constructor

```ts
new HighlightNode( width: number, height: number, providedOptions?: HighlightNodeOptions )
```

`width` becomes the `HBox`'s `spacing` between the two bars (so it's the gap the highlight leaves open for the button content), and `height` sets both bars' rectangle height.

## Options

`HighlightNodeOptions` extends `HBoxOptions` with:

| Option | Default | Effect |
| --- | --- | --- |
| `fill` | `'white'` | The color at the gradient's center; `HighlightNode` derives a fully-transparent version of the same color for the gradient's top/bottom stops |
| `highlightWidth` | `1` | The width (thickness) of each of the two vertical bars |

`HighlightNode` also forces `pickable: false` (a highlight should never intercept input meant for the button it's decorating) and sets `children` internally — passing either as an option is redundant with what the constructor already does.

::: tip `HighlightNode` is purely decorative — visibility is your responsibility
`HighlightNode` doesn't listen to any pointer/focus state itself; it's a static pair of gradient rectangles. The Node that owns it (e.g. a navigation bar screen button) is responsible for toggling its `visible` property in response to hover/press/focus, typically via a [`PressListener`](/api/scenery/press-listener)'s `isHighlightedProperty`.
:::


========================================================================
Page: HomeScreen
URL: https://veillette.github.io/Almanach/api/joist/home-screen
Source: docs/api/joist/home-screen.md
Category: API | Tags: joist, HomeScreen, Screen, Sim | Status: verified
========================================================================

# HomeScreen

`HomeScreen` is itself a [`Screen`](/api/joist/screen) subclass — the one showing a grid of icon buttons, one per entry in `sim.simScreens`, so the user can pick which screen to run. `Sim` constructs a `HomeScreen` automatically whenever it's given more than one screen; with exactly one screen, there's nothing to choose between and no `HomeScreen` is created at all. You don't construct or configure a `HomeScreen` directly — it's entirely managed by `Sim` — but you do control what it shows via each screen's [`Screen`](/api/joist/screen) options (`name`, `homeScreenIcon`).

::: warning `HomeScreen` is exported from `scenerystack/sim`, not `scenerystack/joist`
Same gotcha as [`Sim`](/api/joist/sim), [`Screen`](/api/joist/screen), and [`ScreenIcon`](/api/joist/screen-icon): despite living in the `joist` repository, it's exported from **`scenerystack/sim`**.
:::

```ts
import { Sim, onReadyToLaunch } from 'scenerystack/sim';
import { Property } from 'scenerystack/axon';

onReadyToLaunch( () => {
  // Passing 2+ screens is what causes Sim to auto-create a HomeScreen.
  const sim = new Sim( new Property( 'My Simulation' ), [ firstScreen, secondScreen ] );
  sim.start();
  sim.screens[ 0 ]; // the auto-created HomeScreen (always first in sim.screens when one exists)
} );
```

## Constructor

```ts
new HomeScreen(
  simNameProperty: TReadOnlyProperty<string>,
  getScreenProperty: () => Property<AnyScreen>,
  simScreens: AnyScreen[],
  activeSimScreensProperty: ReadOnlyProperty<AnyScreen[]>,
  providedOptions: HomeScreenOptions
)
```

Constructed once by `Sim` during startup, when `allSimScreens.length > 1`; not intended to be called from simulation code.

## Behavior worth knowing

| Aspect | Detail |
| --- | --- |
| `sim.screens` vs `sim.simScreens` | `sim.screens` includes the auto-created `HomeScreen` first (when one exists); `sim.simScreens` excludes it — use `simScreens` when iterating "the sim's actual content screens" |
| `BACKGROUND_COLOR` (static) | Black — also what [`NavigationBar`](/api/joist/navigation-bar)'s fill matches while the home screen is selected, so the bar blends in rather than reading as a separate strip |
| `name` | Defaults to a localized "Home" label; not usually overridden |
| Icon buttons | Each button is built from the corresponding screen's `homeScreenIcon` (a [`ScreenIcon`](/api/joist/screen-icon)) and `name`; clicking one sets `sim.selectedScreenProperty` to that screen |
| `instrumentNameProperty` | `false` by default for `HomeScreen` (unlike ordinary screens) — its name isn't independently PhET-iO instrumented |

## Related

- [Sim](/api/joist/sim) — decides whether to auto-create a `HomeScreen`, based on `allSimScreens.length`.
- [Screen](/api/joist/screen) — the base class `HomeScreen` extends, and the source of the icons/names it displays.
- [ScreenIcon](/api/joist/screen-icon) — builds each screen's `homeScreenIcon`.
- [NavigationBar](/api/joist/navigation-bar) — matches its fill to `HomeScreen.BACKGROUND_COLOR` while the home screen is active.


========================================================================
Page: JoistButton
URL: https://veillette.github.io/Almanach/api/joist/joist-button
Source: docs/api/joist/joist-button.md
Category: API | Tags: joist, JoistButton, Sim, NavigationBar, button | Status: complete
========================================================================

# JoistButton

`JoistButton` (from `scenerystack/joist`) is the base class behind the chrome buttons that live directly in the [`NavigationBar`](/api/joist/navigation-bar) — `HomeButton`, the PhET-menu button, and similar — none of which use the ordinary `sun` button visuals. Instead of a fixed background rectangle, `JoistButton` draws two overlapping highlight shapes (one for a light background, one for a dark one) and shows whichever one is legible against the navigation bar's current fill, switching automatically as `sim.lookAndFeel`'s color changes (e.g. between the black home-screen background and a lighter in-sim navigation bar). You extend it directly only if you're building a custom navigation-bar-style button; ordinary in-sim UI should use `sun`'s regular button classes instead.

```ts
import { JoistButton } from 'scenerystack/joist';
import type { TReadOnlyProperty } from 'scenerystack/axon';
import type { Color, Node } from 'scenerystack/scenery';
```

## A minimal example

```ts
class MyChromeButton extends JoistButton {
  public constructor( content: Node, navigationBarFillProperty: TReadOnlyProperty<Color>, tandem: Tandem ) {
    super( content, navigationBarFillProperty, {
      tandem: tandem,
      listener: () => console.log( 'pressed' )
    } );
  }
}
```

## Constructor

```ts
new JoistButton(
  content: Node,
  navigationBarFillProperty: TReadOnlyProperty<Color>,
  providedOptions: JoistButtonOptions // tandem is required
)
```

`navigationBarFillProperty` is what drives the light/dark highlight swap — pass `sim.lookAndFeel.navigationBarFillProperty` (a `TReadOnlyProperty<Color>`) when building a real navigation-bar button.

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `listener` | `null` | Callback invoked when the button fires |
| `highlightExtensionWidth` / `highlightExtensionHeight` | `0` | Grows the highlight shape beyond `content`'s bounds |
| `highlightCenterOffsetX` / `highlightCenterOffsetY` | `0` | Shifts the highlight's center relative to `content`'s center |
| `pointerAreaDilationX` / `pointerAreaDilationY` | `0` | Expands mouse/touch areas beyond `content`'s bounds, to close gaps between adjacent chrome buttons and their labels |
| `focusHighlightDilationX` / `focusHighlightDilationY` | `0` | Expands the keyboard focus highlight independently of the pointer areas |
| `enabledPropertyOptions` | `{ phetioFeatured: false }` | `JoistButton`s intentionally default to a non-featured `enabledProperty`, unlike most `sun` buttons |

## Protected members (for subclasses)

| Member | Description |
| --- | --- |
| `buttonModel` | The underlying `PushButtonModel` driving press/release behavior |
| `interactionStateProperty` | A `PushButtonInteractionStateProperty` tracking over/pressed/idle state, used to decide which highlight is visible |

## Method

| Method | Effect |
| --- | --- |
| `isPDOMClicking()` | Whether the button is currently firing due to keyboard/screen-reader (PDOM) activation rather than pointer input |

::: tip The two highlight `Node`s are both always in the scene graph
`JoistButton` builds a `brightenHighlight` (white, for dark backgrounds) and a `darkenHighlight` (black, for light backgrounds) as siblings of `content` in every instance, and toggles their `visible` flags based on `navigationBarFillProperty` and interaction state rather than swapping children in and out. If you're customizing appearance by inspecting a `JoistButton`'s children, expect exactly three: `content`, `brightenHighlight`, `darkenHighlight`, in that order.
:::


========================================================================
Page: LookAndFeel
URL: https://veillette.github.io/Almanach/api/joist/look-and-feel
Source: docs/api/joist/look-and-feel.md
Category: API | Tags: joist, LookAndFeel, Sim, Screen, color, navigation-bar | Status: complete
========================================================================

# LookAndFeel

`LookAndFeel` (from `scenerystack/joist`) is a small class, one instance per running [`Sim`](/api/joist/sim), that owns the single source of truth for the currently-displayed screen's background color and derives the navigation bar's fill/text colors from it. A `Sim` creates its own `LookAndFeel` and exposes it as `sim.lookAndFeel`; each [`Screen`](/api/joist/screen)'s `backgroundColorProperty` is wired to update `lookAndFeel.backgroundColorProperty` whenever that screen is the one currently selected.

```ts
import { LookAndFeel } from 'scenerystack/joist';

// Typically accessed from the running Sim, not constructed directly by sim code:
declare const lookAndFeel: LookAndFeel;

lookAndFeel.backgroundColorProperty.link( backgroundColor => {
  console.log( 'Current screen background:', backgroundColor.toCSS() );
} );

console.log( lookAndFeel.navigationBarDarkProperty.value ); // true when the nav bar background is black
```

## Constructor

```ts
new LookAndFeel()
```

Takes no options — sim code virtually never constructs a `LookAndFeel` itself; use the one already created by `Sim` (`sim.lookAndFeel`).

## Public API

| Member | Description |
| --- | --- |
| `backgroundColorProperty` | `Property<Color>`, initially `Color.BLACK`. Set by `Sim` to track whichever screen is currently selected; this is also the `Color` applied to the `Display`'s `backgroundColor` |
| `navigationBarDarkProperty` | `TReadOnlyProperty<boolean>` — `true` exactly when `backgroundColorProperty` equals `Color.BLACK` |
| `navigationBarFillProperty` | `TReadOnlyProperty<Color>` — `white` when the background is black, `black` otherwise (i.e. the navigation bar always contrasts with the current screen background) |
| `navigationBarTextFillProperty` | `TReadOnlyProperty<Color>` — the readable text/icon color for whatever `navigationBarFillProperty` currently is (`white` text on a black nav bar, `black` text on a white nav bar) |
| `reset()` | Resets `backgroundColorProperty` to its initial value (`Color.BLACK`); the three derived Properties update automatically since they're `DerivedProperty`s |

## How this ties into `Screen`

Every `Screen` accepts a `backgroundColorProperty` option; whichever screen is currently active has its background color propagated into `sim.lookAndFeel.backgroundColorProperty` by `Sim`'s screen-selection logic. Because `navigationBarFillProperty`/`navigationBarTextFillProperty` are derived from that single Property, the navigation bar's contrast is automatically correct for every screen without each screen needing to compute or declare its own navigation bar colors.

::: tip Read from `LookAndFeel`, don't write to it, outside of `Sim` internals
The only Property on `LookAndFeel` meant to be set from outside is `backgroundColorProperty`, and even that is normally driven by `Sim`'s screen-switching logic rather than sim code setting it directly. Screen and view code should treat `lookAndFeel`'s Properties as read-only signals for "what should currently contrast well," not as a general-purpose theming API — for broader theming, use [`ColorProperty`/`ProfileColorProperty`](/api/scenery/color-property-and-profile-color-property).
:::


========================================================================
Page: NavigationBar
URL: https://veillette.github.io/Almanach/api/joist/navigation-bar
Source: docs/api/joist/navigation-bar.md
Category: API | Tags: joist, NavigationBar, Screen, Sim | Status: verified
========================================================================

# NavigationBar

`NavigationBar` is the strip shown at the bottom of every running [`Sim`](/api/joist/sim): the sim's title on the left, a row of per-[`Screen`](/api/joist/screen) buttons and a home button for multi-screen sims, and the PhET/accessibility menu buttons on the right. `Sim` constructs exactly one `NavigationBar` internally — you never build one yourself, and its constructor even takes the owning `Sim` instance as an argument. Documented here because you'll see it referenced when reading `Sim`/`Screen` internals or customizing sim chrome via [`LookAndFeel`](/api/joist/sim), and because its static size constants are occasionally useful for layout math.

```ts
import { NavigationBar } from 'scenerystack/sim';

NavigationBar.NAVIGATION_BAR_SIZE; // Dimension2 - the bar's un-scaled design size (width matches HomeScreenView's layout bounds; height 40)
```

::: tip You configure the navigation bar through `Screen` and `Sim`, not `NavigationBar` itself
As a sim author, everything you'd want to change about the navigation bar is exposed elsewhere: a screen's button icon and label come from [`Screen`](/api/joist/screen)'s `navigationBarIcon`/`name` options (built with [`ScreenIcon`](/api/joist/screen-icon)), and the bar's fill/text colors come from `Sim.lookAndFeel` (a `LookAndFeel` instance, exported from `scenerystack/joist`). There's no supported way to construct or restyle a `NavigationBar` directly.
:::

## Constructor

```ts
new NavigationBar( sim: Sim, tandem: Tandem )
```

Constructed once by `Sim` during startup; not intended to be called from simulation code.

## Behavior worth knowing

| Aspect | Detail |
| --- | --- |
| Single-screen sims | Shows only the sim title (left) and PhET/a11y buttons (right) — no home button or per-screen buttons, since there's nothing to switch between |
| Multi-screen sims | Adds a home button and one button per entry in `sim.simScreens`, laid out and centered via `ManualConstraint`, with each screen's width driven by its `navigationBarIcon`'s label |
| Fill when on the home screen | The bar's background matches `HomeScreen.BACKGROUND_COLOR` (black) while the home screen is selected, so it visually blends into the [`HomeScreen`](/api/joist/home-screen) rather than showing as a separate bar |
| `layout( scale, width, height )` | Called by `Sim` on window resize to rescale/reposition the bar's contents; not meant to be called directly by simulation code |

## Related

- [Sim](/api/joist/sim) — owns the single `NavigationBar` instance and its `lookAndFeel`.
- [Screen](/api/joist/screen) — supplies the `name`/`navigationBarIcon` each screen button displays.
- [ScreenIcon](/api/joist/screen-icon) — builds the icon `navigationBarIcon` expects.
- [HomeScreen](/api/joist/home-screen) — the screen the home button switches to, and whose background color the bar matches when selected.


========================================================================
Page: PreferencesModel and PreferencesDialog
URL: https://veillette.github.io/Almanach/api/joist/preferences-model-and-dialog
Source: docs/api/joist/preferences-model-and-dialog.md
Category: API | Tags: joist, PreferencesModel, PreferencesDialog, Sim, preferences | Status: verified
========================================================================

# PreferencesModel and PreferencesDialog

`PreferencesModel` is the configuration object you pass to [`Sim`](/api/joist/sim) to declare which Preferences features a simulation supports — projector mode, sound, voicing, gesture input, locale switching, and simulation-specific custom controls. `PreferencesDialog` is the tabbed dialog that renders whatever `PreferencesModel` describes; you never construct it yourself — `Sim` wires a `NavigationBarPreferencesButton` to build one lazily (`new PreferencesDialog( preferencesModel, ... )`) the first time the user opens it. This pairing is covered end-to-end, with a full example, in [Preferences and Feature Flags](/guides/preferences-and-feature-flags) — this page is the API-reference companion, focused on what each class actually exposes.

::: warning Both are exported from `scenerystack/sim`, not `scenerystack/joist`
Same gotcha as [`Sim`](/api/joist/sim) and [`Screen`](/api/joist/screen): despite living in the `joist` repository, both `PreferencesModel` and `PreferencesDialog` are exported from **`scenerystack/sim`**.
:::

```ts
import { Sim, onReadyToLaunch, PreferencesModel } from 'scenerystack/sim';
import { Property } from 'scenerystack/axon';

const preferencesModel = new PreferencesModel( {
  visualOptions: { supportsProjectorMode: true },
  audioOptions: { supportsSound: true, supportsExtraSound: true }
} );

onReadyToLaunch( () => {
  const sim = new Sim( new Property( 'My Simulation' ), [ /* screens */ ], { preferencesModel } );
  sim.start(); // Sim wires up the Preferences button; PreferencesDialog is built lazily on first click
} );
```

## `PreferencesModel`

### Constructor

```ts
new PreferencesModel( providedOptions?: PreferencesModelOptions )
```

### Options

| Option | Surfaces | Notable sub-options |
| --- | --- | --- |
| `simulationOptions` | The "Simulation" tab | `customPreferences` — your own controls; this tab only appears if you supply at least one |
| `visualOptions` | The "Visual" tab | `supportsProjectorMode`, `supportsInteractiveHighlights`, plus `customPreferences` |
| `audioOptions` | The "Audio" tab | `supportsSound`, `supportsExtraSound`, `supportsVoicing`, `supportsCoreVoicing`, plus `customPreferences` (which can specify a `column: 'left' \| 'right'`) |
| `inputOptions` | The "Input" tab | `supportsGestureControl`, plus `customPreferences` |
| `localizationOptions` | The "Localization" tab | `supportsDynamicLocale`, `includeLocalePanel`, plus `customPreferences` |

Every one of these is optional — an untouched `new PreferencesModel()` supports nothing extra, and `Sim`'s Preferences button only appears at all if `shouldShowDialog()` (below) is `true`.

### Public API

| Member | Description |
| --- | --- |
| `simulationModel`, `visualModel`, `audioModel`, `inputModel`, `localizationModel` | The resolved model for each tab (options merged with defaults, plus derived Properties like `visualModel.interactiveHighlightsEnabledProperty`) |
| `supportsSimulationPreferences()` / `supportsVisualPreferences()` / `supportsAudioPreferences()` / `supportsInputPreferences()` / `supportsLocalizationPreferences()` | Whether each tab has anything to show — `PreferencesDialog` uses these to decide which tabs to build |
| `shouldShowDialog()` | `true` if *any* tab would have content — `Sim` uses this to decide whether to show a Preferences button at all |

## `PreferencesDialog`

### Constructor

```ts
new PreferencesDialog( preferencesModel: PreferencesModel, providedOptions?: PreferencesDialogOptions )
```

You won't call this yourself in ordinary sim code — it's what `Sim`'s `NavigationBarPreferencesButton` constructs internally, once, the first time a user opens Preferences. `PreferencesDialog` is a `Dialog` subclass (see `scenerystack/sim`'s `Dialog`/`Popupable` re-exports), and is never disposed once created (`isDisposable: false`) — subsequent opens reuse the same instance.

### Behavior worth knowing

| Aspect | Detail |
| --- | --- |
| Tab selection | Built from whichever `supports*Preferences()` calls on `preferencesModel` return `true`; the "Overview" tab is always present |
| `focusSelectedTab()` | Public method to move keyboard focus to the currently selected tab — used when the dialog opens |
| Keyboard navigation | Arrow-down from the tab row moves focus into the selected panel; arrow-up from the panel moves focus back to the tab row |

::: tip Configure preferences through `PreferencesModel`; you'll rarely touch `PreferencesDialog`
Everything a sim author controls — which tabs appear, which toggles are in them, custom per-sim controls — is a `PreferencesModel` option. `PreferencesDialog` exists mostly so its shape is documented; the only thing you'd construct one for directly is testing/exploratory code, not ordinary sim wiring.
:::

## Related

- [Preferences and Feature Flags](/guides/preferences-and-feature-flags) — the narrative walkthrough this reference page complements, including query-parameter interactions.
- [Sim](/api/joist/sim) — takes `preferencesModel` as a `SimOptions` field and owns the Preferences button that lazily builds the dialog.


========================================================================
Page: PreferencesPanel, PreferencesPanelSection, PreferencesControl, PreferencesTabs, and PreferencesTab
URL: https://veillette.github.io/Almanach/api/joist/preferences-panel-components
Source: docs/api/joist/preferences-panel-components.md
Category: API | Tags: joist, PreferencesPanel, PreferencesPanelSection, PreferencesControl, PreferencesTabs, PreferencesTab, PreferencesModel, PreferencesDialog | Status: complete
========================================================================

# PreferencesPanel, PreferencesPanelSection, PreferencesControl, PreferencesTabs, and PreferencesTab

[`PreferencesModel` and `PreferencesDialog`](/api/joist/preferences-model-and-dialog) documents the dialog as a whole; this page covers the five smaller pieces (all from `scenerystack/joist`) it's assembled from. Two of them — **`PreferencesPanelSection`** and **`PreferencesControl`** — are the ones sim authors actually construct, via a `PreferencesModel` option's `customPreferences: [{ createContent: ( parentTandem ) => Node }]`. The other three — **`PreferencesPanel`**, **`PreferencesTabs`**, and **`PreferencesTab`** — are the scaffolding `PreferencesDialog` uses internally to build each tab and its panel; documented here for completeness, but you won't normally construct them yourself.

```ts
import { PreferencesModel, Sim, onReadyToLaunch } from 'scenerystack/sim';
import { PreferencesPanelSection, PreferencesControl } from 'scenerystack/joist';
import { Text } from 'scenerystack/scenery';
import { ToggleSwitch } from 'scenerystack/sun';
import { BooleanProperty, Property } from 'scenerystack/axon';

const showGridProperty = new BooleanProperty( false );

const preferencesModel = new PreferencesModel( {
  simulationOptions: {
    customPreferences: [ {
      createContent: parentTandem => {
        const label = new Text( 'Show grid' );
        const toggle = new ToggleSwitch( showGridProperty, false, true, {
          tandem: parentTandem.createTandem( 'showGridSwitch' )
        } );

        // PreferencesControl handles the label/control/description layout for you.
        const control = new PreferencesControl( {
          labelNode: label,
          controlNode: toggle
        } );

        // PreferencesPanelSection adds the standard section spacing/indentation.
        return new PreferencesPanelSection( { contentNode: control } );
      }
    } ]
  }
} );

onReadyToLaunch( () => {
  const sim = new Sim( new Property( 'My Simulation' ), [ /* screens */ ], { preferencesModel } );
  sim.start();
} );
```

## `PreferencesControl`

A `GridBox` that lays out an optional `labelNode`, an optional `controlNode`, and an optional `descriptionNode` in the standard Preferences arrangement — label and control on one row, a full-width description below — and wires up sensible accessibility defaults between them.

| Option | Default | Effect |
| --- | --- | --- |
| `labelNode` | — | Node placed at the left of the control's row |
| `controlNode` | — | The actual UI control (a switch, radio buttons, combo box, …); right-aligned |
| `descriptionNode` | — | Node placed below the label/control row, spanning both columns |
| `labelSpacing` | `10` | Horizontal gap between `labelNode` and `controlNode` when there's no `descriptionNode` |
| `ySpacing` | `5` | Vertical gap between the label/control row and `descriptionNode` |
| `allowDescriptionStretch` | `true` | If `true`, the description cell stretches to a minimum content width (`480`) so the control aligns with other controls in the panel |
| `headingControl` | `false` | Set `true` for a control acting as a section heading — it won't stretch to fill the row like an ordinary control does |

If `controlNode` has no `accessibleName`/`accessibleHelpText` already set, `PreferencesControl` derives them from `labelNode`/`descriptionNode`'s text automatically. `PreferencesControl` also manages `disabledOpacity` on itself, so nesting it inside another disableable container doesn't compound dimming.

## `PreferencesPanelSection`

A `VBox` providing the standard vertical spacing and title/content indentation for one logical group of preferences within a tab.

| Option | Default | Effect |
| --- | --- | --- |
| `titleNode` | `null` | If provided, a heading for this section |
| `contentNode` | `null` | If provided, the section's body — indented under `titleNode` by `contentLeftMargin` |
| `contentLeftMargin` | `30` | Indentation applied to `contentNode` when a `titleNode` is also present |
| `contentNodeOptions` | `{}` | Extra `NodeOptions` applied to the wrapper around `contentNode` |

For a `customPreferences` entry with just one control and no separate heading (as in the example above), passing only `contentNode` (no `titleNode`) is the common case.

## `PreferencesPanel`

The `Node` base class each of joist's built-in tab panels (Simulation, Visual, Audio, Input, Localization) extends. Its entire job is visibility: it shows itself only when `selectedTabProperty` matches its own `PreferencesType` **and** `tabVisibleProperty` is `true`.

```ts
new PreferencesPanel(
  preferencesType: PreferencesType,
  selectedTabProperty: TReadOnlyProperty<PreferencesType>,
  tabVisibleProperty: TReadOnlyProperty<boolean>,
  providedOptions?: PreferencesPanelOptions
)
```

You would only construct one directly if building an entirely custom Preferences tab structure outside of `PreferencesModel`'s supported tabs — ordinary `customPreferences` content does not need to touch `PreferencesPanel` at all, since it's nested inside whichever built-in panel (Simulation/Visual/Audio/Input/Localization) you attached it to.

## `PreferencesTabs` and `PreferencesTab`

`PreferencesTabs` is the `HBox` of tab buttons across the top of the dialog (implemented as `role="tablist"`/`role="tab"` for accessibility, with arrow-key navigation between tabs built in); `PreferencesTab` is a single tab button within it, associated with one `PreferencesType` value.

```ts
new PreferencesTabs(
  supportedTabs: PreferencesType[],
  selectedPanelProperty: TProperty<PreferencesType>,
  providedOptions: PreferencesTabsOptions // tandem is required
)

new PreferencesTab(
  labelProperty: TReadOnlyProperty<string>,
  property: TProperty<PreferencesType>,
  value: PreferencesType,
  providedOptions: PreferencesTabOptions // tandem is required
)
```

`PreferencesTabs` builds one `PreferencesTab` per entry in `supportedTabs` that matches a known `PreferencesType` (`OVERVIEW`, `SIMULATION`, `VISUAL`, `AUDIO`, `INPUT`, `LOCALIZATION` — the `LOCALIZATION` tab additionally gets a globe icon). `PreferencesTabs.focusSelectedTab()` (surfaced on `PreferencesDialog` too, see [PreferencesModel and PreferencesDialog](/api/joist/preferences-model-and-dialog)) moves keyboard focus to whichever tab is currently selected.

::: tip For ordinary custom preferences, you only need `PreferencesPanelSection` and `PreferencesControl`
`PreferencesModel`'s `customPreferences.createContent` callback is expected to return a single `Node` — nesting your control(s) in `PreferencesControl` (for label/control/description layout) inside `PreferencesPanelSection` (for standard section spacing) is enough to match the built-in tabs' look. `PreferencesPanel`/`PreferencesTabs`/`PreferencesTab` are the dialog's own scaffolding, not something a `customPreferences` entry needs to construct.
:::


========================================================================
Page: Region, Culture, and Locale Selection UI
URL: https://veillette.github.io/Almanach/api/joist/region-culture-and-locale-selection
Source: docs/api/joist/region-culture-and-locale-selection.md
Category: API | Tags: joist, LocalizedImageProperty, RegionAndCultureComboBox, LanguageSelectionNode, LocalePanel, localeProperty, regionAndCultureProperty, i18n | Status: complete
========================================================================

# Region, Culture, and Locale Selection UI

SceneryStack draws a line between two independent runtime i18n concerns, each with its own global singleton `Property` (both exported from `scenerystack/joist`): **`localeProperty`** controls which *language* strings are displayed in, and **`regionAndCultureProperty`** controls how *images/illustrations* are styled — the region-and-culture of the people and objects depicted — independent of language. A sim can support one without the other. Both are surfaced to end users through the "Localization" tab of the Preferences dialog (see [PreferencesModel and PreferencesDialog](/api/joist/preferences-model-and-dialog)), built from the UI classes documented below.

```ts
import {
  localeProperty,
  regionAndCultureProperty,
  LocalizedImageProperty,
  RegionAndCultureComboBox,
  LanguageSelectionNode,
  LocalePanel
} from 'scenerystack/joist';
```

## `localeProperty` — which language is displayed

`localeProperty` is a module-level singleton `LocaleProperty` (a `Property<Locale>` subclass), initialized from `phet.chipper.locale` and instrumented at `Tandem.GENERAL_MODEL.createTandem('localeProperty')`. Setting its value re-renders every `StringProperty`-backed string in the sim — see [Translation and Localization](/guides/translation-and-localization) for how strings react to it.

```ts
localeProperty.value; // e.g. 'es' — the current Locale
localeProperty.availableRuntimeLocales; // Locale[] actually built into this sim
localeProperty.supportsDynamicLocale; // false if only one locale was built — switching is pointless
```

| Member | Description |
| --- | --- |
| `availableRuntimeLocales` | `Locale[]`, sorted by each locale's localized display name — the full set this build supports |
| `supportsDynamicLocale` | `true` only when `availableRuntimeLocales.length > 1` |
| `isLocaleChanging` | `true` while a locale switch is in progress, so listeners can opt out of redundant work mid-switch |

## `regionAndCultureProperty` — how images are styled

`regionAndCultureProperty` is a separate singleton `Property<RegionAndCulture>`, where `RegionAndCulture` is one of `'usa' | 'africa' | 'africaModest' | 'asia' | 'latinAmerica' | 'oceania' | 'random'`. Its runtime choices are narrowed to `supportedRegionAndCultureValues` — derived from `"supportedRegionsAndCultures"` in the sim's `package.json`, always including `'usa'` (`DEFAULT_REGION_AND_CULTURE`) as the guaranteed fallback. It's only instrumented (given a real tandem instead of `Tandem.OPT_OUT`) when more than one value is actually supported.

```ts
import type { RegionAndCulture } from 'scenerystack/joist';

regionAndCultureProperty.value; // e.g. 'africa'
```

### `LocalizedImageProperty` — region-varying images

`LocalizedImageProperty` is a `DerivedProperty1<ImageableImage, ConcreteRegionAndCulture>` that picks an image out of a map keyed by region-and-culture, re-deriving whenever `regionAndCultureProperty`'s *concrete* value (the resolved value, with `'random'` already picked) changes. You build one per region-varying illustration:

```ts
import handSoap_usa_png from '../../images/handSoap_usa_png.js';
import handSoap_africa_png from '../../images/handSoap_africa_png.js';

const handSoapImageProperty = new LocalizedImageProperty( 'handSoap', {
  usa: handSoap_usa_png,     // required — the guaranteed fallback
  africa: handSoap_africa_png
  // any concrete RegionAndCulture you omit falls back to asserting at construction time
} );
```

`usa` is required in the image map (it's the fallback), and every other *concrete* region-and-culture value the sim declares support for must also have an entry, or construction asserts.

## The Preferences "Localization" UI

Three joist classes build the panels a sim's Preferences dialog shows for these two Properties — you rarely construct them directly (they're wired up automatically when `PreferencesModel`'s `localizationOptions` are configured), but you'll encounter them reading Preferences internals:

| Class | Role |
| --- | --- |
| `RegionAndCultureComboBox` | A `ComboBox<RegionAndCulture>` bound to `regionAndCultureProperty`, listing `supportedRegionAndCultureValues` sorted and localized; shown in Preferences > Localization when more than one value is supported |
| `LanguageSelectionNode` | A single clickable `Rectangle` showing one locale's localized name; clicking it sets `localeProperty.value` to that locale and highlights the currently-selected one |
| `LocalePanel` | A `Panel` laying out one `LanguageSelectionNode` per entry in `localeProperty.availableRuntimeLocales`, in a `GridBox` — the full language picker shown in Preferences > Localization |

```ts
// Roughly what PreferencesModel builds internally when includeLocalePanel is true:
const localePanel = new LocalePanel( localeProperty );
```

::: tip Preferences UI components are not PhET-iO instrumented
`RegionAndCultureComboBox` and `LanguageSelectionNode`'s internal listeners deliberately use `Tandem.OPT_OUT` — Preferences controls are considered part of the platform chrome, not part of a sim's own instrumented API surface (see the `joist#744` discussion referenced in source comments). Don't expect to find these under a sim's PhET-iO tree; `localeProperty` and `regionAndCultureProperty` themselves *are* instrumented (under `Tandem.GENERAL_MODEL`), but the buttons that drive them are not.
:::


========================================================================
Page: Screen
URL: https://veillette.github.io/Almanach/api/joist/screen
Source: docs/api/joist/screen.md
Category: API | Tags: joist, Screen | Status: verified
========================================================================

# Screen

`Screen` is the largest organizational chunk inside a [`Sim`](/api/joist/sim): it pairs a model factory and a view factory into one selectable unit, shown as a button in the navigation bar (and, for multi-screen sims, on the home screen). `Screen` doesn't build the model or view itself — it holds *functions* that build them lazily, plus the name/icons/background color used to represent the screen in the UI.

::: warning `Screen` is exported from `scenerystack/sim`, not `scenerystack/joist`
Same gotcha as [`Sim`](/api/joist/sim): despite living in the `joist` repository, the published package exports `Screen` from **`scenerystack/sim`**, alongside `Sim` and [`ScreenView`](/api/joist/screen-view).
:::

```ts
import { Screen } from 'scenerystack/sim';
import { Tandem } from 'scenerystack/tandem';
import { Property } from 'scenerystack/axon';
```

## A minimal example

```ts
const screenTandem = Tandem.ROOT.createTandem( 'myScreen' );

const myScreen = new Screen(
  () => new MyModel(),
  model => new MyScreenView( model, { tandem: screenTandem.createTandem( 'view' ) } ),
  {
    name: new Property( 'My Screen' ),
    backgroundColorProperty: new Property( 'white' ),
    tandem: screenTandem
  }
);
```

## Constructor

```ts
new Screen<M extends TModel, V extends ScreenView>(
  createModel: () => M,
  createView: ( model: M ) => V,
  providedOptions: ScreenOptions
)
```

`createModel` and `createView` are called lazily by the owning `Sim` (only once the screen is actually needed), not eagerly at `Screen` construction time. `tandem` is the one option that's always required — everything else has a usable default for a single-screen sim.

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `name` | `null` | A `Property<string>` shown as the screen's label; required for multi-screen sims, may be omitted for single-screen sims |
| `backgroundColorProperty` | `Property( 'white' )` | Background color behind the screen's view |
| `homeScreenIcon` | auto-generated rectangle | Icon shown on the home screen button for this screen |
| `navigationBarIcon` | defaults to `homeScreenIcon`, scaled | Icon shown in the navigation bar; both icons must share the same aspect ratio |
| `showUnselectedHomeScreenIconFrame` | `false` | Whether to draw a frame around this screen's home-screen icon when it isn't selected |
| `showScreenIconFrameForNavigationBarFill` | `null` | Draw a frame around the navigation bar icon when the bar's fill is `'black'` or `'white'` (or `null` for no frame) |
| `maxDT` | `0.5` | Caps the `dt` passed to the model/view per frame, to avoid large jumps after e.g. a background tab resumes |
| `createKeyboardHelpNode` | `null` | `( tandem ) => Node` building the content shown in the keyboard-help dialog for this screen |
| `screenButtonsHelpText` | derived from `name` | Accessible help text on the home screen and navigation bar buttons for this screen |
| `instrumentNameProperty` | `true` | Whether `nameProperty` is instrumented for PhET-iO |

## Public API

| Member | Description |
| --- | --- |
| `model` | The constructed model (getter) — asserts if accessed before `initializeModel()` has run |
| `view` | The constructed [`ScreenView`](/api/joist/screen-view) (getter) — asserts if accessed before `initializeView()` has run |
| `hasModel()` / `hasView()` | Whether the model/view have been constructed yet |
| `activeProperty` | `BooleanProperty` — whether this screen is the one currently displayed |
| `nameProperty` | `TReadOnlyProperty<string>` — the screen's display name (empty string if `name` was omitted) |
| `reset()` | Called by `ResetAllButton` handling; the base implementation is a no-op (background color is intentionally not reset here) |

::: tip Model and view aren't built until the screen is needed
`createModel`/`createView` are only invoked once, lazily, when `Sim` initializes that screen — this is what lets multi-screen sims start up faster by deferring work for screens the user hasn't visited yet. Don't rely on side effects in the constructor of a not-yet-selected screen having already run.
:::


========================================================================
Page: ScreenIcon
URL: https://veillette.github.io/Almanach/api/joist/screen-icon
Source: docs/api/joist/screen-icon.md
Category: API | Tags: joist, ScreenIcon, Screen | Status: verified
========================================================================

# ScreenIcon

`ScreenIcon` is a `Node` that wraps an arbitrary icon `Node` in a fixed-size background rectangle, automatically scaling and centering the icon to fit — it's the standard way to build the `homeScreenIcon`/`navigationBarIcon` options a [`Screen`](/api/joist/screen) takes. Without it, you'd have to hand-compute scale factors and centering every time an icon's own bounds change (e.g. because it contains a string `Property` that changes with locale).

::: warning `ScreenIcon` is exported from `scenerystack/sim`, not `scenerystack/joist`
Same gotcha as [`Screen`](/api/joist/screen), [`Sim`](/api/joist/sim), and [`ScreenView`](/api/joist/screen-view): despite living in the `joist` repository, it's exported from **`scenerystack/sim`**.
:::

```ts
import { Screen, ScreenIcon } from 'scenerystack/sim';
import { Circle } from 'scenerystack/scenery';

const homeScreenIcon = new ScreenIcon( new Circle( 40, { fill: 'blue' } ), {
  fill: 'white'
} );

const myScreen = new Screen( createModel, createView, {
  name: myScreenNameProperty,
  homeScreenIcon: homeScreenIcon,
  tandem: screenTandem
} );
```

## Constructor

```ts
new ScreenIcon( iconNode: Node, providedOptions?: ScreenIconOptions )
```

`iconNode` is made `pickable: false` internally (icons shouldn't intercept input), and a listener on `iconNode.localBoundsProperty` keeps it centered and re-scaled if its bounds ever change after construction.

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `size` | `Screen.MINIMUM_HOME_SCREEN_ICON_SIZE` (`Dimension2( 548, 373 )`) | Size of the background rectangle. There's no `ScreenIcon.MINIMUM_HOME_SCREEN_ICON_SIZE` static — the default value is mirrored on `Screen` (and also importable as the standalone `MINIMUM_HOME_SCREEN_ICON_SIZE` export). Pass `Screen.MINIMUM_NAVBAR_ICON_SIZE` when building a `navigationBarIcon` specifically, so it matches the navigation bar's smaller aspect |
| `maxIconWidthProportion` | `0.85` | Max proportion of the background's width the icon is scaled to fill |
| `maxIconHeightProportion` | `0.85` | Max proportion of the background's height the icon is scaled to fill |
| `fill` | `'white'` | Background rectangle fill |
| `stroke` | `null` | Background rectangle stroke |

`iconNode` is scaled uniformly (never stretched) by `Math.min` of the two proportion-based limits, then centered on the background — so a non-square icon never overflows either dimension.

::: tip `homeScreenIcon` and `navigationBarIcon` must share the same aspect ratio
`Screen` asserts this at construction time, because the navigation bar's icon is effectively a scaled-down version of the home screen's — if you only build one `ScreenIcon`, `navigationBarIcon` defaults to a scaled copy of `homeScreenIcon`, which is usually what you want. Build `navigationBarIcon` separately (with `size: Screen.MINIMUM_NAVBAR_ICON_SIZE`) only if the two icons genuinely need different content, not just different sizes.
:::

## Related

- [Screen](/api/joist/screen) — the `homeScreenIcon`/`navigationBarIcon` options that consume a `ScreenIcon`.
- [HomeScreen](/api/joist/home-screen) — renders each sim screen's `homeScreenIcon` as a selectable button.
- [NavigationBar](/api/joist/navigation-bar) — renders each sim screen's `navigationBarIcon`.


========================================================================
Page: ScreenView
URL: https://veillette.github.io/Almanach/api/joist/screen-view
Source: docs/api/joist/screen-view.md
Category: API | Tags: joist, ScreenView | Status: verified
========================================================================

# ScreenView

`ScreenView` is a `Node` subclass that serves as the root of a [`Screen`](/api/joist/screen)'s view. It defines `layoutBounds` — a fixed design-time coordinate frame you lay content out against — and `visibleBoundsProperty`, which tracks how much of that coordinate frame is actually visible after `Sim` scales/letterboxes it to fit the real browser window.

::: warning `ScreenView` is exported from `scenerystack/sim`, not `scenerystack/joist`
Same gotcha as [`Sim`](/api/joist/sim) and [`Screen`](/api/joist/screen): despite living in the `joist` repository, it's exported from **`scenerystack/sim`**.
:::

```ts
import { ScreenView, type ScreenViewOptions } from 'scenerystack/sim';
import { Text } from 'scenerystack/scenery';
```

## A minimal example

```ts
class MyScreenView extends ScreenView {
  public constructor( model: MyModel, providedOptions: ScreenViewOptions ) {
    super( providedOptions );

    const greetingText = new Text( 'Hello, SceneryStack!', {
      font: '24px sans-serif'
    } );
    greetingText.center = this.layoutBounds.center;
    this.addChild( greetingText );
  }
}
```

## Constructor

```ts
new ScreenView( providedOptions?: ScreenViewOptions )
```

`tandem` defaults to `Tandem.REQUIRED` and, when instrumented, is asserted to be named exactly `'view'` — pass `screenTandem.createTandem( 'view' )` from your `Screen`'s `createView` factory, not an arbitrary name.

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `layoutBounds` | `new Bounds2( 0, 0, 1024, 618 )` | The fixed design-time coordinate frame content is laid out against |
| `includePDOMNodes` | `true` | Whether the screen-summary/play-area/control-area accessibility Nodes are added to the PDOM |
| `screenSummaryContent` | `null` | A `ScreenSummaryContent` Node describing the screen for the Voicing/description features |

## Public API

| Member | Description |
| --- | --- |
| `layoutBounds` | The fixed `Bounds2` this view's content is designed against — use `this.layoutBounds.center`, `.maxX`, etc. to position children |
| `visibleBoundsProperty` | `Property<Bounds2>`, in the same coordinate frame as `layoutBounds`; shrinks from the full `layoutBounds` when the actual browser window is a different aspect ratio, so UI meant to be reachable (buttons, controls) should stay inside it rather than assuming all of `layoutBounds` is always shown |
| `step( dt )` | No-op by default — override in a subclass if the view itself needs per-frame updates (most simulations only need the model to step) |
| `getVoicingOverviewContent()` / `getVoicingDetailsContent()` / `getVoicingHintContent()` | Supply the Voicing feature's "Overview"/"Details"/"Hint" responses; default implementations delegate to `screenSummaryContent` |

::: warning Don't set `pdomOrder` directly on a `ScreenView`
`ScreenView` throws if you call `setPDOMOrder()` on it. It maintains its own PDOM structure via `pdomPlayAreaNode` and `pdomControlAreaNode` (protected members) so every screen in every sim gets the same heading structure for screen readers — order your accessible content under those Nodes instead, not the `ScreenView` itself.
:::


========================================================================
Page: Sim
URL: https://veillette.github.io/Almanach/api/joist/sim
Source: docs/api/joist/sim.md
Category: API | Tags: joist, Sim | Status: verified
========================================================================

# Sim

`Sim` is the single top-level object for a simulation: it owns the list of `Screen`s, builds the home screen (for multi-screen sims) and navigation bar, drives the `requestAnimationFrame` loop that steps the active screen, and manages global concerns like credits, PhET-iO state, and preferences. Every simulation constructs exactly one `Sim` and calls `start()` on it.

::: warning `Sim` is exported from `scenerystack/sim`, not `scenerystack/joist`
The class lives in the `joist` repository internally, but the published package puts `Sim`, [`Screen`](/api/joist/screen), and [`ScreenView`](/api/joist/screen-view) on the **`scenerystack/sim`** subpath. `scenerystack/joist` still exists, but only exports supporting pieces (preferences panels, `CreditsNode`, locale utilities) — not these three classes.
:::

```ts
import { Sim, onReadyToLaunch } from 'scenerystack/sim';
import { Property } from 'scenerystack/axon';
```

## A minimal example

```ts
onReadyToLaunch( () => {
  const sim = new Sim( new Property( 'My Simulation' ), [ myScreen, anotherScreen ], {
    credits: {
      leadDesign: 'Ada Lovelace'
    }
  } );
  sim.start();
} );
```

Always construct and start the `Sim` from inside `onReadyToLaunch` — it waits for SceneryStack's asynchronous asset loader (fonts, images, translated strings) to finish before it's safe to build the scene graph.

## Constructor

```ts
new Sim(
  simNameProperty: TReadOnlyProperty<string>,
  allSimScreens: AnyScreen[],
  providedOptions?: SimOptions
)
```

`simNameProperty` is a string Property (not a plain string) so the sim's title can be translated; `allSimScreens` is the full ordered list of [`Screen`](/api/joist/screen) instances, in the order they should appear in the navigation bar.

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `credits` | `{}` | A `CreditsData` object rendered in the About dialog (`leadDesign`, `softwareDevelopment`, `team`, etc.) |
| `homeScreenWarningNode` | `null` | A `Node` placed onto the home screen, e.g. for an experimental-build warning |
| `preferencesModel` | auto-created | A `PreferencesModel` describing which Preferences dialog panels/features are available; omit it to get the default (no extra preferences) |
| `webgl` | `SimDisplay.DEFAULT_WEBGL` | Whether the underlying `Display` may use WebGL rendering |
| `detachInactiveScreenViews` | `false` | If `true`, only the active screen's `ScreenView` stays in the scene graph (saves memory/perf at the cost of slower screen switches); if `false`, all screens' views remain children and only one is visible |

## Public API

| Member | Description |
| --- | --- |
| `screens` | All screens in the running sim, with the auto-created `HomeScreen` first if one exists |
| `simScreens` | Just the sim-specific screens (excludes the `HomeScreen`) |
| `selectedScreenProperty` | `Property<AnyScreen>` — which screen is currently showing |
| `activeProperty` | `Property<boolean>` — settable; whether the whole sim is running and processing user input. Setting it to `false` pauses the sim. Distinct from `browserTabVisibleProperty` (`TReadOnlyProperty<boolean>`), which tracks the actual browser tab's visibility state |
| `isConstructionCompleteProperty` | `TReadOnlyProperty<boolean>` — becomes `true` once every screen's model and view have been constructed (useful for PhET-iO tooling) |
| `dimensionProperty` | `TReadOnlyProperty<Dimension2>` — current browser viewport size |
| `lookAndFeel` | A `LookAndFeel` instance controlling navigation bar fill/text colors |
| `start()` | Kicks off asynchronous screen initialization, then begins the animation-frame loop. Call this once, after construction |
| `stepOneFrame()` | Advances model/view/display by a single frame — used by embedding contexts that need manual frame control |

::: tip A single-screen sim needs no home screen icons
`Screen` options like `homeScreenIcon`/`navigationBarIcon` only matter once a sim has more than one entry in `allSimScreens` — with exactly one screen, there's no home screen or navigation bar screen button to show them in. See [Screen](/api/joist/screen) and [Your First Simulation](/getting-started/your-first-simulation) for the smallest possible wiring.
:::


========================================================================
Page: SimInfo
URL: https://veillette.github.io/Almanach/api/joist/sim-info
Source: docs/api/joist/sim-info.md
Category: API | Tags: joist, SimInfo, Sim, phet-io | Status: verified
========================================================================

# SimInfo

`SimInfo` is a diagnostic snapshot — sim name/version, screen names, browser user agent, viewport size, WebGL support, and (when running under PhET-iO) data-stream/wrapper metadata — collected once when a [`Sim`](/api/joist/sim) starts up. `Sim` constructs exactly one internally (`this.simInfo = new SimInfo( this )`, an internal/private field); as a simulation author you don't construct one yourself or read it off `sim` directly. It exists mostly so PhET-iO's data stream can emit a `simStarted` event describing the environment, and to back the diagnostic info shown in the sim's About dialog.

```ts
import type { SimInfoState } from 'scenerystack/sim';
// SimInfo itself is constructed internally by Sim; simulation code doesn't create instances directly.
```

::: tip This is a read-only diagnostic record, not a live/reactive object
Every field in `SimInfoState` is captured once, synchronously, at construction time (`self.navigator.userAgent`, `window.innerWidth`, etc.) — there are no Properties here to `link()` to, and nothing updates after the fact (e.g. resizing the browser window afterward doesn't change the captured `window` field). If you need live values for something `SimInfo` also captures — like viewport size — use `Sim.dimensionProperty` instead.
:::

## Constructor

```ts
new SimInfo( sim: Sim )
```

Constructed once, internally, by `Sim`.

## `SimInfoState` fields

| Field | Contents |
| --- | --- |
| `simName`, `simVersion`, `repoName` | The sim's display name, version string, and repository name |
| `screens` | One `{ name, phetioID? }` entry per entry in `sim.screens` |
| `url`, `userAgent`, `language`, `referrer`, `randomSeed` | Captured from `location`/`navigator`/`document`/the `randomSeed` query parameter at startup |
| `window` | The browser viewport size at startup, as a `"widthxheight"` string |
| `pixelRatio`, `isWebGLSupported`, `checkIE11StencilSupport`, `flags` | Rendering-capability diagnostics (device pixel ratio vs. backing-store ratio, WebGL availability, assorted browser input-capability flags) |
| `screenPropertyValue`, `wrapperMetadata`, `dataStreamVersion`, `phetioCommandProcessorProtocol` | Populated only when running under PhET-iO |

## Related

- [Sim](/api/joist/sim) — constructs the single `SimInfo` instance and is the source of most of its data (`simNameProperty`, `screens`, `version`).


========================================================================
Page: Arc
URL: https://veillette.github.io/Almanach/api/kite/arc
Source: docs/api/kite/arc.md
Category: API | Tags: kite, Arc, segment, path | Status: verified
========================================================================

# Arc

`Arc` (from `scenerystack/kite`) is a [`Segment`](/api/kite/shape) describing a piece of a circle — every point on it is equidistant (`radius`) from a `center`, swept from `startAngle` to `endAngle`. It's what `shape.arc( centerX, centerY, radius, startAngle, endAngle, anticlockwise )` appends to the current subpath, and it's also what `LineStyles` uses internally to build `'round'` line caps and joins (see [LineStyles](/api/kite/line-styles)).

```ts
import { Arc, Shape } from 'scenerystack/kite';
import { Vector2 } from 'scenerystack/dot';

const halfCircle = new Arc( new Vector2( 0, 0 ), 50, 0, Math.PI, false );
halfCircle.start;    // Vector2( 50, 0 )
halfCircle.end;      // Vector2( -50, 0 ) (approximately)
halfCircle.bounds;   // Bounds2 tightly containing the arc

// The usual way you'll get one: build it through Shape
const shape = new Shape().arc( 0, 0, 50, 0, Math.PI, false );
```

::: tip Angles are in radians, and `anticlockwise` follows the Canvas 2D convention
`startAngle`/`endAngle` are radians, not degrees, and `anticlockwise` matches the [HTML Canvas `arc()`](http://www.w3.org/TR/2dcontext/#dom-context-2d-arc) parameter of the same name — it's easy to get a swept direction backwards by assuming it means "counterclockwise in screen space," when scenery's y-axis points down, so `anticlockwise: true` sweeps what looks like *clockwise* on screen. If an arc looks like it's going the wrong way, flip this flag before touching the angles.
:::

## Constructor

```ts
new Arc( center: Vector2, radius: number, startAngle: number, endAngle: number, anticlockwise: boolean )
```

If `startAngle`/`endAngle` differ by (approximately) a full turn, the `Arc` represents a complete circle rather than a partial arc — see `isFullPerimeter` below.

## Public API

| Member | Description |
| --- | --- |
| `center`, `radius`, `startAngle`, `endAngle`, `anticlockwise` | The five defining values, each with a getter and a setter (setters recompute cached bounds/tangents) |
| `start` / `end` | The endpoint `Vector2`s, derived from `center` + `radius` at `startAngle`/`endAngle` |
| `startTangent` / `endTangent` | Normalized tangent direction at each endpoint |
| `actualEndAngle` | `endAngle` remapped relative to `startAngle` so it always represents the actual angular sweep direction |
| `angleDifference` | The signed angular sweep of the arc, accounting for `anticlockwise` |
| `isFullPerimeter` | `true` if the arc is (approximately) a complete circle rather than a partial sweep |
| `bounds` | The tight `Bounds2` around the swept arc (not the full circle, unless `isFullPerimeter`) |
| `positionAtAngle( angle )` / `tangentAtAngle( angle )` | Position/tangent at a raw angle, rather than a parametric `t` |
| `transformed( matrix )` | Returns `Arc \| EllipticalArc` — a uniform-scale/rotation transform stays a circular `Arc`, but a non-uniform scale turns it into an [`EllipticalArc`](/api/kite/elliptical-arc), since circles don't stay circular under non-uniform scaling |
| `reversed()` | A new `Arc` tracing the same points in the opposite direction |

`Arc` also implements the full [`Segment`](/api/kite/shape) contract shared by every segment type — `positionAt( t )`, `tangentAt( t )`, `curvatureAt( t )`, `subdivided( t )`, and `getArcLength()` all work the same way they do on [`Line`](/api/kite/line-segment), [`Quadratic`](/api/kite/quadratic), and [`Cubic`](/api/kite/cubic).

## Related

- [Shape](/api/kite/shape) — how `Arc` and other segments compose into subpaths and shapes; also has the fluent `arc()`/static `Shape.circle()` builders.
- [EllipticalArc](/api/kite/elliptical-arc) — the more general segment `Arc.transformed()` can produce under non-uniform scaling.
- [LineStyles](/api/kite/line-styles) — `'round'` caps/joins are built from `Arc` segments.


========================================================================
Page: Cubic
URL: https://veillette.github.io/Almanach/api/kite/cubic
Source: docs/api/kite/cubic.md
Category: API | Tags: kite, Cubic, bezier, segment, path | Status: verified
========================================================================

# Cubic

`Cubic` (from `scenerystack/kite`) is a [`Segment`](/api/kite/shape) describing a cubic Bézier curve — a `start` point, two control points (`control1`, `control2`) that shape the curve without the curve passing through them, and an `end` point. It's what `shape.cubicCurveTo( cp1x, cp1y, cp2x, cp2y, x, y )` appends to the current subpath, and it's the curve type behind most hand-drawn or design-tool-exported SVG path data (`C`/`c` commands).

```ts
import { Cubic, Shape } from 'scenerystack/kite';
import { Vector2 } from 'scenerystack/dot';

const curve = new Cubic(
  new Vector2( 0, 0 ),     // start
  new Vector2( 30, 100 ),  // control1
  new Vector2( 70, 100 ),  // control2
  new Vector2( 100, 0 )    // end
);
curve.positionAt( 0.5 ); // the curve's midpoint

// The usual way you'll get one: build it through Shape
const shape = new Shape().moveTo( 0, 0 ).cubicCurveTo( 30, 100, 70, 100, 100, 0 );
```

::: tip Cubics can have cusps and inflection points — flatten before assuming smoothness
Unlike `Quadratic`, a `Cubic` can have an S-shape, a cusp (a sharp point where the tangent direction reverses), or self-intersect. `Cubic` exposes `tCusp`, `tInflection1`/`tInflection2`, and `xExtremaT`/`yExtremaT` so algorithms that need monotonic pieces (hit-testing, stroking, tessellation) can `subdivided()` at those `t` values first. If you're writing code that assumes a curve bends only one way, check these before trusting that assumption.
:::

## Constructor

```ts
new Cubic( start: Vector2, control1: Vector2, control2: Vector2, end: Vector2 )
```

## Public API

| Member | Description |
| --- | --- |
| `start`, `control1`, `control2`, `end` | The four defining points, each with a getter and setter (setters recompute cached bounds/tangents) |
| `startTangent` / `endTangent` | Normalized tangent direction at each endpoint — toward `control1` from `start`, and from `control2` toward `end` |
| `tCusp` | Parametric `t` of a potential cusp (a point where the derivative vanishes and direction can flip) |
| `tInflection1` / `tInflection2` | Parametric `t` values where curvature changes sign (`NaN` if not applicable) |
| `xExtremaT` / `yExtremaT` | Arrays of `t` values where the x- or y-derivative is zero, used to compute tight bounds |
| `bounds` | The tight `Bounds2` around the curve, accounting for the extrema above |
| `subdivided( t )` | Splits into two `Cubic`s at parametric `t`, each an exact piece of the original curve |
| `getArcLength()` | Approximate arc length, computed via recursive subdivision (see [Segment](/api/kite/shape)'s shared `getArcLength()`) |
| `reversed()` | A new `Cubic` with `start`/`end` swapped and `control1`/`control2` swapped |
| `transformed( matrix )` | A new `Cubic` with all four points transformed by a [`Matrix3`](/api/dot/matrix3) |

`Cubic` also implements the shared [`Segment`](/api/kite/shape) contract — `positionAt( t )`, `tangentAt( t )`, `curvatureAt( t )` — the same as [`Line`](/api/kite/line-segment), [`Arc`](/api/kite/arc), and [`Quadratic`](/api/kite/quadratic).

## Related

- [Shape](/api/kite/shape) — the fluent `cubicCurveTo()` builder.
- [Quadratic](/api/kite/quadratic) — the simpler one-control-point curve.


========================================================================
Page: EllipticalArc
URL: https://veillette.github.io/Almanach/api/kite/elliptical-arc
Source: docs/api/kite/elliptical-arc.md
Category: API | Tags: kite, EllipticalArc, segment, path | Status: verified
========================================================================

# EllipticalArc

`EllipticalArc` (from `scenerystack/kite`) is a [`Segment`](/api/kite/shape) that generalizes [`Arc`](/api/kite/arc) to ellipses: instead of a single `radius`, it has independent `radiusX`/`radiusY`, plus a `rotation` for the ellipse's semi-major axis. It's what `shape.ellipticalArc( centerX, centerY, radiusX, radiusY, rotation, startAngle, endAngle, anticlockwise )` appends to the current subpath, and it's also what `Arc.transformed()` produces when a circular arc is transformed by a non-uniform scale (circles don't stay circular once x and y are scaled differently).

```ts
import { EllipticalArc, Shape } from 'scenerystack/kite';
import { Vector2 } from 'scenerystack/dot';

const halfEllipse = new EllipticalArc( new Vector2( 0, 0 ), 80, 40, 0, 0, Math.PI, false );
halfEllipse.start;   // Vector2( 80, 0 )
halfEllipse.bounds;  // Bounds2 tightly containing the swept arc

// The usual way you'll get one: build it through Shape
const shape = new Shape().ellipticalArc( 0, 0, 80, 40, 0, 0, Math.PI, false );
```

::: tip A circular `Arc` is just an `EllipticalArc` with `radiusX === radiusY` and `rotation === 0`
kite keeps them as separate classes for efficiency (circular math is cheaper), not because they're conceptually different — if you're writing code generic over "some kind of arc segment," `EllipticalArc` is the superset. Internally, `EllipticalArc` computes a `unitTransform` (a `Transform3` mapping the ellipse to a unit circle) and delegates position/tangent queries to the equivalent `Arc` on that unit circle, exposed as `unitArcSegment`.
:::

## Constructor

```ts
new EllipticalArc(
  center: Vector2,
  radiusX: number,
  radiusY: number,
  rotation: number,
  startAngle: number,
  endAngle: number,
  anticlockwise: boolean
)
```

`rotation` (radians) rotates the whole ellipse — including which direction counts as `radiusX` vs `radiusY` — around `center`, applied before `startAngle`/`endAngle` are measured.

## Public API

| Member | Description |
| --- | --- |
| `center`, `radiusX`, `radiusY`, `rotation`, `startAngle`, `endAngle`, `anticlockwise` | The defining values, each with a getter and setter (setters recompute cached bounds/tangents) |
| `start` / `end` | The endpoint `Vector2`s |
| `startTangent` / `endTangent` | Normalized tangent direction at each endpoint |
| `actualEndAngle` | `endAngle` remapped relative to `startAngle` to reflect the true angular sweep |
| `angleDifference` | The signed angular sweep, accounting for `anticlockwise` |
| `isFullPerimeter` | `true` if the arc sweeps a complete ellipse |
| `unitTransform` | The `Transform3` mapping this ellipse to/from a unit circle |
| `unitArcSegment` | The equivalent circular [`Arc`](/api/kite/arc) on that unit circle |
| `bounds` | The tight `Bounds2` around the swept arc |
| `positionAtAngle( angle )` / `tangentAtAngle( angle )` | Position/tangent at a raw angle, rather than a parametric `t` |
| `transformed( matrix )` | Always returns another `EllipticalArc` (unlike `Arc.transformed()`, which can stay circular) |
| `reversed()` | A new `EllipticalArc` tracing the same points in the opposite direction |

`EllipticalArc` also implements the shared [`Segment`](/api/kite/shape) contract — `positionAt( t )`, `tangentAt( t )`, `curvatureAt( t )`, `subdivided( t )`, `getArcLength()` — the same as [`Arc`](/api/kite/arc), [`Line`](/api/kite/line-segment), [`Quadratic`](/api/kite/quadratic), and [`Cubic`](/api/kite/cubic).

## Related

- [Shape](/api/kite/shape) — the fluent `ellipticalArc()` builder and static `Shape.ellipse()` factory.
- [Arc](/api/kite/arc) — the circular special case, and what a uniformly-scaled `EllipticalArc.transformed()` conceptually mirrors.


========================================================================
Page: Graph and Boolean Shape Operations
URL: https://veillette.github.io/Almanach/api/kite/graph-and-boolean-operations
Source: docs/api/kite/graph-and-boolean-operations.md
Category: API | Tags: kite, Graph, Shape, Face, HalfEdge, Loop, Boundary, Edge, Vertex, boolean-operations | Status: complete
========================================================================

# Graph and Boolean Shape Operations

`Graph` (from `scenerystack/kite`, exported alongside `Shape` from the same module) is the machinery behind [`Shape`](/api/kite/shape)'s boolean operations — `Shape.union()`, `Shape.intersection()`, `Shape.xor()`, and shape clipping. It builds a planar subdivision (a doubly-connected-edge-list-style structure of `Vertex`/`Edge`/`HalfEdge`/`Loop`/`Boundary`/`Face` objects) out of one or more shapes' segments, resolves every self-intersection and overlap between them, and then re-derives a clean output `Shape` from whichever faces satisfy a winding-number rule. In practice, you almost never touch `Graph` directly — you call the `Shape` static methods that use it internally.

```ts
import { Shape } from 'scenerystack/kite';

const circle = Shape.circle( 50, 50, 40 );
const square = Shape.rectangle( 30, 30, 60, 60 );

const combined = Shape.union( [ circle, square ] );          // everything covered by either shape
const overlap = Shape.intersection( [ circle, square ] );     // only the region covered by both
const symmetricDifference = Shape.xor( [ circle, square ] );  // covered by exactly one, not both
```

## The `Shape` entry points

| Method | Result |
| --- | --- |
| `Shape.union( shapes )` | The region covered by at least one input shape |
| `Shape.intersection( shapes )` | The region covered by every input shape |
| `Shape.xor( shapes )` | The region covered by an odd number of input shapes (their symmetric difference) |

All three (and `Graph.simplifyNonZero( shape )`, used to clean up self-intersections in a single shape) are implemented by constructing a `Graph`, adding each input shape with a distinct integer ID, computing the planar subdivision, then filtering faces by a `windingMap` predicate — a record of, for each shape ID, how many times that shape's boundary winds around a given face. `union` keeps any face where at least one shape's winding is non-zero; `intersection` keeps only faces where *every* shape's winding is non-zero; `xor` keeps faces where an odd number of shapes wind around it.

## Clipping one shape to another

`Graph.clipShape( clipAreaShape, shape, options? )` returns the portion of `shape` that falls inside `clipAreaShape`, useful for anything that needs to restrict a drawn path to a clip region using real geometry (rather than a Canvas/SVG clip path) — for example, precomputing the clipped area to measure it, or to further combine it with other shapes.

| Option | Default | Effect |
| --- | --- | --- |
| `includeExterior` | `false` | Keep the parts of `shape` outside `clipAreaShape` |
| `includeBoundary` | `true` | Keep the parts of `shape` exactly on `clipAreaShape`'s boundary |
| `includeInterior` | `true` | Keep the parts of `shape` inside `clipAreaShape` |

## What's inside a `Graph`, briefly

If you do need to go one level deeper — say, to inspect exactly which faces a combination produced — a `Graph` is built from these pieces, in rough dependency order: `Vertex` (a point where segments meet), `Edge` (a `Segment` between two vertices, with a `forwardHalf`/`reversedHalf` pair of `HalfEdge`s for its two traversal directions), `Loop` (a cyclic sequence of half-edges from one original subpath), `Boundary` (a maximal cycle of half-edges bounding a region, possibly nested as holes via `childBoundaries`), and `Face` (a region bounded by a `Boundary`, with a `windingMap` recording each input shape's winding number there and a `filled` flag once `computeFaceInclusion()` has run). The typical pipeline a `Graph` runs through is: `addShape()` for each input, `computeSimplifiedFaces()` (resolves self-intersections/overlaps and builds faces), `computeFaceInclusion( windingMapFilter )` (marks `filled` per your predicate), `createFilledSubGraph()`, then `facesToShape()`/`Shape.fromGraph()` to get the resulting `Shape` back out.

::: tip Boolean operations are exact geometry, not a rendering trick
Because `Graph` resolves the actual intersection points and rebuilds real segments, the `Shape` returned by `union`/`intersection`/`xor`/`clipShape` is genuine vector geometry — it has correct `bounds`, `containsPoint()`, and stroke behavior, unlike compositing two overlapping shapes with Canvas globalCompositeOperation tricks. The tradeoff is cost: computing intersections across many segments is the dominant expense in these operations, so avoid recomputing a boolean combination every frame for shapes that aren't actually changing.
:::


========================================================================
Page: Line
URL: https://veillette.github.io/Almanach/api/kite/line-segment
Source: docs/api/kite/line-segment.md
Category: API | Tags: kite, Line, KiteLine, segment, path | Status: verified
========================================================================

# Line

kite's `Line` is a [`Segment`](/api/kite/shape) — a straight line between two points, and one of the primitive pieces that a [`Shape`](/api/kite/shape)'s subpaths are built from. It is **not** a scene-graph node: it has no `fill`, `stroke`, or `addChild`, and rendering nothing on its own. For a drawable straight line, use scenery's [`Line`](/api/scenery/line) `Path` subclass instead — this page is about the geometry primitive underneath `Shape.lineTo()`, not the thing you'd add to a scene graph.

You'll rarely construct a kite `Line` directly; `shape.lineTo( x, y )` and `Shape.lineSegment( p1, p2 )` create them for you. Where you do encounter the class directly is inspecting a built `Shape`'s internals, e.g. `shape.subpaths[ 0 ].segments[ 0 ]`.

::: warning Imported as `KiteLine`, not `Line`
`scenerystack/kite`'s barrel re-exports this class as `KiteLine` specifically to avoid a naming collision with scenery's `Line` node: `import { KiteLine } from 'scenerystack/kite'`. There is no `Line` export from `scenerystack/kite` — only `scenerystack/scenery` exports a `Line` (the renderable one).
:::

```ts
import { KiteLine, Shape } from 'scenerystack/kite';
import { Vector2 } from 'scenerystack/dot';

const segment = new KiteLine( new Vector2( 0, 0 ), new Vector2( 100, 50 ) );
segment.start;   // Vector2( 0, 0 )
segment.end;     // Vector2( 100, 50 )
segment.bounds;  // Bounds2 tightly containing the segment

// The usual way you'll actually get one: build it through Shape
const shape = new Shape().moveTo( 0, 0 ).lineTo( 100, 50 );
shape.subpaths[ 0 ].segments[ 0 ] instanceof KiteLine; // true
```

## Constructor

```ts
new KiteLine( start: Vector2, end: Vector2 )
```

## Public API

| Member | Description |
| --- | --- |
| `start` / `end` | The two endpoints (`Vector2`, settable via `setStart()`/`setEnd()` or the `start`/`end` setters — either recomputes bounds and tangents) |
| `startTangent` / `endTangent` | Both equal the normalized direction from `start` to `end` — a straight line has one constant tangent along its whole length |
| `bounds` | The tight axis-aligned `Bounds2` around the two endpoints |
| `positionAt( t )` | Linear interpolation between `start` and `end`, `0 <= t <= 1` |
| `tangentAt( t )` | Constant regardless of `t` — unlike other segment types, `Line.tangentAt()` actually returns the same *normalized* direction as `startTangent`/`endTangent` (it delegates straight to `getStartTangent()`), not a raw `end.minus( start )` |
| `getArcLength()` | Equal to `start.distance( end )` — a line needs no subdivision to measure exactly |
| `reversed()` | A new `KiteLine` with `start`/`end` swapped |
| `transformed( matrix )` | A new `KiteLine` with both endpoints transformed by a [`Matrix3`](/api/dot/matrix3) |

See [Shape](/api/kite/shape) for how segments compose into subpaths and shapes, [Subpath](/api/kite/subpath) for the ordered-run container these segments live in, and [LineStyles](/api/kite/line-styles) for how a stroke turns a run of segments into an outline (`Line`'s bevel/miter joins and butt/round/square caps are built out of `KiteLine` and [`Arc`](/api/kite/arc) segments).


========================================================================
Page: LineStyles
URL: https://veillette.github.io/Almanach/api/kite/line-styles
Source: docs/api/kite/line-styles.md
Category: API | Tags: kite, LineStyles, stroke, path | Status: verified
========================================================================

# LineStyles

`LineStyles` (from `scenerystack/kite`) is a small immutable-in-practice value object bundling every parameter that affects how a stroke is drawn: `lineWidth`, `lineCap`, `lineJoin`, `lineDash`, `lineDashOffset`, and `miterLimit`. It mirrors the [SVG stroke properties](https://svgwg.org/svg2-draft/painting.html) of the same names. You'll mostly encounter it as the argument to [`Shape.getStrokedShape()`](/api/kite/shape) — the method that computes the actual outline a stroke would draw, as a new fillable `Shape` — rather than constructing it to configure a scenery `Path`'s visual stroke directly (that's done with `Path`'s own `lineWidth`/`lineCap`/`lineJoin`/... options).

```ts
import { LineStyles, Shape } from 'scenerystack/kite';

const styles = new LineStyles( {
  lineWidth: 4,
  lineCap: 'round',
  lineJoin: 'round'
} );

const shape = new Shape().moveTo( 0, 0 ).lineTo( 100, 0 ).lineTo( 50, 80 );
const strokedOutline = shape.getStrokedShape( styles ); // a new Shape describing the stroke's outline
```

::: tip `getStrokedShape()` is for hit-testing a stroke-only path, not for changing how it's drawn
If you just want a `Path` to render with a particular `lineWidth`/`lineCap`/`lineJoin`, set those directly as `Path` options — scenery renders strokes natively via Canvas/SVG without needing a `LineStyles`. Construct a `LineStyles` and call `shape.getStrokedShape( styles )` only when you need the *outline geometry itself*, e.g. to hit-test clicks against a stroked-but-unfilled path, or to feed the stroke outline into another kite operation like `Shape.union()`.
:::

## Constructor

```ts
new LineStyles( options?: LineStylesOptions )
```

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `lineWidth` | `1` | Total stroke width — the outline extends `lineWidth / 2` to each side of the path |
| `lineCap` | `'butt'` | Appearance at the ends of an open subpath: `'butt'` (flat, at the endpoint), `'round'` (a semicircle, built from an [`Arc`](/api/kite/arc)), or `'square'` (flat, extended by `lineWidth / 2` past the endpoint) |
| `lineJoin` | `'miter'` | Appearance where two segments meet: `'miter'` (sharp corner, extended until it meets or falls back to `'bevel'` past `miterLimit`), `'round'` (a circular fillet), or `'bevel'` (a single flat cut across the gap) |
| `lineDash` | `[]` | Alternating dash/gap lengths (`[dash, gap, dash, gap, ...]`); empty means a solid line |
| `lineDashOffset` | `0` | Offset into the `lineDash` pattern at which the dash starts, measured along the path |
| `miterLimit` | `10` | How sharp a `'miter'` join is allowed to get (as `1 / sin(angle / 2)`) before falling back to a bevel — prevents extremely acute corners from producing enormous spikes |

## Public API

| Member | Description |
| --- | --- |
| `equals( other )` | Value equality across all six properties (including element-wise `lineDash` comparison) |
| `copy()` | A new `LineStyles` with the same values |
| `leftJoin( center, fromTangent, toTangent )` / `rightJoin( ... )` | Build the array of segments forming a join on a given side, per `lineJoin` — used internally by `Subpath.stroked()` |
| `cap( center, tangent )` | Build the array of segments forming an end cap at a subpath endpoint, per `lineCap` |

## Related

- [Shape](/api/kite/shape) — `getStrokedShape( lineStyles )` is the main entry point that consumes a `LineStyles`.
- [Subpath](/api/kite/subpath) — `subpath.stroked( lineStyles )` does the actual per-subpath outline construction that `Shape.getStrokedShape()` delegates to.
- [Arc](/api/kite/arc) — `'round'` caps and joins are literally built from `Arc` segments.


========================================================================
Page: Quadratic
URL: https://veillette.github.io/Almanach/api/kite/quadratic
Source: docs/api/kite/quadratic.md
Category: API | Tags: kite, Quadratic, bezier, segment, path | Status: verified
========================================================================

# Quadratic

`Quadratic` (from `scenerystack/kite`) is a [`Segment`](/api/kite/shape) describing a quadratic Bézier curve — a `start` point, one `control` point the curve bends toward (but usually doesn't pass through), and an `end` point. It's what `shape.quadraticCurveTo( cpx, cpy, x, y )` appends to the current subpath. Quadratic curves are less common in hand-authored shapes than [`Cubic`](/api/kite/cubic) (SVG path data and most design tools default to cubic curves), but they're cheaper to evaluate and show up in font glyph outlines and some procedurally-generated shapes.

```ts
import { Quadratic, Shape } from 'scenerystack/kite';
import { Vector2 } from 'scenerystack/dot';

const curve = new Quadratic(
  new Vector2( 0, 0 ),    // start
  new Vector2( 50, 100 ), // control
  new Vector2( 100, 0 )   // end
);
curve.positionAt( 0.5 ); // the curve's midpoint (not the control point)

// The usual way you'll get one: build it through Shape
const shape = new Shape().moveTo( 0, 0 ).quadraticCurveTo( 50, 100, 100, 0 );
```

::: tip The curve doesn't pass through its control point
It's tempting to read `control` as a point the curve visits, but a Bézier control point only *pulls* the curve toward it — the curve touches `start` and `end` only. If you need a curve that passes through a specific interior point, either solve for the control point that produces it, or use several segments (`subdivided( t )`) to compose the shape you actually want.
:::

## Constructor

```ts
new Quadratic( start: Vector2, control: Vector2, end: Vector2 )
```

## Public API

| Member | Description |
| --- | --- |
| `start`, `control`, `end` | The three defining points, each with a getter and setter (setters recompute cached bounds/tangents) |
| `startTangent` / `endTangent` | Normalized tangent direction at each endpoint — points from `start` toward `control`, and from `control` toward `end`, respectively |
| `tCriticalX` / `tCriticalY` | The parametric `t` where the x- or y-derivative is zero (`NaN` if that extremum falls outside `[0, 1]`) — used internally to compute tight bounds |
| `bounds` | The tight `Bounds2` around the curve (accounting for the extrema above, not just the three defining points) |
| `subdivided( t )` | Splits into two `Quadratic`s at parametric `t`, each an exact piece of the original curve |
| `getArcLength()` | Approximate arc length, computed via recursive subdivision (see [Segment](/api/kite/shape)'s shared `getArcLength()`) |
| `reversed()` | A new `Quadratic` with `start`/`end` swapped and `control` unchanged |
| `transformed( matrix )` | A new `Quadratic` with all three points transformed by a [`Matrix3`](/api/dot/matrix3) |

`Quadratic` also implements the shared [`Segment`](/api/kite/shape) contract — `positionAt( t )`, `tangentAt( t )`, `curvatureAt( t )` — the same as [`Line`](/api/kite/line-segment), [`Arc`](/api/kite/arc), and [`Cubic`](/api/kite/cubic).

## Related

- [Shape](/api/kite/shape) — the fluent `quadraticCurveTo()` builder.
- [Cubic](/api/kite/cubic) — the two-control-point curve most SVG/design-tool path data actually uses.


========================================================================
Page: RayIntersection and SegmentIntersection
URL: https://veillette.github.io/Almanach/api/kite/ray-and-segment-intersections
Source: docs/api/kite/ray-and-segment-intersections.md
Category: API | Tags: kite, RayIntersection, SegmentIntersection, Segment, Shape, intersection | Status: complete
========================================================================

# RayIntersection and SegmentIntersection

`RayIntersection` and `SegmentIntersection` (both from `scenerystack/kite`) are small, immutable data classes describing the result of two different kinds of intersection query. `RayIntersection` describes where a [`Ray2`](/api/dot/ray2) crosses a [`Segment`](/api/kite/segment) or [`Shape`](/api/kite/shape) — the result of `segment.intersection( ray )` or `shape.intersection( ray )`. `SegmentIntersection` describes where two segments cross each other — the result of `Segment.intersect( a, b )`, used internally by shape simplification and boolean operations.

```ts
import { Shape, Segment } from 'scenerystack/kite';
import { Ray2, Vector2 } from 'scenerystack/dot';

const shape = Shape.circle( 0, 0, 50 );
const ray = new Ray2( new Vector2( -100, 0 ), new Vector2( 1, 0 ) );

const hits = shape.intersection( ray ); // RayIntersection[]
hits[ 0 ].point;    // Vector2(-50, 0) - where the ray first crosses the circle
hits[ 0 ].distance; // 50 - distance from the ray's origin to that point
```

## `RayIntersection`

One crossing point between a ray and a single segment (a `Shape`'s `intersection( ray )` collects these across every segment in every subpath).

| Field | Meaning |
| --- | --- |
| `point` | The `Vector2` location of the intersection |
| `distance` | Distance from the ray's origin to `point` (always `>= 0`) |
| `normal` | Unit normal to the segment at the intersection, oriented so its dot product with the ray's direction is `<= 0` |
| `wind` | `1` or `-1` — the winding contribution of this crossing, used by the non-zero fill rule that backs `Shape.containsPoint()` |
| `t` | The parametric value (`0` to `1`) along the specific segment where the crossing occurs |

`RayIntersection` is a plain constructed value (`new RayIntersection( distance, point, normal, wind, t )`) — you receive instances of it as return values; you won't typically construct one yourself.

## `SegmentIntersection`

One crossing point between two arbitrary segments, as returned by the static `Segment.intersect( a, b )`.

| Field | Meaning |
| --- | --- |
| `point` | The `Vector2` location of the intersection |
| `aT` | Parametric value (`0` to `1`) along the *first* segment (`a`) where the crossing occurs |
| `bT` | Parametric value (`0` to `1`) along the *second* segment (`b`) where the crossing occurs |
| `getSwapped()` | Returns an equivalent `SegmentIntersection` with `aT`/`bT` swapped — useful if you called `Segment.intersect( a, b )` but want the result as if you'd called `Segment.intersect( b, a )` |

```ts
import { Segment, Shape } from 'scenerystack/kite';

const line = Shape.lineSegment( 0, -50, 0, 50 ).subpaths[ 0 ].segments[ 0 ];
const circleArc = Shape.circle( 0, 0, 30 ).subpaths[ 0 ].segments[ 0 ];

const crossings = Segment.intersect( line, circleArc ); // SegmentIntersection[]
```

::: tip These describe *where* two things cross — not whether a shape contains a point
`shape.containsPoint( point )` and boolean shape operations (`Shape.union`/`intersection`/`xor`, see [Graph and Boolean Shape Operations](/api/kite/graph-and-boolean-operations)) are built out of exactly these intersection primitives internally (`RayIntersection.wind` for hit-testing, `SegmentIntersection` for splitting overlapping segments during simplification) — but as an API consumer you'd reach for `RayIntersection`/`SegmentIntersection` directly only for a custom geometry query (e.g. "where along this path does a laser beam first hit"), not for ordinary hit-testing or shape combination, which already have dedicated, higher-level methods.
:::


========================================================================
Page: Segment
URL: https://veillette.github.io/Almanach/api/kite/segment
Source: docs/api/kite/segment.md
Category: API | Tags: kite, Segment, Arc, Cubic, Quadratic, Line, EllipticalArc, path | Status: complete
========================================================================

# Segment

`Segment` (from `scenerystack/kite`) is the abstract base class behind every curve type kite offers: [`Arc`](/api/kite/arc), [`Cubic`](/api/kite/cubic), [`Quadratic`](/api/kite/quadratic), [`Line`](/api/kite/line-segment) (exported as `KiteLine`), and [`EllipticalArc`](/api/kite/elliptical-arc) all extend it. A [`Shape`](/api/kite/shape) is ultimately just an array of [`Subpath`](/api/kite/subpath)s, and each `Subpath` is an ordered array of `Segment`s — this page documents the contract they all share, so you can treat a mixed array of segment types uniformly (e.g. when walking `shape.subpaths[i].segments`) without caring which concrete subclass each one is.

```ts
import { Shape, Segment } from 'scenerystack/kite';

const shape = new Shape().moveTo( 0, 0 ).lineTo( 100, 0 ).quadraticCurveTo( 150, 50, 100, 100 );

for ( const subpath of shape.subpaths ) {
  for ( const segment: Segment of subpath.segments ) {
    // Every segment, regardless of concrete type, supports this same API:
    console.log( segment.start.toString(), '->', segment.end.toString() );
    console.log( 'arc length:', segment.getArcLength() );
    console.log( 'midpoint:', segment.positionAt( 0.5 ).toString() );
  }
}
```

Every segment is parameterized over `t` from `0` (its `start`) to `1` (its `end`) — the same convention `Cubic` and `Quadratic`'s Bézier parameter uses, and `Arc`/`EllipticalArc` map linearly onto their angular sweep.

## The shared contract

These members are declared `abstract` on `Segment` — every concrete subclass must implement them, each according to its own geometry:

| Member | Effect |
| --- | --- |
| `start` / `end` (getters) | The segment's endpoints, at `t=0` and `t=1` |
| `startTangent` / `endTangent` (getters) | Normalized tangent vectors at the endpoints, pointing in the direction of travel |
| `bounds` (getter) / `getBounds()` | The segment's axis-aligned `Bounds2` |
| `positionAt( t )` | The point at parametric value `t` (`0 <= t <= 1`) |
| `tangentAt( t )` | The non-normalized tangent `(dx/dt, dy/dt)` at `t` |
| `curvatureAt( t )` | Signed curvature at `t` (positive for a visually-clockwise turn) |
| `subdivided( t )` | Splits the segment into up to 2 sub-segments at `t`, together tracing the same curve |
| `getInteriorExtremaTs()` | The interior `t` values (`0 < t < 1`) where `dx/dt` or `dy/dt` is zero — subdividing at these produces monotone pieces |
| `strokeLeft( lineWidth )` / `strokeRight( lineWidth )` | The offset-curve segments for the logical left/right side of a stroke |
| `windingIntersection( ray )` | The winding-number contribution of a ray/segment intersection, used by `Shape.containsPoint()` |
| `intersection( ray )` | The list of [`RayIntersection`](/api/kite/ray-and-segment-intersections)s between this segment and a `Ray2` |
| `getOverlaps( segment, epsilon? )` | Whether (and how) this segment overlaps another of a compatible type, for shape-simplification purposes |
| `getSignedAreaFragment()` | This segment's contribution to a subpath's signed area (Green's theorem) |
| `getNondegenerateSegments()` | A list of equivalent, non-degenerate segments (e.g. an `Arc` with zero radius simplifies away) |
| `transformed( matrix )` | A new segment of the same or an equivalent type, transformed by a `Matrix3` |
| `reversed()` | A new segment tracing the same curve with `start`/`end` swapped |
| `getSVGPathFragment()` | The SVG path-data fragment for this segment alone (assuming the pen is already at `start`) |
| `writeToContext( context )` | Draws the segment to a `CanvasRenderingContext2D`, assuming the context is already at `start` |
| `serialize()` / `Segment.deserialize()` | Round-trip to/from a plain serializable object |
| `invalidate()` | Recomputes any cached derived state after mutating the segment in place |

## Shared concrete behavior

`Segment` also implements a handful of concrete methods, in terms of the abstract ones above, so every subclass gets them for free:

| Member | Effect |
| --- | --- |
| `getArcLength( distanceEpsilon?, curveEpsilon?, maxLevels? )` | Adaptive-subdivision arc length estimate — recursively `subdivided()` until each piece is "sufficiently flat," then sums straight-line distances |
| `slice( t0, t1 )` | The portion of the segment between two parametric values, via `subdivided()` |
| `subdivisions( tList )` | Splits at every `t` in a sorted list, in one pass |
| `subdividedIntoMonotone()` | `subdivisions( this.getInteriorExtremaTs() )` |
| `isSufficientlyFlat( distanceEpsilon, curveEpsilon )` | Whether the segment is close enough to its start-end chord to treat as flat, used internally by `getArcLength()` and piecewise-linear conversion |
| `getDashValues( lineDash, lineDashOffset, ... )` | Parametric `t` values where dash boundaries fall, for rendering a dashed stroke |
| `toPiecewiseLinearSegments( options )` | Approximates the curve as a series of `Line` segments |
| `getClosestPoints( point )` / `Segment.closestToPoint( segments, point, threshold )` | Finds the closest point(s) on a segment (or set of segments) to an arbitrary point |
| `Segment.intersect( a, b )` | Static: all [`SegmentIntersection`](/api/kite/ray-and-segment-intersections)s between two arbitrary segments |

::: tip Reach for the shared `Segment` API when writing type-agnostic geometry code
Anything that processes `shape.subpaths[i].segments` generically — measuring total path length, hit-testing, generating a dashed outline, or converting to line-only approximations for export — should be written against this shared `Segment` contract rather than switching on `instanceof Arc`/`Cubic`/etc. The five concrete pages ([Arc](/api/kite/arc), [Cubic](/api/kite/cubic), [Quadratic](/api/kite/quadratic), [Line](/api/kite/line-segment), [EllipticalArc](/api/kite/elliptical-arc)) only need to document what's *specific* to each curve type — their constructors and shape-specific accessors (`center`/`radius` for `Arc`, control points for `Cubic`/`Quadratic`) — since everything on this page already applies uniformly.
:::


========================================================================
Page: Shape
URL: https://veillette.github.io/Almanach/api/kite/shape
Source: docs/api/kite/shape.md
Category: API | Tags: kite, Shape, path | Status: verified
========================================================================

# Shape

`Shape` (from `scenerystack/kite`) describes a 2D path — one or more subpaths built from line, quadratic, cubic, and arc segments — independent of how it's drawn. It's the geometry engine behind scenery's [`Path`](/api/scenery/path) (and `Path`'s subclasses like `Rectangle`, `Circle`, and `Line`): a `Path` node just takes a `Shape` and renders it with fill/stroke.

```ts
import { Shape } from 'scenerystack/kite';
import { Vector2 } from 'scenerystack/dot';

const triangle = new Shape()
  .moveTo( 0, 0 )
  .lineTo( 100, 0 )
  .lineTo( 50, 80 )
  .close();

triangle.bounds;                                  // Bounds2 tightly containing the triangle
triangle.containsPoint( new Vector2( 50, 40 ) );  // true
```

## Building shapes with the fluent API

The constructor `new Shape()` starts empty (or you can pass an SVG path-data string, e.g. `new Shape( 'M0,0 L100,0 L50,80 Z' )`). From there, chain path-drawing commands — each one returns `this`, so calls read like a pen tracing a line:

| Method | Draws |
| --- | --- |
| `moveTo( x, y )` / `moveToPoint( vector )` | Starts a new subpath at a point (no line drawn) |
| `lineTo( x, y )` / `lineToPoint( vector )` | A straight line from the current point |
| `quadraticCurveTo( cpx, cpy, x, y )` | A quadratic Bézier curve |
| `cubicCurveTo( cp1x, cp1y, cp2x, cp2y, x, y )` | A cubic Bézier curve |
| `arc( centerX, centerY, radius, startAngle, endAngle, anticlockwise? )` | A circular arc |
| `ellipticalArc( centerX, centerY, radiusX, radiusY, rotation, startAngle, endAngle, anticlockwise? )` | An elliptical arc |
| `rect( x, y, width, height )` | An axis-aligned rectangle subpath |
| `polygon( vertices )` | A closed polygon through the given `Vector2[]` points |
| `close()` | Closes the current subpath back to its start point |

Each of these also has a `...Relative` variant (`lineToRelative`, `moveToRelative`, ...) that interprets its arguments as a displacement from the current point rather than an absolute position.

## Static factories

For common shapes, the static factories are usually more direct than the fluent builder:

```ts
Shape.rectangle( 0, 0, 100, 50 );                 // same as Shape.rect(...)
Shape.circle( 50, 50, 20 );                        // centerX, centerY, radius
Shape.circle( new Vector2( 50, 50 ), 20 );          // center point, radius
Shape.ellipse( 50, 50, 30, 20, 0 );                 // centerX, centerY, radiusX, radiusY, rotation
Shape.roundRect( 0, 0, 100, 50, 8, 8 );             // x, y, width, height, arc-width, arc-height
Shape.polygon( [ new Vector2( 0, 0 ), new Vector2( 10, 0 ), new Vector2( 5, 10 ) ] );
Shape.lineSegment( 0, 0, 100, 100 );                 // or Shape.lineSegment( p1, p2 )
Shape.regularPolygon( 6, 40 );                       // sides, radius
```

`Shape.union( shapes )`, `Shape.intersection( shapes )`, and `Shape.xor( shapes )` perform boolean operations across an array of shapes, using kite's internal `Graph` machinery.

## Querying and transforming a shape

| Method | Effect |
| --- | --- |
| `bounds` (getter, backed by `getBounds()`) | The tight-fitting axis-aligned [`Bounds2`](/api/dot/bounds2) |
| `containsPoint( point )` | Hit-testing — whether the point is inside the shape (respecting winding rule) |
| `copy()` | A deep copy of the shape |
| `transformed( matrix )` | A new `Shape` with every segment transformed by a [`Matrix3`](/api/dot/matrix3) |
| `getStrokedShape( lineStyles )` | A new `Shape` describing the *outline* a stroke of the given `LineStyles` would draw — useful for hit-testing a stroked-only path |

::: tip `Shape` is mutable while you build it, but treat finished shapes as immutable
The fluent `moveTo`/`lineTo`/`arc`/... calls mutate the `Shape` instance in place (that's why they can be chained). Once a `Shape` is handed to a scenery `Path` (`new Path( shape )`), don't keep mutating that same instance to "animate" the path — `Path` doesn't automatically know the shape changed unless you call `path.shape = newShape` (or `path.invalidateShape()`), so prefer building a fresh `Shape` per frame, or wrap it in a `Property<Shape>` if a shape needs to change reactively. Note also that `Shape.transformed()`, unlike the drawing methods, returns a **new** `Shape` rather than mutating the original.
:::

## Related

- [Path](/api/scenery/path) — the scenery `Node` that renders a `Shape` with fill/stroke.
- [Bounds2](/api/dot/bounds2) — the type returned by `shape.bounds`.
- [Matrix3](/api/dot/matrix3) — the transform type accepted by `shape.transformed()`.
- [Vector2](/api/dot/vector2) — the point type used throughout `Shape`'s construction methods.


========================================================================
Page: Subpath
URL: https://veillette.github.io/Almanach/api/kite/subpath
Source: docs/api/kite/subpath.md
Category: API | Tags: kite, Subpath, path | Status: verified
========================================================================

# Subpath

`Subpath` (from `scenerystack/kite`) holds one connected, ordered run of [`Segment`](/api/kite/shape)s — the layer between individual segments and a whole [`Shape`](/api/kite/shape). Every `Shape` is really just an array of these: `shape.subpaths` is a `Subpath[]`, and each call to `moveTo()` on a `Shape` starts a new one. A single `moveTo().lineTo().lineTo()` traces one `Subpath`; calling `moveTo()` again (or drawing a shape with multiple disconnected pieces, like the two loops of a letter "B") starts another.

```ts
import { Shape } from 'scenerystack/kite';

const shape = new Shape()
  .moveTo( 0, 0 ).lineTo( 100, 0 ).lineTo( 50, 80 ).close()   // subpath 0: a triangle
  .moveTo( 200, 0 ).lineTo( 300, 0 );                          // subpath 1: an open line

shape.subpaths.length;          // 2
shape.subpaths[ 0 ].closed;     // true  - closed with .close()
shape.subpaths[ 0 ].segments;   // the 3 Line segments making up the triangle
shape.subpaths[ 1 ].closed;     // false - never closed
```

::: tip A `Subpath` being `closed` isn't the same as its first and last points coinciding
`closed` reflects whether `.close()` was called (which also appends a real closing segment connecting the last point back to the first, via `getClosingSegment()`) — it's not inferred from geometry. A subpath whose last `lineTo()` happens to land exactly on the start point, but which never called `.close()`, still reports `closed === false` and has no closing segment. Use `isClosed()` (equivalent to reading `.closed`) rather than comparing `getFirstPoint()`/`getLastPoint()` yourself.
:::

## Constructor

```ts
new Subpath( segments?: Segment[], points?: Vector2[], closed?: boolean )
```

You'll rarely construct a `Subpath` directly — build shapes through `Shape`'s fluent API (`moveTo`/`lineTo`/`arc`/...) and read the resulting `shape.subpaths` instead. The constructor mainly exists for `Shape`'s own internals (`copy()`, transform methods) and for advanced code assembling a `Shape` from pre-built segments.

## Public API

| Member | Description |
| --- | --- |
| `segments` | The ordered `Segment[]` making up this subpath |
| `points` | The `Vector2[]` of segment start points, plus the final segment's end point |
| `closed` | Whether `.close()` was called on this subpath |
| `bounds` | The `Bounds2` union of every segment's bounds |
| `getFirstPoint()` / `getLastPoint()` | The subpath's first and last points |
| `getFirstSegment()` / `getLastSegment()` | The subpath's first and last segments |
| `isClosed()` | Same as reading `.closed` |
| `hasClosingSegment()` / `getClosingSegment()` | A purely geometric check — whether (and what) synthetic `Line` segment would connect the last point back to the first. This is independent of the `closed` flag: it returns `true` whenever the first and last points differ by more than a tiny epsilon, even on a subpath that never called `.close()` |
| `isDrawable()` | Whether there's at least one segment to draw |
| `getArcLength()` | Sum of every contained segment's arc length |
| `getFillSegments()` | Segments to use for filling — includes the closing segment even if `.close()` was never explicitly called, since fills always implicitly close |
| `stroked( lineStyles )` | Returns `Subpath[]` describing the outline this subpath would have when stroked with the given [`LineStyles`](/api/kite/line-styles) — what `Shape.getStrokedShape()` delegates to per subpath |
| `transformed( matrix )` | A new `Subpath` with every segment transformed by a [`Matrix3`](/api/dot/matrix3) |
| `copy()` | A shallow-ish copy (new `Subpath`, same segment/point arrays sliced) |

## Related

- [Shape](/api/kite/shape) — the `subpaths: Subpath[]` container, and the fluent builder that creates them.
- [LineStyles](/api/kite/line-styles) — the stroke configuration `subpath.stroked()` consumes.
- [Line](/api/kite/line-segment) — the segment type used for a subpath's synthetic closing segment.


========================================================================
Page: SVG Path Parsing and Serialization
URL: https://veillette.github.io/Almanach/api/kite/svg-path-parsing-and-serialization
Source: docs/api/kite/svg-path-parsing-and-serialization.md
Category: API | Tags: kite, svgPath, svgNumber, Shape, SVG | Status: complete
========================================================================

# SVG Path Parsing and Serialization

kite can both **read** an SVG path-data string into a [`Shape`](/api/kite/shape) and **write** a `Shape` back out as one. Reading goes through `svgPath`, a generated PEG.js parser (also exported directly from `scenerystack/kite`, for advanced use); writing goes through `Shape.getSVGPath()`, which stitches together each segment's own `getSVGPathFragment()` using `svgNumber` (also exported directly) to format numbers.

```ts
import { Shape, svgPath, svgNumber } from 'scenerystack/kite';

// Reading: parse SVG path data directly in the Shape constructor
const triangle = new Shape( 'M0,0 L100,0 L50,80 Z' );

// Writing: serialize any Shape back to an SVG path-data string
triangle.getSVGPath(); // 'M 0.00... 0.00... L 100.00... 0.00... L 50.00... 80.00... Z '

svgNumber( 1 / 3 ); // '0.33333333333333331483' - toFixed(20), not scientific notation
```

## Parsing: `new Shape( svgPathString )`

`Shape`'s constructor accepts an SVG path-data string as its first argument (instead of, or in addition to, an array of pre-built `Subpath`s). Internally it runs the string through the `svgPath` parser (exported standalone as `svgPath` from `scenerystack/kite`, generated from a PEG.js grammar) to get a sequence of drawing commands, then replays those commands through the same fluent builder methods (`moveTo`, `lineTo`, `cubicCurveTo`, `arc`, ...) documented on [Shape](/api/kite/shape). This means anything valid in an SVG `d` attribute — absolute and relative commands, arcs, shorthand cubic/quadratic continuations — is supported, since it's the same grammar SVG itself uses.

```ts
import { Shape } from 'scenerystack/kite';

// Arcs, relative commands, and shorthand curves all parse the same as in raw SVG:
const path = new Shape( 'M10,10 h80 v80 h-80 Z' ); // a square, using relative h/v line commands
```

## Serializing: `shape.getSVGPath()`

`Shape.prototype.getSVGPath()` walks every subpath and every [`Segment`](/api/kite/segment) within it, calling each segment's own `getSVGPathFragment()` (part of the shared `Segment` contract — every concrete segment type implements it) and joining the fragments with an `M x y` at the start of each drawable subpath and a trailing `Z` for closed ones. The result is ready to assign directly to an SVG `<path>` element's `d` attribute, or to hand back into `new Shape( ... )` to round-trip.

## `svgNumber`: why plain `toFixed` instead of dot's number formatting

`svgNumber( n )` is a one-line function: `n.toFixed( 20 )`. Its doc comment explains why it deliberately bypasses dot's usual number-formatting utilities (like `toFixed` from `scenerystack/dot`): **SVG's path grammar doesn't support scientific notation** (e.g. `7e5`), so any formatter that might emit it (as `Number.prototype.toString()` can for very large/small numbers) would produce path data a browser can't parse. Using the built-in `toFixed` guarantees a plain fixed-point decimal string every time, at the cost of some (irrelevant, display-only) precision.

::: warning `svgPath` and `svgNumber` are low-level building blocks, not the typical entry point
Most code should go through `new Shape( svgString )` and `shape.getSVGPath()` rather than calling `svgPath.parse()` or `svgNumber()` directly — those two exports exist mainly because `Shape` and `Segment` are built out of them internally, and are exposed for advanced cases (e.g. a tool that wants the raw parsed command list before it's turned into a `Shape`). For everyday reading/writing of SVG path data, the `Shape` methods above are simpler and keep bounds/segment invalidation consistent.
:::


========================================================================
Page: ThreeIsometricNode
URL: https://veillette.github.io/Almanach/api/mobius/three-isometric-node
Source: docs/api/mobius/three-isometric-node.md
Category: API | Tags: mobius, ThreeIsometricNode, ThreeNode, three.js, 3d, isometric | Status: verified
========================================================================

# ThreeIsometricNode

`ThreeIsometricNode` (from `scenerystack/mobius`) is the full-screen counterpart to [`ThreeNode`](/api/mobius/node-wrapping-conventions): instead of hosting a fixed-size three.js canvas as one child among other scenery Nodes, it takes a `ScreenView`'s `layoutBounds` and fills them with an isometric-scaled three.js viewport. `MobiusScreenView` and the [Three.js Integration](/examples/three-js-integration) example use this shape when 3D content is the primary backdrop for an entire screen.

```ts
import { ThreeIsometricNode } from 'scenerystack/mobius';
import { Bounds2 } from 'scenerystack/dot';
import { THREE } from 'scenerystack/mobius';

const threeIsometricNode = new ThreeIsometricNode( layoutBounds, {
  cameraPosition: new THREE.Vector3( 0, 0, 5 ),
  fov: 50
} );

threeIsometricNode.stage.threeScene.add( myMesh );
this.addChild( threeIsometricNode );
```

## Constructor

```ts
new ThreeIsometricNode( layoutBounds: Bounds2, providedOptions?: ThreeIsometricNodeOptions )
```

`ThreeIsometricNodeOptions` combines `NodeOptions` with `ThreeStageOptions` plus mobius-specific fields:

| Option | Default | Effect |
| --- | --- | --- |
| `fov` | `50` | Perspective camera field of view in degrees |
| `parentMatrixProperty` | identity `Matrix3` | Optional parent transform applied when projecting between screen and 3D space |
| `viewOffset` | `(0, 0)` | Pixel offset applied when mapping layout bounds to the embedded canvas |
| `getPhetioMouseHit` | `null` | Optional `( point: Vector2 ) => PhetioObject | null | 'phetioNotSelectable'` callback for PhET-iO Studio autoselect on background clicks |

Most `ThreeStageOptions` (`cameraPosition`, `backgroundColor`, `rendererParameters`, …) pass through to the internal [`ThreeStage`](/api/mobius/scene-and-camera-setup) the node constructs.

## Public members

| Member | Description |
| --- | --- |
| `stage` | The internal `ThreeStage` — add meshes/lights to `stage.threeScene` and read `stage.threeCamera` |
| `backgroundEventTarget` | A transparent `Rectangle` sized to `layoutBounds` that receives pointer events on empty background areas (useful for drag-to-rotate handlers) |

## When to use `ThreeIsometricNode` vs. `ThreeNode`

| Shape | Use when |
| --- | --- |
| `ThreeIsometricNode` | 3D fills (or dominates) an entire screen's layout bounds — typical mobius sim screens |
| `ThreeNode` | 3D is one fixed-size panel among other 2D UI — a small 3D preview, an inset viewport |

Both embed the renderer canvas via a `DOM` node with `preventTransform: true` so scenery never CSS-transforms the WebGL surface directly.


========================================================================
Page: ThreeNode, ThreeInstrumentable, and ThreeObject3DPhetioObject
URL: https://veillette.github.io/Almanach/api/mobius/node-wrapping-conventions
Source: docs/api/mobius/node-wrapping-conventions.md
Category: API | Tags: mobius, ThreeNode, ThreeInstrumentable, ThreeObject3DPhetioObject, three.js, phet-io | Status: verified
========================================================================

# ThreeNode, ThreeInstrumentable, and ThreeObject3DPhetioObject

These three exports from `scenerystack/mobius` solve two related but distinct problems: getting a three.js viewport onto the scenery scene graph at all (`ThreeNode`), and giving individual `THREE.Object3D` instances placed inside that viewport a PhET-iO identity (`ThreeInstrumentable` + `ThreeObject3DPhetioObject`).

## `ThreeNode`: a fixed-size three.js viewport

`ThreeNode` extends `scenerystack/scenery`'s `Node` and hosts one `ThreeStage` (see [ThreeStage](/api/mobius/scene-and-camera-setup)) at a fixed `width`/`height`, embedding the stage's renderer `<canvas>` via a `DOM` node (`preventTransform: true`, `pickable: false`) so scenery never tries to CSS-transform the canvas itself. It's the "content sits at one place in the scene graph" counterpart to `ThreeIsometricNode`, which instead takes over an entire `ScreenView`'s layout bounds with isometric scaling (that's the Node `MobiusScreenView` sets up for you — see [Three.js Integration](/examples/three-js-integration)). Use `ThreeNode` directly when you want 3D content as one ordinary-sized child among other scenery Nodes, rather than a full-screen 3D backdrop.

```ts
import { ThreeNode, THREE } from 'scenerystack/mobius';
import { Vector3 } from 'scenerystack/dot';

const threeNode = new ThreeNode( 400, 300, {
  cameraPosition: new Vector3( 0, 0, 3 )
} );

const geometry = new THREE.SphereGeometry( 0.5, 32, 16 );
const material = new THREE.MeshNormalMaterial();
threeNode.stage.threeScene.add( new THREE.Mesh( geometry, material ) );
threeNode.stage.threeScene.add( new THREE.DirectionalLight( 0xffffff, 1 ) );

// Call once the Node's transform/position in the global scene is settled...
threeNode.layout();
// ...and on every animation frame:
threeNode.render();
```

### `ThreeNode` constructor

```ts
new ThreeNode( width: number, height: number, providedOptions?: ThreeNodeOptions )
```

`ThreeNodeOptions` = `{ fov?: number }` (default `50`) plus every `ThreeStageOptions` (`cameraPosition`, `backgroundColorProperty`, `threeRendererOptions`, `threeRendererPixelRatio` — forwarded straight to the internal `ThreeStage`) plus ordinary `NodeOptions`.

| Member | Description |
| --- | --- |
| `stage` | The `ThreeStage` this Node hosts — add `THREE.Object3D`s to `stage.threeScene` |
| `backgroundEventTarget` | A `Rectangle` sized to `width`×`height`, added as the first child, for capturing drags/clicks that don't hit specific 3D content |
| `projectPoint( Vector3 )` → `Vector2` | Delegates to `stage.projectPoint` |
| `layout()` | Recomputes the stage's pixel dimensions from this Node's current global bounds and repositions the embedded canvas; call after any transform change |
| `render( target? )` | Renders the stage (`autoClear: true`) |
| `dispose()` | Disposes the `stage` |

## Instrumenting individual three.js objects

`ThreeNode`/`ThreeIsometricNode` give the *viewport* a place in the scene graph, but a `THREE.Object3D` you add to `stage.threeScene` (a `THREE.Mesh`, `THREE.Group`, etc.) is not itself a scenery `Node` or a `PhetioObject` — three.js has no concept of PhET-iO. `ThreeObject3DPhetioObject` and the `ThreeInstrumentable` mixin exist to attach a PhET-iO identity to such objects by composition, so PhET-iO Studio can see and select them in the tree.

```ts
import { ThreeInstrumentable, THREE } from 'scenerystack/mobius';

const InstrumentedMesh = ThreeInstrumentable( THREE.Mesh );

const sphere = new InstrumentedMesh( geometry, material, {
  tandem: tandem.createTandem( 'sphereMesh' )
} );
threeNode.stage.threeScene.add( sphere );
// sphere.phetioObject is the underlying ThreeObject3DPhetioObject.
```

### `ThreeObject3DPhetioObject`

```ts
new ThreeObject3DPhetioObject( providedOptions?: PhetioObjectOptions )
```

A `PhetioObject` subclass with no extra state of its own: `phetioType` defaults to its own `ThreeObject3DIO`, and `tandem` defaults to `Tandem.REQUIRED` (you must supply one). It's meant to be held *by composition* inside a three.js object, not extended.

### `ThreeInstrumentable( type )`

A memoized mixin function: `ThreeInstrumentable( SomeThreeClass )` returns a subclass of `SomeThreeClass` whose constructor takes the usual three.js constructor arguments plus a trailing `PhetioObjectOptions` object, and which exposes a `phetioObject: ThreeObject3DPhetioObject` (constructed from those options). Its overridden `dispose()` calls the wrapped type's own `dispose()` first, then disposes `phetioObject`.

| Member | Description |
| --- | --- |
| `phetioObject` | The `ThreeObject3DPhetioObject` instrumented for this instance |
| `dispose()` | Calls the wrapped type's own `dispose()` first (if present), then disposes `phetioObject` |

::: warning Instrumenting a three.js object does not capture its state
`ThreeObject3DIO`'s `toStateObject`/`stateSchema` are both empty (`{}`) — wrapping a `THREE.Object3D` with `ThreeInstrumentable` only gives it an address in the PhET-iO tree for Studio to select and reference. It does **not** serialize or restore position, rotation, material, or any other three.js state on PhET-iO save/load. If your sim needs 3D object state to survive a state restore, you must model that state separately (e.g. as `Property`s on your own model) and use it to drive the three.js object, rather than relying on this instrumentation.
:::


========================================================================
Page: ThreeStage
URL: https://veillette.github.io/Almanach/api/mobius/scene-and-camera-setup
Source: docs/api/mobius/scene-and-camera-setup.md
Category: API | Tags: mobius, ThreeStage, three.js, webgl, 3d | Status: verified
========================================================================

# ThreeStage

`ThreeStage` (from `scenerystack/mobius`) encapsulates the three main three.js primitives needed to render a 3D scene: a `THREE.Scene`, a `THREE.PerspectiveCamera`, and (when WebGL is available) a `THREE.WebGLRenderer`. It is a plain class, not a scenery `Node` — the two Nodes that actually place mobius content in a scene graph, `ThreeNode` and `ThreeIsometricNode`, each construct one `ThreeStage` internally and embed its renderer's `<canvas>` via a `DOM` node (see [ThreeNode and Object3D Instrumentation](/api/mobius/node-wrapping-conventions)). `ThreeStage` is where camera position, background color, dimensions, and screen-space/3D-space projection all live.

```ts
import { ThreeStage, THREE } from 'scenerystack/mobius';
import { Vector3 } from 'scenerystack/dot';
import { Color } from 'scenerystack/scenery';
import { Property } from 'scenerystack/axon';
```

## A minimal example

```ts
const stage = new ThreeStage( {
  cameraPosition: new Vector3( 0, 0, 5 ),
  backgroundColorProperty: new Property( new Color( 'black' ) )
} );

const geometry = new THREE.BoxGeometry( 1, 1, 1 );
const material = new THREE.MeshNormalMaterial();
const cube = new THREE.Mesh( geometry, material );
stage.threeScene.add( cube );

stage.threeScene.add( new THREE.DirectionalLight( 0xffffff, 1 ) );

stage.setDimensions( 400, 300 );
stage.render( undefined, true );
```

In an actual scenery-based sim you would not construct a bare `ThreeStage` like this — you'd get one for free from `ThreeNode`/`ThreeIsometricNode` (`someThreeNode.stage`), as shown in [Three.js Integration](/examples/three-js-integration). This snippet shows the pieces `ThreeStage` itself owns.

## Constructor

```ts
new ThreeStage( providedOptions?: ThreeStageOptions )
```

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `backgroundColorProperty` | `new Property( Color.BLACK )` | `TReadOnlyProperty<Color>` — sets `threeRenderer`'s clear color/alpha whenever it changes |
| `cameraPosition` | `new Vector3( 0, 0, 10 )` | Initial position of `threeCamera` |
| `threeRendererOptions` | `{ antialias, alpha: true, preserveDrawingBuffer }`, with `antialias`/`preserveDrawingBuffer` sourced from `MobiusQueryParameters` (`threeRendererAntialias`, `threeRendererPreserveDrawingBuffer`) — `alpha` is always hardcoded `true` | Forwarded to `new THREE.WebGLRenderer(...)` |
| `threeRendererPixelRatio` | from `MobiusQueryParameters` | Forwarded to `threeRenderer.setPixelRatio(...)` |

## Properties and methods

| Member | Description |
| --- | --- |
| `threeScene` | `THREE.Scene` — add your `THREE.Object3D`s (meshes, lights, groups) here |
| `threeCamera` | `THREE.PerspectiveCamera` — `near`/`far` are fixed to `1`/`100`; `fov`/`aspect` are set by the hosting Node |
| `threeRenderer` | `THREE.WebGLRenderer \| null` — `null` if WebGL isn't available (see `ThreeUtils.isWebGLEnabled()`) |
| `canvasWidth` / `canvasHeight`, `width`/`height` getters | Current renderer dimensions |
| `activeScale` | Scale factor applied to non-screen-coordinate interactions (e.g. rotation drags); maintained by the hosting Node's layout |
| `dimensionsChangedEmitter` / `contextLostEmitter` / `contextRestoredEmitter` | `TEmitter`s for size changes and WebGL context loss/restore |
| `setDimensions( width, height )` | Sets `canvasWidth`/`canvasHeight`, resizes the renderer, calls `threeCamera.updateProjectionMatrix()`, and fires `dimensionsChangedEmitter` — it does **not** itself change `threeCamera.aspect`; the hosting Node (or `adjustViewOffset`) is responsible for that |
| `render( target, autoClear )` | Renders `threeScene`/`threeCamera` into `target` (or the canvas, if `target` is `undefined`) |
| `renderToCanvas( supersampleMultiplier?, backingMultiplier?, scale? )` | Renders offscreen into a returned `HTMLCanvasElement` (used for screenshots) |
| `projectPoint( Vector3 )` → `Vector2` | Projects a 3D world point to a 2D global (screen) point |
| `unprojectPoint( Vector2, modelZ? )` → `Vector3` | Projects a 2D screen point back into the 3D scene at a given model z |
| `getRayFromScreenPoint( Vector2 )` → `Ray3` | Returns the camera ray through a given screen point (useful for picking) |
| `adjustViewOffset( cameraBounds: Bounds2 )` | Shifts the camera's projection view offset so its output lines up with `cameraBounds` — used internally for isometric layout/pan/zoom |
| `ThreeStage.computeIsometricFOV( fov, canvasWidth, canvasHeight, layoutWidth, layoutHeight )` | Static helper computing the FOV needed to keep isometric content correctly scaled across aspect ratios |
| `dispose()` | Disposes `threeRenderer` and `threeScene`, unlinks `backgroundColorProperty` |

::: warning `threeRenderer` can be `null`
`ThreeStage` only creates a `THREE.WebGLRenderer` if `ThreeUtils.isWebGLEnabled()` returns true at construction time. Every renderer-touching call in `ThreeStage` itself already guards with `this.threeRenderer && ...` — if you call `threeRenderer` methods directly from your own code, guard the same way rather than assuming WebGL is always available.
:::


========================================================================
Page: ThreeUtils
URL: https://veillette.github.io/Almanach/api/mobius/three-utils-helpers
Source: docs/api/mobius/three-utils-helpers.md
Category: API | Tags: mobius, ThreeUtils, three.js, webgl, 3d | Status: verified
========================================================================

# ThreeUtils

`ThreeUtils` (from `scenerystack/mobius`) is a plain object of static helper functions (not a class you instantiate) that bridges SceneryStack's own `dot`/`scenery` types and three.js's equivalents, provides low-level vertex-buffer writers for building simple quad geometry, and exposes the WebGL-availability check that `ThreeStage` uses to decide whether to create a `WebGLRenderer` at all.

```ts
import { ThreeUtils } from 'scenerystack/mobius';
import { Vector3 } from 'scenerystack/dot';
```

## A minimal example

```ts
// Guard before doing any WebGL-dependent setup.
if ( ThreeUtils.isWebGLEnabled() ) {
  const modelPosition = new Vector3( 1, 2, 3 );
  mesh.position.copy( ThreeUtils.vectorToThree( modelPosition ) );
}

// Build a single front-facing quad's position buffer, e.g. for a custom BufferGeometry.
import { Bounds2 } from 'scenerystack/dot';
const positions = ThreeUtils.frontVertices( new Bounds2( -1, -1, 1, 1 ), 0 );
geometry.setAttribute( 'position', new THREE.BufferAttribute( positions, 3 ) );
```

## Methods

| Member | Description |
| --- | --- |
| `vectorToThree( vector: Vector3 )` → `THREE.Vector3` | Converts a dot `Vector3` to a three.js vector |
| `threeToVector( vector: THREE.Vector3 )` → `Vector3` | The inverse conversion |
| `colorToThree( color: Color )` → `THREE.Color` | Converts a scenery `Color` to a three.js color |
| `frontVertices( bounds2: Bounds2, z )` → `Float32Array` | Vertices for a quad facing the camera (+z), spanning `bounds2` in x/y |
| `topVertices( bounds2: Bounds2, y )` → `Float32Array` | Vertices for an up-facing quad, spanning `bounds2` in x/z |
| `rightVertices( bounds2: Bounds2, x )` / `leftVertices( bounds2: Bounds2, x )` → `Float32Array` | Vertices for a right- or left-facing quad, spanning `bounds2` in z/y |
| `writeTriangle( array, index, x0, y0, z0, ..., x2, y2, z2 )` → `number` | Writes 9 floats (one triangle, counterclockwise winding) into `array` at `index`, returns the next free index |
| `writeQuad( array, index, ... 4 vertices ... )` → `number` | Writes 18 floats (two triangles) into `array`, returns the next free index |
| `textureLoader` (getter) | Singleton `THREE.TextureLoader`, created lazily on first access |
| `imageToTexture( image: HTMLImageElement, waitForLoad? )` → `THREE.Texture` | Loads a texture from an already-loaded `<img>`; pass `waitForLoad: true` to register an `asyncLoader` lock until it decodes |
| `isWebGLEnabled()` → `boolean` | `true` if the `webgl` query parameter allows it *and* `Utils.isWebGLSupported` — what `ThreeStage` checks before constructing a `WebGLRenderer` |

::: tip Check `isWebGLEnabled()` before assuming a renderer exists
`ThreeStage.threeRenderer` is only non-null when `ThreeUtils.isWebGLEnabled()` was true at construction time. Any code that builds textures, geometry, or renderer-dependent state outside of `ThreeStage` itself should perform the same check first, rather than assuming WebGL is always available (some embedding contexts and the `?webgl=false` query parameter can disable it).
:::


========================================================================
Page: Atom, Element, and AtomNode
URL: https://veillette.github.io/Almanach/api/nitroglycerin/atom-and-element
Source: docs/api/nitroglycerin/atom-and-element.md
Category: API | Tags: nitroglycerin, Atom, Element, AtomNode, chemistry | Status: verified
========================================================================

# Atom, Element, and AtomNode

`Element`, `Atom`, and `AtomNode` (all from `scenerystack/nitroglycerin`) split the model/view concerns for a single atom in a chemistry sim. `Element` is a set of ~17 static, immutable instances holding real physical constants (covalent radius, electronegativity, atomic weight, display color) for specific elements (H, C, N, O, ...). `Atom` is a lightweight, constructible-many-times wrapper around one `Element` that adds per-instance identity (a unique `id`/`reference`) — you construct many `Atom`s referencing the same `Element.O` static. `AtomNode` is the `scenery` view: a shaded sphere sized and colored from the wrapped `Element`.

```ts
import { Atom, Element, AtomNode } from 'scenerystack/nitroglycerin';
```

## A minimal example

```ts
const oxygenAtom = new Atom( Element.O );
const oxygenNode = new AtomNode( Element.O );

// or, from a symbol string:
const hydrogenAtom = Atom.createAtomFromSymbol( 'H' );
```

## `Element`

`Element` is not meant to be constructed directly in client code — use one of its static instances or look one up by symbol.

| Member | Description |
| --- | --- |
| `Element.H`, `Element.C`, `Element.N`, `Element.O`, ... | Static instances for the ~17 elements nitroglycerin models (`Ar, B, Be, Br, C, Cl, F, H, I, N, Ne, O, P, S, Si, Sn, Xe`) |
| `Element.elements` | Array of all static instances |
| `symbol` | e.g. `'O'` |
| `covalentRadius` / `vanDerWaalsRadius` | In picometers |
| `electronegativity` | Pauling units, `null` for noble gasses |
| `atomicWeight` | Atomic mass units (u) |
| `color` | `Color \| string` used by `AtomNode` |
| `Element.getElementBySymbol( symbol )` | Static lookup; asserts if the symbol isn't one of the modeled elements |
| `isSameElement( element )` / `isHydrogen()` / `isCarbon()` / `isOxygen()` | Identity/convenience predicates |

## `Atom`

```ts
new Atom( element: Element )
```

| Member | Description |
| --- | --- |
| `element` | The wrapped `Element` |
| `symbol`, `covalentRadius`, `covalentDiameter`, `electronegativity`, `atomicWeight`, `color` | Unpacked from `element` for convenience (`covalentDiameter` is `2 * covalentRadius`, otherwise not present on `Element`) |
| `id` / `reference` | Per-instance unique identifiers (`reference` is a hex counter, `id` is `` `${symbol}_${reference}` ``) — distinguishes two `Atom`s wrapping the same `Element` |
| `Atom.createAtomFromSymbol( symbol )` | Static convenience combining `Element.getElementBySymbol` and `new Atom(...)` |
| `hasSameElement( atom )` / `isHydrogen()` / `isCarbon()` / `isOxygen()` | Delegate to the wrapped `Element` |

## `AtomNode`

```ts
new AtomNode( element: Element, providedOptions?: AtomNodeOptions )
```

`AtomNode extends ShadedSphereNode` (from `scenerystack/scenery-phet`) — it takes an `Element`, not an `Atom`, and computes a display diameter from `element.covalentRadius` (compressed nonlinearly so the largest and smallest modeled atoms don't differ as dramatically on screen as their real radii would suggest). `mainColor` defaults to `element.color`; any other `ShadedSphereNodeOptions` may be passed through and override it.

```ts
const bigOxygen = new AtomNode( Element.O );
const smallHydrogen = new AtomNode( Element.H, { mainColor: 'lightgray' } ); // override the default element color
```

::: tip `AtomNode` takes an `Element`, not an `Atom`
Since `AtomNode` only needs `covalentRadius` and `color` — both already on `Element` — it skips `Atom` entirely. Reach for `Atom` only when you need per-instance identity (e.g. tracking individual atoms in a reaction simulation); for pure rendering, construct `AtomNode` straight from the `Element` static you need.
:::


========================================================================
Page: ChemUtils
URL: https://veillette.github.io/Almanach/api/nitroglycerin/chem-utils
Source: docs/api/nitroglycerin/chem-utils.md
Category: API | Tags: nitroglycerin, ChemUtils, Element, chemistry, formula | Status: verified
========================================================================

# ChemUtils

`ChemUtils` (from `scenerystack/nitroglycerin`) is a plain object of static chemistry helpers — not a class you construct. Simulation code reaches for it when building molecular formula strings from [`Element`](/api/nitroglycerin/atom-and-element) lists, sorting atoms for Hill-system display order, or turning plain-text formulas like `C2H4` into HTML subscripts for `RichText`.

```ts
import { ChemUtils, Element } from 'scenerystack/nitroglycerin';

const elements = [ Element.C, Element.C, Element.H, Element.H, Element.H, Element.H ];

ChemUtils.createSymbolWithoutSubscripts( elements ); // "C2H4"
ChemUtils.createSymbol( elements );                  // "C<sub>2</sub>H<sub>4</sub>"
ChemUtils.toSubscript( 'C2H4' );                     // same HTML subscript form
```

## Formula helpers

| Method | Description |
| --- | --- |
| `createSymbolWithoutSubscripts( elements )` | Builds a plain-text formula from an ordered `Element[]`, collapsing consecutive identical elements into counts (e.g. `[C,C,H,H,H,H]` → `"C2H4"`) |
| `createSymbol( elements )` | Same as above, then runs `toSubscript()` for HTML display |
| `toSubscript( inputString )` | Wraps every digit run in `<sub>` tags — `'C2H4'` → `'C<sub>2</sub>H<sub>4</sub>'` |

The input `elements` array must list atoms **in the order they should appear in the symbol** — `ChemUtils` does not infer ordering from connectivity; use the Hill-system sorters below when you need standard ordering first.

## Hill-system sorting

| Method | Description |
| --- | --- |
| `carbonHillSortValue( element )` | Sort key when the molecule contains carbon — carbon first, then hydrogen, then other elements alphabetically |
| `nonCarbonHillSortValue( element )` | Sort key for molecules without carbon — alphabetical by element symbol, with two-letter symbols after one-letter symbols sharing the same first character |

These return integers suitable for `Array.sort()` — lower values sort earlier. See the [Hill system](https://en.wikipedia.org/wiki/Hill_system) for the convention they implement.

::: tip Prefer prebuilt molecule Nodes for common formulas
Nitroglycerin also exports dozens of ready-made `*Node` classes (`H2ONode`, `CO2Node`, …) and [`MoleculeNode`](/api/nitroglycerin/molecule-node) for drawing. Reach for `ChemUtils` when your sim builds formulas dynamically from a model's atom list rather than from a fixed chemical identity.
:::


========================================================================
Page: MoleculeNode
URL: https://veillette.github.io/Almanach/api/nitroglycerin/molecule-node
Source: docs/api/nitroglycerin/molecule-node.md
Category: API | Tags: nitroglycerin, MoleculeNode, AtomNode, chemistry | Status: verified
========================================================================

# MoleculeNode

`MoleculeNode` (from `scenerystack/nitroglycerin`) is the abstract base class every pre-built molecule `Node` extends — it takes a fixed array of already-positioned `AtomNode`s, wraps them in an inner `Node` re-centered on `Vector2.ZERO` (so the molecule's origin is its geometric center regardless of how lopsided the individual atoms' layout is), and exposes that as the molecule's contents. Its constructor is `protected`, so you never instantiate `MoleculeNode` directly — you use one of its ~40 concrete subclasses (`H2ONode`, `CO2Node`, `NH3Node`, and so on), each of which knows its own molecule's atom arrangement.

```ts
import { H2ONode, CO2Node, NH3Node } from 'scenerystack/nitroglycerin';
```

## A minimal example

```ts
const water = new H2ONode();
const carbonDioxide = new CO2Node( { atomNodeOptions: { opacity: 0.9 } } );
const ammonia = new NH3Node();

someLayerNode.children = [ water, carbonDioxide, ammonia ];
```

## Constructor (subclasses only)

```ts
protected constructor( atomNodes: AtomNode[], providedOptions?: MoleculeNodeOptions )
```

Each concrete subclass builds its own `AtomNode[]` (using real bond geometry — e.g. `H2ONode` places two hydrogens below-and-to-the-sides of a larger oxygen) and calls `super( atomNodes, providedOptions )`. `HorizontalMoleculeNode` is one such intermediate subclass that lays out a linear sequence of elements left-to-right for you (used by `CO2Node`, among others), which is why some molecule Node constructors take an `Element[]` instead of pre-built `AtomNode[]`.

## `MoleculeNodeOptions`

| Option | Default | Effect |
| --- | --- | --- |
| `atomNodeOptions` | `undefined` | Forwarded to every `AtomNode` the concrete subclass constructs — the one option point common to all molecule Nodes, useful for e.g. dimming every atom uniformly |
| ...rest of `NodeOptions` | — | Everything `scenery`'s `Node` accepts, except `children` (owned internally by `MoleculeNode`) |

## Pre-built molecule subclasses (examples)

`scenerystack/nitroglycerin` exports around 40 concrete `MoleculeNode` subclasses, one per commonly-used molecule — each is a small, dedicated class rather than something you configure generically:

| Class | Molecule |
| --- | --- |
| `H2ONode` | Water |
| `CO2Node` | Carbon dioxide |
| `NH3Node` | Ammonia |
| `CH4Node` | Methane |
| `N2ONode` | Nitrous oxide |

(and ~35 more — `C2H4Node`, `SO2Node`, `PCl5Node`, `HClNode`, etc. — one per molecule nitroglycerin models.) Each accepts the same `atomNodeOptions` plus standard `NodeOptions`; check the specific subclass's `*NodeOptions` type for any molecule-specific additions.

::: tip Reach for a named subclass, not `MoleculeNode` itself
`MoleculeNode`'s constructor is `protected` specifically to prevent constructing a generic, ad hoc molecule shape — every real molecule in nitroglycerin has its own class encoding correct bond angles and atom placement. If the molecule you need isn't among the ~40 pre-built subclasses, compose your own `AtomNode`s directly (as `H2ONode` does internally) rather than trying to instantiate `MoleculeNode`.
:::


========================================================================
Page: arrayRemove, arrayDifference, and cleanArray
URL: https://veillette.github.io/Almanach/api/phet-core/collection-utilities
Source: docs/api/phet-core/collection-utilities.md
Category: API | Tags: phet-core, arrayRemove, arrayDifference, cleanArray, array, collections | Status: verified
========================================================================

# arrayRemove, arrayDifference, and cleanArray

`scenerystack/phet-core` exports a handful of small, standalone array utilities used throughout SceneryStack instead of hand-rolled loops or a general utility-belt library. The three most broadly useful are `arrayRemove` (delete one matching element in place), `arrayDifference` (classify elements of two arrays as "only in A," "only in B," or "in both"), and `cleanArray` (empty an array in place, or create one if given a falsy value) — all plain functions with no class or options object involved.

```ts
import { arrayRemove, arrayDifference, cleanArray } from 'scenerystack/phet-core';
```

## `arrayRemove`

```ts
arrayRemove<T>( array: T[], toRemove: T ): void
```

Removes the *first* matching element from `array` in place (via `splice`), asserting that the element is actually present — this is not a safe no-op removal, it's an assertion that the caller expected the element to be there.

```ts
const listeners = [ listenerA, listenerB, listenerC ];
arrayRemove( listeners, listenerB );
// listeners is now [ listenerA, listenerC ]
```

## `arrayDifference`

```ts
arrayDifference<T>( a: T[], b: T[], aOnly?: T[], bOnly?: T[], inBoth?: T[] ): T[]
```

Given two arrays of unique elements, sorts every element into "only in `a`," "only in `b`," or "in both," optionally writing into caller-supplied output arrays (each must start empty), and returns `aOnly` (the classic set-difference result).

```ts
const aOnly: number[] = [];
const bOnly: number[] = [];
const inBoth: number[] = [];
arrayDifference( [ 1, 2 ], [ 5, 2, 0 ], aOnly, bOnly, inBoth );
// aOnly: [ 1 ], bOnly: [ 5, 0 ], inBoth: [ 2 ]
```

Both input arrays must contain only unique values (`arrayDifference` asserts this) — it is not a general multiset diff.

## `cleanArray`

```ts
cleanArray<T>( arr?: T[] | null | undefined ): T[]
```

If given an array, empties it in place (via repeated `pop()`, chosen to avoid the garbage `length = 0` can generate) and returns the same reference; if given `null`/`undefined`, returns a fresh empty array instead. Useful for a field you want to "reset to empty" without deciding at each call site whether it's already been allocated.

```ts
this.activeListeners = cleanArray( this.activeListeners );
```

## Summary

| Function | Mutates input? | Returns |
| --- | --- | --- |
| `arrayRemove( array, toRemove )` | Yes | `void` |
| `arrayDifference( a, b, aOnly?, bOnly?, inBoth? )` | Only the output arrays, if supplied | `aOnly` |
| `cleanArray( arr? )` | Yes, if `arr` is truthy | The (now-empty) array |

::: tip `arrayRemove` asserts the element exists — it is not a safe "remove if present"
Calling `arrayRemove` on a value that isn't actually in the array throws (`item not found in Array`) rather than silently doing nothing. If removal is conditional, check `array.includes( item )` first, or use `_.pull`/manual filtering when "not found" is an expected case rather than a bug.
:::


========================================================================
Page: assertHasProperties and assertMutuallyExclusiveOptions
URL: https://veillette.github.io/Almanach/api/phet-core/assertion-helpers
Source: docs/api/phet-core/assertion-helpers.md
Category: API | Tags: phet-core, assertHasProperties, assertMutuallyExclusiveOptions, assertions, options | Status: verified
========================================================================

# assertHasProperties and assertMutuallyExclusiveOptions

`assertHasProperties` and `assertMutuallyExclusiveOptions` (from `scenerystack/phet-core`) are development-time assertion helpers for validating an object's shape at a call site — the first checks that certain named members exist (anywhere in the prototype chain), the second checks that certain groups of option keys are never supplied together. Both are no-ops in a production build; like the rest of SceneryStack's `assert && assert(...)` convention, they only run when assertions are enabled, so they should guard invariants, not carry runtime logic.

```ts
import { assertHasProperties, assertMutuallyExclusiveOptions } from 'scenerystack/phet-core';
```

## `assertHasProperties`

```ts
assertHasProperties( object: unknown, properties: string[] ): void
```

Asserts that `object` has an own property *or* an inherited (prototype-chain) property for every name in `properties`. Useful for validating a duck-typed dependency (e.g. "this object needs to look like a `TColor`") without importing its concrete class.

```ts
assertHasProperties( someNode, [ 'getOpacity', 'opacity', '_opacity' ] ); // no error if all three exist somewhere in the chain
assertHasProperties( { flower: 2 }, [ 'tree' ] );                        // throws: property not defined: tree
```

## `assertMutuallyExclusiveOptions`

```ts
assertMutuallyExclusiveOptions( options: object | null | undefined, ...sets: string[][] ): void
```

Asserts that at most one of the given key-sets has any of its keys present in `options` — pass one `string[]` per mutually-exclusive group. `options` may be `null`/`undefined` (treated as "nothing set," so it always passes).

Only one of the provided sets may have any of its keys present at all — using multiple keys *within* the same set is fine:

```ts
assertMutuallyExclusiveOptions( { tree: 1, flower: 2 }, [ 'tree' ], [ 'flower' ] );               // throws - one key used from each of the two sets
assertMutuallyExclusiveOptions( { flower: 2 }, [ 'tree' ], [ 'flower' ] );                        // fine - only the second set is used
assertMutuallyExclusiveOptions( { tree: 1, mountain: 2 }, [ 'tree', 'mountain' ], [ 'flower' ] ); // fine - both used keys belong to the first set
```

## Summary

| Function | Checks | Throws when |
| --- | --- | --- |
| `assertHasProperties( object, properties )` | Named members exist (own or inherited) | Any name in `properties` is missing everywhere in the chain |
| `assertMutuallyExclusiveOptions( options, ...sets )` | At most one option-key group is used | Keys from more than one of the provided `sets` are present in `options` |

::: tip Both are guarded by the global assertion flag, not a manual `if`
Call these directly — don't wrap them in `assert && assertHasProperties(...)` yourself the way you would with `window.assert`; these two functions already check internally whether assertions are enabled and no-op if not, matching the convention used by `merge` and other `phet-core` runtime checks.
:::


========================================================================
Page: EnumerationValue
URL: https://veillette.github.io/Almanach/api/phet-core/enumeration-value
Source: docs/api/phet-core/enumeration-value.md
Category: API | Tags: phet-core, EnumerationValue, Enumeration, enumeration | Status: verified
========================================================================

# EnumerationValue

`EnumerationValue` (from `scenerystack/phet-core`) is the base class every value of a closed, PhET-style enumeration extends — see [the Enumeration Pattern](/patterns/enumeration-pattern) for the full "why" and a worked example. This page documents `EnumerationValue` itself: what it provides once its sibling class `Enumeration` has scanned a subclass's static instances and wired them up.

```ts
import { EnumerationValue, Enumeration } from 'scenerystack/phet-core';
```

## Usage

```ts
class Direction extends EnumerationValue {
  public static readonly NORTH = new Direction();
  public static readonly SOUTH = new Direction();

  // Must come last: scans the static instances declared above.
  public static readonly enumeration = new Enumeration( Direction );
}

Direction.NORTH.name;              // 'NORTH' - filled in by the Enumeration constructor
Direction.NORTH.enumeration.values; // [ Direction.NORTH, Direction.SOUTH ]
Direction.NORTH.toString();        // 'NORTH'
```

Before `new Enumeration( Direction )` runs, a freshly-constructed `EnumerationValue`'s `name` and `enumeration` are unset — reading them throws. `Enumeration`'s constructor walks `Object.keys` on the class (and its supertypes, to support augmenting an existing enumeration) looking for `instanceof` matches, and assigns `name`/`enumeration` on each one it finds, in declaration order.

## Members

| Member | Description |
| --- | --- |
| `name` (getter) | The static property key the instance was assigned to (e.g. `'NORTH'`); throws if read before `Enumeration` has run |
| `enumeration` (getter) | The owning `Enumeration<this>` instance; throws if read before `Enumeration` has run |
| `toString()` | Returns `name` |
| `EnumerationValue.sealedCache` | A `Set` of constructors that already have an `Enumeration` built for them — `Enumeration`'s constructor adds to it, and the base `EnumerationValue` constructor throws if you try to `new` a sealed constructor directly (subclassing it further is still fine) |

`name` and `enumeration` are set-once: assigning either a second time throws, which is what makes them safe to treat as immutable identity after construction.

::: warning You cannot construct new values after `Enumeration` has run
Calling `new Enumeration( Direction )` seals `Direction` in `EnumerationValue.sealedCache` — any subsequent `new Direction()` throws. Declare every static instance *before* the `public static readonly enumeration = new Enumeration( Direction )` line, and add that line last, exactly once, per concrete enumeration class.
:::


========================================================================
Page: optionize and merge
URL: https://veillette.github.io/Almanach/api/phet-core/optionize-and-merge
Source: docs/api/phet-core/optionize-and-merge.md
Category: API | Tags: phet-core, optionize, merge, combineOptions, options | Status: verified
========================================================================

# optionize and merge

`optionize` (from `scenerystack/phet-core`) is the type-checked function almost every SceneryStack class constructor calls to combine its own default option values, its superclass's defaults, and a caller-provided options object into one final options object — it's what the [options pattern](/patterns/options-pattern) is built on. `merge` is the plain-JavaScript deep-merge function `optionize` delegates to at runtime; reach for `merge` directly only when you're combining plain option-literal objects outside a class constructor and don't need `optionize`'s compile-time "every optional field needs a default" check.

```ts
import { optionize, merge, combineOptions } from 'scenerystack/phet-core';
```

## `optionize`

```ts
optionize<ProvidedOptions, SelfOptions = ProvidedOptions, ParentOptions = Record<never, never>>()
  ( defaults: OptionizeDefaults<SelfOptions, ParentOptions, ProvidedOptions>,
    providedOptions: ProvidedOptions | undefined )
  => OptionizeDefaults<SelfOptions, ParentOptions> & ProvidedOptions
```

It's called with an empty type-argument list `<...>()` immediately followed by the actual `( defaults, providedOptions )` call — the split exists so TypeScript can infer `ProvidedOptions`/`SelfOptions`/`ParentOptions` from explicit type arguments while still inferring the return type from the runtime arguments.

```ts
type SelfOptions = {
  headHeight?: number;
  doubleHead?: boolean;
};
export type ArrowNodeOptions = SelfOptions & PathOptions;

const options = optionize<ArrowNodeOptions, SelfOptions, PathOptions>()( {
  headHeight: 10,
  doubleHead: false,
  fill: 'black' // a PathOptions default this class chooses to supply
}, providedOptions );
```

The type system enforces that every optional key declared in `SelfOptions` has a default in the first argument — omit one and the call fails to typecheck, not just at runtime.

## Related functions in the same file

| Function | Signature | When to use |
| --- | --- | --- |
| `optionize3` | `optionize3<ProvidedOptions, SelfOptions, ParentOptions>()( {}, defaults, providedOptions )` | Same as `optionize`, for call sites (like `ResponsePacket`) that need an explicit empty-object first argument rather than mutating `defaults` in place |
| `optionize4` | `optionize4<ProvidedOptions, SelfOptions, ParentOptions>()( {}, constantDefaults, classDefaults, providedOptions )` | Adds a middle layer — e.g. sim-wide constants — between class defaults and the caller's options |
| `combineOptions<Type>( target, ...sources )` | Returns `Type` | Merges plain option-literal objects of the *same* type (no self/parent split, no default-completeness check) — for combining options outside a constructor |

All four are thin typed wrappers that call `merge` underneath; the type layer is compile-time only; `merge` performs the actual runtime combination.

## `merge`

```ts
merge<A, B>( target: A, ...sources: B[] ): A & B
```

Recursively copies every own, non-`undefined` property from each source onto `target`, left to right (later sources win). Nested objects are merged recursively **only** when the key ends in `Options` (case-sensitive) and is not literally `'Options'` itself — e.g. `numberDisplayOptions: {...}` recurses, but arrays, functions, class instances, and any object with getters/setters throw an assertion error rather than being merged, since `merge` only supports plain object literals.

```ts
const options = merge( {}, CommonConstants.SOME_DEFAULTS, { fill: 'red' }, providedOptions );
```

::: warning `merge`'s recursion is keyed on the literal suffix `Options`
A field named `buttonOptions` merges deeply with a same-named field from an earlier source; a field named `button` (holding an object) is replaced wholesale instead. This is easy to get wrong when refactoring a nested options object — renaming a `*Options` field to drop that suffix silently changes merge behavior from "combine" to "overwrite."
:::


========================================================================
Page: Orientation
URL: https://veillette.github.io/Almanach/api/phet-core/orientation
Source: docs/api/phet-core/orientation.md
Category: API | Tags: phet-core, Orientation, EnumerationValue, layout, enumeration | Status: complete
========================================================================

# Orientation

`Orientation` (from `scenerystack/phet-core`) is a two-valued [`EnumerationValue`](/api/phet-core/enumeration-value) enumeration — `Orientation.HORIZONTAL` and `Orientation.VERTICAL` — used throughout layout-adjacent code (`FlowBox`, sliders, bamboo's [`GridLineSet`/`TickMarkSet`/`TickLabelSet`](/api/bamboo/gridlines-and-tick-marks) and [axis Nodes](/api/bamboo/axis-nodes)) so that logic can be written once and parameterized by orientation, instead of duplicated for the horizontal and vertical cases. Each value carries a bundle of orientation-specific string keys (`'centerX'` vs `'centerY'`, `'left'`/`'right'` vs `'top'`/`'bottom'`, `'preferredWidth'` vs `'preferredHeight'`, …) so you can index into a `Node` or `Bounds2` generically: `node[ orientation.centerCoordinate ] = value` works for either orientation without an `if`.

```ts
import { Orientation } from 'scenerystack/phet-core';
```

## A minimal example

```ts
function centerAlong( node: Node, orientation: Orientation, value: number ): void {
  // For HORIZONTAL this sets node.centerX; for VERTICAL it sets node.centerY.
  node[ orientation.centerCoordinate ] = value;
}

centerAlong( myNode, Orientation.HORIZONTAL, 100 );

// The opposite orientation, useful for "the other axis" logic.
Orientation.HORIZONTAL.opposite === Orientation.VERTICAL; // true

// Build a Vector-like value with the components in the right order for this orientation.
const size = Orientation.VERTICAL.toVector( 10, 20, Vector2 ); // Vector2( 20, 10 ) -- (secondary, primary) for VERTICAL
```

## Values

| Value | Meaning |
| --- | --- |
| `Orientation.HORIZONTAL` | The x-axis / left-right orientation |
| `Orientation.VERTICAL` | The y-axis / top-bottom orientation |

## Members

Every `Orientation` value carries these fields (all set in the constructor, `readonly`):

| Member | `HORIZONTAL` value | `VERTICAL` value |
| --- | --- | --- |
| `coordinate` | `'x'` | `'y'` |
| `centerCoordinate` | `'centerX'` | `'centerY'` |
| `minCoordinate` / `maxCoordinate` | `'minX'` / `'maxX'` | `'minY'` / `'maxY'` |
| `minSide` / `maxSide` | `'left'` / `'right'` | `'top'` / `'bottom'` |
| `minSize` / `maxSize` | `'minWidth'` / `'maxWidth'` | `'minHeight'` / `'maxHeight'` |
| `rectCoordinate` / `rectSize` | `'rectX'` / `'rectWidth'` | `'rectY'` / `'rectHeight'` |
| `flowBoxOrientation` / `ariaOrientation` | `'horizontal'` | `'vertical'` |
| `size` | `'width'` | `'height'` |
| `line` | `'column'` | `'row'` |
| `preferredSize` / `localPreferredSize` | `'preferredWidth'` / `'localPreferredWidth'` | `'preferredHeight'` / `'localPreferredHeight'` |
| `sizable` | `'widthSizable'` | `'heightSizable'` |
| `opposite` | `Orientation.VERTICAL` | `Orientation.HORIZONTAL` |

And these methods:

| Member | Description |
| --- | --- |
| `modelToView( modelViewTransform, value )` / `viewToModel( modelViewTransform, value )` | Calls the transform's `modelToViewX`/`Y` (or `viewToModelX`/`Y`) method matching this orientation |
| `toVector( primary, secondary, VectorType )` | Builds a `VectorType` instance with components in the right slot for this orientation — `(primary, secondary)` for `HORIZONTAL`, `(secondary, primary)` for `VERTICAL` — zero-padded to support up to a 4-component vector type |
| `Orientation.fromLayoutOrientation( 'horizontal' \| 'vertical' )` | Static helper converting a `FlowBox`-style string literal to the matching `Orientation` value |

::: tip Prefer `orientation.opposite` over hardcoding a check
Because `HORIZONTAL.opposite` and `VERTICAL.opposite` are wired up as circular references right after both values are constructed, code that needs "the other axis" (e.g. bamboo's `TickMarkSet`, which positions a tick's tail using `axisOrientation.opposite`) can just read `.opposite` instead of writing `orientation === Orientation.HORIZONTAL ? Orientation.VERTICAL : Orientation.HORIZONTAL`. It also composes correctly if a third orientation value were ever added, which a hardcoded ternary would not.
:::


========================================================================
Page: platform
URL: https://veillette.github.io/Almanach/api/phet-core/platform-detection
Source: docs/api/phet-core/platform-detection.md
Category: API | Tags: phet-core, platform, browser, useragent | Status: complete
========================================================================

# platform

`platform` (from `scenerystack/phet-core`, note the lowercase name — it's a plain object, not a class) is a set of boolean flags describing the current browser and OS, derived once from `navigator.userAgent` when the module is first imported. It exists for the rare cases where SceneryStack's normal feature/capability abstractions aren't enough and code genuinely needs to branch on *which* browser it's running in.

```ts
import { platform } from 'scenerystack/phet-core';
```

## A minimal example

```ts
if ( platform.mobileSafari ) {
  // Work around an iOS Safari-specific rendering quirk.
  node.renderer = 'canvas';
}

if ( platform.firefox ) {
  // ...
}
```

## Flags

| Flag | True when |
| --- | --- |
| `firefox` | User agent string contains `"firefox"` (case-insensitive) |
| `mobileSafari` | Running as a PhET "phet-app" wrapper, or the UA matches iPod/iPhone/iPad, or `navigator.platform === 'MacIntel'` with multitouch (modern iPadOS reporting as Mac) — combined with an `AppleWebKit` match |
| `safari` | `mobileSafari`, or the UA matches a `Version/…` + `Safari/…` + `AppleWebKit` pattern (desktop Safari) |
| `safari5` / `safari6` / `safari7` / `safari9` / `safari10` / `safari11` | Desktop/iOS Safari matching that specific major version string |
| `ie` | Detected as any version of Internet Explorer (via `getInternetExplorerVersion() !== -1`) |
| `ie9` / `ie10` / `ie11` | Detected as that specific IE version |
| `edge` | UA contains `Edge/` (legacy EdgeHTML Edge, not Chromium Edge) |
| `chromium` | UA matches `chrom(e\|ium)` and is not legacy Edge |
| `chromeOS` | UA contains `CrOS` |
| `android` | UA contains `Android` |
| `mac` | `navigator.platform` contains `Mac` |

## Methods

`platform` has no methods — it is a plain object of booleans computed eagerly at import time, not re-evaluated if the environment somehow changes afterward.

::: warning "Use sparingly, if at all"
That's the source file's own doc comment. Almost everything `platform` is used for in practice — layout quirks, input event differences, rendering fallbacks — has a better, more targeted abstraction elsewhere in SceneryStack (feature detection, capability checks, CSS). Reach for `platform` only as a last resort for a genuinely browser-specific workaround, and prefer the narrowest flag available (e.g. `mobileSafari` over `safari`) so the branch doesn't accidentally widen to browsers you didn't test.
:::


========================================================================
Page: Pool
URL: https://veillette.github.io/Almanach/api/phet-core/pool
Source: docs/api/phet-core/pool.md
Category: API | Tags: phet-core, Pool, Poolable, performance, memory | Status: complete
========================================================================

# Pool

`Pool` (from `scenerystack/phet-core`) manages a reusable set of instances of a single class, so that code creating and discarding many short-lived objects per frame (vectors for an intermediate calculation, drag-listener event objects, per-point plot helpers) can pull an existing instance back out of a pool instead of paying for a fresh allocation and, later, garbage collection. You construct one `Pool<T>` per class, typically stored as a `static readonly pool` field on that class, and the pool's `create()`/`fetch()`/`freeToPool()` methods stand in for `new`.

```ts
import { Pool } from 'scenerystack/phet-core';
```

## A minimal example

```ts
class Vector2Scratch {
  public x = 0;
  public y = 0;

  public initialize( x: number, y: number ): this {
    this.x = x;
    this.y = y;
    return this;
  }

  public freeToPool(): void {
    Vector2Scratch.pool.freeToPool( this );
  }

  // Must come after `initialize` is defined -- Pool reads it off the prototype.
  public static readonly pool = new Pool( Vector2Scratch );
}

// Pulls a recycled instance and re-initializes it, or constructs a new one if the pool is empty.
const scratch = Vector2Scratch.pool.create( 3, 4 );

// ...use scratch...

// Release it back to the pool once you're done -- no other references should remain.
scratch.freeToPool();
```

## Constructor

```ts
new Pool<T extends Constructor>( type: T, providedOptions?: PoolOptions<T> )
```

`type` is the class being pooled. If `type.prototype.initialize` exists with a compatible signature, `providedOptions` is optional; otherwise TypeScript requires you to pass an `initialize` option explicitly (`Pool` needs some function to call to "re-run the constructor" on a recycled instance).

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `initialize` | `type.prototype.initialize` | The function called on a recycled instance to reinitialize it with new constructor-like arguments; must return the object itself |
| `defaultArguments` | `[]` | Arguments used to construct instances when the pool needs to grow without a caller-supplied argument list (e.g. filling `initialSize`) |
| `maxSize` | `100` | Upper bound on how many instances `freeToPool()` will retain; excess instances are simply dropped (left for normal GC) |
| `initialSize` | `0` | Number of instances eagerly created (via `defaultArguments`) when the `Pool` is constructed |
| `useDefaultConstruction` | `false` | If `true`, a pool miss always constructs via `defaultArguments` first and then calls `initialize` with the real arguments, instead of constructing directly with the real arguments |

## Methods

| Member | Description |
| --- | --- |
| `create( ...args )` | Returns an instance behaving as if constructed with `args`: pops one from the pool and calls `initialize( ...args )` on it if available, otherwise constructs a new one |
| `fetch()` | Returns an instance with *arbitrary* leftover state — pops one from the pool if available, otherwise constructs one from `defaultArguments`. Use this only when you're about to overwrite all relevant state yourself |
| `freeToPool( object )` | Returns `object` to the pool if `poolSize < maxPoolSize`; otherwise the object is silently dropped (left for the garbage collector) |
| `forEach( callback )` | Iterates the objects currently sitting in the pool |
| `poolSize` (getter) | Number of instances currently held in the pool |
| `maxPoolSize` (getter/setter) | The cap `freeToPool()` checks against |

::: tip `Pool` supersedes the older `Poolable.mixInto()` mixin
`scenerystack/phet-core` also exports `Poolable`, but its own source comment marks it `@deprecated - Please use Pool.ts instead as the new pooling pattern`. `Poolable.mixInto( MyType, options )` retrofits static `pool`/`createFromPool`/`dirtyFromPool` members onto an existing class via mutation, whereas `Pool` is a plain, explicit object you construct and assign yourself (`static readonly pool = new Pool( MyType )`) — prefer `Pool` in new code, and treat `Poolable` as something you might still encounter reading older call sites, not something to reach for.
:::


========================================================================
Page: Bucket
URL: https://veillette.github.io/Almanach/api/phetcommon/bucket
Source: docs/api/phetcommon/bucket.md
Category: API | Tags: phetcommon, Bucket, SphereBucket, model | Status: verified
========================================================================

# Bucket

`Bucket` (from `scenerystack/phetcommon`) is the model half of the "bucket" UI element seen across PhET sims — a container drawn with a 3D-ish tilted opening that other model objects (atoms, molecules, balls) can be dragged out of and back into. `Bucket` itself only computes shapes and stores presentation data (position, size, colors, caption); it defines no notion of "contents," which is deliberately left to a subclass. It extends `PhetioObject` (from `scenerystack/tandem`), so a `Bucket` can be instrumented for PhET-iO like any other model element.

```ts
import { Bucket } from 'scenerystack/phetcommon';
import { Vector2, Dimension2 } from 'scenerystack/dot';

const bucket = new Bucket( {
  position: new Vector2( 0, 0 ),
  size: new Dimension2( 220, 60 ),
  baseColor: '#4d92c0',
  captionText: 'Atoms'
} );

// Shapes are computed at construction time from position/size:
bucket.holeShape;      // the elliptical "opening" of the bucket
bucket.containerShape; // the tilted 3D-ish body of the bucket
```

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `position` | `Vector2.ZERO` | Model position of the **center of the bucket's opening** — not the bottom or the visual center, since that's the point other code most often needs to align against |
| `size` | `Dimension2( 200, 50 )` | Overall dimensions used to derive `holeShape` and `containerShape` |
| `baseColor` | `'#ff0000'` | Base fill color for the bucket body (a view reads this to style itself) |
| `captionText` | `''` | Label text (plain string or `TReadOnlyProperty<string>` for translated/dynamic captions) |
| `captionColor` | `'white'` | Color for the caption text |
| `invertY` | `false` | Flips the bucket's shape vertically, for use with a y-down (inverted) model coordinate convention |

`Bucket` is a base class — the shapes it computes are for a view to render, but `Bucket` itself has no `addParticle`/`removeParticle`-style API for managing contents.

## Public state

| Member | Effect |
| --- | --- |
| `position` | The model position (mutable) of the bucket's opening center |
| `size` | The `Dimension2` used to compute the bucket's shapes |
| `holeShape` | A `Shape` (from `scenerystack/kite`) for the elliptical opening |
| `containerShape` | A `Shape` for the tilted body of the bucket |
| `baseColor`, `captionText`, `captionColor` | Presentation data for a view to read |

::: tip SphereBucket adds the actual contents-management API
`Bucket` only computes geometry — for a working bucket that spherical model objects can actually be added to, removed from, and stacked within (with automatic layout/relayout as items come and go), use `SphereBucket<Particle>` (also exported from `scenerystack/phetcommon`), which extends `Bucket` and adds `addParticleFirstOpen()`, `addParticleNearestOpen()`, `removeParticle()`, `extractClosestParticle()`, and `reset()`. It expects each particle to expose `positionProperty`, `destinationProperty`, `isDraggingProperty`, and `containerProperty` — see the `Spherical` type it's generic over.
:::

On the view side, `scenerystack/scenery-phet` exports matching `BucketFront` and `BucketHole` Nodes, which read a `Bucket`'s (or `SphereBucket`'s) `containerShape`/`holeShape`/colors/caption directly — `BucketHole` is drawn behind the draggable contents and `BucketFront` in front, so particles can appear to drop "into" the bucket.


========================================================================
Page: Fraction
URL: https://veillette.github.io/Almanach/api/phetcommon/fraction
Source: docs/api/phetcommon/fraction.md
Category: API | Tags: phetcommon, Fraction, model, math | Status: complete
========================================================================

# Fraction

`Fraction` (from `scenerystack/phetcommon`) represents a fraction as an integer `numerator` and integer `denominator`, with arithmetic operations that stay exact (no floating-point rounding) as long as the values involved stay below 2^53. It's the model class behind PhET's fraction- and ratio-based sims — every operation preserves the numerator/denominator pair rather than collapsing to a decimal, so `1/3 + 1/3` stays representable exactly instead of becoming `0.6666666666666666`.

```ts
import { Fraction } from 'scenerystack/phetcommon';
```

## A minimal example

```ts
const a = new Fraction( 1, 3 );
const b = new Fraction( 1, 6 );

const sum = a.plus( b );        // Fraction( 9, 18 ) -- lcm-based denominator, NOT auto-reduced
sum.reduce();                   // mutates sum in place to Fraction( 1, 2 )

a.getValue();                   // 0.3333333333333333 -- the fraction still exposes a numeric value
a.isReduced();                  // true (gcd(1, 3) === 1)
Fraction.fromDecimal( 0.25 );   // Fraction( 1, 4 )
```

## Constructor

```ts
new Fraction( numerator: number, denominator: number )
```

Both arguments must be integers — asserted at construction and on every subsequent `numerator`/`denominator` setter call. `Fraction` does not validate `denominator !== 0`; a zero denominator is allowed to be constructed (some operations, like `dividedInteger`, explicitly note that division by zero is permitted).

## Static members

| Member | Value / Signature |
| --- | --- |
| `Fraction.ZERO` | `new Fraction( 0, 1 )` |
| `Fraction.ONE` | `new Fraction( 1, 1 )` |
| `Fraction.fromInteger( value )` | Builds `new Fraction( value, 1 )` |
| `Fraction.fromDecimal( value )` | Converts a decimal `number` to an equivalent, reduced `Fraction` by counting decimal places |
| `Fraction.fromStateObject( stateObject )` | Deserializes from `{ numerator, denominator }`, for PhET-iO |
| `Fraction.FractionIO` | The `IOType` used to serialize/deserialize `Fraction` instances for PhET-iO state |

## Instance members

| Member | Effect |
| --- | --- |
| `numerator` / `denominator` (getter/setter) | Read or replace either integer component directly |
| `getValue()` / `value` (getter) | `numerator / denominator` as a floating-point number |
| `isInteger()` | Whether the fraction reduces to a whole number (`numerator % denominator === 0`) |
| `isReduced()` | Whether `gcd(numerator, denominator) === 1` |
| `reduce()` | Divides both components by their GCD, **mutating this instance**; returns `this` |
| `reduced()` | Returns a new, reduced `Fraction`, leaving this one untouched |
| `copy()` | Returns a new `Fraction` with the same numerator/denominator |
| `equals( fraction )` | True only if numerator **and** denominator match exactly — `1/2` and `2/4` are not `equals()`, even though they have the same value |
| `isLessThan( fraction )` | Value comparison, computed via exact subtraction (not floating-point division) to avoid precision loss |
| `sign` (getter) | `Math.sign( this.getValue() )` |
| `abs()` | Returns a new `Fraction` with both components made non-negative |
| `add( f )` / `subtract( f )` / `multiply( f )` / `divide( f )` | **Mutating** operations — modify `this` and return it. Sums/differences use the LCM of the two denominators; none of these reduce the result automatically |
| `plus( f )` / `minus( f )` / `times( f )` / `divided( f )` | Non-mutating equivalents — each returns a new `Fraction`, leaving `this` unchanged |
| `plusInteger( n )` / `minusInteger( n )` / `timesInteger( n )` / `dividedInteger( n )` | Convenience non-mutating operations against a plain integer, keeping this fraction's existing denominator (for `plusInteger`/`minusInteger`/`timesInteger`) |
| `toString()` | Returns `"numerator/denominator"` |
| `toStateObject()` | Serializes to `{ numerator, denominator }` |

::: warning Arithmetic results are not automatically reduced
`plus()`, `minus()`, `times()`, `divided()` (and their mutating counterparts) deliberately leave the result unreduced — e.g. `new Fraction(1,3).plus(new Fraction(1,6))` gives `Fraction(9, 18)`, not `Fraction(1, 2)`. Call `.reduce()` (mutating) or `.reduced()` (non-mutating) explicitly whenever you need a fraction in lowest terms, such as before comparing two fractions with `equals()`, which checks the numerator/denominator pair exactly rather than the reduced value.
:::


========================================================================
Page: ModelViewTransform2
URL: https://veillette.github.io/Almanach/api/phetcommon/model-view-transform
Source: docs/api/phetcommon/model-view-transform.md
Category: API | Tags: phetcommon, dot, coordinates, transform, ModelViewTransform2 | Status: verified
========================================================================

# ModelViewTransform2

`ModelViewTransform2` (from `scenerystack/phetcommon`) converts between **model coordinates** — meters, moles, whatever your physics uses, typically with **y pointing up** — and **view coordinates** — scenery pixels, with **y pointing down**. Keeping the model in physical units and doing all conversion at the view boundary is a core SceneryStack convention; the model should never know about pixels.

```ts
import { ModelViewTransform2 } from 'scenerystack/phetcommon';
import { Vector2 } from 'scenerystack/dot';
```

## Creating a transform

The most common factory for physics-style simulations maps a single model point to a view point, applies a uniform scale, and inverts the y axis:

```ts
// Model origin at the horizontal center, 100 px from the bottom of the layout
// bounds; 1 model unit (e.g. 1 meter) = 50 view pixels; +y up in the model.
const modelViewTransform = ModelViewTransform2.createSinglePointScaleInvertedYMapping(
  Vector2.ZERO,                                             // model point
  new Vector2( layoutBounds.centerX, layoutBounds.maxY - 100 ), // view point
  50                                                        // view units per model unit
);
```

Other factory methods:

| Factory | Use case |
| --- | --- |
| `createIdentity()` | Model units are view units (still useful as a placeholder) |
| `createOffsetScaleMapping( offset, scale )` | Translate + uniform scale, no y inversion |
| `createSinglePointScaleMapping( modelPoint, viewPoint, scale )` | Like the inverted-y version, but y-down in the model too |
| `createSinglePointScaleInvertedYMapping( modelPoint, viewPoint, scale )` | The standard choice for physics (y-up model) |
| `createRectangleMapping( modelBounds, viewBounds )` | Fit a model rectangle onto a view rectangle |
| `createRectangleInvertedYMapping( modelBounds, viewBounds )` | Same, with y inversion |

## Converting values

```ts
// Positions (affected by translation, scale, and y inversion)
const viewPosition = modelViewTransform.modelToViewPosition( body.positionProperty.value );
const modelPosition = modelViewTransform.viewToModelPosition( viewPoint );

// Deltas and distances (affected by scale only — no translation)
const viewDx = modelViewTransform.modelToViewDeltaX( body.radius );
const viewDelta = modelViewTransform.modelToViewDelta( velocity );

// Bounds and shapes
const viewBounds = modelViewTransform.modelToViewBounds( model.wallBounds );
const viewShape = modelViewTransform.modelToViewShape( orbitShape );
```

::: warning Positions vs. deltas
`modelToViewPosition` applies the full transform including translation. For *sizes*, *radii*, and *velocities*, use the delta methods (`modelToViewDeltaX`, `modelToViewDelta`, …) — otherwise the offset of the model origin gets baked into your lengths, and with an inverted-y mapping `modelToViewDeltaY` of a positive height is correctly **negative**.
:::

## Typical wiring in a view component

```ts
class BodyNode extends Circle {
  public constructor( body: Body, modelViewTransform: ModelViewTransform2 ) {
    super( modelViewTransform.modelToViewDeltaX( body.radius ), { fill: 'teal' } );

    body.positionProperty.link( position => {
      this.translation = modelViewTransform.modelToViewPosition( position );
    } );
  }
}
```

The same transform instance is passed to [drag listeners](/patterns/drag-listeners) via their `transform` option, so pointer motion in view coordinates updates the model in model coordinates.


========================================================================
Page: StringUtils
URL: https://veillette.github.io/Almanach/api/phetcommon/string-utils
Source: docs/api/phetcommon/string-utils.md
Category: API | Tags: phetcommon, StringUtils, i18n, strings | Status: verified
========================================================================

# StringUtils

::: warning About this page's title
This page was originally planned to cover `PhetcommonQueryParameters` — but no such export exists in the real `scenerystack` package. `phetcommon`'s barrel (`src/phetcommon.ts`) exports exactly five things: `AssertUtils`, [`Bucket`](/api/phetcommon/bucket), `Fraction`, `SphereBucket`, `StringUtils`, and [`ModelViewTransform2`](/api/phetcommon/model-view-transform); phetcommon defines no query parameters of its own (query parameters for a sim's screens/behavior are declared per-library, e.g. `sunQueryParameters`, and read via `scenerystack/query-string-machine` — see the [Query Parameters Pattern](/patterns/query-parameters-pattern)). This page documents `StringUtils` instead, a real, exported, and frequently-used phetcommon utility.
:::

`StringUtils` (from `scenerystack/phetcommon`) is a small collection of static string-handling functions, used throughout SceneryStack for filling in translated pattern strings and for keeping bidirectional (LTR/RTL) text safe when numbers or substrings get spliced into a larger, possibly differently-directioned, string. It's a plain object of functions, not a class — there's nothing to construct.

```ts
import { StringUtils } from 'scenerystack/phetcommon';

StringUtils.fillIn( '{{name}} is {{age}} years old', { name: 'Ada', age: 23 } );
// 'Ada is 23 years old'

StringUtils.capitalize( 'hello there' );
// 'Hello there'
```

## Methods

| Method | Effect |
| --- | --- |
| `fillIn( template, values )` | Replaces `{{key}}` placeholders in `template` with `values[key]` — `template` may be a plain string or anything with a `.get()` (like a Property); unused keys in `values` are ignored, and unmatched placeholders are left as-is |
| `format( pattern, ...args )` | **Deprecated** — the older positional `{0}`/`{1}` substitution; prefer `fillIn` for new code |
| `capitalize( str )` | Capitalizes the first letter, skipping any leading whitespace/control characters — English-oriented, not locale-aware |
| `wrapLTR( str )` / `wrapRTL( str )` | Wraps `str` in Unicode LTR/RTL embedding marks so it renders in a fixed direction regardless of surrounding text |
| `wrapDirection( str, direction )` | Calls `wrapLTR`/`wrapRTL` based on a `'ltr' \| 'rtl'` argument |
| `toFixedLTR( number, digits )` | `number.toFixed( digits )`, wrapped with `wrapLTR` so a negative sign always renders on the left even inside RTL text |
| `toFixedNumberLTR( number, digits )` | Like `toFixedLTR`, but drops trailing zeros (uses `toFixedNumber` instead of `toFixed`) |
| `embeddedSlice`, `embeddedSplit`, `embeddedDebugString`, `isEmbeddingMark` | Lower-level helpers for slicing/splitting strings that already contain LTR/RTL embedding marks without corrupting the marks |
| `localeToLocalizedName( locale )` | Looks up a locale code's own-language display name (e.g. `'es'` → `'Español'`), correctly directioned |

## When you'd reach for this directly

Most simulation code never calls `StringUtils.fillIn` by hand — [`PatternStringProperty`](/api/axon/pattern-string-property) wraps exactly this call (plus `toFixedLTR` for numeric decimal-place formatting) in a reactive, disposable `DerivedProperty`, and is the preferred way to build a *dynamic* pattern-filled string. Call `StringUtils` directly only for one-off, non-reactive string formatting — e.g. building a debug log line, or formatting a value at a point where wiring up a full derived Property would be overkill.


========================================================================
Page: Query parameter schema conventions (QSMSchemaObject)
URL: https://veillette.github.io/Almanach/api/query-string-machine/query-parameter-schema-conventions
Source: docs/api/query-string-machine/query-parameter-schema-conventions.md
Category: API | Tags: query-string-machine, QSMSchemaObject, schema, validValues, elementSchema, query-parameters | Status: verified
========================================================================

# Query parameter schema conventions

Each key passed to `QueryStringMachine.getAll` (see `QSMSchemaObject`, exported from `scenerystack/query-string-machine`) maps to one schema object describing how that parameter should be parsed and validated. Every schema variant shares a required `type` discriminant plus a fixed set of optional fields depending on that type; `QueryStringMachine` validates the schema itself (not just the parsed value) at parse time, so a malformed schema fails fast rather than silently misbehaving.

```ts
import type { QSMSchemaObject } from 'scenerystack/query-string-machine';
```

## The five schema types

| `type` | Result TS type | Fields |
| --- | --- | --- |
| `'flag'` | `boolean` | No `defaultValue` — presence in the URL (with no `=value`) means `true`, absence means `false` |
| `'boolean'` | `boolean` | `defaultValue?: boolean` |
| `'number'` | `number` | `defaultValue?: number` |
| `'string'` | `string \| null` | `defaultValue?: string \| null` |
| `'array'` | `T[]` | `elementSchema: Schema` (required), `separator?: string` (single character, default `','`), `defaultValue?: readonly T[] \| null` |
| `'custom'` | Whatever `parse` returns | `parse: ( str: string ) => T` (required) |

All types additionally accept `public` and `private` (below). `validValues`/`isValidValue` are supported only on `'number'`, `'string'`, `'array'`, and `'custom'` schemas — `'flag'` and `'boolean'` schemas do not accept either (their only two possible values, `true`/`false`, make an extra validity check redundant).

## Shared optional fields

| Field | Effect |
| --- | --- |
| `validValues` | Restricts the parsed value to a fixed set — mutually exclusive with `isValidValue` (schemas providing both throw at parse time) |
| `isValidValue` | A custom predicate the parsed value must satisfy — mutually exclusive with `validValues` |
| `public` | If `true`, an invalid value logs to `QueryStringMachine.warnings` and falls back to `defaultValue` instead of throwing. Requires `defaultValue` to be present (except for `'flag'`, which has none by definition) |
| `private` | The URL value is only honored for team members (gated on a `phetTeamMember` localStorage check); otherwise treated as absent |

## `'array'` schemas nest a full sub-schema

```ts
const screensSchema: QSMSchemaObject = {
  screens: {
    type: 'array',
    elementSchema: {
      type: 'number',
      isValidValue: ( n: number ) => Number.isInteger( n ) && n >= 1
    },
    separator: ',',
    defaultValue: null
  }
};
// ?screens=1,3,4  ->  screens: [ 1, 3, 4 ]
```

`elementSchema` is itself a full `Schema` and is recursively validated the same way the outer schema is — but it may not declare `public` itself (that comes from the array schema as a whole, not per element).

## `'custom'` schemas hand parsing to you entirely

```ts
const colorSchema: QSMSchemaObject = {
  backgroundColor: {
    type: 'custom',
    parse: ( str: string ) => new Color( str ),
    defaultValue: Color.WHITE
  }
};
```

`isValidValue` for a `'custom'` schema defaults to "always valid" — validation is the parse function's responsibility unless you also supply `isValidValue`/`validValues`.

## Validation rules enforced on the schema itself

`QueryStringMachine` asserts all of the following before it will parse a value, throwing immediately if violated:

- `type` is present and is one of the five known types.
- `validValues` and `isValidValue` are not both present on the same schema.
- `defaultValue`, if present, passes that type's own `isValidValue` check (and must be a member of `validValues` if both are given).
- `public: true` requires `defaultValue` to be present, except for `'flag'` schemas.
- No unsupported keys are present for the given `type` (e.g. a `'number'` schema with an `elementSchema` field throws).
- For `'array'` schemas: `separator`, if given, is exactly one character, and `elementSchema` does not itself declare `public`.

::: warning `validValues` and `isValidValue` are mutually exclusive, not layered
Supplying both on the same schema entry throws at parse time — `QueryStringMachine` doesn't combine them (e.g. "must be one of these, and also pass this extra check"). If you need both a fixed set and an extra predicate, encode the extra check as the *only* validation via `isValidValue`, checking membership yourself inside it.
:::


========================================================================
Page: QueryStringMachine.getAll
URL: https://veillette.github.io/Almanach/api/query-string-machine/query-string-machine-getall
Source: docs/api/query-string-machine/query-string-machine-getall.md
Category: API | Tags: query-string-machine, QueryStringMachine, getAll, query-parameters | Status: verified
========================================================================

# QueryStringMachine.getAll

`QueryStringMachine` (from `scenerystack/query-string-machine`) is a plain object — not a class — exposing `get`/`getAll` and their string-based variants for parsing `location.search` against a declared schema. `getAll` is the entry point almost every sim uses: pass a map of parameter name to schema, get back a fully-typed, defaulted, validated object in one call. See [the Query Parameters Pattern](/patterns/query-parameters-pattern) for *why* this convention exists and a worked schema; this page documents `QueryStringMachine`'s methods themselves.

```ts
import { QueryStringMachine } from 'scenerystack/query-string-machine';
```

## `getAll`

```ts
QueryStringMachine.getAll<SchemaMap extends QSMSchemaObject>( schemaMap: SchemaMap ): QSMParsedParameters<SchemaMap>
```

```ts
const parameters = QueryStringMachine.getAll( {
  speed: { type: 'number', defaultValue: 1 },
  showAnswers: { type: 'flag' }
} );

parameters.speed;       // number
parameters.showAnswers; // boolean
parameters.SCHEMA_MAP;  // the schemaMap you passed in, attached for introspection
```

Internally, `getAll` reads `self.location.search` and delegates to `getAllForString`, which loops the schema map calling `getForString` per key — so `getAll`'s behavior is entirely explained by `get`'s single-key behavior, run once per declared parameter.

## The full method surface

| Method | Signature | Use when |
| --- | --- | --- |
| `get( key, schema )` | `( key: string, schema: Schema ) => ParsedValue` | You only need one parameter's value |
| `getAll( schemaMap )` | `( schemaMap: QSMSchemaObject ) => QSMParsedParameters` | The common case: parse every declared parameter for the sim at startup |
| `getForString( key, schema, string )` | Same as `get`, plus an explicit query string | Testing, or parsing a query string that isn't `location.search` |
| `getAllForString( schemaMap, string )` | Same as `getAll`, plus an explicit query string | Same, for the batch form |
| `containsKey( key )` | `( key: string ) => boolean` | Check presence without parsing/validating a value |
| `containsKeyForString( key, string )` | Same, with an explicit string | Testing variant |

`string` arguments must be either the empty string or start with `?`; anything else throws.

## Other members on the same object

| Member | Purpose |
| --- | --- |
| `warnings` | A read-only array of `{ key, value, message }` accumulated whenever a `public: true` schema silently falls back to its default because the URL supplied an invalid value |
| `addWarning( key, value, message )` | Appends to `warnings` (de-duplicated); called internally, rarely by client code |
| `removeKeyValuePair( queryString, key )` / `removeKeyValuePairs( queryString, keys )` | Returns a new query string with the given key(s) stripped — useful for constructing a "relaunch without this flag" URL |
| `appendQueryString( url, queryParameters )` / `appendQueryStringArray( url, queryStringArray )` | Appends one or more `key=value` fragments to a URL, handling the `?`/`&` join correctly |
| `getQueryString( url )` | Returns the `?...` tail of a URL, or `'?'` if there is none |

::: tip Invalid values only fall back silently when the schema is `public: true`
If a URL supplies a value that fails validation (wrong type, not in `validValues`, fails `isValidValue`) and the schema does *not* set `public: true`, `QueryStringMachine` throws instead of warning-and-defaulting. Reserve `public: true` for parameters end users might plausibly mistype and where continuing with the default is safe; leave it off for internal/debug flags where a bad value should fail loudly.
:::


========================================================================
Page: AlignBox
URL: https://veillette.github.io/Almanach/api/scenery/align-box
Source: docs/api/scenery/align-box.md
Category: API | Tags: scenery, AlignBox, layout | Status: verified
========================================================================

# AlignBox

`AlignBox` (from `scenerystack/scenery`) wraps a single content [`Node`](/api/scenery/node) and positions it within a bounding box (`alignBounds`) according to horizontal/vertical alignment and margins — the scenery equivalent of centering or pinning one element inside a fixed-size slot. It's the standard way to reserve a consistent amount of space for content whose size can vary (e.g. a translated string) inside a [`FlowBox`](/api/scenery/flow-box) or [`GridBox`](/api/scenery/grid-box) cell, without the varying content shifting its neighbors.

```ts
import { AlignBox, Circle } from 'scenerystack/scenery';
import { Bounds2 } from 'scenerystack/dot';

const icon = new Circle( 12, { fill: 'seagreen' } );

const centeredSlot = new AlignBox( icon, {
  alignBounds: new Bounds2( 0, 0, 60, 60 ),
  xAlign: 'center',
  yAlign: 'center'
} );
```

If `alignBounds` isn't provided, `AlignBox` sizes itself to fit the content plus margins, with a left-top corner at `(0, 0)` — in that case it behaves mostly as a margin wrapper rather than a fixed-size slot. Passing a preferred width/height (e.g. from a parent layout container) also drives `alignBounds` automatically.

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `alignBounds` | `null` (fits content) | The `Bounds2` the content is aligned within; see [`Bounds2`](/api/dot/bounds2) |
| `alignBoundsProperty` | — | Drives `alignBounds` dynamically from a `TReadOnlyProperty<Bounds2>`; mutually exclusive with `alignBounds` |
| `align` | — | Shorthand setting both `xAlign` and `yAlign` (only `'center'` or `'stretch'` are valid for both axes at once) |
| `xAlign` | `'center'` | `'left'`, `'center'`, `'right'`, or `'stretch'` |
| `yAlign` | `'center'` | `'top'`, `'center'`, `'bottom'`, or `'stretch'` |
| `margin` | `0` | Shorthand for all four margins |
| `xMargin` / `yMargin` | `0` | Shorthand for left+right / top+bottom margins |
| `leftMargin` / `rightMargin` / `topMargin` / `bottomMargin` | `0` | Per-side margin |
| `group` | `null` | An `AlignGroup` that synchronizes this box's `alignBounds` with sibling boxes in the same group, so they all end up the same size |

## Methods

| Method | Effect |
| --- | --- |
| `getContent()` / `.content` | Returns the wrapped content `Node` |
| `setAlignBounds( bounds )` | Updates the bounds content is aligned within |
| `invalidateAlignment()` | Forces an immediate re-layout — useful when content changed in a way that doesn't automatically trigger it |
| `getContentBounds()` | Returns the content's current bounds within the alignment frame |
| `dispose()` | Releases the box's internal listeners on the content and any `alignBoundsProperty`/`group` |

::: tip `sizable` defaults to `false`
Unlike most layout-participating Nodes, `AlignBox` defaults to `sizable: false` — it's usually used to carve out a fixed amount of space, not to grow/shrink with its parent. Pass `sizable: true` (or set `xAlign`/`yAlign` to `'stretch'` with a resizable content Node) if you want it to participate in a parent's `grow`/`stretch` layout.
:::

::: warning Layout can lag by one frame
`AlignBox` recomputes its layout when the content's bounds change, but per the source's own documentation, that update "may not happen immediately, and may be delayed until bounds of a alignBox's child occurs." Reading `alignBox.getBounds()` right after mutating content does not force a refresh and can return stale bounds — call `invalidateAlignment()` if you need the new layout synchronously, or rely on it settling before the next [`Display.updateDisplay()`](/api/scenery/display).
:::


========================================================================
Page: AlignGroup
URL: https://veillette.github.io/Almanach/api/scenery/align-group
Source: docs/api/scenery/align-group.md
Category: API | Tags: scenery, AlignGroup, AlignBox, layout | Status: verified
========================================================================

# AlignGroup

`AlignGroup` (from `scenerystack/scenery`) coordinates a set of [`AlignBox`](/api/scenery/align-box)es that don't otherwise share a parent, so they all end up sized to the same width/height — the largest of the group's minimum content sizes. Where a single `AlignBox` just centers/aligns one child in a bounding box you specify, `AlignGroup` computes that bounding box *for* you from whichever member currently needs the most space, and every box in the group is resized to match, guaranteeing every box ends up sized identically without measuring anything by hand.

```ts
import { AlignGroup, AlignBox, Text } from 'scenerystack/scenery';

const group = new AlignGroup();

const shortLabel = group.createBox( new Text( 'Short' ), { xAlign: 'left' } );
const longLabel = group.createBox( new Text( 'A much longer label' ), { xAlign: 'left' } );
// Both boxes now report the same (largest) size to whatever lays them out — e.g. side-by-side panels.
```

`createBox()` is the usual way to add a member — it constructs an `AlignBox` with `group: this` already set. You can also build an `AlignBox` yourself and assign `group` on it directly.

## Constructor options

| Option | Default | Effect |
| --- | --- | --- |
| `matchHorizontal` | `true` | Whether every box in the group is forced to the same width (the group's max content width) |
| `matchVertical` | `true` | Whether every box in the group is forced to the same height (the group's max content height) |

Also accepts `DisposableOptions` (e.g. `disposer`), inherited from `Disposable`.

If only one of `matchHorizontal`/`matchVertical` is `false`, boxes use their own preferred size on that axis instead of the group's max — useful when you want boxes to share a common width but keep independent heights, for example.

## Methods

| Method | Effect |
| --- | --- |
| `createBox( content, options? )` | Creates and registers a new `AlignBox` in this group, wrapping `content` |
| `updateLayout()` | Forces an immediate recomputation of the shared size and reapplies it to every member box — normally you don't need this, since bounds changes on any member trigger it automatically |
| `setMatchHorizontal( value )` / `.matchHorizontal` | Toggles horizontal size-matching after construction |
| `setMatchVertical( value )` / `.matchVertical` | Toggles vertical size-matching after construction |
| `getMaxWidth()` / `.maxWidth` | The group's current shared width |
| `getMaxHeight()` / `.maxHeight` | The group's current shared height |
| `getMaxWidthProperty()` / `.maxWidthProperty` | A `TProperty<number>` tracking the shared width, for cases that need to observe it |
| `getMaxHeightProperty()` / `.maxHeightProperty` | A `TProperty<number>` tracking the shared height |
| `dispose()` | Disposes every `AlignBox` the group created — disposing the group is enough to clean up its members too |

::: tip Populate largest-content boxes first
Per source: since many `sun` UI components don't support resizing their contents dynamically after construction, populate an `AlignGroup` in order from largest expected content to smallest, so the group's shared size is established correctly from the start rather than needing every box to grow into a later-discovered maximum.
:::


========================================================================
Page: AnimatedPanZoomListener
URL: https://veillette.github.io/Almanach/api/scenery/animated-pan-zoom-listener
Source: docs/api/scenery/animated-pan-zoom-listener.md
Category: API | Tags: scenery, AnimatedPanZoomListener, input, pan, zoom, accessibility | Status: verified
========================================================================

# AnimatedPanZoomListener

`AnimatedPanZoomListener` (from `scenerystack/scenery`) transforms a target [`Node`](/api/scenery/node) — usually the whole rendered scene — in response to trackpad pinch gestures, mouse wheel scroll/zoom, middle-mouse-drag panning, and keyboard pan/zoom commands, animating toward the requested pan position and scale rather than jumping instantly. It extends `PanZoomListener` (itself a `MultiListener`), adding the animation and the input-gesture handling on top. Most applications don't construct it directly — they use the pre-built `animatedPanZoomSingleton` (also from `scenerystack/scenery`), which owns one shared instance for the whole document.

```ts
import { Node, Display, animatedPanZoomSingleton } from 'scenerystack/scenery';
import { Bounds2 } from 'scenerystack/dot';

const rootNode = new Node();
const display = new Display( rootNode );

animatedPanZoomSingleton.initialize( rootNode, {
  panBounds: new Bounds2( 0, 0, display.width, display.height )
} );

display.addInputListener( animatedPanZoomSingleton.listener );
```

Because the default `stepEmitter` option is the shared `axon` `stepTimer` (which PhET-iO sims already drive every frame), the animation advances automatically — you only need to call `.step( dt )` yourself if you're not using the standard sim time loop.

## Key options (`AnimatedPanZoomListenerOptions`)

Inherited from `PanZoomListener` / `MultiListener`:

| Option | Default | Effect |
| --- | --- | --- |
| `panBounds` | `Bounds2.NOTHING` | The bounds (global frame) that must stay fully filled with content at all times — effectively the viewport |
| `targetBounds` | `null` (uses `targetNode.globalBounds`) | Overrides the bounds considered to belong to the target, e.g. when the Node has invisible content extending off-screen |
| `targetScale` | `1` | A scale factor describing the target Node's own content scale, applied to translation during panning (for content that's uniformly scaled independent of this listener) |
| `minScale` / `maxScale` | `1` / `4` | Clamps how far the listener can zoom the target in/out |
| `allowScale` / `allowRotation` | `true` / `false` | Whether pinch/gesture input is allowed to scale / rotate the target (`AnimatedPanZoomListener` disables rotation by default via `PanZoomListener`) |

Specific to `AnimatedPanZoomListener`:

| Option | Default | Effect |
| --- | --- | --- |
| `stepEmitter` | `stepTimer` | The `TReadOnlyEmitter<[number]>` that drives animation frames; pass `null` to step it manually instead |

## Public state and methods

| Member | Meaning |
| --- | --- |
| `animatingProperty` | `true` while the listener is actively animating toward its destination pan/scale |
| `step( dt )` | Advances the pan/zoom animation by `dt` seconds; called automatically unless `stepEmitter: null` |
| `panToNode( node, panToCenter, panDirection? )` | Pans so `node`'s bounds become visible within `panBounds` |
| `panToTrail( trail )` (internal use pattern) | Keeps a given [`Trail`](/api/scenery/trail)'s bounds in view, panning if they fall outside `panBounds` |
| `setPanBounds( bounds )` | Updates the viewport bounds that must stay filled, e.g. on window resize |
| `setTargetScale( scale )` | Updates `targetScale` at runtime |
| `cancel()` | Cancels any in-progress gesture/animation |
| `dispose()` | Releases the listener's internal Properties and DOM gesture listeners |

::: warning It listens for keyboard zoom globally, so give it the whole Display
`AnimatedPanZoomListener` attaches trackpad-gesture and keyboard-zoom handling at the `Display` level (via `display.addInputListener(...)`), and reacts to PDOM focus changes to keep the focused element in view. Initializing more than one, or attaching it to something other than the Display's root, produces competing pan/zoom behavior — use the shared `animatedPanZoomSingleton` unless you have a specific reason to manage your own instance.
:::


========================================================================
Page: Circle
URL: https://veillette.github.io/Almanach/api/scenery/circle
Source: docs/api/scenery/circle.md
Category: API | Tags: scenery, Circle, Path | Status: verified
========================================================================

# Circle

`Circle` (from `scenerystack/scenery`) is a [`Path`](/api/scenery/path) subclass that builds its own circular `Shape` from a single `radius` parameter, so you don't need to construct a kite `Shape` by hand for the common case of a plain circle.

```ts
import { Circle } from 'scenerystack/scenery';

// new Circle( radius, options ) ...
const ball = new Circle( 20, {
  fill: 'crimson',
  stroke: 'black',
  lineWidth: 2
} );

// ...or new Circle( { radius, ...options } )
const marker = new Circle( { radius: 5, fill: 'black' } );

ball.radius = 25; // radius is also a settable property
```

## Options

| Option | Effect |
| --- | --- |
| `radius` | The non-negative radius of the circle, in local coordinates |

`Circle` accepts every [`Path` option](/api/scenery/path) (`fill`, `stroke`, `lineWidth`, `boundsMethod`, …) except `shape`/`shapeProperty`, which `Circle` computes itself, plus the full set of [`Node` options](/api/scenery/node).

::: tip Constructor overloads
`Circle` supports both `new Circle( radius, options )` and `new Circle( { radius, ...options } )` — pick whichever reads more clearly at the call site; they're equivalent.
:::


========================================================================
Page: Color
URL: https://veillette.github.io/Almanach/api/scenery/color
Source: docs/api/scenery/color.md
Category: API | Tags: scenery, Color, paint, fill, stroke | Status: verified
========================================================================

# Color

`Color` (from `scenerystack/scenery`) represents an RGBA color in the sRGB space, and is one of the value types scenery's `fill`/`stroke` options accept directly (alongside a plain CSS string, `null`, or a `Property<Color | string | null>`). Unlike `Font`, `Color` is **mutable** — its `r`/`g`/`b`/`a` channels can be changed after construction, which lets you reuse one `Color` instance and get every Node using it to repaint automatically.

```ts
import { Color, Circle } from 'scenerystack/scenery';

const bodyColor = new Color( 255, 100, 0 );       // r, g, b (0-255), alpha defaults to 1
const fromHex = new Color( 0xff6400 );             // hex number
const fromKeyword = new Color( 'orange' );         // any CSS color keyword or string
const transparent = new Color( null );             // fully transparent

const body = new Circle( 20, { fill: bodyColor } );

bodyColor.red = 200;      // mutating the instance repaints every Node using it as fill/stroke
```

## Construction forms

The constructor is overloaded — pass one of:

| Form | Example |
| --- | --- |
| `r, g, b, a?` | `new Color( 255, 100, 0 )`, `new Color( 255, 100, 0, 0.5 )` |
| A single hex `number`, `a?` | `new Color( 0xff6400 )` |
| A CSS color `string` | `new Color( 'rgb(255,100,0)' )`, `new Color( 'orange' )`, `new Color( '#ff6400' )` |
| Another `Color` | `new Color( existingColor )` (copies channel values) |
| `null` | `new Color( null )` — fully transparent black |

## Mutating and deriving

| Method | Effect |
| --- | --- |
| `setRGBA( r, g, b, a )` | Sets all four channels at once, returns `this` for chaining |
| `red` / `green` / `blue` / `alpha` (get/set) | Individual channel accessors, e.g. `color.alpha = 0.5` |
| `setAlpha( a )` | Sets just the alpha channel, returns `this` |
| `withAlpha( a )` | Returns a **new** `Color` with a different alpha, leaving the original untouched |
| `blend( otherColor, ratio )` | Returns a new `Color` linearly interpolated between this color and `otherColor` |
| `brighterColor( factor? )` / `darkerColor( factor? )` | Returns a new, lighter/darker `Color`, useful for hover/pressed button states |
| `toCSS()` | Returns the CSS `rgba(...)` string form, e.g. for use outside scenery (DOM styling) |
| `equals( otherColor )` | Channel-wise equality check |

## Static helpers

| Static member | Effect |
| --- | --- |
| `Color.toColor( colorSpec )` | Normalizes a `TColor` (string, `Color`, `null`, or `Property` of one) into a `Color` instance |
| `Color.interpolateRGBA( c1, c2, distance )` | Interpolates between two colors at a given `distance` (0-1) |
| `Color.isDarkColor( color, threshold? )` / `isLightColor( color, threshold? )` | Luminance-based checks, useful for choosing readable text color on top of a background |
| `Color.getLuminance( color )` | Returns the color's perceptual luminance |
| `Color.grayColor( rgb, a? )` | Shorthand for an equal-channel gray |
| `Color.BLACK`, `Color.WHITE`, `Color.RED`, `Color.BLUE`, … | Named static `Color` constants for CSS basic color keywords (also available lowercase, e.g. `Color.black`) |

::: tip A shared, mutable `Color` beats an inline string when a color needs to change at runtime
Passing `'orange'` directly as `fill` works, but scenery can't push runtime updates to it — you'd have to reassign `node.fill` yourself. A shared `Color` instance (or better, a `Property<Color>` via `ProfileColorProperty`, see [Color Profiles](/styling/color-profiles)) lets every Node using it repaint automatically when the color changes, which is how PhET's light/dark ("projector") theme switching works.
:::


========================================================================
Page: ColorProperty, ProfileColorProperty, and PaintColorProperty
URL: https://veillette.github.io/Almanach/api/scenery/color-property-and-profile-color-property
Source: docs/api/scenery/color-property-and-profile-color-property.md
Category: API | Tags: scenery, ColorProperty, ProfileColorProperty, PaintColorProperty, Color, Property, theming | Status: complete
========================================================================

# ColorProperty, ProfileColorProperty, and PaintColorProperty

All three of these classes (from `scenerystack/scenery`) are `Property<Color>` subclasses — they let a `fill`/`stroke` respond to a `Property` link like any other dynamic value, instead of being a fixed `Color`/string. They differ in *why* the color changes:

- **`ColorProperty`** is the plain case: a `Property<Color>` you set directly, with a `valueType`/`phetioValueType` already configured for `Color` so you don't have to specify that yourself every time.
- **`ProfileColorProperty`** changes its value automatically based on a global `colorProfileProperty` (e.g. switching between a `'default'` and `'projector'` color scheme) — you give it a map from profile name to color once, and it picks the right one and re-picks whenever the profile changes.
- **`PaintColorProperty`** *derives* its value from another paint (a `Color`, a CSS string, a gradient, or even another `Property<Color>`) and stays in sync as that source paint changes — optionally brightening or darkening it via `luminanceFactor`.

```ts
import { ColorProperty, ProfileColorProperty, PaintColorProperty, Color } from 'scenerystack/scenery';
import { Namespace } from 'scenerystack/phet-core';

// Plain, directly-set color Property
const highlightColorProperty = new ColorProperty( new Color( 'yellow' ) );
highlightColorProperty.value = new Color( 'orange' ); // change it later

// A namespace is required so ProfileColorProperty names stay globally unique
const myNamespace = new Namespace( 'myModule' );

// Switches automatically with the global color profile
const backgroundColorProperty = new ProfileColorProperty( myNamespace, 'background', {
  default: new Color( 'white' ),
  projector: new Color( '#f0f0f0' )
} );

// Always a slightly darker version of backgroundColorProperty, kept in sync automatically
const shadowColorProperty = new PaintColorProperty( backgroundColorProperty, {
  luminanceFactor: -0.3
} );
```

## `ColorProperty`

```ts
new ColorProperty( color: Color, providedOptions?: PropertyOptions<Color> )
```

Just a `Property<Color>` with `valueType: Color` and `phetioValueType: Color.ColorIO` pre-set — you cannot pass either of those options yourself (it asserts if you try). Use this whenever a color needs to be observable/settable but doesn't need profile-switching or paint-derivation behavior.

## `ProfileColorProperty`

```ts
new ProfileColorProperty(
  namespace: Namespace,
  colorName: string,
  colorProfileMap: Record<string, Color | string>,
  providedOptions?: PropertyOptions<Color>
)
```

`colorProfileMap` must include a `default` entry (asserted at construction) — other keys are additional profiles (PhET's convention is `projector` for a white-background, high-contrast alternative). All map values are eagerly coerced to immutable `Color` instances. Internally, a listener on the shared `colorProfileProperty` re-selects `this.value` from the map (falling back to `default` if the current profile has no entry) every time the profile changes — you never call anything to trigger the switch yourself.

`namespace` + `colorName` together form a unique identifier (`${namespace.name}.${colorName}`) used to report color values to PhET's HTML color-editor tooling; constructing two `ProfileColorProperty`s with the same combination asserts.

## `PaintColorProperty`

```ts
new PaintColorProperty( paint: TPaint, providedOptions?: PaintColorPropertyOptions )
```

`paint` accepts anything scenery treats as a paint — a `Color`, a CSS color string, a gradient/pattern, or a `Property`/`TinyProperty` wrapping one of those — and `PaintColorProperty` resolves it to a concrete `Color` value, staying subscribed so `this.value` updates whenever the source paint (or a `Property` wrapping it) changes.

| Option | Default | Effect |
| --- | --- | --- |
| `luminanceFactor` | `0` | `-1` (black) to `1` (white); adjusts the resolved color's brightness via `Color.colorUtilsBrightness()`. `0` applies no change |

| Member | Effect |
| --- | --- |
| `paint` (getter/setter) | Swap to a different source paint at runtime; `this.value` updates immediately |
| `luminanceFactor` (getter/setter) | Change the brightening/darkening amount at runtime |

::: tip Use `PaintColorProperty` to derive "lighter"/"darker" variants instead of hand-picking a second color
A common pattern is a button's `baseColor` plus a slightly darker `PaintColorProperty` (via `luminanceFactor`) for its pressed/stroke state — if the base color is later changed (including by a `ProfileColorProperty` switching profiles), the derived color updates automatically instead of drifting out of sync.
:::

::: warning `ProfileColorProperty` is a JS-side profile switch, not a full re-theming system
Only the colors you've explicitly wrapped in `ProfileColorProperty` respond to `colorProfileProperty` changes — it doesn't retroactively make every `fill`/`stroke` in your sim swappable. Sim-wide color profile support means consistently using `ProfileColorProperty` (often centralized in a single colors file) for every themeable color.
:::


========================================================================
Page: Display
URL: https://veillette.github.io/Almanach/api/scenery/display
Source: docs/api/scenery/display.md
Category: API | Tags: scenery, Display, rendering, input | Status: verified
========================================================================

# Display

`Display` (from `scenerystack/scenery`) is the bridge between a [`Node`](/api/scenery/node) scene graph and the actual DOM: it owns a root DOM element, tracks a root `Node`, and repaints that DOM element whenever you call `updateDisplay()`. Every scenery application needs exactly one (or occasionally more) `Display` — nothing is drawn to the page until one exists and is driven.

```ts
import { Display, Node, Circle } from 'scenerystack/scenery';

const rootNode = new Node( {
  children: [ new Circle( 30, { fill: 'orange', x: 100, y: 100 } ) ]
} );

const display = new Display( rootNode, {
  width: 400,
  height: 300,
  backgroundColor: 'white'
} );

document.body.appendChild( display.domElement );

display.initializeEvents();          // wires up mouse/touch/keyboard input
display.updateOnRequestAnimationFrame( dt => {
  // per-frame update logic (dt is elapsed seconds) goes here
} );
```

The typical lifecycle is: build a root `Node`, construct a `Display` around it, attach `display.domElement` to the page, call `initializeEvents()` if the scene needs input, then drive repaints with `updateOnRequestAnimationFrame()` (or call `updateDisplay()` yourself in a custom loop).

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `width` / `height` | `640` / `480` | Initial size of the Display's DOM element |
| `backgroundColor` | `null` | A CSS color string or `Color` applied to the root DOM element |
| `allowCSSHacks` | `true` | Applies CSS (disables text selection, touch callouts, drag) that makes the element behave like an interactive app surface rather than a document |
| `allowSceneOverflow` | `false` | When `false`, content outside the Display's bounds is clipped |
| `allowWebGL` | `true` | Whether WebGL-rendered drawables are allowed at all in this Display |
| `accessibility` | `true` | Enables PDOM (accessibility tree) creation and support |
| `interactive` | `true` | Whether input events reach listeners; setting `false` also interrupts in-progress input |
| `assumeFullWindow` | `false` | If `true`, skips a `getBoundingClientRect()` call per event by assuming the Display fills the browser viewport |
| `container` | — | An existing `HTMLElement` to repurpose as the Display's root element, instead of creating a new one |

## Frequently used methods

| Method | Effect |
| --- | --- |
| `updateDisplay()` | Synchronously syncs the scene graph and repaints the DOM element — call this once per frame |
| `updateOnRequestAnimationFrame( stepCallback? )` | Drives `updateDisplay()` from `requestAnimationFrame`, optionally calling `stepCallback( dt )` first each frame |
| `initializeEvents( options? )` | Attaches browser input listeners so `Node` input listeners (e.g. [`FireListener`](/api/scenery/fire-listener)) start receiving events |
| `detachEvents()` | Reverses `initializeEvents()` |
| `addInputListener( listener )` / `removeInputListener( listener )` | Adds/removes a listener that hears every input event on the whole Display, not scoped to one Node |
| `setWidthHeight( width, height )` | Resizes the DOM element on the next `updateDisplay()` |
| `getRootNode()` / `.rootNode` | Returns the root `Node` this Display renders |
| `dispose()` | Tears down the Display, detaching events and releasing DOM/listener resources |

## Reading `domElement`

`display.domElement` (or `display.getDOMElement()`) is the plain `HTMLElement` you attach to the page yourself — `Display` does not insert itself into the DOM automatically:

```ts
document.body.appendChild( display.domElement );
```

::: tip Input requires `initializeEvents()`
Constructing a `Display` does not wire up mouse/touch/keyboard listeners by itself — attach a root `Node`'s [`inputListeners`](/api/scenery/node) (like a [`FireListener` or `PressListener`](/api/scenery/fire-listener)) and then call `display.initializeEvents()` once, or those listeners will never fire. Call `display.detachEvents()` if you need to reverse this later (e.g. tearing down the Display).
:::

::: warning Don't call `updateDisplay()` more than once per frame
`updateOnRequestAnimationFrame()` already schedules a repaint every animation frame; calling `updateDisplay()` again yourself outside that loop (or from multiple independent loops) does redundant sync/repaint work. Prefer driving all per-frame work through the single `stepCallback` passed to `updateOnRequestAnimationFrame()`.
:::


========================================================================
Page: DragListener
URL: https://veillette.github.io/Almanach/api/scenery/drag-listener
Source: docs/api/scenery/drag-listener.md
Category: API | Tags: scenery, DragListener, PressListener, input, drag | Status: complete
========================================================================

# DragListener

`DragListener` (from `scenerystack/scenery`) is a `PressListener` subclass specialized for dragging: it tracks a pointer from press through release, converts the pointer's position into local/parent/model coordinate frames, and (optionally) writes the result straight into a `positionProperty`. As [`PressListener` and `FireListener`](/api/scenery/fire-listener) documents, `PressListener` is the shared base for both — `FireListener` adds a `fire()` callback for clicks, while `DragListener` adds coordinate tracking and repositioning for drags. If you also need keyboard support on the same draggable object, reach for [`RichDragListener`](/api/scenery/rich-drag-listener) instead, which composes a `DragListener` with a [`KeyboardDragListener`](/api/scenery/keyboard-drag-listener) rather than requiring you to wire up both yourself.

```ts
import { Node, DragListener } from 'scenerystack/scenery';
import { Vector2 } from 'scenerystack/dot';
import { Property } from 'scenerystack/axon';

const positionProperty = new Property( new Vector2( 0, 0 ) );

const body = new Node( { cursor: 'pointer' } );
body.translation = positionProperty.value;

body.addInputListener( new DragListener( {
  positionProperty: positionProperty,
  transform: modelViewTransform, // maps model <-> view (parent) coordinates
  dragBoundsProperty: model.dragBoundsProperty,
  start: () => body.moveToFront(),
  end: () => { /* drag finished */ }
} ) );

positionProperty.link( position => {
  body.translation = modelViewTransform.modelToViewPosition( position );
} );
```

This is the typical PhET pattern: give `DragListener` a `positionProperty` and a `transform`, and it keeps the model position in sync with the pointer without you writing any coordinate math. If you'd rather read the drag out manually, omit `positionProperty` and use the `drag` callback together with `listener.modelDelta`/`listener.modelPoint`.

## Options

`DragListenerOptions` combines everything [`PressListener`](/api/scenery/fire-listener) accepts (`targetNode`, `attach`, `mouseButton`, `pressCursor`, `canStartPress`, `collapseDragEvents`, …) with:

| Option | Default | Effect |
| --- | --- | --- |
| `positionProperty` | `null` | A `Property`-like object (needs only a settable `.value`) kept in sync with the drag, in the model coordinate frame |
| `transform` | `null` | A `Transform3` or `TReadOnlyProperty<Transform3>` mapping the parent (view) frame to the model frame |
| `dragBoundsProperty` | `null` | Constrains the model position to a `Bounds2` (via `closestPointTo`); combine with `mapPosition` for custom constraints |
| `mapPosition` | `null` | `(point: Vector2) => Vector2` — custom mapping from desired to allowed model position, applied before `dragBoundsProperty` |
| `translateNode` | `false` | If `true`, directly sets the drag target's `translation` during the drag, instead of (or in addition to) `positionProperty` |
| `start` / `drag` / `end` | no-ops | Preferred over overriding `press`/`release` — these fire after the listener has already updated its internal state for the event |
| `allowTouchSnag` | `true` | Whether an unattached touch that moves across the target will "snag" and start a press — helps with small draggable targets |
| `applyOffset` | `true` | Whether the initial offset between the pointer and the target's local origin is preserved throughout the drag |
| `useParentOffset` | `false` | Compute the offset in the parent coordinate frame from `positionProperty` instead of the target Node's actual transform — for cases where no single Node's transform represents the dragged thing |
| `trackAncestors` | `false` | If `true`, an internal [`TransformTracker`](/api/scenery/transform-tracker) watches ancestor transforms and repositions automatically when they change |
| `offsetPosition` | `null` | `(point, listener) => Vector2` added to the parent point before computation — useful to offset touch drags away from being directly under the finger |
| `canClick` | `false` | `DragListener` normally can't be "clicked" (a single tap would pick up and immediately drop); set `true` to allow accessible single-activation in addition to dragging |

## Reading the drag state

| Member | Meaning |
| --- | --- |
| `isPressedProperty` / `isUserControlledProperty` | Whether a drag is in progress (`isUserControlledProperty` is just a more readable alias for the same Property) |
| `globalPoint` / `parentPoint` / `localPoint` / `modelPoint` | Defensive-copy getters for the current drag point in each coordinate frame |
| `modelDelta` | The change in `modelPoint` since the previous reposition |
| `dragBounds` | The current value of `dragBoundsProperty` |
| `reposition( globalPoint )` | Recomputes all the coordinate-frame points and applies `positionProperty`/`translateNode`; called automatically on pointer move |
| `interrupt()` | Cancels an in-progress drag without it looking like a normal release |
| `dispose()` | Releases the listener's `Property`/`Action` resources |

::: tip DragListener is not itself keyboard-accessible
`DragListener` only responds to pointer input (mouse/touch/pen). If a draggable object also needs to work with a keyboard, don't hand-wire a separate [`KeyboardDragListener`](/api/scenery/keyboard-drag-listener) alongside it — use [`RichDragListener`](/api/scenery/rich-drag-listener), which composes both and keeps their shared options (`positionProperty`, `transform`, `dragBoundsProperty`, `start`/`drag`/`end`) in sync automatically.
:::

::: warning `tandem` defaults to required, and drag actions are read-only for PhET-iO
Like `PressListener`/`FireListener`, `DragListener` defaults `tandem` to `Tandem.REQUIRED`. Its internal `dragAction` is also `phetioReadOnly: true` by default — PhET-iO can observe drag events in the data stream, but can't trigger them, since simulating a drag requires more state than a single data-stream call can carry.
:::


========================================================================
Page: Filter and the Node.filters visual effects
URL: https://veillette.github.io/Almanach/api/scenery/visual-filters
Source: docs/api/scenery/visual-filters.md
Category: API | Tags: scenery, Filter, Brightness, Contrast, Grayscale, Invert, Sepia, HueRotate, Saturate, ColorMatrixFilter, Node | Status: complete
========================================================================

# Filter and the Node.filters visual effects

`Filter` (from `scenerystack/scenery`) is the abstract base class behind [`Node`](/api/scenery/node)'s `filters` option — an array of post-processing effects applied to that Node's rendered subtree, the scenery equivalent of the CSS `filter` property. You rarely construct a `Filter` directly; instead you construct one of its named subtypes (`Brightness`, `Contrast`, `Grayscale`, `Invert`, `Sepia`, `HueRotate`, `Saturate`, or a custom `ColorMatrixFilter`) and assign an array of them to `filters`.

```ts
import { Node, Circle, Grayscale, Brightness, Contrast } from 'scenerystack/scenery';

const icon = new Node( {
  children: [ new Circle( 30, { fill: 'crimson' } ) ]
} );

// Applied in array order: grayscale first, then brighten the result.
icon.filters = [ new Grayscale( 1 ), new Brightness( 1.2 ) ];

// A disabled-looking control, built from two filters composed together:
const disabledLookFilters = [ new Contrast( 0.6 ), new Brightness( 1.1 ) ];
```

## The shared pattern

Every named filter is a small class that computes a fixed CSS filter string (e.g. `grayscale(1)`) and, where the effect can be expressed as a 4x5 color matrix (all of them except `Invert`), extends `ColorMatrixFilter` so the same math also works under SVG and Canvas rendering — not just DOM/CSS. `Node.filters` accepts an array so multiple effects can stack; they apply in array order.

All of these filters live under `scenerystack/scenery`. Most take a single `amount` constructor argument that behaves like the equivalent CSS filter function:

| Filter | Constructor | `amount` meaning |
| --- | --- | --- |
| `Brightness` | `new Brightness( amount )` | `0` = black, `1` = normal, greater = brighter. Non-negative, required |
| `Contrast` | `new Contrast( amount )` | `0` = flat gray, `1` = normal, greater = higher contrast. Non-negative, required |
| `Grayscale` | `new Grayscale( amount = 1 )` | `0` = unchanged, `1` = fully gray-scale. Must be in `[0, 1]` |
| `Invert` | `new Invert( amount = 1 )` | `0` = unchanged, `1` = fully inverted. Must be in `[0, 1]` |
| `Sepia` | `new Sepia( amount = 1 )` | `0` = unchanged, `1` = fully sepia-toned. Must be in `[0, 1]` |
| `Saturate` | `new Saturate( amount )` | `0` = fully desaturated (grayscale), `1` = normal, greater = over-saturated. Non-negative, required |
| `HueRotate` | `new HueRotate( amount )` | Hue rotation **in radians** (converted to degrees internally for the CSS string). Non-negative, required |

`Brightness` and `Grayscale` each expose a convenience static: `Brightness.BLACKEN` (`new Brightness( 0 )`) and `Grayscale.FULL` (`new Grayscale( 1 )`); `Contrast.GRAY` (`new Contrast( 0 )`) similarly turns content flat gray.

## `ColorMatrixFilter`

```ts
new ColorMatrixFilter(
  m00, m01, m02, m03, m04,
  m10, m11, m12, m13, m14,
  m20, m21, m22, m23, m24,
  m30, m31, m32, m33, m34
)
```

Every named filter above (except `Invert`) is implemented purely by calling `super(...)` with 20 fixed matrix values — `ColorMatrixFilter` multiplies this 4x5 matrix against each pixel's `[r, g, b, a, 1]` column to produce a new `[r, g, b, a]`. Writing a custom `ColorMatrixFilter` is possible but PhET's own guidance is to prefer the named subtypes wherever they cover the need: a custom matrix filter is SVG/Canvas-compatible but is **not** compatible with WebGL or DOM content, and forces everything under it into a single SVG or Canvas block, which can reduce rendering performance.

## `Filter` (the abstract base)

You won't subclass `Filter` directly in ordinary sim code, but its interface is why every filter can be mixed freely: each subclass implements `getCSSFilterString()` (for DOM/Canvas), `applySVGFilter( svgFilter, inName, resultName? )` (for SVG), and `applyCanvasFilter( wrapper )` (the ImageData fallback path), plus compatibility checks (`isDOMCompatible()`, `isSVGCompatible()`, `isCanvasCompatible()`, `isWebGLCompatible()`) that scenery uses to decide which rendering strategy can honor a given `filters` array.

::: tip Filters apply to the whole subtree, and can be animated like any other option
Because `filters` is a plain `Node` option, it can be set/replaced at any time — e.g. swap in `[ new Grayscale( fraction ) ]` on every frame of a fade-to-grayscale transition by recomputing the array as `fraction` changes. There's no `Filter` `Property` API for interpolating an amount smoothly; you construct a fresh filter instance with the new amount.
:::

::: warning Mixed compatibility can force a slower rendering path
Not every filter works under every renderer. If a Node's subtree can't be placed in a single SVG block or Canvas (e.g. because of a `layerSplit` or DOM content), some filters may fall back to a more expensive strategy, or in the case of custom `ColorMatrixFilter`s under WebGL/DOM content, may not be supported at all. Prefer the DOM-compatible named filters (all of the ones listed above are DOM-compatible) when performance matters and the content underneath isn't guaranteed to be single-block SVG or Canvas.
:::


========================================================================
Page: FlowBox
URL: https://veillette.github.io/Almanach/api/scenery/flow-box
Source: docs/api/scenery/flow-box.md
Category: API | Tags: scenery, FlowBox, HBox, VBox, layout | Status: verified
========================================================================

# FlowBox

`FlowBox` (from `scenerystack/scenery`) is a [`Node`](/api/scenery/node) that automatically positions its children along one axis (a row or a column), with configurable spacing, alignment, and wrapping — the scenery equivalent of a CSS flexbox with a single main axis. It re-runs layout whenever children are added/removed/reordered or resized, so you don't have to compute positions by hand. In practice, most code uses the fixed-orientation convenience subclasses `HBox` (`orientation: 'horizontal'`) and `VBox` (`orientation: 'vertical'`) instead of `FlowBox` directly.

```ts
import { HBox, Circle, Rectangle } from 'scenerystack/scenery';

const row = new HBox( {
  spacing: 10,
  align: 'center',
  children: [
    new Circle( 15, { fill: 'crimson' } ),
    new Rectangle( 0, 0, 40, 30, { fill: 'teal' } ),
    new Circle( 10, { fill: 'goldenrod' } )
  ]
} );
```

Adding, removing, or reordering `row.children` afterward re-lays-out the remaining children automatically — no manual repositioning needed.

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `orientation` | `'horizontal'` | `'horizontal'` (row) or `'vertical'` (column) — fixed by `HBox`/`VBox` |
| `spacing` | `0` | Gap between adjacent children along the main axis |
| `lineSpacing` | `0` | Gap between wrapped lines, when `wrap: true` |
| `align` | `'center'` | Cross-axis alignment for children — for a horizontal `FlowBox`: `'top'`, `'bottom'`, `'center'`, or `'origin'`; for a vertical one: `'left'`, `'right'`, `'center'`, or `'origin'` |
| `stretch` | `false` | Whether children grow to fill the cross axis (requires the child to be resizable on that axis) |
| `grow` | `0` | How much a child should grow to fill leftover main-axis space, relative to other children's `grow` |
| `justify` | `'spaceBetween'` | How extra main-axis space is distributed, e.g. `'left'`/`'right'`/`'center'` (horizontal) or `'top'`/`'bottom'`/`'center'` (vertical), plus `'spaceBetween'`, `'spaceAround'`, `'spaceEvenly'` |
| `wrap` | `false` | Whether children flow onto additional lines instead of overflowing |
| `resize` | `true` | Whether the FlowBox keeps re-running layout after construction; set `false` and call `updateLayout()` manually for performance-sensitive cases |
| `forward` | `true` | If `false`, children are laid out in reverse order (useful for RTL locales via `forwardProperty`) |
| `margin` / `xMargin` / `yMargin` / `leftMargin` / `rightMargin` / `topMargin` / `bottomMargin` | `0` | Per-cell margins, settable box-wide or per-child via `layoutOptions` |
| `minContentWidth` / `minContentHeight` / `maxContentWidth` / `maxContentHeight` | — | Clamp the FlowBox's own content size |

Per-child overrides (`align`, `stretch`, `grow`, `margin`, …) can also be set on an individual child via that child's `layoutOptions`, taking precedence over the FlowBox-wide value:

```ts
someChild.layoutOptions = { grow: 1, stretch: true };
```

## Methods

| Method | Effect |
| --- | --- |
| `getCell( node )` | Returns the internal `FlowCell` tracking a given child, for advanced layout inspection |
| `updateLayout()` (via `constraint`) | Forces an immediate re-layout, useful when `resize: false` |
| `setForward( forward )` / `.forward` | Toggles child order, or bind `forwardProperty` to a locale/orientation `Property` |
| `dispose()` | Releases layout listeners; call this when discarding the box for good |

::: tip Reach for `HBox`/`VBox` first
`HBox` and `VBox` are `FlowBox` with `orientation` fixed to `'horizontal'`/`'vertical'` — use `FlowBox` directly only when the orientation itself needs to change at runtime.
:::

::: warning Per-child layout options live in `layoutOptions`, not on the child itself
Options like `align`, `grow`, `stretch`, and margins are consumed by the parent `FlowBox` from each child's `layoutOptions` object, not from options passed directly to the child's own constructor. Setting `someChild.align = 'center'` does nothing — set `someChild.layoutOptions = { align: 'center' }` instead (or pass `align` on the `FlowBox` itself to apply it to every child).
:::


========================================================================
Page: FocusManager
URL: https://veillette.github.io/Almanach/api/scenery/focus-manager
Source: docs/api/scenery/focus-manager.md
Category: API | Tags: scenery, FocusManager, focus, accessibility, pdomFocus | Status: verified
========================================================================

# FocusManager

`FocusManager` (from `scenerystack/scenery`) is the class-level API behind scenery's focus system — it owns the Properties that track *where* focus currently is (DOM/keyboard focus, pointer hover focus for [Interactive Highlighting](/api/scenery/interactive-highlighting), and reading-block focus for Voicing) and a few Properties that control whether the corresponding highlights are visible. This page documents `FocusManager` itself; for what the Parallel DOM is and how to opt a `Node` into it, see [The Parallel DOM](/accessibility/pdom), and for customizing the highlight that's drawn, see [Focus Highlights](/accessibility/focus-highlights).

Simulation code rarely constructs a `FocusManager` directly — a `Display` owns one — but reads and writes its static `pdomFocus` to inspect or move keyboard focus programmatically:

```ts
import { FocusManager } from 'scenerystack/scenery';

// What Node currently has DOM/keyboard focus, if any
const focusedNode = FocusManager.pdomFocus?.trail.lastNode() ?? null;

// Move focus to null to defocus everything (also blurs the active element)
FocusManager.pdomFocus = null;
```

## Static members

`pdomFocus` is a **static** accessor, because the DOM itself only allows one focused element at a time — it wouldn't make sense per-Display.

| Member | Effect |
| --- | --- |
| `FocusManager.pdomFocus` | Static get/set `Focus \| null` — the `Focus` (a `Display` + `Trail` pair) whose Node currently has DOM/keyboard focus. Setting it to `null` blurs the active element |
| `FocusManager.pdomFocusProperty` | Static `Property<Focus \| null>` mirroring `pdomFocus`, for listening to focus changes rather than polling |
| `FocusManager.windowHasFocusProperty` | Static `TReadOnlyProperty<boolean>` — whether the browser window itself currently has focus (useful for pausing global keyboard listeners when the tab is backgrounded) |
| `FocusManager.attachToWindow()` / `detachFromWindow()` | Static — wires/unwires the window `focus`/`blur` listeners behind `windowHasFocusProperty`; called for you when a `Display` initializes events |

## Instance Properties

Each `Display` holds one `FocusManager` instance with these Properties:

| Property | Tracks |
| --- | --- |
| `pointerFocusProperty` | `Focus \| null` — the Node under the pointer that supports [Interactive Highlighting](/api/scenery/interactive-highlighting) |
| `lockedPointerFocusProperty` | `Focus \| null` — set while a pointer is actively interacting with a Node, so the highlight doesn't jump to whatever the pointer happens to be over mid-drag |
| `readingBlockFocusProperty` | `Focus \| null` — the Node whose Voicing "reading block" content is currently being spoken |
| `pdomFocusHighlightsVisibleProperty` | `boolean` — whether highlights for DOM/keyboard focus should be drawn |
| `interactiveHighlightsVisibleProperty` | `boolean` — whether pointer-hover highlights should be drawn (a user preference, off by default) |
| `readingBlockHighlightsVisibleProperty` | `boolean` — whether reading-block highlights should be drawn |
| `pointerHighlightsVisibleProperty` | Derived `boolean` — `true` if either interactive-highlight or reading-block highlights are enabled |

::: tip Setting `pdomFocus` does not scroll or validate focusability for you
`FocusManager.pdomFocus = new Focus( display, trail )` moves scenery's notion of focus, but the underlying DOM element must actually be focusable (`focusable: true` and present in the PDOM, see [The Parallel DOM](/accessibility/pdom)) — assigning a `Focus` for a Node that isn't focusable is a no-op from the browser's perspective even though the Property changes.
:::


========================================================================
Page: Font
URL: https://veillette.github.io/Almanach/api/scenery/font
Source: docs/api/scenery/font.md
Category: API | Tags: scenery, Font, typography, text | Status: verified
========================================================================

# Font

`Font` (from `scenerystack/scenery`) is an immutable object describing a CSS-style font — style, variant, weight, stretch, size, line-height, and family — used by [`Text`](/api/scenery/text) and `RichText`'s `font` option. Simulation code almost always reaches for `PhetFont` (from `scenerystack/scenery-phet`) instead of constructing a plain `Font` directly; see [Typography and Fonts](/styling/typography-and-fonts) for that convention. This page documents the lower-level `Font` class itself.

```ts
import { Font, Text } from 'scenerystack/scenery';

const font = new Font( {
  family: '"Times New Roman", serif',
  style: 'italic',
  size: 16,
  weight: 'bold'
} );

const label = new Text( 'Hello', { font } );

font.font;   // "italic bold 16px 'Times New Roman', serif" — the combined CSS shorthand
font.family; // "'Times New Roman', serif"
```

`Font` is immutable: every property is set once at construction and there are no setters, only getters — to change a Text's font, construct a new `Font` (or use `Text`'s `fontSize`/`fontWeight`/etc. shorthand setters, which do this for you).

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `style` | `'normal'` | `'normal' \| 'italic' \| 'oblique'` |
| `variant` | `'normal'` | `'normal' \| 'small-caps'` |
| `weight` | `'normal'` | A CSS font-weight keyword (`'normal'`, `'bold'`, `'bolder'`, `'lighter'`) or a `'100'`–`'900'` string/number |
| `stretch` | `'normal'` | A CSS font-stretch keyword, e.g. `'condensed'`, `'expanded'` |
| `size` | `'10px'` | A number (treated as a pixel count) or any valid CSS font-size string |
| `lineHeight` | `'normal'` | A CSS line-height value |
| `family` | `'sans-serif'` | A comma-separated CSS font-family list |

## Reading values

| Member | Returns |
| --- | --- |
| `font` | The combined CSS font shorthand string, e.g. `"bold 10px sans-serif"` |
| `style`, `variant`, `weight`, `stretch`, `size`, `lineHeight`, `family` | The individual component, as given (or defaulted) at construction |

## Static helpers

| Static member | Effect |
| --- | --- |
| `Font.DEFAULT` | The shared default `Font` instance (`10px sans-serif`) |
| `Font.isFontStyle( s )` / `isFontVariant( s )` / `isFontWeight( s )` / `isFontStretch( s )` | Type-guard validators for each component's valid string values |
| `Font.fromCSS( cssString )` | Parses a CSS font shorthand string (e.g. `"italic bold 16px serif"`) into a `Font` instance |

::: tip Prefer `PhetFont`, not raw `Font`
`PhetFont` (from `scenerystack/scenery-phet`) wraps `Font` with the project's standard typeface and a guaranteed `sans-serif` fallback, so simulation code stays visually consistent. Reach for plain `Font` only when working outside a PhET-style project, or when building `PhetFont` itself. See [Typography and Fonts](/styling/typography-and-fonts) for the full convention.
:::


========================================================================
Page: GridBox
URL: https://veillette.github.io/Almanach/api/scenery/grid-box
Source: docs/api/scenery/grid-box.md
Category: API | Tags: scenery, GridBox, layout | Status: verified
========================================================================

# GridBox

`GridBox` (from `scenerystack/scenery`) is a [`Node`](/api/scenery/node) that arranges its children in a two-dimensional grid of rows and columns, similar to CSS grid. Where [`FlowBox`](/api/scenery/flow-box) only handles one axis at a time, `GridBox` positions each child at an explicit `(row, column)` cell (or lets it auto-place), independently controlling per-column width and per-row height so everything lines up.

```ts
import { GridBox, Rectangle, Circle } from 'scenerystack/scenery';

const grid = new GridBox( {
  xSpacing: 10,
  ySpacing: 8,
  children: [
    new Rectangle( 0, 0, 40, 40, { fill: 'teal', layoutOptions: { column: 0, row: 0 } } ),
    new Circle( 20, { fill: 'crimson', layoutOptions: { column: 1, row: 0 } } ),
    new Rectangle( 0, 0, 90, 20, { fill: 'goldenrod', layoutOptions: { column: 0, row: 1, horizontalSpan: 2 } } )
  ]
} );
```

Each child's cell position and span are set through that child's `layoutOptions`, not through `GridBox` options — `GridBox` itself only configures grid-wide defaults (spacing, alignment, margins) and how auto-placement behaves.

## `GridBox`-level options

| Option | Default | Effect |
| --- | --- | --- |
| `rows` | — | Sets children all at once from a 2D `(Node \| null)[][]` (`rows[row][column]`); mutually exclusive with `children`/`columns` |
| `columns` | — | Same idea, transposed (`columns[column][row]`); mutually exclusive with `children`/`rows` |
| `autoRows` | `null` | When set, children auto-place into 1-column-wide cells, wrapping to a new column after this many rows |
| `autoColumns` | `null` | Same idea, wrapping to a new row after this many columns |
| `resize` | `true` | Whether the GridBox keeps re-running layout after construction |
| `spacing` | `0` | Shorthand for setting both `xSpacing` and `ySpacing` |
| `xSpacing` / `ySpacing` | `0` | Gap between columns / between rows |
| `xAlign` | `'center'` | Horizontal alignment within a cell: `'left'`, `'right'`, `'center'`, or `'origin'` |
| `yAlign` | `'center'` | Vertical alignment within a cell: `'top'`, `'bottom'`, `'center'`, or `'origin'` |
| `margin` / `xMargin` / `yMargin` / `leftMargin` / `rightMargin` / `topMargin` / `bottomMargin` | `0` | Per-cell margins, box-wide or overridable per child |
| `minContentWidth` / `minContentHeight` / `maxContentWidth` / `maxContentHeight` | — | Clamp the GridBox's own content size |

## Per-child `layoutOptions` (grid position)

These can **only** be set via a child's `layoutOptions`, not as `GridBox` constructor options:

| `layoutOptions` key | Effect |
| --- | --- |
| `column` | Zero-based column index for this child (leftmost column is `0`) |
| `row` | Zero-based row index for this child (topmost row is `0`) |
| `horizontalSpan` | Number of columns this child occupies (default `1`) |
| `verticalSpan` | Number of rows this child occupies (default `1`) |
| `xAlign` / `yAlign` / `xStretch` / `yStretch` / `xGrow` / `yGrow` / margins | Per-child overrides of the corresponding `GridBox`-level option |

## Methods

| Method | Effect |
| --- | --- |
| `setLines( orientation, lineArrays )` / `getLines( orientation )` | Programmatic equivalent of the `rows`/`columns` options, for reading or rewriting the whole grid at once |
| `dispose()` | Releases layout listeners |

::: tip Auto-placement vs. explicit placement
Use `autoRows`/`autoColumns` when children are added dynamically and you just want them to flow into a grid (like a tag list). Use explicit `layoutOptions.row`/`.column` (or the `rows`/`columns` constructor options) when the grid has a fixed, meaningful structure — the two approaches are mutually exclusive per the source's own `NOTE`s.
:::

::: warning `rows`/`columns` rewrites `layoutOptions` and replaces all children
Passing `rows` or `columns` mutates every listed child's `layoutOptions` to bake in its `(row, column)` position, and replaces the `GridBox`'s entire `children` list. Don't mix it with manually calling `addChild()`/`removeChild()` afterward without accounting for that; prefer `autoRows`/`autoColumns` or manual `layoutOptions` if you need to add/remove children incrementally.
:::


========================================================================
Page: HBox
URL: https://veillette.github.io/Almanach/api/scenery/h-box
Source: docs/api/scenery/h-box.md
Category: API | Tags: scenery, HBox, VBox, FlowBox, layout | Status: verified
========================================================================

# HBox

`HBox` (from `scenerystack/scenery`) is [`FlowBox`](/api/scenery/flow-box) with `orientation` fixed to `'horizontal'` — it lays its children out left-to-right in a single row. Like [`VBox`](/api/scenery/v-box), it's the class most code reaches for instead of `FlowBox` directly, since orientation rarely changes at runtime; `HBox` accepts every `FlowBox` option (`spacing`, `align`, `stretch`, `grow`, `justify`, `wrap`, margins, …) except `orientation`, which the constructor sets for you and asserts you didn't also pass.

```ts
import { HBox, Circle, Rectangle } from 'scenerystack/scenery';

const row = new HBox( {
  spacing: 10,
  align: 'center',
  children: [
    new Circle( 15, { fill: 'crimson' } ),
    new Rectangle( 0, 0, 40, 30, { fill: 'teal' } ),
    new Circle( 10, { fill: 'goldenrod' } )
  ]
} );
```

For a vertical (column) layout, use [`VBox`](/api/scenery/v-box) instead; for the full option table (spacing, alignment, growth, wrapping, margins) see [`FlowBox`](/api/scenery/flow-box), which documents everything `HBox` inherits.

## Options and methods

`HBoxOptions` is `FlowBoxOptions` with `orientation` omitted — every option and method documented on [`FlowBox`](/api/scenery/flow-box) (`spacing`, `align`, `grow`, `justify`, `wrap`, `getCell()`, `dispose()`, …) applies here unchanged, just fixed to a horizontal main axis. For a row layout, `align` takes the vertical-alignment values (`'top'`, `'bottom'`, `'center'`, `'origin'`) since it controls cross-axis (vertical) placement of each child.

::: warning Use `VSeparator`, not `HSeparator`, to divide an `HBox`
`HBox` asserts against inserting an `HSeparator` child — a *horizontal* dividing line makes no sense between columns laid out *horizontally*. Use `VSeparator` (a vertical rule, also from `scenerystack/scenery`) to visually divide sections of an `HBox`; `HSeparator` is for dividing rows inside a [`VBox`](/api/scenery/v-box) instead.
:::


========================================================================
Page: Highlight Rendering: HighlightPath and HighlightOverlay
URL: https://veillette.github.io/Almanach/api/scenery/highlight-rendering
Source: docs/api/scenery/highlight-rendering.md
Category: API | Tags: scenery, HighlightPath, HighlightOverlay, HighlightFromNode, accessibility, focus | Status: complete
========================================================================

# Highlight Rendering: HighlightPath and HighlightOverlay

[Focus Highlights](/accessibility/focus-highlights) explains *how to customize* the highlight a focusable Node shows — swapping in a `HighlightFromNode`, a raw `Shape`, or a Node of your own. This page covers the machinery underneath that actually draws those highlights: `HighlightPath` (from `scenerystack/scenery`), the `Path` subclass with the double-stroke "glow" look, and `HighlightOverlay`, the per-`Display` overlay that decides which highlight is currently active and renders it in its own child `Display`.

## HighlightPath: the double-stroke look

A `HighlightPath` is a `Path` with a second, child `Path` (`innerHighlightPath`) drawn on top — an "outer" highlight (lighter, wider) and an "inner" highlight (darker, more opaque), giving the appearance of a highlight fading outward. `HighlightFromNode` (used throughout the [Focus Highlights guide](/accessibility/focus-highlights)) is a `HighlightPath` subclass that derives its shape from a Node's bounds and keeps it updated as those bounds change.

```ts
import { HighlightPath } from 'scenerystack/scenery';
import { Shape } from 'scenerystack/kite';

const highlight = new HighlightPath( Shape.roundRect( 0, 0, 40, 40, 4, 4 ), {
  dashed: true // e.g. to indicate the target is currently being manipulated
} );
```

| Option | Default | Effect |
| --- | --- | --- |
| `outerStroke` / `innerStroke` | `HighlightPath.OUTER_FOCUS_COLOR` / `INNER_FOCUS_COLOR` | Colors of the two strokes |
| `outerLineWidth` / `innerLineWidth` | `null` (computed from the local-to-global transform) | Fix the line widths instead of letting them scale automatically with the highlighted Node |
| `lineDashOverride` | `null` | Fixes the dash pattern instead of letting it scale with the transform |
| `dashed` | `false` | Whether the highlight uses a dashed stroke — PhET convention for "this is currently grabbed/being manipulated" |
| `transformSourceNode` | `null` | The Node whose transform this highlight should track (set automatically by `HighlightFromNode`) |

Static helpers worth knowing: `HighlightPath.getDilationCoefficient( matrix )` computes how far outside a Node's bounds the highlight should sit so there's visible whitespace between the Node and the inner edge of the highlight, and `HighlightPath.getDefaultHighlightLineWidth()` returns the untransformed default line width — useful if you need to reserve layout space for a highlight.

## HighlightOverlay: one per Display

Every [`Display`](/api/scenery/display) that supports focus gets a `HighlightOverlay`, which owns a completely separate child `Display` layered on top of the main scene graph (`pointer-events: none`, so it never intercepts input). It listens to the global PDOM focus Property, the [`FocusManager`](/api/scenery/focus-manager)'s pointer/reading-block focus Properties, and picks one of four modes per activation:

| Mode | When |
| --- | --- |
| `'bounds'` | Default — no custom `focusHighlight` was set; draws a `HighlightFromNode` around the focused Node's bounds |
| `'shape'` | The Node's `focusHighlight`/`interactiveHighlight` is a kite `Shape` |
| `'node'` | The Node's highlight is itself a `Node` (optionally `focusHighlightLayerable` to place it in the main scene graph instead of the overlay) |
| `'invisible'` | The literal string `'invisible'` — suppresses the highlight entirely (mainly for automated testing) |

`HighlightOverlay` also owns the group-focus-highlight and reading-block-highlight rendering, and exposes static setters for globally re-theming every highlight in an application:

```ts
import { HighlightOverlay } from 'scenerystack/scenery';
import { Color } from 'scenerystack/scenery';

// Re-theme every focus highlight application-wide, e.g. for a dark background.
HighlightOverlay.setInnerHighlightColor( new Color( 'yellow' ) );
```

| Static method | Effect |
| --- | --- |
| `setInnerHighlightColor( color )` / `getInnerHighlightColor()` | Inner stroke color used by all subsequently drawn focus highlights |
| `setOuterHilightColor( color )` / `getOuterHighlightColor()` | Outer stroke color (note the source's method name is `setOuterHilightColor`, missing a "g") |
| `setInnerGroupHighlightColor` / `setOuterGroupHighlightColor` | Same, for group focus highlights |

::: tip Line width and dash scale automatically with pan/zoom and Node scale
`HighlightOverlay` recomputes each highlight's line width and dash pattern every time its [`TransformTracker`](/api/scenery/transform-tracker) reports a transform change, combining the Node's own scale with the inverse of the current pan/zoom matrix (`HighlightPath.getCorrectiveScalingMatrix()`). This is why a focus highlight looks the same relative thickness whether the Node is scaled up, scaled down, or the user has zoomed in with [`AnimatedPanZoomListener`](/api/scenery/animated-pan-zoom-listener) — you don't need to correct for either case yourself.
:::


========================================================================
Page: Hit-Testing and Picking
URL: https://veillette.github.io/Almanach/api/scenery/hit-testing-and-picking
Source: docs/api/scenery/hit-testing-and-picking.md
Category: API | Tags: scenery, Picker, pickable, mouse-area, touch-area, cursor, input | Status: complete
========================================================================

# Hit-Testing and Picking

Every `Node` internally owns a `Picker` (`scenerystack/scenery`, but never constructed directly — it's an implementation detail of `Node`) that decides whether a given point hits that Node's subtree, and caches enough bounds information to prune most of the scene graph before doing expensive per-shape containment checks. You won't call into `Picker` yourself, but its behavior is controlled entirely through Node options you *do* set directly: `pickable`, `mouseArea`, `touchArea`, and `cursor`.

```ts
import { Circle } from 'scenerystack/scenery';
import { Shape } from 'scenerystack/kite';

const smallTarget = new Circle( 6, {
  fill: 'red',
  cursor: 'pointer',
  // Expand the *touch* hit region well beyond the drawn 6px radius, without changing
  // how it looks or how mouse hit-testing behaves.
  touchArea: Shape.circle( 0, 0, 22 )
} );
```

## `pickable`: the tri-state that controls pruning

| Value | Meaning |
| --- | --- |
| `null` (default) | Pass-through: this subtree is only hit-tested if some ancestor or descendant is `pickable: true` or has an input listener attached |
| `false` | This Node and its entire subtree are pruned — nothing in it will ever be hit, receive events, or be picked, regardless of listeners |
| `true` | This subtree is never pruned for lacking a listener (it's always searched), except where a descendant sets `pickable: false` |

The practical rule: **you almost never need to set `pickable` explicitly.** Attaching an input listener (a [`FireListener`](/api/scenery/fire-listener), [`DragListener`](/api/scenery/drag-listener), etc.) already makes a Node's subtree includable in hit-testing. `pickable: false` is for the opposite case — a decorative overlay drawn on top of interactive content that should be visible but never intercept input, letting hits fall through to whatever is beneath it.

## `mouseArea` and `touchArea`

Both accept a `Shape` (see [kite `Shape`](/api/kite/shape)) or a `Bounds2`, in the Node's local coordinate frame, and completely replace the drawn shape for the purposes of hit-testing that input type — a mouse/touch position only counts as "over" the Node if it falls inside the given area, not the Node's actual painted region. This is the standard way to make small controls touch-friendly without changing how they look: dilate the touch area well past the visual bounds while leaving `mouseArea` unset (so precise mouse pointing still behaves normally).

## `cursor`

A CSS cursor string (or `null` to inherit from whatever's shown by default). `Node.getEffectiveCursor()` walks: this Node's own `cursor`, then any attached input listener's cursor (see `useInputListenerCursor` on [`PressListener`](/api/scenery/fire-listener)), falling through to ancestors if none is set — this is how a listener's `pressCursor` can force a specific cursor for the duration of a press even as the pointer moves off the original target.

::: tip `pickable: false` is not the same as `inputEnabled: false`
If you want a Node to still be "pickable" — showing a cursor, appearing as hovered/focused, participating in [interactive highlighting](/api/scenery/interactive-highlighting) — but not actually respond to input, use `inputEnabled: false` on the Node instead of `pickable: false`. `pickable: false` removes the subtree from hit-testing entirely (so nothing under it looks interactive either); `inputEnabled: false` only suppresses the *events* while leaving picking behavior alone.
:::


========================================================================
Page: Hotkey, HotkeyData, and globalHotkeyRegistry
URL: https://veillette.github.io/Almanach/api/scenery/hotkeys
Source: docs/api/scenery/hotkeys.md
Category: API | Tags: scenery, Hotkey, HotkeyData, globalHotkeyRegistry, input, keyboard, accessibility | Status: complete
========================================================================

# Hotkey, HotkeyData, and globalHotkeyRegistry

`Hotkey` (from `scenerystack/scenery`) is the low-level object that represents a single keyboard shortcut — one main key plus optional modifier keys, with press/release/fire callbacks. [`KeyboardListener`](/api/scenery/keyboard-listener) is built on top of `Hotkey` (its `keys` option internally creates one `Hotkey` per entry, exposed via `keyboardListener.hotkeys`), and most application code should reach for `KeyboardListener` first. Use `Hotkey` directly when you need a shortcut that lives *outside* the usual "attach to a focusable Node" model — either globally regardless of focus (via `globalHotkeyRegistry`), or as a light-weight `TInputListener` entry without the rest of `KeyboardListener`'s API.

```ts
import { Hotkey, globalHotkeyRegistry } from 'scenerystack/scenery';
import { Property } from 'scenerystack/axon';

// Available anywhere in the document, regardless of what has focus.
globalHotkeyRegistry.add( new Hotkey( {
  keyStringProperty: new Property( 'alt+shift+d' ),
  fire: () => console.log( 'debug overlay toggled' )
} ) );

// Or, scoped to a Node's own focus, added directly as an inputListeners entry:
someNode.addInputListener( {
  hotkeys: [
    new Hotkey( {
      keyStringProperty: new Property( 'escape' ),
      fire: () => console.log( 'closed' )
    } )
  ]
} );
```

## `Hotkey` options

| Option | Default | Effect |
| --- | --- | --- |
| `keyStringProperty` | *(required)* | A `TReadOnlyProperty<OneKeyStroke>` describing the key + modifiers, e.g. `'shift+tab'` — a Property (not a plain string) so hotkeys can support i18n/remapping later |
| `fire` | no-op | `( event: KeyboardEvent \| null ) => void` — the event is `null` when fired via fire-on-hold repetition |
| `press` / `release` | no-op | Called on press/release; `press` is not called for fire-on-hold repeats |
| `fireOnDown` | `true` | Fire when the combination is first pressed; `false` fires on release instead |
| `fireOnHold` | `false` | Whether holding the combination repeats `fire` |
| `fireOnHoldTiming` | `'browser'` | `'browser'` uses the OS/browser's own key-repeat timing; `'custom'` uses the two options below |
| `fireOnHoldCustomDelay` / `fireOnHoldCustomInterval` | `400` / `100` | Timing in ms when `fireOnHoldTiming: 'custom'` |
| `overlapBehavior` | `'handle'` | How this hotkey behaves when another active hotkey shares one of its keys — see below |

`isPressedProperty` reports whether the hotkey is currently active, `interrupted` records whether the most recent release was due to an interruption rather than a key-up, and `interrupt()` cancels an in-progress press.

### `overlapBehavior`

| Value | Meaning |
| --- | --- |
| `'handle'` | Default for node-scoped hotkeys — if two active hotkeys share keys, only the one closest to the focused Node in the scene graph fires |
| `'prevent'` | Default for `globalHotkeyRegistry` entries — overlapping global hotkeys are treated as a programming error and assert |
| `'allow'` | Both overlapping hotkeys fire; takes precedence over `'prevent'` if the two disagree |

## `HotkeyData`

`HotkeyData` bundles a set of keystrokes with the documentation metadata scenery needs for the keyboard-help dialog and PhET's internal "binder" documentation generator — it doesn't itself listen for anything. It's the shape [`KeyboardDragListener`](/api/scenery/keyboard-drag-listener) and other built-in listeners use internally to describe *which* keys they respond to, separately from the listener that acts on them.

| Member | Meaning |
| --- | --- |
| `keys` (constructor option) | `Array<OneKeyStroke \| TReadOnlyProperty<OneKeyStroke>>` — the keystrokes this data describes |
| `keyStringProperties` | Normalized array of `TReadOnlyProperty<OneKeyStroke>`, one per key in `keys` |
| `hasKeyStroke( keyStroke )` | Whether any of this data's keys match the given stroke |
| `HotkeyData.combineKeyStringProperties( array )` | Static — flattens several `HotkeyData`'s key Properties into one array, handy for feeding a single `KeyboardListener` |
| `HotkeyData.anyHaveKeyStroke( array, keyStroke )` | Static — checks a keystroke against a whole array of `HotkeyData` at once |

## `globalHotkeyRegistry`

A module-level singleton (not a class you construct) with one member: `hotkeysProperty`, a `TProperty<Set<Hotkey>>` of every currently-registered global hotkey. Call `globalHotkeyRegistry.add( hotkey )` / `.remove( hotkey )` to make a `Hotkey` active regardless of what has document focus — this is what `KeyboardListener.createGlobal()` uses internally.

::: warning Modifier keys must be listed explicitly, exactly as with KeyboardListener
`Hotkey` (and therefore `KeyboardListener`) only fires when *exactly* the described keys are down. A hotkey for `'tab'` will not fire while shift is also held — add `'shift+tab'` as a second `Hotkey`, or mark the modifier ignorable in the key string with `'shift?+tab'`, exactly as documented on [`KeyboardListener`](/api/scenery/keyboard-listener).
:::


========================================================================
Page: HSeparator, VSeparator, HStrut, and VStrut
URL: https://veillette.github.io/Almanach/api/scenery/separators-and-struts
Source: docs/api/scenery/separators-and-struts.md
Category: API | Tags: scenery, HSeparator, VSeparator, HStrut, VStrut, Separator, FlowBox, layout | Status: complete
========================================================================

# HSeparator, VSeparator, HStrut, and VStrut

These four small `Node` subclasses (all from `scenerystack/scenery`) exist to be dropped directly into a layout container's `children` array as spacing helpers, rather than being positioned by hand: `HSeparator`/`VSeparator` draw a thin dividing line that automatically stretches to fill the container's cross-axis width/height, while `HStrut`/`VStrut` draw nothing and simply reserve a fixed amount of space along one axis. Both pairs are meant to read clearly at the call site — "put a divider here" or "put a fixed gap here" — inside a [`FlowBox`](/api/scenery/flow-box), [`VBox`](/api/scenery/v-box), or [`HBox`](/api/scenery/h-box).

```ts
import { VBox, HSeparator, Text, HBox, HStrut, Circle } from 'scenerystack/scenery';

const menu = new VBox( {
  align: 'left',
  spacing: 4,
  children: [
    new Text( 'Option A' ),
    new Text( 'Option B' ),
    new HSeparator(),      // a full-width horizontal rule between the groups
    new Text( 'Option C' )
  ]
} );

const row = new HBox( {
  spacing: 4,
  children: [
    new Circle( 10, { fill: 'crimson' } ),
    new HStrut( 40 ),      // a fixed 40px gap, wider than `spacing` alone
    new Circle( 10, { fill: 'teal' } )
  ]
} );
```

## `HSeparator` and `VSeparator`

`new HSeparator( options? )` and `new VSeparator( options? )` are both `Line` subclasses (via a shared internal `Separator` base) that default to a dark gray `stroke` (`'rgb(100,100,100)'`) and set `layoutOptions: { stretch: true, isSeparator: true }`. `HSeparator` draws a horizontal line and grows to fill the *width* offered by its parent's layout constraint (for use inside a vertical container like `VBox`); `VSeparator` draws a vertical line and grows to fill *height* (for use inside a horizontal container like `HBox`). `SeparatorOptions` is `LineOptions` minus `tandem` — separators are purely presentational and are not PhET-iO instrumented.

The `isSeparator: true` layout flag is what makes separators special inside `FlowBox`-based containers (`VBox`/`HBox`): a separator that would end up first, last, or immediately adjacent to another separator in the visible layout order is automatically hidden, so toggling the visibility of surrounding items never leaves a dangling or doubled-up divider line.

## `HStrut` and `VStrut`

`HStrut` and `VStrut` are thin [`Spacer`](/api/scenery/spacer) subclasses — `new HStrut( width, options? )` is exactly `new Spacer( width, 0, options )`, and `new VStrut( height, options? )` is exactly `new Spacer( 0, height, options )`. Like `Spacer`, they draw nothing and can never have children; they exist purely so a layout container sees reserved space of the given size. `HStrutOptions`/`VStrutOptions` are just `SpacerOptions` (in turn just `NodeOptions`) — there's no strut-specific option beyond the constructor's single dimension argument. See [Spacer](/api/scenery/spacer) for the full details these two thin wrappers build on.

## Choosing between them

| Need | Use |
| --- | --- |
| A visible dividing line, full-width/height, that auto-hides at the edges | `HSeparator` / `VSeparator` |
| An invisible, fixed-size gap along one axis, larger or smaller than the container's uniform `spacing` | `HStrut` / `VStrut` |
| An invisible, fixed-size rectangular block (both dimensions) | [`Spacer`](/api/scenery/spacer) directly |

::: tip Separators only auto-hide inside FlowBox-based containers
The "hide at the edges / hide when adjacent to another separator" behavior comes from `isSeparator` being read by `FlowBox`'s layout constraint (which `VBox`/`HBox` both use). An `HSeparator`/`VSeparator` placed outside of a `FlowBox`-family container is just a `Line` with default styling — it stretches via `localPreferredWidthProperty`/`localPreferredHeightProperty` only when a layout container actually provides a preferred size.
:::


========================================================================
Page: Image
URL: https://veillette.github.io/Almanach/api/scenery/image
Source: docs/api/scenery/image.md
Category: API | Tags: scenery, Image, mipmap | Status: verified
========================================================================

# Image

`Image` (from `scenerystack/scenery`) is a [`Node`](/api/scenery/node) that displays a single raster image, accepting a URL string, an `HTMLImageElement`, an `HTMLCanvasElement`, or a mipmap data structure (`ImageableImage`).

```ts
import { Image } from 'scenerystack/scenery';

const icon = new Image( '/assets/icon.png', {
  scale: 0.5,
  imageOpacity: 0.9
} );

icon.image = '/assets/icon-hover.png'; // swap the displayed image later
```

## Swapping the image via a Property

Pass a `TReadOnlyProperty<ImageableImage>` directly as the constructor argument (or as the `imageProperty` option) to have the displayed image track a `Property`, e.g. for theme or state-driven artwork:

```ts
import { Image } from 'scenerystack/scenery';
import { Property } from 'scenerystack/axon';

const sourceProperty = new Property<string>( '/assets/switch-off.png' );
const switchImage = new Image( sourceProperty );

sourceProperty.value = '/assets/switch-on.png'; // switchImage updates automatically
```

## Options

| Option | Effect |
| --- | --- |
| `image` | The image source: a URL string, `HTMLImageElement`, `HTMLCanvasElement`, or mipmap array |
| `imageProperty` | Sets forwarding of the image source from a `TReadOnlyProperty<ImageableImage>` |
| `imageOpacity` | Opacity applied to just this image (not its children), in `[0, 1]` |
| `imageBounds` | Overrides what region of the image is considered "inside" for bounds/hit-testing purposes |
| `initialWidth`, `initialHeight` | Placeholder dimensions to use for layout before the image has finished loading |
| `mipmap` | Whether mipmapped rendering is enabled, trading memory for smoother minification |
| `mipmapBias`, `mipmapInitialLevel`, `mipmapMaxLevel` | Fine-tune mipmap generation and level selection |
| `hitTestPixels` | Whether hit-testing should respect per-pixel transparency instead of the bounding rectangle |

`Image` also accepts the full set of [`Node` options](/api/scenery/node).

::: tip Give not-yet-loaded images a size
If an image URL hasn't finished loading when a layout container ([`FlowBox`](/api/scenery/flow-box), [`GridBox`](/api/scenery/grid-box)) measures it, its bounds will be empty and layout will shift once it loads. Set `initialWidth`/`initialHeight` to the image's known final dimensions to reserve the right amount of space up front.
:::


========================================================================
Page: InteractiveHighlighting
URL: https://veillette.github.io/Almanach/api/scenery/interactive-highlighting
Source: docs/api/scenery/interactive-highlighting.md
Category: API | Tags: scenery, InteractiveHighlighting, highlight, accessibility, pointer | Status: verified
========================================================================

# InteractiveHighlighting

`InteractiveHighlighting` (from `scenerystack/scenery`) is a trait that gives a Node a highlight on **pointer** hover (mouse/touch), the same visual language as the keyboard-focus highlights covered in [Focus Highlights](/accessibility/focus-highlights) — it exists so mouse and touch users get the same "this is interactive" affordance that keyboard users get for free from focus. Highlight visibility is gated behind a user preference (`FocusManager.interactiveHighlightsVisibleProperty`, see [`FocusManager`](/api/scenery/focus-manager)), so it does nothing until that preference is enabled.

`InteractiveHighlighting` is a mixin function, applied the same way as `Voicing`:

```ts
import { Node, InteractiveHighlighting, Rectangle } from 'scenerystack/scenery';

const iconNode = new Rectangle( 0, 0, 40, 40, { fill: 'teal' } );

class HoverableIcon extends InteractiveHighlighting( Node ) {
  public constructor() {
    super( {
      children: [ iconNode ],
      cursor: 'pointer',
      tagName: 'button',
      accessibleName: 'Play'
    } );
  }
}
```

For cases where composing a trait is more friction than it's worth, `InteractiveHighlightingNode` (from `scenerystack/scenery`) is a ready-made `InteractiveHighlighting( Node )` subclass:

```ts
import { InteractiveHighlightingNode } from 'scenerystack/scenery';

const hoverable = new InteractiveHighlightingNode( {
  children: [ iconNode ],
  cursor: 'pointer'
} );
```

## Options

These are `InteractiveHighlighting`'s mutator keys (`INTERACTIVE_HIGHLIGHTING_OPTIONS` in source):

| Option | Effect |
| --- | --- |
| `interactiveHighlight` | A `Shape \| Node \| 'invisible' \| null` highlight shown on pointer hover, analogous to `focusHighlight` from `ParallelDOM`. `null`/omitted falls back to the Node's bounds-based default |
| `interactiveHighlightLayerable` | If `true`, you take responsibility for placing the highlight Node in the scene graph yourself, rather than scenery's overlay drawing it on top |
| `interactiveHighlightEnabled` | `boolean` — turns the highlight-on-hover behavior on or off for this specific Node without removing the trait |

## Reading highlight-active state

| Member | Effect |
| --- | --- |
| `isInteractiveHighlightActiveProperty` | `TReadOnlyProperty<boolean>` — `true` while this Node's interactive highlight is currently displayed |
| `isInteractiveHighlighting( node )` | Exported standalone function (from `scenerystack/scenery`) — a type guard checking whether an arbitrary `Node` has composed this trait, preferred over `instanceof` checks against the mixin |

::: tip `Voicing` already includes `InteractiveHighlighting`
If a Node composes [`Voicing`](/api/scenery/voicing), it is already `InteractiveHighlighting`-capable — `Voicing`'s implementation extends `InteractiveHighlighting( Type )` internally. Reach for `InteractiveHighlighting` on its own only for Nodes that need a hover highlight but don't need Voicing's spoken responses.
:::


========================================================================
Page: KeyboardDragListener
URL: https://veillette.github.io/Almanach/api/scenery/keyboard-drag-listener
Source: docs/api/scenery/keyboard-drag-listener.md
Category: API | Tags: scenery, KeyboardDragListener, input, keyboard, accessibility, drag | Status: verified
========================================================================

# KeyboardDragListener

`KeyboardDragListener` (from `scenerystack/scenery`) is a `KeyboardListener` specialized for dragging: it moves an object with the arrow keys or W/A/S/D, writing to the same kind of model `positionProperty` a pointer [`DragListener`](/patterns/drag-listeners) would. Pointer dragging alone is never accessible, so any draggable object that needs to work for keyboard/switch users needs this listener (or [`RichDragListener`](/api/scenery/rich-drag-listener), which bundles both) in addition to — or instead of — pointer dragging.

```ts
import { Node, KeyboardDragListener } from 'scenerystack/scenery';

const bodyNode = new Node( { tagName: 'div', focusable: true } );

bodyNode.addInputListener( new KeyboardDragListener( {
  positionProperty: body.positionProperty,
  transform: modelViewTransform,
  dragBoundsProperty: model.dragBoundsProperty,
  dragSpeed: 150,     // model units/second while a key is held
  shiftDragSpeed: 50  // finer motion with shift held
} ) );
```

## Options

`KeyboardDragListenerOptions` accepts everything `DragListener` shares via `AllDragListenerOptions` (`positionProperty`, `transform`, `dragBoundsProperty`, `mapPosition`, `translateNode`, `start`/`drag`/`end`), plus:

| Option | Default | Effect |
| --- | --- | --- |
| `dragDelta` | `10` | Discrete step (in parent/view coordinates) moved per `moveOnHoldInterval` tick — a "typical application" feel; mutually exclusive with `dragSpeed`/`shiftDragSpeed` |
| `shiftDragDelta` | `5` | Finer `dragDelta` while shift is held |
| `dragSpeed` | `0` | Continuous units/second moved while a direction key is held — smoother, game-like motion; mutually exclusive with `dragDelta`/`shiftDragDelta` |
| `shiftDragSpeed` | `0` | Finer `dragSpeed` while shift is held |
| `keyboardDragDirection` | `'both'` | Constrains motion: `'both'` (2D), `'leftRight'`, or `'upDown'` |
| `moveOnHoldDelay` | `500` | Milliseconds a key must be held before repeat movement begins (delta mode only) |
| `moveOnHoldInterval` | `400` | Milliseconds between discrete steps once repeating (delta mode only; must be > 0) |

`dragSpeed`/`shiftDragSpeed` and `dragDelta`/`shiftDragDelta` are mutually exclusive — pick one motion model per listener. If you pass `dragBoundsProperty`, you must also provide `positionProperty` or `translateNode: true`, since the listener otherwise has no way to know the current position to constrain.

## Public state

| Member | Meaning |
| --- | --- |
| `modelDelta` | The `Vector2` delta (in model coordinates) applied during the current drag step |
| `modelPoint` | The current drag point in model coordinates |
| `isPressedProperty` (inherited from `KeyboardListener`) | Whether a drag is currently active |

## Methods

Shares `interrupt()` and `dispose()` with [`KeyboardListener`](/api/scenery/keyboard-listener), since `KeyboardDragListener` extends it directly.

::: tip Requires a focusable target — pair it with the PDOM
`KeyboardDragListener` only receives key events when its Node has keyboard focus. Set `tagName: 'div'` and `focusable: true` (and a meaningful `accessibleName`) on the target Node, or the listener will never fire. See [Drag Listeners](/patterns/drag-listeners) for the full checklist, including combining this with pointer dragging via `RichDragListener`.
:::


========================================================================
Page: KeyboardListener
URL: https://veillette.github.io/Almanach/api/scenery/keyboard-listener
Source: docs/api/scenery/keyboard-listener.md
Category: API | Tags: scenery, KeyboardListener, input, keyboard, accessibility, hotkey | Status: verified
========================================================================

# KeyboardListener

`KeyboardListener` (from `scenerystack/scenery`) declares one or more key combinations ("hotkeys") as strings and fires a callback when they're pressed, without you having to track `keydown`/`keyup` state by hand. It's the keyboard counterpart to [`FireListener`](/api/scenery/fire-listener): attach it via [`inputListeners`](/api/scenery/node) on a focusable `Node`, and it fires while that Node has focus (or, via `KeyboardListener.createGlobal`, anywhere in the document regardless of focus).

```ts
import { Node, KeyboardListener } from 'scenerystack/scenery';

const panel = new Node( { tagName: 'div', focusable: true } );

panel.addInputListener( new KeyboardListener( {
  keys: [ 'escape', 'shift+t' ],
  fire: ( event, keysPressed, listener ) => {
    if ( keysPressed === 'escape' ) {
      console.log( 'closed' );
    }
    else if ( keysPressed === 'shift+t' ) {
      console.log( 'shift+t pressed' );
    }
  }
} ) );
```

Each entry in `keys` is a combination like `'alt+shift+r'` — keys before the last one are modifiers, and modifier order doesn't matter. A `'?'` marks a modifier as ignorable: `'shift?+y'` fires on `y` whether or not shift is held.

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `keys` | `null` | Array of key combination strings, e.g. `[ 'a+b', 'shift+arrowLeft' ]`; mutually exclusive with `keyStringProperties` |
| `keyStringProperties` | `null` | Array of `TReadOnlyProperty<OneKeyStroke>` instead of static strings — for hotkeys that change with i18n or remapping |
| `fire` | no-op | `( event, keysPressed, listener ) => void`, called when the combination fires |
| `press` | no-op | Called on the initial press of a combination, before fire-on-hold repetition |
| `release` | no-op | Called on release (or `null` `keysPressed` on interruption) |
| `focus` / `blur` | no-op | Called when the listener's target Node gains/loses focus |
| `fireOnDown` | `true` | Fire when the combination is pressed; set `false` to fire on release instead |
| `fireOnHold` | `false` | Whether holding the combination repeats `fire` |
| `fireOnHoldTiming` | `'browser'` | `'browser'` (use the OS/browser's own key-repeat timing) or `'custom'` (use the two delay/interval options below) |
| `fireOnHoldCustomDelay` | `400` | Milliseconds held before repeat starts, when `fireOnHoldTiming: 'custom'` |
| `fireOnHoldCustomInterval` | `100` | Milliseconds between repeats, when `fireOnHoldTiming: 'custom'` |
| `overlapBehavior` | `'handle'` | How this listener behaves when another active `KeyboardListener` shares overlapping keys |

## Public state and methods

| Member | Meaning |
| --- | --- |
| `hotkeys` | The underlying `Hotkey[]` this listener created from `keys`/`keyStringProperties` |
| `isPressedProperty` | `true` while any of the listener's hotkeys is active |
| `interrupted` | Whether the most recent release was due to an interruption |
| `interrupt()` | Cancels any in-progress press without firing `release` normally |
| `dispose()` | Disposes every underlying `Hotkey` and this listener's Properties |
| `KeyboardListener.createGlobal( target, options )` | Static factory for a listener registered in the global hotkey registry — fires regardless of document focus, as long as `target` can receive input (visible, enabled, input-enabled) |

::: warning Modifier keys must be listed explicitly, or they suppress firing
The `fire` callback only runs when *exactly* the keys in a combination are down. Listing `'tab'` alone means it will **not** fire while shift is also held — you must add `'shift+tab'` as a separate entry in `keys` to handle that case too, or mark the modifier as ignorable with `'shift?+tab'`. This also applies to `KeyboardDragListener`'s underlying arrow/WASD keys, which is why the drag keys are declared with `?` internally.
:::


========================================================================
Page: Line
URL: https://veillette.github.io/Almanach/api/scenery/line
Source: docs/api/scenery/line.md
Category: API | Tags: scenery, Line, Path | Status: verified
========================================================================

# Line

`Line` (from `scenerystack/scenery`) is a [`Path`](/api/scenery/path) subclass that draws a single straight segment between two points, built from `p1`/`p2` (or `x1`/`y1`/`x2`/`y2`) parameters instead of a hand-built kite `Shape`. Since a `Line` has no interior area, only `stroke` (not `fill`) has a visible effect.

```ts
import { Line } from 'scenerystack/scenery';
import { Vector2 } from 'scenerystack/dot';

// new Line( x1, y1, x2, y2, options )
const axis = new Line( 0, 0, 100, 0, {
  stroke: 'black',
  lineWidth: 2
} );

// new Line( p1, p2, options )
const diagonal = new Line( new Vector2( 0, 0 ), new Vector2( 50, 50 ), { stroke: 'gray' } );

axis.x2 = 150; // update an endpoint after construction
```

## Constructor overloads

| Signature | Use case |
| --- | --- |
| `new Line( options )` | Fully options-driven |
| `new Line( p1, p2, options? )` | Endpoints as `Vector2`s |
| `new Line( x1, y1, x2, y2, options? )` | Endpoints as separate numbers |

## Options

| Option | Effect |
| --- | --- |
| `p1` | Start point as a `Vector2` |
| `p2` | End point as a `Vector2` |
| `x1`, `y1` | Start point coordinates individually |
| `x2`, `y2` | End point coordinates individually |

`Line` accepts every [`Path` option](/api/scenery/path) except `shape`/`shapeProperty` — `stroke`, `lineWidth`, `lineCap`, `lineDash`, etc. all apply — plus the full set of [`Node` options](/api/scenery/node).

::: tip `fill` has no effect
A `Line` has zero area, so setting `fill` does nothing visible; use `stroke` and `lineWidth` to control its appearance.
:::


========================================================================
Page: LinearGradient
URL: https://veillette.github.io/Almanach/api/scenery/linear-gradient
Source: docs/api/scenery/linear-gradient.md
Category: API | Tags: scenery, LinearGradient, gradient, paint, fill, stroke | Status: verified
========================================================================

# LinearGradient

`LinearGradient` (from `scenerystack/scenery`) is a paint type — like [`Color`](/api/scenery/color) — that can be assigned directly to a Node's `fill` or `stroke` option to render a color gradient along a straight line between two points, in the Node's local coordinate frame. It extends the abstract `Gradient` base class it shares with [`RadialGradient`](/api/scenery/radial-gradient), which supplies the shared `addColorStop` API.

```ts
import { Rectangle, LinearGradient } from 'scenerystack/scenery';

// Gradient line from (0, 0) to (100, 0) — a horizontal sweep across the Rectangle's width
const gradient = new LinearGradient( 0, 0, 100, 0 )
  .addColorStop( 0, 'red' )
  .addColorStop( 0.5, 'yellow' )
  .addColorStop( 1, 'green' );

const bar = new Rectangle( 0, 0, 100, 20, { fill: gradient } );
```

## Constructor

`new LinearGradient( x0, y0, x1, y1 )` — the four coordinates describe the gradient line's start (ratio 0) and end (ratio 1) points, in the local coordinate frame of whatever Node it's used on. The gradient extends perpendicular to this line and repeats the end colors beyond the line's extent.

## Color stops

`addColorStop( ratio, color )` (inherited from `Gradient`) appends one stop and returns `this`, so calls chain naturally:

| Parameter | Meaning |
| --- | --- |
| `ratio` | A number from `0` to `1`, position along the gradient line |
| `color` | `null`, a CSS string, a [`Color`](/api/scenery/color) instance, or a `Property` resolving to one of those |

Stops must be added in non-decreasing `ratio` order — calling `addColorStop` with a smaller ratio than the previous call throws, since browsers handle out-of-order stops inconsistently.

::: warning Color stops must be added in increasing order
`addColorStop( 0.5, 'yellow' )` followed by `addColorStop( 0.2, 'red' )` throws `'Color stops not specified in the order of increasing ratios'`. If stop positions are computed dynamically, sort them before calling `addColorStop` in a loop.
:::


========================================================================
Page: ManualConstraint
URL: https://veillette.github.io/Almanach/api/scenery/manual-constraint
Source: docs/api/scenery/manual-constraint.md
Category: API | Tags: scenery, ManualConstraint, layout, constraint | Status: verified
========================================================================

# ManualConstraint

`ManualConstraint` (from `scenerystack/scenery`) exists for the cases [`FlowBox`](/api/scenery/flow-box)/[`GridBox`](/api/scenery/grid-box) don't cover: one-off imperative positioning code like `node.left = otherNode.right + 5` that needs to automatically rerun whenever any of the involved Nodes' bounds change. Unlike writing that assignment once in application code, `ManualConstraint` also handles Nodes that don't share a coordinate frame directly — only a common ancestor — by giving the callback `LayoutProxy` objects (bounds-based positional getters/setters, like a Node's own `left`/`right`/`centerY`, but transformed into the ancestor's coordinate frame).

```ts
import { ManualConstraint, Node, Circle, Rectangle } from 'scenerystack/scenery';

const ancestor = new Node();
const label = new Rectangle( 0, 0, 100, 30, { fill: 'white' } );
const icon = new Circle( 8, { fill: 'crimson' } );
ancestor.children = [ label, icon ];

new ManualConstraint( ancestor, [ label, icon ], ( labelProxy, iconProxy ) => {
  iconProxy.left = labelProxy.right + 5;
  iconProxy.centerY = labelProxy.centerY;
} );
```

The constraint reruns the callback automatically whenever `label` or `icon`'s bounds change (or they're reparented) — you never call the assignment again yourself.

## Constructor

`new ManualConstraint( ancestorNode, nodes, layoutCallback )`

| Parameter | Meaning |
| --- | --- |
| `ancestorNode` | The common ancestor `Node` whose coordinate frame the layout is computed relative to; must be an ancestor of every entry in `nodes` |
| `nodes` | A tuple of `Node`s the callback needs to position — each becomes one `LayoutProxy` argument, in the same order |
| `layoutCallback` | `( ...proxies: LayoutProxy[] ) => void` — read/write positional properties on the proxies to perform layout |

A static `ManualConstraint.create( ancestorNode, nodes, layoutCallback )` is equivalent to calling the constructor directly, useful when you want a factory function reference instead of `new`.

## Behavior notes

- The callback only runs once every involved Node currently has a connected `Trail` back to `ancestorNode` — if a Node is temporarily removed from the tree, the constraint simply skips re-running until it's reconnected.
- Each `LayoutProxy` exposes the same bounds-based getters/setters as [`Node`](/api/scenery/node) (`left`, `right`, `top`, `bottom`, `centerX`, `centerY`, `center`, `width`, `height`, …), but reads/writes them in `ancestorNode`'s coordinate frame rather than the proxied Node's own parent frame.
- `dispose()` releases the constraint's internal `LayoutCell`s and stops listening to the constrained Nodes.

::: tip Reach for `FlowBox`/`GridBox`/`AlignBox` first
`ManualConstraint` is intentionally low-level — it doesn't know about spacing, alignment, or growth, it just reruns a callback you wrote. Prefer [`FlowBox`](/api/scenery/flow-box) or [`GridBox`](/api/scenery/grid-box) for anything expressible as a row/column/grid; reach for `ManualConstraint` only for relationships those containers can't express, such as positioning one Node relative to another that lives in a completely different part of the tree.
:::


========================================================================
Page: Node
URL: https://veillette.github.io/Almanach/api/scenery/node
Source: docs/api/scenery/node.md
Category: API | Tags: scenery, Node, scene-graph, transform, bounds | Status: verified
========================================================================

# Node

`Node` (from `scenerystack/scenery`) is the base class for every visual element in a scenery scene graph. On its own a `Node` draws nothing — it's a container that holds `children` and applies a transform (translation/rotation/scale), visibility, opacity, input behavior, and layout options to that subtree. Every other page in this section — [`Path`](/api/scenery/path), [`Text`](/api/scenery/text), [`Image`](/api/scenery/image), the layout containers — is a `Node` subclass, so the options and methods documented here apply everywhere.

```ts
import { Node, Circle, Rectangle } from 'scenerystack/scenery';
import { Vector2 } from 'scenerystack/dot';

const group = new Node( {
  children: [
    new Circle( 20, { fill: 'orange' } ),
    new Rectangle( 30, -10, 40, 20, { fill: 'teal' } )
  ],
  x: 100,
  y: 50,
  scale: 1.5,
  visible: true
} );

group.addChild( new Circle( 5, { fill: 'black', x: 60 } ) );
```

## Building the scene graph

| Method | Effect |
| --- | --- |
| `addChild( node )` | Appends `node` as the last (topmost) child |
| `insertChild( index, node )` | Inserts `node` at a specific position in the children order |
| `removeChild( node )` | Removes a specific child |
| `removeChildAt( index )` | Removes the child at a given index |
| `removeAllChildren()` | Clears all children |
| `mutate( options )` | Applies a `NodeOptions` object all at once, in a fixed, documented order |

Children later in the list are drawn on top of earlier ones — order matters for visual stacking, not just structure.

## Frequently used options

| Option | Effect |
| --- | --- |
| `children` | Initial list of child `Node`s, added in order |
| `visible` | Whether this Node (and its subtree) is displayed; invisible subtrees are also excluded from picking by default |
| `pickable` | `true`/`false`/`null` — overrides whether this subtree can receive input events |
| `enabled` | Application-level enabled state (paired with `enabledProperty`) |
| `inputEnabled` | Whether input events are allowed to reach this subtree |
| `inputListeners` | Array of input listeners attached at construction, e.g. a [`FireListener`](/api/scenery/fire-listener) |
| `opacity` | 0 (transparent) to 1 (opaque) applied to the whole subtree |
| `cursor` | CSS cursor shown when the pointer is over this Node |
| `x`, `y`, `translation` | Translation of this Node relative to its parent |
| `rotation` | Rotation in radians |
| `scale` | Uniform or `Vector2` scale |
| `left`, `right`, `top`, `bottom`, `centerX`, `centerY`, `center`, `leftTop`, `rightBottom`, … | Positioning shortcuts based on this Node's (parent-coordinate-frame) bounds — applied *after* other transform options |
| `maxWidth` / `maxHeight` | Automatically scales the Node down (never up) to fit within the given local-bounds dimensions |
| `clipArea` | A `Shape` (see [kite `Shape`](/api/kite/shape)) outside of which content is hidden |
| `mouseArea` / `touchArea` | Overrides the hit-testing region, independent of the drawn shape |
| `layoutOptions` | Options consumed by a parent layout container, e.g. [`FlowBox`](/api/scenery/flow-box) or [`GridBox`](/api/scenery/grid-box) |

## Reading bounds and position

```ts
const b = group.bounds;       // Bounds2 in the parent coordinate frame
const local = group.localBounds; // Bounds2 in this Node's own coordinate frame

group.center = new Vector2( 0, 0 ); // reposition using the bounds-based setter
```

`Node` also exposes coordinate-conversion helpers: `localToGlobalPoint( point )` and `globalToLocalPoint( point )` convert between this Node's local frame and the `Display`'s root frame — useful when translating pointer coordinates.

::: tip Order of options in `mutate()`
Node options are applied in a fixed, documented order (transform options like `x`/`scale` before bounds-based options like `left`/`center`). This is why you can safely pass both a `scale` and a `center` in the same options object and get the expected result — the centering happens after scaling.
:::

::: warning Dispose subtrees you remove permanently
Removing a `Node` from its parent does not automatically dispose it. If a subtree is being discarded for good (not just hidden), call `dispose()` (or `disposeSubtree()`) to release its listeners, `Property` links, and other resources — otherwise removed simulation elements can leak memory.
:::


========================================================================
Page: ParallelDOM
URL: https://veillette.github.io/Almanach/api/scenery/parallel-dom-deep-dive
Source: docs/api/scenery/parallel-dom-deep-dive.md
Category: API | Tags: scenery, ParallelDOM, pdom, accessibility, tagName, accessibleName | Status: verified
========================================================================

# ParallelDOM

`ParallelDOM` (from `scenerystack/scenery`) is the trait mixed into `Node` itself — every `Node`, not just some subset, has the options documented here available, though most are no-ops until you set `tagName` to place the Node in the Parallel DOM. This page documents the trait's actual options and accessors; for what the Parallel DOM is, why it exists, and worked examples of building an accessible scene graph, read the narrative guide [The Parallel DOM](/accessibility/pdom) first.

```ts
import { Node, Rectangle } from 'scenerystack/scenery';

const resetButton = new Rectangle( 0, 0, 40, 40, {
  tagName: 'button',
  accessibleName: 'Reset Masses',
  accessibleHelpText: 'Return both masses to their starting values.'
} );

const infoSection = new Node( {
  tagName: 'div',
  labelTagName: 'h3',
  labelContent: 'Mass Controls',
  descriptionContent: 'Adjust the mass of each body, in kilograms.'
} );
```

## Options

These are `ParallelDOM`'s actual mutator keys (`ACCESSIBILITY_OPTION_KEYS` in source), grouped as the source groups them:

| Option | Effect |
| --- | --- |
| `tagName` | HTML element name for this Node's primary sibling (`'div'`, `'button'`, `'ul'`, …). Setting it is what places the Node in the PDOM; `null` removes it |
| `focusable` | `boolean \| null` — whether the element can receive keyboard focus |
| `accessibleName` | Higher-level API: the accessible name announced by screen readers. Prefer this over the lower-level `innerContent`/`ariaLabel` options below |
| `accessibleHelpText` | Higher-level API: supplementary guidance text associated with the element |
| `accessibleParagraph` | Higher-level API: a standalone paragraph of accessible content, for a Node that is purely descriptive rather than interactive |
| `accessibleNameBehavior` / `accessibleHelpTextBehavior` / `accessibleParagraphBehavior` | Lower-level: functions controlling *how* the corresponding higher-level API value is rendered into the PDOM (which sibling, which attribute) — most code never needs to override these; reusable UI components (`sun` controls) do |
| `accessibleHeading` | Sets heading text for this Node using scenery's automatic heading-level management |
| `accessibleHeadingIncrement` | Adjusts how much this subtree increments the heading level counter |
| `containerTagName` / `containerAriaRole` | Tag name and ARIA role for an optional parent element wrapping this Node's own siblings |
| `innerContent` | Lower-level: text content placed inside the primary sibling element |
| `inputType` / `inputValue` / `pdomChecked` | Lower-level: for `tagName: 'input'` elements — the `type` attribute, `value`, and checked state |
| `ariaLabel` / `ariaRole` | Lower-level: raw `aria-label` and `role` attributes |
| `labelTagName` / `labelContent` / `appendLabel` | A sibling label element, its content, and whether it's ordered after (rather than before) the primary sibling |
| `descriptionTagName` / `descriptionContent` / `appendDescription` | A sibling description element, its content, and ordering |
| `focusHighlight` / `focusHighlightLayerable` / `groupFocusHighlight` | The Node's focus highlight — see [Focus Highlights](/accessibility/focus-highlights) for the full picture |
| `pdomVisible` / `pdomVisibleProperty` | Whether this Node's PDOM content is present at all, independent of its visual `visible` |
| `pdomOrder` | Explicit traversal order for this Node's PDOM children, overriding scene-graph order |
| `pdomAttributes` | Arbitrary additional PDOM element attributes |
| `ariaLabelledbyAssociations` / `ariaDescribedbyAssociations` / `activeDescendantAssociations` | Cross-Node ARIA relationships (`aria-labelledby`, `aria-describedby`, `aria-activedescendant`) pointing at other Nodes' PDOM elements |
| `focusPanTargetBoundsProperty` / `limitPanDirection` | Controls for auto-panning the viewport to keep this Node visible when it receives focus |
| `positionInPDOM` | Whether this Node's DOM element should also be moved to visually overlap its rendered position (needed for some native form controls) |
| `pdomTransformSourceNode` | An alternate Node whose transform should be used to position this Node's PDOM element |

## Reading values back

Every option above has a matching getter (e.g. `getAccessibleName()` / `accessibleName`, `getTagName()` / `tagName`), following the same `set`/`get` + ES5 accessor pattern as the rest of `Node`.

::: warning `accessibleName` supersedes the lower-level options for most use cases
`ParallelDOM` exposes both a higher-level API (`accessibleName`, `accessibleHelpText`, `accessibleParagraph`) and the lower-level primitives it's built from (`innerContent`, `ariaLabel`, `labelContent`, behavior functions). Mixing both on the same Node — e.g. setting `accessibleName` and also hand-writing `labelContent` — can conflict, since `accessibleName` may itself be implemented via one of these lower-level options through its behavior function. Reach for the higher-level options first; only touch the lower-level ones (or a custom `accessibleNameBehavior`) when a reusable component needs to render its name into a non-default sibling or attribute.
:::


========================================================================
Page: Path
URL: https://veillette.github.io/Almanach/api/scenery/path
Source: docs/api/scenery/path.md
Category: API | Tags: scenery, Path, Shape, fill, stroke | Status: verified
========================================================================

# Path

`Path` (from `scenerystack/scenery`) is a [`Node`](/api/scenery/node) that draws an arbitrary [kite `Shape`](/api/kite/shape) — the general-purpose way to render vector graphics that aren't a plain circle, rectangle, or line. `Circle`, `Rectangle`, and `Line` are all `Path` subclasses that build their `shape` for you from simpler parameters; reach for `Path` directly when you need a custom outline.

```ts
import { Path } from 'scenerystack/scenery';
import { Shape } from 'scenerystack/kite';

const triangle = new Shape()
  .moveTo( 0, 0 )
  .lineTo( 40, 0 )
  .lineTo( 20, -30 )
  .close();

const triangleNode = new Path( triangle, {
  fill: 'rebeccapurple',
  stroke: 'black',
  lineWidth: 2
} );
```

## Options

| Option | Effect |
| --- | --- |
| `shape` | The `Shape` (or SVG path-data string, or `null` for nothing drawn) to render — see `InputShape` |
| `shapeProperty` | Sets the shape via a `TReadOnlyProperty<Shape \| string \| null>` instead of a plain value |
| `boundsMethod` | How self bounds are computed: `'accurate'` (default, exact stroked bounds), `'unstroked'`, `'tightPadding'`, `'safePadding'`, or `'none'` |
| `fill` | Fill paint — a CSS color string, `Color`, `LinearGradient`, `RadialGradient`, or `Pattern` (from `Paintable`, shared with `Text`) |
| `stroke` | Stroke paint, same paint types as `fill` |
| `lineWidth` | Width of the stroked outline |
| `lineCap` / `lineJoin` / `miterLimit` | Stroke cap/join rendering, matching the Canvas 2D API |
| `lineDash` / `lineDashOffset` | Dash pattern for the stroke |

All `Path` subclasses also accept the full set of [`Node` options](/api/scenery/node) (`x`, `scale`, `visible`, `inputListeners`, `layoutOptions`, …).

::: warning Don't mutate a shared `Shape` in place
If a `Shape` isn't marked immutable (`shape.makeImmutable()`), `Path` attaches a listener so it re-renders when the shape mutates — which also means the `Path` keeps a reference to the `Shape` (and vice versa) for as long as that link is alive. Reusing one mutable `Shape` instance across many `Path`s can create surprising update coupling and memory retention; prefer building each `Path`'s shape independently, or call `path.dispose()` / set `path.shape = null` when finished with it.
:::


========================================================================
Page: Pattern
URL: https://veillette.github.io/Almanach/api/scenery/pattern-paint
Source: docs/api/scenery/pattern-paint.md
Category: API | Tags: scenery, Pattern, paint, fill, stroke, image | Status: verified
========================================================================

# Pattern (paint)

`Pattern` (from `scenerystack/scenery`) is a paint type — assignable to a `fill` or `stroke` alongside [`Color`](/api/scenery/color) and the gradient paints — that repeats an image tile in both directions to fill a shape, matching the CSS/Canvas notion of a repeating image pattern. This is unrelated to the "design pattern" write-ups in Almanach's [`patterns/`](/patterns/options-pattern) section (options pattern, enumeration pattern, etc.) — this `Pattern` is a rendering primitive, not a coding convention.

```ts
import { Pattern, Rectangle } from 'scenerystack/scenery';

const image = document.createElement( 'img' );
image.src = '/assets/checker-tile.png';

const pattern = new Pattern( image );
const tiledBackground = new Rectangle( 0, 0, 200, 100, { fill: pattern } );
```

## Constructor

`new Pattern( image )` takes a single `HTMLImageElement` that repeats (tiled, `'repeat'` in both x and y) to fill whatever shape it's used as `fill`/`stroke` on. Unlike [`Image`](/api/scenery/image), `Pattern` does not accept a URL string directly or manage loading — the `HTMLImageElement` should already have a `src` set (and typically already be loaded) before constructing the `Pattern`.

## Deriving a pattern from a Node instead of an image file

`NodePattern` (from `scenerystack/scenery`) is a `Pattern` subclass that rasterizes an arbitrary `Node` subtree into the backing image, for tiling a pattern built from scenery content (shapes, gradients, text) rather than a static asset:

```ts
import { NodePattern, Circle } from 'scenerystack/scenery';

const dot = new Circle( 4, { fill: 'black' } );
const dotPattern = new NodePattern( dot, 2, -8, -8, 16, 16 ); // node, resolution, x, y, width, height
```

::: warning `Pattern` does not load the image for you
Passing an `HTMLImageElement` whose `src` hasn't finished loading yet produces a blank or stale pattern — `Pattern`'s constructor synchronously builds a `CanvasPattern` from whatever image data is available at that moment. Wait for the image's `load` event (or use an already-loaded/cached image) before constructing the `Pattern`, rather than relying on it to update once loading completes.
:::


========================================================================
Page: Pointer, Mouse, Touch, and Pen
URL: https://veillette.github.io/Almanach/api/scenery/pointer-mouse-touch-pen
Source: docs/api/scenery/pointer-mouse-touch-pen.md
Category: API | Tags: scenery, Pointer, Mouse, Touch, Pen, input | Status: complete
========================================================================

# Pointer, Mouse, Touch, and Pen

`Pointer` (from `scenerystack/scenery`) is scenery's abstraction for a single input device: the one system mouse, one instance per active touch contact, or one instance per stylus. Every scenery input event carries a reference to the `Pointer` that triggered it via [`SceneryEvent.pointer`](/api/scenery/scenery-event), and listeners like [`FireListener`](/api/scenery/fire-listener) and [`DragListener`](/api/scenery/drag-listener) track pointers internally to know when a press is still "over" their target. `Pointer` itself is abstract — what you actually get is always a `Mouse`, `Touch`, or `Pen` instance (or the internal PDOM pointer used for keyboard/assistive-technology activation).

```ts
import { FireListener, Mouse } from 'scenerystack/scenery';

button.addInputListener( new FireListener( {
  press: ( event, listener ) => {
    // Special-case mouse-only behavior, e.g. restrict to the right button
    if ( event.pointer instanceof Mouse ) {
      console.log( 'pressed with the mouse' );
    }
  }
} ) );
```

## The `Pointer` base class

| Member | Meaning |
| --- | --- |
| `point` | Current position in the global (Display root) coordinate frame |
| `type` | `'mouse'` \| `'touch'` \| `'pen'` \| `'pdom'` — cheaper than an `instanceof` check when you just need the category |
| `trail` | The `Trail` this pointer is currently over, updated as it moves |
| `isDownProperty` | Whether the pointer is currently pressed |
| `attachedProperty` / `isAttached()` | Whether a "primary" listener has claimed this pointer (see `attach` on [`PressListener`](/api/scenery/fire-listener)) — used to prevent two listeners from responding to the same physical drag |
| `cursor` | An override cursor that takes precedence over the trail's CSS cursor, typically set for the duration of a drag |
| `isTouchLike()` | `true` for `Touch` and `Pen`, `false` for `Mouse` — useful when code should treat touch and pen the same way |
| `addInputListener( listener, attach? )` / `removeInputListener( listener )` | Attaches a listener directly to the pointer (rather than to a Node) — this is how `PressListener` tracks moves/releases after a press starts |
| `interruptAttached()` | Interrupts whichever listener is currently attached, if any |
| `interruptAll()` | Interrupts every listener on this pointer |
| `reserveForDrag()` / `reserveForKeyboardDrag()` | Marks the pointer with an `Intent` (`Intent.DRAG` or `Intent.KEYBOARD_DRAG`) so other listeners in the same dispatch can change behavior — `DragListener` calls `reserveForDrag()` automatically on a successful press |
| `hasIntent( intent )` | Checks whether a given `Intent` is currently set |

## `Mouse`, `Touch`, and `Pen`

| Class | `type` | Notes |
| --- | --- | --- |
| `Mouse` | `'mouse'` | A singleton per `Display` — there's only ever one. Adds `leftDown`/`middleDown`/`rightDown` (deprecated in favor of DOM button tracking), plus `wheelDelta`/`wheelDeltaMode` for wheel events |
| `Touch` | `'touch'` | One instance per active touch contact, identified by `id`. `isTouchLike()` returns `true` |
| `Pen` | `'pen'` | One instance per active stylus contact, identified by `id`. Also carries tilt/pressure information from the underlying `PointerEvent`. `isTouchLike()` returns `true` |

Because touches come and go as fingers land and lift, code that needs to distinguish "the mouse" from "some touch" should check `pointer.type === 'mouse'` or `pointer instanceof Mouse`, not assume there's exactly one pointer active at a time — a multi-touch interaction can have several `Touch` pointers live simultaneously.

::: tip Prefer `mouseButton` and `pressCursor` over checking `Mouse` yourself
Most pointer-type-specific behavior is already exposed as options on the listeners themselves — [`PressListener`](/api/scenery/fire-listener)'s `mouseButton` restricts which mouse button starts a press (any touch/pen still works), and `pressCursor` only visibly applies to `Mouse` anyway (touch/pen have no persistent cursor). Reach for `instanceof Mouse` only when you need behavior no listener option already covers.
:::


========================================================================
Page: PressListener (direct usage)
URL: https://veillette.github.io/Almanach/api/scenery/press-listener
Source: docs/api/scenery/press-listener.md
Category: API | Tags: scenery, PressListener, DragListener, FireListener, input, accessibility, PDOM | Status: complete
========================================================================

# PressListener (direct usage)

`PressListener` (from `scenerystack/scenery`) is the shared base class documented alongside its most common subclass in [PressListener and FireListener](/api/scenery/fire-listener) — that page covers the options and read-only Properties both classes share. This page is for the case [PressListener and FireListener](/api/scenery/fire-listener) calls out explicitly: reaching for `PressListener` **directly**, without `FireListener`'s fire-on-release semantics or `DragListener`'s coordinate tracking, because the interaction is something else — a press-and-hold tool, a custom multi-pointer gesture, or a Node whose "pressed" visual state needs to track PDOM (keyboard/switch-device) focus as well as pointer input.

```ts
import { Node, Circle, PressListener } from 'scenerystack/scenery';
import { Tandem } from 'scenerystack/tandem';

const magnifier = new Node( { children: [ new Circle( 20, { fill: 'lightblue' } ) ], cursor: 'pointer' } );

const magnifyListener = new PressListener( {
  press: () => magnifier.setScaleMagnitude( 1.5 ),
  release: () => magnifier.setScaleMagnitude( 1 ),
  canStartPress: () => !magnifier.isDisposed,
  tandem: Tandem.OPT_OUT
} );

magnifier.addInputListener( magnifyListener );

// Drive a highlight off state that also accounts for keyboard focus, not just pointer hover:
magnifyListener.isOverOrFocusedProperty.link( overOrFocused => {
  magnifier.opacity = overOrFocused ? 1 : 0.8;
});
```

`PressListener` extends axon's `EnabledComponent`, so every instance also has a standard `enabledProperty`/`enabled` — disabling the listener prevents new presses from starting without needing a separate guard in `canStartPress`.

## PDOM- and focus-aware state

Beyond the `isPressedProperty`/`isOverProperty`/`isHoveringProperty`/`isHighlightedProperty` covered in [PressListener and FireListener](/api/scenery/fire-listener), `PressListener` tracks additional state specifically so a Node's "looks interactive" visuals stay correct for keyboard and switch-device users, not just mouse/touch:

| Property | Meaning |
| --- | --- |
| `isFocusedProperty` | Whether this listener's Node currently has PDOM focus |
| `isOverOrFocusedProperty` | `isOverProperty \|\| ` (focused **and** the Display is currently showing focus highlights) — the right signal for "should this look highlighted," including keyboard users |
| `pdomClickingProperty` | `true` while a press is being processed from a PDOM `click` event (as opposed to real pointer down/up) — needed because some assistive devices send a single `click` rather than separate down/up |
| `looksPressedProperty` | `pdomClickingProperty \|\| isPressedProperty` — whether the button should render as pressed, accounting for the fact that a PDOM click fires the press/release callbacks immediately but should still *look* pressed briefly |
| `overPointers` | An `ObservableArray<Pointer>` of every pointer currently over the listener's Node |

`a11yLooksPressedInterval` (default `100` ms) controls how long `looksPressedProperty` stays `true` after a PDOM click, since the press and release callbacks both fire essentially at once for that input source.

## Methods beyond press/release/drag

| Method | Effect |
| --- | --- |
| `canPress( event )` | Whether a press could currently start for the given event (checks button/attachment/`canStartPress`) |
| `canClick()` | Whether a programmatic `click()` could currently succeed |
| `click( event, callback? )` | Simulates a full press-then-release from a single PDOM click event; used internally by [`FireListener`](/api/scenery/fire-listener) and accessible-input handling |
| `focus( event )` / `blur()` | Called by scenery's focus system to update `isFocusedProperty`; not something you typically call directly |
| `step()` | Advances any pending collapsed drag event (see `collapseDragEvents`); called automatically if the listener is registered appropriately |
| `setCreatePanTargetBounds( fn )` | Supplies a callback returning the `Bounds2` that [`AnimatedPanZoomListener`](/api/scenery/animated-pan-zoom-listener) should keep in view while this listener is pressed — useful when the pressed/dragged region differs from the listener's Node bounds |

## `useInputListenerCursor`

`useInputListenerCursor: true` makes any Node this listener is attached to adopt `pressCursor` as its effective cursor whenever that Node's own `cursor` is `null` — a small convenience so you don't have to set `cursor: 'pointer'` on the Node separately from configuring the listener's `pressCursor`.

::: tip Reach for PressListener directly when the interaction isn't "fire" or "drag"
If the shape of the interaction is genuinely custom — press-and-hold-to-charge, multi-touch gesture recognition, or anything that needs `isOverOrFocusedProperty`/`overPointers` — build on `PressListener` directly rather than working around `FireListener`'s fire semantics or `DragListener`'s coordinate machinery. Both of those subclasses exist specifically to save you from reimplementing this state for the two most common cases.
:::

::: warning `tandem` still defaults to required
Like `FireListener` and `DragListener`, a directly-constructed `PressListener` defaults `tandem` to `Tandem.REQUIRED` and defaults `phetioReadOnly: true` on its internal press/release `PhetioAction`s. Pass `Tandem.OPT_OUT` for non-instrumented sim code, as shown above.
:::


========================================================================
Page: PressListener and FireListener
URL: https://veillette.github.io/Almanach/api/scenery/fire-listener
Source: docs/api/scenery/fire-listener.md
Category: API | Tags: scenery, FireListener, PressListener, input | Status: verified
========================================================================

# PressListener and FireListener

`PressListener` and `FireListener` (both from `scenerystack/scenery`) are the input listeners that give a `Node` press/click behavior. `PressListener` is the general-purpose base — it tracks whether a pointer is pressed/hovering/focused and exposes `press`/`release`/`drag` callbacks — and is also the shared base class for `DragListener`. `FireListener` adds one thing on top: a `fire()` callback invoked on a complete press-then-release (or on down, if `fireOnDown` is set), which is exactly the "button" interaction pattern. Attach either as an [`inputListeners`](/api/scenery/node) entry on a `Node`, and make sure the owning [`Display`](/api/scenery/display) has called `initializeEvents()`.

```ts
import { Circle, FireListener } from 'scenerystack/scenery';
import { Tandem } from 'scenerystack/tandem';

const button = new Circle( 25, {
  fill: 'dodgerblue',
  cursor: 'pointer'
} );

button.addInputListener( new FireListener( {
  fire: () => console.log( 'fired!' ),
  tandem: Tandem.REQUIRED
} ) );
```

## `FireListener` options

`FireListenerOptions` adds these to everything `PressListener` accepts:

| Option | Default | Effect |
| --- | --- | --- |
| `fire` | no-op | Called as `fire( event )` when the button fires |
| `fireOnDown` | `false` | If `true`, fires on press instead of on release-while-hovering |
| `fireOnHold` | `false` | Enables fire-on-hold (repeated firing while held) |
| `fireOnHoldDelay` | `400` | Milliseconds held before fire-on-hold starts repeating |
| `fireOnHoldInterval` | `100` | Milliseconds between repeated fires once fire-on-hold is active |

## `PressListener` options

| Option | Default | Effect |
| --- | --- | --- |
| `press` | no-op | Called as `press( event, listener )` when a press starts |
| `release` | no-op | Called as `release( event \| null, listener )` when released, interrupted, or canceled |
| `drag` | no-op | Called as `drag( event, listener )` on pointer move while pressed |
| `targetNode` | `null` | Overrides the Node used to compute the pressed `Trail`/coordinate frame, when it differs from the Node the listener is attached to |
| `attach` | `true` | Whether this listener attaches itself to the pointer (blocking other `attach: true` listeners while pressed) |
| `mouseButton` | `0` (left) | Restricts which mouse button starts a press; any touch/pen still works |
| `pressCursor` | `'pointer'` | Cursor to force while pressed |
| `canStartPress` | always `true` | Predicate checked before allowing a press to start |
| `collapseDragEvents` | `false` | Coalesces multiple drag events between frames into one `drag()` call |

## Useful read-only properties

| Property | Meaning |
| --- | --- |
| `isPressedProperty` | Whether the listener is currently pressed |
| `isOverProperty` | Whether a pointer is currently over the associated Node |
| `isHoveringProperty` | `true` while a pointer that could fire this listener is over it (pressed-and-over, or unpressed-and-over) |
| `isHighlightedProperty` | `isPressed || isHovering` — the usual signal for "should this look highlighted" |
| `pointer` / `pressedTrail` | The active `Pointer` and press `Trail`, or `null` when not pressed |
| `interrupted` | Whether the most recent release was due to an interruption rather than a normal up/click |

## Methods shared by both

| Method | Effect |
| --- | --- |
| `press( event, targetNode?, callback? )` | Programmatically attempts to start a press; returns whether it succeeded |
| `release( event?, callback? )` | Programmatically ends the press |
| `interrupt()` | Cancels an in-progress press without treating it as a normal release (no `fire()` on `FireListener`) |
| `dispose()` | Releases the listener's `Property`/`Emitter` resources |

`FireListener` additionally exposes `fire( event )` (invoke the fire callback directly) and `click( event, callback? )` (used by PDOM/accessibility interactions to press-and-release in one step).

::: tip Use `FireListener` for buttons, `PressListener`/`DragListener` for everything else
If you just need "clicked," reach for `FireListener` — it already integrates with keyboard/PDOM activation. If you need to track pointer movement while pressed (dragging a `Node` around), use `PressListener` directly or [`DragListener`](/guides/scenery-input), which builds on the same `press`/`release`/`drag` shape.
:::

::: warning `tandem` defaults to required
Both listeners default `tandem` to `Tandem.REQUIRED` (for PhET-iO instrumentation of user actions). If your project isn't PhET-iO-instrumented, pass `Tandem.OPT_OUT`, or supply a real tandem as shown above — leaving the default in place will throw if PhET-iO validation is active.
:::


========================================================================
Page: RadialGradient
URL: https://veillette.github.io/Almanach/api/scenery/radial-gradient
Source: docs/api/scenery/radial-gradient.md
Category: API | Tags: scenery, RadialGradient, gradient, paint, fill, stroke | Status: verified
========================================================================

# RadialGradient

`RadialGradient` (from `scenerystack/scenery`) is a paint type — assignable to a Node's `fill` or `stroke` just like [`Color`](/api/scenery/color) or [`LinearGradient`](/api/scenery/linear-gradient) — that renders a gradient between two circles (a start circle at ratio 0 and an end circle at ratio 1), matching the CSS/SVG/Canvas notion of a radial gradient. It extends the same abstract `Gradient` base class `LinearGradient` does, so color stops work identically.

```ts
import { Circle, RadialGradient } from 'scenerystack/scenery';

// Start circle: center (0,0), radius 0 (a point). End circle: center (0,0), radius 20.
const gradient = new RadialGradient( 0, 0, 0, 0, 0, 20 )
  .addColorStop( 0, 'white' )
  .addColorStop( 1, 'steelblue' );

const sphere = new Circle( 20, { fill: gradient } );
```

## Constructor

`new RadialGradient( x0, y0, r0, x1, y1, r1 )` — the start circle's center and radius (ratio 0), then the end circle's center and radius (ratio 1), all in the Node's local coordinate frame. A common "spherical" look uses the same center for both circles with `r0` near `0` and `r1` matching the shape's radius, as above; offsetting the start circle's center instead produces a highlight-style radial gradient.

## Color stops

`addColorStop( ratio, color )` is inherited from the same `Gradient` base class [`LinearGradient`](/api/scenery/linear-gradient) uses — stops must be added in non-decreasing `ratio` order, and `color` accepts `null`, a CSS string, a [`Color`](/api/scenery/color), or a `Property` resolving to one of those.

::: tip Safari gets a workaround for coincident-center radial gradients
Scenery detects Safari and nudges both circles' centers to their midpoint internally to work around a browser gradient-rendering bug — you don't need to do anything for this, but it's worth knowing if a `RadialGradient`'s rendered center looks *slightly* off from the coordinates you passed specifically on Safari; the visual difference is designed to be imperceptible.
:::


========================================================================
Page: Rectangle
URL: https://veillette.github.io/Almanach/api/scenery/rectangle
Source: docs/api/scenery/rectangle.md
Category: API | Tags: scenery, Rectangle, Path | Status: verified
========================================================================

# Rectangle

`Rectangle` (from `scenerystack/scenery`) is a [`Path`](/api/scenery/path) subclass that builds its own rectangular (optionally rounded) `Shape` from `x`/`y`/`width`/`height` parameters, so you don't need to construct a kite `Shape` by hand for plain or rounded rectangles.

```ts
import { Rectangle } from 'scenerystack/scenery';
import { Bounds2 } from 'scenerystack/dot';

// new Rectangle( x, y, width, height, options )
const panel = new Rectangle( 0, 0, 200, 100, {
  fill: '#eee',
  stroke: 'black',
  lineWidth: 1
} );

// new Rectangle( x, y, width, height, cornerXRadius, cornerYRadius, options )
const roundedPanel = new Rectangle( 0, 0, 200, 100, 8, 8, { fill: '#eee' } );

// new Rectangle( bounds, options )
const fromBounds = new Rectangle( new Bounds2( 0, 0, 200, 100 ), { fill: 'white' } );

panel.rectWidth = 220; // resize after construction
```

## Constructor overloads

| Signature | Use case |
| --- | --- |
| `new Rectangle( options )` | Fully options-driven |
| `new Rectangle( bounds, options? )` | From a `Bounds2` |
| `new Rectangle( bounds, cornerXRadius, cornerYRadius, options? )` | From a `Bounds2` with rounded corners |
| `new Rectangle( x, y, width, height, options? )` | Explicit geometry |
| `new Rectangle( x, y, width, height, cornerXRadius, cornerYRadius, options? )` | Explicit geometry, rounded corners |

## Options

| Option | Effect |
| --- | --- |
| `rectBounds` | Sets `x`/`y`/`width`/`height` at once from a `Bounds2` |
| `rectSize` | Sets `width`/`height` at once from a `Dimension2` |
| `rectX`, `rectY` | Top-left corner position |
| `rectWidth`, `rectHeight` | Dimensions |
| `cornerRadius` | Sets both `cornerXRadius` and `cornerYRadius` together |
| `cornerXRadius`, `cornerYRadius` | Independent horizontal/vertical radii for elliptical rounded corners |

`Rectangle` also accepts every [`Path` option](/api/scenery/path) (`fill`, `stroke`, `lineWidth`, …) except `shape`/`shapeProperty`, plus the full set of [`Node` options](/api/scenery/node) — including layout sizing, since `Rectangle` mixes in `Sizable` and can be given a `preferredWidth`/`preferredHeight` by a parent layout container.

::: tip Resizing without rebuilding the shape
Prefer `rectWidth`/`rectHeight`/`rectX`/`rectY`/`rectBounds` over recreating the `Rectangle` or setting `.shape` directly — these setters update the internal shape efficiently and are what layout containers use when they resize a `Rectangle` child.
:::


========================================================================
Page: RichDragListener
URL: https://veillette.github.io/Almanach/api/scenery/rich-drag-listener
Source: docs/api/scenery/rich-drag-listener.md
Category: API | Tags: scenery, RichDragListener, input, drag, keyboard, accessibility | Status: verified
========================================================================

# RichDragListener

`RichDragListener` (from `scenerystack/scenery`) is not a subclass of `DragListener` — it *composes* one internal `DragListener` and one internal `KeyboardDragListener`, forwarding every scenery input-listener callback (`down`, `up`, `keydown`, `focus`, …) to whichever of the two applies, and implements `TInputListener` so it can be attached to a Node exactly like either listener alone. It exists so a draggable object gets pointer *and* keyboard support from one declaration instead of wiring up both listeners and their shared options by hand — see [Drag Listeners](/patterns/drag-listeners) for why it's the recommended default for new draggable code, with plain `DragListener`/`KeyboardDragListener` reserved for cases needing one modality only or finer control.

```ts
import { Node, RichDragListener } from 'scenerystack/scenery';

const bodyNode = new Node( { tagName: 'div', focusable: true, cursor: 'pointer' } );

bodyNode.addInputListener( new RichDragListener( {
  positionProperty: body.positionProperty,
  transform: modelViewTransform,
  dragBoundsProperty: model.dragBoundsProperty,
  start: () => body.userControlledProperty.set( true ),
  end: () => body.userControlledProperty.set( false ),
  keyboardDragListenerOptions: {
    dragSpeed: 150
  }
} ) );
```

## Options

`RichDragListenerOptions` shares the common drag options (`positionProperty`, `transform`, `dragBoundsProperty`, `mapPosition`, `translateNode`, `start`/`drag`/`end`) applied to *both* internal listeners, plus:

| Option | Default | Effect |
| --- | --- | --- |
| `dragListenerOptions` | `{}` | Additional/overriding options passed only to the internal `DragListener` (e.g. `allowTouchSnag`, `mouseButton`) |
| `keyboardDragListenerOptions` | `{}` | Additional/overriding options passed only to the internal `KeyboardDragListener` (e.g. `dragSpeed`, `keyboardDragDirection`) |
| `tandem` | `Tandem.REQUIRED` | Split internally into `tandem.createTandem('dragListener')` / `'keyboardDragListener'` for PhET-iO |

`start`/`drag`/`end` given directly on `RichDragListener` fire for *either* input type; listener-specific callbacks in `dragListenerOptions`/`keyboardDragListenerOptions` fire in addition to (not instead of) the shared ones.

## Public state and methods

| Member | Meaning |
| --- | --- |
| `dragListener` | The internal `DragListener` instance — public, so you can inspect/reuse it directly |
| `keyboardDragListener` | The internal `KeyboardDragListener` instance |
| `isPressedProperty` | `true` if either internal listener is pressed |
| `interrupt()` | Interrupts both internal listeners |
| `dispose()` | Disposes both internal listeners and this listener's own Properties |

::: tip Starting one input type interrupts the other
When the pointer `DragListener` starts, it interrupts the `KeyboardDragListener` (and vice versa) — the two are mutually exclusive at any instant, so a drag can't be simultaneously driven by a mouse and the keyboard. This is handled internally; you don't need to manage it in your `start`/`end` callbacks.
:::


========================================================================
Page: RichText
URL: https://veillette.github.io/Almanach/api/scenery/rich-text
Source: docs/api/scenery/rich-text.md
Category: API | Tags: scenery, RichText, markup, links | Status: verified
========================================================================

# RichText

`RichText` (from `scenerystack/scenery`) renders a string containing a constrained, security-conscious subset of HTML-like markup, splitting it internally into multiple [`Text`](/api/scenery/text) children. Use it when a single string needs mixed styling — bold/italic runs, sub/superscripts, links, line breaks — that plain `Text` can't express. Malformed markup is not accepted, and HTML entities in the content must be escaped.

```ts
import { RichText } from 'scenerystack/scenery';
import { PhetFont } from 'scenerystack/scenery-phet';

const description = new RichText(
  'RichText supports <b>bold</b>, <i>italic</i>, and H<sub>2</sub>O-style subscripts.',
  { font: new PhetFont( 16 ), fill: 'black' }
);

const withLink = new RichText(
  'See <a href="{{phetWebsite}}">our website</a> for more.',
  {
    links: {
      phetWebsite: 'https://phet.colorado.edu'
    }
  }
);
```

## Supported markup

`<b>`/`<strong>`, `<i>`/`<em>`, `<sub>`, `<sup>`, `<u>`, `<s>`, `<br>`, `<span style="color: ...; font-size: ...; font-family: ...;">`, `<span dir="ltr"/"rtl">`, `<a href="...">` links, and `<node id="...">` for embedding an arbitrary `Node` inline.

## Options

| Option | Effect |
| --- | --- |
| `string` / `stringProperty` | The markup string to render, same as `Text` |
| `font`, `fill`, `stroke`, `lineWidth` | Base styling applied to unmarked text (per-tag colors override `fill` locally) |
| `links` | Either `true` (embed `href`s directly from the markup) or a `Record<string, string \| (() => void)>` mapping placeholder names to real URLs/callbacks — the default (safer) way to allow links |
| `linkFill` | Fill color used specifically for link text |
| `linkEventsHandled` | Whether clicking a link calls `event.handle()`, stopping propagation |
| `nodes` | A `Record<string, Node>` of Nodes to splice in for `<node id="...">` tags |
| `tags` | A `Record<string, (node: Node) => Node>` for custom wrapping tags, e.g. `<blur>...</blur>` |
| `align` | `'left'`, `'center'`, or `'right'` alignment across wrapped lines |
| `lineWrap` | Maximum line width (in local coordinates) before wrapping; `null` disables wrapping |
| `leading` | Extra vertical spacing between wrapped lines |
| `subScale`, `subXSpacing`, `subYOffset`, `supScale`, `supXSpacing`, `supYOffset` | Fine-tune subscript/superscript sizing and placement |
| `underlineLineWidth`, `underlineHeightScale`, `strikethroughLineWidth`, `strikethroughHeightScale` | Fine-tune `<u>`/`<s>` rendering |

`RichText` also accepts the full set of [`Node` options](/api/scenery/node).

::: warning Links default to being ignored, not embedded
Passing a raw `<a href="https://example.com">` without a matching `links` map entry causes that link to be silently ignored — this is a deliberate XSS guard, since `RichText` content often comes from translated strings. To use literal `href`s straight from the markup, pass `links: true` explicitly; to remap placeholders to safe destinations, use the `links: { placeholder: url }` form shown above.
:::


========================================================================
Page: SceneryEvent
URL: https://veillette.github.io/Almanach/api/scenery/scenery-event
Source: docs/api/scenery/scenery-event.md
Category: API | Tags: scenery, SceneryEvent, input, Trail | Status: complete
========================================================================

# SceneryEvent

`SceneryEvent<DOMEvent>` (from `scenerystack/scenery`) is the object every scenery input listener callback receives — `press`, `release`, `drag`, `fire`, and the raw listener methods (`down`, `up`, `move`, …) documented on [`PressListener`/`FireListener`](/api/scenery/fire-listener) and [`DragListener`](/api/scenery/drag-listener) all take one. It wraps the native browser event together with scenery-specific context: which [`Pointer`](/api/scenery/pointer-mouse-touch-pen) triggered it, and the [`Trail`](/api/scenery/trail) of Nodes it was dispatched through. A single DOM `TouchEvent` can carry multiple touch points, so don't assume a `SceneryEvent`'s `domEvent` is exclusive to that event — the same DOM event object can back multiple `SceneryEvent`s.

```ts
import { FireListener } from 'scenerystack/scenery';

button.addInputListener( new FireListener( {
  fire: event => {
    console.log( 'fired by', event.pointer.type );      // 'mouse' | 'touch' | 'pen' | 'pdom'
    console.log( 'hit trail', event.trail.toString() );
    console.log( 'leaf node', event.target === event.trail.lastNode() ); // true
  }
} ) );
```

## Properties

| Property | Meaning |
| --- | --- |
| `trail` | Root-to-leaf `Trail` of Nodes hit by this event |
| `type` | The scenery event type string that was fired, e.g. `'down'`, `'move'` |
| `pointer` | The [`Pointer`](/api/scenery/pointer-mouse-touch-pen) (`Mouse`/`Touch`/`Pen`/PDOM pointer) that triggered this event |
| `domEvent` | The raw underlying DOM event (`MouseEvent`, `TouchEvent`, `PointerEvent`, `KeyboardEvent`, …), or `null` |
| `context` | The `EventContext` scenery captured around the DOM event (environment info at dispatch time) |
| `activeElement` | `document.activeElement` at the time the event fired |
| `currentTarget` | The Node the listener was attached to; `null` when the event is being fired directly on a `Pointer` rather than dispatched through the scene graph |
| `target` | The leaf-most Node in `trail` — the actual Node that was hit |
| `isPrimary` | `true` for touches, and for the mouse only when it's the primary (left) button |
| `handled` / `aborted` | Set by `handle()`/`abort()`, see below |

## Methods

| Method | Effect |
| --- | --- |
| `handle()` | Marks the event `handled`, signaling it shouldn't bubble further — analogous to DOM `stopPropagation()`, but named differently because it does **not** call the underlying DOM method |
| `abort()` | Marks the event `aborted`, so no further listeners see it at all (stronger than `handle()`) |
| `isFromPDOM()` | `true` if the event originated from the Parallel DOM (keyboard/assistive-technology activation) rather than a physical pointer |
| `canStartPress()` | `true` if a fresh, unattached `PressListener` could start a press with this event — ignores non-left mouse buttons and pointers already attached to another listener |

::: tip `handle()` doesn't touch the native DOM event
Calling `event.handle()` stops *scenery's* internal dispatch from continuing to bubble the `SceneryEvent` up the trail — it deliberately does not call `stopPropagation()` on the underlying DOM event, since other (non-scenery) listeners on the page may still need to see it. If you need to prevent default browser behavior too, call `event.domEvent?.preventDefault()` yourself.
:::


========================================================================
Page: Sizable, WidthSizable, and HeightSizable
URL: https://veillette.github.io/Almanach/api/scenery/sizable-mixins
Source: docs/api/scenery/sizable-mixins.md
Category: API | Tags: scenery, Sizable, WidthSizable, HeightSizable, layout | Status: complete
========================================================================

# Sizable, WidthSizable, and HeightSizable

By default, a `Node`'s size is whatever its content makes it — layout containers like [`FlowBox`](/api/scenery/flow-box) and [`GridBox`](/api/scenery/grid-box) can position such a Node, but can't make it *fill* available space, because it has no way to be told "be this wide." `WidthSizable`, `HeightSizable`, and `Sizable` (all from `scenerystack/scenery`) are mixin traits that add exactly that capability: a settable `preferredWidth`/`preferredHeight` the layout container writes to, and a `minimumWidth`/`minimumHeight` the component reports back so the container knows how small it can be shrunk. `Sizable` is just `WidthSizable` and `HeightSizable` combined, with `Dimension2`-based convenience accessors on top.

```ts
import { Node, Rectangle, Sizable, HBox } from 'scenerystack/scenery';

class FillBar extends Sizable( Node ) {
  private readonly background: Rectangle;

  public constructor() {
    super();
    this.background = new Rectangle( 0, 0, 0, 20, { fill: 'teal' } );
    this.addChild( this.background );

    // Mutate sizable options AFTER the super() call, in a later mutate() — see the warning below.
    this.mutate( { minimumWidth: 20 } );

    this.preferredWidthProperty.link( preferredWidth => {
      this.background.rectWidth = preferredWidth ?? this.minimumWidth ?? 0;
    } );
  }
}

const bar = new FillBar();
bar.layoutOptions = { stretch: true, grow: 1 };

const row = new HBox( { children: [ bar ], stretch: true } );
```

Once `bar` is `WidthSizable`, `HBox`/`FlowBox` recognizes it as resizable and — combined with `stretch`/`grow` [layout options](/api/scenery/flow-box) — will set its `preferredWidth` to fill the row, instead of leaving it at its natural (zero, in this example) content width.

## Options (per trait)

| Option | Default | Effect |
| --- | --- | --- |
| `preferredWidth` / `preferredHeight` | `null` | Set by the parent layout container (in the parent coordinate frame); the component should try to make `node.width`/`node.height` match this |
| `minimumWidth` / `minimumHeight` | `null` | Set by the component itself, to report the smallest size it can render acceptably; usually derived from `localMinimumWidth`/`localMinimumHeight` |
| `localPreferredWidth` / `localPreferredHeight` | `null` | The same preferred size, in the Node's own local coordinate frame — kept in sync with the parent-frame version automatically as the transform changes |
| `localMinimumWidth` / `localMinimumHeight` | `null` | The local-frame minimum size — this is usually the one a resizable component sets directly |
| `widthSizable` / `heightSizable` | `true` | Whether this Node currently accepts a preferred size from its layout container at all; set `false` to opt a specific instance out |

`Sizable` adds `preferredSize`/`minimumSize`/`localPreferredSize`/`localMinimumSize` as `Dimension2`-valued get/set pairs over both dimensions at once, plus a single `sizable` boolean covering both `widthSizable` and `heightSizable`.

## Checking whether an arbitrary Node participates

`scenerystack/scenery` also exports type-check helpers for code that receives an arbitrary `Node` and needs to know whether it supports sizing before touching these properties:

| Helper | Checks |
| --- | --- |
| `isWidthSizable( node )` / `isHeightSizable( node )` / `isSizable( node )` | Whether a Node's *current* `widthSizable`/`heightSizable`/`sizable` value is `true` |
| `extendsWidthSizable( node )` / `extendsHeightSizable( node )` / `extendsSizable( node )` | Whether a Node was constructed *with* the trait at all, regardless of its current boolean value |

::: warning Set sizable options from a later `mutate()`, not the constructor options passed to `super()`
The properties these mixins add (`preferredWidthProperty`, etc.) aren't initialized until partway through the mixed-in constructor. If you pass `widthSizable`-related options directly into the `Node` options object handed to `super()` in your subclass constructor, they'll fail — assertions catch this, but it's easy to trip over. Apply them via a follow-up `this.mutate( { ... } )` call after `super()` returns, as in the example above.
:::


========================================================================
Page: Spacer
URL: https://veillette.github.io/Almanach/api/scenery/spacer
Source: docs/api/scenery/spacer.md
Category: API | Tags: scenery, Spacer, layout, bounds | Status: verified
========================================================================

# Spacer

`Spacer` (from `scenerystack/scenery`) is a [`Node`](/api/scenery/node) that draws nothing and can never have children — it exists purely to occupy a fixed rectangular region of `[0, width] x [0, height]` in its own local coordinate frame, so a layout container that sees its `bounds` treats that region as reserved space. It's the scenery equivalent of a CSS empty spacer `<div>`: use it inside a [`FlowBox`](/api/scenery/flow-box)/[`GridBox`](/api/scenery/grid-box) to force a gap that isn't uniform `spacing`, or standalone to pad out a fixed layout.

```ts
import { Spacer, HBox, Circle } from 'scenerystack/scenery';

const row = new HBox( {
  spacing: 4,
  children: [
    new Circle( 10, { fill: 'crimson' } ),
    new Spacer( 40, 1 ),   // a 40-wide gap wider than `spacing` alone would give
    new Circle( 10, { fill: 'teal' } )
  ]
} );
```

## Constructor

`new Spacer( width, height, options? )` — `width` and `height` must both be finite numbers; they set `localBounds` to `Bounds2( 0, 0, width, height )` before any `options` (standard [`Node`](/api/scenery/node) options like `x`/`y`/`layoutOptions`) are applied via `mutate()`.

`SpacerOptions` is just `NodeOptions` — `Spacer` adds no options of its own beyond the `width`/`height` constructor arguments.

## `HStrut` and `VStrut`

`HStrut` and `VStrut` (also from `scenerystack/scenery`) are thin `Spacer` subclasses for the common one-dimensional case: `new HStrut( width, options? )` is exactly `new Spacer( width, 0, options )`, and `new VStrut( height, options? )` is exactly `new Spacer( 0, height, options )`. Reach for these when you only need to reserve space along one axis — e.g. a horizontal gap inside a [`VBox`](/api/scenery/v-box) — since the intent reads more clearly than a `Spacer` with an explicit `0`.

::: warning A Spacer can never have children
`Spacer` is built with scenery's `Leaf` mixin, which throws if you try to `addChild()` to it — it is always and only a leaf in the scene graph. If you need an invisible *container* (something that can hold other Nodes but isn't itself drawn), use a plain [`Node`](/api/scenery/node) with no visible content instead of `Spacer`.
:::


========================================================================
Page: Sprites, Sprite, SpriteImage, and SpriteSheet
URL: https://veillette.github.io/Almanach/api/scenery/sprites
Source: docs/api/scenery/sprites.md
Category: API | Tags: scenery, Sprites, Sprite, SpriteImage, SpriteSheet, SpriteInstance, performance, particles, webgl, canvas | Status: complete
========================================================================

# Sprites, Sprite, SpriteImage, and SpriteSheet

`Sprites` (from `scenerystack/scenery`) is a single `Node` that draws a large number of image instances — hundreds or thousands of particles, molecules, coins, whatever — with far less overhead than giving each instance its own [`Image`](/api/scenery/image) `Node`. Where an ordinary scene graph pays a per-Node cost for transforms, bounds, and picking, `Sprites` collapses an entire population of same-looking-but-differently-placed images into one `Node` and one WebGL/Canvas draw call, driven by a plain array you mutate directly rather than a tree of children.

The pieces work together like this: a `Sprite` wraps a `SpriteImage` (the actual pixel content plus a center offset); a `SpriteInstance` is a lightweight, poolable record of "this sprite, at this matrix, with this alpha"; and `Sprites` is the `Node` that takes an array of `Sprite`s and an array of `SpriteInstance`s and paints them all. `SpriteSheet` is a lower-level utility (a single Canvas/WebGL texture packing multiple source images together) that most sim code won't touch directly — it exists so custom WebGL drawables can batch several distinct images into one texture.

```ts
import { Sprites, Sprite, SpriteImage, SpriteInstance, SpriteInstanceTransformType } from 'scenerystack/scenery';
import { Vector2 } from 'scenerystack/dot';
import { Bounds2 } from 'scenerystack/dot';

// Build one Sprite from a loaded image, offset so (0,0) is the image's center.
const particleImage: HTMLImageElement = document.createElement( 'img' ); // in practice, an already-loaded image
const particleSpriteImage = new SpriteImage( particleImage, new Vector2( particleImage.width / 2, particleImage.height / 2 ) );
const particleSprite = new Sprite( particleSpriteImage );

// Create (or pool-fetch) one SpriteInstance per on-screen particle.
const instances: SpriteInstance[] = [];
for ( let i = 0; i < 500; i++ ) {
  const instance = SpriteInstance.pool.fetch();
  instance.sprite = particleSprite;
  instance.transformType = SpriteInstanceTransformType.TRANSLATION;
  instance.matrix.setToTranslation( Math.random() * 400, Math.random() * 400 );
  instances.push( instance );
}

const spritesNode = new Sprites( {
  sprites: [ particleSprite ],
  spriteInstances: instances,
  canvasBounds: new Bounds2( 0, 0, 400, 400 )
} );

// After mutating positions in the model's step function:
instances.forEach( instance => instance.matrix.setToTranslation( /* new x */ 0, /* new y */ 0 ) );
spritesNode.invalidatePaint(); // tell Sprites to repaint with the updated matrices
```

## `Sprite`

`new Sprite( spriteImage: SpriteImage )` wraps a `SpriteImage` in a mutable `imageProperty`, so the same `Sprite` object referenced by many `SpriteInstance`s can have its underlying image swapped (e.g. regenerated at a different resolution) without touching every instance. `Sprite` exposes `getShape()` and `containsPoint( point )`, both delegating to the current `SpriteImage`.

## `SpriteImage`

`new SpriteImage( image, offset: Vector2, providedOptions? )` — `image` is an `HTMLImageElement` or `HTMLCanvasElement` (or a `TReadOnlyProperty` of one), and `offset` is the 2D point (in image pixels, top-left origin) that should be treated as the sprite's local "center" — this is what a `SpriteInstance`'s matrix positions.

| Option | Default | Effect |
| --- | --- | --- |
| `hitTestPixels` | `false` | If `true`, hit-testing uses the actual non-transparent pixels instead of the full rectangular bounds |
| `pickable` | `true` | Whether this image participates in hit-testing at all |

## `SpriteInstance`

`SpriteInstance` is deliberately a bare data container, not something you subclass or configure via options — instances are meant to be created via `SpriteInstance.pool.fetch()` and mutated directly for performance, then returned with `freeToPool()` when no longer needed.

| Field | Meaning |
| --- | --- |
| `sprite` | The `Sprite` to display for this instance (`null` means nothing is drawn) |
| `matrix` | A `Matrix3` positioning this instance; mutate it directly rather than replacing it |
| `transformType` | A `SpriteInstanceTransformType` telling `Sprites` how much of `matrix` to trust — see below |
| `alpha` | Per-instance opacity, `0` to `1` |

`SpriteInstanceTransformType` has four values, each a performance/flexibility tradeoff: `TRANSLATION` (fastest — only `matrix`'s translation is used), `TRANSLATION_AND_SCALE`, `TRANSLATION_AND_ROTATION`, and `AFFINE` (slowest — the full matrix is respected). Pick the cheapest one that describes how your instances actually move.

## `Sprites` options

| Option | Default | Effect |
| --- | --- | --- |
| `sprites` | `[]` | The fixed set of `Sprite`s this Node can draw; cannot be changed after construction |
| `spriteInstances` | `[]` | The array of `SpriteInstance`s to paint, in order (later entries draw on top); mutate this array in place |
| `canvasBounds` | — | The `Bounds2` scenery uses for layout/repainting/hit-testing fallback — must cover everywhere the sprites actually draw, or content can be clipped |
| `hitTestSprites` | `false` | If `true`, picking calls each instance's `containsPoint()`; if `false`, any point inside `canvasBounds` counts as a hit |
| `renderer` | `'webgl'` | `Sprites` defaults to WebGL rendering (unlike most Nodes), since that's normally why you'd reach for it; Canvas is also supported |

## Updating what's drawn

Because `spriteInstances` is a plain array you mutate directly (add, remove, or change `sprite`/`matrix`/`alpha` on existing entries), `Sprites` has no automatic dirty-tracking — call `invalidatePaint()` after any change you want reflected on the next frame.

::: tip Sprites exists for populations too large for one Node each
If you have a handful of images, ordinary [`Image`](/api/scenery/image) Nodes in the scene graph are simpler and get you free input handling, layout participation, and per-Node transforms. Reach for `Sprites` specifically when the population is large enough (hundreds-plus, changing every frame) that per-Node overhead becomes the bottleneck — it trades scene-graph convenience for one big, hand-managed draw call.
:::

::: warning `canvasBounds` is not computed automatically
Unlike most Nodes, `Sprites` has no way to infer its own bounds from its content — you must set `canvasBounds` yourself (initially via the option, or later via `setCanvasBounds()`) to a region that covers every instance's drawn extent, and keep it updated as instances move.
:::


========================================================================
Page: Text
URL: https://veillette.github.io/Almanach/api/scenery/text
Source: docs/api/scenery/text.md
Category: API | Tags: scenery, Text, PhetFont, font | Status: verified
========================================================================

# Text

`Text` (from `scenerystack/scenery`) is a [`Node`](/api/scenery/node) that displays a single string with a chosen `font`, `fill`, and (optionally) `stroke`. Use it for plain, single-style strings; reach for [`RichText`](/api/scenery/rich-text) instead when a string needs mixed styling (bold, sub/superscript, links) within itself.

```ts
import { Text, Font } from 'scenerystack/scenery';
import { PhetFont } from 'scenerystack/scenery-phet';

const label = new Text( 'Hello, world!', {
  font: new PhetFont( 24 ),
  fill: 'black'
} );

// Shorthand font properties instead of a Font instance:
const caption = new Text( 'caption text', {
  fontSize: 14,
  fontWeight: 'bold'
} );
```

Simulations conventionally use [`PhetFont`](/api/scenery-phet/phet-font) (from `scenerystack/scenery-phet`) rather than the browser default or a raw `Font` so that text renders consistently across platforms; `Font` (from `scenerystack/scenery`) is the lower-level class `PhetFont` builds on.

## Options

| Option | Effect |
| --- | --- |
| `string` | The text to display (also accepts a `number`, which is stringified) |
| `stringProperty` | Sets forwarding of the string from a `TReadOnlyProperty<string>` — the standard way to make displayed text respond to changing/translated content |
| `font` | A `Font` (or `PhetFont`) instance, or a CSS font shorthand string |
| `fontWeight`, `fontFamily`, `fontStretch`, `fontStyle`, `fontSize` | Shorthand setters that construct/replace the underlying `Font` for you |
| `boundsMethod` | How bounds are computed: `'fast'`, `'fastCanvas'`, `'accurate'`, or `'hybrid'` (default) |

`Text` also mixes in `Paintable` (`fill`, `stroke`, `lineWidth`, …) and accepts the full set of [`Node` options](/api/scenery/node). The default `fill` is `'#000000'` (black), unlike a plain `Node`.

## Reacting to changing text

```ts
import { Text } from 'scenerystack/scenery';
import { StringProperty } from 'scenerystack/axon';

const messageProperty = new StringProperty( 'Score: 0' );
const scoreText = new Text( messageProperty, { fontSize: 18 } );

messageProperty.value = 'Score: 10'; // scoreText updates automatically
```

::: tip Pass a Property directly as the first constructor argument
`new Text( stringProperty, options )` is equivalent to `new Text( '', { stringProperty, ...options } )` — either form links the displayed string to a `TReadOnlyProperty<string>` (see [`StringProperty`](/api/axon/string-property)) so translated or dynamically-generated strings update the display without manual re-rendering.
:::


========================================================================
Page: Trail
URL: https://veillette.github.io/Almanach/api/scenery/trail
Source: docs/api/scenery/trail.md
Category: API | Tags: scenery, Trail, scene-graph, hit-testing, coordinates | Status: verified
========================================================================

# Trail

`Trail` (from `scenerystack/scenery`) represents one path through the scene graph — an ordered array of [`Node`](/api/scenery/node)s from some root down to a descendant, plus the child index at each step. Because a `Node` can appear under more than one parent (a DAG, not just a tree), a single `Node` can be reached by multiple distinct trails; `Trail` is what disambiguates *which* instance of a Node is meant when computing bounds, transforms, or picking. Scenery hands you a `Trail` on every input event (`event.trail`) and uses trails internally to walk the [`Display`](/api/scenery/display)'s rendered tree.

```ts
import { Node, Circle } from 'scenerystack/scenery';
import { Vector2 } from 'scenerystack/dot';

const root = new Node();
const group = new Node();
const dot = new Circle( 5, { fill: 'crimson' } );

root.addChild( group );
group.addChild( dot );

const trail = new Trail( [ root, group, dot ] );

trail.lastNode();  // dot
trail.rootNode();  // root
trail.getMatrix();          // Matrix3: dot's full transform relative to root
trail.localToGlobalPoint( new Vector2( 0, 0 ) ); // dot's local origin, in root's frame
```

## Building and inspecting a Trail

| Method | Effect |
| --- | --- |
| `new Trail( nodes )` | Builds a trail from a `Node[]` (root-to-leaf order), a single `Node`, or copies another `Trail` |
| `addAncestor( node, index? )` / `addDescendant( node, index? )` | Extends the trail at the root end / leaf end |
| `removeAncestor()` / `removeDescendant()` | Shortens the trail from either end |
| `slice( start, end? )` / `subtrailTo( node, excludeNode? )` | Returns a new `Trail` covering part of this one |
| `copy()` | Independent copy that can be mutated without affecting the original |
| `reindex()` | Recomputes `indices` after the scene graph has changed, since indices can go stale |
| `lastNode()` / `rootNode()` | The leaf Node / the root Node of the trail |
| `nodes` / `indices` / `length` | The raw `Node[]`, per-step child indices, and trail length |

## Queries used for hit-testing and visibility

| Method | Meaning |
| --- | --- |
| `isValid()` | Whether every node in the trail is still actually connected root-to-leaf (reindexes first) |
| `isVisible()` | `true` only if every Node along the trail has `visible: true` |
| `isPickable()` | Whether this trail would actually be hit-tested, given `pickable`/`visible`/attached listeners along the way |
| `getOpacity()` | Combined (multiplied) opacity of every Node on the trail |
| `containsNode( node )` | Whether `node` appears anywhere on this trail |
| `isExtensionOf( other, allowSameTrail? )` | Whether this trail continues on from `other` (i.e. `other` is a prefix) |
| `equals( other )` / `compare( other )` | Structural equality, or a stable ordering comparison (for z-order-like sorting) |

## Coordinate transforms

| Method | Effect |
| --- | --- |
| `getMatrix()` | `Matrix3` transforming the leaf Node's local coordinates into the root's coordinate frame |
| `getTransform()` | Same, wrapped as a `Transform3` |
| `localToGlobalPoint( point )` / `globalToLocalPoint( point )` | Converts a `Vector2` between the leaf's local frame and the trail's root frame |
| `localToGlobalBounds( bounds )` / `globalToLocalBounds( bounds )` | Same, for a `Bounds2` |
| `getTransformTo( otherTrail )` / `getMatrixTo( otherTrail )` | Transform between two trails that share a common ancestor |

::: tip A Node's `Trail` isn't unique — request it when you need it
Because Nodes can have multiple parents, there's no single "the trail" for a Node in general; that's why `Trail` objects are handed to you contextually (an input event's `event.trail`, or `node.getUniqueTrail()` when a Node is only used once) rather than stored permanently on the `Node` itself. Don't cache a `Trail` across scene graph edits without calling `reindex()` or rechecking `isValid()` first — added/removed/reordered children can make its `indices` stale.
:::


========================================================================
Page: TransformTracker
URL: https://veillette.github.io/Almanach/api/scenery/transform-tracker
Source: docs/api/scenery/transform-tracker.md
Category: API | Tags: scenery, TransformTracker, Trail, transform | Status: complete
========================================================================

# TransformTracker

`TransformTracker` (from `scenerystack/scenery`) watches every Node along a [`Trail`](/api/scenery/trail) and notifies you when the trail's *cumulative* transform (the composed local-to-global matrix) changes — without recomputing the whole matrix chain from scratch each time. It caches the composed matrix and only recomputes the portion downstream of whichever Node actually changed, using a dirty index. Scenery uses it internally for exactly this reason: [`DragListener`](/api/scenery/drag-listener)'s `trackAncestors` option creates one to reposition a dragged Node when an ancestor moves, and the [highlight-rendering overlay](/api/scenery/highlight-rendering) uses one per active focus highlight to keep it aligned with the Node it surrounds.

```ts
import { TransformTracker } from 'scenerystack/scenery';

const trail = someNode.getUniqueTrail();
const tracker = new TransformTracker( trail );

tracker.addListener( () => {
  console.log( 'cumulative transform changed:', tracker.matrix );
} );

// ... later, when this tracker is no longer needed:
tracker.dispose();
```

## Constructor and options

`new TransformTracker( trail, providedOptions? )` takes the `Trail` to watch and:

| Option | Default | Effect |
| --- | --- | --- |
| `isStatic` | `false` | If `true`, listeners are notified synchronously without defensively copying the listener array first — a minor performance win when you're certain listeners won't add/remove other listeners during notification |

## Methods

| Method | Effect |
| --- | --- |
| `addListener( listener )` | Registers a no-argument callback fired synchronously whenever any Node in the trail (except the root) changes its transform |
| `removeListener( listener )` | Removes a previously added listener |
| `getMatrix()` / `.matrix` | Returns the current local-to-global `Matrix3` for the trail's leaf node — recomputed lazily, only as far up the dirty chain as needed |
| `dispose()` | Removes all the internal per-Node listeners this tracker installed; call this when you're done, or the tracked Nodes will hold references indefinitely |

::: tip Exclude the leaf node's own transform with `trail.copy().removeDescendant()`
A `TransformTracker` includes every Node in the given trail. If you only care about *ancestor* transform changes (not the dragged/highlighted Node's own transform, which you're presumably setting yourself), pass a trail with the leaf removed — this is exactly the pattern `DragListener` uses internally: `new TransformTracker( pressedTrail.copy().removeDescendant() )`.
:::


========================================================================
Page: VBox
URL: https://veillette.github.io/Almanach/api/scenery/v-box
Source: docs/api/scenery/v-box.md
Category: API | Tags: scenery, VBox, HBox, FlowBox, layout | Status: verified
========================================================================

# VBox

`VBox` (from `scenerystack/scenery`) is [`FlowBox`](/api/scenery/flow-box) with `orientation` fixed to `'vertical'` — it stacks its children top-to-bottom in a single column. It's the class most code reaches for instead of `FlowBox` directly, since orientation rarely needs to change at runtime; `VBox` accepts every `FlowBox` option (`spacing`, `align`, `stretch`, `grow`, `justify`, `wrap`, margins, …) except `orientation`, which the constructor sets for you and asserts you didn't also pass.

```ts
import { VBox, Circle, Rectangle } from 'scenerystack/scenery';

const column = new VBox( {
  spacing: 8,
  align: 'center',
  children: [
    new Circle( 15, { fill: 'crimson' } ),
    new Rectangle( 0, 0, 40, 30, { fill: 'teal' } ),
    new Circle( 10, { fill: 'goldenrod' } )
  ]
} );
```

For a horizontal (row) layout, use [`HBox`](/api/scenery/h-box) instead; for the full option table (spacing, alignment, growth, wrapping, margins) see [`FlowBox`](/api/scenery/flow-box), which documents everything `VBox` inherits.

## Options and methods

`VBoxOptions` is `FlowBoxOptions` with `orientation` omitted — every option and method documented on [`FlowBox`](/api/scenery/flow-box) (`spacing`, `align`, `grow`, `justify`, `wrap`, `getCell()`, `dispose()`, …) applies here unchanged, just fixed to a vertical main axis. For a vertical stack, `align` takes the horizontal-alignment values (`'left'`, `'right'`, `'center'`, `'origin'`) since it controls cross-axis (horizontal) placement of each row.

::: warning Use `HSeparator`, not `VSeparator`, to divide a `VBox`
`VBox` asserts against inserting a `VSeparator` child — a *vertical* dividing line makes no sense between rows stacked *vertically*. Use `HSeparator` (a horizontal rule, also from `scenerystack/scenery`) to visually divide sections of a `VBox`; `VSeparator` is for dividing columns inside an [`HBox`](/api/scenery/h-box) instead.
:::


========================================================================
Page: Voicing
URL: https://veillette.github.io/Almanach/api/scenery/voicing
Source: docs/api/scenery/voicing.md
Category: API | Tags: scenery, Voicing, voicing, speech, accessibility | Status: verified
========================================================================

# Voicing

This page is the **class-level API reference** for the `Voicing` trait (from `scenerystack/scenery`) — its options, Properties, and methods as defined in source. For what Voicing is, why it's layered on top of the PDOM rather than replacing it, and worked examples, read the narrative guide at [Voicing](/accessibility/voicing) first; this page assumes that context and only documents the surface itself.

`Voicing` is a mixin function: `Voicing( Node )` (or `Voicing( SomeNodeSubclass )`) returns a class with the response Properties and speak methods below, layered on top of [`InteractiveHighlighting`](/api/scenery/interactive-highlighting) (so every `Voicing` Node is also automatically interactive-highlighting-capable).

```ts
import { Node, Voicing } from 'scenerystack/scenery';

class LaunchButtonNode extends Voicing( Node ) {
  public constructor() {
    super( {
      tagName: 'button',
      accessibleName: 'Launch',
      voicingNameResponse: 'Launch',
      voicingHintResponse: 'Launches the ball at the current angle and speed.'
    } );
  }
}
```

## Options / response Properties

These are `Voicing`'s mutator keys (`VOICING_OPTION_KEYS` in source):

| Option | Effect |
| --- | --- |
| `voicingNameResponse` | The "what is it" response — a `VoicingResponse` (string, `null`, or a function/Property resolving to one) |
| `voicingObjectResponse` | The "current state" response |
| `voicingContextResponse` | The "what changed elsewhere" response |
| `voicingHintResponse` | The "how to interact" response |
| `voicingResponsePatternCollection` | A `ResponsePatternCollection` controlling how the four responses above are combined into spoken sentences |
| `voicingIgnoreVoicingManagerProperties` | If `true`, this Node's speech ignores the global response-category preferences (`responseCollector`) that normally let users silence hints, etc. |
| `voicingUtterance` | A specific `Utterance` instance to funnel all of this Node's speech through, instead of an internally-created one |
| `voicingFocusListener` | The listener invoked on DOM focus; defaults to speaking the full response. Pass `null` to suppress automatic speech-on-focus |
| `voicingPressable` | If `true`, attaches a `VoicingActivationResponseListener` so responses are also spoken on press, not just focus |

Each option has a matching getter/setter pair (`setVoicingNameResponse()` / `voicingNameResponse`, etc.), consistent with the rest of scenery's mutator pattern.

## Speak-on-demand methods

| Method | Speaks |
| --- | --- |
| `voicingSpeakFullResponse( options? )` | All four response categories currently assigned to the Node |
| `voicingSpeakResponse( options? )` | Only whatever response strings are passed in `options` |
| `voicingSpeakNameResponse( options? )` | The name response |
| `voicingSpeakObjectResponse( options? )` | The object response |
| `voicingSpeakContextResponse( options? )` | The context response |
| `voicingSpeakHintResponse( options? )` | The hint response |

`SpeakingOptions` accepts an `utterance` override alongside the response text, for one-off calls that shouldn't use `voicingUtterance`.

::: tip `Voicing` composes `InteractiveHighlighting` automatically
`VoicingOptions` extends `InteractiveHighlightingOptions`, and the trait's implementation class extends `InteractiveHighlighting( Type )` internally — so a `Voicing`-enabled Node is already pointer-highlightable without separately mixing in [`InteractiveHighlighting`](/api/scenery/interactive-highlighting). Mixing both traits directly on the same class is redundant and unnecessary.
:::


========================================================================
Page: WebGLNode, CanvasNode, and DOM
URL: https://veillette.github.io/Almanach/api/scenery/rendering-backends
Source: docs/api/scenery/rendering-backends.md
Category: API | Tags: scenery, WebGLNode, CanvasNode, DOM, rendering, renderer | Status: verified
========================================================================

# WebGLNode, CanvasNode, and DOM

Most scenery content is built from `Path`/`Text`/`Image`-style Nodes and rendered through scenery's own SVG or Canvas layers, chosen automatically per-Node. `WebGLNode`, `CanvasNode`, and `DOM` (all from `scenerystack/scenery`) are the three escape hatches for content scenery's normal drawing pipeline can't produce — each locks a subtree to one specific rendering backend and hands you direct control of that backend's drawing surface (or, for `DOM`, an actual live DOM element). All three are `Node` subclasses, so they take part in the scene graph, transforms, and bounds like any other Node.

## When to reach for each

| Class | Use it for |
| --- | --- |
| `CanvasNode` | Custom 2D drawing that's cheaper or only expressible as imperative Canvas calls — particle systems, heatmaps, per-pixel effects — where per-Node SVG elements would be too slow or don't have an equivalent primitive |
| `WebGLNode` | Custom GPU-accelerated drawing — large numbers of instances, shader effects — where even Canvas 2D isn't fast enough |
| `DOM` | Embedding an actual pre-existing HTML element (an `<iframe>`, a third-party widget, a native `<video>`) that can't be expressed as scenery drawing at all |

All three are **abstract or near-abstract**: `CanvasNode` and `WebGLNode` must be subclassed to provide painting logic; `DOM` is concrete but exists specifically to wrap an element you already have.

## CanvasNode

Subclass it and override `paintCanvas`; supply `canvasBounds` (covering everything you'll draw, since content outside it isn't guaranteed to render):

```ts
import { CanvasNode, CanvasNodeOptions } from 'scenerystack/scenery';
import { Bounds2 } from 'scenerystack/dot';

class TrailNode extends CanvasNode {
  public constructor( options?: CanvasNodeOptions ) {
    super( { canvasBounds: new Bounds2( 0, 0, 200, 200 ), ...options } );
  }

  public override paintCanvas( context: CanvasRenderingContext2D ): void {
    context.fillStyle = 'rgba(0, 100, 255, 0.5)';
    context.fillRect( 10, 10, 50, 50 );
  }
}
```

Call `invalidatePaint()` whenever the drawing needs to be redone (scenery does not re-invoke `paintCanvas` on its own schedule) — `paintCanvas` runs during `Display.updateDisplay()`, so it must not mutate any scenery Node.

## WebGLNode

Subclass it and pass a "painter type" constructor — a class implementing `paint( modelViewMatrix, projectionMatrix )` and `dispose()` — plus `canvasBounds`:

```ts
import { WebGLNode, WebGLNodeOptions, WebGLNodePainter, WebGLNodePainterResult } from 'scenerystack/scenery';
import { Matrix3, Bounds2 } from 'scenerystack/dot';

class MyPainter implements WebGLNodePainter {
  public constructor( private gl: WebGLRenderingContext, private node: MyWebGLNode ) {}
  public paint( modelViewMatrix: Matrix3, projectionMatrix: Matrix3 ): WebGLNodePainterResult {
    // issue gl.* draw calls here
    return 1; // WebGLNode.PAINTED_SOMETHING
  }
  public dispose(): void {}
}

class MyWebGLNode extends WebGLNode {
  public constructor( options?: WebGLNodeOptions ) {
    super( MyPainter, { canvasBounds: new Bounds2( 0, 0, 200, 200 ), ...options } );
  }
}
```

A distinct painter instance is created per WebGL context the Node is displayed under, since GPU buffers/textures aren't shareable across contexts — this is why `painterType` is a constructor, not a single painter object.

## DOM

Wraps a real `Element`, keeping it positioned/transformed to match the Node's place in the scene graph:

```ts
import { DOM } from 'scenerystack/scenery';

const iframe = document.createElement( 'iframe' );
iframe.src = 'https://example.com/embed';
iframe.style.border = 'none';

const embedded = new DOM( iframe, {
  preventTransform: false // let scenery apply its CSS transform to the element
} );
```

| Option | Effect |
| --- | --- |
| `element` | The wrapped `Element` (also settable post-construction via `setElement`) |
| `preventTransform` | If `true`, scenery will not apply its own transform to the element — use when the embedded content manages its own positioning |
| `allowInput` | Whether input events are allowed to reach the DOM element (rather than being captured by scenery's input system) |

::: warning None of these three participate in scenery's normal renderer-switching
A `Path` or `Text` Node can be drawn with SVG, Canvas, or WebGL depending on context and scenery's own heuristics — `CanvasNode`, `WebGLNode`, and `DOM` each lock themselves to exactly one renderer (`Renderer.bitmaskCanvas`, `bitmaskWebGL`, and `bitmaskDOM` respectively) for the lifetime of the Node. Reach for one of these only when you specifically need that backend's capabilities (imperative pixel/GPU control, or a real DOM element) — for everything else, prefer the standard Node subclasses so scenery can pick the best renderer per [`Display`](/api/scenery/display).
:::


========================================================================
Page: ArrowNode
URL: https://veillette.github.io/Almanach/api/scenery-phet/arrow-node
Source: docs/api/scenery-phet/arrow-node.md
Category: API | Tags: scenery-phet, ArrowNode | Status: verified
========================================================================

# ArrowNode

`ArrowNode` (from `scenerystack/scenery-phet`) draws a single- or double-headed arrow between two points. It's the standard way to render vectors (velocity, force, momentum), callouts, and directional indicators — most of the actual geometry work happens in the internal `ArrowShape`, so `ArrowNode` itself is a thin, mutable `Path` wrapper around it.

```ts
import { ArrowNode } from 'scenerystack/scenery-phet';
```

## A minimal example

```ts
// Draw an arrow from (0, 0) to (100, -40)
const forceArrow = new ArrowNode( 0, 0, 100, -40, {
  fill: 'red',
  stroke: 'red',
  headHeight: 12,
  headWidth: 12,
  tailWidth: 4
} );

// Later, as the modeled force vector changes, update the geometry in place
// rather than creating a new ArrowNode:
forceArrow.setTailAndTip( 0, 0, newTipX, newTipY );
```

When the vector being drawn comes from model coordinates, convert both endpoints through a [`ModelViewTransform2`](/api/phetcommon/model-view-transform) before constructing or updating the `ArrowNode`.

## Constructor

```ts
new ArrowNode( tailX: number, tailY: number, tipX: number, tipY: number, providedOptions?: ArrowNodeOptions )
```

`ArrowNodeOptions` is `SelfOptions & PathOptions` — every `Path` option (`fill`, `stroke`, `lineWidth`, `pickable`, `visible`, …) is accepted alongside the arrow-specific options below. Defaults for the `Path` options are `fill: 'black'`, `stroke: 'black'`, `lineWidth: 1`.

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `headHeight` | `10` | Length of the arrowhead along the shaft |
| `headWidth` | `10` | Width of the arrowhead's base |
| `tailWidth` | `5` | Width of the shaft |
| `fractionalHeadHeight` | `0.5` | The head is scaled down once `headHeight` would exceed this fraction of the total arrow length (keeps short arrows from being all head) |
| `doubleHead` | `false` | `true` puts an arrowhead on both ends; `false` puts one head at the tip |
| `isHeadDynamic` | `false` | Whether the head scales as the arrow's length changes |
| `scaleTailToo` | `false` | Whether the tail width scales along with a dynamic head |

## Methods

| Method | Effect |
| --- | --- |
| `setTailAndTip( tailX, tailY, tipX, tipY )` | Repositions both ends and rebuilds the shape; reuses the existing `Shape` instance when possible for performance |
| `setTail( tailX, tailY )` | Repositions only the tail |
| `setTip( tipX, tipY )` | Repositions only the tip |
| `setTailWidth( tailWidth )` | Changes the shaft width and rebuilds the shape |
| `setDoubleHead( doubleHead )` | Toggles single/double-headed and rebuilds the shape |
| `.tailX` / `.tailY` / `.tipX` / `.tipY` | Read-only getters for the current endpoints |

::: tip headWidth must exceed tailWidth
The constructor asserts `headWidth > tailWidth`. If your arrowhead isn't visibly wider than the shaft, this is the first thing to check — it's a common typo when copying options between arrows of different sizes.
:::


========================================================================
Page: BackButton
URL: https://veillette.github.io/Almanach/api/scenery-phet/back-button
Source: docs/api/scenery-phet/back-button.md
Category: API | Tags: scenery-phet, BackButton, button | Status: verified
========================================================================

# BackButton

`BackButton` (from `scenerystack/scenery-phet`) is a [`RectangularPushButton`](/api/sun/rectangular-push-button) preloaded with a leftward arrow icon (built from `ArrowShape`, not an image), PhET's standard yellow button color, and margins tuned to visually match a refresh/step button of the same height. It originated for returning to a level-selection screen from a PhET game, and is generally appropriate anywhere a sim needs a "go back" affordance distinct from a browser's own back button.

```ts
import { BackButton } from 'scenerystack/scenery-phet';
```

## A minimal example

```ts
const backButton = new BackButton( {
  listener: () => {
    sceneProperty.value = 'levelSelection';
  },
  tandem: tandem.createTandem( 'backButton' )
} );
```

## Options

`BackButtonOptions` adds one option on top of the [same `RectangularPushButtonOptions`](/api/sun/rectangular-push-button) every rectangular push button accepts — `content` is fixed and not settable, since the arrow icon defines this button.

| Option | Default | Effect |
| --- | --- | --- |
| `soundPlayer` | the shared `'goBack'` sound player | Overridable if a different button in the same sim needs a distinct sound |
| `baseColor` | `PhetColorScheme.BUTTON_YELLOW` | The standard PhET yellow |
| `xMargin` / `yMargin` | `8` / `10.9` | Tuned specifically so `BackButton` matches the height of PhET's refresh button, since the two often appear side by side — avoid overriding lightly |

::: tip Margins are tuned to match other same-height buttons
`BackButton`'s default `xMargin`/`yMargin` values aren't arbitrary — they were chosen so this button's overall height lines up with PhET's refresh/step buttons when placed in the same row. Overriding them can introduce a visible height mismatch in a control strip.
:::


========================================================================
Page: Background Nodes
URL: https://veillette.github.io/Almanach/api/scenery-phet/background-nodes
Source: docs/api/scenery-phet/background-nodes.md
Category: API | Tags: scenery-phet, BackgroundNode, GradientBackgroundNode, GradientRectangle, SkyNode, GroundNode, OutsideBackgroundNode, background, gradient | Status: complete
========================================================================

# Background Nodes

`scenerystack/scenery-phet` exports a handful of small, unrelated-but-similarly-named "background" helpers. Four of them — `OutsideBackgroundNode`, `SkyNode`, `GroundNode`, and `GradientBackgroundNode` — form one family: the sky-over-ground gradient scene backdrop used by outdoor-themed sims (projectile motion, gravity/forces sims, anything with a horizon). The other two, `BackgroundNode` and `GradientRectangle`, are general-purpose, standalone utilities that happen to live in the same file group. This page covers all six together since each is too small to warrant its own page.

```ts
import {
  OutsideBackgroundNode, SkyNode, GroundNode, GradientBackgroundNode,
  BackgroundNode, GradientRectangle
} from 'scenerystack/scenery-phet';
```

## The sky/ground gradient family

`GradientBackgroundNode` is the base class: a `Rectangle` filled with a single vertical `LinearGradient` between two colors. `SkyNode` and `GroundNode` are thin subclasses that fix sensible default colors (sky: blue-to-pale-blue; ground: green-to-darker-green) and orient the gradient correctly for "up" (sky) or "down" (ground). `OutsideBackgroundNode` composes one `SkyNode` and one `GroundNode` into a single ready-to-use backdrop.

### A minimal example

```ts
// A full-screen outdoor backdrop: sky above, ground below, centered horizontally.
const backgroundNode = new OutsideBackgroundNode(
  layoutBounds.centerX, // centerX
  layoutBounds.centerY, // centerY — the horizon, where sky meets ground
  layoutBounds.width * 3, // width
  layoutBounds.height,    // skyHeight
  layoutBounds.height     // groundDepth
);
screenView.addChild( backgroundNode );
```

`OutsideBackgroundNode` has no options object — every parameter is positional, and colors can only be customized by building `SkyNode`/`GroundNode` yourself instead of using the composite:

```ts
const sky = new SkyNode( 0, -300, 800, 300, 150, {
  topColor: 'midnightblue',
  bottomColor: 'skyblue'
} );
const ground = new GroundNode( 0, 0, 800, 200, 100 );
```

### Constructors

| Class | Constructor |
| --- | --- |
| `GradientBackgroundNode` | `( x, y, width, height, color1: TColor, color2: TColor, y1: number, y2: number )` — plain two-stop vertical gradient between `y1` and `y2` |
| `SkyNode` | `( x, y, width, height, gradientEndHeight: number, providedOptions?: SkyNodeOptions )` |
| `GroundNode` | `( x, y, width, height, gradientEndDepth: number, providedOptions?: GroundNodeOptions )` |
| `OutsideBackgroundNode` | `( centerX, centerY, width, skyHeight, groundDepth )` — no options |

`SkyNodeOptions` and `GroundNodeOptions` are both just `{ topColor?: TColor; bottomColor?: TColor }` — `SkyNode` defaults to a blue-to-pale-blue gradient, `GroundNode` to a green-to-darker-green one.

::: tip `gradientEndHeight` / `gradientEndDepth` control gradient extent, not visual extent
For `SkyNode`, the rectangle always spans the full `height` you pass, but the gradient itself only transitions over `gradientEndHeight` (from the bottom of the sky, going up) — past that point the color is solid `topColor`. `GroundNode` works the same way in reverse. `OutsideBackgroundNode` passes half of `skyHeight`/`groundDepth` for these, giving a gradient that fades out before reaching the horizon on one side and before reaching the far edge on the other.
:::

## BackgroundNode

`BackgroundNode` is unrelated to the sky/ground family — it puts an arbitrary `Node` on top of a translucent rectangle sized to fit it, dynamically resizing as the wrapped Node's bounds change. It's a quick way to keep text or an icon readable when it might overlap other content (e.g. a label drawn on top of a photo or a `WireNode`).

```ts
import { Text } from 'scenerystack/scenery';

const label = new Text( 'Voltage' );
const labelWithBackground = new BackgroundNode( label, {
  xMargin: 4,
  yMargin: 4,
  rectangleOptions: { fill: 'white', opacity: 0.85 }
} );
```

### `BackgroundNode` options

| Option | Default | Effect |
| --- | --- | --- |
| `xMargin` / `yMargin` | `2` / `2` | Margin between the wrapped Node's bounds and the background rectangle's edge |
| `rectangleOptions` | `{ fill: 'white', opacity: 0.75 }` | Options forwarded to the internal background [`Rectangle`](/api/scenery/rectangle) |

## GradientRectangle

`GradientRectangle` is also unrelated to the sky/ground family — it's a `Rectangle` whose edges fade out via [`LinearGradient`](/api/scenery/linear-gradient)s on each side and [`RadialGradient`](/api/scenery/radial-gradient)s at the corners, instead of having a hard edge. Use it where content needs to visually fade at its boundary, e.g. the edge of a scrolling or clipped region.

```ts
const fadingPanel = new GradientRectangle( {
  rectWidth: 200,
  rectHeight: 100,
  fill: 'white',
  margin: 20,       // all four sides fade over a 20px band
  roundMargins: true
} );
```

### `GradientRectangle` options

| Option | Default | Effect |
| --- | --- | --- |
| `margin` | `0` | Sets `leftMargin`, `rightMargin`, `topMargin`, `bottomMargin` together — width of the fade band on each side |
| `xMargin` / `yMargin` | `0` / `0` | Set left+right or top+bottom margins together |
| `leftMargin` / `rightMargin` / `topMargin` / `bottomMargin` | `0` | Fade-band width for one side individually |
| `roundMargins` | `true` | Whether the corners fade with a rounded (radial) gradient or a squared-off one |
| `extension` | `0` | Where (from `0` to `<1`, as a fraction of the margin) the fade actually starts — `0` starts fading immediately at the rectangle edge |
| `border` | `null` | The color the fade transitions *to*; `null` means "fully transparent version of `fill`" |

::: warning Only `fill` is supported, not `stroke`
`GradientRectangle` overrides `setStroke()` to assert that the stroke is always `null` — the fading effect is implemented as fill-only child shapes, so a stroke has no sensible rendering here. Set `fill` (a solid `ColorDef`, not a gradient/pattern) and let `GradientRectangle` build its own internal gradients from it.
:::


========================================================================
Page: BannedNode
URL: https://veillette.github.io/Almanach/api/scenery-phet/banned-node
Source: docs/api/scenery-phet/banned-node.md
Category: API | Tags: scenery-phet, BannedNode, icon, prohibition | Status: complete
========================================================================

# BannedNode

`BannedNode` (from `scenerystack/scenery-phet`) draws the universal "no" or prohibition symbol — a stroked circle with a diagonal line through it, as seen on "no entry" road signs (see [the Wikipedia article on the no symbol](https://en.wikipedia.org/wiki/No_symbol)). It's a static icon Node with no interactive behavior or bound Property: construct it, style it, and use it wherever a design calls for "this action/state is disallowed" — for example, disabling a tool or indicating an invalid configuration. For the octagonal red "stop" icon instead of the circle-slash icon, see [`StopSignNode`](/api/scenery-phet/stop-sign-node).

```ts
import { BannedNode } from 'scenerystack/scenery-phet';
```

## A minimal example

```ts
const bannedIcon = new BannedNode( {
  radius: 16,
  stroke: 'red',
  lineWidth: 4
} );

toolboxIcon.addChild( bannedIcon );
```

## Constructor

```ts
new BannedNode( providedOptions?: BannedNodeOptions )
```

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `radius` | `20` | Radius of the circle (and half the length of the diagonal slash) |
| `stroke` | `'red'` | Stroke color of both the circle and the slash |
| `lineWidth` | `5` | Stroke width of both the circle and the slash |
| `fill` | `null` | Fill of the circle's interior; `null` leaves it transparent |

`BannedNodeOptions` also accepts every plain `NodeOptions` field (`scale`, `opacity`, `visible`, …) except `children`, which is set internally.

::: tip The circle and slash always share `stroke` and `lineWidth`
There's no way to give the circle and the diagonal line independent colors or weights — both options apply to both shapes. If you need mismatched styling, compose your own `Circle` + `Line` pair instead of using `BannedNode`.
:::


========================================================================
Page: BicyclePumpNode
URL: https://veillette.github.io/Almanach/api/scenery-phet/bicycle-pump-node
Source: docs/api/scenery-phet/bicycle-pump-node.md
Category: API | Tags: scenery-phet, BicyclePumpNode, pump, particles | Status: verified
========================================================================

# BicyclePumpNode

`BicyclePumpNode` (from `scenerystack/scenery-phet`) draws a bicycle pump — base, body, handle, hose, and a segmented "remaining capacity" indicator built into the body — and lets the user drag (or keyboard-drag) the handle down to inject discrete units into a model quantity. It's used in sims like States of Matter and Gas Properties to let users add particles one pump-stroke at a time.

```ts
import { BicyclePumpNode } from 'scenerystack/scenery-phet';
import { NumberProperty, Property } from 'scenerystack/axon';
import { Range, Vector2 } from 'scenerystack/dot';
```

## A minimal example

```ts
const numberOfParticlesProperty = new NumberProperty( 0 );
const rangeProperty = new Property( new Range( 0, 100 ) );

const pumpNode = new BicyclePumpNode( numberOfParticlesProperty, rangeProperty, {
  width: 200,
  height: 250,
  hoseAttachmentOffset: new Vector2( 100, -50 ),
  tandem: tandem.createTandem( 'pumpNode' )
} );
```

Call `pumpNode.reset()` from your screen's `reset()` to snap the handle back to its initial (fully raised) position and clear internal drag-accumulation state — this does not touch `numberOfParticlesProperty` itself.

## Constructor

```ts
new BicyclePumpNode(
  numberProperty: TProperty<number>,
  rangeProperty: TReadOnlyProperty<Range>,
  providedOptions?: BicyclePumpNodeOptions
)
```

`numberProperty` is incremented as the handle is dragged down; the pump refuses to push `numberProperty` above `rangeProperty.value.max`.

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `width` / `height` | `200` / `250` | Overall size; every part of the pump is proportioned from these |
| `handleFill` / `shaftFill` / `bodyFill` / `bodyTopFill` / `baseFill` / `hoseFill` | assorted grays/red | Colors of each visual part |
| `indicatorBackgroundFill` / `indicatorRemainingFill` | dark gray / light gray | Colors of the segmented capacity indicator on the pump body |
| `hoseCurviness` | `1` | Larger values curve the hose more; smaller values straighten it |
| `hoseAttachmentOffset` | `Vector2(100, 100)` | Where the hose's far end attaches, relative to the pump's origin; its sign (x > 0 or < 0) decides which side of the cone the hose comes off |
| `nodeEnabledProperty` | `null` (an owned `BooleanProperty` is created) | Pass your own to share enabled-state externally; passing `null` means the Node owns and disposes its own |
| `injectionEnabledProperty` | always-`true` `BooleanProperty` | Throttle: when `false`, the pump stays visually interactive but stops actually adding particles (for model back-pressure) |
| `numberOfParticlesPerPumpAction` | `10` | How many full handle-down strokes worth of travel corresponds to one full "pump action" of particle additions |
| `addParticlesOneAtATime` | `true` | If `false`, particles accumulated during one stroke are added in a single batch at the end instead of one at a time as the threshold is crossed |
| `handleTouchAreaXDilation` / `handleTouchAreaYDilation` | `15` / `15` | Touch-area dilation around the handle |
| `dragListenerOptions` / `keyboardDragListenerOptions` | — | Passed through to the internal pointer/keyboard drag listeners |

## Methods

| Method | Effect |
| --- | --- |
| `reset()` | Returns the handle/shaft to their initial position and clears drag-accumulation state |

::: tip `injectionEnabledProperty` vs `nodeEnabledProperty`
These control two different things: `nodeEnabledProperty` (or the owned default) governs whether the handle can be grabbed at all — when disabled, the handle dims and stops responding to input. `injectionEnabledProperty` leaves the handle fully interactive but silently stops incrementing `numberProperty`, which is the hook meant for "the model can't accept particles this fast" without making the control itself look broken.
:::


========================================================================
Page: BoxNode
URL: https://veillette.github.io/Almanach/api/scenery-phet/box-node
Source: docs/api/scenery-phet/box-node.md
Category: API | Tags: scenery-phet, BoxNode, BoxShapeCreator, capacitor, pseudo-3d | Status: complete
========================================================================

# BoxNode

`BoxNode` (from `scenerystack/scenery-phet`) draws a pseudo-3D rectangular box by rendering three flat parallelograms — a top face, a front face, and a right-side face — each a `Path` filled with a progressively darker shade of the same base `Color`. It's the building block PhET's capacitor and battery visualizations use to fake a 3D dielectric slab or plate without any real 3D rendering. The origin is at the center of the top face.

The actual 2D geometry for each face is computed by the companion class `BoxShapeCreator`, which projects 3D model coordinates (a `Bounds3`) into 2D view-coordinate `Shape`s using a [`YawPitchModelViewTransform3`](https://github.com/phetsims/scenery-phet) — the same yaw/pitch/scale projection used throughout PhET's capacitor sims.

```ts
import { BoxNode, YawPitchModelViewTransform3 } from 'scenerystack/scenery-phet';
import { Bounds3 } from 'scenerystack/dot';
import { Color } from 'scenerystack/scenery';
```

## A minimal example

```ts
const transform = new YawPitchModelViewTransform3( {
  scale: 12000,
  pitch: 30 * Math.PI / 180,
  yaw: -45 * Math.PI / 180
} );

// A slab of dielectric material, in model coordinates (meters).
const size = new Bounds3( -0.005, 0, -0.0025, 0.005, 0.001, 0.0025 );

const boxNode = new BoxNode( transform, new Color( 'yellow' ), size, {
  pickable: true // so a probe/voltmeter can hit-test the box
} );

// Resize later without recreating the Node:
boxNode.setBoxSize( size.dilatedY( 0.0005 ) );
```

`BoxNode.topNode` and `BoxNode.frontNode` are exposed read-only if you need to layer additional graphics (like a charge overlay) directly on top of a specific face.

## Constructor

```ts
new BoxNode( transform: YawPitchModelViewTransform3, color: Color, size: Bounds3, options?: NodeOptions )
```

| Parameter | Description |
| --- | --- |
| `transform` | The `YawPitchModelViewTransform3` used to project all three faces |
| `color` | Base color; the front face uses `color.darkerColor()` and the right-side face uses `color.darkerColor().darkerColor()`, giving the top face the lightest, most "lit" appearance |
| `size` | A model-coordinate `Bounds3`, with the box's top-face center at `(size.minX, size.minY, size.minZ)` plus `width`/`height`/`depth` |
| `options` | Plain `NodeOptions`; `pickable: true` is merged in by default so the box can be hit-tested |

## Methods

| Method | Effect |
| --- | --- |
| `setBoxSize( size: Bounds3 )` | Updates the box's size and rebuilds all three face shapes, only if the new size actually differs from the current one |

## BoxShapeCreator

`BoxShapeCreator` is the standalone shape-generation half of `BoxNode` — construct one directly if you need the raw `Shape`s (e.g. to draw a face yourself, or to hit-test without a `Path`) rather than a ready-made `Node`.

```ts
const shapeCreator = new BoxShapeCreator( transform );
const topShape = shapeCreator.createTopFaceBounds3( size );
```

| Method | Returns |
| --- | --- |
| `createTopFace( x, y, z, width, height, depth )` / `createTopFaceBounds3( bounds )` | `Shape` for the top parallelogram |
| `createFrontFace( x, y, z, width, height, depth )` / `createFrontFaceBounds3( bounds )` | `Shape` for the front rectangle |
| `createRightSideFace( x, y, z, width, height, depth )` / `createRightSideFaceBounds3( bounds )` | `Shape` for the right-side parallelogram |
| `createBoxShape( x, y, z, width, height, depth )` | The union of all three faces as one `Shape` |

::: tip Not a general-purpose 3D primitive
`BoxNode` and `BoxShapeCreator` were built specifically for PhET's capacitor/battery circuit visualizations and assume a fixed yaw/pitch projection supplied via `YawPitchModelViewTransform3` — they're not a general "3D box" utility. If you just need an isometric-looking box icon with no model-coordinate semantics, it's usually simpler to hand-build the three parallelogram `Shape`s yourself.
:::


========================================================================
Page: BracketNode
URL: https://veillette.github.io/Almanach/api/scenery-phet/bracket-node
Source: docs/api/scenery-phet/bracket-node.md
Category: API | Tags: scenery-phet, BracketNode, bracket, label | Status: complete
========================================================================

# BracketNode

`BracketNode` (from `scenerystack/scenery-phet`) draws a single smooth bracket — two curved end caps joined by straight sides that meet at one rounded tip — with an optional label centered on that tip. It's the shape used to visually group a span of other content and attach one caption to the group, e.g. spanning several bars in a graph with a bracket labeled "total," rather than labeling each bar individually.

```ts
import { BracketNode } from 'scenerystack/scenery-phet';
import { Text } from 'scenerystack/scenery';
```

## A minimal example

```ts
const bracketNode = new BracketNode( {
  orientation: 'down',
  bracketLength: 150,
  labelNode: new Text( 'Total distance' )
} );
bracketNode.centerX = layoutBounds.centerX;
bracketNode.top = 50;
screenView.addChild( bracketNode );
```

With the default `orientation: 'down'`, the bracket's tip points downward and the label is centered just below it — position `bracketNode` so its straight top edge spans whatever content it's grouping, with the tip/label hanging below.

## Constructor

```ts
new BracketNode( providedOptions?: BracketNodeOptions )
```

`BracketNode` takes no required arguments — the bracket's length, tip position, and appearance are all options.

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `orientation` | `'down'` | `'left'` \| `'right'` \| `'up'` \| `'down'` — the direction the bracket's tip points |
| `labelNode` | `null` | An optional `Node` (typically `Text`) centered on the tip, offset by `spacing` |
| `bracketLength` | `100` | Overall length of the bracket, along its straight (non-tip) axis |
| `bracketTipPosition` | `0.5` | Where along `bracketLength` (exclusive `0` to `1`) the tip sits — `0.5` centers it |
| `bracketEndRadius` | `5` | Radius of the curved caps at each end of the bracket |
| `bracketTipRadius` | `6` | Radius of the two small curves forming the tip's point |
| `bracketStroke` | `'black'` | Stroke color/paint of the bracket path |
| `bracketLineWidth` | `1` | Stroke width of the bracket path |
| `spacing` | `2` | Gap between the bracket's tip and `labelNode` |

```ts
// A bracket pointing right, with its tip 30% of the way down its length.
const sideBracket = new BracketNode( {
  orientation: 'right',
  bracketLength: 80,
  bracketTipPosition: 0.3,
  labelNode: new Text( 'Δy' )
} );
```

::: tip `bracketTipPosition` must leave room for the end and tip radii
`BracketNode` is built as a horizontal, downward-pointing shape and then rotated into place for other orientations. It asserts that the computed tip position falls strictly between `bracketEndRadius + bracketTipRadius` and `bracketLength - ( bracketEndRadius + bracketTipRadius )` — pushing `bracketTipPosition` too close to `0` or `1` (especially combined with large radii) throws at construction rather than silently clipping the shape.
:::


========================================================================
Page: BucketFront and BucketHole
URL: https://veillette.github.io/Almanach/api/scenery-phet/bucket-front-and-hole
Source: docs/api/scenery-phet/bucket-front-and-hole.md
Category: API | Tags: scenery-phet, BucketFront, BucketHole, bucket, drag-and-drop | Status: complete
========================================================================

# BucketFront and BucketHole

`BucketFront` and `BucketHole` (both from `scenerystack/scenery-phet`) are the two view halves of the "bucket" UI element used across PhET sims for dragging model objects (atoms, balls, particles) in and out of a container. Together they create the illusion of depth: `BucketHole` is added to the scene graph *behind* the draggable contents, and `BucketFront` is added *in front* of them, so a dragged object visually passes "into" the bucket's opening as it's released.

Both Nodes are purely presentational — they read their shape, position, and colors from a [`Bucket`](/api/phetcommon/bucket) model instance (or a subclass like `SphereBucket`) and a `ModelViewTransform2`, but do nothing on their own with the objects being dragged. That's on you (or a helper like a drag listener) to implement, typically by reparenting a dragged object's Node between "in front of `BucketHole`, behind `BucketFront`" and "in front of `BucketFront`" as it's picked up and released.

```ts
import { BucketFront, BucketHole } from 'scenerystack/scenery-phet';
import { Bucket } from 'scenerystack/phetcommon';
import { ModelViewTransform2 } from 'scenerystack/phetcommon';
import { Vector2, Dimension2 } from 'scenerystack/dot';
```

## A minimal example

```ts
const bucket = new Bucket( {
  position: new Vector2( 0, 0 ),
  size: new Dimension2( 220, 60 ),
  baseColor: '#4d92c0',
  captionText: 'Atoms'
} );

const modelViewTransform = ModelViewTransform2.createIdentity();

const bucketHole = new BucketHole( bucket, modelViewTransform );
const bucketFront = new BucketFront( bucket, modelViewTransform );

// Layer order matters: hole first, then draggable contents, then front.
screenView.addChild( bucketHole );
screenView.addChild( atomsLayer ); // the draggable content Nodes
screenView.addChild( bucketFront );
```

::: tip The model class lives in `phetcommon`, not here
`Bucket` (and its contents-managing subclass `SphereBucket`) is exported from `scenerystack/phetcommon` and is entirely separate from these two view Nodes — see [`Bucket`](/api/phetcommon/bucket) for the model-side API (`holeShape`, `containerShape`, `addParticleFirstOpen()`, etc.). `BucketFront`/`BucketHole` never mutate the model; they only read its shapes and colors to draw themselves and reposition themselves at `bucket.position`.
:::

## Constructors

```ts
new BucketFront(
  bucket: Bucket,
  modelViewTransform: ModelViewTransform2,
  providedOptions?: BucketFrontOptions
)

new BucketHole(
  bucket: Bucket,
  modelViewTransform: ModelViewTransform2,
  providedOptions?: BucketHoleOptions
)
```

Both constructors set the Node's `translation` from `modelViewTransform.modelToViewPosition( bucket.position )` — you don't position them manually.

## BucketFront

`BucketFront` draws the tilted 3D-ish body of the bucket (`bucket.containerShape`, filled with a left-to-right gradient derived from `bucket.baseColor`) and a caption label centered on it.

| Option | Default | Effect |
| --- | --- | --- |
| `labelNode` | an owned `Text` showing `bucket.captionText` | Supply your own label Node instead of the default caption text |
| `gradientLuminanceLeft` | `0.5` | Luminance adjustment (`-1` to `1`) applied to `bucket.baseColor` for the left edge of the front's gradient |
| `gradientLuminanceRight` | `-0.5` | Luminance adjustment for the right edge |

| Member | Description |
| --- | --- |
| `bucket` | Public read-only reference to the `Bucket` model this Node renders |
| `setLabel( labelNode )` | Swaps out the label Node shown on the bucket's front, re-centering it |

## BucketHole

`BucketHole` draws `bucket.holeShape` as a dark elliptical `Path` with a gradient (always black-to-light-gray, independent of `bucket.baseColor`) and a thin stroke — it has no options of its own beyond standard `NodeOptions`.

::: warning Add `BucketHole` and `BucketFront` on either side of the draggable contents
Neither Node clips or layers its sibling automatically — the "objects go into the bucket" illusion only works if *you* add `bucketHole`, then the layer holding the draggable contents, then `bucketFront`, in that z-order. Getting the order wrong makes dragged objects appear to sit permanently on top of (or disappear behind) the bucket.
:::


========================================================================
Page: Capacitor Visualization Nodes
URL: https://veillette.github.io/Almanach/api/scenery-phet/capacitor-visualization-nodes
Source: docs/api/scenery-phet/capacitor-visualization-nodes.md
Category: API | Tags: scenery-phet, CapacitorNode, PlateNode, PlateChargeNode, EFieldNode, ElectronChargeNode, CapacitorConstants, capacitor | Status: complete
========================================================================

# Capacitor Visualization Nodes

`CapacitorNode` (from `scenerystack/scenery-phet`, under `scenery-phet/js/capacitor/`) draws a pseudo-3D parallel-plate capacitor: two foreshortened plates with a vacuum gap between them, optional `+`/`-` charge symbols distributed across each plate's top face, and optional electric-field arrows in the gap. It was built for PhET's Capacitor Lab sims and is also reused by Circuit Construction Kit for its capacitor component — it's a model-driven composite `Node`, not a standalone drawing primitive, and expects a small cluster of collaborating pieces (a capacitor-shaped model object, a [`YawPitchModelViewTransform3`](/api/scenery-phet/yaw-pitch-model-view-transform3), and visibility Properties) rather than plain constructor arguments.

This page documents `CapacitorNode` and the pieces it assembles: `PlateNode` (one plate, with an internal `PlateChargeNode`), `EFieldNode` (the field-line canvas layer), the standalone `ElectronChargeNode` (a single shaded electron, used elsewhere for wire/circuit charge animations), and the `CapacitorConstants` shared defaults. All of these are implemented in plain JavaScript (not TypeScript) in the real source, so constructor parameter types below are inferred from JSDoc comments rather than a `.d.ts` file.

```ts
import { CapacitorNode, CapacitorConstants, YawPitchModelViewTransform3 } from 'scenerystack/scenery-phet';
import { NumberProperty, Property } from 'scenerystack/axon';
import { Bounds3 } from 'scenerystack/dot';
import { Orientation } from 'scenerystack/phet-core';
```

## A minimal example

`CapacitorNode`'s first argument is a `circuit`-shaped object exposing a `.capacitor` (itself exposing plate-size/separation/charge/voltage Properties and a `getEffectiveEField()` method), plus `.maxPlateCharge` and `.maxEffectiveEField` used to normalize the charge/field density. A real sim gets this from its circuit model; here it's assembled by hand to show the shape `CapacitorNode` expects:

```ts
const capacitor = {
  plateSizeProperty: new Property( new Bounds3(
    -0.0075, 0, -0.0075,
    0.0075, CapacitorConstants.PLATE_HEIGHT, 0.0075
  ) ),
  plateSeparationProperty: new NumberProperty( CapacitorConstants.PLATE_SEPARATION_RANGE.defaultValue ),
  plateChargeProperty: new NumberProperty( 0 ),
  plateVoltageProperty: new NumberProperty( 0 ),
  getEffectiveEField: () => 0
};

const circuit = {
  capacitor,
  maxPlateCharge: 2.7e-12,
  maxEffectiveEField: 4e6
};

const modelViewTransform = new YawPitchModelViewTransform3();
const plateChargeVisibleProperty = new Property( true );
const electricFieldVisibleProperty = new Property( true );

const capacitorNode = new CapacitorNode(
  circuit,
  modelViewTransform,
  plateChargeVisibleProperty,
  electricFieldVisibleProperty,
  { orientation: Orientation.VERTICAL }
);

capacitor.plateChargeProperty.value = 1.5e-12; // redraws the '+'/'-' charge grid on the plates
```

## Constructor

```ts
new CapacitorNode(
  circuit: { capacitor: Capacitor, maxPlateCharge: number, maxEffectiveEField: number },
  modelViewTransform: YawPitchModelViewTransform3,
  plateChargeVisibleProperty: Property<boolean>,
  electricFieldVisibleProperty: Property<boolean>,
  options?: { orientation?: Orientation, includeChargeNode?: boolean }
)
```

`options.orientation` (default `Orientation.VERTICAL`, from [`scenerystack/phet-core`](/api/phet-core/orientation)) affects only how negative-charge minus signs are drawn (see `PlateChargeNode` below); it does not rotate the whole node. `options.includeChargeNode` (default `true`) can be set `false` to skip building the charge overlay entirely — used by toolbox icons where charges are never shown and the extra canvas bounds would otherwise throw off icon sizing.

## Methods

| Method | Effect |
| --- | --- |
| `frontSideContainsSensorPoint( globalPoint )` / `backSideContainsSensorPoint( globalPoint )` | Hit-test a global point against the top or bottom plate, used to detect a voltmeter probe touching a specific plate face |
| `getTopPlateClipShapeToGlobal()` / `getBottomPlateClipShapeToGlobal()` | Global-coordinate clip `Shape`s used to mask wires or animated charges as they enter/exit the capacitor |
| `getPlatesBounds()` | `Bounds2` enclosing both plates, computed from their current layout |

The node automatically re-lays out its plates whenever `capacitor.plateSizeProperty` or `plateSeparationProperty` changes, and toggles per-plate charge visibility / field-line visibility in response to the two visibility Properties passed to the constructor — there's no separate "update" call to make from application code.

## PlateNode

`PlateNode` draws a single pseudo-3D plate (a `BoxNode` — a thin foreshortened box with top/front/right-side faces) and owns a child `PlateChargeNode` for that plate's charge overlay.

```ts
new PlateNode(
  capacitor: Capacitor,
  modelViewTransform: YawPitchModelViewTransform3,
  polarity: typeof CapacitorConstants.POLARITY.POSITIVE,  // pass CapacitorConstants.POLARITY.POSITIVE or .NEGATIVE — these are enum values, not the strings 'POSITIVE'/'NEGATIVE'
  maxPlateCharge: number,
  orientation: Orientation,
  includeChargeNode?: boolean          // default true
)
```

| Method | Effect |
| --- | --- |
| `setChargeVisible( visible )` | Shows/hides this plate's `PlateChargeNode` |
| `setBoxSize( size: Bounds3 )` | Resizes the plate (inherited from `BoxNode`); no-ops if `size` already equals the current size |

## PlateChargeNode

A `CanvasNode` that paints an integer number of `+`/`-` symbols in a grid across the portion of the plate facing the vacuum gap, linearly proportional to `capacitor.plateChargeProperty` (clamped between 1 and 625 charges once any charge is present, and normalized against `maxPlateCharge`). Positive charges are drawn in `PhetColorScheme.RED_COLORBLIND`; negative charges are drawn in `'blue'`, as a short horizontal rectangle whose orientation (`VERTICAL`/`HORIZONTAL`) affects only its exact offset.

| Method | Effect |
| --- | --- |
| `isPositivelyCharged()` | `true` if the plate's charge sign matches its own `polarity` option |
| `getNumberOfCharges( plateCharge, maxPlateCharge )` | The symbol count for a given charge, before layout into a grid |
| `getGridSize( numberOfObjects, width, height )` | Chooses rows/columns for the charge grid that best approximates a square packing over the given aspect ratio |

## EFieldNode

A `CanvasNode` that paints evenly-spaced vertical arrows between the plates, representing the effective E-field. Line spacing is inversely proportional to the square root of `|effectiveEField|` (denser field ⇒ closer-spaced lines), and arrows point down for a positive field, up for negative. It repaints whenever plate size, separation, or voltage changes and the node is visible.

## ElectronChargeNode

A small, self-contained `Node` — not part of the capacitor's own plate rendering, but shipped alongside these pieces and reused wherever a single shaded "blue sphere with a white minus sign" electron glyph is needed (e.g. animating charge flow through a wire in Circuit Construction Kit).

```ts
new ElectronChargeNode( providedOptions?: {
  sphereOpacity?: number;   // default 1
  minusSignOpacity?: number; // default 1
  radius?: number;          // default 10
} & NodeOptions )
```

## CapacitorConstants

A plain object of shared numeric defaults, reused by the model and by `PlateNode`/`PlateChargeNode` for layout:

| Constant | Value | Meaning |
| --- | --- | --- |
| `PLATE_WIDTH_RANGE` | `RangeWithValue( 0.01, 0.02, √(200/1e6) )` meters | Legal plate width range; default corresponds to a 200 mm² plate area |
| `PLATE_HEIGHT` | `0.0005` meters | Fixed plate thickness |
| `PLATE_SEPARATION_RANGE` | `RangeWithValue( 0.002, 0.01, 0.006 )` meters | Legal gap range between plates |
| `POLARITY` | `EnumerationDeprecated.byKeys(['POSITIVE', 'NEGATIVE'])` | The two values accepted by `PlateNode`'s `polarity` parameter |

`PLATE_WIDTH_RANGE` and `PLATE_SEPARATION_RANGE` are [`RangeWithValue`](/api/dot/range-with-value) instances, so each carries its own `.defaultValue` in addition to `.min`/`.max`.

::: warning These are JavaScript files with untyped, model-shaped constructor arguments
Unlike most of `scenery-phet`, `CapacitorNode`, `PlateNode`, `PlateChargeNode`, `EFieldNode`, and `CapacitorConstants` are still plain `.js` files (only `ElectronChargeNode` has been converted to TypeScript). Their constructors expect a `Capacitor`-model-shaped object with specific Property names (`plateSizeProperty`, `plateSeparationProperty`, `plateChargeProperty`, `plateVoltageProperty`, `getEffectiveEField()`) rather than a generic `NodeOptions`-style bag — reusing these nodes outside a capacitor-shaped model means constructing an object that duck-types the same shape, as in the example above.
:::


========================================================================
Page: CloseButton
URL: https://veillette.github.io/Almanach/api/scenery-phet/close-button
Source: docs/api/scenery-phet/close-button.md
Category: API | Tags: scenery-phet, CloseButton, button | Status: verified
========================================================================

# CloseButton

`CloseButton` (from `scenerystack/scenery-phet`) is a [`RectangularPushButton`](/api/sun/rectangular-push-button) preloaded with a white "X" icon (built from a `Shape`, not an image) on PhET's standard colorblind-safe red background. It's the standard control for dismissing a dialog, popup, or closable panel — distinct from [`BackButton`](/api/scenery-phet/back-button), which navigates rather than dismisses.

```ts
import { CloseButton } from 'scenerystack/scenery-phet';
```

## A minimal example

```ts
const closeButton = new CloseButton( {
  listener: () => {
    dialog.hide();
  },
  tandem: tandem.createTandem( 'closeButton' )
} );
```

## Options

`CloseButtonOptions` adds two options on top of the [same `RectangularPushButtonOptions`](/api/sun/rectangular-push-button) every rectangular push button accepts — `content` is fixed and not settable, since the "X" icon defines this button.

| Option | Default | Effect |
| --- | --- | --- |
| `iconLength` | `16` | Side length of the square "X" icon |
| `pathOptions` | `{ stroke: 'white', lineWidth: 2.5, lineCap: 'round' }` | Options forwarded to the `Path` that draws the "X" strokes |
| `baseColor` | `PhetColorScheme.RED_COLORBLIND` | A red tuned to remain distinguishable in colorblind testing, rather than a plain CSS `'red'` |
| `xMargin` / `yMargin` | `4` / `4` | Margin between the icon and the button edge |
| `soundPlayer` | the shared `'generalClose'` sound player | Overridable if a different button in the same sim needs a distinct sound |

::: tip Use `PhetColorScheme.RED_COLORBLIND`, not plain `'red'`, for anything red
`CloseButton`'s default background isn't CSS `'red'` — it's `PhetColorScheme.RED_COLORBLIND`, chosen specifically to stay distinguishable from green under common forms of color blindness. If you ever need a custom red element elsewhere in a sim, reuse that same constant instead of a literal color string.
:::


========================================================================
Page: ComboBoxDisplay
URL: https://veillette.github.io/Almanach/api/scenery-phet/combo-box-display
Source: docs/api/scenery-phet/combo-box-display.md
Category: API | Tags: scenery-phet, ComboBoxDisplay, NumberDisplay, ComboBox | Status: complete
========================================================================

# ComboBoxDisplay

`ComboBoxDisplay<T>` (from `scenerystack/scenery-phet`) combines a [`ComboBox`](/api/sun/combo-box) with a [`NumberDisplay`](/api/scenery-phet/number-display) per item: instead of choosing among static labels, the user chooses which of several *dynamic numeric quantities* to display, and the selected item's live value is what's shown in the closed combo box. It's the control to reach for when a sim lets the user pick, say, "voltage" vs. "current" vs. "resistance" to watch in one readout, rather than showing all three permanently.

Ordinary `ComboBox` items are built once with a `createNode` factory and don't grow or shrink afterward — `ComboBoxDisplay` adds the bookkeeping needed to keep each item's `NumberDisplay` from resizing as its underlying number changes, so the dropdown's layout doesn't jitter as values update in the background.

```ts
import { ComboBoxDisplay, type ComboBoxDisplayItem } from 'scenerystack/scenery-phet';
import { Property } from 'scenerystack/axon';
import { Node } from 'scenerystack/scenery';
import { Range } from 'scenerystack/dot';
```

## A minimal example

```ts
type Quantity = 'voltage' | 'current';
const choiceProperty = new Property<Quantity>( 'voltage' );

const voltageProperty = new Property<number | null>( 9 );
const currentProperty = new Property<number | null>( 0.5 );

const listParent = new Node();

const items: ComboBoxDisplayItem<Quantity>[] = [
  { choice: 'voltage', numberProperty: voltageProperty, range: new Range( 0, 12 ), units: 'V' },
  { choice: 'current', numberProperty: currentProperty, range: new Range( 0, 2 ), units: 'A' }
];

const display = new ComboBoxDisplay( choiceProperty, items, listParent, {
  tandem: tandem.createTandem( 'quantityDisplay' )
} );

screenView.addChild( display );
screenView.addChild( listParent ); // must be an ancestor high enough not to be clipped
```

## Constructor

```ts
new ComboBoxDisplay<T>(
  choiceProperty: Property<T>,
  items: ComboBoxDisplayItem<T>[],
  listParent: Node,
  providedOptions?: ComboBoxDisplayOptions
)
```

As with plain `ComboBox`, `listParent` needs to be added to the scene graph as an ancestor high enough that the popup list isn't clipped or drawn behind other content.

## `ComboBoxDisplayItem<T>`

| Field | Effect |
| --- | --- |
| `choice` | The value of `choiceProperty` this item corresponds to |
| `numberProperty` | `TReadOnlyProperty<number \| null>` — the live value shown when this item is selected |
| `range` | The display range used to size this item's `NumberDisplay` (as with `NumberDisplay` itself, this bounds the layout width, not the value) |
| `units` | A string or `TReadOnlyProperty<string>` label appended to the formatted value |
| `numberDisplayOptions` | Per-item overrides, applied on top of `ComboBoxDisplayOptions.numberDisplayOptions` |
| `tandemName` | Tandem name for this item, as with a regular `ComboBoxItem` |

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `numberDisplayOptions` | borderless, right-aligned, zero-margin `NumberDisplay` styling | Propagated to every item's internal `NumberDisplay`; overridden per-item by that item's own `numberDisplayOptions` |
| `align` | `'right'` | Inherited from `ComboBoxOptions` — right-aligned suits numeric content better than `ComboBox`'s usual default |

::: tip Each item's `NumberDisplay` is capped to its initial size
`ComboBoxDisplay` sets `maxWidth`/`maxHeight` on each item's `NumberDisplay` to its size at construction time, so a value growing wider later (more digits, a longer unit string) gets clipped rather than resizing the dropdown. Pick a `range` (and `decimalPlaces`, if you override `numberDisplayOptions`) generous enough to cover every value the item will ever show.
:::


========================================================================
Page: ConductivityTesterNode
URL: https://veillette.github.io/Almanach/api/scenery-phet/conductivity-tester-node
Source: docs/api/scenery-phet/conductivity-tester-node.md
Category: API | Tags: scenery-phet, ConductivityTesterNode, chemistry, probe, wire | Status: complete
========================================================================

# ConductivityTesterNode

`ConductivityTesterNode` (from `scenerystack/scenery-phet`) draws a light bulb connected by wires to a battery and two draggable probes (a red "+" and a black "−"). When both probes are immersed in a conductive solution, the model sets `brightnessProperty` above zero and the bulb glows — the classic "does this liquid conduct electricity" apparatus used in chemistry sims like Acid-Base Solutions. It reuses [`ProbeNode`](/api/scenery-phet/probe-node)-style probe graphics and [`WireNode`](/api/scenery-phet/wire-node)-style cubic-bezier wires internally (as private helper classes local to this file, not the standalone exported `ProbeNode`/`WireNode`).

```ts
import { ConductivityTesterNode } from 'scenerystack/scenery-phet';
import { NumberProperty, Property } from 'scenerystack/axon';
import { Vector2 } from 'scenerystack/dot';
```

## A minimal example

```ts
const brightnessProperty = new NumberProperty( 0, { range: { min: 0, max: 1 } } );
const positionProperty = new Property( new Vector2( 0, 0 ) );
const positiveProbePositionProperty = new Property( new Vector2( -0.5, -1 ) );
const negativeProbePositionProperty = new Property( new Vector2( 0.5, -1 ) );

const conductivityTesterNode = new ConductivityTesterNode(
  brightnessProperty,
  positionProperty,
  positiveProbePositionProperty,
  negativeProbePositionProperty,
  { tandem: tandem.createTandem( 'conductivityTesterNode' ) }
);
```

## Constructor

```ts
new ConductivityTesterNode(
  brightnessProperty: TReadOnlyProperty<number>,
  positionProperty: TProperty<Vector2>,
  positiveProbePositionProperty: TProperty<Vector2>,
  negativeProbePositionProperty: TProperty<Vector2>,
  providedOptions: ConductivityTesterNodeOptions // tandem is required
)
```

All four positions are in the model coordinate frame; `positionProperty` is the bottom-center of the bulb, and moving it translates both probes with it (their relative offset is preserved).

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `modelViewTransform` | identity | Projects all four model positions into view coordinates |
| `probeSize` | `Dimension2(20, 68)` | Shared dimensions for both probe plates |
| `probeDragYRange` | `null` | If set, constrains how far probes can be dragged vertically relative to `positionProperty`, in view coordinates; `null` means unconstrained |
| `positiveProbeFill` / `negativeProbeFill` | `'red'` / `'black'` | Probe plate colors |
| `bulbToBatteryWireLength` | `40` | View-coordinate length of the wire between bulb and battery |
| `keyboardDragListenerOptions` | — | Forwarded to the shared `KeyboardDragListener` that moves both probes together |

## Instance API

| Member | Effect |
| --- | --- |
| `shortCircuit` *(getter/setter)* | Shows/hides a "Short Circuit" label above the bulb; it's the caller's responsibility to also set `brightnessProperty` appropriately when toggling this |

::: warning The two probes always drag together, vertically only
`ConductivityTesterNode` wires **one** `DragListener` to both probes (`positiveProbe` and `negativeProbe` share `probeDragListener`/`probeKeyboardDragListener`), and that listener only ever changes their shared y-coordinate — there's no way to drag the probes independently or horizontally with the built-in listeners. If your sim needs independently movable probes, you'll need to compose your own probe graphics rather than repurposing this Node's drag behavior.
:::


========================================================================
Page: Developer Overlay Nodes
URL: https://veillette.github.io/Almanach/api/scenery-phet/dev-overlay-nodes
Source: docs/api/scenery-phet/dev-overlay-nodes.md
Category: API | Tags: scenery-phet, CanvasWarningNode, PointerCoordinatesNode, debug, developer | Status: complete
========================================================================

# Developer Overlay Nodes

`CanvasWarningNode` and `PointerCoordinatesNode` (both from `scenerystack/scenery-phet`) are two unrelated, small `Node`s that share a common theme: neither is meant to appear in a finished sim for end users. One is a fallback warning shown when a sim can't get WebGL and had to degrade to Canvas rendering; the other is a debug overlay for developers who need to see live pointer coordinates in both view and model space while working on layout or a model-view transform. They're grouped on this page because each is small enough that a dedicated page would mostly restate this same "developer/debug-only" framing twice.

```ts
import { CanvasWarningNode, PointerCoordinatesNode } from 'scenerystack/scenery-phet';
import { ModelViewTransform2 } from 'scenerystack/phetcommon';
```

## CanvasWarningNode

An `HBox` combining a warning-triangle icon with a two-line message ("your browser doesn't support WebGL" style copy, pulled from translated string Properties), used by sims that render some content in WebGL and need a graceful, clickable fallback notice when the runtime has to use Canvas instead. It takes no constructor arguments — there's nothing to configure.

```ts
const warningNode = new CanvasWarningNode();
```

Clicking (or tapping) the node opens `https://phet.colorado.edu/webgl-disabled-page` in a new tab/popup, with the current locale appended, via `openPopup` — it's cursor-styled as a link (`cursor: 'pointer'`) and its mouse/touch areas are dilated to its full local bounds so it's easy to tap on a phone.

::: tip Not meant to be conditionally sized or restyled
`CanvasWarningNode` has no options at all — if you need different copy or layout for a WebGL-fallback message, compose your own `Node` from the same pieces (`HBox`/`VBox`/`Text`/`Path`) rather than trying to configure this one; it's a fixed, PhET-house-style notice, not a general-purpose warning banner.
:::

## PointerCoordinatesNode

A tiny `Node` (a background `Rectangle` behind a `RichText`, styled with [`PhetFont`](/api/scenery-phet/phet-font) by default) that follows the pointer and displays both its view-space and model-space coordinates, updated on every `move` event, using a [`ModelViewTransform2`](/api/phetcommon/model-view-transform) to convert between the two. It's explicitly a debugging tool — the doc comment on the source calls out that it was "originally implemented for use in gas-properties... exclusively for debugging" — not something to ship visible in a released sim.

```ts
const modelViewTransform = ModelViewTransform2.createIdentity();

const pointerCoordinatesNode = new PointerCoordinatesNode( modelViewTransform, {
  modelDecimalPlaces: 2,
  viewDecimalPlaces: 0
} );

// Typically added directly to a ScreenView, on top of everything else:
// screenView.addChild( pointerCoordinatesNode );
```

### Constructor

```ts
new PointerCoordinatesNode(
  modelViewTransform: ModelViewTransform2,
  providedOptions?: PointerCoordinatesNodeOptions   // NOT propagated to the Node superclass
)
```

### Options

| Option | Default | Effect |
| --- | --- | --- |
| `display` | `phet.joist.display` (read off a global) | The `Display` to attach the pointer-move listener to |
| `pickable` | `false` | Forwarded to the Node's own `pickable`, kept `false` so the overlay never itself intercepts input |
| `font` | `PhetFont(14)` | Font for the coordinate text |
| `textColor` | `'black'` | Text fill |
| `align` | `'center'` | `RichText` horizontal alignment |
| `modelDecimalPlaces` | `1` | Decimal places shown for the model-space `(x, y)` pair |
| `viewDecimalPlaces` | `0` | Decimal places shown for the view-space `(x, y)` pair |
| `backgroundColor` | `'rgba(255,255,255,0.5)'` | Fill of the background rectangle behind the text |

::: warning Adds a listener directly to the Display, not to itself
`PointerCoordinatesNode` attaches its `move` listener to the `Display` (`options.display.addInputListener(...)`), not to the node instance — this is called out explicitly in the source comment because Scenery doesn't support routing the same pointer event through two different trails, so a Display-level listener is the only way to see every pointer move regardless of what else on screen is consuming events. One consequence: it keeps receiving and reacting to pointer-move events **even when its current screen is inactive**, since Display-level listeners aren't scoped to the active screen.
:::


========================================================================
Page: Drawer
URL: https://veillette.github.io/Almanach/api/scenery-phet/drawer
Source: docs/api/scenery-phet/drawer.md
Category: API | Tags: scenery-phet, Drawer, animation | Status: complete
========================================================================

# Drawer

`Drawer` (from `scenerystack/scenery-phet`) wraps an arbitrary `contentsNode` in a clipped container with a clickable handle: clicking the handle slides the contents in and out of view (by default, animated), the way a physical drawer opens and closes. It's used wherever a sim wants to tuck away optional content — a mini legend, a secondary control — behind a single, low-profile handle instead of an [`AccordionBox`](/api/sun/accordion-box)'s title bar.

```ts
import { Drawer } from 'scenerystack/scenery-phet';
import { Text } from 'scenerystack/scenery';
```

## A minimal example

```ts
const contentsNode = new Text( 'Extra info goes here' );

const drawer = new Drawer( contentsNode, {
  open: false,
  handlePosition: 'top',
  tandem: tandem.createTandem( 'drawer' )
} );

screenView.addChild( drawer );

// Open/close programmatically:
drawer.openProperty.value = true;
```

Clicking the handle toggles `drawer.openProperty`; toggling `openProperty` yourself (or via PhET-iO) drives the same animation the handle click would.

## Constructor

```ts
new Drawer( contentsNode: Node, provideOptions?: DrawerOptions )
```

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `size` | `null` | If provided, the container is fixed at this `Dimension2` and `contentsNode` is scaled down (never up) to fit; if `null`, the container is sized to fit `contentsNode` exactly |
| `cornerRadius` | `0` | Corner radius of the container's background/border |
| `xMargin` / `yMargin` | `0` / `0` | Margin between `contentsNode` and the container edge, before any `size`-driven scaling |
| `open` | `true` | Whether the drawer starts open |
| `handlePosition` | `'top'` | `'top'` or `'bottom'` — which edge the handle (and the rounded corners on it) is drawn on |
| `handleSize` | `Dimension2( 70, 20 )` | Size of the handle bar |
| `handleFill` | `'rgb( 230, 230, 230 )'` | Fill color of the handle |
| `handleTouchAreaXDilation` / `handleTouchAreaYDilation` | `0` / `0` | Touch-area dilation around the handle |
| `grippyDotRows` / `grippyDotColumns` | `2` / `4` | Layout of the small "grippy" dots drawn on the handle |
| `beforeOpen` | makes `contentsNode` visible | Called immediately before opening starts |
| `afterClose` | hides `contentsNode` | Called immediately after closing finishes — the default behavior is why the drawer's content can safely keep updating only while visible |
| `animationEnabled` | `true` | Whether opening/closing is animated at all; `false` snaps instantly |
| `animationDuration` | `0.5` | Duration of the open/close animation, in seconds, using [`Animation`](/api/twixt/animation)'s `QUADRATIC_IN_OUT` easing |

## Public API

| Member | Description |
| --- | --- |
| `openProperty` | `Property<boolean>` — the drawer's open/closed state; settable directly or via the handle |
| `contentsNode` | The `Node` passed to the constructor |
| `reset( animationEnabled? )` | Returns `openProperty` to its initial value, optionally overriding whether that reset itself is animated |
| `animationEnabled` (get/set) | Whether future open/close transitions are animated |

::: tip `beforeOpen` / `afterClose` are how `contentsNode` avoids updating while hidden
By default, `Drawer` makes `contentsNode` invisible only *after* the close animation finishes, and visible again *before* the open animation starts — so if `contentsNode`'s own updates are gated on `node.visible`, they naturally pause while the drawer is fully closed. Overriding `beforeOpen`/`afterClose` replaces this behavior entirely, so re-implement the visibility toggle yourself if you still want it.
:::

::: warning `Drawer`'s handle is a distinct graphic from [`HandleNode`](/api/scenery-phet/handle-node)
`Drawer` draws its own small rounded pull-tab with dots — it does not compose a `HandleNode` internally, and there's no option to swap in one. If you need `HandleNode`'s grip-and-attachment look specifically, you'll need a custom container rather than `Drawer`.
:::


========================================================================
Page: EraserButton
URL: https://veillette.github.io/Almanach/api/scenery-phet/eraser-button
Source: docs/api/scenery-phet/eraser-button.md
Category: API | Tags: scenery-phet, EraserButton, button | Status: verified
========================================================================

# EraserButton

`EraserButton` (from `scenerystack/scenery-phet`) is a [`RectangularPushButton`](/api/sun/rectangular-push-button) preloaded with an eraser icon (an `Image` node built from an SVG asset baked into scenery-phet, not a `Shape`-based icon) and PhET's standard yellow button color. Use it for "clear" actions — wiping a drawing, clearing accumulated data points, removing user-placed objects — that are narrower in scope than a full [`ResetAllButton`](/api/scenery-phet/reset-all-button), which resets the entire screen.

```ts
import { EraserButton } from 'scenerystack/scenery-phet';
```

## A minimal example

```ts
const clearButton = new EraserButton( {
  listener: () => {
    pointsProperty.reset();
  },
  tandem: tandem.createTandem( 'eraserButton' )
} );
```

## Options

`EraserButtonOptions` adds one option on top of the [same `RectangularPushButtonOptions`](/api/sun/rectangular-push-button) every rectangular push button accepts (`listener`, `xMargin`/`yMargin`, `fireOnHold`, `enabledProperty`, `touchAreaXDilation`/`touchAreaYDilation`, …) — note that `content` is fixed and not settable, since the icon is what defines this button.

| Option | Default | Effect |
| --- | --- | --- |
| `iconWidth` | `20` | Width the eraser icon is scaled to (height follows from the image's aspect ratio) |
| `baseColor` | `PhetColorScheme.BUTTON_YELLOW` | Overridable, but yellow is the PhET-standard color for this button |

::: tip Keep the yellow base color unless there's a strong reason not to
`EraserButton`'s default `baseColor` matches `PhetColorScheme.BUTTON_YELLOW` — the same convention [`BackButton`](/api/scenery-phet/back-button) uses. Sims that recolor individual buttons ad hoc make the UI harder to scan at a glance; prefer leaving PhET's standard button colors alone and reserve custom colors for content that specifically needs to stand out.
:::


========================================================================
Page: EyeDropperNode
URL: https://veillette.github.io/Almanach/api/scenery-phet/eye-dropper-node
Source: docs/api/scenery-phet/eye-dropper-node.md
Category: API | Tags: scenery-phet, EyeDropperNode, fluid, dropper | Status: complete
========================================================================

# EyeDropperNode

`EyeDropperNode` (from `scenerystack/scenery-phet`) draws an eye dropper — glass bulb, glass body, and a red squeeze button — with a colored fluid shape visible inside the glass. Pressing and holding the button sets `isDispensingProperty` to `true` for as long as it's held, which is the hook your model uses to actually add fluid/particles to whatever the dropper is squeezed over. It's used in sims like pH Scale and Beer's Law Lab wherever the user needs to add a small, discrete amount of something by "squeezing."

```ts
import { EyeDropperNode } from 'scenerystack/scenery-phet';
import { Property } from 'scenerystack/axon';
```

## A minimal example

```ts
const isDispensingProperty = new Property( false );
const isEmptyProperty = new Property( false );

const dropperNode = new EyeDropperNode( {
  isDispensingProperty: isDispensingProperty,
  isEmptyProperty: isEmptyProperty,
  fluidColor: 'red',
  tandem: tandem.createTandem( 'dropperNode' )
} );

isDispensingProperty.link( isDispensing => {
  if ( isDispensing && !isEmptyProperty.value ) {
    // add fluid to the model here, once per frame while isDispensing is true
  }
} );
```

`EyeDropperNode`'s origin is the bottom-center of its tip, matching the point fluid visually emerges from — the same convention [`FaucetNode`](/api/scenery-phet/faucet-node) uses for its spout.

## Constructor

```ts
new EyeDropperNode( provideOptions?: EyeDropperNodeOptions )
```

`EyeDropperNode` takes no required arguments — all of its state is supplied through options (or the owned defaults created for you).

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `isDispensingProperty` | an owned `Property<boolean>( false )` | `true` while the button is held down; this is the signal your model listens to |
| `isEmptyProperty` | an owned `Property<boolean>( false )` | When `true`, the glass renders as visibly empty (a different background image) and the fluid shape is hidden |
| `fluidColor` | `'yellow'` | Fill color of the visible fluid inside the glass, ignored while `isEmptyProperty` is `true` |
| `buttonOptions` | `{ touchAreaDilation: 15, baseColor: 'red', radius: 18, listenerOptions: { attach: false } }` | Propagated to the internal `RoundMomentaryButton` that drives `isDispensingProperty` |

## Public API

| Member | Description |
| --- | --- |
| `button` | The internal button `Node`, exposed so a client can hide it (e.g. to make the dropper non-interactive) |
| `fluidColor` (get/set) | The fluid color, equivalent to `getFluidColor()` / `setFluidColor()` |
| `EyeDropperNode.TIP_WIDTH`, `.TIP_HEIGHT`, `.GLASS_WIDTH` | Static geometry constants, useful if you need to draw fluid emerging from the tip yourself |
| `EyeDropperNode.GLASS_MIN_Y`, `.GLASS_MAX_Y` | Static y-extents of the glass, relative to the bottom-center origin, useful for positioning a label inside the glass |

::: tip The button only sets a Property — it never touches your model directly
Squeezing the bulb toggles `isDispensingProperty` while held (using a momentary, not toggle, button internally); `EyeDropperNode` has no notion of "how much fluid" or "what fluid" is being added. Link a listener to `isDispensingProperty` (typically inside a `step()` call, so it runs once per animation frame) to perform the actual model update, and set `isEmptyProperty` yourself once the model runs out.
:::


========================================================================
Page: FaceNode
URL: https://veillette.github.io/Almanach/api/scenery-phet/face-node
Source: docs/api/scenery-phet/face-node.md
Category: API | Tags: scenery-phet, FaceNode, feedback, face | Status: verified
========================================================================

# FaceNode

`FaceNode` (from `scenerystack/scenery-phet`) draws a circular head with two eyes and either a smiling or frowning mouth — a small, self-contained way to give users visual feedback for a correct/incorrect result. It has no Property to bind to; you construct it once and call `smile()` or `frown()` imperatively whenever the state you're representing changes.

```ts
import { FaceNode } from 'scenerystack/scenery-phet';
```

## A minimal example

```ts
const faceNode = new FaceNode( 100 ); // headDiameter = 100

// Later, respond to a check:
if ( isCorrect ) {
  faceNode.smile();
}
else {
  faceNode.frown();
}
```

## Constructor

```ts
new FaceNode( headDiameter: number, providedOptions?: FaceNodeOptions )
```

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `headFill` | `Color.YELLOW` | Fill of the circular head |
| `headStroke` | `null` (derives a darker shade of `headFill` automatically) | Stroke around the head; if you supply your own, it replaces the auto-derived one |
| `eyeFill` | `'black'` | Fill of both eyes |
| `mouthStroke` | `'black'` | Stroke of the smile/frown arc |
| `headLineWidth` | `1` | Stroke width of the head outline |

## Methods

| Method | Effect |
| --- | --- |
| `smile()` | Shows the smiling mouth, hides the frowning mouth; returns `this` |
| `frown()` | Shows the frowning mouth, hides the smiling mouth; returns `this` |

::: tip Both mouths always exist; only one is ever hidden
`FaceNode` builds both the smile and the frown `Path`s up front and toggles their `visible` flags — it never destroys or recreates geometry when you switch expressions, and it starts in the smiling state by default. `headDiameter` scales every other feature (eye size, mouth size, stroke widths) proportionally, so there's no separate way to resize the mouth or eyes independently of the head.
:::


========================================================================
Page: FaucetNode
URL: https://veillette.github.io/Almanach/api/scenery-phet/faucet-node
Source: docs/api/scenery-phet/faucet-node.md
Category: API | Tags: scenery-phet, FaucetNode, faucet, fluid, flow-rate | Status: verified
========================================================================

# FaucetNode

`FaucetNode` (from `scenerystack/scenery-phet`) draws a faucet whose interactive part is a "shooter" that behaves like a horizontal slider — sliding it out increases a `flowRateProperty`, and the visuals (pipe, spout, track, knob) are all pre-built PNG-based image assets. It's used in fluid/flow sims like pH Scale and Molarity wherever the user needs to turn on a flow of something.

```ts
import { FaucetNode } from 'scenerystack/scenery-phet';
import { Property } from 'scenerystack/axon';
```

## A minimal example

```ts
const maxFlowRate = 10; // L/s
const flowRateProperty = new Property( 0 );
const enabledProperty = new Property( true );

const faucetNode = new FaucetNode( maxFlowRate, flowRateProperty, enabledProperty, {
  tandem: tandem.createTandem( 'faucetNode' )
} );
```

`FaucetNode`'s origin is the bottom-center of its spout, which makes it easy to align against wherever fluid should visually emerge.

## Constructor

```ts
new FaucetNode(
  maxFlowRate: number,
  flowRateProperty: Property<number>,
  enabledProperty: TReadOnlyProperty<boolean>,
  providedOptions?: FaucetNodeOptions
)
```

`FaucetNode` extends `AccessibleSlider`, so `flowRateProperty` also drives keyboard alt-input the same way a slider's value would.

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `horizontalPipeLength` | spout's x-center | Distance from the left edge of the horizontal pipe to the spout's center |
| `verticalPipeLength` | `43` | Length of the vertical pipe connecting the body to the spout |
| `closeOnRelease` | `true` | If `true`, releasing the shooter always sets flow to zero ("close-on-release"); if `false`, it stays wherever released ("slider mode") |
| `tapToDispenseEnabled` | `true` | Tapping the shooter without dragging toggles a burst of flow on/off |
| `tapToDispenseAmount` | `0.25 * maxFlowRate` | Amount dispensed per tap, in L |
| `tapToDispenseInterval` | `500` | Duration (ms) that a tap-to-dispense burst runs |
| `interactiveProperty` | always-`true` `Property` | When `false`, hides the shooter and track entirely (the flow control becomes non-interactive) |
| `rasterizeHorizontalPipeNode` | `false` | Rasterizes the tiled horizontal pipe image, to work around flickering seen in some sims |
| `grabSoundPlayer` / `releaseSoundPlayer` | shared grab/release sounds | Sounds played on drag-start / on flow reaching zero |
| `shooterOptions` | — | Options for the internal shooter (e.g. `knobScale`, touch/mouse area dilation) |

::: warning `closeOnRelease` defaults to `true`
Out of the box, dragging the shooter and letting go snaps the flow rate back to zero — it is **not** slider-like persistence by default. If you want the faucet to stay open at whatever rate the user left it at (as with a real tap), you must explicitly pass `closeOnRelease: false`.
:::


========================================================================
Page: FineCoarseSpinner
URL: https://veillette.github.io/Almanach/api/scenery-phet/fine-coarse-spinner
Source: docs/api/scenery-phet/fine-coarse-spinner.md
Category: API | Tags: scenery-phet, FineCoarseSpinner, spinner, NumberDisplay | Status: complete
========================================================================

# FineCoarseSpinner

`FineCoarseSpinner` (from `scenerystack/scenery-phet`) lays out five subcomponents in a row — `<  <<  [ value ]  >>  >` — giving the user both fine (single-step) and coarse (multi-step) control over one `NumberProperty` from a single control. It's the arrangement to reach for whenever a plain increment/decrement spinner's step size is too coarse for precise adjustment but too fine for large jumps — letting both live side by side instead of forcing a compromise value.

```ts
import { FineCoarseSpinner } from 'scenerystack/scenery-phet';
import { NumberProperty } from 'scenerystack/axon';
import { Range } from 'scenerystack/dot';
```

## A minimal example

```ts
const volumeProperty = new NumberProperty( 50, { range: new Range( 0, 100 ) } );

const volumeSpinner = new FineCoarseSpinner( volumeProperty, {
  deltaFine: 1,
  deltaCoarse: 10,
  tandem: tandem.createTandem( 'volumeSpinner' )
} );
```

Clicking `<`/`>` changes `volumeProperty.value` by `deltaFine`; clicking `<<`/`>>` changes it by `deltaCoarse` (clamped so it never overshoots `numberProperty.range`). All four buttons automatically disable themselves when the value is already at `range.min` or `range.max`.

## Constructor

```ts
new FineCoarseSpinner(
  numberProperty: NumberProperty,
  providedOptions?: FineCoarseSpinnerOptions
)
```

`numberProperty.range` (from its `rangeProperty`) supplies both the enabled-range checks and the range shown by the internal [`NumberDisplay`](/api/scenery-phet/number-display) — there's no separate range argument.

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `deltaFine` | `1` | Amount `<`/`>` change the value by per click |
| `deltaCoarse` | `10` | Amount `<<`/`>>` change the value by per click |
| `spacing` | `10` | Horizontal space between the five subcomponents |
| `arrowsSoundPlayer` | the shared `'pushButton'` sound | Sound played when any arrow button is pressed (and, via keyboard, on Home/End) |
| `numberDisplayOptions` | — | Options forwarded to the internal `NumberDisplay` readout |
| `arrowButtonOptions` | — | Options forwarded to all four internal `ArrowButton`s (excluding `numberOfArrows`, `tandem`, `focusable`, `soundPlayer`, which `FineCoarseSpinner` controls itself) |

::: tip Keyboard input drives the buttons, not a separate code path
`FineCoarseSpinner` implements `AccessibleNumberSpinner`, so arrow keys, Page Up/Down, and Home/End all work — but instead of changing `numberProperty` directly, keyboard input synthetically "clicks" the corresponding fine or coarse button (holding Shift routes to the fine button) so the pressed button visually depresses just as it would with a pointer. This is why `keyboardStep`/`shiftKeyboardStep`/`pageKeyboardStep` aren't exposed as options here — `deltaFine` and `deltaCoarse` are the only step sizes that exist.
:::


========================================================================
Page: FormulaNode
URL: https://veillette.github.io/Almanach/api/scenery-phet/formula-node
Source: docs/api/scenery-phet/formula-node.md
Category: API | Tags: scenery-phet, FormulaNode, katex, latex, math | Status: complete
========================================================================

# FormulaNode

`FormulaNode` (from `scenerystack/scenery-phet`) renders a LaTeX-style string as typeset math, using the [KaTeX](https://katex.org/) library, and wraps the result in a `DOM` Node so it can be placed in the scene graph like any other visual. Reach for it when a formula needs real mathematical typesetting (fraction bars, radicals, summations, matrices) that [`RichText`](/api/scenery/rich-text) markup and [`MathSymbolFont`](/api/scenery-phet/math-symbol-font) italics can't express — a single italic variable or a simple superscript is usually better served by plain `RichText`, reserving `FormulaNode` for genuinely formula-shaped content.

```ts
import { FormulaNode } from 'scenerystack/scenery-phet';
```

## A minimal example

```ts
const formulaNode = new FormulaNode( 'y = mx + b' );
formulaNode.center = layoutBounds.center;
screenView.addChild( formulaNode );

// Update the formula later:
formulaNode.formula = '\\frac{-b \\pm \\sqrt{b^2 - 4ac}}{2a}';
```

## Constructor

```ts
new FormulaNode( formula: string, options?: object )
```

`FormulaNode` extends `DOM` and predates SceneryStack's typed-options convention — it has no exported `FormulaNodeOptions` type. The two formula-specific settings, `formula` and `displayMode`, are ordinary mutator keys you can pass in the options object or set as properties after construction, alongside anything `DOM`/`Node` accepts.

## Options / properties

| Option | Default | Effect |
| --- | --- | --- |
| `formula` | (constructor argument) | The LaTeX-style string to render, assumed to already be in math mode |
| `displayMode` | `true` | `true` renders KaTeX's "display" style (larger, on its own line, as `$$...$$` would in LaTeX); `false` renders "inline" style (more vertically compact, as `$...$` would) |

```ts
const inlineFormula = new FormulaNode( 'E = mc^2', { displayMode: false } );
```

## Methods

| Method | Effect |
| --- | --- |
| `setFormula( formula )` / `formula` (setter) | Updates the displayed formula and recomputes bounds |
| `getFormula()` / `formula` (getter) | Returns the currently displayed formula string |
| `setDisplayMode( mode )` / `displayMode` (setter) | Switches between display and inline KaTeX rendering |
| `getDisplayMode()` / `displayMode` (getter) | Returns the current display mode |

::: warning Requires the KaTeX preloads to be included in the sim
`FormulaNode` calls the global `katex.render(...)` — it does not bundle or lazily load KaTeX itself. Using `FormulaNode` in a sim requires including the KaTeX CSS/font and JS preloads (e.g. `katex-<version>-css-all.js` and `katex-<version>.min.js`) at build time; without them, `katex` is undefined and construction throws. If you only need italic variable names or simple superscripts/subscripts, `RichText` with [`MathSymbolFont`](/api/scenery-phet/math-symbol-font) avoids this dependency entirely.
:::


========================================================================
Page: Fraction Display Nodes
URL: https://veillette.github.io/Almanach/api/scenery-phet/fraction-display-nodes
Source: docs/api/scenery-phet/fraction-display-nodes.md
Category: API | Tags: scenery-phet, MixedFractionNode, PropertyFractionNode, MinusNode, PlusNode, fraction, math | Status: complete
========================================================================

# Fraction Display Nodes

Four small `scenerystack/scenery-phet` Nodes share a common motivation: rendering mathematical marks (fractions, mixed numbers, plus/minus signs) as precisely-positioned shapes instead of relying on a font's glyphs for `-`, `+`, or a fraction bar. Font rendering of `-` and `+` varies across platforms and is hard to center reliably (particularly on Windows), so PhET builds these as `Rectangle`/`Path` primitives instead. `MixedFractionNode` and `PropertyFractionNode` build on the same idea for fractions — a numerator, a denominator, an optional whole-number part, and a hand-drawn horizontal line (a "vinculum") between them.

```ts
import { MixedFractionNode, PropertyFractionNode, MinusNode, PlusNode } from 'scenerystack/scenery-phet';
```

## MixedFractionNode

The base display: an `HBox` with an optional whole-number `Text`, followed by a numerator/vinculum/denominator stack, wherever you set them imperatively via setters. Passing `null` to any of `whole`/`numerator`/`denominator` leaves that slot blank (and removed from layout, for `whole`).

```ts
const fractionNode = new MixedFractionNode( {
  whole: 1,
  numerator: 3,
  denominator: 4,
  wholeNumberFont: new PhetFont( 40 ),
  fractionNumbersFont: new PhetFont( 24 )
} );

// Change a value later — MixedFractionNode rebuilds its own layout:
fractionNode.numerator = 1;
```

| Option | Default | Effect |
| --- | --- | --- |
| `whole` / `numerator` / `denominator` | `null` | Initial values; `null` hides that slot |
| `maxWhole` / `maxNumerator` / `maxDenominator` | `null` | If set, reserves layout space for every value from `0` up to this maximum, so changing the digit doesn't shift surrounding layout |
| `wholeFill` / `numeratorFill` / `denominatorFill` / `separatorFill` | `'black'` | Per-part colors, including the vinculum (`separatorFill`) |
| `wholeNumberFont` | `new PhetFont( 50 )` | Font for the whole-number part |
| `fractionNumbersFont` | `new PhetFont( 30 )` | Font for the numerator and denominator |
| `vinculumLineWidth` | `2` | Stroke width of the fraction bar |
| `vinculumExtension` | `0` | How far the fraction bar extends past the numerator/denominator bounds on both sides |
| `vinculumLineCap` | `'butt'` | Line cap style of the fraction bar |

## PropertyFractionNode

`PropertyFractionNode extends MixedFractionNode`, replacing the imperative setters with a live binding to a numerator `Property<number>` and a denominator `Property<number>` — the display updates itself whenever either Property changes.

```ts
const numeratorProperty = new NumberProperty( 5 );
const denominatorProperty = new NumberProperty( 3 );

const liveFraction = new PropertyFractionNode( numeratorProperty, denominatorProperty, {
  type: PropertyFractionNode.DisplayType.MIXED,
  simplify: true
} );
```

| Option | Default | Effect |
| --- | --- | --- |
| `type` | `PropertyFractionNode.DisplayType.IMPROPER` | `IMPROPER` shows e.g. `5/3`; `MIXED` shows e.g. `1 2/3`, splitting off the whole-number part |
| `simplify` | `false` | When `true` and the fraction is a whole number, hides the fraction part (governed by `showZeroImproperFraction`) |
| `showZeroImproperFraction` | `true` | With `simplify: true`, controls whether a numerator of `0` still shows an empty/zero fraction part or hides it entirely |

`PropertyFractionNode.DisplayType` is an `EnumerationDeprecated` with two values, `IMPROPER` and `MIXED`. Call `dispose()` when you're done with a `PropertyFractionNode` — it unlinks its own listeners from both Properties.

## MinusNode and PlusNode

Standalone sign glyphs, each built from a primitive shape rather than `Text`:

| Node | Base class | Shape |
| --- | --- | --- |
| `MinusNode` | `Rectangle` | A single filled rectangle |
| `PlusNode` | `Path` | A `PlusShape` (a "+"-shaped polygon) |

```ts
const minusSign = new MinusNode( { size: new Dimension2( 16, 3 ) } );
const plusSign = new PlusNode( { size: new Dimension2( 16, 3 ) } );
```

Both take a single `size: Dimension2` option (default `20×5`) — `width` is the overall length of the sign, `height` is its stroke thickness — plus whatever `Rectangle`/`Path` options apply (`fill` defaults to `'black'` for both). `MinusNode` asserts `size.width >= size.height`. Both have their origin at the upper-left of their bounding box, like any other `Node`.

::: tip These are marks, not editable text
None of these four Nodes accept a string or format pattern — they're geometric marks assembled from primitives. If you need a fraction embedded inside a larger internationalized sentence (e.g. "add 1/2 cup"), compose it with `RichText`/`StringProperty` patterns instead; reach for this family when you want a big, standalone, visually precise fraction or sign, independent of any specific font's glyph metrics.
:::


========================================================================
Page: GaugeNode
URL: https://veillette.github.io/Almanach/api/scenery-phet/gauge-node
Source: docs/api/scenery-phet/gauge-node.md
Category: API | Tags: scenery-phet, GaugeNode, gauge, dial, meter | Status: verified
========================================================================

# GaugeNode

`GaugeNode` (from `scenerystack/scenery-phet`) draws a speedometer-style dial: a circular background, major/minor tick marks around most of the circle, a text label, and a needle that rotates to reflect a numeric value clamped to a fixed `Range`. It was generalized out of the speedometer in Forces and Motion: Basics and works for any bounded numeric quantity — speed, force, temperature, whatever your label says it is.

```ts
import { GaugeNode } from 'scenerystack/scenery-phet';
import { NumberProperty } from 'scenerystack/axon';
import { Range } from 'scenerystack/dot';
import { StringProperty } from 'scenerystack/axon';
```

## A minimal example

```ts
const speedProperty = new NumberProperty( 0 );
const speedRange = new Range( 0, 100 );
const labelProperty = new StringProperty( 'm/s' );

const gaugeNode = new GaugeNode( speedProperty, labelProperty, speedRange, {
  radius: 120
} );
```

## Constructor

```ts
new GaugeNode(
  valueProperty: TReadOnlyProperty<number>,
  labelProperty: TReadOnlyProperty<string>,
  range: Range,
  providedOptions?: GaugeNodeOptions
)
```

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `radius` | `100` | Radius of the gauge |
| `backgroundFill` / `backgroundStroke` / `backgroundLineWidth` | `'white'` / `'rgb(85,85,85)'` / `2` | Styling of the circular background |
| `maxLabelWidthScale` | `1.3` | Max width of the label, as a multiple of `radius` (label scales down to fit) |
| `numberOfTicks` | `21` | Total ticks around the span (odd numbers keep one tick centered) |
| `majorTickStroke` / `minorTickStroke` | `'gray'` / `'gray'` | Tick colors; every other tick (starting at index 0) is drawn as "major" |
| `majorTickLength` / `minorTickLength` | `10` / `5` | Tick lengths |
| `majorTickLineWidth` / `minorTickLineWidth` | `2` / `1` | Tick stroke widths |
| `labelTextOptions` | `{ font: PhetFont(20) }` | Options forwarded to the internal label `Text` |
| `span` | `Math.PI + Math.PI / 4` | Angular span the ticks/needle range covers, in radians (default is the top half-circle plus a bit past horizontal on each side) |
| `needleLineWidth` | `3` | Stroke width of the needle |
| `updateWhenInvisible` | `true` | If `false`, the needle stops recomputing while the gauge is invisible (a perf optimization), catching up once it becomes visible again |

## Members

| Member | Description |
| --- | --- |
| `radius` | Public readonly copy of the resolved `radius` option |

::: warning The needle disappears for non-numeric values, and clamps otherwise
`GaugeNode` hides the needle entirely (`needle.visible = false`) whenever `valueProperty.get()` is not a `number` — useful if you're deriving the value and want to represent "no reading." For actual numbers, the needle instead **clamps** to `range.min`/`range.max` rather than disappearing or overshooting, so an out-of-range value still shows a (misleadingly) valid-looking needle position.
:::

For a variant with a numeric readout built in, see `ValueGaugeNode` (its own source file, `ValueGaugeNode.ts`) — it's a `GaugeNode` subclass that adds a centered [`NumberDisplay`](/api/scenery-phet/number-display) and a `numberDisplayVisible` setter/getter, otherwise sharing the same constructor shape.


========================================================================
Page: GrabDragInteraction
URL: https://veillette.github.io/Almanach/api/scenery-phet/grab-drag-interaction
Source: docs/api/scenery-phet/grab-drag-interaction.md
Category: API | Tags: scenery-phet, GrabDragInteraction, GrabDragUsageTracker, GrabReleaseCueNode, keyboard, accessibility, drag | Status: complete
========================================================================

# GrabDragInteraction

Dragging a `Node` with a `KeyboardDragListener` works as soon as the Node is focusable, but a lone focusable draggable object is a trap for keyboard users: arrow keys move it immediately on focus, competing with Tab for moving between other elements on the page. `GrabDragInteraction` (from `scenerystack/scenery-phet`) solves this with the standard two-state PDOM pattern used throughout PhET sims: the object starts as an "idle" `button` in the tab order ("Grab Ball"); pressing Space/Enter turns it into a focused, `application`-role "grabbed" `div` where the arrow keys now drag it; Escape (or Space/Enter again) releases it back to idle. It works like a mixin — you construct it with the target `Node` and a `KeyboardDragListener`, and it mutates that Node's PDOM content and swaps its input listeners as the state changes; you don't subclass anything.

```ts
import { GrabDragInteraction, KeyboardDragListener } from 'scenerystack/scenery-phet';
import { Node, RichDragListener } from 'scenerystack/scenery';

const ballNode = new Node( { cursor: 'pointer' } );

// Pointer dragging, wired up separately as usual.
const richDragListener = new RichDragListener( {
  positionProperty: ball.positionProperty,
  transform: modelViewTransform
} );
ballNode.addInputListener( richDragListener );

// The keyboard drag listener that will be added only while "grabbed".
const keyboardDragListener = new KeyboardDragListener( {
  positionProperty: ball.positionProperty,
  transform: modelViewTransform
} );

// interactionCueParent hosts the little "Press Space to grab/release" and
// "Use arrow keys" cue Nodes; it's usually the ScreenView itself.
const grabDragInteraction = new GrabDragInteraction( ballNode, keyboardDragListener, screenView, {
  objectToGrabString: 'Ball',
  tandem: tandem.createTandem( 'grabDragInteraction' )
} );
```

## Constructor

```ts
new GrabDragInteraction(
  node: Node,
  keyboardDragListener: KeyboardDragListener,
  interactionCueParent: Node,
  providedOptions?: GrabDragInteractionOptions
)
```

`node` is mutated in place with the PDOM options for whichever state it's currently in; `keyboardDragListener` is added to `node`'s input listeners only while grabbed; `interactionCueParent` is where the grab/drag cue Nodes are added as children (positioned relative to `node` automatically).

## Key options

| Option | Effect |
| --- | --- |
| `objectToGrabString` | The name filled into the default "Grab {{thing}}" idle-state label |
| `onGrab` / `onRelease` | Callbacks `( inputType ) => void`, called on the idle→grabbed / grabbed→idle transition; `inputType` is `'alternative'` (keyboard), `'pointer'`, or `'programmatic'` |
| `listenersWhileIdle` / `listenersWhileGrabbed` | Extra `TInputListener`s active only in that state — **never add listeners to the Node directly**, they must be registered here so `GrabDragInteraction` can swap them |
| `grabCueOptions`, `grabCuePosition`, `dragCueOptions` (via `dragCueNode`), `dragCuePosition` | Position and style the "Press Space to grab" / drag cue relative to the Node |
| `shouldShowGrabCueNode` / `shouldShowDragCueNode` | Predicates controlling whether each cue is currently visible; default to "until the user has successfully grabbed once with a keyboard" |
| `grabDragUsageTracker` | A shared `GrabDragUsageTracker` (see below), for coordinating cue visibility across multiple `GrabDragInteraction` instances |
| `supportsGestureDescription` | Whether to use the shorter, screen-reader-gesture-tuned label/help text instead of the desktop keyboard phrasing |
| `enabledProperty` | Disabling forces the interaction back to idle and blocks grabbing |
| `tandem` | Required, like most instrumented scenery-phet types |

## GrabDragUsageTracker

`GrabDragUsageTracker` is a small plain object tracking `numberOfGrabs`, `numberOfKeyboardGrabs`, and `shouldShowDragCue`. `GrabDragInteraction` creates its own by default, but you can construct one explicitly and pass it via `grabDragUsageTracker` to **share cueing state across multiple interaction instances** — for example, several identical draggable objects on one screen, where a keyboard user grabbing any one of them should be enough to stop showing "Grab" cues on all the others.

```ts
import { GrabDragUsageTracker, GrabDragInteraction } from 'scenerystack/scenery-phet';

const sharedTracker = new GrabDragUsageTracker();

const interactionA = new GrabDragInteraction( nodeA, dragListenerA, screenView, {
  grabDragUsageTracker: sharedTracker,
  tandem: tandemA
} );
const interactionB = new GrabDragInteraction( nodeB, dragListenerB, screenView, {
  grabDragUsageTracker: sharedTracker,
  tandem: tandemB
} );
```

## GrabReleaseCueNode

`GrabReleaseCueNode` is the small `Panel` — a Space key icon next to "Press Space to Grab or Release" text — that `GrabDragInteraction` shows near the idle-state Node on focus, until the user has grabbed with the keyboard at least once. It's built and owned internally (exposed read-only as `grabDragInteraction.grabCueNode` for repositioning only); most code never constructs one directly, though it's also the same cue Node reused by the [group-sort interaction](/api/scenery-phet/group-sort-interaction) for its own grab/release step.

::: warning Don't attach input listeners to the target Node directly
`GrabDragInteraction` interrupts and removes exactly the listeners it was given via `listenersWhileIdle`/`listenersWhileGrabbed` (plus the `keyboardDragListener` you passed to the constructor) whenever the state changes. A pointer listener added straight to the Node outside of that bookkeeping will keep firing in both states, which is rarely what you want — most sims instead attach ordinary pointer dragging (a plain `DragListener`/`RichDragListener`) directly to the Node as shown above, since pointer users aren't affected by the idle/grabbed PDOM split at all.
:::


========================================================================
Page: GridCheckbox and GridIcon
URL: https://veillette.github.io/Almanach/api/scenery-phet/grid-checkbox
Source: docs/api/scenery-phet/grid-checkbox.md
Category: API | Tags: scenery-phet, GridCheckbox, GridIcon, checkbox, grid | Status: complete
========================================================================

# GridCheckbox and GridIcon

`GridCheckbox` (from `scenerystack/scenery-phet`) is a [`Checkbox`](/api/sun/checkbox) whose label is a small grid-of-squares icon instead of text — the standard PhET affordance for "show/hide the coordinate grid" controls, most often paired with a [`GridNode`](/api/scenery-phet/grid-node) via a shared `Property<boolean>`. `GridIcon` is the icon itself (an NxN grid of lines drawn as a single `Path`), exported separately in case you need the icon without the checkbox behavior — e.g. inside a toolbar button or a legend.

```ts
import { GridCheckbox, GridIcon } from 'scenerystack/scenery-phet';
import { BooleanProperty } from 'scenerystack/axon';
```

## A minimal example

```ts
const gridVisibleProperty = new BooleanProperty( false );

const gridCheckbox = new GridCheckbox( gridVisibleProperty, {
  tandem: tandem.createTandem( 'gridCheckbox' )
} );

// Elsewhere, a GridNode reacts to the same Property:
gridNode.visibleProperty = gridVisibleProperty;
```

## Constructors

```ts
new GridCheckbox( property: Property<boolean>, providedOptions?: GridCheckboxOptions )

new GridIcon( providedOptions?: GridIconOptions )
```

`GridCheckboxOptions` is `{ iconOptions?: GridIconOptions } & CheckboxOptions` — `GridCheckbox` accepts every [`Checkbox`](/api/sun/checkbox) option (`boxWidth`, `touchAreaXDilation`, `tandem`, etc.) plus `iconOptions` to customize the grid icon it builds internally.

## GridIcon options

| Option | Default | Effect |
| --- | --- | --- |
| `size` | `30` | Width and height of the icon, in pixels (the icon is always square) |
| `numberOfRows` | `4` | Number of rows (and, since the grid is always N×N, columns) of cells; must be an integer greater than `2` |
| `stroke` | `'rgb( 100, 100, 100 )'` | Line color of the grid lines (any `PathOptions` field is also accepted) |
| `lineWidth` | `1` | Line thickness of the grid lines |

```ts
const bigGridIcon = new GridIcon( { size: 20, numberOfRows: 3, stroke: 'black' } );
const gridCheckbox = new GridCheckbox( gridVisibleProperty, { iconOptions: { size: 20 } } );
```

::: tip `GridCheckbox` and `GridNode` are independent — you wire them together
Neither Node knows about the other; `GridCheckbox` only flips a `Property<boolean>`, and [`GridNode`](/api/scenery-phet/grid-node) only draws lines. The common pattern is to pass the same `BooleanProperty` as `gridCheckbox`'s bound property and as `gridNode`'s `visibleProperty`, so checking the box shows the grid and unchecking it hides it — but nothing stops you from using `GridCheckbox` to drive a completely different piece of grid-shaped state.
:::


========================================================================
Page: GridNode
URL: https://veillette.github.io/Almanach/api/scenery-phet/grid-node
Source: docs/api/scenery-phet/grid-node.md
Category: API | Tags: scenery-phet, GridNode, grid, coordinates | Status: complete
========================================================================

# GridNode

`GridNode` (from `scenerystack/scenery-phet`) is a `Path` that draws a coordinate grid — evenly spaced horizontal and vertical lines centered on a model-coordinate point — to help users make quantitative comparisons between distances in the play area. It's a thin, purely-visual overlay: it takes a live `TReadOnlyProperty<ModelViewTransform2>` and redraws its shape every time the transform changes, so panning/zooming the view keeps the grid aligned with the model.

```ts
import { GridNode } from 'scenerystack/scenery-phet';
import { Vector2 } from 'scenerystack/dot';
```

## A minimal example

```ts
const gridNode = new GridNode(
  modelViewTransformProperty,  // TReadOnlyProperty<ModelViewTransform2>
  1,                           // spacing between grid lines, in model coordinates
  new Vector2( 0, 0 ),         // center of the grid, in model coordinates
  10,                          // numberOfGridLines on each side of center
  { stroke: 'gray' }
);
```

This draws 21 evenly spaced lines in each direction (10 on either side of `center`, plus the center line itself), each `spacing` model units apart.

## Constructor

```ts
new GridNode(
  transformProperty: TReadOnlyProperty<ModelViewTransform2>,
  spacing: number,
  center: Vector2,
  numberOfGridLines: number,
  providedOptions?: GridNodeOptions
)
```

`GridNodeOptions` is just `PathOptions` — `GridNode` has no options of its own beyond what any [`Path`](/api/scenery/path) accepts (it defaults `stroke` to `'gray'`).

## Parameters

| Parameter | Effect |
| --- | --- |
| `transformProperty` | Supplies the `ModelViewTransform2` used to project the grid's model-coordinate shape into view coordinates; re-projects on every change |
| `spacing` | Distance between adjacent grid lines, in model coordinates |
| `center` | The grid's center point, in model coordinates — lines are drawn symmetrically around it |
| `numberOfGridLines` | How many lines to draw on *each side* of `center`, per axis |

::: tip `spacing`, `center`, and `numberOfGridLines` are fixed at construction
Unlike `transformProperty`, the other three constructor arguments are plain values captured in a closure, not Properties — there's no way to change the spacing or extent of an existing `GridNode` later. If your sim needs a grid whose spacing changes at runtime (e.g. a "coarse/fine grid" toggle), construct a new `GridNode` (or swap between two pre-built ones) rather than mutating this one.
:::


========================================================================
Page: Group Sort Interaction
URL: https://veillette.github.io/Almanach/api/scenery-phet/group-sort-interaction
Source: docs/api/scenery-phet/group-sort-interaction.md
Category: API | Tags: scenery-phet, GroupSelectModel, GroupSelectView, GroupSortInteractionView, SortCueArrowNode, keyboard, accessibility | Status: complete
========================================================================

# Group Sort Interaction

Some sims have a *group* of interchangeable model items — bar-chart bars, number-line points, histogram entries — where keyboard users need to (1) move focus between items in the group, and (2) change an item's value once it's selected, all without those two things fighting over the same arrow keys. The "group sort interaction" is scenery-phet's standard pattern for this, split into three collaborating types under `scenerystack/scenery-phet`. **Read them in this order**, per the source's own documentation: `GroupSelectModel` first (it explains the interaction conceptually), then `GroupSelectView` (selection only), then `GroupSortInteractionView` (adds sorting on top).

The interaction has two states, deliberately named differently from focus to avoid overloading the term:

- **Selecting** — the group has focus; arrow keys move a "selection" cursor between items (visualized with a solid focus highlight around the selected item). This state doesn't change any values.
- **Sorting** — Space/Enter "grabs" the selected item (dashed focus highlight); arrow keys/WASD/Page Up/Page Down/Home/End now change *its* value; Space/Enter/Escape releases back to selecting.

```ts
import { GroupSelectModel, GroupSortInteractionView } from 'scenerystack/scenery-phet';
import { Range } from 'scenerystack/dot';

// One model per screen (not per scene) — see GroupSelectModel's own doc comment.
const groupSelectModel = new GroupSelectModel( {
  getGroupItemValue: ( item: BarModel ) => item.valueProperty.value,
  tandem: tandem.createTandem( 'groupSelectModel' )
} );

// One view per scene.
const groupSortInteractionView = new GroupSortInteractionView( groupSelectModel, groupNode, {
  getGroupItemToSelect: () => bars[ 0 ] ?? null,
  getNodeFromModelItem: ( item: BarModel ) => barNodeMap.get( item ) ?? null,
  sortingRangeProperty: new Property( new Range( 0, 10 ) ),
  sortGroupItem: ( item: BarModel, newValue: number ) => { item.valueProperty.value = newValue; }
} );
```

## GroupSelectModel\<ItemModel\>

Holds the interaction's state, independent of any view: which item is selected (`selectedGroupItemProperty`), whether it's currently grabbed for sorting (`isGroupItemKeyboardGrabbedProperty`), and a set of "has this ever happened" booleans (`hasKeyboardGrabbedGroupItemProperty`, `hasKeyboardSortedGroupItemProperty`, …) used to decide when hint cues should stop showing. It's generic over your item type — `null` is reserved to mean "nothing selected," so it must never be a valid `ItemModel` value.

| Constructor option | Effect |
| --- | --- |
| `getGroupItemValue: ( item ) => number \| null` | Required. Reads the sortable value out of an item; `null` means the item isn't part of the interaction right now |
| `initialMouseSortCueVisible` | Whether the mouse/touch sort cue starts visible |
| `tandem` | Required |

| Method | Effect |
| --- | --- |
| `resetInteractionState()` | Clears selection/grabbed/focus state, without resetting cueing history — call on scene changes |
| `reset()` | Full reset, including "has this happened" cue-visibility booleans |
| `registerUpdateSortCueNode( callback )` | Registers a callback to re-run whenever any Property relevant to mouse-cue visibility changes |
| `mouseSortCueShouldBeVisible()` | A partial answer for whether to show your own mouse/touch sort cue — combine with sim-specific logic |

## GroupSelectView\<ItemModel, ItemNode\>

Adds the keyboard controller for the **selecting** half of the interaction to a `primaryFocusedNode` (typically a `Node` representing the whole group, made focusable with `tagName: 'div'`/`ariaRole: 'application'` internally). It manages the group focus highlight, wires up a `KeyboardListener` for Space/Enter/Escape (toggling `isGroupItemKeyboardGrabbedProperty`), and owns a `GrabReleaseCueNode` (the same cue used by [`GrabDragInteraction`](/api/scenery-phet/grab-drag-interaction)) shown until the user has grabbed at least once.

| Constructor option | Effect |
| --- | --- |
| `getGroupItemToSelect: () => ItemModel \| null` | Required. The default/best-guess selection when the group first receives focus and nothing is selected yet |
| `getNodeFromModelItem: ( item ) => ItemNode \| null` | Required. Maps a model item to its view `Node`, so focus highlights and pan-to-view can find it |
| `isGroupItemEnabled` | Whether a given item can be grabbed/sorted right now; defaults to the corresponding Node's `enabled` |
| `onGrab` / `onRelease` | Callbacks fired on the selecting→sorting / sorting→selecting transition |
| `grabbedRoleDescription` / `releasedRoleDescription` | ARIA role descriptions announced in each state |

## GroupSortInteractionView\<ItemModel, ItemNode\>: adding sorting

`GroupSortInteractionView` extends `GroupSelectView`, adding a second `KeyboardListener` for the actual value-changing keys once an item is grabbed: arrow keys/WASD (`sortStep`), Shift+arrow/WASD (`shiftSortStep`), Page Up/Page Down (`pageSortStep`), and Home/End (jump to range min/max). The same keys, when *not* grabbed, instead move the selection between items via `getNextSelectedGroupItem`.

| Constructor option | Effect |
| --- | --- |
| `sortingRangeProperty: TReadOnlyProperty<Range>` | Required. The legal range for the sorted value |
| `sortGroupItem: ( item, newValue ) => void` | Required. Applies a computed value to the selected item |
| `getNextSelectedGroupItem: ( delta, current ) => ItemModel` | Required. Given a signed delta, returns which item should become selected next (used while *not* grabbed) |
| `sortStep` / `shiftSortStep` / `pageSortStep` | Step sizes for plain, Shift-modified, and Page Up/Down input (defaults `1`, `2`, `range.length / 5`) |
| `numberKeyMapper` | Optional `( keysPressed ) => number \| null` letting number keys 0-9 jump the grabbed item directly to a mapped value |
| `onSort` | Callback `( item, oldValue ) => void` fired after each sort |

`GroupSortInteractionView.createSortCueNode( visibleProperty, scale? )` is a static convenience that builds a `SortCueArrowNode` wired to the given visibility Property — the usual way to get the keyboard sort hint arrow without constructing `SortCueArrowNode` by hand.

## SortCueArrowNode

A small `HBox`-based `Node` drawing a dashed double- or single-headed arrow (`TriangleNode` heads plus a row of `Rectangle` dashes) — the visual "you can sort this with the arrow keys" hint shown near a freshly grabbed item.

```ts
import { SortCueArrowNode } from 'scenerystack/scenery-phet';

const sortCue = new SortCueArrowNode( {
  numberOfDashes: 3,
  doubleHead: true
} );
```

::: tip One model per screen, one view per scene
Per the source's own guidance: use a single `GroupSelectModel` per screen (so a successful sort in one scene "teaches" the interaction for the next scene too), but construct a fresh `GroupSelectView`/`GroupSortInteractionView` per scene, since each scene has a different set of item Nodes.
:::


========================================================================
Page: HandleNode
URL: https://veillette.github.io/Almanach/api/scenery-phet/handle-node
Source: docs/api/scenery-phet/handle-node.md
Category: API | Tags: scenery-phet, HandleNode, handle | Status: complete
========================================================================

# HandleNode

`HandleNode` (from `scenerystack/scenery-phet`) draws a horizontal bar with finger-shaped indents along its top and bottom edges — the "grip" — mounted to a surface by one or two elbow-shaped "attachment" bars. It's a static, decorative graphic: `HandleNode` has no drag behavior, Property, or model connection of its own. Sims use it as the visual affordance suggesting "this is grabbable," typically layered underneath or alongside a separate drag listener attached to the draggable object it represents.

```ts
import { HandleNode } from 'scenerystack/scenery-phet';
```

## A minimal example

```ts
const handleNode = new HandleNode( {
  gripBaseColor: 'orange',
  cursor: 'pointer'
} );
handleNode.center = layoutBounds.center;
screenView.addChild( handleNode );
```

Since `HandleNode` is purely visual, making it interactive means adding your own input listener (e.g. a `DragListener`) to it, the same as with any other `Node`.

## Constructor

```ts
new HandleNode( providedOptions?: HandleNodeOptions )
```

`HandleNode` takes no required arguments — every visual choice is made through options.

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `gripBaseColor` | `'rgb( 183, 184, 185 )'` | Base color of the vertical gradient painted on the grip |
| `gripStroke` | `'black'` | Stroke color of the grip's outline |
| `gripLineWidth` | `3` | Stroke width of the grip's outline |
| `attachmentFill` | `'gray'` | Solid fill color of the attachment bar(s) |
| `attachmentStroke` | `'black'` | Stroke color of the attachment bar(s) |
| `attachmentLineWidth` | `3` | Stroke width of the attachment bar(s) |
| `hasLeftAttachment` | `true` | Whether an attachment is drawn on the left side of the grip |
| `hasRightAttachment` | `true` | Whether an attachment is drawn on the right side of the grip |

```ts
// A handle mounted only on its left side, e.g. hanging off the edge of a panel.
const wallHandle = new HandleNode( {
  hasRightAttachment: false,
  attachmentFill: 'darkgray'
} );
```

::: tip At least one attachment is required
`HandleNode` asserts at construction that `hasLeftAttachment || hasRightAttachment` — a handle with no attachments at all isn't a supported configuration, since the grip alone doesn't read as "mounted to something."
:::

::: tip Not the same graphic [`Drawer`](/api/scenery-phet/drawer) uses
`Drawer`'s pull-tab is drawn independently (a small rounded-rectangle with dots), not by composing a `HandleNode`. If you need a drawer-style component with `HandleNode`'s specific grip-and-attachment look, you'll need to build it yourself rather than configuring `Drawer`.
:::


========================================================================
Page: HeaterCoolerNode
URL: https://veillette.github.io/Almanach/api/scenery-phet/heater-cooler-node
Source: docs/api/scenery-phet/heater-cooler-node.md
Category: API | Tags: scenery-phet, HeaterCoolerNode, heat-cool-control, heater, cooler, slider | Status: verified
========================================================================

# HeaterCoolerNode

There is no `HeatCoolControl` export in `scenerystack/scenery-phet` — the real class backing a bidirectional heat/cool control is `HeaterCoolerNode`. It draws a stove-like bucket with a flame/ice graphic (split into `HeaterCoolerBack` and `HeaterCoolerFront` so other Nodes can be layered inside the opening for a 3D effect) and an embedded vertical slider that drives a single `heatCoolAmountProperty` from `-1` (max cooling) through `0` (off) to `+1` (max heating). It's used in sims like States of Matter and Energy Forms and Changes wherever the user needs to add or remove heat from a system.

```ts
import { HeaterCoolerNode } from 'scenerystack/scenery-phet';
import { NumberProperty } from 'scenerystack/axon';
```

## A minimal example

```ts
const heatCoolAmountProperty = new NumberProperty( 0, {
  range: new Range( -1, 1 )
} );

const heaterCoolerNode = new HeaterCoolerNode( heatCoolAmountProperty, {
  tandem: tandem.createTandem( 'heaterCoolerNode' )
} );
```

Step your model's heat/cool logic off `heatCoolAmountProperty` directly (e.g. `heatCoolAmountProperty.value * maxHeatingRate`); `HeaterCoolerNode` only reflects and lets the user drag the value, it does not apply any heating/cooling itself.

## Constructor

```ts
new HeaterCoolerNode(
  heatCoolAmountProperty: NumberProperty,
  providedOptions?: HeaterCoolerNodeOptions
)
```

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `baseColor` | `HeaterCoolerBack.DEFAULT_BASE_COLOR` | Color of the stove body, applied consistently to both the front and back parts |
| `frontOptions` | — | Options forwarded to the internal `HeaterCoolerFront` (which owns the labels, stove body, and slider) |
| `backOptions` | — | Options forwarded to the internal `HeaterCoolerBack` (the opening and flame/ice graphics) |

Both `frontOptions` and `backOptions` reject an explicit `baseColor` — `HeaterCoolerNode` asserts against it, since it sets `baseColor` on both children itself from the top-level option.

## Members

| Member | Description |
| --- | --- |
| `heatCoolAmountProperty` | The `NumberProperty` passed to the constructor, ranging `-1` to `+1` |
| `slider` | The internal `VSlider` (from `scenerystack/sun`) that drives `heatCoolAmountProperty`; public so PhET-iO/Studio and edge-case client code can reach it directly |

::: tip `slider` is exposed, but treat it as read-mostly
`HeaterCoolerNode` deliberately makes its internal `VSlider` public (the source comment reads "with public visibility annotation comes great power — use it wisely") so tooling can instrument or inspect it. Reaching in to change its layout or behavior couples you to `HeaterCoolerFront`'s internals; prefer driving everything through `heatCoolAmountProperty` and the top-level options instead.
:::


========================================================================
Page: Icon Toggle Buttons
URL: https://veillette.github.io/Almanach/api/scenery-phet/icon-toggle-buttons
Source: docs/api/scenery-phet/icon-toggle-buttons.md
Category: API | Tags: scenery-phet, SoundToggleButton, TimerToggleButton, EyeToggleButton, button | Status: complete
========================================================================

# Icon Toggle Buttons

`SoundToggleButton`, `TimerToggleButton`, and `EyeToggleButton` are all built the same way: two pre-built icon `Node`s (an "on" state and an "off" state) handed to a member of the [toggle-button family](/api/sun/toggle-button), which shows exactly one of the two depending on a `Property<boolean>` and flips it on press. Unlike the [round icon utility buttons](/api/scenery-phet/round-icon-buttons), these hold state — the button's own appearance *is* the current value of the bound Property, and it stays in sync if that Property changes from elsewhere.

```ts
import { SoundToggleButton, TimerToggleButton, EyeToggleButton } from 'scenerystack/scenery-phet';
import { Property } from 'scenerystack/axon';
```

## A minimal example

```ts
const soundEnabledProperty = new Property<boolean>( true );
const timerRunningProperty = new Property<boolean>( false );
const eyeOpenProperty = new Property<boolean>( true );

const soundToggleButton = new SoundToggleButton( soundEnabledProperty, {
  tandem: tandem.createTandem( 'soundToggleButton' )
} );

const timerToggleButton = new TimerToggleButton( timerRunningProperty, {
  tandem: tandem.createTandem( 'timerToggleButton' )
} );

const eyeToggleButton = new EyeToggleButton( eyeOpenProperty, {
  tandem: tandem.createTandem( 'eyeToggleButton' )
} );
```

## The family

| Class | Base class | `true` icon | `false` icon | Default size |
| --- | --- | --- | --- | --- |
| `SoundToggleButton` | `BooleanRectangularToggleButton` | A speaker/volume glyph | The same glyph with an "x" drawn beside it | `45 × 45`, `4`px margin |
| `TimerToggleButton` | `BooleanRectangularToggleButton` | A `SimpleClockIcon` | The same clock, dimmed, with a red "x" over it (`offIconOptions` lets you restyle the "x") | `45 × 45`, `4`px margin |
| `EyeToggleButton` | `RectangularToggleButton<boolean>` | An open-eye glyph (`eyeSolidShape`) | A closed/slashed-eye glyph (`eyeSlashSolidShape`) | Sized to the icon, no fixed `minWidth`/`minHeight` |

`SoundToggleButton` and `TimerToggleButton` both default `baseColor` to `PhetColorScheme.BUTTON_YELLOW`; `EyeToggleButton` doesn't override `baseColor`, so it uses the plain `RectangularToggleButton` default.

## Constructor shape

All three take the boolean `Property` first, then options:

```ts
new SoundToggleButton( property: Property<boolean>, providedOptions?: SoundToggleButtonOptions )
new TimerToggleButton( timerRunningProperty: Property<boolean>, providedOptions?: TimerToggleButtonOptions )
new EyeToggleButton( eyeOpenProperty: Property<boolean>, providedOptions?: EyeToggleButtonOptions )
```

`EyeToggleButton`'s `eyeOpenProperty` is read as `true` = eye open (showing something), `false` = eye closed (hiding it) — the same true/false polarity you'd use for a `visibleProperty`.

::: tip These are conveniences, not the only way to build a boolean icon toggle
Each of these classes just wires two hand-picked icons into `BooleanRectangularToggleButton` or `RectangularToggleButton<boolean>`. If you need a similar on/off icon swap for a concept that isn't sound, timer, or visibility, build it the same way directly against the [toggle-button family](/api/sun/toggle-button) rather than trying to repurpose one of these three.
:::


========================================================================
Page: InfoButton
URL: https://veillette.github.io/Almanach/api/scenery-phet/info-button
Source: docs/api/scenery-phet/info-button.md
Category: API | Tags: scenery-phet, InfoButton, button | Status: verified
========================================================================

# InfoButton

`InfoButton` (from `scenerystack/scenery-phet`) is a [`RoundPushButton`](/api/sun/round-push-button) preloaded with the international "information" symbol (a solid circled "i") and a neutral grey base color. It's the standard way to expose a "more information" or "about this control" affordance that opens a dialog — [`ResetAllButton`](/api/scenery-phet/reset-all-button) is the other common round PhET-standard button, though built for a different, unrelated action.

```ts
import { InfoButton } from 'scenerystack/scenery-phet';
```

## A minimal example

```ts
const infoButton = new InfoButton( {
  listener: () => {
    infoDialog.show();
  },
  tandem: tandem.createTandem( 'infoButton' )
} );
```

## Options

`InfoButtonOptions` adds one option on top of `RoundPushButtonOptions` (`listener`, `radius`, `touchAreaDilation`, `enabledProperty`, …) — `content` is fixed and not settable, since the icon defines this button.

| Option | Default | Effect |
| --- | --- | --- |
| `iconFill` | `'rgb( 41, 106, 163 )'` (PhET's standard info blue) | Fill color of the "i" icon |
| `baseColor` | `'rgb( 238, 238, 238 )'` (light grey) | Button background color |
| `xMargin` / `yMargin` | `10` / `10` | Margin between the icon and the button edge |
| `touchAreaDilation` | `10` | Touch-area expansion beyond the visual bounds |
| `soundPlayer` | a silent (`nullSoundPlayer`) player | No sound plays on press by default |

::: tip Info buttons default to silent
Unlike most PhET buttons, `InfoButton`'s default `soundPlayer` is a no-op. Since pressing it almost always opens a dialog, and the dialog itself plays a sound when it appears, giving the button its own sound too would produce an audible double-fire — leave the default alone unless your use case genuinely doesn't open a dialog.
:::


========================================================================
Page: Keyboard Help Node Basics
URL: https://veillette.github.io/Almanach/api/scenery-phet/keyboard-help-node-basics
Source: docs/api/scenery-phet/keyboard-help-node-basics.md
Category: API | Tags: scenery-phet, KeyNode, LetterKeyNode, NumberKeyNode, TextKeyNode, ArrowKeyNode, KeyboardHelpIconFactory, keyboard, accessibility | Status: complete
========================================================================

# Keyboard Help Node Basics

A Keyboard Help Dialog tells the user which keys do what, and it does that visually with little keycap-shaped icons — a rounded rectangle with a drop shadow, containing a letter, a symbol, or an arrow glyph. `KeyNode` (from `scenerystack/scenery-phet`) draws that keycap shape around any icon `Node`; `LetterKeyNode`, `NumberKeyNode`, `TextKeyNode`, and `ArrowKeyNode` are `KeyNode` subclasses pre-configured for the most common contents. `KeyboardHelpIconFactory` then composes multiple key icons into rows (`A` **+** `D`, `↑` **or** `↓`, and so on) for use as [`KeyboardHelpSection`](/api/scenery-phet/keyboard-help-sections) rows. None of this renders live keyboard state — these are static icons describing what a key *looks like*, not indicators of whether it's currently pressed.

```ts
import { KeyboardHelpIconFactory, LetterKeyNode, TextKeyNode, ArrowKeyNode } from 'scenerystack/scenery-phet';

// A single "W" keycap.
const wKey = LetterKeyNode.w();

// "Shift" and "Tab" keycaps combined with a plus icon: "Shift + Tab".
const shiftTabRow = KeyboardHelpIconFactory.shiftPlusIcon( TextKeyNode.tab() );

// The four arrow keys in a row: "← ↑ ↓ →".
const arrowRow = KeyboardHelpIconFactory.arrowKeysRowIcon();
```

## KeyNode: the shared keycap shape

`KeyNode` wraps an arbitrary icon `Node` in a background rectangle plus an offset shadow rectangle, giving it a slight 3D "physical key" look. Every key has the same height by default (`keyHeight`); width grows to fit the icon and padding, or the icon scales down if it would overflow `minKeyWidth`/`forceSquareKey`.

```ts
import { KeyNode } from 'scenerystack/scenery-phet';
import { Text } from 'scenerystack/scenery';

const customKey = new KeyNode( new Text( '?' ), {
  keyFill: 'white',
  cornerRadius: 2
} );
```

| Option | Default | Effect |
| --- | --- | --- |
| `keyFill` / `keyShadowFill` | `'white'` / `'black'` | Fill of the foreground key and its drop shadow |
| `keyHeight` | `23` | Height every key shares by default, in ScreenView coordinates |
| `minKeyWidth` | `23` (same as `keyHeight`) | Minimum width; the icon can force it wider |
| `forceSquareKey` | `false` | If `true`, width is forced to equal `keyHeight`, scaling the icon down if needed |
| `xPadding` / `yPadding` | `4` / `4` | Space around the icon before it forces the key to grow |
| `xShadowOffset` / `yShadowOffset` | `1.7` / `1.7` | Offset of the shadow rectangle, producing the 3D look |

## The KeyNode subclasses

Each subclass fixes sensible defaults and adds static factory methods for the specific glyphs a Keyboard Help Dialog needs over and over, so you rarely construct them with `new` directly.

| Class | Wraps | Static factories (examples) |
| --- | --- | --- |
| `TextKeyNode` | A `RichText` label, for multi-character keys | `TextKeyNode.space()`, `.enter()`, `.esc()`, `.tab()`, `.shift()`, `.altOrOption()` (renders "Alt" or "Option" per platform), `.pageUp()`, `.pageDown()`, `.home()`, `.end()`, `.backspace()`, `.delete()` |
| `LetterKeyNode` | A single letter/digit, forced square | `LetterKeyNode.w()`, `.a()`, `.s()`, `.d()`, `.r()`, … (also `.one()`, `.two()`, `.three()` for digit-as-letter contexts) |
| `NumberKeyNode` | A single non-negative integer, via `LetterKeyNode` | `new NumberKeyNode( 9 )` |
| `ArrowKeyNode` | A rounded-triangle arrow glyph, forced square | `new ArrowKeyNode( 'up' \| 'down' \| 'left' \| 'right' )` |

```ts
import { NumberKeyNode, ArrowKeyNode, TextKeyNode } from 'scenerystack/scenery-phet';

const nineKey = new NumberKeyNode( 9 );
const upArrowKey = new ArrowKeyNode( 'up' );
const escKey = TextKeyNode.esc();
```

## KeyboardHelpIconFactory: composing keys into rows

`KeyboardHelpIconFactory` has only static methods (it asserts if you try to construct it) for laying out multiple key icons horizontally, the way a help row usually needs: a plain row, two icons joined by "or"/"-", or icons joined by a `+` (via `PlusNode`) to represent a chorded shortcut.

| Method | Produces |
| --- | --- |
| `iconRow( icons )` | Icons side by side, left to right |
| `iconOrIcon( left, right )` | `left` **or** `right`, separated by localized "or" text |
| `iconToIcon( left, right )` | `left` **-** `right`, separated by a hyphen (e.g. a `0`-`9` range) |
| `iconPlusIcon( left, right )` / `iconPlusIconRow( icons )` | Icons joined by `+` (`PlusNode`), for chorded shortcuts like Shift+Tab |
| `shiftPlusIcon( icon )` / `altPlusIcon( icon )` | Shortcut for `iconPlusIcon( TextKeyNode.shift(), icon )` / with Alt |
| `spaceOrEnter()` | The common "Space or Enter" row used for activating buttons |
| `wasdRowIcon()` / `arrowKeysRowIcon()` / `arrowOrWasdKeysRowIcon()` | The W/A/S/D keys, the four arrow keys, or both joined by "or" |
| `upOrDown()` / `upDownArrowKeysRowIcon()` / `leftRightArrowKeysRowIcon()` | Common two-key subsets of the arrow keys |
| `pageUpPageDownRowIcon()` | Page Up / Page Down pair |
| `fromHotkeyData( hotkeyData )` | Builds the icon row directly from a `HotkeyData`'s key descriptors (see below) |

::: tip Prefer `fromHotkeyData` when a component already defines its own hotkeys
Components like `ResetAllButton` and `PlayControlButton` expose their shortcuts as static `HotkeyData` (e.g. `ResetAllButton.RESET_ALL_HOTKEY_DATA`). `KeyboardHelpIconFactory.fromHotkeyData` (used internally by `KeyboardHelpSectionRow.fromHotkeyData`, see [Keyboard Help Sections](/api/scenery-phet/keyboard-help-sections)) reads that data and builds the matching icon row automatically, so the help dialog can't drift out of sync with the actual keys the component listens for.
:::

## Not the same "Key"/"KeyID" as the numeric keypad

`scenerystack/scenery-phet` also exports a `Key` class and a `KeyID` enum, and their names invite confusion with this page. In the real source, both live under `scenery-phet/js/keypad/` and describe the buttons of the **numeric `Keypad` component** (digits, backspace, decimal point, ±, x², …) — they are unrelated to keyboard-help icons and are not used anywhere in `KeyboardHelpSection`/`KeyboardHelpIconFactory`. If you're building a Keyboard Help Dialog, `KeyNode` and its subclasses above are the types you want; `Key`/`KeyID` only matter if you're customizing the on-screen `Keypad`.


========================================================================
Page: Keyboard Help Sections
URL: https://veillette.github.io/Almanach/api/scenery-phet/keyboard-help-sections
Source: docs/api/scenery-phet/keyboard-help-sections.md
Category: API | Tags: scenery-phet, KeyboardHelpSection, KeyboardHelpSectionRow, BasicActionsKeyboardHelpSection, MoveDraggableItemsKeyboardHelpSection, SliderControlsAndBasicActionsKeyboardHelpContent, SpinnerControlsKeyboardHelpSection, TimeControlsKeyboardHelpSection, ComboBoxKeyboardHelpSection, FaucetControlsKeyboardHelpSection, HeatCoolControlsKeyboardHelpSection, GrabReleaseKeyboardHelpSection, TwoColumnKeyboardHelpContent, WASDCueNode, keyboard, accessibility | Status: complete
========================================================================

# Keyboard Help Sections

A `KeyboardHelpSection` is one labeled group inside a Keyboard Help Dialog — a heading (e.g. "Move Draggable Items") plus a vertically aligned list of rows, each row pairing a text label with a key icon built from [`KeyboardHelpIconFactory`](/api/scenery-phet/keyboard-help-node-basics). `KeyboardHelpSectionRow` is the lower-level type that represents one such row (it aligns the label and icon with an `AlignGroup` so labels and icons form neat columns); most code never constructs a raw `KeyboardHelpSectionRow` directly, because scenery-phet ships ready-made `KeyboardHelpSection` subclasses for the interaction patterns that recur across PhET sims.

```ts
import {
  BasicActionsKeyboardHelpSection,
  SliderControlsAndBasicActionsKeyboardHelpContent
} from 'scenerystack/scenery-phet';

// A sim whose only interactions are a slider and standard tab/button navigation
// can use this ready-made two-column content wholesale in its KeyboardHelpDialog.
const helpContent = new SliderControlsAndBasicActionsKeyboardHelpContent();

// Or assemble a single section on its own, e.g. for a custom layout:
const basicActionsSection = new BasicActionsKeyboardHelpSection( {
  withCheckboxContent: true
} );
```

## KeyboardHelpSection and KeyboardHelpSectionRow

`KeyboardHelpSection`'s constructor takes a heading string and an array of `KeyboardHelpSectionRow`s; it lays out all the row labels in one `VBox` and all the row icons in a second `VBox`, side by side, so icons align into a column regardless of label length. It also doubles as a `ReadingBlock` — with Voicing enabled, activating the section reads its heading and every row's content aloud.

`KeyboardHelpSectionRow` provides the static helpers that actually build rows; you'll see these inside the ready-made sections below, and you can use them directly for a custom section:

| Static method | Produces |
| --- | --- |
| `labelWithIcon( labelString, icon, options? )` | The common case: one label, one icon, aligned in a row |
| `labelWithIconList( labelString, icons, options? )` | One label next to several icons stacked vertically, separated by "or" (e.g. "Move slower" listing both the Shift+arrows and Shift+WASD variants) |
| `fromHotkeyData( hotkeyData, options? )` | Builds both the label *and* the icon straight from a component's `HotkeyData` (e.g. `ResetAllButton.RESET_ALL_HOTKEY_DATA`), so the row can't drift out of sync with the actual shortcut |

```ts
import { KeyboardHelpSection, KeyboardHelpSectionRow, KeyboardHelpIconFactory, TextKeyNode } from 'scenerystack/scenery-phet';

const customSection = new KeyboardHelpSection( 'Custom Shortcuts', [
  KeyboardHelpSectionRow.labelWithIcon( 'Toggle play', KeyboardHelpIconFactory.spaceOrEnter() ),
  KeyboardHelpSectionRow.labelWithIcon( 'Exit', TextKeyNode.esc() )
] );
```

## The ready-made sections

Each of these is a `KeyboardHelpSection` (or, for the two "content" types, a layout wrapper around several sections) tuned for one recurring UI pattern. All accept an options object to override headings, strings, or which optional rows appear.

| Type | Covers | Notable options |
| --- | --- | --- |
| `BasicActionsKeyboardHelpSection` | Tab/Shift+Tab navigation, arrow-key group navigation, Space/Enter to press buttons, Reset All (via `ResetAllButton.RESET_ALL_HOTKEY_DATA`), Escape to exit a dialog | `withCheckboxContent`, `withKeypadContent` add optional rows |
| `MoveDraggableItemsKeyboardHelpSection` | Arrow/WASD movement and Shift+arrow/WASD for finer movement, for any draggable item | `headingStringProperty` |
| `SliderControlsAndBasicActionsKeyboardHelpContent` | A ready-to-use `TwoColumnKeyboardHelpContent` pairing a slider-controls section with `BasicActionsKeyboardHelpSection` — the whole dialog body for slider-only sims | `sliderSectionOptions`, `generalSectionOptions` |
| `SpinnerControlsKeyboardHelpSection` | A `SliderControlsKeyboardHelpSection` variant tuned for spinners (defaults `includeLargerStepsRow` to `false`, since spinners rarely support Page Up/Down) | Inherits slider-section options |
| `HeatCoolControlsKeyboardHelpSection` | A `SliderControlsKeyboardHelpSection` variant for `HeaterCoolerNode`-style heat/cool sliders — up/down arrows, an added "off" (`0` key) row, and heat/cool-specific min/max labels | Inherits slider-section options |
| `TimeControlsKeyboardHelpSection` | Play/pause toggle, built from `PlayControlButton.TOGGLE_PLAY_HOTKEY_DATA` (labeled per-platform, since the modifier differs on macOS) | `headingString` |
| `ComboBoxKeyboardHelpSection` | The four-step combo-box interaction: Space/Enter to open, arrows to move through options, Enter to choose, Escape to close without changing — rendered as a numbered list | `thingAsLowerCaseSingular`/`Plural` fill in "option(s)" with your own noun |
| `FaucetControlsKeyboardHelpSection` | Left/right arrows to adjust flow, Shift+arrows for smaller steps, Page Up/Down for larger steps, Home/End to close/open fully, matching `FaucetNode`'s [own hotkeys](/api/scenery-phet/faucet-node) | `tapToDispenseEnabled`, `reverseAlternativeInput` (for a faucet facing left) |
| `GrabReleaseKeyboardHelpSection` | The single-row "Press Space or Enter to grab or release {thing}" explanation for the [grab/drag interaction](/api/scenery-phet/grab-drag-interaction) | Constructor takes `thingAsTitle`/`thingAsLowerCase` strings, not options |

```ts
import { GrabReleaseKeyboardHelpSection } from 'scenerystack/scenery-phet';
import { StringProperty } from 'scenerystack/axon';

const ballGrabHelp = new GrabReleaseKeyboardHelpSection(
  new StringProperty( 'Grab or Release Ball' ),
  new StringProperty( 'ball' )
);
```

## Layout: TwoColumnKeyboardHelpContent

`TwoColumnKeyboardHelpContent` is not itself a `KeyboardHelpSection` — it's a plain layout `Node` that arranges two arrays of `KeyboardHelpSection`s into left/right columns (`columnSpacing`, `sectionSpacing` control the gaps). It's what `SliderControlsAndBasicActionsKeyboardHelpContent` uses internally, and it's the type to reach for when you have several ready-made sections and need to assemble a full dialog body yourself:

```ts
import {
  TwoColumnKeyboardHelpContent,
  MoveDraggableItemsKeyboardHelpSection,
  BasicActionsKeyboardHelpSection
} from 'scenerystack/scenery-phet';

const dialogContent = new TwoColumnKeyboardHelpContent(
  [ new MoveDraggableItemsKeyboardHelpSection() ],  // left column
  [ new BasicActionsKeyboardHelpSection() ]         // right column
);
```

## WASDCueNode: an on-screen cue, not a help-dialog row

`WASDCueNode` is unrelated to the Keyboard Help Dialog's content — it's a small `Node` of arrow-plus-letter-key icons (built from the same `LetterKeyNode`/`ArrowKeyNode` building blocks) meant to sit directly next to a draggable object in the play area itself, as a one-time on-screen hint that WASD/arrow keys move it. Give it the object's `boundsProperty` and it repositions its four key icons around the object automatically:

```ts
import { WASDCueNode } from 'scenerystack/scenery-phet';

const dragCue = new WASDCueNode( ballNode.boundsProperty );
```

::: tip Most sims should reach for the ready-made "content" types first
`SliderControlsAndBasicActionsKeyboardHelpContent` covers the majority of simple sims outright. For anything more custom, compose the individual sections above (they're designed to be mixed) inside your own `TwoColumnKeyboardHelpContent` rather than building `KeyboardHelpSection`/`KeyboardHelpSectionRow` from scratch — you'll get correct translations, PDOM structure, and Voicing support for free.
:::


========================================================================
Page: Keypad
URL: https://veillette.github.io/Almanach/api/scenery-phet/keypad
Source: docs/api/scenery-phet/keypad.md
Category: API | Tags: scenery-phet, Keypad, NumberAccumulator, AbstractKeyAccumulator, BidirectionalControlChars, input | Status: complete
========================================================================

# Keypad

`Keypad` (from `scenerystack/scenery-phet`) renders a grid of number-pad-style buttons — digits, a decimal point, backspace, plus/minus — and delegates the job of interpreting a sequence of key presses into a value to a separate **accumulator** object. This split exists so the same button grid can back different numeric formats (plain positive integers, signed decimals, …) just by swapping the accumulator, without touching the layout or rendering code.

```ts
import { Keypad, NumberAccumulator } from 'scenerystack/scenery-phet';
import { Tandem } from 'scenerystack/tandem';
```

## A minimal example

```ts
const keypad = new Keypad( Keypad.PositiveAndNegativeFloatingPointLayout, {
  accumulatorOptions: {
    maxDigits: 4,
    maxDigitsRightOfMantissa: 2
  },
  tandem: Tandem.REQUIRED.createTandem( 'keypad' )
} );

// Read the accumulated value reactively:
keypad.valueProperty.link( value => {
  console.log( 'current keypad value:', value ); // number | null
} );

// Programmatically clear it, e.g. after the value is "submitted":
keypad.clear();
```

## The layout / accumulator split

A `Keypad` is built from two independent pieces:

1. **Layout** — a 2D array of `Key | null` (a `KeypadLayout`) passed as the constructor's first argument, describing which keys appear where, including multi-cell spans for wide/tall keys (like the `0` key spanning two columns in `PositiveIntegerLayout`).
2. **Accumulator** — an `AbstractKeyAccumulator` subclass (by default, a `NumberAccumulator` `Keypad` creates for you) that receives every key press via `handleKeyPressed()` and decides whether the resulting sequence is valid and how to turn it into a displayable string and a number.

You rarely need to build a custom `KeypadLayout` — `Keypad` ships several ready-made static layouts:

| Static layout | Keys |
| --- | --- |
| `Keypad.PositiveIntegerLayout` | `0`–`9`, wide `0`, backspace — no decimal, no sign |
| `Keypad.PositiveDecimalLayout` / `PositiveFloatingPointLayout` | `0`–`9`, decimal point, backspace |
| `Keypad.PositiveAndNegativeIntegerLayout` | `0`–`9`, backspace, plus/minus toggle |
| `Keypad.PositiveAndNegativeFloatingPointLayout` | `0`–`9`, wide `0`, decimal point, plus/minus toggle, backspace |

Individual keys are also exposed as statics (`Keypad.KEY_0`...`KEY_9`, `KEY_DECIMAL`, `KEY_BACKSPACE`, `KEY_PLUS_MINUS`, `KEY_WIDE_ZERO`) if you want to assemble your own `KeypadLayout` from the same building blocks.

## Constructor

```ts
new Keypad( layout: ( Key | null )[][], providedOptions?: KeypadOptions )
```

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `buttonWidth` / `buttonHeight` | `35` / `35` | Size of a single-span key |
| `xSpacing` / `ySpacing` | `10` / `10` | Gaps between buttons |
| `touchAreaXDilation` / `touchAreaYDilation` | `5` / `5` | Touch-area dilation on every button |
| `buttonColor` | `'white'` | Base color of every key button |
| `buttonFont` | `new PhetFont({ size: 20 })` | Font for text-labeled keys |
| `accumulator` | `null` | Supply your own `AbstractKeyAccumulator` instance; if provided, `Keypad` disposes it along with itself |
| `accumulatorOptions` | `null` | Options forwarded to the default `NumberAccumulator` — ignored if `accumulator` is provided |
| `useGlobalKeyboardListener` | `false` | If `true`, keyboard input drives this `Keypad` regardless of DOM focus (only one such global `Keypad` may exist at a time — asserted) |

## Public API

| Member | Description |
| --- | --- |
| `accumulatedKeysProperty` | `ReadOnlyProperty<KeyIDValue[]>` — the raw sequence of accumulated key IDs |
| `stringProperty` | `ReadOnlyProperty<string>` — the string representation shown to the user (e.g. `"-12.5"`) |
| `valueProperty` | `ReadOnlyProperty<number \| null>` — the numeric value, or `null` if nothing meaningful has been entered yet |
| `clear()` | Clears the accumulator |
| `setClearOnNextKeyPress( clearOnNextKeyPress: boolean )` / `getClearOnNextKeyPress()` | Controls whether the *next* non-backspace key press wipes the existing value first — useful for "start typing a fresh number after submitting" UX |

Every digit and control key also responds to physical keyboard input (via a Scenery `KeyboardListener` built from each `Key`'s `keyboardIDs`) whenever the `Keypad` has focus, or globally if `useGlobalKeyboardListener: true`. See [Keyboard Input and Hotkeys](/accessibility/keyboard-input-and-hotkeys) for how `KeyboardListener` fits into PhET's broader input model.

## NumberAccumulator

`NumberAccumulator extends AbstractKeyAccumulator` and is the default accumulator `Keypad` creates when you don't supply your own. It interprets a sequence of digit/decimal/plus-minus/backspace key IDs as a single signed decimal number, enforcing digit-count limits.

```ts
new NumberAccumulator( providedOptions?: NumberAccumulatorOptions )
```

| Option | Default | Effect |
| --- | --- | --- |
| `maxDigitsRightOfMantissa` | `0` | Maximum digits allowed after the decimal point (`0` effectively disallows a fractional part) |
| `maxDigits` | `Number.MAX_SAFE_INTEGER`'s digit count | Maximum total digits allowed (left + right of the decimal point) |

It exposes the same `stringProperty` / `valueProperty` pair that `Keypad` re-exposes at the top level, and automatically strips a leading zero once a second digit is typed (so `0` → `5` becomes `5`, not `05`).

## AbstractKeyAccumulator

`AbstractKeyAccumulator` is the base class `NumberAccumulator` extends, and the type you implement against if you need a keypad that produces something other than a plain signed decimal (a custom expression, a unit-tagged value, etc.). It owns the shared bookkeeping:

| Member | Description |
| --- | --- |
| `accumulatedKeysProperty` | `Property<KeyIDValue[]>` — the array of key IDs pressed so far; this is the one piece of state every subclass builds on |
| `handleKeyPressed( keyID: KeyIDValue )` | *(abstract)* — subclasses must implement how a new key mutates the accumulated sequence |
| `stringProperty` / `valueProperty` | *(abstract)* — subclasses must supply these as derived views over `accumulatedKeysProperty` |
| `clearOnNextKeyPress` (getter/setter) | Same "clear on next key" behavior `Keypad.setClearOnNextKeyPress()` delegates to |
| `handleClearOnNextKeyPress( keyID )` *(protected)* | Helper subclasses call at the top of `handleKeyPressed()` to honor the clear-on-next-press flag uniformly |
| `validateKeys( proposedKeys )` / `updateKeys( proposedKeys )` *(protected)* | Runs the constructor-supplied validator functions against a proposed new sequence, and commits it if valid |

::: tip Build a validator list, don't override validation logic directly
`AbstractKeyAccumulator`'s constructor takes an array of `( keys: KeyIDValue[] ) => boolean` validator functions (see how `NumberAccumulator` passes a single digit-count validator). Compose your custom accumulator's rules as validator functions rather than fighting the base class's `validateKeys()` — it already runs every validator and ANDs the results together.
:::

## BidirectionalControlChars

`BidirectionalControlChars` is a small, unrelated utility that happens to live in `scenerystack/scenery-phet` alongside the keypad classes (its actual source file is `scenery-phet/js/BidirectionalControlChars.ts`, not the `keypad/` subfolder). It's a frozen object of Unicode bidirectional-control characters, for consistently isolating left-to-right or right-to-left text fragments inside a larger internationalized string:

```ts
import { BidirectionalControlChars } from 'scenerystack/scenery-phet';

const isolatedNumber = `${BidirectionalControlChars.LRI}${value}${BidirectionalControlChars.PDI}`;
```

| Key | Character | Purpose |
| --- | --- | --- |
| `LRI` | U+2066 | Start a left-to-right isolated run |
| `RLI` | U+2067 | Start a right-to-left isolated run |
| `PDI` | U+2069 | End an isolated run started by `LRI`/`RLI` |
| `LRE` / `RLE` / `PDF` | U+202A / U+202B / U+202C | Older embedding-style equivalents, kept for compatibility with existing code; prefer the isolate (`*I`) characters above in new code |

It has no relationship to `Keypad`'s accumulator pattern — it's included here purely for reference completeness.


========================================================================
Page: LaserPointerNode
URL: https://veillette.github.io/Almanach/api/scenery-phet/laser-pointer-node
Source: docs/api/scenery-phet/laser-pointer-node.md
Category: API | Tags: scenery-phet, LaserPointerNode, optics, button | Status: complete
========================================================================

# LaserPointerNode

`LaserPointerNode` (from `scenerystack/scenery-phet`) draws a laser-pointer body — a tapered nozzle and casing, pointing right by default with its origin at the output nozzle — with an optional built-in on/off button wired to a boolean Property. It's the standard "light source the user can turn on and point" graphic in optics/light sims (e.g. bending-light-style sims), and can also represent a plain flashlight-style light source with `hasButton: false`.

```ts
import { LaserPointerNode } from 'scenerystack/scenery-phet';
import { BooleanProperty } from 'scenerystack/axon';
```

## A minimal example

```ts
const onProperty = new BooleanProperty( false );

const laserPointerNode = new LaserPointerNode( onProperty, {
  tandem: tandem.createTandem( 'laserPointerNode' ),
  hasGlass: true // draws a small lens at the nozzle output
} );
```

`onProperty` is two-way bound: toggling the built-in button flips it, and setting it programmatically updates the button's pressed appearance.

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `bodySize` / `nozzleSize` | `Dimension2(110,78)` / `Dimension2(20,60)` | Dimensions of the main casing and the narrower nozzle |
| `topColor` / `bottomColor` / `highlightColor` | grays / near-white | Vertical gradient colors for both body and nozzle |
| `hasButton` | `true` | Whether an on/off button is drawn at all — other button options are ignored if `false` |
| `buttonType` | `'toggle'` | `'toggle'` uses a `RoundStickyToggleButton` (press to latch on, press again to turn off); `'momentary'` uses a `RoundMomentaryButton` (on only while held) |
| `buttonOptions` | `{ baseColor: 'red', radius: 22, … }` | Forwarded to the underlying round button |
| `getButtonLocation` | `bodyNode => bodyNode.center` | Function computing where the button sits within the body |
| `hasGlass` | `false` | Draws a semicircular lens `ShadedSphereNode` at the nozzle output — a visual cue that this is a non-laser light source, without moving the Node's origin |
| `glassOptions` | tuned defaults | `heightProportion`/`proportionStickingOut` control the lens's size and how far it protrudes, plus standard `ShadedSphereNode` coloring |

## Instance member

| Member | Type | Description |
| --- | --- | --- |
| `onOffButton` | `Node \| null` | Read-only reference to the button Node (if `hasButton` is `true`), safe to add listeners to but not to mutate structurally |

## Static member

| Member | Description |
| --- | --- |
| `LaserPointerNode.DEFAULT_LASER_NODE_OPTIONS` | The frozen default options object, useful for building a variant that overrides only a few fields |

::: tip `tandem` defaults to `Tandem.REQUIRED`
Like other instrumentable scenery-phet components, `LaserPointerNode`'s default options set `tandem: Tandem.REQUIRED` and a `tandemNameSuffix` of `['LaserPointerNode', 'LightNode']` — omitting a real tandem asserts in an instrumented build. Always pass `tandem: someTandem.createTandem( '...' )` explicitly. See [Tandem](/api/tandem/tandem) for why `Tandem.REQUIRED` exists as a sentinel rather than a usable default.
:::


========================================================================
Page: LightBulbNode
URL: https://veillette.github.io/Almanach/api/scenery-phet/light-bulb-node
Source: docs/api/scenery-phet/light-bulb-node.md
Category: API | Tags: scenery-phet, LightBulbNode, LightRaysNode, light, bulb | Status: complete
========================================================================

# LightBulbNode

`LightBulbNode` (from `scenerystack/scenery-phet`) draws a light bulb that glows in response to a `brightnessProperty` in the range `[0, 1]`: at `0` only the "off" bulb image is shown, and as brightness rises the "on" image fades in (via opacity) while a [`LightRaysNode`](/api/scenery-phet/light-rays-node) radiates more and longer rays behind it. It's the standard "is this circuit/light source active, and how strongly" visual used across circuit and light-related simulations.

```ts
import { LightBulbNode } from 'scenerystack/scenery-phet';
import { NumberProperty } from 'scenerystack/axon';
```

## A minimal example

```ts
const brightnessProperty = new NumberProperty( 0 ); // 0 (off) to 1 (full brightness)

const bulbNode = new LightBulbNode( brightnessProperty, {
  bulbImageScale: 0.5
} );

// Later, as current/voltage changes:
brightnessProperty.value = 0.75;
```

## Constructor

```ts
new LightBulbNode(
  brightnessProperty: TReadOnlyProperty<number>,
  providedOptions?: LightBulbNodeOptions
)
```

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `bulbImageScale` | `0.33` | Scale applied to both the "on" and "off" bulb images |
| `lightBulbOnImage` / `lightBulbOffImage` | PhET's standard bulb mipmaps | Override to use custom bulb artwork |
| `lightRaysNodeOptions` | `{}` | Options forwarded to the internal [`LightRaysNode`](/api/scenery-phet/light-rays-node) (`x`/`y` are computed automatically to center the rays behind the bulb) |

::: warning `brightnessProperty` must stay within `[0, 1]`, and updates pause while invisible
`LightBulbNode` asserts that `brightnessProperty.value` is between `0` and `1` inclusive. For performance, it also skips recomputing the "on" image's opacity and the rays while the node is invisible, and only catches up (via a `visibleProperty` listener) the next time it becomes visible — so don't expect a `LightBulbNode` hidden behind another screen's content to be pixel-accurate the instant you show it if brightness changed many times while hidden; it will simply jump straight to the current value.
:::

`LightBulbNode` links to `brightnessProperty` for the lifetime of the Node and unlinks in its own `dispose()` override — see [Dispose and Memory Management](/patterns/dispose-and-memory-management) if you're creating and destroying bulbs dynamically (e.g. one per circuit element in a list).


========================================================================
Page: LightRaysNode
URL: https://veillette.github.io/Almanach/api/scenery-phet/light-rays-node
Source: docs/api/scenery-phet/light-rays-node.md
Category: API | Tags: scenery-phet, LightRaysNode, light, rays | Status: complete
========================================================================

# LightRaysNode

`LightRaysNode` (from `scenerystack/scenery-phet`) draws a fan of straight line segments radiating outward from a circle of a given radius, filling roughly three-quarters of the surrounding circle. It's the "glow" effect behind [`LightBulbNode`](/api/scenery-phet/light-bulb-node) — which constructs one internally — but it's a standalone `Path` you can attach to any circular light source (a laser aperture, a glowing indicator, etc.) and drive directly.

```ts
import { LightRaysNode } from 'scenerystack/scenery-phet';
```

## A minimal example

```ts
const bulbRadius = 20;

const raysNode = new LightRaysNode( bulbRadius, {
  stroke: 'yellow',
  maxRays: 40,
  maxRayLength: 150
} );

raysNode.setBrightness( 0.75 ); // 0 (no rays, invisible) to 1 (maxRays, full length)
```

## Constructor

```ts
new LightRaysNode( bulbRadius: number, providedOptions?: LightRaysNodeOptions )
```

`bulbRadius` is the radius of the circle the rays emanate from (they start at that radius, not at the origin).

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `minRays` / `maxRays` | `8` / `60` | Number of rays at brightness `0` (rays only appear above brightness `0`) and brightness `1` |
| `minRayLength` / `maxRayLength` | `0` / `200` | Ray length at the low and high ends of the brightness range |
| `shortRayLineWidth` / `mediumRayLineWidth` / `longRayLineWidth` | `0.5` / `1` / `1.5` | Stroke widths interpolated across as computed ray length grows |
| `stroke` (inherited `PathOptions`) | `'yellow'` | Color of the rays |

## Methods

| Method | Effect |
| --- | --- |
| `setBrightness( brightness )` | Recomputes the number, length, and line width of rays for a brightness in `[0, 1]`, and sets `visible = false` when `brightness` is exactly `0` |

::: tip At brightness `0`, the shape becomes an invisible circle, not an empty shape
When `numberOfRays` drops to `0`, `LightRaysNode` still assigns an (invisible, since `visible` is set to `false`) circle of radius `bulbRadius` as its shape rather than clearing it entirely — this keeps local bounds well-defined at construction time instead of momentarily reporting empty bounds.
:::


========================================================================
Page: LineArrowNode
URL: https://veillette.github.io/Almanach/api/scenery-phet/line-arrow-node
Source: docs/api/scenery-phet/line-arrow-node.md
Category: API | Tags: scenery-phet, LineArrowNode, arrow, vector | Status: complete
========================================================================

# LineArrowNode

`LineArrowNode` (from `scenerystack/scenery-phet`) draws an arrow from three separately-stroked line segments: one for the tail, and two forming a V-shaped, open (unfilled) arrowhead. It exists alongside [`ArrowNode`](/api/scenery-phet/arrow-node) as a deliberately lighter-weight alternative — read on for when to reach for which.

## LineArrowNode vs. ArrowNode

Both draw an arrow between two points, but they render it completely differently:

| | `ArrowNode` | `LineArrowNode` |
| --- | --- | --- |
| Geometry | One filled `Shape` (tail + head combined into a single closed outline) | Two `Path`s: a straight tail line segment, and an open two-segment "V" head |
| Appearance | Solid, filled arrowhead — the classic "vector diagram" arrow | Open, stroke-only arrowhead — thinner, more like a technical-drawing callout |
| Head sizing near short arrows | `fractionalHeadHeight` shrinks the head so it never overwhelms a short shaft | Head height is simply capped at `0.99 *` the arrow's length; no separate fractional-scaling option |
| `doubleHead` / dynamic head scaling | Supported (`doubleHead`, `isHeadDynamic`, `scaleTailToo`) | Not supported — always single-headed, fixed head size |
| Typical use | Force/velocity vectors, filled callout arrows | Thin diagram annotations, sort/reorder cue arrows, anywhere a heavier filled arrowhead would be visually too "loud" |

If you're unsure which to use: reach for `ArrowNode` by default (it's the more common, more configurable choice across PhET sims), and switch to `LineArrowNode` specifically when you want a thinner, unfilled arrowhead that reads as a line drawing rather than a solid vector glyph.

```ts
import { LineArrowNode } from 'scenerystack/scenery-phet';
```

## A minimal example

```ts
const cueArrow = new LineArrowNode( 0, 0, 0, -30, {
  stroke: 'black',
  headHeight: 8,
  headWidth: 8,
  tailLineWidth: 1.5
} );

// Reposition later without creating a new Node:
cueArrow.setTailAndTip( 0, 0, 40, 0 );
```

## Constructor

```ts
new LineArrowNode( tailX: number, tailY: number, tipX: number, tipY: number, providedOptions?: LineArrowNodeOptions )
```

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `stroke` | `'black'` | Stroke color of both the tail and the head |
| `lineJoin` | `'miter'` | Affects the appearance of the arrow tip, where the two head segments meet |
| `lineCap` | `'butt'` | Affects the tail's ends and the outside ends of the head segments |
| `headHeight` | `10` | Length of the arrowhead along the shaft; clamped to `0.99 ×` the total arrow length for short arrows |
| `headWidth` | `10` | Width of the arrowhead's open "V" |
| `headLineWidth` | `1` | Stroke width of the two head segments |
| `tailLineWidth` | `1` | Stroke width of the tail segment |
| `tailLineDash` | `[]` | Dash pattern for the tail, e.g. `[ 4, 2 ]` for a dashed shaft |

## Methods

| Method | Effect |
| --- | --- |
| `setTailAndTip( tailX, tailY, tipX, tipY )` | Repositions both ends and rebuilds both the tail and head shapes |

::: tip No `doubleHead` option
Unlike `ArrowNode`, `LineArrowNode` always draws exactly one arrowhead, at the tip end. If you need heads on both ends, construct two `LineArrowNode`s back-to-back or use `ArrowNode` with `doubleHead: true`.
:::


========================================================================
Page: LockNode
URL: https://veillette.github.io/Almanach/api/scenery-phet/lock-node
Source: docs/api/scenery-phet/lock-node.md
Category: API | Tags: scenery-phet, LockNode, icon, toggle, padlock | Status: complete
========================================================================

# LockNode

`LockNode` (from `scenerystack/scenery-phet`) shows a padlock that visually flips between a closed-lock image and an open-lock image, driven entirely by a boolean `Property`. It's built on top of `sun`'s `BooleanToggleNode`, so it inherits that class's simple "one Property, two Nodes" swapping behavior rather than defining any of its own. It's typically wrapped in a button (an `EyeToggleButton`-style toggle or a plain `RectangularPushButton`) so clicking it flips `isLockedProperty` — `LockNode` itself is just the icon, not a clickable control.

```ts
import { LockNode } from 'scenerystack/scenery-phet';
import { BooleanProperty } from 'scenerystack/axon';
```

## A minimal example

```ts
const isLockedProperty = new BooleanProperty( true );

const lockIcon = new LockNode( isLockedProperty );

// Elsewhere, e.g. inside a button's listener:
isLockedProperty.toggle();
```

Both the open and closed lock images are wrapped in `AlignBox`es that share a single `AlignGroup`, and the open-lock image gets an extra `HStrut` on its left — this keeps the lock body horizontally centered and the overall icon the same effective width in both states, so surrounding layout (e.g. inside an `HBox`) doesn't shift when the state toggles.

## Constructor

```ts
new LockNode( isLockedProperty: TProperty<boolean>, providedOptions?: LockNodeOptions )
```

| Parameter | Description |
| --- | --- |
| `isLockedProperty` | `true` shows the closed-lock image, `false` shows the open-lock image |
| `providedOptions` | `LockNodeOptions` — `BooleanToggleNodeOptions` (from `sun`) with no additional self options; accepts things like `alignChildren`, plus any `NodeOptions` |

::: tip `LockNode` has no self options of its own
Every option it accepts comes from `BooleanToggleNode` (which in turn extends `ToggleNode<boolean>`). If you need to change how the closed/open icons are wrapped or spaced beyond what `BooleanToggleNode`'s options expose, build your own `ToggleNode` from the raw `lockClosed_png` / `lockOpened_png` images instead.
:::


========================================================================
Page: MagnifyingGlassNode
URL: https://veillette.github.io/Almanach/api/scenery-phet/magnifying-glass-node
Source: docs/api/scenery-phet/magnifying-glass-node.md
Category: API | Tags: scenery-phet, MagnifyingGlassNode | Status: complete
========================================================================

# MagnifyingGlassNode

`MagnifyingGlassNode` (from `scenerystack/scenery-phet`) draws a magnifying glass: a stroked circle (the "glass") with a short diagonal line (the "handle") extending from its lower-left, built entirely from `Circle` and `Line` — no image assets. It optionally centers an arbitrary icon `Node` inside the glass, which is how [`ZoomButton`](/api/scenery-phet/zoom-button-groups) and `MagnifyingGlassZoomButtonGroup` place a "+" or "−" sign inside the lens.

```ts
import { MagnifyingGlassNode } from 'scenerystack/scenery-phet';
import { PlusNode } from 'scenerystack/scenery-phet';
```

## A minimal example

```ts
// A plain magnifying glass, no icon inside.
const magnifyingGlassNode = new MagnifyingGlassNode( {
  glassRadius: 20
} );

// A magnifying glass with a "+" centered in the lens, matching ZoomButton's look.
const zoomInIcon = new MagnifyingGlassNode( {
  glassRadius: 15,
  icon: new PlusNode( { size: new Dimension2( 1.3 * 15, 15 / 3 ) } )
} );
```

## Constructor

```ts
new MagnifyingGlassNode( providedOptions: MagnifyingGlassNodeOptions )
```

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `glassRadius` | `15` | Radius of the circular glass; also drives the glass's stroke width (`0.25 × glassRadius`) and the handle's length/thickness |
| `glassFill` | `'white'` | Fill of the glass interior |
| `glassStroke` | `'black'` | Stroke color of both the glass rim and the handle |
| `icon` | `null` | An optional `Node`, centered inside the glass if provided (`content` itself is not settable — the glass and handle are always built) |

::: tip It's a pure icon `Node`, not a button
`MagnifyingGlassNode` has no interactive behavior of its own — it's just the drawn glyph. To make it clickable, wrap it as the `content` of a [`RectangularPushButton`](/api/sun/rectangular-push-button) yourself, or use the pre-built [`ZoomButton` / zoom button groups](/api/scenery-phet/zoom-button-groups), which already do exactly that.
:::


========================================================================
Page: MathSymbolFont
URL: https://veillette.github.io/Almanach/api/scenery-phet/math-symbol-font
Source: docs/api/scenery-phet/math-symbol-font.md
Category: API | Tags: scenery-phet, MathSymbolFont, typography | Status: verified
========================================================================

# MathSymbolFont

`MathSymbolFont` (from `scenerystack/scenery-phet`) is a `Font` subclass fixed to `"Times New Roman", Times, serif` and an italic style, used exclusively for rendering math symbols and variables (`x`, `y`, `θ`, …). It exists precisely so that math symbols look typographically different from ordinary sim UI text — which should always use [`PhetFont`](/api/scenery-phet/phet-font), a sans-serif family — matching the convention (borrowed from print textbooks) that variables are set in italic serif type.

```ts
import { MathSymbolFont } from 'scenerystack/scenery-phet';
```

## A minimal example

```ts
// Convenience form: just a size
const variableFont = new MathSymbolFont( 18 );

const xLabel = new Text( 'x', { font: variableFont } );
```

```ts
// Embedding a symbol inside a larger RichText string, without a separate Text node
const equationText = new RichText(
  `F = ${MathSymbolFont.getRichTextMarkup( 'm' )}${MathSymbolFont.getRichTextMarkup( 'a' )}`
);
```

## Constructor

```ts
new MathSymbolFont( providedOptions?: number | string | MathSymbolFontOptions )
```

A bare `number` or `string` is shorthand for `{ size: providedOptions }`, matching `PhetFont`'s convenience form. `MathSymbolFontOptions` is `FontOptions` minus `family` — `family` is fixed and cannot be overridden through the constructor.

## Static members

| Member | Description |
| --- | --- |
| `MathSymbolFont.FAMILY` | The fixed font family string, `'"Times New Roman", Times, serif'` |
| `MathSymbolFont.getRichTextMarkup( text, style? )` | Returns a `<span style="...">` markup fragment that renders `text` in the math-symbol family/style, for embedding inside a `RichText` string alongside other content |
| `MathSymbolFont.createDerivedProperty( symbolStringProperty, options? )` | Wraps a dynamic (i18n) string Property so its value is always the `RichText`-markup-wrapped form, for use directly as `RichText` content |

## `PhetFont` vs. `MathSymbolFont`

| | `PhetFont` | `MathSymbolFont` |
| --- | --- | --- |
| Family | Sans-serif (PhET's configured UI family) | Serif (`Times New Roman`) |
| Style | Upright (unless you set `style: 'italic'` yourself) | Italic by default |
| Use for | Labels, titles, readouts — all ordinary sim UI text | Math variables and symbols only (`x`, `t`, `θ`) |

::: tip Use `getRichTextMarkup`/`createDerivedProperty` when mixing symbols into a larger string
Constructing a whole separate `Text` node with `MathSymbolFont` only works for a standalone symbol. If a symbol appears inline within a larger translated string (e.g. "Velocity, *v*, is constant"), use `MathSymbolFont.getRichTextMarkup()` (or its Property-aware counterpart) inside a `RichText` instead, so the symbol's italic serif styling survives string interpolation and translation.
:::


========================================================================
Page: MatrixNode
URL: https://veillette.github.io/Almanach/api/scenery-phet/matrix-node
Source: docs/api/scenery-phet/matrix-node.md
Category: API | Tags: scenery-phet, MatrixNode, matrix, math | Status: complete
========================================================================

# MatrixNode

`MatrixNode` (from `scenerystack/scenery-phet`) displays a static MxN grid of values — numbers or strings — flanked by hand-drawn bracket shapes, the standard way to typeset a mathematical matrix. It was built for a specific demo (a Google Group question about rendering matrices in HTML5) rather than as a general linear-algebra display widget, so treat it as a solid starting point rather than a fully general math-typesetting tool.

```ts
import { MatrixNode } from 'scenerystack/scenery-phet';
```

## A minimal example

```ts
const matrixNode = new MatrixNode( [
  [ 2, 3, -2 ],
  [ 1, 0, -4 ],
  [ 2, -1, -6 ]
], {
  decimalPlaces: 0,
  cellXSpacing: 20
} );
```

Values may be numbers or strings, mixed freely within the same matrix — a string is rendered verbatim (handy for a variable name or an ellipsis), while a number is formatted according to `decimalPlaces` and `stripTrailingZeros`. Every row must have the same number of columns; `MatrixNode` asserts this at construction.

## Constructor

```ts
new MatrixNode( matrix: ( number | string )[][], options?: object )
```

`matrix` is in row-major order: `matrix[ row ][ column ]`.

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `font` | `new PhetFont( 20 )` | Font used for every cell value |
| `decimalPlaces` | `0` | Decimal places shown for numeric cell values |
| `stripTrailingZeros` | `true` | Whether `1.20` collapses to `1.2`; set `false` to keep a fixed number of decimals |
| `cellXSpacing` | `25` | Horizontal spacing between columns |
| `cellYSpacing` | `5` | Vertical spacing between rows |
| `leftBracketXSpacing` / `rightBracketXSpacing` | `10` / `10` | Horizontal gap between each bracket and the grid of values |
| `bracketWidth` | `8` | Width (horizontal extent) of each bracket's "foot" |
| `bracketHeightPadding` | `5` | Extra height added above/below the grid when sizing the brackets |
| `bracketNodeOptions` | `{ stroke: 'black', lineWidth: 2 }` | `Path` options forwarded to both bracket shapes |

::: tip Cells are right-aligned and sized via a shared `AlignGroup`
Every cell is wrapped in an `AlignBox` sharing one `AlignGroup`, so all cells in the matrix occupy the same width and align consistently on their right edge — a matrix mixing `-6` and `100` won't have its columns drift out of alignment. There's no built-in support for per-column alignment or column headers; build a wrapper `Node` around `MatrixNode` if you need those.
:::


========================================================================
Page: MeasuringTapeNode
URL: https://veillette.github.io/Almanach/api/scenery-phet/measuring-tape-node
Source: docs/api/scenery-phet/measuring-tape-node.md
Category: API | Tags: scenery-phet, MeasuringTapeNode, measurement, drag | Status: complete
========================================================================

# MeasuringTapeNode

`MeasuringTapeNode` (from `scenerystack/scenery-phet`) draws a classic tape-measure image with two independently draggable ends — a base (the case) and a tip (the free end of the tape) — connected by a line, with a text readout showing the distance between them in whatever units you supply. Dragging the base moves the whole tape (tip included); dragging the tip alone extends or retracts the tape. It's the standard "let the user measure something" tool across PhET simulations, distinct from [`RulerNode`](/api/scenery-phet/ruler-node), which is a rigid ruler graphic rather than a two-point tape.

```ts
import { MeasuringTapeNode } from 'scenerystack/scenery-phet';
import { Property } from 'scenerystack/axon';
```

## A minimal example

```ts
const unitsProperty = new Property( { name: 'cm', multiplier: 100 } );

const measuringTapeNode = new MeasuringTapeNode( unitsProperty, {
  tandem: tandem.createTandem( 'measuringTapeNode' ),
  dragBounds: layoutBounds.eroded( 20 ) // model-coordinate Bounds2 the tape stays within
} );

// Position it explicitly (base at model origin, tip 1 model unit to the right)
measuringTapeNode.basePositionProperty.value = new Vector2( 0, 0 );
measuringTapeNode.tipPositionProperty.value = new Vector2( 1, 0 );
```

The `multiplier` in `unitsProperty`'s value converts the internal model-coordinate distance into display units before formatting the readout — a `multiplier: 100` reading of `0.5` model units displays as `50 cm`.

## Constructor

```ts
new MeasuringTapeNode(
  unitsProperty: TReadOnlyProperty<MeasuringTapeUnits>,
  providedOptions?: MeasuringTapeNodeOptions
)
```

where `MeasuringTapeUnits = { name: string; multiplier: number }`.

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `basePositionProperty` | new `Vector2Property( (0,0) )` | Model-coordinate position of the base (case); supply your own to share it with model code |
| `tipPositionProperty` | new `Vector2Property( (1,0) )` | Model-coordinate position of the tip |
| `hasValue` | `true` | Set `false` to hide the text readout entirely (useful when building an icon) |
| `dragBounds` | `Bounds2.EVERYTHING` | Model-coordinate bounds constraining the base (and, if `isTipDragBounded`, the tip) |
| `modelViewTransform` | identity | Must have equal x/y scale factors — asserted at construction |
| `significantFigures` | `1` | Digits shown in the distance readout |
| `isTipDragBounded` | `true` | Whether the tip is also constrained to `dragBounds`, or free to roam anywhere |
| `interactive` | `true` | Set `false` to disable the built-in drag/keyboard-drag listeners, e.g. when using `MeasuringTapeNode.createIcon()` |
| `baseScale` | `0.8` | Scales the base image, and with it the crosshair/text layout that's positioned relative to it |
| `textColor` / `textBackgroundColor` | `'white'` / `null` | Readout text and background colors |
| `baseDragStarted` / `baseDragEnded` | no-ops | Callbacks fired when a base drag starts/ends — handy for "dropped into toolbox" detection |
| `phetioFeaturedMeasuredDistanceProperty` | `false` | Whether `measuredDistanceProperty` is marked `phetioFeatured` |

## Instance properties

| Property | Type | Description |
| --- | --- | --- |
| `measuredDistanceProperty` | `TReadOnlyProperty<number>` | Model-coordinate distance between base and tip, as a `DerivedProperty` |
| `basePositionProperty` / `tipPositionProperty` | `Property<Vector2>` | Live positions, read-write unless you passed your own |
| `isBaseUserControlledProperty` / `isTipUserControlledProperty` | `TReadOnlyProperty<boolean>` | Whether the user is actively dragging that end right now |
| `modelViewTransformProperty` | `Property<ModelViewTransform2>` | Wraps the `modelViewTransform` option; update it to re-project the tape live |

## Methods

| Method | Effect |
| --- | --- |
| `reset()` | Resets `basePositionProperty`/`tipPositionProperty` — only the ones this Node created itself (see warning below) |
| `setDragBounds( bounds )` / `getDragBounds()` | Changes the model-coordinate drag bounds, immediately clamping the current base (and tip, if bounded) into them |
| `startBaseDrag( event )` | Programmatically begins a base drag from a Scenery input event |
| `getLocalBaseCenter()` / `getLocalBaseBounds()` | Base image geometry in the Node's local coordinate frame |
| `MeasuringTapeNode.createIcon( options? )` *(static)* | Builds a non-interactive, valueless snapshot `Node` suitable for a toolbox icon |

::: warning `reset()` and `dispose()` only touch Properties `MeasuringTapeNode` created itself
If you pass your own `basePositionProperty`/`tipPositionProperty` (so your model can read them directly), `MeasuringTapeNode` does **not** reset or dispose them — you own their lifecycle. `reset()`/`dispose()` only reset/dispose the default `Vector2Property` instances it constructs internally when you *don't* supply your own. Forgetting this is a common source of "reset all doesn't move the tape back" bugs when a model-owned position Property is involved.
:::


========================================================================
Page: Movement and Border Alerters
URL: https://veillette.github.io/Almanach/api/scenery-phet/movement-and-border-alerters
Source: docs/api/scenery-phet/movement-and-border-alerters.md
Category: API | Tags: scenery-phet, Alerter, MovementAlerter, BorderAlertsDescriber, voicing, description, accessibility | Status: complete
========================================================================

# Movement and Border Alerters

When a screen-reader or Voicing user drags something around a bounded play area, they need spoken feedback for two things a sighted mouse user gets for free: which direction the object just moved, and whether it just ran into the edge of its allowed area. `Alerter`, `MovementAlerter`, and `BorderAlertsDescriber` (from `scenerystack/scenery-phet`) are the layered utilities that generate and dispatch that feedback — to both description (screen readers, via the PDOM) and Voicing (speech synthesis), depending on how they're configured.

```ts
import { MovementAlerter } from 'scenerystack/scenery-phet';

const movementAlerter = new MovementAlerter( ball.positionProperty, {
  descriptionAlertNode: ballNode,   // required for description alerts to reach an UtteranceQueue
  modelViewTransform: modelViewTransform
} );

// Typically called at the end of a drag (see PhET a11y convention below).
someDragListener.endDrag = () => movementAlerter.endDrag();
```

## Alerter: the generic base

`Alerter` is a small `EnabledComponent` that knows how to send an alertable (a string, a `ResponsePacket`, or an `Utterance`) to whichever queues are configured — it doesn't know anything about movement or direction itself. `MovementAlerter` extends it; you'd only reach for plain `Alerter` when building an unrelated alerting utility that wants the same to-Voicing/to-description plumbing.

| Option | Default | Effect |
| --- | --- | --- |
| `alertToVoicing` | `true` | If `true`, `alert()` also sends the alertable to the Voicing queue (requires the alertable to be an `Utterance`) |
| `descriptionAlertNode` | `null` | The `Node` used to reach a `Display`'s `UtteranceQueue` for description alerts; **no description alert is sent without this** |

| Method | Effect |
| --- | --- |
| `alert( alertable )` | Sends to Voicing (if enabled) and to description (if `descriptionAlertNode` is set), only while `enabled` |
| `addAccessibleResponse( alertable )` | Description-only alert, forwarded through `descriptionAlertNode` |

## MovementAlerter: describing which way something moved

`MovementAlerter` compares a `positionProperty`'s current value against the position at the last alert, converts the delta into one of eight compass directions (`UP`, `DOWN`, `LEFT`, `RIGHT`, and the four diagonals) using `Math.atan2` in the *view* coordinate frame (via an optional `modelViewTransform`), and speaks/describes the matching phrase from a `movementAlerts` map.

| Option | Default | Effect |
| --- | --- | --- |
| `movementAlerts` | The 8 default direction phrases ("up", "down and to the left", …) | Map from direction key to the alertable spoken for it; omit a key (or pass `{}`) to silence that direction |
| `modelViewTransform` | Identity transform | Converts model-frame positions to view-frame before computing the direction, so "up" always means visually up |
| `alertDiagonal` | `false` | If `false`, a diagonal move like up-and-left is split into two back-to-back alerts ("up", then "left") instead of one composite phrase |
| `borderAlertsOptions` | — | Forwarded to an internal `BorderAlertsDescriber` (see below) |

| Method | Effect |
| --- | --- |
| `alertDirectionalMovement()` | Computes and alerts the direction moved since the last alert; call after a drag changes the position |
| `endDrag( domEvent? )` | The typical hook: alerts directional movement, *then* asks the internal `BorderAlertsDescriber` whether a border was hit and alerts that too — PhET convention is to call this from a drag listener's `end` |
| `reset()` | Resets the last-alerted position and the border describer |

```ts
import { MovementAlerter } from 'scenerystack/scenery-phet';
import { RichDragListener } from 'scenerystack/scenery';

const movementAlerter = new MovementAlerter( ball.positionProperty, {
  descriptionAlertNode: ballNode,
  borderAlertsOptions: {
    boundsProperty: model.dragBoundsProperty
  }
} );

ballNode.addInputListener( new RichDragListener( {
  positionProperty: ball.positionProperty,
  transform: modelViewTransform,
  end: () => movementAlerter.endDrag()
} ) );
```

## BorderAlertsDescriber: the border-hit sub-describer

`BorderAlertsDescriber` is used internally by `MovementAlerter` (via `borderAlertsOptions`) to decide whether the current position sits exactly on the left/right/top/bottom edge of a bounds `Property`, and if so return the matching alert. It's rarely constructed directly, but its options are what you pass through `MovementAlerter`'s `borderAlertsOptions`:

| Option | Default | Effect |
| --- | --- | --- |
| `boundsProperty` | Infinite bounds (never triggers) | The drag-bounds `Property<Bounds2>` to check the position against |
| `leftAlert` / `rightAlert` / `topAlert` / `bottomAlert` | Default per-edge phrases | The alertable for each edge; pass `null` to skip alerting that edge |

`getAlertOnEndDrag( position, domEvent? )` is the method `MovementAlerter.endDrag()` calls; if the position is in a corner (touching two edges at once), an optional `domEvent` lets it prefer whichever edge matches the key that was actually pressed.

::: tip These generate alertables — they don't create the UtteranceQueue connection themselves
`Alerter`/`MovementAlerter` only produce the right *content*; getting that content to a screen reader still requires `descriptionAlertNode` to be an actual displayed `Node` connected to a `Display`, and getting it spoken via Voicing still requires the alerted `Utterance` to be registered the normal Voicing way. See [Voicing](/accessibility/voicing) and [Describing Dynamic State](/accessibility/describing-dynamic-state) for that layer.
:::


========================================================================
Page: NumberControl
URL: https://veillette.github.io/Almanach/api/scenery-phet/number-control
Source: docs/api/scenery-phet/number-control.md
Category: API | Tags: scenery-phet, NumberControl | Status: verified
========================================================================

# NumberControl

`NumberControl` (from `scenerystack/scenery-phet`) bundles a title, a value readout, a slider, and (by default) increment/decrement arrow buttons into one composite `Node` bound to a numeric Property. It's the standard way to expose a bounded numeric quantity to the user without hand-assembling a slider, a `NumberDisplay`, and arrow buttons yourself every time.

```ts
import { NumberControl } from 'scenerystack/scenery-phet';
import { NumberProperty } from 'scenerystack/axon';
import { Range } from 'scenerystack/dot';
```

## A minimal example

```ts
const frequencyProperty = new NumberProperty( 5, { range: new Range( 0, 10 ) } );

const frequencyControl = new NumberControl(
  'Frequency',
  frequencyProperty,
  new Range( 0, 10 ),
  {
    delta: 0.5,
    numberDisplayOptions: {
      decimalPlaces: 1,
      valuePattern: '{{value}} Hz'
    }
  }
);
```

<SceneryDemo demo="number-control" />

## Constructor

```ts
new NumberControl(
  title: string | TReadOnlyProperty<string> | Node,
  numberProperty: PhetioProperty<number>,
  numberRange: Range,
  providedOptions?: NumberControlOptions
)
```

`title` can be a plain string, a string Property (for i18n), or an arbitrary `Node` if you need something richer than text.

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `delta` | `1` | Step size used by both the arrow buttons and the slider's keyboard shift-step |
| `includeArrowButtons` | `true` | Whether to show the increment/decrement arrow buttons |
| `numberDisplayOptions` | `{}` | Options forwarded to the internal `NumberDisplay` (readout formatting, units, decimal places, …) |
| `sliderOptions` | `{}` | Options forwarded to the internal `Slider` — accepts `majorTicks`, `minorTickSpacing` in addition to normal slider options |
| `arrowButtonOptions` | `{}` | Options forwarded to the increment/decrement `ArrowButton`s |
| `titleNodeOptions` | `{}` | Options forwarded to the title `Text`/`RichText` |
| `useRichText` | `false` | Render the title with `RichText` instead of `Text` |
| `enabledRangeProperty` | — | Constrains the effective slider/arrow-button range to a sub-range of `numberRange` |
| `startCallback` / `endCallback` | no-ops | Called when interaction begins/ends on **any** subcomponent (slider drag or arrow press) |
| `layoutFunction` | `NumberControl.createLayoutFunction1()` | Arranges title, readout, slider, and arrow buttons; swap in `createLayoutFunction2`/`3`/`4` for the other standard layouts |
| `soundGenerator` | auto-created | A `ValueChangeSoundPlayer`; pass `null` for silence |

## Static helpers

| Static member | Purpose |
| --- | --- |
| `NumberControl.withMinMaxTicks( label, property, range, options? )` | Convenience constructor that adds major ticks labeled with the range's min and max |
| `NumberControl.createLayoutFunction1()` … `createLayoutFunction4()` | Pre-built layout strategies for `options.layoutFunction`, each with its own spacing/alignment options |

## Public API

| Member | Description |
| --- | --- |
| `slider` | The internal `HSlider`, exposed read-only for accessibility wiring |

::: warning Don't mix general and per-component callbacks
Use either the top-level `startCallback`/`endCallback` pair, **or** the per-component callbacks nested in `sliderOptions`/`arrowButtonOptions` (`startDrag`, `leftStart`, `rightEnd`, …) — never both. `NumberControl` asserts against mixing them, since it can't guarantee sensible ordering between the two mechanisms.
:::


========================================================================
Page: NumberDisplay
URL: https://veillette.github.io/Almanach/api/scenery-phet/number-display
Source: docs/api/scenery-phet/number-display.md
Category: API | Tags: scenery-phet, NumberDisplay | Status: verified
========================================================================

# NumberDisplay

`NumberDisplay` (from `scenerystack/scenery-phet`) shows a `Property<number | null>`'s value as formatted text inside a bordered background rectangle. It pre-computes its width from a supplied `displayRange` so the background doesn't resize as the value changes — this is the readout half of [`NumberControl`](/api/scenery-phet/number-control), which composes one internally, but it's equally useful standalone whenever you need a numeric readout without a slider attached.

```ts
import { NumberDisplay } from 'scenerystack/scenery-phet';
import { NumberProperty } from 'scenerystack/axon';
import { Range } from 'scenerystack/dot';
```

## A minimal example

```ts
const temperatureProperty = new NumberProperty( 20, { range: new Range( -20, 100 ) } );

const temperatureDisplay = new NumberDisplay( temperatureProperty, new Range( -20, 100 ), {
  decimalPlaces: 1,
  valuePattern: '{{value}} °C',
  align: 'right'
} );
```

## Constructor

```ts
new NumberDisplay(
  numberProperty: TReadOnlyProperty<number | null>,
  displayRange: Range,
  providedOptions?: NumberDisplayOptions
)
```

`displayRange` is used only to measure the widest possible formatted string (so the background is sized once and doesn't jitter) — it's independent of `numberProperty`'s own range and doesn't clamp the displayed value.

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `align` | `'right'` | Horizontal alignment of the value text (`'center'`, `'left'`, `'right'`) |
| `valuePattern` | `SunConstants.VALUE_NAMED_PLACEHOLDER` (`'{{value}}'`) | Template the formatted value is filled into, e.g. `'{{value}} m/s'` |
| `decimalPlaces` | `0` | Decimal places to show; `null` displays the full value. Mutually exclusive with `numberFormatter` |
| `numberFormatter` | `null` | A `( n: number ) => string` for full control over formatting; mutually exclusive with `valuePattern`/`decimalPlaces`/`numberFormatOptions` |
| `useRichText` | `false` | Render the value with `RichText` instead of `Text` (needed for markup, e.g. superscripts) |
| `textOptions` | `{ font: new PhetFont(20), fill: 'black' }` | Options forwarded to the internal `Text`/`RichText` |
| `xMargin` / `yMargin` | `8` / `2` | Margin between the value text and the background edge |
| `cornerRadius` | `0` | Background rectangle corner radius |
| `backgroundFill` / `backgroundStroke` | `'white'` / `'lightGray'` | Background rectangle colors |
| `minBackgroundWidth` | `0` | Floor on the computed background width |
| `noValueString` | `MathSymbols.NO_VALUE` (an em dash) | Text shown when `numberProperty.value` is `null` — the PhET standard; avoid overriding lightly |
| `noValueAlign` / `noValuePattern` | fall back to `align` / `valuePattern` | Separate alignment/pattern for the no-value case, if needed |

## Public API

| Member | Description |
| --- | --- |
| `valueStringProperty` | Read-only `TReadOnlyProperty<string>` of the currently displayed (visual) text |
| `numberFont` / `numberFill` | Settable properties for the value text's font and fill |
| `backgroundFill` / `backgroundStroke` / `backgroundWidth` | Settable properties for the background rectangle |

::: tip `valuePattern` and `decimalPlaces` are mutually exclusive with `numberFormatter`
Pass either the simple `valuePattern` + `decimalPlaces` pair, or a `numberFormatter` function for full control — never both. `NumberDisplay` asserts if it detects both were customized, since it can't tell which formatting path should win.
:::


========================================================================
Page: OffScaleIndicatorNode
URL: https://veillette.github.io/Almanach/api/scenery-phet/off-scale-indicator-node
Source: docs/api/scenery-phet/off-scale-indicator-node.md
Category: API | Tags: scenery-phet, OffScaleIndicatorNode, plot, chart, accessibility | Status: complete
========================================================================

# OffScaleIndicatorNode

`OffScaleIndicatorNode` (from `scenerystack/scenery-phet`) is a small `Panel` containing a text label and an `ArrowNode`, used to tell the user that a data point (or points) has gone off the visible edge of a plot — "points off scale," with an arrow pointing in whichever direction the data actually went. It's a static display component: you construct one per direction you need to support and toggle its `visible` property based on your model's state; it doesn't track any Property itself.

```ts
import { OffScaleIndicatorNode } from 'scenerystack/scenery-phet';
```

## A minimal example

```ts
const offScaleUpIndicator = new OffScaleIndicatorNode( 'up', {
  arrowTailLength: 20
} );
offScaleUpIndicator.visible = false;

// Later, when the model detects an out-of-range point:
offScaleUpIndicator.visible = pointsAreAboveChartTop;
```

For every direction except `'right'`, the arrow is placed to the left of the text; for `'right'`, the text comes first and the arrow points away to the right — so the arrow always points outward, away from the label, toward the edge of the plot it corresponds to.

## Constructor

```ts
new OffScaleIndicatorNode( direction: 'left' | 'right' | 'up' | 'down', providedOptions?: OffScaleIndicatorNodeOptions )
```

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `offScaleStringProperty` | PhET's built-in "points off scale" string | The label text; supply your own `TReadOnlyProperty<string>` to customize or localize it further |
| `arrowTailLength` | `25` | Length of the arrow's tail, oriented according to `direction` |
| `spacing` | `5` | Spacing between the label and the arrow inside the `HBox` |
| `arrowNodeOptions` | `{ tailWidth: 2 }` | Options forwarded to the internal `ArrowNode` |
| `richTextOptions` | `{ font: new PhetFont(14), maxWidth: 100, maxHeight: 50, align: 'left' }` | Options forwarded to the internal `RichText` label |
| `panelOptions` | `{ fill: 'white', stroke: 'black', cornerRadius: 3 }` | Options forwarded to the wrapping `Panel` |

## Accessibility

`OffScaleIndicatorNode` mixes in Scenery's `ReadingBlock` trait, so it's voicing-ready out of the box: if you don't supply `accessibleParagraph`, it derives one automatically from `direction` (e.g. "points off scale, up"), and `readingBlockNameResponse` defaults to that same string unless overridden. See [Voicing](/accessibility/voicing) for how `ReadingBlock` fits into PhET's broader accessibility story.

::: tip Direction controls layout and default text — it can't be changed after construction
`direction` is a constructor parameter, not a settable property, because it determines which side the arrow renders on and drives the default accessible paragraph. To point in a different direction, construct a new `OffScaleIndicatorNode` (typically PhET sims keep one instance per direction and toggle `visible`, rather than reusing a single instance).
:::


========================================================================
Page: PaperAirplaneNode and SimpleClockIcon
URL: https://veillette.github.io/Almanach/api/scenery-phet/paper-airplane-and-simple-clock-icon
Source: docs/api/scenery-phet/paper-airplane-and-simple-clock-icon.md
Category: API | Tags: scenery-phet, PaperAirplaneNode, SimpleClockIcon, icon | Status: complete
========================================================================

# PaperAirplaneNode and SimpleClockIcon

`PaperAirplaneNode` and `SimpleClockIcon` (both from `scenerystack/scenery-phet`) are two small, unrelated, non-interactive icon Nodes. They're grouped on this page because each is a single self-contained shape with no state to bind to — construct once, style with ordinary options, done. `SimpleClockIcon` in particular never animates or ticks; it's a frozen decorative face, not a live clock.

```ts
import { PaperAirplaneNode, SimpleClockIcon } from 'scenerystack/scenery-phet';
```

## PaperAirplaneNode

`PaperAirplaneNode extends Path` and draws the exact paper-airplane silhouette used in the PhET logo, traced from the coordinates in PhET's logo artwork file. It's a fixed shape — there's no way to change its proportions, only how it's painted and transformed like any other `Path`.

```ts
const airplaneIcon = new PaperAirplaneNode( {
  scale: 0.5
} );
```

| Option | Default | Effect |
| --- | --- | --- |
| `fill` | `PhetColorScheme.PHET_LOGO_YELLOW` | Fill color; override for a monochrome or themed variant |

`PaperAirplaneNodeOptions` also accepts any other `PathOptions` (`stroke`, `opacity`, `scale`, …). Because the underlying shape is fixed, resize it with `scale` rather than trying to pass width/height options — there are none.

## SimpleClockIcon

`SimpleClockIcon extends Node` and draws a plain circular clock face — an outer circle, a small center dot, and two clock hands frozen at a fixed "4 o'clock" position. It's intended purely as a visual stand-in for "this represents time" (e.g. a button icon), not as a live or interactive clock face.

```ts
const clockIcon = new SimpleClockIcon( 20, {
  fill: 'white',
  stroke: 'black',
  lineWidth: 2
} );
```

## Constructor

```ts
new SimpleClockIcon( radius: number, providedOptions?: SimpleClockIconOptions )
```

| Option | Default | Effect |
| --- | --- | --- |
| `fill` | `'white'` | Fill of the clock face circle |
| `stroke` | `'black'` | Stroke of the face circle, the center dot's fill, and both hands |
| `lineWidth` | `2` | Stroke width of both clock hands |

::: tip The hands are permanently fixed at "4 o'clock"
`SimpleClockIcon` has no Property, no animation, and no way to point the hands at an arbitrary time — the hour and minute hand angles are hard-coded. If you need a clock that reflects live simulation time, build a dedicated animated Node instead; use `SimpleClockIcon` only where a generic "clock" glyph is all that's needed.
:::


========================================================================
Page: ParametricSpringNode
URL: https://veillette.github.io/Almanach/api/scenery-phet/parametric-spring-node
Source: docs/api/scenery-phet/parametric-spring-node.md
Category: API | Tags: scenery-phet, ParametricSpringNode, spring, coil | Status: complete
========================================================================

# ParametricSpringNode

`ParametricSpringNode` (from `scenery-phet`) draws a coiled spring using a parametric curve (a variation on a prolate cycloid), rendered as two separate front/back `Path`s so the coil reads with a pseudo-3D over/under weave. Every shape parameter — loop count, radius, aspect ratio, phase, line width — is exposed as its own `NumberProperty`, so you can animate the spring (e.g. stretching it as a mass drags down on it) just by setting those Properties; the Node recomputes its shape automatically.

The origin `(0, 0)` of a `ParametricSpringNode` is at its **left-center**, not its bounds' top-left — useful to know when positioning it next to an anchor point.

```ts
import { ParametricSpringNode } from 'scenerystack/scenery-phet';
```

## A minimal example

```ts
const springNode = new ParametricSpringNode( {
  loops: 8,
  radius: 15,
  aspectRatio: 3,
  frontColor: 'lightBlue',
  middleColor: 'blue',
  backColor: 'darkblue',
  left: 100,
  centerY: 200
} );

// Stretch the spring by changing the loop radius live:
springNode.radiusProperty.value = 20;
```

## Constructor

```ts
new ParametricSpringNode( providedOptions?: ParametricSpringNodeOptions )
```

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `loops` | `10` | Number of coil loops (seeds `loopsProperty`) |
| `pointsPerLoop` | `40` | Points used to approximate one loop (seeds `pointsPerLoopProperty`); higher is smoother but costlier |
| `radius` | `10` | Radius of a loop at aspect ratio 1:1 (seeds `radiusProperty`) |
| `aspectRatio` | `4` | y:x aspect ratio of each loop, i.e. how "squashed" the coil looks (seeds `aspectRatioProperty`) |
| `phase` | `Math.PI` | Phase angle where the loop starts, in `(0, 2π)` (seeds `phaseProperty`) |
| `deltaPhase` | `Math.PI / 2` | Controls how much the coil "leans," a Lissajous-style parameter (seeds `deltaPhaseProperty`) |
| `xScale` | `2.5` | Multiplier stretching the coil horizontally as it progresses (seeds `xScaleProperty`) |
| `lineWidth` | `3` | Stroke width of both the front and back paths (seeds `lineWidthProperty`) |
| `leftEndLength` / `rightEndLength` | `15` / `25` | Length of the straight horizontal segments added at the left/right ends of the coil |
| `frontColor` / `middleColor` / `backColor` | `'lightGray'` / `'gray'` / `'black'` | Colors used to build the front and back paths' gradients (`middleColor` is the dominant color) |
| `boundsMethod` | `'accurate'` | Forwarded to the internal `Path`s; set to `'none'` for a large performance win if you only rely on `x`/`y` (not bounds-based layout) for positioning |

## Public API

| Member | Description |
| --- | --- |
| `loopsProperty`, `radiusProperty`, `aspectRatioProperty`, `pointsPerLoopProperty`, `lineWidthProperty`, `phaseProperty`, `deltaPhaseProperty`, `xScaleProperty` | Public `NumberProperty` for each shape parameter above; set any of them to reshape the spring live |
| `reset()` | Resets every one of the Properties above to its initial value |

::: warning Changing `loops`, `pointsPerLoop`, `aspectRatio`, `phase`, or `deltaPhase` rebuilds the point array; changing `radius`/`xScale` alone is cheaper
The first group of Properties changes how many points exist or how they're allocated to the front/back paths, so `ParametricSpringNode` regenerates the coil's `Vector2` points from scratch. `radiusProperty` and `xScaleProperty` alone only need to *mutate* the existing points in place — a meaningfully cheaper path internally. If you're animating a spring every frame, prefer driving `radiusProperty` (e.g. to simulate stretch) over the other parameters.
:::


========================================================================
Page: PhetColorScheme, SceneryPhetColors, and SceneryPhetConstants
URL: https://veillette.github.io/Almanach/api/scenery-phet/phet-color-scheme-and-constants
Source: docs/api/scenery-phet/phet-color-scheme-and-constants.md
Category: API | Tags: scenery-phet, PhetColorScheme, SceneryPhetColors, SceneryPhetConstants, colors, constants | Status: complete
========================================================================

# PhetColorScheme, SceneryPhetColors, and SceneryPhetConstants

`PhetColorScheme`, `SceneryPhetColors`, and `SceneryPhetConstants` (all from `scenerystack/scenery-phet`) are three small plain-object modules of shared defaults, in the same spirit as `scenerystack/sun`'s [`ColorConstants`/`SunConstants`](/api/sun/color-constants): reuse a fixed value from one of these tables instead of re-picking an RGB triple or a magic number every time a physics quantity or a round button shows up in a new sim. None of the three is a class — all are read directly as properties on a plain object (or, for `SceneryPhetColors`, a plain object of `ProfileColorProperty` instances).

```ts
import { PhetColorScheme, SceneryPhetColors, SceneryPhetConstants } from 'scenerystack/scenery-phet';
import { GaugeNode } from 'scenerystack/scenery-phet';
```

## A minimal example

```ts
// Color a force vector consistently with every other PhET sim that shows applied force:
const arrowFill = PhetColorScheme.APPLIED_FORCE;

// Size a custom round button the same as scenery-phet's own round buttons:
const buttonRadius = SceneryPhetConstants.DEFAULT_BUTTON_RADIUS;

// Read (or link to) the currently-active fill for a beaker drawing:
const beakerFill = SceneryPhetColors.solutionFillProperty.value;
```

## PhetColorScheme

A flat table of `Color` (from `scenerystack/scenery`) and one plain hex-string constant, mostly named after the physical quantity each color conventionally represents in PhET sims (kinetic/potential energy, forces, momentum, and so on) — the exact palette PhET's own physics sims (Forces and Motion, Energy Skate Park, etc.) draw from so a "kinetic energy" bar chart segment looks the same color from one sim to the next.

| Constant | Value | Notes |
| --- | --- | --- |
| `ACCELERATION` | `Color(255, 255, 50)` | |
| `APPLIED_FORCE` | `Color(236, 153, 55)` | |
| `BUTTON_YELLOW` | `Color(254, 225, 5)` | Same value as `PHET_LOGO_YELLOW` |
| `ELASTIC_POTENTIAL_ENERGY` | `Color(0, 204, 255)` | |
| `FRICTION_FORCE` | `Color(255, 85, 0)` | Same value as `RED_COLORBLIND` |
| `GRAVITATIONAL_FORCE` | `Color(50, 130, 215)` | |
| `GRAVITATIONAL_POTENTIAL_ENERGY` | `Color(55, 130, 215)` | |
| `HEAT_THERMAL_ENERGY` | `Color(255, 85, 0)` | Same value as `RED_COLORBLIND` |
| `IMAGINARY_PART` | `Color(153, 51, 102)` | |
| `KINETIC_ENERGY` | `Color(30, 200, 45)` | |
| `MOMENTUM` | `Color(50, 50, 255)` | |
| `NET_WORK` | `Color(0, 200, 0)` | "Dark green" |
| `NORMAL_FORCE` | `Color(255, 235, 0)` | |
| `PHET_LOGO_BLUE` | `Color(106, 206, 245)` | The blue in the PhET logo |
| `PHET_LOGO_YELLOW` | `Color(254, 225, 5)` | The yellow in the PhET logo |
| `POSITION` | `Color.BLUE` | Scenery's built-in blue |
| `REAL_PART` | `Color(255, 153, 0)` | |
| `RED_COLORBLIND` | `Color(255, 85, 0)` | Reads well in colorblindness tests; used in place of plain `'red'` throughout PhET sims |
| `GREEN_COLORBLIND` | `Color(0, 135, 0)` | Pairs correctly with `RED_COLORBLIND` in colorblindness tests |
| `RESET_ALL_BUTTON_BASE_COLOR` | `Color(247, 151, 34)` | The standard PhET orange — [`ResetAllButton`](/api/scenery-phet/reset-all-button)'s default `baseColor` |
| `TOTAL_ENERGY` | `Color(180, 180, 0)` | |
| `TOTAL_FORCE` | `Color(0, 200, 0)` | Same value as `NET_WORK` |
| `VELOCITY` | `Color(50, 255, 50)` | |
| `WALL_FORCE` | `Color(153, 51, 0)` | |
| `SCREEN_ICON_FRAME` | `'#dddddd'` | The one plain CSS-string constant in the table (not a `Color` instance) |

::: tip Prefer `RED_COLORBLIND`/`GREEN_COLORBLIND` over plain `'red'`/`'green'`
These two are called out by name in the source comments as deliberately colorblind-safe substitutes — reach for them instead of literal `'red'`/`'green'` whenever a sim needs a red/green pair that must stay distinguishable under common color-vision deficiencies.
:::

## SceneryPhetColors

Unlike `PhetColorScheme`, every value here is a `ProfileColorProperty` (from `scenerystack/scenery`) rather than a bare `Color` — meaning these support PhET's color-profile system (e.g. a "projector mode" palette swap) and should be linked to, not read once, if you want a component to update live when the active profile changes. All are used for the beaker drawings shared by state-of-matter/fractions-style sims.

| Property | Default |
| --- | --- |
| `emptyBeakerFillProperty` | `Color(249, 253, 255, 0.2)` |
| `solutionFillProperty` | `Color(165, 217, 242)` |
| `beakerShineFillProperty` | `Color(255, 255, 255, 0.4)` |
| `solutionShadowFillProperty` | `Color(142, 198, 221)` |
| `solutionShineFillProperty` | `Color(180, 229, 249)` |
| `beakerStroke` | `'black'` |
| `tickStroke` | `'black'` |

## SceneryPhetConstants

The smallest of the three — just two numbers, used to keep round buttons visually consistent in size across components that don't otherwise share a base class.

| Constant | Value | Used for |
| --- | --- | --- |
| `DEFAULT_BUTTON_RADIUS` | `20.8` | Default radius for most round buttons (e.g. [`ResetAllButton`](/api/scenery-phet/reset-all-button)) |
| `PLAY_CONTROL_BUTTON_RADIUS` | `28` | Default radius for `PlayControlButton` and its subtypes (play/pause, step) |

::: warning `PhetColorScheme` values are plain `Color`s; `SceneryPhetColors` values are `ProfileColorProperty`s
Passing `PhetColorScheme.APPLIED_FORCE` directly as a `fill` works exactly like passing any other `Color`. Passing `SceneryPhetColors.solutionFillProperty` the same way is also valid (scenery accepts a `TReadOnlyProperty<Color>` as a paint), but reading `.value` off of it up front (as in the minimal example) discards the live color-profile updates you'd otherwise get for free — prefer passing the Property itself as the `fill`/`stroke` option when you want profile changes to repaint automatically.
:::


========================================================================
Page: PhetFont
URL: https://veillette.github.io/Almanach/api/scenery-phet/phet-font
Source: docs/api/scenery-phet/phet-font.md
Category: API | Tags: scenery-phet, PhetFont, typography | Status: verified
========================================================================

# PhetFont

`PhetFont` (from `scenerystack/scenery-phet`) is a thin subclass of scenery's `Font` that applies PhET's standard font family and guarantees a `sans-serif` fallback. Simulations should use `PhetFont` everywhere instead of constructing a plain `Font`, so that every piece of text in the sim renders consistently and degrades gracefully if the preferred family isn't installed.

```ts
import { PhetFont } from 'scenerystack/scenery-phet';
```

## A minimal example

```ts
// Convenience form: just a size
const labelFont = new PhetFont( 16 );

// Full FontOptions form, same options as scenery's Font
const titleFont = new PhetFont( { size: 24, weight: 'bold' } );

text.font = labelFont;
```

## Constructor

```ts
new PhetFont( providedOptions?: number | string | FontOptions )
```

A bare `number` or `string` is treated as a convenience shorthand for `{ size: providedOptions }`; otherwise the argument is a normal scenery `FontOptions` object (`size`, `weight`, `style`, `family`, …).

## What it changes versus `Font`

| Behavior | Effect |
| --- | --- |
| `family` default | If you don't supply one, PhET's configured font family (from `sceneryPhetQueryParameters.fontFamily`) is used |
| Fallback guarantee | Whatever `family` ends up being (default or your own), `PhetFont` always appends `, sans-serif` so text never falls back to the browser's serif default |

::: tip Always construct through PhetFont, never bare Font
Sim-specific text should virtually never use scenery's `Font` directly — `PhetFont` is what guarantees the PhET look-and-feel and a safe fallback family across every simulation built on SceneryStack. Reach for a bare `Font` only when intentionally opting out of that convention.
:::


========================================================================
Page: PhetUnit
URL: https://veillette.github.io/Almanach/api/scenery-phet/phet-unit
Source: docs/api/scenery-phet/phet-unit.md
Category: API | Tags: scenery-phet, PhetUnit, units, i18n, formatting | Status: complete
========================================================================

# PhetUnit

`PhetUnit` (from `scenerystack/scenery-phet`) is a small class representing a *unit of measurement* — "m", "N", "°C" — as a first-class value that can be attached to a numeric `Property` via its `units` option, rather than baked into a hardcoded format string wherever that Property's value gets displayed. It implements the `Unit` interface defined in `scenerystack/axon`, and exists so that a value's units, and the translated strings for formatting "value + units" both visually and for accessibility, travel with the Property itself instead of being re-specified at every display site.

`scenery-phet` ships several dozen ready-made instances built on `PhetUnit` — `metersUnit`, `newtonsUnit`, `centimetersUnit`, `kelvinUnit`, and so on, under `scenery-phet/js/units/` — but they are not re-exported from the library's public barrel, so application code that wants one either constructs its own `PhetUnit` (as below) or imports a specific unit file directly.

```ts
import { PhetUnit } from 'scenerystack/scenery-phet';
import { NumberProperty, StringProperty } from 'scenerystack/axon';
```

## A minimal example

```ts
const wattsUnit = new PhetUnit( 'W', {
  visualStandaloneStringProperty: new StringProperty( 'watts' ),
  visualPatternStringProperty: new StringProperty( '{{value}} W' )
} );

wattsUnit.getVisualStandaloneString(); // 'watts'
wattsUnit.getVisualString( 42 );       // '42 W'

// Attach it to a Property so downstream display components can find it:
const powerProperty = new NumberProperty( 0, {
  units: wattsUnit
} );
```

## Constructor

```ts
new PhetUnit<InputPropertyType extends TReadOnlyProperty<string>>(
  name: string,                                   // backwards-compatible short name, e.g. 'm' or 'm/s^2'
  options?: {
    visualStandaloneStringProperty?: InputPropertyType; // e.g. 'meters', for units-with-no-value display
    visualPatternStringProperty?: InputPropertyType;    // e.g. '{{value}} m', filled in via a value
    accessiblePattern?: AccessibleValuePattern;          // a Fluent pattern for PDOM/voicing strings
  }
)
```

All three options are optional and independent — a `PhetUnit` can support none, some, or all of standalone/visual/accessible strings. `hasVisualStandaloneString`, `hasVisualString`, and `hasAccessibleString` (all public readonly booleans) reflect which were supplied.

## Methods

| Method | Effect |
| --- | --- |
| `getVisualStandaloneString()` | Current value of `visualStandaloneStringProperty`; throws if not configured |
| `getVisualString( value, options? )` | Fills `value` into `visualPatternStringProperty`'s pattern via `StringUtils.fillIn`; throws if not configured |
| `getAccessibleString( value, options? )` | Formats `value` through `accessiblePattern`; throws if not configured |
| `getDualString( value, options? )` | `{ visualString, accessibleString }` — convenience wrapper calling both of the above |
| `getVisualStringProperty( valueProperty, options? )` | A reactive `ReadOnlyProperty<string>` version of `getVisualString`, derived from `valueProperty` |
| `getAccessibleStringProperty( valueProperty, options? )` | Reactive version of `getAccessibleString` |
| `getDualStringProperty( valueProperty, options? )` | Reactive version of `getDualString` |
| `getDependentProperties()` | The string Properties this unit's formatting depends on — used internally to build correct derivations |

`getFallbackAccessibleUnitsStringProperty( valueProperty, options? )` is also exported alongside `PhetUnit` (not a method on the class): given any numeric Property, it returns that Property's unit's accessible string Property if `units` is a `PhetUnit`, or a plain formatted-number string Property otherwise — a convenient one-liner for accessibility code that doesn't want to branch on whether a `units` value happens to be rich.

## Where this connects to NumberProperty and NumberDisplay

Any `Property` (including [`NumberProperty`](/api/axon/number-property)) accepts a `units` option typed `Unit | string | null`. When a `PhetUnit` instance is passed there, [`NumberDisplay`](/api/scenery-phet/number-display) automatically picks it up: if `numberProperty.units` is a `PhetUnit` (not a plain string) **and** both `hasVisualString` and `hasAccessibleString` are `true`, `NumberDisplay` uses `unit.getDualString(...)` as its default number formatter instead of the plain numeric formatter — meaning a well-configured `PhetUnit` gives you correctly-formatted, translated, accessible value-plus-units text with no `valuePattern` option needed. [`NumberControl`](/api/scenery-phet/number-control) inherits this automatically, since it composes a `NumberDisplay` internally via its `numberDisplayOptions`.

::: warning The automatic NumberDisplay formatter requires *both* visual and accessible support
`NumberDisplay` only switches to a unit's own formatter when `unit.hasVisualString && unit.hasAccessibleString` are both `true`. A `PhetUnit` built with only `visualPatternStringProperty` (as in the minimal example above, which omits `accessiblePattern`) will **not** be picked up automatically — `NumberDisplay` falls back to its default numeric formatter, and `valuePattern`/`decimalPlaces` still need to be set explicitly. Call `unit.getVisualString(...)` directly if you only need visual formatting without wiring up a full `AccessibleValuePattern`.
:::

::: tip Distinct from UnitConversionProperty
[`UnitConversionProperty`](/api/axon/unit-conversion-property) converts a *numeric value* between units (e.g. meters to centimeters, via a multiplicative factor) — it changes what number you're holding. `PhetUnit` doesn't convert anything; it labels a Property's existing numeric value with a unit for display purposes. The two compose naturally: convert with `UnitConversionProperty`, then tag the result's `units` option with the matching `PhetUnit`.
:::


========================================================================
Page: Play Control Buttons
URL: https://veillette.github.io/Almanach/api/scenery-phet/play-control-buttons
Source: docs/api/scenery-phet/play-control-buttons.md
Category: API | Tags: scenery-phet, PlayControlButton, PlayStopButton, RecordStopButton, PlayPauseStepButtonGroup, PlayPauseButton, button | Status: complete
========================================================================

# Play Control Buttons

`PlayControlButton` is the round `BooleanRoundToggleButton` base class behind [`PlayPauseButton`](/api/scenery-phet/play-pause-button): it always shows a triangular "play" icon for `false`, and takes an arbitrary `Node` icon for whatever `true` ("currently playing/running") should look like. `PlayStopButton` is the other built-in specialization, using a square "stop" icon instead of pause bars. `RecordStopButton` looks like a sibling but is actually independent — and `PlayPauseStepButtonGroup` is the `HBox` layout that combines a play/pause button with step buttons, used internally by [`TimeControlNode`](/api/scenery-phet/time-control-node).

```ts
import { PlayStopButton, RecordStopButton, PlayPauseStepButtonGroup } from 'scenerystack/scenery-phet';
import { Property } from 'scenerystack/axon';
```

## A minimal example

```ts
const isRunningProperty = new Property<boolean>( false );
const isRecordingProperty = new Property<boolean>( false );

// A play/stop toggle where stopping restarts from the beginning (unlike PlayPauseButton).
const playStopButton = new PlayStopButton( isRunningProperty, {
  tandem: tandem.createTandem( 'playStopButton' )
} );

// A record/stop toggle for a data-recording feature.
const recordStopButton = new RecordStopButton( isRecordingProperty, {
  tandem: tandem.createTandem( 'recordStopButton' )
} );

// The play/pause + step-forward group TimeControlNode builds internally.
const buttonGroup = new PlayPauseStepButtonGroup( isRunningProperty, {
  includeStepBackwardButton: true,
  tandem: tandem.createTandem( 'buttonGroup' )
} );
```

## `PlayControlButton` (base class)

```ts
new PlayControlButton(
  isPlayingProperty: Property<boolean>,
  endPlayingIcon: Node,
  providedOptions?: PlayControlButtonOptions
)
```

| Option | Default | Effect |
| --- | --- | --- |
| `radius` | `SceneryPhetConstants.PLAY_CONTROL_BUTTON_RADIUS` (`28`) | Button radius; both the play triangle and `endPlayingIcon` are sized relative to it |
| `scaleFactorWhenNotPlaying` | `1` | Scales the whole button up (or down) while showing the "play" icon, per PhET's convention of enlarging play buttons that don't immediately resume stepping |
| `includeGlobalHotkey` | `false` | If `true` (and interactive description is supported), wires a global `alt+K` hotkey — via the static `PlayControlButton.TOGGLE_PLAY_HOTKEY_DATA` — that toggles `isPlayingProperty` regardless of document focus |
| `startPlayingAccessibleName` / `endPlayingAccessibleName` | localized "Play" / `null` | PDOM accessible names for each state; subclasses fill in `endPlayingAccessibleName` |
| `valueOnSoundPlayer` / `valueOffSoundPlayer` | shared `'play'` / `'pause'` sound players | Sounds played only by the global hotkey path, not by pointer presses (those use the button's own `soundPlayer`) |

`PlayPauseButton` (documented separately) fixes `endPlayingIcon` to a two-bar pause glyph and turns `includeGlobalHotkey` on by default.

## `PlayStopButton`

```ts
new PlayStopButton( isPlayingProperty: Property<boolean>, providedOptions?: PlayStopButtonOptions )
```

A `PlayControlButton` subclass with `endPlayingIcon` fixed to a square "stop" glyph (`StopIconShape`). The source comment is explicit about the semantic difference from `PlayPauseButton`: "Unlike the `PlayPauseButton`, this indicates that play will re-start from the beginning after switching from play to stop" — use it wherever pressing stop resets progress rather than merely pausing it.

## `RecordStopButton`

```ts
new RecordStopButton( recordingProperty: Property<boolean>, providedOptions?: RecordStopButtonOptions )
```

| Option | Default | Effect |
| --- | --- | --- |
| `radius` | `30` | Button radius |
| `recordIconColor` / `stopIconColor` | `PhetColorScheme.RED_COLORBLIND` for both | Colors of the record-dot and stop-square icons |

::: warning `RecordStopButton` does not extend `PlayControlButton`
Despite the naming pattern, `RecordStopButton` is its own direct `BooleanRoundToggleButton` subclass (a red circle for "record," a red square for "stop") — it doesn't share `PlayControlButton`'s `radius` default, hotkey support, or `scaleFactorWhenNotPlaying` option. Don't assume `PlayControlButtonOptions` apply to it.
:::

## `PlayPauseStepButtonGroup`

```ts
new PlayPauseStepButtonGroup( isPlayingProperty: Property<boolean>, providedOptions?: PlayPauseStepButtonGroupOptions )
```

An `HBox` that lays out one [`PlayPauseButton`](/api/scenery-phet/play-pause-button) alongside optional [`StepForwardButton`](/api/scenery-phet/step-forward-button)/[`StepBackwardButton`](/api/scenery-phet/step-backward-button) instances. This is what `TimeControlNode` builds internally rather than composing those buttons by hand.

| Option | Default | Effect |
| --- | --- | --- |
| `includeStepForwardButton` | `true` | Whether a step-forward button is included |
| `includeStepBackwardButton` | `false` | Whether a step-backward button is included |
| `playPauseStepXSpacing` | `10` | Horizontal spacing between the play/pause button and the step buttons |
| `playPauseButtonOptions` / `stepForwardButtonOptions` / `stepBackwardButtonOptions` | radius `SceneryPhetConstants.DEFAULT_BUTTON_RADIUS` / `15` / `15` | Forwarded to the respective internal button |

If you don't supply an `enabledProperty` for the step buttons yourself, the group derives one automatically as `DerivedProperty.not( isPlayingProperty )`, so step buttons are enabled only while paused — you don't have to wire that up by hand the way you would using `StepForwardButton`/`StepBackwardButton` standalone.

## Members

| Member | Description |
| --- | --- |
| `playPauseButton` | Public reference to the internal `PlayPauseButton`, for positioning |
| `getPlayPauseButtonCenter()` | Returns the `PlayPauseButton`'s center in the group's local coordinate frame |

::: tip Reach for `TimeControlNode` first
Unless you're building a custom layout, [`TimeControlNode`](/api/scenery-phet/time-control-node) already composes `PlayPauseStepButtonGroup` with an optional `TimeSpeedRadioButtonGroup` — most sims never need to construct `PlayPauseStepButtonGroup` directly.
:::


========================================================================
Page: PlayPauseButton
URL: https://veillette.github.io/Almanach/api/scenery-phet/play-pause-button
Source: docs/api/scenery-phet/play-pause-button.md
Category: API | Tags: scenery-phet, PlayPauseButton, button | Status: verified
========================================================================

# PlayPauseButton

`PlayPauseButton` (from `scenerystack/scenery-phet`) is a round toggle button bound to a `Property<boolean>`: it shows a triangular "play" icon when stopped and a two-bar "pause" icon when running, swapping between them as the Property changes (from any source, not just the button itself). It's generated programmatically from vector shapes rather than raster images, and is normally used inside [`TimeControlNode`](/api/scenery-phet/time-control-node) rather than constructed on its own — `TimeControlNode` composes exactly one `PlayPauseButton` alongside optional step buttons and speed radio buttons.

```ts
import { PlayPauseButton } from 'scenerystack/scenery-phet';
import { Property } from 'scenerystack/axon';
```

## A minimal example

```ts
const isPlayingProperty = new Property<boolean>( true );

const playPauseButton = new PlayPauseButton( isPlayingProperty, {
  tandem: tandem.createTandem( 'playPauseButton' )
} );
```

## Constructor

```ts
new PlayPauseButton(
  isPlayingProperty: Property<boolean>,
  providedOptions?: PlayPauseButtonOptions
)
```

`PlayPauseButton` extends the more general `PlayControlButton` (which takes an arbitrary "end playing" icon `Node`; `PlayPauseButton` fixes that icon to the standard two-bar pause shape).

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `radius` | `SceneryPhetConstants.PLAY_CONTROL_BUTTON_RADIUS` (`28`) | Button radius — distinct from the smaller `SceneryPhetConstants.DEFAULT_BUTTON_RADIUS` used by most other round buttons |
| `scaleFactorWhenNotPlaying` | `1` | Scales the button up (or down) while showing the "play" icon — PhET convention is to enlarge the play button when pressing it does *not* immediately resume stepping the model |
| `includeGlobalHotkey` | `true` for `PlayPauseButton` specifically | Wires the `alt+K` global hotkey (via `PlayControlButton.TOGGLE_PLAY_HOTKEY_DATA`) to toggle `isPlayingProperty`, when interactive description is supported |
| `startPlayingAccessibleName` / `endPlayingAccessibleName` | localized "Play" / "Pause" strings | PDOM accessible names for each state |
| `valueOnSoundPlayer` / `valueOffSoundPlayer` | shared `'play'` / `'pause'` sound players | Sounds played on each toggle direction |

## Public API

Being a `BooleanRoundToggleButton` under the hood, `PlayPauseButton` shares the [same toggle-button surface](/api/sun/toggle-button) — no additional public members beyond the options above.

::: tip Don't drive time from the button itself
`PlayPauseButton` only flips a boolean — it never calls `step()` for you. Read `isPlayingProperty` from your model's own step/animation-frame logic (as shown in [`TimeControlNode`](/api/scenery-phet/time-control-node)) rather than trying to hook additional behavior into the button's listener.
:::


========================================================================
Page: ProbeNode
URL: https://veillette.github.io/Almanach/api/scenery-phet/probe-node
Source: docs/api/scenery-phet/probe-node.md
Category: API | Tags: scenery-phet, ProbeNode, sensor, probe | Status: verified
========================================================================

# ProbeNode

`ProbeNode` (from `scenerystack/scenery-phet`) draws a stylized, beveled sensor probe: a circular sensing head with a handle at the bottom, shaded with gradients to look physical. It was generalized out of Bending Light and Beer's Law Lab, where it's dragged around a scene and connected by a `WireNode` to a body that displays the reading. `ProbeNode` itself has no Property or reading logic — it's pure graphics, plus a slot (`sensorTypeFunction`) for what's drawn inside the circular sensor area.

```ts
import { ProbeNode } from 'scenerystack/scenery-phet';
```

## A minimal example

```ts
const probeNode = new ProbeNode( {
  radius: 50,
  innerRadius: 35,
  sensorTypeFunction: ProbeNode.crosshairs( { intersectionRadius: 6 } ),
  cursor: 'pointer'
} );
```

The origin of a `ProbeNode` is the center of its circular sensor area, not its top-left bounding-box corner — useful to remember when positioning it against a model coordinate.

## Constructor

```ts
new ProbeNode( providedOptions?: ProbeNodeOptions )
```

There are no required positional arguments — everything, including size, is an option.

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `radius` | `50` | Outer radius of the circular sensor head |
| `innerRadius` | `35` | Radius of the cut-out sensor area inside the head (clamped to `<= radius`) |
| `handleWidth` | `50` | Width of the handle at the bottom |
| `handleHeight` | `30` | Height of the handle |
| `handleCornerRadius` | `10` | Corner radius of the handle |
| `lightAngle` | `1.35 * Math.PI` | Angle (radians) the simulated light comes from, used to place the gradient highlight; `0` is from the right, `PI/2` from the bottom — since scenery's y-axis points down, increasing angle rotates clockwise on screen (right → bottom → left → top) |
| `color` | `'#008541'` (dark green) | Base color of the probe body; all gradient shades are derived from it |
| `sensorTypeFunction` | `ProbeNode.glass()` | A `(radius) => Node` factory that produces what's drawn inside the sensor cut-out; pass `null` to leave it empty |

## Static factories for `sensorTypeFunction`

| Static member | Produces |
| --- | --- |
| `ProbeNode.glass( { centerColor, middleColor, edgeColor } )` | A radial-gradient "glass lens" look (the default) |
| `ProbeNode.crosshairs( { stroke, lineWidth, intersectionRadius } )` | A crosshairs pattern, with a gap at the center |
| `ProbeNode.DEFAULT_PROBE_NODE_OPTIONS` | The full set of default option values, useful for `combineOptions` when writing a custom `sensorTypeFunction` |

::: tip `lightAngle` is not auto-derived from the Node's rotation
Because `ProbeNode` can't reliably know its own global rotation within a scene graph, `lightAngle` must be set explicitly by whoever places it — it does not update automatically if you rotate the probe. PhET's convention is a light source from the upper-left, so rotate `lightAngle` to match however you've oriented this particular probe.
:::


========================================================================
Page: ProtractorNode
URL: https://veillette.github.io/Almanach/api/scenery-phet/protractor-node
Source: docs/api/scenery-phet/protractor-node.md
Category: API | Tags: scenery-phet, ProtractorNode, protractor, angle, measurement | Status: complete
========================================================================

# ProtractorNode

`ProtractorNode` (from `scenerystack/scenery-phet`) displays a protractor image with a public `angleProperty` tracking its current rotation, in radians. By default it's a static image; pass `rotatable: true` and it adds a hit-tested outer ring that the user can drag with a [`DragListener`](/patterns/drag-listeners) to spin the protractor around its center, keeping `angleProperty` in sync in both directions.

```ts
import { ProtractorNode } from 'scenerystack/scenery-phet';
import { Vector2 } from 'scenerystack/dot';
```

## A minimal example

```ts
const protractorNode = new ProtractorNode( {
  rotatable: true,
  angle: 0,
  center: new Vector2( 200, 200 )
} );

protractorNode.angleProperty.link( angle => {
  console.log( 'protractor angle (radians):', angle );
} );
```

## Constructor

```ts
new ProtractorNode( providedOptions?: ProtractorNodeOptions )
```

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `angle` | `0` | Initial value (in radians) used to seed `angleProperty` |
| `rotatable` | `false` | If `true`, adds an outer-ring hit target the user can drag to rotate the protractor; if `false`, the protractor is a static, non-interactive image |

## Public API

| Member | Description |
| --- | --- |
| `angleProperty` | `Property<number>` — the protractor's current rotation, in radians. Read it to know the current angle; when `rotatable` is `true`, dragging the outer ring also writes to it |
| `reset()` | Resets `angleProperty` to its initial value |
| `ProtractorNode.createIcon( options )` (static) | Returns a plain `Image` of the protractor artwork, for use in toolboxes or checkboxes, independent of any live instance |

::: tip The image uses pixel hit-testing
The protractor `Image` is created with `hitTestPixels: true`, so pointer events only register over the image's non-transparent pixels — dragging near the protractor's transparent corners won't pick it up, only its printed outline will.
:::


========================================================================
Page: QuestionBar
URL: https://veillette.github.io/Almanach/api/scenery-phet/question-bar
Source: docs/api/scenery-phet/question-bar.md
Category: API | Tags: scenery-phet, QuestionBar | Status: complete
========================================================================

# QuestionBar

`QuestionBar` (from `scenerystack/scenery-phet`) is a [`StatusBar`](/api/scenery-phet/status-bar) subclass that shows a single bold `Text` — a framing question or instruction — left-aligned and vertically centered in the bar. Its own source comment describes the intent: "In every screen, the question bar at the top provides a framing question and context." It's simpler than `vegas`'s [`FiniteStatusBar`/`InfiniteStatusBar`](/api/vegas/status-bars): no score display, no level text, no buttons — just one piece of text.

```ts
import { QuestionBar } from 'scenerystack/scenery-phet';
```

## A minimal example

```ts
const questionBar = new QuestionBar( this.layoutBounds, this.visibleBoundsProperty, {
  questionString: 'How does temperature affect pressure?',
  tandem: tandem.createTandem( 'questionBar' )
} );
this.addChild( questionBar );
```

## Constructor

```ts
new QuestionBar(
  layoutBounds: Bounds2,
  visibleBoundsProperty: TReadOnlyProperty<Bounds2>,
  providedOptions: QuestionBarOptions
)
```

Like [`StatusBar`](/api/scenery-phet/status-bar), it takes the `ScreenView`'s `layoutBounds` and `visibleBoundsProperty` first so the bar (and its text) can stretch to the browser's actual visible width.

## Options

`QuestionBarOptions` is `SelfOptions & StatusBarOptions` with `floatToTop` omitted (fixed internally) — it accepts the [same `barFill`/`barHeight`/`xMargin`/etc. options as `StatusBar`](/api/scenery-phet/status-bar), plus:

| Option | Default | Effect |
| --- | --- | --- |
| `questionString` | — (required) | The question text, as a plain `string` or a `TReadOnlyProperty<string>` for i18n/dynamic updates |
| `textOptions` | `{ font: new PhetFont( { weight: 'bold', size: '23px' } ), maxWidth: layoutBounds.width - 60 }` | Options for the internal `Text` node |
| `floatToTop` | `true` (fixed, not overridable) | `QuestionBar` always floats to the top of the browser's visible bounds |
| `barHeight` | `70` | Taller than `StatusBar`'s own default of `50`, to comfortably fit a large bold question |

## Layout

The question `Text` is kept left-aligned with a fixed `30`px margin and vertically centered using a `Multilink` on the text's own bounds and the inherited `positioningBoundsProperty` — so it re-centers automatically both when the string changes length and when the browser window resizes.

::: tip Use `QuestionBar` for framing text, `FiniteStatusBar`/`InfiniteStatusBar` for scored games
If your screen needs a score display, level indicator, or timer alongside a message, reach for `vegas`'s [`FiniteStatusBar`/`InfiniteStatusBar`](/api/vegas/status-bars) instead — `QuestionBar` intentionally has no score-related options at all.
:::


========================================================================
Page: ResetAllButton
URL: https://veillette.github.io/Almanach/api/scenery-phet/reset-all-button
Source: docs/api/scenery-phet/reset-all-button.md
Category: API | Tags: scenery-phet, ResetAllButton | Status: verified
========================================================================

# ResetAllButton

`ResetAllButton` (from `scenerystack/scenery-phet`) is the standard orange circular button that appears in the bottom-right of every PhET-style [`ScreenView`](/api/joist/screen-view) and restores that screen's model and view to their initial state. It's a specialized `ResetButton` (itself a `RoundPushButton`) that additionally handles PhET-iO state restoration, interrupting in-progress input, and voicing/alert suppression while the reset is in progress.

```ts
import { ResetAllButton } from 'scenerystack/scenery-phet';
```

## A minimal example

```ts
class MyScreenView extends ScreenView {
  public constructor( model: MyModel, tandem: Tandem ) {
    super( { tandem } );

    const resetAllButton = new ResetAllButton( {
      listener: () => {
        model.reset();
        this.reset();
      },
      right: this.layoutBounds.maxX - 25,
      bottom: this.layoutBounds.maxY - 25,
      tandem: tandem.createTandem( 'resetAllButton' )
    } );
    this.addChild( resetAllButton );
  }
}
```

<SceneryDemo demo="reset-all-button" />

## Options

`ResetAllButtonOptions` is `SelfOptions & ResetButtonOptions` (minus `xMargin`/`yMargin`, which `ResetAllButton` fixes itself). The `listener` option is inherited all the way from `RoundPushButton` — call your model's (and view's) `reset()` from it.

| Option | Default | Effect |
| --- | --- | --- |
| `listener` | — | Callback fired when the button is pressed; this is where you call `model.reset()` |
| `radius` | `SceneryPhetConstants.DEFAULT_BUTTON_RADIUS` | Button radius |
| `phetioRestoreScreenStateOnReset` | `true` | In a PhET-iO build, also restores the screen to its last-saved PhET-iO state |
| `interruptScreenViewInput` | `true` | Interrupts any in-progress input (drags, etc.) on ancestor `ScreenView`s before resetting |
| `baseColor` | `PhetColorScheme.RESET_ALL_BUTTON_BASE_COLOR` | The standard PhET orange |
| `touchAreaDilation` | `5.2` | Tuned touch-area expansion — avoid overriding lightly |

## Built-in behavior

- Fires an `alt+R` global keyboard hotkey (`ResetAllButton.RESET_ALL_HOTKEY_DATA`) equivalent to pressing the button.
- Mutes voicing/description alerts while the reset is firing, then announces a single "everything was reset" alert afterward instead of a flood of per-Property alerts.

::: tip Requires a real tandem
Like most PhET-iO-instrumented components, `tandem` defaults to `Tandem.REQUIRED` with `tandemNameSuffix: 'ResetAllButton'`. Supply a real child tandem (e.g. `screenTandem.createTandem( 'resetAllButton' )`) — see [Tandem](/api/tandem/tandem) — rather than leaving the sentinel default in place.
:::


========================================================================
Page: RulerNode
URL: https://veillette.github.io/Almanach/api/scenery-phet/ruler-node
Source: docs/api/scenery-phet/ruler-node.md
Category: API | Tags: scenery-phet, RulerNode, ruler, measurement, ticks | Status: verified
========================================================================

# RulerNode

`RulerNode` (from `scenerystack/scenery-phet`) draws the visual body of a ruler: a tinted background rectangle, evenly spaced major/minor tick lines, tick labels, and a units label. It doesn't do any measuring itself or attach to a model Property — you position it (often inside a `DragListener`-driven wrapper) and supply the tick labels for whatever scale you want.

```ts
import { RulerNode } from 'scenerystack/scenery-phet';
```

## A minimal example

```ts
const rulerNode = new RulerNode(
  500,                                        // rulerWidth, in view coordinates
  40,                                          // rulerHeight
  100,                                         // majorTickWidth, in the same view coordinates
  [ '0', '10', '20', '30', '40', '50' ],       // majorTickLabels, one per major tick
  'cm',                                        // units
  {
    minorTicksPerMajorTick: 4,
    insetsWidth: 15
  }
);
```

## Constructor

```ts
new RulerNode(
  rulerWidth: number,
  rulerHeight: number,
  majorTickWidth: number,
  majorTickLabels: ( string | number )[],
  units: string | TReadOnlyProperty<string>,
  providedOptions?: RulerNodeOptions
)
```

`rulerWidth` is the distance between the leftmost and rightmost tick, in view coordinates — `insetsWidth` adds extra background on either side beyond that. `majorTickWidth` is the spacing between major ticks in those same view coordinates, and it need not correspond 1:1 with the values in `majorTickLabels`; the label strings are just what gets drawn at each major tick position, in order.

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `backgroundFill` | `RulerNode.DEFAULT_FILL` (`'rgb(236, 225, 113)'`, a pale wood tone) | Fill of the ruler body |
| `backgroundStroke` | `'black'` | Stroke around the ruler body |
| `backgroundLineWidth` | `1` | Stroke width of the ruler body |
| `insetsWidth` | `14` | Extra background width beyond the first/last tick, on each side |
| `majorTickFont` / `minorTickFont` | `PhetFont(18)` | Fonts for major/minor tick labels |
| `majorTickHeight` / `minorTickHeight` | `0.4 * rulerHeight / 2` / `0.2 * rulerHeight / 2` | Lengths of the tick lines |
| `majorTickStroke` / `minorTickStroke` | `'black'` | Colors of the tick lines |
| `majorTickLineWidth` / `minorTickLineWidth` | `1` | Stroke widths of the tick lines |
| `minorTicksPerMajorTick` | `0` | Number of minor ticks drawn between each pair of major ticks |
| `unitsFont` | `PhetFont(18)` | Font for the units label |
| `unitsMajorTickIndex` | `0` | The units label is placed to the right of this major tick (by index) |
| `unitsSpacing` | `3` | Horizontal gap between a tick label and the units label |
| `tickMarksOnTop` / `tickMarksOnBottom` | `true` / `true` | Whether tick lines are drawn on each edge |
| `instrumentUnitsLabelText` | `true` | Whether the internal units `Text` gets its own PhET-iO tandem |

::: warning `majorTickLabels.length` must match the tick count exactly
`RulerNode` asserts `Math.floor( rulerWidth / majorTickWidth ) + 1 === majorTickLabels.length`. Passing too few or too many labels for the given `rulerWidth`/`majorTickWidth` combination throws in an assertion-enabled build rather than silently truncating or padding. Compute the label array's length the same way when generating it dynamically.
:::


========================================================================
Page: sceneryPhetQueryParameters and isResettingAllProperty
URL: https://veillette.github.io/Almanach/api/scenery-phet/scenery-phet-query-parameters
Source: docs/api/scenery-phet/scenery-phet-query-parameters.md
Category: API | Tags: scenery-phet, sceneryPhetQueryParameters, isResettingAllProperty, query-parameters, QueryStringMachine | Status: complete
========================================================================

# sceneryPhetQueryParameters and isResettingAllProperty

`sceneryPhetQueryParameters` and `isResettingAllProperty` (both from `scenerystack/scenery-phet`) are two small, unrelated top-level values grouped on this page because neither is big enough to justify its own: one is a `QueryStringMachine.getAll(...)` schema object (see the [Query Parameters Pattern](/patterns/query-parameters-pattern) for the general mechanism), the other is a single global boolean flag Property.

```ts
import { sceneryPhetQueryParameters, isResettingAllProperty } from 'scenerystack/scenery-phet';
```

## sceneryPhetQueryParameters

```ts
sceneryPhetQueryParameters.backgroundColor; // string, defaults to 'white'
sceneryPhetQueryParameters.fontFamily;      // string, defaults to 'Arial'
```

| Parameter | Type | Default | Effect |
| --- | --- | --- | --- |
| `backgroundColor` | `string` | `'white'` | Any CSS color format (`'green'`, `'ff8c00'`, `'rgb(255,0,255)'`) |
| `fontFamily` | `string` | `'Arial'` | Any CSS `font-family`-compatible string |

::: warning This is `scenery-phet`'s internal demo-application schema, not a general sim query-parameter API
The source file's own doc comment labels these "Query parameters for the scenery-phet demo application" — the small internal gallery app used to visually exercise every `scenery-phet` component during development. They control that demo app's own screen background and font, not anything about how `scenery-phet` components behave inside a real simulation. If you're looking for a real sim's own query-parameter conventions, see the [Query Parameters Pattern](/patterns/query-parameters-pattern) and [`QueryStringMachine.getAll`](/api/query-string-machine/query-string-machine-getall) instead — most libraries define their own `<library>QueryParameters` module the same way this one does, but this specific instance isn't meant to be read by application code.
:::

## isResettingAllProperty

A single, always-present `TProperty<boolean>` (backed by a `TinyProperty`, so it isn't disposable and isn't PhET-iO instrumented) that is `true` for the duration of any "reset all" in progress, and `false` otherwise.

```ts
isResettingAllProperty.lazyLink( isResetting => {
  if ( isResetting ) {
    // e.g. suppress a sound effect that would otherwise fire from the reset itself
  }
} );
```

[`ResetAllButton`](/api/scenery-phet/reset-all-button) is the sole writer: it sets `isResettingAllProperty.value = isFiring` as its own `pushButtonModel.isFiringProperty` changes, so the flag flips `true` right as the button starts firing and back to `false` once the reset's callbacks finish. `scenery-phet`'s sound-generation base class (`SoundGenerator`, in `scenerystack/tambo`) reads it as one of several inputs to its `fullyEnabledProperty`, muting sound generators for the duration of a reset so a cascade of Property resets doesn't trigger a burst of individual sound effects.

::: tip A shared global, not scoped per-screen
There is exactly one `isResettingAllProperty` for the whole runtime — it isn't tied to a specific `ScreenView` or model. If two `ResetAllButton`s exist (unusual, but possible in a multi-screen sim with per-screen reset buttons active simultaneously in some embedded context), they both read and write the same flag.
:::


========================================================================
Page: ScientificNotationNode
URL: https://veillette.github.io/Almanach/api/scenery-phet/scientific-notation-node
Source: docs/api/scenery-phet/scientific-notation-node.md
Category: API | Tags: scenery-phet, ScientificNotationNode, number-formatting | Status: complete
========================================================================

# ScientificNotationNode

`ScientificNotationNode` (from `scenerystack/scenery-phet`) displays a numeric `TReadOnlyProperty<number | null>` as `M x 10^E` — a mantissa, a "x 10" label, and a superscript-styled exponent — updating automatically whenever the Property changes. It handles the layout of the three text pieces (mantissa, "x 10", exponent) for you, including several special-cased display simplifications for integers and zero.

```ts
import { ScientificNotationNode } from 'scenerystack/scenery-phet';
import { NumberProperty } from 'scenerystack/axon';
```

## A minimal example

```ts
const valueProperty = new NumberProperty( 0.0002342 );

const notationNode = new ScientificNotationNode( valueProperty, {
  mantissaDecimalPlaces: 2
} );
// displays "2.34 x 10⁻⁴" (10 with a small, raised exponent)

valueProperty.value = 8000;
// showIntegersAsMantissaOnly defaults to false, so this still displays as "8 x 10³"
```

## Constructor

```ts
new ScientificNotationNode(
  valueProperty: TReadOnlyProperty<number | null>,
  providedOptions?: ScientificNotationNodeOptions
)
```

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `font` | `PhetFont( 20 )` | Font for the mantissa and "x 10" text |
| `fill` | `'black'` | Text color |
| `exponent` | `null` | Force a specific exponent (mantissa is scaled to match); `null` computes the exponent so the mantissa has exactly one digit before the decimal point |
| `mantissaDecimalPlaces` | `1` | Decimal places shown in the mantissa |
| `exponentScale` | `0.75` | Scale of the exponent text relative to the mantissa/"x 10" text |
| `showIntegersAsMantissaOnly` | `false` | If `true`, integers display as a plain number (`'8000'`) instead of `'8 x 10^3'` |
| `showZeroAsInteger` | `true` | If `true`, a zero mantissa displays as `'0'` instead of `'0 x 10^E'` |
| `showZeroExponent` | `false` | If `false`, an exponent of `0` displays as just the mantissa (`'M'`) instead of `'M x 10^0'` |
| `nullValueString` | `MathSymbols.NO_VALUE` | Displayed string when `valueProperty`'s value is `null` |

## Static method

| Method | Effect |
| --- | --- |
| `ScientificNotationNode.toScientificNotation( value, options? )` | Pure function (no Node needed) converting a finite `number` to `{ mantissa: string; exponent: string }`, using the same `mantissaDecimalPlaces`/`exponent` options |

::: tip Non-finite values bypass scientific notation entirely
If `valueProperty`'s value is `null`, `NaN`, or `±Infinity`, `ScientificNotationNode` shows `nullValueString`, `'NaN'`, or `'Infinity'`/`'-Infinity'` respectively — it never calls `toScientificNotation` on a non-finite number (which would throw, since `toScientificNotation` asserts its input `isFinite`). If you need custom formatting for those edge cases, handle them in a sibling Node rather than expecting an option here.
:::


========================================================================
Page: Screen Summary Layout Nodes
URL: https://veillette.github.io/Almanach/api/scenery-phet/screen-summary-layout-nodes
Source: docs/api/scenery-phet/screen-summary-layout-nodes.md
Category: API | Tags: scenery-phet, PlayAreaNode, ControlAreaNode, ScreenSummaryNode, pdom, accessibility | Status: complete
========================================================================

# Screen Summary Layout Nodes

A screen reader user exploring a PhET sim's [PDOM](/accessibility/pdom) benefits from a consistent, predictable structure — rather than every sim inventing its own heading layout, `ScreenView` divides accessible content into three standard sections, each backed by one of these `Node` types from `scenerystack/scenery-phet`: `ScreenSummaryNode` (an overview of the screen, read first), `PlayAreaNode` (the primary, pedagogically important interactive content), and `ControlAreaNode` (secondary controls). Every `ScreenView` already constructs one instance of each internally — you don't construct these types yourself — but you do route your own content into two of them.

```ts
// Inside a ScreenView subclass constructor:

// Order the accessible content within the play area section.
this.pdomPlayAreaNode.pdomOrder = [ ballNode, trackNode ];

// And within the control area section.
this.pdomControlAreaNode.pdomOrder = [ resetAllButton ];
```

## The shared shape: PDOMSectionNode

`PlayAreaNode` and `ControlAreaNode` are both thin subclasses of a shared (internal) `PDOMSectionNode` base: each renders as an HTML `<section>` containing a `<div>`, with an `accessibleHeading` set from a translated label ("Play Area" / "Control Area") baked in by the constructor — you supply content, not the heading.

| Type | Section heading | Intended contents |
| --- | --- | --- |
| `PlayAreaNode` | "Play Area" | The main interactive, pedagogically central elements of the screen |
| `ControlAreaNode` | "Control Area" | Secondary controls — reset buttons, settings, anything supporting rather than central to the interaction |

`ScreenView` exposes its instances as the **protected**, read-only fields `pdomPlayAreaNode` and `pdomControlAreaNode`, accessible from a `ScreenView` subclass. Route your Nodes into one or the other with `pdomOrder`, as in the example above — `ScreenView.setPDOMOrder()` is overridden to throw, specifically to force all accessible content through these two sections rather than directly on the `ScreenView` itself, keeping the heading structure identical across every PhET sim.

## ScreenSummaryNode: the opening overview

`ScreenSummaryNode` is a plain `Node` (not a `PDOMSectionNode`) that renders as two paragraphs read at the very top of the PDOM: an opening summary sentence and a fixed "use keyboard shortcuts" hint, in that order, with room in between for your own content. `ScreenView` holds its instance privately and calls `setIntroString( simName, screenDisplayName, isMultiScreen )` on it internally — a `ScreenView` subclass never touches `ScreenSummaryNode` directly.

Instead, `ScreenView` exposes a `screenSummaryContent` constructor option (and matching `screenSummaryContent` getter/setter) that takes a `ScreenSummaryContent` — a separate, higher-level `Node` (from `scenerystack/sim`, alongside `ScreenView` itself) for structuring play-area/control-area/current-details/interaction-hint description text — which is added as a child of the internal `ScreenSummaryNode`:

```ts
import { ScreenView, ScreenSummaryContent } from 'scenerystack/sim';

class MyScreenView extends ScreenView {
  public constructor( model: MyModel, providedOptions: MyScreenViewOptions ) {
    super( {
      screenSummaryContent: new ScreenSummaryContent( {
        playAreaContent: 'A ball moves across a frictionless track.',
        controlAreaContent: 'Reset the sim, or change the track shape.'
      } ),
      ...providedOptions
    } );
  }
}
```

`ScreenSummaryNode` itself stays an implementation detail of `ScreenView` — treat it as the low-level container `ScreenSummaryContent` is composed into, not a type you construct or mutate from sim code.

::: tip These sections already exist on your ScreenView — route content into them, don't build new ones
Constructing extra `PlayAreaNode`/`ControlAreaNode`/`ScreenSummaryNode` instances yourself would create disconnected sections nothing points to. Use `this.pdomPlayAreaNode.pdomOrder`/`this.pdomControlAreaNode.pdomOrder` for interactive content, and the `screenSummaryContent` option/setter (with a `ScreenSummaryContent` from `scenerystack/sim`) for the opening description.
:::


========================================================================
Page: ShadedRectangle and ShadedSphereNode
URL: https://veillette.github.io/Almanach/api/scenery-phet/shaded-rectangle-and-sphere
Source: docs/api/scenery-phet/shaded-rectangle-and-sphere.md
Category: API | Tags: scenery-phet, ShadedRectangle, ShadedSphereNode, shading, gradient, pseudo-3d | Status: complete
========================================================================

# ShadedRectangle and ShadedSphereNode

`ShadedRectangle` and `ShadedSphereNode` (both from `scenerystack/scenery-phet`) are small, self-contained pseudo-3D shading primitives: rather than importing beveled-button or glossy-marble artwork, you give each a size/diameter and a base color, and it builds the highlight/shadow gradients procedurally. They're unrelated as classes (different base types, different constructors) but share the same purpose — cheap faux-3D chrome — so they're documented together.

```ts
import { ShadedRectangle, ShadedSphereNode } from 'scenerystack/scenery-phet';
import { Bounds2 } from 'scenerystack/dot';
```

## ShadedRectangle

Draws a rounded rectangle with a beveled, embossed look: light and dark gradients along each edge and rounded corner, as if lit from one direction.

```ts
const panel = new ShadedRectangle( new Bounds2( 0, 0, 120, 60 ), {
  baseColor: 'rgb(80,130,230)',
  cornerRadius: 8,
  lightSource: 'leftTop'
} );
```

### Constructor

```ts
new ShadedRectangle( rectBounds: Bounds2, providedOptions?: ShadedRectangleOptions )
```

`rectBounds` sets the rectangle's exact size and position (in the parent coordinate frame) — it isn't resized afterward by mutating `bounds`.

### Options

| Option | Default | Effect |
| --- | --- | --- |
| `baseColor` | `new Color(80,130,230)` | The rectangle's nominal (unshaded) color |
| `lightSource` | `'leftTop'` | Which corner the light appears to come from: `'leftTop'`, `'rightTop'`, `'leftBottom'`, `'rightBottom'` |
| `cornerRadius` | `10` | Corner radius; also determines how far the shading gradients extend |
| `lightFactor` / `lighterFactor` | `0.5` / `0.1` | How much lighter the lit edges are, and how much lighter the lit *corner* is than the lit edges |
| `darkFactor` / `darkerFactor` | `0.5` / `0.1` | How much darker the shadowed edges are, and how much darker the shadowed *corner* is than the shadowed edges |
| `lightOffset` / `darkOffset` | `0.525` / `0.375` | Fraction of `cornerRadius` the light/dark gradients extend into the rectangle (must each be `< 1`) |

## ShadedSphereNode

Extends `Circle` and fills it with a `RadialGradient` positioned off-center, giving the impression of a glossy 3D sphere lit from one corner.

```ts
const marble = new ShadedSphereNode( 40, {
  mainColor: 'red',
  highlightColor: 'white',
  shadowColor: 'darkred'
} );
```

### Constructor

```ts
new ShadedSphereNode( diameter: number, providedOptions?: ShadedSphereNodeOptions )
```

### Options

| Option | Default | Effect |
| --- | --- | --- |
| `mainColor` | `'gray'` | The sphere's dominant color |
| `highlightColor` | `'white'` | Color of the specular highlight |
| `shadowColor` | `'black'` | Color at the sphere's outer edge |
| `highlightDiameterRatio` | `0.5` | How large the highlight is, as a fraction of the diameter (must be `< 1`) |
| `highlightXOffset` / `highlightYOffset` | `-0.4` / `-0.4` | Position of the highlight, as a fraction of the radius in `[-1, 1]` — negative values move it toward the top-left |

::: tip `ShadedSphereNode` is the base for `AtomNode` and lens/bulb graphics elsewhere in scenery-phet
Several other Nodes across scenerystack subclass `ShadedSphereNode` directly rather than reimplementing sphere shading — for example the `laser-pointer-node`'s glass lens. If you need a round, glossy indicator (a status light, a ball, an atom), check whether extending `ShadedSphereNode` covers it before building a custom gradient.
:::


========================================================================
Page: ShadowText
URL: https://veillette.github.io/Almanach/api/scenery-phet/shadow-text
Source: docs/api/scenery-phet/shadow-text.md
Category: API | Tags: scenery-phet, ShadowText, text, shadow | Status: complete
========================================================================

# ShadowText

`ShadowText` (from `scenerystack/scenery-phet`) draws a string as two overlapping `Text` nodes: a shadow copy offset by a few pixels and drawn first, and a foreground copy drawn on top. It's a cheap way to make a label stand out against a busy or variable-color background without a real CSS/canvas drop-shadow filter.

```ts
import { ShadowText } from 'scenerystack/scenery-phet';
import { PhetFont } from 'scenerystack/scenery-phet';
```

## A minimal example

```ts
const scoreText = new ShadowText( 'Score: 100', {
  font: new PhetFont( 32 ),
  fill: 'yellow',
  shadowFill: 'black',
  shadowXOffset: 2,
  shadowYOffset: 2
} );
```

## Constructor

```ts
new ShadowText( text: string, providedOptions?: ShadowTextOptions )
```

`text` is passed once at construction — `ShadowText` has no settable `stringProperty` of its own; to change the text later, construct a new instance or drop down to its two internal `Text` children directly (not part of the public API).

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `font` | `new PhetFont(24)` | Font shared by both the foreground and shadow text |
| `fill` / `stroke` | `'lightGray'` / `null` | Fill and stroke of the foreground text |
| `shadowFill` | `'black'` | Fill of the background (shadow) text |
| `shadowXOffset` / `shadowYOffset` | `3` / `1` | Offset of the shadow copy relative to the foreground copy |

::: tip Pick a `fill`/`shadowFill` pair with real contrast
Because both copies use the same `font`, the "shadow" effect only reads clearly when `fill` and `shadowFill` contrast strongly (e.g. a light `fill` over a `'black'` `shadowFill`, as in the default). Two similar colors just look like slightly blurry text rather than a shadow.
:::


========================================================================
Page: Small Icon Utility Buttons
URL: https://veillette.github.io/Almanach/api/scenery-phet/round-icon-buttons
Source: docs/api/scenery-phet/round-icon-buttons.md
Category: API | Tags: scenery-phet, RefreshButton, RestartButton, ReturnButton, CameraButton, ClapperboardButton, StarButton, button | Status: complete
========================================================================

# Small Icon Utility Buttons

`scenerystack/scenery-phet` ships a handful of small, single-purpose push buttons whose entire job is "one fixed icon, one momentary action." Each is a thin wrapper: pick a base push button class ([`RectangularPushButton`](/api/sun/rectangular-push-button) for most, [`RoundPushButton`](/api/sun/round-push-button) for `RestartButton`), build a `Path`/`Shape` icon in the constructor, assign it to `content`, and forward everything else. None of them add meaningful behavior beyond their parent class — no state, no toggling — so once you know one, you know the shape of all of them.

```ts
import { RefreshButton, RestartButton, ReturnButton, CameraButton, StarButton } from 'scenerystack/scenery-phet';
```

## A minimal example

```ts
const refreshButton = new RefreshButton( {
  listener: () => model.reshuffle(),
  tandem: tandem.createTandem( 'refreshButton' )
} );

const restartButton = new RestartButton( {
  listener: () => model.restart(),
  tandem: tandem.createTandem( 'restartButton' )
} );
```

## The family

| Class | Base class | Icon | Typical use |
| --- | --- | --- | --- |
| `RefreshButton` | `RectangularPushButton` | A circular "sync" arrows glyph (`iconHeight` option, default `35`) | Re-randomizing or reshuffling a scene without a full reset |
| `RestartButton` | `RoundPushButton` | Two back-to-back triangles plus a bar — a "restart from beginning" glyph | Restarting an activity or animation from its start state |
| `ReturnButton` | `RectangularPushButton` | `ReturnIcon` (a curved "undo/return" arrow), `xMargin`/`yMargin` `5` | Undoing the last action or returning to a previous state |
| `CameraButton` | `RectangularPushButton` | A solid camera glyph, `iconFill`/`iconScale` options (default `'black'` / `0.587`); **requires** a `tandem` | Taking a snapshot of the current sim state |
| `ClapperboardButton` | `Node` (not a push button subclass) | A `RectangularPushButton` labeled "Synchronize Recording" plus a flashing/sounding overlay | Emitting a synchronized audio+visual+PhET-iO marker for aligning screen recordings — a data-collection prototype tool, not a typical sim UI element |
| `StarButton` | `RectangularPushButton` | A filled `StarShape` | A star-icon affordance, sized (`xMargin` ≈ `8.13`) to match `RefreshButton`/`RestartButton` when the three appear together |

All except `ClapperboardButton` default `baseColor` to `PhetColorScheme.BUTTON_YELLOW`, PhET's standard yellow for one-shot action buttons — the same color you'll see on `RefreshButton`, `ReturnButton`, `CameraButton`, `StarButton`, `ZoomButton`, and others.

## Options

Because each class just fixes `content` on top of its base button, the option surface is the base button's own options (`listener`, `xMargin`/`yMargin`, `enabledProperty`, `touchAreaXDilation`, `tandem`, …) plus the small icon-specific knobs called out above. None of these classes expose a settable `content` option.

::: tip `ClapperboardButton` is not a plain icon button
Unlike the rest of this page, `ClapperboardButton` is a composite `Node` — it contains its own `RectangularPushButton` internally, plays a tone via `tambo`, and flashes a full-screen overlay. Its source comments explicitly flag it as "prototype code... not a typical UI component," intended for data-collection studies rather than general sim use.
:::


========================================================================
Page: Sound Drag Listeners
URL: https://veillette.github.io/Almanach/api/scenery-phet/sound-drag-listeners
Source: docs/api/scenery-phet/sound-drag-listeners.md
Category: API | Tags: scenery-phet, SoundDragListener, SoundKeyboardDragListener, SoundRichDragListener, sound, drag, tambo | Status: complete
========================================================================

# Sound Drag Listeners

`SoundDragListener`, `SoundKeyboardDragListener`, and `SoundRichDragListener` (from `scenerystack/scenery-phet`) are subclasses of scenery's [`DragListener`](/api/scenery/drag-listener), [`KeyboardDragListener`](/api/scenery/keyboard-drag-listener), and [`RichDragListener`](/api/scenery/rich-drag-listener) respectively — same constructor options, same drag behavior — that additionally play a grab sound when the drag starts and a release sound when it ends. Most PhET sims should reach for these instead of the plain scenery listeners by default: dragging is one of the most common interactions in a sim, and the shared grab/release sound pair is part of the standard PhET sound-design vocabulary (see [Sound Design](/accessibility/sound-design)).

```ts
import { SoundRichDragListener } from 'scenerystack/scenery-phet';
import { Node } from 'scenerystack/scenery';

const ballNode = new Node( { tagName: 'div', focusable: true, cursor: 'pointer' } );

// Same options as RichDragListener, plus sound.
ballNode.addInputListener( new SoundRichDragListener( {
  positionProperty: ball.positionProperty,
  transform: modelViewTransform,
  dragBoundsProperty: model.dragBoundsProperty
} ) );
```

## Shared sound options

All three add the same `RichDragListenerSoundOptions` on top of their base listener's options:

| Option | Default | Effect |
| --- | --- | --- |
| `grabSoundPlayer` | the shared `'grab'` sound (`sharedSoundPlayers.get( 'grab' )`) | Played when the drag begins; pass `null` for no sound |
| `releaseSoundPlayer` | the shared `'release'` sound | Played when the drag ends normally; **not** played if the listener was interrupted |

`SoundRichDragListener` additionally accepts `dragListenerSoundOptions` and `keyboardDragListenerSoundOptions` — nested overrides so its internal pointer and keyboard listeners can use different sounds than each other, falling back to the top-level `grabSoundPlayer`/`releaseSoundPlayer` when omitted.

```ts
import { SoundRichDragListener } from 'scenerystack/scenery-phet';
import sharedSoundPlayers from 'scenerystack/tambo';

new SoundRichDragListener( {
  positionProperty: ball.positionProperty,
  transform: modelViewTransform,

  // Applies to both the pointer and keyboard listener unless overridden below.
  grabSoundPlayer: sharedSoundPlayers.get( 'grab' ),

  // Keyboard-only override, e.g. a distinct sound for keyboard grabs.
  keyboardDragListenerSoundOptions: {
    grabSoundPlayer: myCustomKeyboardGrabSound
  }
} );
```

## Which one to use

Pick based on which input modality you need, exactly as with the plain scenery listeners:

| Type | Extends | Use when |
| --- | --- | --- |
| `SoundDragListener` | `DragListener` | Pointer-only dragging with sound |
| `SoundKeyboardDragListener` | `KeyboardDragListener` | Keyboard-only dragging with sound |
| `SoundRichDragListener` | `RichDragListener` | Both pointer and keyboard on one Node — the common case for a fully accessible draggable object |

::: tip These are drop-in replacements, not a separate API to learn
Because each type only adds sound on top of its base class, anywhere scenery's `DragListener`/`KeyboardDragListener`/`RichDragListener` is documented (positioning via `positionProperty`/`transform`, `dragBoundsProperty`, `start`/`end` callbacks, `keyboardDragListenerOptions`/`dragListenerOptions` namespacing on the Rich variant) applies unchanged here — the only new surface is the sound options above.
:::


========================================================================
Page: SpectrumNode
URL: https://veillette.github.io/Almanach/api/scenery-phet/spectrum-node
Source: docs/api/scenery-phet/spectrum-node.md
Category: API | Tags: scenery-phet, SpectrumNode, gradient, color, spectrum | Status: complete
========================================================================

# SpectrumNode

`SpectrumNode` (from `scenerystack/scenery-phet`) renders a horizontal bar showing how a numeric range maps to color, by drawing directly onto an offscreen `<canvas>` (for performance) and displaying the result as an `Image`. By default it maps `[0, 1]` onto a black-to-white grayscale gradient, but any `valueToColor` function and any `[minValue, maxValue]` range are supported — this is the building block behind visible-light-spectrum displays and spectrum-based slider tracks.

```ts
import { SpectrumNode } from 'scenerystack/scenery-phet';
import { Color } from 'scenerystack/scenery';
```

## A minimal example

```ts
// A custom red-to-blue spectrum over a [0, 100] range.
const spectrumNode = new SpectrumNode( {
  minValue: 0,
  maxValue: 100,
  valueToColor: value => {
    const t = value / 100;
    return new Color( 255 * ( 1 - t ), 0, 255 * t );
  }
} );
```

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `size` | `Dimension2( 150, 30 )` | Rendered width/height of the bar |
| `valueToColor` | `SpectrumNode.DEFAULT_VALUE_TO_COLOR` | Maps a value in `[minValue, maxValue]` to a `Color` |
| `minValue` / `maxValue` | `0` / `1` | The domain passed to `valueToColor`; must satisfy `minValue < maxValue` |

## Static member

| Member | Description |
| --- | --- |
| `SpectrumNode.DEFAULT_VALUE_TO_COLOR` | The default grayscale mapping: asserts its input is in `[0, 1]` and returns `Color( 255v, 255v, 255v )` |

## Real siblings built on `SpectrumNode`

- **`WavelengthSpectrumNode`** — a `SpectrumNode` subclass that hard-codes `valueToColor` to `VisibleColor.wavelengthToColor` and defaults `minValue`/`maxValue` to the visible wavelength range (`VisibleColor.MIN_WAVELENGTH`/`MAX_WAVELENGTH`), for displaying the visible light spectrum.
- **`SpectrumSliderTrack`** / **`SpectrumSliderThumb`** — a `SliderTrack`/`SliderThumb` pair that composes a `SpectrumNode` internally, so you can build a slider whose track is a color gradient (e.g. picking a wavelength).

::: tip The gradient is baked to a bitmap once, not reactive
`SpectrumNode` draws its canvas and converts it to a static `Image` inside the constructor — it does not re-render if you mutate the `valueToColor` function or the value range afterward. If your spectrum needs to change (a different range, a different color mapping), construct a new `SpectrumNode` rather than expecting the existing instance to update.
:::


========================================================================
Page: SpinningIndicatorNode
URL: https://veillette.github.io/Almanach/api/scenery-phet/spinning-indicator-node
Source: docs/api/scenery-phet/spinning-indicator-node.md
Category: API | Tags: scenery-phet, SpinningIndicatorNode, spinner, loading, progress | Status: complete
========================================================================

# SpinningIndicatorNode

`SpinningIndicatorNode` (from `scenerystack/scenery-phet`) shows a ring of small shapes (rectangles by default) arranged in a circle, used to indicate that an operation is in progress with no known completion percentage — a "loading spinner." The individual elements never actually move; instead, `SpinningIndicatorNode` cycles each element's *fill color* from active to inactive around the ring on every call to `step( dt )`, which reads as clockwise rotation while avoiding the cost of re-laying-out geometry every frame.

Unlike most animated scenery-phet Nodes, `SpinningIndicatorNode` does **not** hook itself into any timer — you must call `step( dt )` yourself, typically from your `ScreenView`'s own `step( dt )` method.

```ts
import { SpinningIndicatorNode } from 'scenerystack/scenery-phet';
```

## A minimal example

```ts
const spinner = new SpinningIndicatorNode( {
  diameter: 30,
  numberOfElements: 12,
  elementFactory: SpinningIndicatorNode.circleFactory
} );

// From your ScreenView's step( dt ) method:
spinner.step( dt );
```

## Constructor

```ts
new SpinningIndicatorNode( providedOptions?: SpinningIndicatorNodeOptions )
```

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `diameter` | `15` | Overall diameter of the ring |
| `numberOfElements` | `16` | Number of elements arranged around the ring |
| `elementFactory` | `SpinningIndicatorNode.rectangleFactory` | `( diameter, numberOfElements ) => Path` used to build each element; also see the built-in `SpinningIndicatorNode.circleFactory` |
| `speed` | `1` | Multiplier on rotation speed |
| `activeColor` | `'rgba(0,0,0,1)'` | Color of the "leading" element in the cycle |
| `inactiveColor` | `'rgba(0,0,0,0.15)'` | Color of the "trailing" element in the cycle |

## Methods

| Method | Effect |
| --- | --- |
| `step( dt )` | Advances the color-cycle animation by `dt` seconds; call this every frame the spinner should appear to spin |

## Static factories

| Method | Effect |
| --- | --- |
| `SpinningIndicatorNode.rectangleFactory( diameter, numberOfElements )` | Default element factory — small rectangles |
| `SpinningIndicatorNode.circleFactory( diameter, numberOfElements )` | Alternative element factory — small circles ("dots") instead of rectangles |

::: tip Nothing spins on its own — wire `step` into your simulation's step loop
Because `SpinningIndicatorNode` has no built-in timer dependency, it stays inert (frozen on its initial coloring) until something calls `step( dt )`. This is deliberate: it keeps the Node usable in contexts with no running `Sim` (static demos, tests) and lets you pause the spin along with the rest of your screen simply by not calling `step` while paused, rather than needing a separate enable/disable flag.
:::


========================================================================
Page: StarNode and StarShape
URL: https://veillette.github.io/Almanach/api/scenery-phet/star-node
Source: docs/api/scenery-phet/star-node.md
Category: API | Tags: scenery-phet, StarNode, StarShape | Status: complete
========================================================================

# StarNode and StarShape

`StarShape` (from `scenerystack/scenery-phet`) is a `kite` `Shape` subclass tracing a five-pointed star outline. `StarNode` layers two `StarShape`-based `Path`s — a bland gray "empty" star behind a bold yellow "filled" star clipped to a horizontal fraction — so that setting a single `value` between `0` and `1` visually fills the star in from left to right. It was built for game score indicators (PhET's [`ScoreDisplayStars`/`ScoreDisplayNumberAndStar`](/api/vegas/score-display-family) both render a row of `StarNode`s), but works anywhere a "how much of this is filled in" glyph is useful.

```ts
import { StarNode, StarShape } from 'scenerystack/scenery-phet';
```

## A minimal example

```ts
// A fully-filled star (the default).
const fullStar = new StarNode();

// A half-filled star, e.g. for a partial score.
const halfStar = new StarNode( { value: 0.5 } );

// An empty outline only, with no foreground star drawn at all.
const emptyStar = new StarNode( { value: 0 } );

// The bare outline shape, usable in any Path.
const starShape = new StarShape( { outerRadius: 20, innerRadius: 10 } );
```

## `StarNode` constructor

```ts
new StarNode( providedOptions?: StarNodeOptions )
```

## `StarNode` options

| Option | Default | Effect |
| --- | --- | --- |
| `value` | `1` | Fraction filled, `0` to `1`. `0` renders only the empty background star (no foreground `Path` is even created); `1` fully fills it |
| `emptyFill` / `emptyStroke` / `emptyLineWidth` / `emptyLineJoin` | `'#e1e1e1'` / `'#d3d1d1'` / `1.5` / `'round'` | Styling of the background (unfilled) star — kept deliberately bland |
| `filledFill` / `filledStroke` / `filledLineWidth` / `filledLineJoin` | `'#fcff03'` (yellow) / `'black'` / `1.5` / `'round'` | Styling of the foreground (filled) star — kept bold and eye-catching |
| `starShapeOptions` | `{}` | Forwarded to both internal `StarShape`s, e.g. `{ outerRadius, innerRadius, numberStarPoints }` |

The fill effect is implemented with a `clipArea` on the foreground star (clipped to `value` of its width), not by redrawing a partial shape — cheaper to compute and gives a clean vertical fill edge.

## `StarShape` constructor

```ts
new StarShape( providedOptions?: StarShapeOptions )
```

| Option | Default | Effect |
| --- | --- | --- |
| `outerRadius` | `15` | Distance from center to each point's tip |
| `innerRadius` | `7.5` | Distance from center to the inner vertices between points — controls how "thick" the star's limbs look |
| `numberStarPoints` | `5` | Number of points; the shape alternates `outerRadius`/`innerRadius` vertices around the full circle |

`StarShape` calls `makeImmutable()` after construction, so a single instance can safely be reused across multiple `Path`s without listener overhead.

::: tip `StarNode` isn't a button
It's a passive display `Node`, not a [`StarButton`](/api/scenery-phet/round-icon-buttons) — `StarButton` uses the same `StarShape` as its icon, but the two classes are otherwise unrelated (one shows a score, the other fires a `listener` on press).
:::


========================================================================
Page: StatusBar
URL: https://veillette.github.io/Almanach/api/scenery-phet/status-bar
Source: docs/api/scenery-phet/status-bar.md
Category: API | Tags: scenery-phet, StatusBar | Status: complete
========================================================================

# StatusBar

`StatusBar` (from `scenerystack/scenery-phet`) is the base class for a `Rectangle` bar that spans the top of a screen and resizes/repositions itself to track the browser's visible bounds. It handles only geometry — sizing the bar to the current `visibleBoundsProperty`, and exposing a `positioningBoundsProperty` that subclasses use to lay out their own content flush with the bar's (margin-adjusted) left/right edges. `StatusBar` itself adds no content; it exists purely to be subclassed.

::: tip Looking for the game status bars?
Most sims never construct `StatusBar` directly. If you're building a standard PhET game screen, use `vegas`'s [`FiniteStatusBar` or `InfiniteStatusBar`](/api/vegas/status-bars) instead — both extend this class and add the score display, level text, and buttons for you. This page documents the shared base they (and [`QuestionBar`](/api/scenery-phet/question-bar)) build on.
:::

```ts
import { StatusBar } from 'scenerystack/scenery-phet';
import { Bounds2 } from 'scenerystack/dot';
```

## A minimal example

Subclassing `StatusBar` to add your own content:

```ts
class MyStatusBar extends StatusBar {
  public constructor( layoutBounds: Bounds2, visibleBoundsProperty: TReadOnlyProperty<Bounds2> ) {
    super( layoutBounds, visibleBoundsProperty, {
      barFill: 'black',
      barHeight: 40
    } );

    const label = new Text( 'Level 1', { fill: 'white', font: StatusBar.DEFAULT_FONT } );
    this.addChild( label );

    // Keep the label vertically centered and flush left as the bar resizes.
    this.positioningBoundsProperty.link( bounds => {
      label.left = bounds.left;
      label.centerY = bounds.centerY;
    } );
  }
}
```

## Constructor

```ts
new StatusBar(
  layoutBounds: Bounds2,
  visibleBoundsProperty: TReadOnlyProperty<Bounds2>,
  providedOptions?: StatusBarOptions
)
```

`layoutBounds` is the `ScreenView`'s fixed design-space bounds; `visibleBoundsProperty` is its actual on-screen visible bounds, which can be wider than `layoutBounds` on ultra-wide browser windows. `StatusBar` needs both so it can choose, per `dynamicAlignment`, whether to stretch content to the real browser width or keep it pinned to the dev-time layout width.

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `barFill` / `barStroke` | `'lightGray'` / `null` | Paint for the bar's background `Rectangle` |
| `barHeight` | `50` | Height of the bar, in the same units as `layoutBounds` |
| `xMargin` / `yMargin` | `10` / `8` | Margin subtracted from the bar's bounds to produce `positioningBoundsProperty` |
| `floatToTop` | `false` | `true` floats the bar to the top of the browser's actual `visibleBounds` (it can move as the window resizes); `false` keeps it fixed at the top of `layoutBounds` |
| `dynamicAlignment` | `true` | `true` keeps content aligned to the left/right edges of `visibleBounds` (the real browser window); `false` aligns to `layoutBounds` instead |

## Members

| Member | Description |
| --- | --- |
| `positioningBoundsProperty` (protected) | A `TReadOnlyProperty<Bounds2>` — the margin-adjusted bounds subclasses should position their content within; updates automatically as `visibleBoundsProperty` changes |
| `StatusBar.DEFAULT_FONT` (static) | `PhetFont( 20 )` — the font subclasses should default to for bar text |
| `StatusBar.DEFAULT_TEXT_FILL` (static) | `Color.BLACK` — the text color subclasses should default to |

::: warning `positioningBoundsProperty` is `protected`
It's readable from subclasses (as shown above) but not from outside code holding a `StatusBar` reference — if you need to react to a status bar's layout externally, read `visibleBoundsProperty` yourself rather than reaching into `positioningBoundsProperty`.
:::


========================================================================
Page: StepBackwardButton
URL: https://veillette.github.io/Almanach/api/scenery-phet/step-backward-button
Source: docs/api/scenery-phet/step-backward-button.md
Category: API | Tags: scenery-phet, StepBackwardButton, button | Status: verified
========================================================================

# StepBackwardButton

`StepBackwardButton` (from `scenerystack/scenery-phet`) is a `RoundPushButton` showing the same bar-plus-triangle icon as [`StepForwardButton`](/api/scenery-phet/step-forward-button), mirrored to point the other way, for rewinding a paused model by one fixed time increment. It's a thin subclass of the shared, also-exported `StepButton` with `direction: 'backward'` fixed. Unlike [`TimeControlNode`](/api/scenery-phet/time-control-node)'s step-forward button, a step-backward button is **not** included by default — it must be opted into explicitly.

```ts
import { StepBackwardButton } from 'scenerystack/scenery-phet';
```

## A minimal example

```ts
const stepBackwardButton = new StepBackwardButton( {
  listener: () => {
    model.step( -0.1 );
  },
  enabledProperty: DerivedProperty.not( isPlayingProperty ),
  tandem: tandem.createTandem( 'stepBackwardButton' )
} );
```

## Options

`StepBackwardButtonOptions` is `StepButtonOptions` with `direction` fixed to `'backward'` — the underlying `content` icon is likewise fixed and not settable directly. It shares the same option surface as [`StepForwardButton`](/api/scenery-phet/step-forward-button) (`radius`, `iconFill`, `fireOnHold`, …), with one difference in its default sound:

| Option | Default | Effect |
| --- | --- | --- |
| `radius` | `20` | Button radius |
| `iconFill` | `'black'` | Fill color of the bar-and-triangle icon |
| `soundPlayer` | the shared `'stepBackward'` sound player | Distinct from `StepForwardButton`'s default `'stepForward'` player, so forward/backward stepping sound different |
| `enabledProperty` | — | Inherited from `RoundPushButton`; no dedicated `isPlayingProperty` option exists (see tip below) |

## Enabling a step-backward button in `TimeControlNode`

```ts
const timeControlNode = new TimeControlNode( isPlayingProperty, {
  playPauseStepButtonOptions: {
    includeStepBackwardButton: true
  }
} );
```

::: tip Not included by default, and no built-in `isPlayingProperty` option
`TimeControlNode` only shows a step-forward button out of the box; pass `playPauseStepButtonOptions.includeStepBackwardButton: true` to add this one. And like `StepForwardButton`, `StepBackwardButton` itself has no special play/pause awareness — if you construct it standalone (outside `TimeControlNode`), derive its `enabledProperty` from your own `isPlayingProperty` (e.g. `DerivedProperty.not( isPlayingProperty )`) so it disables correctly while the sim is running.
:::


========================================================================
Page: StepForwardButton
URL: https://veillette.github.io/Almanach/api/scenery-phet/step-forward-button
Source: docs/api/scenery-phet/step-forward-button.md
Category: API | Tags: scenery-phet, StepForwardButton, button | Status: verified
========================================================================

# StepForwardButton

`StepForwardButton` (from `scenerystack/scenery-phet`) is a `RoundPushButton` showing a bar-plus-triangle "step forward" icon, for advancing a paused model by one fixed time increment. It's a thin subclass of the shared, also-exported `StepButton` with `direction: 'forward'` fixed — [`TimeControlNode`](/api/scenery-phet/time-control-node) includes one by default, but it's also usable standalone wherever a sim needs frame-by-frame stepping without a full play/pause control strip.

```ts
import { StepForwardButton } from 'scenerystack/scenery-phet';
```

## A minimal example

```ts
const stepForwardButton = new StepForwardButton( {
  listener: () => {
    model.step( 0.1 );
  },
  enabledProperty: DerivedProperty.not( isPlayingProperty ),
  tandem: tandem.createTandem( 'stepForwardButton' )
} );
```

## Options

`StepForwardButtonOptions` is `StepButtonOptions` with `direction` fixed to `'forward'` — the underlying `content` icon is likewise fixed and not settable directly.

| Option | Default | Effect |
| --- | --- | --- |
| `radius` | `20` | Button radius (independent of `SceneryPhetConstants`, unlike the play/pause button's radius) |
| `iconFill` | `'black'` | Fill color of the bar-and-triangle icon |
| `fireOnHold` | `true` | Press-and-hold repeats the step, matching the default `fireOnHold`/`fireOnHoldDelay`/`fireOnHoldInterval` behavior of any `RoundPushButton` |
| `soundPlayer` | the shared `'stepForward'` sound player | Overridable if a different button in the same sim needs a distinct sound |
| `enabledProperty` | — | Inherited from `RoundPushButton`; there is no dedicated `isPlayingProperty` option, so disabling while the sim runs is the caller's responsibility (see tip below) |

::: tip There is no built-in `isPlayingProperty` option — wire `enabledProperty` yourself
`StepForwardButton` has no special awareness of play/pause state. [`TimeControlNode`](/api/scenery-phet/time-control-node) achieves "step buttons disable while playing" by deriving `enabledProperty: DerivedProperty.not( isPlayingProperty )` internally (via `PlayPauseStepButtonGroup`) and passing it in as an ordinary option. Do the same if you use `StepForwardButton` standalone, outside `TimeControlNode`.
:::


========================================================================
Page: StopSignNode
URL: https://veillette.github.io/Almanach/api/scenery-phet/stop-sign-node
Source: docs/api/scenery-phet/stop-sign-node.md
Category: API | Tags: scenery-phet, StopSignNode, icon, stop | Status: complete
========================================================================

# StopSignNode

`StopSignNode` (from `scenerystack/scenery-phet`) draws a classic octagonal stop-sign icon: a red octagon, a thin white border, and a thin black outer border, built from three concentric regular-octagon `Path`s. It's a static, non-interactive icon — for the circle-slash "not allowed" icon instead, see [`BannedNode`](/api/scenery-phet/banned-node).

```ts
import { StopSignNode } from 'scenerystack/scenery-phet';
import { Tandem } from 'scenerystack/tandem';
```

## A minimal example

```ts
const stopIcon = new StopSignNode( {
  fillRadius: 18,
  tandem: Tandem.REQUIRED.createTandem( 'stopIcon' )
} );
```

## Constructor

```ts
new StopSignNode( providedOptions?: StopSignNodeOptions )
```

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `fillRadius` | `23` | Radius of the innermost (red) octagon |
| `innerStrokeWidth` | `2` | Width of the white border, added on top of `fillRadius` |
| `outerStrokeWidth` | `1` | Width of the black border, added on top of `fillRadius + innerStrokeWidth` |
| `fill` | `'red'` | Color of the innermost octagon |
| `innerStroke` | `'white'` | Color of the middle border ring |
| `outerStroke` | `'black'` | Color of the outermost border ring |

The three borders are built as three separate, fully-filled octagon `Path`s stacked in z-order (outer, then inner-stroke, then fill) rather than as actual `stroke`s on a single `Path` — that's why they're configured as `fillRadius`/`innerStrokeWidth`/`outerStrokeWidth` instead of ordinary `Path` `stroke`/`lineWidth` options.

::: warning `tandem` is required by default
`StopSignNode`'s options default `tandem: Tandem.REQUIRED` (with `tandemNameSuffix: 'StopSignNode'`) — omitting `tandem` will assert in an instrumented sim. Pass `Tandem.OPT_OUT` explicitly if this particular icon genuinely doesn't need PhET-iO instrumentation.
:::


========================================================================
Page: StopwatchNode
URL: https://veillette.github.io/Almanach/api/scenery-phet/stopwatch-node
Source: docs/api/scenery-phet/stopwatch-node.md
Category: API | Tags: scenery-phet, StopwatchNode | Status: verified
========================================================================

# StopwatchNode

`StopwatchNode` (from `scenerystack/scenery-phet`) is the view for a `Stopwatch` model element: a digital mm:ss.cc readout with play/pause and reset buttons, optionally draggable within a set of bounds. `Stopwatch` itself is a plain `PhetioObject` model holding `positionProperty`, `isVisibleProperty`, `isRunningProperty`, and `timeProperty` — `StopwatchNode` only renders and lets the user drag/press it.

```ts
import { Stopwatch, StopwatchNode } from 'scenerystack/scenery-phet';
import { Property } from 'scenerystack/axon';
import { Bounds2 } from 'scenerystack/dot';
```

## A minimal example

```ts
const stopwatch = new Stopwatch( {
  tandem: tandem.createTandem( 'stopwatch' )
} );

const dragBoundsProperty = new Property( new Bounds2( 0, 0, 768, 504 ) );

const stopwatchNode = new StopwatchNode( stopwatch, {
  dragBoundsProperty: dragBoundsProperty,
  tandem: tandem.createTandem( 'stopwatchNode' )
} );
```

Call `stopwatch.reset()` from your model's `reset()` — resetting only the Node would leave the underlying time/running state untouched.

## Constructor

```ts
new StopwatchNode( stopwatch: Stopwatch, providedOptions?: StopwatchNodeOptions )
```

## `Stopwatch` (the model)

| Member | Description |
| --- | --- |
| `positionProperty` | `Property<Vector2>` — position in view coordinates |
| `isVisibleProperty` | `Property<boolean>` — becoming invisible stops the stopwatch and resets its time |
| `isRunningProperty` | `Property<boolean>` — whether time is currently advancing |
| `timeProperty` | `NumberProperty` — elapsed time, in units the client defines (seconds by default) |
| `step( dt )` | Advances the stopwatch by `dt`, clamped to `timeProperty.range.max`, auto-pausing at the max |
| `setTime( t )` | Sets the time directly (only takes effect while running) |
| `reset()` | Resets position, visibility, running state, and time |
| `Stopwatch.ZERO_TO_ALMOST_SIXTY` | Static `Range( 0, 3599.99 )` — the default `numberDisplayRange`, i.e. up to 59:59.99 |

## `StopwatchNode` options

| Option | Default | Effect |
| --- | --- | --- |
| `dragBoundsProperty` | `null` | If provided, the stopwatch is draggable (mouse + keyboard) and constrained within these bounds; `null` means not draggable |
| `numberDisplayRange` | `Stopwatch.ZERO_TO_ALMOST_SIXTY` | Sizes the internal `NumberDisplay` so the readout doesn't resize as digits change |
| `numberDisplayOptions` | formats mm:ss.cc | Forwarded to the internal `NumberDisplay`; set `numberFormatter` here for custom formatting |
| `includePlayPauseResetButtons` | `true` | Whether the play/pause and reset buttons are shown at all |
| `otherControls` | `[]` | Extra `Node`s stacked below the buttons (e.g. a units selector) |
| `xSpacing` / `ySpacing` | `6` / `6` | Horizontal space between buttons / vertical space between readout and buttons |
| `xMargin` / `yMargin` | `8` / `8` | Margins of the background panel around the contents |
| `playPauseButtonOptions` / `resetButtonOptions` | — | Forwarded to the respective buttons |

## Static formatting helpers

| Static member | Purpose |
| --- | --- |
| `StopwatchNode.DEFAULT_FONT` | The standard monospace-digit font used for the readout |
| `StopwatchNode.RICH_TEXT_MINUTES_AND_SECONDS` | Default `numberDisplayOptions.numberFormatter` — RichText mm:ss.cc with smaller centiseconds |
| `StopwatchNode.PLAIN_TEXT_MINUTES_AND_SECONDS` | Same format as plain text, for contexts that can't render RichText |
| `StopwatchNode.createRichTextNumberFormatter( options )` | Builds a custom formatter — pass `units`, `showAsMinutesAndSeconds`, decimal places, etc. |

::: tip A `Stopwatch` doesn't step itself
`Stopwatch.step( dt )` must be called by something — typically the screen's model `step()`, gated on `stopwatch.isRunningProperty`. `StopwatchNode` never calls it for you; it only reflects `timeProperty` and toggles `isRunningProperty` via its buttons.
:::


========================================================================
Page: TemperatureAndColorSensorNode
URL: https://veillette.github.io/Almanach/api/scenery-phet/temperature-and-color-sensor-node
Source: docs/api/scenery-phet/temperature-and-color-sensor-node.md
Category: API | Tags: scenery-phet, TemperatureAndColorSensorNode, ThermometerNode, sensor | Status: complete
========================================================================

# TemperatureAndColorSensorNode

`TemperatureAndColorSensorNode` (from `scenerystack/scenery-phet`) composes a [`ThermometerNode`](/api/scenery-phet/thermometer-node) with a small triangular color swatch positioned to its left, for probes that sense both a temperature and a color at the same point (for example, a light-absorption probe in a states-of-matter-style sim, where the sampled color communicates *what* is being measured and the thermometer communicates *how hot it is*). The triangle's leftmost point is meant to line up with the sensor's actual position in the model — the thermometer hangs off to the side of it.

```ts
import { TemperatureAndColorSensorNode } from 'scenerystack/scenery-phet';
import { Property } from 'scenerystack/axon';
import { Range } from 'scenerystack/dot';
import { Color } from 'scenerystack/scenery';
```

## A minimal example

```ts
const temperatureProperty = new Property( 293 ); // kelvin
const temperatureRange = new Range( 0, 1000 );
const colorProperty = new Property( Color.RED );

const sensorNode = new TemperatureAndColorSensorNode(
  temperatureProperty,
  temperatureRange,
  colorProperty,
  {
    thermometerNodeOptions: {
      bulbDiameter: 40,
      tubeHeight: 120
    }
  }
);

colorProperty.value = Color.BLUE; // the triangle's fill updates immediately
```

## Constructor

```ts
new TemperatureAndColorSensorNode(
  temperatureProperty: TProperty<number>,
  temperatureRange: Range,
  colorProperty: TProperty<TColor>,
  providedOptions?: TemperatureAndColorSensorNodeOptions
)
```

`temperatureRange.min`/`.max` are forwarded directly as the `minTemperature`/`maxTemperature` arguments of the internal `ThermometerNode`.

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `horizontalSpace` | `3` | Horizontal gap between the color triangle and the thermometer |
| `bottomOffset` | `5` | Vertical difference between the bottom of the color triangle and the bottom of the thermometer |
| `thermometerNodeOptions` | `{ bulbDiameter: 30, tubeWidth: 18, lineWidth: 2, tickSpacingTemperature: 25, majorTickLength: 10, minorTickLength: 5, backgroundFill: Color(256,256,256,0.67) }` | Forwarded to the internal `ThermometerNode`, minus `left`/`bottom` (which this Node computes itself for layout) |
| `colorIndicatorOptions` | `{ fill: Color(0,0,0,0), lineWidth: 2, stroke: 'black', lineJoin: 'round', sideLength: 18 }` | `PathOptions` plus `sideLength`, controlling the size and styling of the triangular color swatch |

## Members and methods

| Member | Effect |
| --- | --- |
| `thermometerBounds` (getter) / `getThermometerBounds()` | `Bounds2` of the internal `ThermometerNode` |
| `colorIndicatorBounds` (getter) / `getColorIndicatorBounds()` | `Bounds2` of the triangular color swatch |

::: tip The triangle's origin is its leftmost point, not its center
The color-indicator `Shape` is built with `moveTo(0, 0)` as the leftmost vertex and the other two vertices extending to the right at ±30°, so `(0, 0)` in the sensor's local coordinate frame is exactly where you'd position the tip of the sensor probe in the model — position the whole `Node` (via `x`/`y`/`translation`/`center` options passed through `providedOptions`) so that point lands on the model's sensor location, rather than trying to center the Node as a whole.
:::


========================================================================
Page: ThermometerNode
URL: https://veillette.github.io/Almanach/api/scenery-phet/thermometer-node
Source: docs/api/scenery-phet/thermometer-node.md
Category: API | Tags: scenery-phet, ThermometerNode | Status: verified
========================================================================

# ThermometerNode

`ThermometerNode` (from `scenerystack/scenery-phet`) draws a classic bulb-and-tube thermometer whose fluid level tracks a temperature value between a min and max. It handles the glass outline, tick marks, and the clipped fluid shape for you — you only supply the temperature Property and the range it can take.

```ts
import { ThermometerNode } from 'scenerystack/scenery-phet';
import { Property } from 'scenerystack/axon';
```

## A minimal example

```ts
const temperatureProperty = new Property<number | null>( 20 );

const thermometer = new ThermometerNode( temperatureProperty, 0, 100, {
  bulbDiameter: 50,
  tubeHeight: 150,
  tickSpacingTemperature: 10 // one tick every 10 degrees, instead of every fixed pixel spacing
} );
```

## Constructor

```ts
new ThermometerNode(
  temperatureProperty: TReadOnlyProperty<number | null>,
  minTemperature: number,
  maxTemperature: number,
  providedOptions?: ThermometerNodeOptions
)
```

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `bulbDiameter` | `50` | Diameter of the bulb at the bottom |
| `tubeWidth` | `30` | Width of the tube |
| `tubeHeight` | `100` | Height of the straight part of the tube |
| `lineWidth` | `4` | Stroke width of the glass outline |
| `outlineStroke` | `'black'` | Color of the glass outline |
| `glassThickness` | `4` | Gap between the outline and the fluid inside it |
| `tickSpacing` | `15` | Pixel spacing between tick marks |
| `tickSpacingTemperature` | `null` | If set, overrides `tickSpacing` to space ticks by units of temperature instead of pixels |
| `majorTickLength` / `minorTickLength` | `15` / `7.5` | Lengths of alternating major/minor ticks |
| `zeroLevel` | `'bulbCenter'` | Where the fluid level sits at `minTemperature` — `'bulbCenter'` or `'bulbTop'` |
| `backgroundFill` | `null` | If set, an extra `Path` is drawn behind the fluid in this color; `null` leaves the tube background transparent |
| `fluidMainColor` / `fluidHighlightColor` / `fluidRightSideColor` | shades of red | Colors for the bulb fluid and the tube's gradient |

## Methods

| Method | Effect |
| --- | --- |
| `temperatureToYPos( temperature )` | Converts a temperature (or `null`) to the internal y-coordinate used for tick placement |
| `yPosToTemperature( y )` | Inverse of the above, useful for mapping a draggable thumb position back to a temperature |

::: tip A `null` temperature is treated as the literal value `0`, not `minTemperature`
`temperatureProperty` accepts `number | null`. Internally, `ThermometerNode` substitutes the literal number `0` for `null` before mapping it through the temperature-to-height function (a legacy requirement carried over from States of Matter) — it does **not** hide the fluid or throw. This only reads the same as `minTemperature` when `minTemperature` happens to be `0`; with a non-zero `minTemperature` (e.g. a negative range), a `null` reading shows the fluid level for temperature `0`, not the bottom of the tube. If you need "no reading" to look visually distinct, handle that in a sibling Node rather than expecting `ThermometerNode` to do it.
:::


========================================================================
Page: TimeControlNode
URL: https://veillette.github.io/Almanach/api/scenery-phet/time-control-node
Source: docs/api/scenery-phet/time-control-node.md
Category: API | Tags: scenery-phet, TimeControlNode | Status: verified
========================================================================

# TimeControlNode

`TimeControlNode` (from `scenerystack/scenery-phet`) is the standard control strip for time-based simulations: a play/pause button, an optional step-forward button (shown by default), an optional step-backward button, and optional radio buttons for selecting a `TimeSpeed`. It's bound to a single `Property<boolean>` that tracks whether the sim is currently playing.

```ts
import { TimeControlNode } from 'scenerystack/scenery-phet';
import { Property } from 'scenerystack/axon';
```

## A minimal example

```ts
const isPlayingProperty = new Property<boolean>( true );

const timeControlNode = new TimeControlNode( isPlayingProperty, {
  playPauseStepButtonOptions: {
    includeStepBackwardButton: true
  },
  tandem: tandem.createTandem( 'timeControlNode' )
} );
```

`isPlayingProperty` is the single source of truth for whether the model is stepping — read it in your model's `step` logic, or the model's animation loop, rather than having `TimeControlNode` drive time directly.

## Constructor

```ts
new TimeControlNode(
  isPlayingProperty: Property<boolean>,
  providedOptions?: TimeControlNodeOptions
)
```

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `timeSpeedProperty` | `null` | An `EnumerationProperty<TimeSpeed>` for the speed radio buttons; if `null`, no radio buttons are included |
| `timeSpeeds` | `[ TimeSpeed.NORMAL, TimeSpeed.SLOW ]` | Which speeds get a radio button, and in what order, when `timeSpeedProperty` is provided |
| `speedRadioButtonGroupPlacement` | `'right'` | Where the speed radio buttons sit relative to the play/pause/step buttons — `'left'`, `'right'`, `'top'`, or `'bottom'` |
| `playPauseStepButtonOptions` | — | Forwarded to the internal `PlayPauseStepButtonGroup`; use this to add a step-backward button (see below) |
| `speedRadioButtonGroupOptions` | — | Forwarded to the internal `TimeSpeedRadioButtonGroup` |
| `flowBoxAlign` | `'center'` | Alignment of the `FlowBox` laying out the buttons and (if present) radio buttons |
| `flowBoxSpacing` | `40` | Spacing between the button group and the radio button group |

### `playPauseStepButtonOptions`

| Option | Default | Effect |
| --- | --- | --- |
| `includeStepForwardButton` | `true` | Whether a step-forward button is shown |
| `includeStepBackwardButton` | `false` | Whether a step-backward button is shown |
| `playPauseStepXSpacing` | `10` | Horizontal spacing between the play/pause and step buttons |

## Methods

| Method | Effect |
| --- | --- |
| `addPushButton( pushButton, index )` | Inserts an extra `RoundPushButton` into the button group at the given index — for a custom control alongside play/pause/step |

::: tip Step buttons default to forward-only
Out of the box you only get a step-forward button; a step-backward button must be opted into via `playPauseStepButtonOptions.includeStepBackwardButton: true`. The step buttons are automatically disabled while `isPlayingProperty` is `true` — you don't need to wire that up yourself.
:::


========================================================================
Page: TimeSpeedRadioButtonGroup
URL: https://veillette.github.io/Almanach/api/scenery-phet/time-speed-radio-button-group
Source: docs/api/scenery-phet/time-speed-radio-button-group.md
Category: API | Tags: scenery-phet, TimeSpeedRadioButtonGroup, TimeSpeed | Status: complete
========================================================================

# TimeSpeedRadioButtonGroup

`TimeSpeedRadioButtonGroup` (from `scenerystack/scenery-phet`) is a `VerticalAquaRadioButtonGroup<TimeSpeed>` for choosing a simulation's playback speed. It's driven by the `TimeSpeed` enumeration — `TimeSpeed.SLOW`, `TimeSpeed.NORMAL`, `TimeSpeed.FAST` — each rendered as a localized text label ("Slow"/"Normal"/"Fast"). It's a subcomponent of [`TimeControlNode`](/api/scenery-phet/time-control-node) (passed via that component's `timeSpeedProperty`/`timeSpeeds` options), but is exported and usable standalone.

```ts
import { TimeSpeedRadioButtonGroup, TimeSpeed } from 'scenerystack/scenery-phet';
import { EnumerationProperty } from 'scenerystack/axon';
```

## A minimal example

```ts
const timeSpeedProperty = new EnumerationProperty( TimeSpeed.NORMAL );

const timeSpeedRadioButtonGroup = new TimeSpeedRadioButtonGroup(
  timeSpeedProperty,
  [ TimeSpeed.NORMAL, TimeSpeed.SLOW ],
  { tandem: tandem.createTandem( 'timeSpeedRadioButtonGroup' ) }
);
```

## Constructor

```ts
new TimeSpeedRadioButtonGroup(
  timeSpeedProperty: EnumerationProperty<TimeSpeed>,
  timeSpeeds: TimeSpeed[],
  providedOptions?: TimeSpeedRadioButtonGroupOptions
)
```

The `timeSpeeds` array controls both *which* speeds get a radio button and the *order* they're listed in — a sim that only ever runs at normal or slow speed (a common PhET pattern) would pass `[ TimeSpeed.NORMAL, TimeSpeed.SLOW ]` and omit `FAST` entirely.

## The `TimeSpeed` enumeration

```ts
class TimeSpeed extends EnumerationValue {
  static readonly FAST: TimeSpeed;
  static readonly NORMAL: TimeSpeed;
  static readonly SLOW: TimeSpeed;
  static readonly enumeration: Enumeration<TimeSpeed>;
}
```

`TimeSpeed` has exactly three values and carries no numeric multiplier itself — mapping `TimeSpeed.SLOW`/`FAST` to an actual time-scale factor (e.g. `0.25`, `1`, `2`) is left entirely to the sim's own step logic; `TimeSpeedRadioButtonGroup` and `TimeControlNode` only manage which value is currently selected.

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `radius` | Half the height of a rendered label `Text` | Radius of each Aqua radio button circle, computed so buttons visually match the label text size unless overridden |
| `labelOptions` | `{ font: new PhetFont( 14 ), maxWidth: 130 }` | Options for each speed's `Text` label |
| `spacing` | `9` | Vertical spacing between radio button rows (inherited from `VerticalAquaRadioButtonGroup`) |

::: tip The label-to-`TimeSpeed` mapping is fixed
`TimeSpeedRadioButtonGroup` builds its items from an internal map of `TimeSpeed` to a localized string and PhET-iO tandem name — there's no option to relabel or reorder an individual speed's text. If you need custom labels, build your own `VerticalAquaRadioButtonGroup<TimeSpeed>` directly instead.
:::


========================================================================
Page: Trash Buttons
URL: https://veillette.github.io/Almanach/api/scenery-phet/trash-buttons
Source: docs/api/scenery-phet/trash-buttons.md
Category: API | Tags: scenery-phet, MoveToTrashButton, MoveToTrashLegendButton, TrashButton, button | Status: complete
========================================================================

# Trash Buttons

`scenerystack/scenery-phet` has three [`RectangularPushButton`](/api/sun/rectangular-push-button) subclasses built around the same trash-can `Path` (`trashShape`), differing in whether a curved "move to" arrow is added and how muted the styling is. All are one-shot action buttons — pressing one removes or discards something, they hold no toggle state.

```ts
import { MoveToTrashButton, TrashButton } from 'scenerystack/scenery-phet';
```

## A minimal example

```ts
const moveToTrashButton = new MoveToTrashButton( {
  arrowColor: 'blue',
  listener: () => {
    particlesProperty.value = [];
  },
  tandem: tandem.createTandem( 'moveToTrashButton' )
} );

const trashButton = new TrashButton( {
  listener: () => {
    selectedItemProperty.value = null;
  },
  tandem: tandem.createTandem( 'trashButton' )
} );
```

## The family

| Class | Icon | Notable options | Typical use |
| --- | --- | --- | --- |
| `MoveToTrashButton` | Trash can plus a curved arrow pointing into it (`arrowColor`, default `'black'`; `iconScale`, default `0.46`) | `arrowColor` lets the arrow be color-coded to the thing being deleted (e.g. match a particle's color) | "Send this specific thing to the trash," where the arrow communicates *moving* something rather than an instantaneous delete |
| `MoveToTrashLegendButton` | Same icon as `MoveToTrashButton` (it's a direct subclass) | Muted, flat styling: `baseColor: 'rgb( 230, 230, 240 )'`, `buttonAppearanceStrategy: ButtonNode.FlatAppearanceStrategy`, smaller `cornerRadius`/margins/`iconScale` | Appearing inside a legend or as part of a bar-chart label, where a bold yellow 3D button would be visually too loud |
| `TrashButton` | Plain trash can only, no arrow (`iconOptions`, default `{ scale: 0.95, fill: 'black' }`) | Simplest of the three — just the can | A direct "delete" action where the "moving into the trash" metaphor of the arrow isn't needed |

`MoveToTrashButton` and `TrashButton` both default `baseColor` to `PhetColorScheme.BUTTON_YELLOW` (inherited from `RectangularPushButtonOptions`, not overridden); `MoveToTrashLegendButton` overrides it to a muted gray-blue since it's meant to sit quietly inside other content.

::: tip Pick the icon based on whether "moving" is meaningful
Use `MoveToTrashButton` when the action reads as relocating a specific object (a draggable item, a data point) into a trash can — the arrow reinforces that. Use plain `TrashButton` for a generic "delete/clear" action where there's nothing being visually "moved." Reach for `MoveToTrashLegendButton` only when the button itself is a label inside a legend, not a primary interactive control.
:::


========================================================================
Page: TriangleNode
URL: https://veillette.github.io/Almanach/api/scenery-phet/triangle-node
Source: docs/api/scenery-phet/triangle-node.md
Category: API | Tags: scenery-phet, TriangleNode, triangle, shape, marker | Status: complete
========================================================================

# TriangleNode

`TriangleNode` (from `scenerystack/scenery-phet`) draws a triangle `Path` — equilateral if `triangleWidth` and `triangleHeight` produce one, isosceles otherwise — pointing up by default, with its point drawn perpendicular from the midpoint of its base. It's a lightweight alternative to building the same `Shape` by hand whenever you need a simple triangular marker, arrowhead, or indicator.

```ts
import { TriangleNode } from 'scenerystack/scenery-phet';
```

## A minimal example

```ts
const arrowHead = new TriangleNode( {
  pointDirection: 'right',
  triangleWidth: 20,
  triangleHeight: 16,
  fill: 'black'
} );
```

## Constructor

```ts
new TriangleNode( providedOptions?: TriangleNodeOptions )
```

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `pointDirection` | `'up'` | Which way the triangle's point faces: `'up'`, `'down'`, `'left'`, `'right'` |
| `triangleWidth` | `15` | Width of the base (before rotation for `pointDirection`) |
| `triangleHeight` | `13` | Altitude from the base to the point |
| `stroke` (inherited `PathOptions`) | `'black'` | Outline color |
| `lineWidth` (inherited `PathOptions`) | `1` | Outline width |
| `cursor` (inherited `NodeOptions`) | `'pointer'` | Default cursor, since `TriangleNode` is commonly used as a clickable indicator |

::: tip `rotation` and `shape` are not accepted as options
`TriangleNodeOptions` omits `rotation`, `shape`, and `shapeProperty` from the underlying `PathOptions` — the triangle's shape is always built internally from `triangleWidth`/`triangleHeight`, and its orientation is controlled only through `pointDirection`. Setting `.rotation` on an instance afterward will rotate it away from the cardinal direction `pointDirection` implies.
:::


========================================================================
Page: ValueGaugeNode
URL: https://veillette.github.io/Almanach/api/scenery-phet/value-gauge-node
Source: docs/api/scenery-phet/value-gauge-node.md
Category: API | Tags: scenery-phet, ValueGaugeNode, GaugeNode, NumberDisplay, gauge, dial | Status: complete
========================================================================

# ValueGaugeNode

`ValueGaugeNode` (from `scenerystack/scenery-phet`) is a [`GaugeNode`](/api/scenery-phet/gauge-node) subclass that adds a centered [`NumberDisplay`](/api/scenery-phet/number-display) showing the same value the needle points to, positioned in the bottom half of the dial. It takes the exact same constructor arguments as `GaugeNode` — use it whenever readers should see both the analog needle position *and* an exact numeric readout, without composing the two Nodes yourself.

```ts
import { ValueGaugeNode } from 'scenerystack/scenery-phet';
import { NumberProperty, StringProperty } from 'scenerystack/axon';
import { Range } from 'scenerystack/dot';
```

## A minimal example

```ts
const speedProperty = new NumberProperty( 42 );
const speedRange = new Range( 0, 100 );
const labelProperty = new StringProperty( 'm/s' );

const gaugeNode = new ValueGaugeNode( speedProperty, labelProperty, speedRange, {
  radius: 120,
  numberDisplayOptions: {
    decimalPlaces: 1
  }
} );

gaugeNode.numberDisplayVisible = false; // hide just the numeric readout; the needle and dial stay visible
```

## Constructor

```ts
new ValueGaugeNode(
  valueProperty: TReadOnlyProperty<number>,
  labelProperty: TReadOnlyProperty<string>,
  range: Range,
  providedOptions?: ValueGaugeNodeOptions
)
```

Identical signature to [`GaugeNode`](/api/scenery-phet/gauge-node#constructor), plus one extra option below. All of `GaugeNode`'s options (`radius`, `span`, tick options, etc.) are accepted too.

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `numberDisplayOptions` | `{ textOptions: { font: new PhetFont(16) }, backgroundStroke: 'black', align: 'center', cornerRadius: 5 }` | Options forwarded to the internal [`NumberDisplay`](/api/scenery-phet/number-display) |

## Public API

| Member | Description |
| --- | --- |
| `numberDisplayVisible` | Settable/gettable `boolean` — show or hide the internal `NumberDisplay` without affecting the dial or needle |

::: warning Don't pass position options to `numberDisplayOptions`
`ValueGaugeNode` positions its internal `NumberDisplay` itself, centered at `(0, radius / 2)` via a `ManualConstraint`, and asserts that the `NumberDisplay` has no translation from options you passed. Use `numberDisplayOptions` only for its formatting/appearance options (`decimalPlaces`, `valuePattern`, colors, etc.), not `x`/`y`/`center`.
:::


========================================================================
Page: ViewSynchronizer
URL: https://veillette.github.io/Almanach/api/scenery-phet/view-synchronizer
Source: docs/api/scenery-phet/view-synchronizer.md
Category: API | Tags: scenery-phet, ViewSynchronizer, model-view, dynamic-elements | Status: complete
========================================================================

# ViewSynchronizer

`ViewSynchronizer<Model, View extends Node>` (from `scenerystack/scenery-phet`) is a plain (non-`Node`) utility class that automates the common "one view Node per model element" bookkeeping: give it a container `Node` and a factory function, and its `add`/`remove` methods create-and-attach or detach-and-dispose the corresponding view for you, tracked internally in a `Map`. It's most useful paired with an [observable array](/api/axon/observable-array) of model elements, wiring `add`/`remove` straight to `elementAddedEmitter`/`elementRemovedEmitter`.

```ts
import { ViewSynchronizer } from 'scenerystack/scenery-phet';
import { createObservableArray } from 'scenerystack/axon';
import { Node, Circle } from 'scenerystack/scenery';
```

## A minimal example

```ts
type Particle = { id: number; radius: number };

const particles = createObservableArray<Particle>();
const particlesLayer = new Node();

const synchronizer = new ViewSynchronizer<Particle, Node>( particlesLayer, particle =>
  new Circle( particle.radius, { fill: 'blue' } )
);

particles.elementAddedEmitter.addListener( particle => synchronizer.add( particle ) );
particles.elementRemovedEmitter.addListener( particle => synchronizer.remove( particle ) );

particles.push( { id: 1, radius: 10 } ); // creates a Circle and adds it to particlesLayer
particles.pop();                          // removes that Circle from particlesLayer and disposes it
```

## Constructor

```ts
new ViewSynchronizer<Model, View extends Node>(
  container: Node,
  factory: ( model: Model ) => View
)
```

| Parameter | Effect |
| --- | --- |
| `container` | The `Node` that every created view becomes a child of |
| `factory` | Builds the view `Node` for a given model element; called once per `add()` |

## Public API

| Member | Description |
| --- | --- |
| `add( model )` | Builds a view via `factory( model )`, records the model → view mapping, and adds the view as a child of `container` |
| `remove( model )` | Looks up the view for `model`, removes it from `container`, calls `view.dispose()`, and forgets the mapping |
| `getView( model )` | Returns the view currently associated with `model` |
| `getViews()` | Returns an array of every currently-tracked view |
| `dispose()` | Calls `remove()` for every tracked model element, tearing down all views at once |

::: tip `ViewSynchronizer` doesn't listen to anything on its own
It exposes `add`/`remove` as plain methods — you're responsible for calling them at the right time, typically from an observable array's `elementAddedEmitter`/`elementRemovedEmitter` listeners as shown above. This keeps `ViewSynchronizer` decoupled from any specific collection type. See [Dispose and Memory Management](/patterns/dispose-and-memory-management) for why `remove()` disposing the view (rather than just detaching it) matters for dynamically-created elements.
:::


========================================================================
Page: Wavelength and Spectrum Sliders
URL: https://veillette.github.io/Almanach/api/scenery-phet/wavelength-and-spectrum-sliders
Source: docs/api/scenery-phet/wavelength-and-spectrum-sliders.md
Category: API | Tags: scenery-phet, SpectrumSliderThumb, SpectrumSliderTrack, WavelengthNumberControl, WavelengthSpectrumNode, VisibleColor, wavelength, color, slider | Status: complete
========================================================================

# Wavelength and Spectrum Sliders

Picking a color by dragging a slider along a visible-light gradient is a recurring PhET interaction (light/color sims, wave-interference sims, anything with a "choose a wavelength" control). `scenerystack/scenery-phet` provides this in two layers: generic color-gradient slider parts (`SpectrumSliderThumb`, `SpectrumSliderTrack`, built on [`SpectrumNode`](/api/scenery-phet/spectrum-node)), and a ready-made wavelength-specific composite (`WavelengthNumberControl`, `WavelengthSpectrumNode`), all backed by `VisibleColor`'s physically-grounded wavelength-to-RGB conversion.

```ts
import { WavelengthNumberControl } from 'scenerystack/scenery-phet';
import { NumberProperty } from 'scenerystack/axon';

// A wavelength in nanometers, defaulting to a value in the visible range.
const wavelengthProperty = new NumberProperty( 550 );

const wavelengthControl = new WavelengthNumberControl( wavelengthProperty );
```

## VisibleColor: the wavelength <-> RGB conversion

`VisibleColor` is a static utility object (not a class) mapping between nanometer wavelengths and sRGB `Color`s using a precomputed lookup table, plus a couple of physical constants.

| Member | Value / signature | Notes |
| --- | --- | --- |
| `MIN_WAVELENGTH` / `MAX_WAVELENGTH` | `380` / `780` (nm) | The visible range the lookup table covers |
| `MIN_FREQUENCY` / `MAX_FREQUENCY` | Derived from `SPEED_OF_LIGHT` | In Hz |
| `SPEED_OF_LIGHT` | `299792458` (m/s) | Speed of light in a vacuum |
| `wavelengthToColor( wavelength, options? )` | `( number, WavelengthToColorOptions? ) => Color` | Below `MIN_WAVELENGTH` is "UV," above `MAX_WAVELENGTH` is "IR" — both return `options.uvColor`/`options.irColor` (default `null`, meaning you must supply one to avoid an assertion) rather than a spectrum color |
| `frequencyToColor( frequency, options? )` | `( number, WavelengthToColorOptions? ) => Color` | Converts frequency to wavelength first, then calls `wavelengthToColor` |
| `colorToWavelength( color, reduceIntensityAtExtrema? )` | `( Color, boolean? ) => number` | The inverse lookup; asserts if no close-enough match is found in the table |
| `isVisibleWavelength` / `isIRWavelength` / `isUVWavelength` | `( number ) => boolean` | Range checks against `MIN_WAVELENGTH`/`MAX_WAVELENGTH` |

`reduceIntensityAtExtrema` (default `true` on the options) dims colors near the edges of the visible range, since perceived brightness falls off there — pass `false` for full-intensity colors throughout.

```ts
import { VisibleColor } from 'scenerystack/scenery-phet';

const greenish = VisibleColor.wavelengthToColor( 550 ); // ~green
const isVisible = VisibleColor.isVisibleWavelength( 900 ); // false (infrared)
```

## SpectrumSliderTrack and SpectrumSliderThumb: generic gradient slider parts

These are a matched `SliderTrack`/(thumb `Node`) pair — see [Slider, SliderTrack, and SliderThumb](/api/sun/slider-track-and-thumb) — meant to be passed as `trackNode`/`thumbNode` options to a plain [`Slider`](/api/sun/slider) when you want the track itself to *be* the color gradient, rather than a plain gray bar. Both take the same `valueToColor: ( value: number ) => Color` function so the track and the thumb's fill stay in sync.

| Type | Base class | Key options |
| --- | --- | --- |
| `SpectrumSliderTrack` | `SliderTrack` (`sun`) | `valueToColor` (default grayscale), `size` (default `150 x 30`); internally builds a [`SpectrumNode`](/api/scenery-phet/spectrum-node) for the visual |
| `SpectrumSliderThumb` | `Path` | `valueToColor`, `width`/`height` (default `35 x 45`) for the teardrop handle shape, `cursorHeight`/`cursorWidth` for the thin indicator line overlaid on the track |

```ts
import { SpectrumSliderTrack, SpectrumSliderThumb, VisibleColor } from 'scenerystack/scenery-phet';
import { Slider } from 'scenerystack/sun';
import { NumberProperty } from 'scenerystack/axon';
import { Range } from 'scenerystack/dot';

const valueProperty = new NumberProperty( 550 );
const range = new Range( VisibleColor.MIN_WAVELENGTH, VisibleColor.MAX_WAVELENGTH );

const trackNode = new SpectrumSliderTrack( valueProperty, range, {
  valueToColor: VisibleColor.wavelengthToColor
} );
const thumbNode = new SpectrumSliderThumb( valueProperty, {
  valueToColor: VisibleColor.wavelengthToColor
} );

const spectrumSlider = new Slider( valueProperty, range, {
  trackNode: trackNode,
  thumbNode: thumbNode
} );
```

## WavelengthSpectrumNode and WavelengthNumberControl: the wavelength-specific composites

`WavelengthSpectrumNode` is a [`SpectrumNode`](/api/scenery-phet/spectrum-node) subclass that hard-codes `valueToColor` to `VisibleColor.wavelengthToColor` and defaults its `minValue`/`maxValue` to `VisibleColor.MIN_WAVELENGTH`/`MAX_WAVELENGTH` — a static, non-interactive rendering of the visible spectrum bar, useful as a legend or backdrop.

`WavelengthNumberControl` goes further and assembles the entire interactive control: it's a [`NumberControl`](/api/scenery-phet/number-control) whose slider is built from `SpectrumSliderTrack`/`SpectrumSliderThumb` (both wired to `VisibleColor.wavelengthToColor` by default), plus the standard title and numeric ("### nm") readout.

```ts
import { WavelengthNumberControl, WavelengthSpectrumNode } from 'scenerystack/scenery-phet';
import { NumberProperty } from 'scenerystack/axon';
import { Range, Dimension2 } from 'scenerystack/dot';

const wavelengthProperty = new NumberProperty( 650 );

// The full interactive control: title, slider with gradient track, and "650 nm" readout.
const control = new WavelengthNumberControl( wavelengthProperty, {
  range: new Range( 400, 700 ) // narrower than the full visible range, if desired
} );

// A static, non-interactive spectrum bar, e.g. as a legend.
const legend = new WavelengthSpectrumNode( {
  size: new Dimension2( 200, 20 )
} );
```

::: tip Reach for WavelengthNumberControl first
Unless you need a bare gradient bar (`WavelengthSpectrumNode`) or a custom composite slider (assembled from `SpectrumSliderTrack`/`SpectrumSliderThumb` directly), `WavelengthNumberControl` is the one-line way to get a fully wired wavelength picker with title, gradient slider, and numeric readout, matching the standard PhET look.
:::


========================================================================
Page: WireNode
URL: https://veillette.github.io/Almanach/api/scenery-phet/wire-node
Source: docs/api/scenery-phet/wire-node.md
Category: API | Tags: scenery-phet, WireNode, wire, cable, circuit | Status: verified
========================================================================

# WireNode

`WireNode` (from `scenerystack/scenery-phet`) is a `Path` subclass that draws a cubic Bezier curve between two positions and keeps redrawing it as either position changes — the classic use is visually connecting a `ProbeNode` to the body that shows its reading, but it works for any two moving endpoints (including circuit-style connections between components).

```ts
import { WireNode } from 'scenerystack/scenery-phet';
import { DerivedProperty } from 'scenerystack/axon';
import { Vector2 } from 'scenerystack/dot';
```

## A minimal example

```ts
// Typically these are DerivedProperties following the probe/body Nodes' translations.
const probePositionProperty = new DerivedProperty( [ probeNode.boundsProperty ], () => probeNode.centerBottom );
const probeNormalProperty = new DerivedProperty( [], () => new Vector2( 0, 50 ) );

const bodyPositionProperty = new DerivedProperty( [ bodyNode.boundsProperty ], () => bodyNode.centerTop );
const bodyNormalProperty = new DerivedProperty( [], () => new Vector2( 0, -50 ) );

const wireNode = new WireNode(
  probePositionProperty, probeNormalProperty,
  bodyPositionProperty, bodyNormalProperty,
  { stroke: 'gray', lineWidth: 3 }
);
```

## Constructor

```ts
new WireNode(
  position1Property: TReadOnlyProperty<Vector2>,
  normal1Property: TReadOnlyProperty<Vector2>,
  position2Property: TReadOnlyProperty<Vector2>,
  normal2Property: TReadOnlyProperty<Vector2>,
  options?: WireNodeOptions
)
```

`positionXProperty` is where that end of the wire attaches. `normalXProperty` is **not** a second point — it's an offset (a vector, in the same coordinate frame) added to `positionXProperty` to get the cubic curve's control point at that end, which is what gives the wire its droop/curve direction and how pronounced it is. `WireNode` internally wires up a `Multilink` across all four Properties and recomputes its `shape` whenever any of them changes.

## Options

`WireNodeOptions` is just `PathOptions` (no wire-specific self options beyond the constructor arguments above); the one default `WireNode` sets is:

| Option | Default | Effect |
| --- | --- | --- |
| `stroke` | `'black'` | Color of the wire |

::: tip The "normal" is a control-point offset, not a direction to normalize
Despite the name, `normal1Property`/`normal2Property` values are used directly as `position.plus( normal )` to compute the cubic curve's control points — their magnitude controls how far the curve bulges out before bending toward the other end, not just its direction. A `Vector2(0, 50)` and a `Vector2(0, 5)` point the same way but produce very differently shaped wires.
:::


========================================================================
Page: XNode
URL: https://veillette.github.io/Almanach/api/scenery-phet/x-node
Source: docs/api/scenery-phet/x-node.md
Category: API | Tags: scenery-phet, XNode, PlusNode, marker, icon | Status: complete
========================================================================

# XNode

`XNode` (from `scenerystack/scenery-phet`) draws an 'x' mark: it's a thin subclass of `PlusNode` that fixes `rotation` to 45 degrees and reinterprets `PlusNode`'s `size` option as `length` (the diagonal length) and `legThickness` (the width of each stroke). It's used, for example, to mark the center of mass of a system of bodies, but works generically anywhere you need a simple 'x' icon or marker.

```ts
import { XNode } from 'scenerystack/scenery-phet';
```

## A minimal example

```ts
const centerOfMassMarker = new XNode( {
  length: 30,
  legThickness: 8,
  fill: 'red'
} );
```

## Constructor

```ts
new XNode( providedOptions?: XNodeOptions )
```

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `length` | `22` | Length of the 'x' along its diagonal |
| `legThickness` | `6` | Thickness of each of the 'x''s two strokes |
| `lineWidth` (inherited `PathOptions`) | `1.5` | Stroke width around the 'x' shape's outline |
| `fill` (inherited `PathOptions`, via `PlusNode`) | `'black'` | Fill color of the 'x' |

::: tip `size` and `rotation` are not accepted
`XNode`'s options type explicitly omits `size` and `rotation` from the underlying `PlusNodeOptions` — it computes both internally from `length`/`legThickness` and the fixed 45-degree rotation. Passing `length`/`legThickness` is the supported way to resize an `XNode`; setting `.rotation` on an instance afterward will visually un-rotate it back away from a proper 'x'.
:::


========================================================================
Page: YawPitchModelViewTransform3
URL: https://veillette.github.io/Almanach/api/scenery-phet/yaw-pitch-model-view-transform3
Source: docs/api/scenery-phet/yaw-pitch-model-view-transform3.md
Category: API | Tags: scenery-phet, YawPitchModelViewTransform3, transform, capacitor, coordinates | Status: complete
========================================================================

# YawPitchModelViewTransform3

`YawPitchModelViewTransform3` (from `scenerystack/scenery-phet`, under `scenery-phet/js/capacitor/`) maps 3D model coordinates onto a 2D view plane using a fixed yaw (rotation about the vertical axis) and pitch (rotation about the horizontal axis), producing the oblique, pseudo-3D look used by [the capacitor visualization nodes](/api/scenery-phet/capacitor-visualization-nodes) (`CapacitorNode`, `PlateNode`, `BoxNode`). It is not a general-purpose 3D engine — there's no camera, no perspective divide, no z-buffering — just a cheap, fixed-angle projection that gives boxes and plates a sense of depth. Internally it composes a 2D [`ModelViewTransform2`](/api/phetcommon/model-view-transform) (for the flat x/y scaling) with a manual z-axis foreshortening step.

In both coordinate systems, +x is to the right, +y is down, and +z is away from the viewer; rotation signs follow the right-hand rule.

```ts
import { YawPitchModelViewTransform3 } from 'scenerystack/scenery-phet';
import { Vector3 } from 'scenerystack/dot';
```

## A minimal example

```ts
const modelViewTransform = new YawPitchModelViewTransform3( {
  scale: 15000,               // model meters -> view pixels
  pitch: 30 * Math.PI / 180,  // rotate 30° about the x-axis
  yaw: -45 * Math.PI / 180    // rotate -45° about the y-axis
} );

// A point 5mm "into the screen" (+z) projects up and to the side, not straight down:
const viewPoint = modelViewTransform.modelToViewPosition( new Vector3( 0, 0, 0.005 ) );

// Round-trip a view-space drag back into model space (z is always 0 on the way back):
const modelPoint = modelViewTransform.viewToModelXY( viewPoint.x, viewPoint.y );
```

## Constructor

```ts
new YawPitchModelViewTransform3( options?: {
  scale?: number;  // default 12000 — shared x/y scale for the underlying 2D transform
  pitch?: number;  // default 30° in radians — rotation about the horizontal (x) axis
  yaw?: number;    // default -45° in radians — rotation about the vertical (y) axis
} )
```

`yaw` is exposed as a public readonly field (`transform.yaw`); `pitch` and the internal 2D transform are private.

## Methods

| Method | Effect |
| --- | --- |
| `modelToViewPosition( modelPoint: Vector3 )` → `Vector2` | Projects a 3D model point to a 2D view point |
| `modelToViewXYZ( x, y, z )` → `Vector2` | Convenience form of the above taking bare numbers |
| `modelToViewDelta( delta: Vector3 )` / `modelToViewDeltaXYZ( dx, dy, dz )` → `Vector2` | Projects a *delta* rather than an absolute position (computed as the projected point minus the projected origin, so it's translation-invariant) |
| `modelToViewShape( modelShape: Shape )` → `Shape` | Transforms a flat (z = 0) model-space `Shape` using only the underlying 2D transform |
| `modelToViewBounds( modelBounds: Bounds2 )` → `Bounds2` | Transforms flat model-space `Bounds2` using only the underlying 2D transform |
| `viewToModelPosition( viewPoint: Vector2 )` → `Vector3` | Inverse of `modelToViewPosition` — **not** a true inverse projection; it uses the 2D transform's inverse and always returns `z = 0` |
| `viewToModelXY( x, y )` → `Vector3` | Convenience form of the above |
| `viewToModelDelta( delta: Vector2 )` / `viewToModelDeltaXY( dx, dy )` → `Vector3` | Inverse-delta versions, again fixed at `z = 0` |
| `viewToModelShape( viewShape: Shape )` / `viewToModelBounds( viewBounds: Bounds2 )` | Inverse shape/bounds transforms, via the 2D transform |

::: warning View-to-model is not a true inverse of model-to-view
Because the forward projection collapses a 3D point onto a 2D plane, there is no unique 3D point to recover from a 2D view coordinate. Every `viewToModel*` method resolves this by ignoring depth entirely and returning `z = 0` — it inverts only the underlying 2D `ModelViewTransform2`, not the yaw/pitch projection. Don't expect `viewToModelPosition( modelToViewPosition( p ) )` to round-trip back to `p` unless `p.z` was already `0`.
:::


========================================================================
Page: Zoom Button Groups
URL: https://veillette.github.io/Almanach/api/scenery-phet/zoom-button-groups
Source: docs/api/scenery-phet/zoom-button-groups.md
Category: API | Tags: scenery-phet, ZoomButton, ZoomButtonGroup, PlusMinusZoomButtonGroup, MagnifyingGlassZoomButtonGroup, button | Status: complete
========================================================================

# Zoom Button Groups

`ZoomButtonGroup` is the base class for a paired "zoom in" / "zoom out" `RectangularPushButton` control bound to a ranged numeric `Property` (`TRangedProperty` — a `Property<number>` with a `.range`). It's `protected`-constructed, so you never instantiate it directly; instead pick one of its two concrete subclasses, `PlusMinusZoomButtonGroup` (flat "+"/"−" signs) or `MagnifyingGlassZoomButtonGroup` (magnifying-glass icons with "+"/"−" inside). Separately, `ZoomButton` is a standalone single button with the same magnifying-glass-plus-sign look, for building a custom zoom UI rather than the standard paired group.

```ts
import { PlusMinusZoomButtonGroup, MagnifyingGlassZoomButtonGroup } from 'scenerystack/scenery-phet';
import { NumberProperty } from 'scenerystack/axon';
import { Range } from 'scenerystack/dot';
```

## A minimal example

```ts
const zoomLevelProperty = new NumberProperty( 2, { range: new Range( 0, 5 ) } );

const zoomButtonGroup = new PlusMinusZoomButtonGroup( zoomLevelProperty, {
  orientation: 'horizontal',
  tandem: tandem.createTandem( 'zoomButtonGroup' )
} );

// Or, with magnifying-glass icons instead of flat +/- signs:
const magnifyingZoomButtonGroup = new MagnifyingGlassZoomButtonGroup( zoomLevelProperty, {
  tandem: tandem.createTandem( 'magnifyingZoomButtonGroup' )
} );
```

`zoomLevelProperty`'s range determines when each button auto-disables — the zoom-out button disables once applying `applyZoomOut` would fall outside the range, and likewise for zoom-in.

## `ZoomButtonGroup` (base class)

```ts
protected constructor(
  zoomLevelProperty: TRangedProperty,
  zoomInIcon: Node,
  zoomOutIcon: Node,
  providedOptions?: ZoomButtonGroupOptions
)
```

An `FlowBox` (horizontal by default) containing two internally-built `RectangularPushButton`s — it does not compose `ZoomButton` instances, even though the resulting look can be visually identical.

| Option | Default | Effect |
| --- | --- | --- |
| `applyZoomIn` / `applyZoomOut` | `currentZoom => currentZoom + 1` / `currentZoom => currentZoom - 1` | Functions computing the new zoom level on each press; override for non-integer zoom steps |
| `buttonOptions` | `{ fireOnHold: true, fireOnHoldDelay: 600, fireOnHoldInterval: 250 }` | Forwarded to both internal buttons (not `content`, `listener`, or `tandem`, which the group manages) |
| `touchAreaXDilation` / `touchAreaYDilation` / `mouseAreaXDilation` / `mouseAreaYDilation` | `0` | Pointer-area dilation; the group shifts the areas so they don't overlap given `spacing` |
| `orientation` | `'horizontal'` | `'horizontal'` places `[ zoomOut, zoomIn ]` left-to-right; `'vertical'` places `[ zoomIn, zoomOut ]` top-to-bottom |
| `spacing` | `0` | Space between the two buttons |

## Members

| Member | Description |
| --- | --- |
| `zoomInButton` / `zoomOutButton` | Public references to the two internal `RectangularPushButton`s |

## `PlusMinusZoomButtonGroup`

```ts
new PlusMinusZoomButtonGroup( zoomLevelProperty: TRangedProperty, providedOptions?: PlusMinusZoomButtonGroupOptions )
```

Uses bare `PlusNode`/`MinusNode` signs (no magnifying glass) as the icons, with flat, white, square-cornered `buttonOptions` (`baseColor: 'white'`, `buttonAppearanceStrategy: ButtonNode.FlatAppearanceStrategy`, `cornerRadius: 0`) — visually closer to a stepper control than a typical yellow PhET button.

| Option | Default | Effect |
| --- | --- | --- |
| `iconOptions` | `{ size: new Dimension2( 7, 1.26 ) }` | Forwarded to the internal `PlusNode`/`MinusNode` |

## `MagnifyingGlassZoomButtonGroup`

```ts
new MagnifyingGlassZoomButtonGroup( zoomLevelProperty: NumberProperty, providedOptions?: MagnifyingGlassZoomButtonGroupOptions )
```

Uses a [`MagnifyingGlassNode`](/api/scenery-phet/magnifying-glass-node) with a "+" or "−" sign inside the glass as each icon, and defaults `buttonOptions.baseColor` to `PhetColorScheme.BUTTON_YELLOW` — the same look as a standalone `ZoomButton`.

| Option | Default | Effect |
| --- | --- | --- |
| `magnifyingGlassNodeOptions` | `{ glassRadius: 15 }` | Forwarded to both internal `MagnifyingGlassNode`s |

## `ZoomButton` (standalone)

```ts
new ZoomButton( providedOptions?: ZoomButtonOptions )
```

A single `RectangularPushButton` with a `MagnifyingGlassNode` icon containing a "+" or "−" sign — the same visual as one button from a `MagnifyingGlassZoomButtonGroup`, but usable on its own (e.g. for a "zoom to fit" control that isn't part of a paired in/out group).

| Option | Default | Effect |
| --- | --- | --- |
| `in` | `true` | `true` draws a "+" (zoom in); `false` draws a "−" (zoom out) |
| `magnifyingGlassOptions` | `{ glassRadius: 15 }` | Forwarded to the internal `MagnifyingGlassNode` |

::: tip Pick a subclass by icon style, not by feature
`PlusMinusZoomButtonGroup` and `MagnifyingGlassZoomButtonGroup` behave identically — same range-driven enabling, same `applyZoomIn`/`applyZoomOut` hooks — they differ only in icon and default button styling. Choose based on which look fits your sim; reach for standalone `ZoomButton` only when you need a single zoom action rather than a bound in/out pair.
:::


========================================================================
Page: ABSwitch
URL: https://veillette.github.io/Almanach/api/sun/ab-switch
Source: docs/api/sun/ab-switch.md
Category: API | Tags: sun, ABSwitch, HBox | Status: complete
========================================================================

# ABSwitch

`ABSwitch<T>` (from `scenerystack/sun`) is an [`HBox`](/api/scenery/h-box) that lays out a label, a sliding switch, and a second label, bound to a `Property<T>` that takes exactly two named values — "choice A" on the left, "choice B" on the right. It's built on the same internal `ToggleSwitch<T>` as [`OnOffSwitch`](/api/sun/on-off-switch), but where `OnOffSwitch` is fixed to `boolean` and has no labels of its own, `ABSwitch` is generic over `T` and requires you to supply a `Node` label for each side — appropriate whenever the two choices need to be named rather than just "on"/"off" (units, difficulty levels, view modes, …).

```ts
import { ABSwitch } from 'scenerystack/sun';
import { Text } from 'scenerystack/scenery';
import { Property } from 'scenerystack/axon';
import { Tandem } from 'scenerystack/tandem';

const unitsProperty = new Property<'metric' | 'imperial'>( 'metric' );

const unitsSwitch = new ABSwitch(
  unitsProperty,
  'metric', new Text( 'cm', { tandem: Tandem.REQUIRED.createTandem( 'metricLabelText' ) } ),
  'imperial', new Text( 'in', { tandem: Tandem.REQUIRED.createTandem( 'imperialLabelText' ) } ),
  { tandem: Tandem.REQUIRED }
);
```

The constructor takes `( property, valueA, labelA, valueB, labelB, options? )` — clicking either label selects its value directly (via an internal [`PressListener`](/api/scenery/fire-listener) on each label), and dragging or clicking the switch itself behaves like `OnOffSwitch`'s underlying `ToggleSwitch` (click anywhere to toggle, drag past the midpoint and release to snap, or drag far enough to toggle immediately).

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `toggleSwitchOptions` | `{}` | Options forwarded to the internal `ToggleSwitch<T>` (`size`, `trackFillLeft`/`trackFillRight`, `thumbFill`, `toggleWhileDragging`, …) — see [`OnOffSwitch`](/api/sun/on-off-switch) for the full set |
| `setLabelEnabled` | Dims the unselected label to `SceneryConstants.DISABLED_OPACITY` | `( labelNode, enabled ) => void` — customize how the non-selected (or, when the whole switch is disabled, both) label looks |
| `valueAAccessibleName` / `valueBAccessibleName` | `null` (derived from the label Nodes if omitted) | Accessible names used to build the switch's combined accessible name, e.g. `"cm, Switch to in"` |
| `centerOnSwitch` | `false` | If `true`, both labels are wrapped in same-size `AlignBox`es (via a shared `AlignGroup`) so `this.center` lands on the switch itself rather than the visual center of the whole row |
| ...plus any [`HBox`](/api/scenery/h-box) option | `spacing: 8`, `cursor: 'pointer'` | `ABSwitch` *is* an `HBox`, so `spacing`, `align`, `justify`, etc. all apply to the label/switch/label row |

## Public API

| Member | Meaning |
| --- | --- |
| `onInputEmitter` | `TEmitter` that fires after the bound `Property`'s value actually changes as a result of user input (clicking a label, or dragging/clicking the switch) — not fired for programmatic changes to the Property |

::: warning Both label Nodes need their own tandem, and the Property must use reference equality
`ABSwitch` asserts that `labelA.tandem` and `labelB.tandem` are set (they need their own PhET-iO identity, since each gets a `PressListener` attached), and — same requirement as `OnOffSwitch` — that `property.valueComparisonStrategy === 'reference'`, since it compares `property.value` against `valueA`/`valueB` with `===`.
:::


========================================================================
Page: AccessibleNumberSpinner
URL: https://veillette.github.io/Almanach/api/sun/accessible-number-spinner
Source: docs/api/sun/accessible-number-spinner.md
Category: API | Tags: sun, AccessibleNumberSpinner, NumberSpinner, PDOM | Status: complete
========================================================================

# AccessibleNumberSpinner

`AccessibleNumberSpinner` (from `scenerystack/sun`) is a trait — like [`AccessibleSlider`](/api/sun/accessible-slider), a function from a `Node` subclass to a new class with behavior mixed in, not a `Node` you instantiate directly. [`NumberSpinner`](/api/sun/number-spinner) is defined as `class NumberSpinner extends AccessibleNumberSpinner( Node, 0 )`; reach for it yourself only when building a custom spinner-like component that needs the same keyboard repeat-on-hold behavior `NumberSpinner` gets for free.

```ts
import { AccessibleNumberSpinner } from 'scenerystack/sun';
import { Node } from 'scenerystack/scenery';
import { NumberProperty, Property } from 'scenerystack/axon';
import { Range } from 'scenerystack/dot';

class MyCustomSpinnerNode extends AccessibleNumberSpinner( Node, 0 ) {
  public constructor( valueProperty: NumberProperty, rangeProperty: Property<Range> ) {
    super( {
      valueProperty: valueProperty,
      enabledRangeProperty: rangeProperty,
      keyboardStep: 1,
      pageKeyboardStep: 5
    } );
    // ...add your own increment/decrement visuals here
  }
}
```

`AccessibleNumberSpinner( Type, optionsArgPosition )` shares its `optionsArgPosition` convention with `AccessibleSlider`. It mixes in the same underlying `AccessibleValueHandler` as `AccessibleSlider` (so `keyboardStep`/`shiftKeyboardStep`/`pageKeyboardStep`/`enabledRangeProperty` all mean the same thing there — see [`AccessibleSlider`](/api/sun/accessible-slider)), but layers spinner-specific behavior on top: a `CallbackTimer`-driven press-and-hold repeat (arrow keys fire once immediately, then repeat), and defaults tuned for a spinner rather than a slider — `ariaOrientation: Orientation.VERTICAL` and an `accessibleRoleDescription` announcing it as a "number spinner" (PhET's own custom ARIA role description, since native `input[type=range]` semantics don't quite fit; spinners use `role="range"` under the hood rather than number-input semantics, deliberately excluding numeric-key entry).

## Behavior it adds beyond AccessibleValueHandler

| Interaction | Effect |
| --- | --- |
| Arrow keys, single press | Change the value once by `keyboardStep` (or `shiftKeyboardStep` with Shift held) |
| Arrow keys, held down | After `pdomTimerDelay`, repeats the change every `pdomTimerInterval` until released |
| Page Up / Page Down, Home / End | Same as `AccessibleSlider` — larger step / jump to range extremes |

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `pdomTimerDelay` | `400` (ms) | Delay before a held key starts auto-repeating |
| `pdomTimerInterval` | `100` (ms) | Interval between repeats once auto-repeat has started |
| `accessibleRoleDescription` | `'number spinner'` string (translated) | Overridable ARIA role description announced to screen readers |

## Members worth knowing

| Member | Meaning |
| --- | --- |
| `pdomIncrementDownEmitter` / `pdomDecrementDownEmitter` | `TEmitter<[boolean]>`s that fire on keyboard-driven increment/decrement key-down and key-up — `NumberSpinner` uses these to style its arrow buttons as "pressed" during keyboard interaction, matching the visual feedback of a mouse press |

::: tip You're almost always consuming this indirectly
As with `AccessibleSlider`, simulation code essentially never invokes this trait directly — it's documented so [`NumberSpinner`](/api/sun/number-spinner)'s keyboard-step-family options and press-and-hold behavior have a page explaining exactly where they come from.
:::


========================================================================
Page: AccessibleSlider
URL: https://veillette.github.io/Almanach/api/sun/accessible-slider
Source: docs/api/sun/accessible-slider.md
Category: API | Tags: sun, AccessibleSlider, Slider, HSlider, VSlider, PDOM | Status: complete
========================================================================

# AccessibleSlider

`AccessibleSlider` (from `scenerystack/sun`) is a trait — a function that takes a `Node` subclass and returns a new class with slider-like keyboard/PDOM behavior mixed in — rather than a `Node` you instantiate directly. [`Slider`](/api/sun/slider) (and through it, [`HSlider`](/api/sun/hslider)/`VSlider`) is defined as `class Slider extends Sizable( AccessibleSlider( Node, 0 ) )`; reach for `AccessibleSlider` yourself only if you're building a custom slider-like component from scratch that needs the same keyboard behavior `Slider` gets for free.

```ts
import { AccessibleSlider } from 'scenerystack/sun';
import { Node } from 'scenerystack/scenery';
import { Range } from 'scenerystack/dot';
import { NumberProperty, Property } from 'scenerystack/axon';

class MyCustomSliderNode extends AccessibleSlider( Node, 0 ) {
  public constructor( valueProperty: NumberProperty, range: Range ) {
    super( {
      valueProperty: valueProperty,
      enabledRangeProperty: new Property( range ),
      keyboardStep: 1,
      shiftKeyboardStep: 0.1,
      pageKeyboardStep: 10
    } );
    // ...add your own visual children and mouse/touch dragging here
  }
}
```

`AccessibleSlider( Type, optionsArgPosition )` takes the base class to extend and the zero-indexed position of that class's constructor options argument (`Slider` passes `0` since its own constructor's options are the first argument after `super()`'s implicit args) — `AccessibleSlider` needs this so its `DelayedMutate`-based option handling can intercept the right argument.

Under the hood, `AccessibleSlider` mixes in `AccessibleValueHandler` (which does the bulk of the PDOM/`aria-valuenow`/`aria-valuetext` work shared with `AccessibleNumberSpinner`) and adds slider-specific `startDrag`/`drag`/`endDrag` hooks on top, named to match `Slider`'s own drag terminology rather than `AccessibleValueHandler`'s more generic `startInput`/`onInput`/`endInput`.

## Behavior it adds

| Interaction | Effect |
| --- | --- |
| Arrow keys (Left/Down, Right/Up) | Decrement/increment `valueProperty` by `keyboardStep` |
| Shift + arrow keys | Decrement/increment by `shiftKeyboardStep` (usually smaller) |
| Page Up / Page Down | Increment/decrement by `pageKeyboardStep` (usually larger) |
| Home / End | Jump to the range's minimum / maximum |

## Options (via `AccessibleValueHandler`)

| Option | Effect |
| --- | --- |
| `valueProperty` | Required — the numeric `Property` this behavior reads and writes |
| `enabledRangeProperty` | Required — a `TReadOnlyProperty<Range>` clamping keyboard-driven changes |
| `keyboardStep` / `shiftKeyboardStep` / `pageKeyboardStep` | Step sizes for the interactions above |
| `constrainValue` | `(value: number) => number`, applied before the value is committed |
| `startDrag` / `drag` / `endDrag` | Hooks fired at each stage of an accessible ("virtual drag") interaction — same names [`Slider`](/api/sun/slider) itself exposes |
| `roundToStepSize` | Round the value to a multiple of `keyboardStep` on ordinary key presses |

::: tip You're almost always consuming this indirectly
Simulation code essentially never calls `AccessibleSlider` directly — it's documented here because [`Slider`](/api/sun/slider)'s own `startDrag`/`drag`/`endDrag`/`keyboardStep`-family options are actually implemented by this trait, so this is the page to check for the precise contract behind those options. Compare [`AccessibleNumberSpinner`](/api/sun/accessible-number-spinner), the equivalent trait behind `NumberSpinner`.
:::


========================================================================
Page: AccordionBox
URL: https://veillette.github.io/Almanach/api/sun/accordion-box
Source: docs/api/sun/accordion-box.md
Category: API | Tags: sun, AccordionBox | Status: verified
========================================================================

# AccordionBox

`AccordionBox` (from `scenerystack/sun`) is a titled container that can be expanded or collapsed by clicking its title bar or expand/collapse button, backed by a `Property<boolean>` (`expandedProperty`). Use it for optional or secondary content you want available but don't want to occupy screen space by default — a "graph" or "advanced options" section is the typical case.

```ts
import { AccordionBox } from 'scenerystack/sun';
import { VBox, Text } from 'scenerystack/scenery';
import { Tandem } from 'scenerystack/tandem';

const graphContent = new VBox( {
  spacing: 6,
  children: [ /* ...plots, legends, etc. */ ]
} );

const graphAccordionBox = new AccordionBox( graphContent, {
  titleNode: new Text( 'Graph' ),
  expandedDefaultValue: false,
  tandem: Tandem.REQUIRED
} );
```

If you need to observe or control the expanded state from outside, supply your own `expandedProperty` instead of `expandedDefaultValue` — `AccordionBox` will use it directly rather than creating one internally:

```ts
import { BooleanProperty } from 'scenerystack/axon';

const isGraphExpandedProperty = new BooleanProperty( false );

const graphAccordionBox = new AccordionBox( graphContent, {
  titleNode: new Text( 'Graph' ),
  expandedProperty: isGraphExpandedProperty,
  tandem: Tandem.REQUIRED
} );
```

You cannot supply both `expandedProperty` and `expandedDefaultValue` — that combination asserts at construction time.

## Options

| Option | Effect |
| --- | --- |
| `titleNode` | Node shown in the title bar; a plain `Text` node is created for you if omitted |
| `expandedProperty` | Externally-owned `Property<boolean>` driving the expanded state |
| `expandedDefaultValue` | Initial value for the internally-created `expandedProperty` (default `true`) |
| `resize` | Whether the box resizes automatically as title/content bounds change (default `true`) |
| `fill` / `stroke` / `lineWidth` / `cornerRadius` | Box appearance, analogous to [`Panel`](/api/sun/panel#options) |
| `titleAlignX` / `titleAlignY` | Title position: `'left'`\|`'center'`\|`'right'` and `'top'`\|`'center'` |
| `buttonAlign` | Which side the expand/collapse button sits on: `'left'` (default) \| `'right'` |
| `showTitleWhenExpanded` | If `false`, the title is hidden once expanded and content is shown beside the button instead of below the title |
| `useExpandedBoundsWhenCollapsed` | If `true` (default), the collapsed box keeps the expanded box's width |
| `contentXMargin` / `contentYMargin` / `contentXSpacing` / `contentYSpacing` | Spacing around/between content, title, and button |
| `titleBarExpandCollapse` | Whether clicking the title bar (not just the button) toggles the box (default `true`) |

## Methods

| Method | Effect |
| --- | --- |
| `reset()` | Resets `expandedProperty` to its initial value (only meaningful if `AccordionBox` owns the Property, i.e. you used `expandedDefaultValue` rather than supplying your own) |
| `getExpandedBoxHeight()` / `getCollapsedBoxHeight()` | The ideal height in each state, ignoring stroke width |

::: warning `reset()` is a no-op if you supplied your own `expandedProperty`
If you pass `expandedProperty` explicitly, `AccordionBox.reset()` does nothing — you own that Property and are responsible for resetting it yourself (typically alongside your model's other Properties via `resetAllButton`). Only the internally-created Property (via `expandedDefaultValue`) is reset by `AccordionBox.reset()`.
:::


========================================================================
Page: AquaRadioButton
URL: https://veillette.github.io/Almanach/api/sun/aqua-radio-button
Source: docs/api/sun/aqua-radio-button.md
Category: API | Tags: sun, AquaRadioButton, RadioButtonGroup | Status: complete
========================================================================

# AquaRadioButton

`AquaRadioButton<T>` (from `scenerystack/sun`) is a single circular radio button styled after macOS' Aqua theme — a ring that fills with a dot when selected — paired with a label `Node` placed to its right. It's the individual button that [`AquaRadioButtonGroup`](/api/sun/aqua-radio-button-group) creates one of per item; you construct it directly only when you need a lone radio-style toggle outside of a managed group (a rare case — [`Checkbox`](/api/sun/checkbox) is almost always the better fit for a single boolean toggle). Compare with [`RectangularRadioButton`](/api/sun/rectangular-radio-button), the boxed equivalent used by `RectangularRadioButtonGroup`.

```ts
import { AquaRadioButton } from 'scenerystack/sun';
import { Text } from 'scenerystack/scenery';
import { Property } from 'scenerystack/axon';
import { Tandem } from 'scenerystack/tandem';

type Shape = 'circle' | 'square';
const shapeProperty = new Property<Shape>( 'circle' );

const circleButton = new AquaRadioButton( shapeProperty, 'circle', new Text( 'Circle' ), {
  tandem: Tandem.REQUIRED
} );
```

The constructor is `( property, value, labelNode, options? )` — `property` must use the default `'reference'` `valueComparisonStrategy` (`AquaRadioButton` compares with `===`), `value` is what gets written to `property` when this button fires, and `labelNode` is vertically centered to the right of the circle. Clicking anywhere on the button or its label sets `property.value = value`; the circle fills in automatically whenever `property.value === value`, from any source.

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `radius` | `7` | Radius of the circular button |
| `selectedColor` / `deselectedColor` | `'rgb( 143, 197, 250 )'` / `'white'` | Fill of the outer ring in each state |
| `centerColor` | `'black'` | Fill of the inner dot shown when selected |
| `stroke` | `'black'` | Stroke of the outer ring |
| `xSpacing` | `8` | Space between the button and `labelNode` |
| `soundPlayer` | first selection sound | Usually left to `AquaRadioButtonGroup`, which assigns one per index |
| `touchAreaXDilation` / `touchAreaYDilation` | `0` / `0` | Expand the touch hit area beyond the visual bounds |
| `a11yNameAttribute` | `null` | The shared `name` attribute the browser uses to group native radio inputs — set automatically by `AquaRadioButtonGroup` |

::: warning A lone `AquaRadioButton` isn't a complete radio group
A single `AquaRadioButton` fires and updates correctly on its own, but radio semantics (arrow-key navigation, mutual exclusivity across several buttons, a shared `a11yNameAttribute`) come from wrapping several of them in [`AquaRadioButtonGroup`](/api/sun/aqua-radio-button-group). If you're presenting more than one option, construct the group rather than several standalone `AquaRadioButton`s.
:::


========================================================================
Page: AquaRadioButtonGroup
URL: https://veillette.github.io/Almanach/api/sun/aqua-radio-button-group
Source: docs/api/sun/aqua-radio-button-group.md
Category: API | Tags: sun, AquaRadioButtonGroup, HorizontalAquaRadioButtonGroup, VerticalAquaRadioButtonGroup, RadioButtonGroup | Status: complete
========================================================================

# AquaRadioButtonGroup

`AquaRadioButtonGroup<T>` (from `scenerystack/sun`) lays out an [`AquaRadioButton`](/api/sun/aqua-radio-button) per item and manages selection, focus, and pointer areas as a group — this is the same class documented at a higher level on the [Radio Button Groups](/api/sun/radio-button-group) page; this page covers its API in more detail, plus its two orientation-fixing convenience subclasses.

```ts
import { AquaRadioButtonGroup, type AquaRadioButtonGroupItem } from 'scenerystack/sun';
import { Text } from 'scenerystack/scenery';
import { Property } from 'scenerystack/axon';
import { Tandem } from 'scenerystack/tandem';

type Shape = 'circle' | 'square';
const shapeProperty = new Property<Shape>( 'circle' );

const items: AquaRadioButtonGroupItem<Shape>[] = [
  { value: 'circle', createNode: () => new Text( 'Circle' ) },
  { value: 'square', createNode: () => new Text( 'Square' ) }
];

const shapeGroup = new AquaRadioButtonGroup( shapeProperty, items, {
  orientation: 'vertical', // the default
  tandem: Tandem.REQUIRED
} );
```

Each item's `createNode` builds the *label* shown beside the round button — not the button's own content, which `AquaRadioButtonGroup` always draws itself. The group extends `FlowBox`, so it lays out like an `HBox`/`VBox` depending on `orientation`.

## HorizontalAquaRadioButtonGroup / VerticalAquaRadioButtonGroup

Both are thin subclasses with the exact same `(property, items, options?)` constructor as `AquaRadioButtonGroup`, minus the `orientation` option (which they fix for you):

| Class | Fixes |
| --- | --- |
| `HorizontalAquaRadioButtonGroup` | `orientation: 'horizontal'` |
| `VerticalAquaRadioButtonGroup` | `orientation: 'vertical'`, `align: 'left'` |
| `AquaRadioButtonGroup` | Neither — `orientation` defaults to `'vertical'` but can be set explicitly |

```ts
import { VerticalAquaRadioButtonGroup } from 'scenerystack/sun';

const verticalGroup = new VerticalAquaRadioButtonGroup( shapeProperty, items, {
  tandem: Tandem.REQUIRED
} );
```

Reach for the orientation-fixed subclasses for an ordinary fixed-layout group — they read more clearly and remove one option you'd otherwise remember to set; use `AquaRadioButtonGroup` directly when orientation needs to vary at runtime or your code is generic over it.

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `orientation` | `'vertical'` | `'horizontal'` or `'vertical'` layout (fixed on the two subclasses) |
| `spacing` | `3` | Space between adjacent buttons |
| `radioButtonOptions` | — | Options applied to every individual `AquaRadioButton` (`radius`, `selectedColor`, `xSpacing`, …) |
| `touchAreaXDilation` / `touchAreaYDilation` | `0` / `0` | Dilation for each button's touch area (X ignored when horizontal, Y ignored when vertical) |
| `mouseAreaXDilation` / `mouseAreaYDilation` | `0` / `0` | Same, for mouse areas |
| `voicingHintResponse` | `null` | Spoken the first time focus lands in the group; falls back to `accessibleHelpText` |

Every item requires a unique `value`, and the group asserts that `property.value` matches one of the supplied items' values at construction — there is no "nothing selected" state.

## Methods

| Method | Effect |
| --- | --- |
| `getButton( value: T )` | Returns the `AquaRadioButton<T>` instance for a given value |

::: tip Choosing between Aqua and rectangular groups
Use `AquaRadioButtonGroup` for a traditional list of labeled options (settings panels, a vertical list of choices); use [`RectangularRadioButtonGroup`](/api/sun/radio-button-group) when the options are best shown as boxed buttons — icons or short labels the user clicks directly. See the [Radio Button Groups](/api/sun/radio-button-group) overview for the full comparison.
:::


========================================================================
Page: ArrowButton
URL: https://veillette.github.io/Almanach/api/sun/arrow-button
Source: docs/api/sun/arrow-button.md
Category: API | Tags: sun, ArrowButton, button | Status: complete
========================================================================

# ArrowButton

`ArrowButton` (from `scenerystack/sun`) is a thin subclass of [`RectangularPushButton`](/api/sun/rectangular-push-button) whose `content` is generated for you: a triangular arrow pointing `'up'`, `'down'`, `'left'`, or `'right'`. It's the button [`NumberSpinner`](/api/sun/number-spinner) uses internally for its increment/decrement controls, and it's a reasonable choice any time you need a standalone "step" control with an arrow glyph rather than building your own `Path` and wiring it into `RectangularPushButton` yourself.

```ts
import { ArrowButton } from 'scenerystack/sun';
import { Tandem } from 'scenerystack/tandem';

const incrementButton = new ArrowButton(
  'right',
  () => {
    model.value += 1;
  },
  {
    tandem: Tandem.REQUIRED
  }
);
```

The constructor takes the direction and the fire callback directly (not through a `listener` option — `ArrowButton` sets `options.listener` internally, so `content` and `listener` are omitted from `ArrowButtonOptions`). Unlike a plain `RectangularPushButton`, `ArrowButton` enables `fireOnHold` by default, so press-and-hold repeats the action automatically.

## Options

`ArrowButtonOptions` combines its own arrow-drawing options with `RectangularPushButtonOptions` (minus `content`/`listener`, which `ArrowButton` supplies):

| Option | Default | Effect |
| --- | --- | --- |
| `arrowHeight` | `20` | Arrow size from tip to base |
| `arrowWidth` | `arrowHeight * √3 / 2` | Width of the arrow's base |
| `arrowFill` / `arrowStroke` / `arrowLineWidth` | `'black'` / `null` / `1` | Styling of the arrow `Path` |
| `numberOfArrows` | `1` | Draws several overlapping arrows (a ">>" fast-forward look) instead of one |
| `arrowSpacing` | `-arrowHeight / 2` | Offset between stacked arrows when `numberOfArrows > 1` |
| `fireOnHold` | `true` | Press-and-hold repeat firing is on by default (opposite of `RectangularPushButton`) |
| `fireOnHoldDelay` / `fireOnHoldInterval` | `400` / `100` | Timing (ms) for the repeat firing |
| `cornerRadius` | `4` | Smaller default than the general-purpose rectangular button |
| `touchAreaXDilation` / `touchAreaYDilation` | `7` / `7` | Expand the touch hit area beyond the small visual button |

::: tip Pass the direction and callback positionally, not as options
`ArrowButton`'s constructor is `new ArrowButton( direction, callback, options? )` — `direction` and the fire callback aren't part of the options object the way `listener` is for `RectangularPushButton`.
:::


========================================================================
Page: Carousel
URL: https://veillette.github.io/Almanach/api/sun/carousel
Source: docs/api/sun/carousel.md
Category: API | Tags: sun, Carousel, layout | Status: verified
========================================================================

# Carousel

`Carousel` (from `scenerystack/sun`) divides a set of `CarouselItem`s into pages — however many fit per page, given `itemsPerPage` — and lets the user page through them with animated next/previous buttons. Use it when you have more choices than comfortably fit in one row/column but still want them all visually browsable, rather than hidden behind a [`ComboBox`](/api/sun/combo-box)'s dropdown.

```ts
import { Carousel, type CarouselItem } from 'scenerystack/sun';
import { Text } from 'scenerystack/scenery';
import { Tandem } from 'scenerystack/tandem';

const items: CarouselItem[] = [
  { createNode: () => new Text( 'Apple' ) },
  { createNode: () => new Text( 'Banana' ) },
  { createNode: () => new Text( 'Cherry' ) },
  { createNode: () => new Text( 'Date' ) },
  { createNode: () => new Text( 'Elderberry' ) }
];

const fruitCarousel = new Carousel( items, {
  itemsPerPage: 3,
  orientation: 'horizontal',
  tandem: Tandem.REQUIRED
} );
```

Each `CarouselItem` supplies a `createNode` factory (like `ComboBoxItem`), not a pre-built `Node` — `Carousel` wraps every created item Node in an `AlignBox` so all items share a uniform "footprint," regardless of their individual sizes.

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `orientation` | `'horizontal'` | `'horizontal'` (paged left-right) or `'vertical'` (paged top-bottom) |
| `itemsPerPage` | `4` | How many items are visible per page |
| `defaultPageNumber` | `0` | Page shown initially |
| `spacing` / `margin` | `12` / `6` | Space between items (and between items and buttons) / space between items and the carousel's edge |
| `fill` / `stroke` / `lineWidth` / `cornerRadius` | `'white'` / `'black'` / `1` / `4` | Carousel background appearance |
| `buttonOptions` | — | Options forwarded to the next/previous `CarouselButton`s |
| `separatorsVisible` | `false` | Draw a separator line between adjacent items |
| `animationEnabled` | `true` | Whether page changes scroll smoothly; `false` jumps instantly |
| `animationOptions` | `{ duration: 0.4, easing: Easing.CUBIC_IN_OUT }` | Tuning for the scroll animation |

## Methods

| Method | Effect |
| --- | --- |
| `reset( animationEnabled? )` | Returns to `defaultPageNumber`; pass `true` to animate the reset (default `false`, i.e. instant) |
| `scrollToItem( item: CarouselItem )` | Pages to whichever page contains `item`, if it's currently visible |
| `setItemVisible( item, visible )` | Shows/hides one item; the layout reflows so hidden items don't leave a gap |
| `getNodeForItem( item: CarouselItem )` | Returns the `Node` that was created for a given item |

Public read-only state: `pageNumberProperty` (current page) and `numberOfPagesProperty` (derived from visible item count and `itemsPerPage`).

::: warning Disposing a Carousel disposes its item Nodes
`Carousel.dispose()` also disposes every `Node` that `createNode` produced for its items — don't hold onto references to those Nodes expecting them to survive the carousel's disposal, and don't pass in Nodes you need to reuse elsewhere afterward.
:::


========================================================================
Page: CarouselButton
URL: https://veillette.github.io/Almanach/api/sun/carousel-button
Source: docs/api/sun/carousel-button.md
Category: API | Tags: sun, CarouselButton, Carousel, button | Status: complete
========================================================================

# CarouselButton

`CarouselButton` (from `scenerystack/sun`) is the arrow button [`Carousel`](/api/sun/carousel) creates for its next/previous controls — a `RectangularPushButton` subclass whose content is an arrow `Path`, styled flat (semi-transparent gray, `ButtonNode.FlatAppearanceStrategy`) so it reads as part of the carousel's frame rather than as a standalone button. You'll rarely construct one directly; it's documented here because `Carousel`'s `buttonOptions` is typed as `CarouselButtonOptions`, and you may want to know what you're actually configuring when you pass options through.

```ts
import { Carousel, type CarouselItem } from 'scenerystack/sun';
import { Text } from 'scenerystack/scenery';
import { Dimension2 } from 'scenerystack/dot';
import { Tandem } from 'scenerystack/tandem';

const items: CarouselItem[] = [
  { createNode: () => new Text( 'A' ) },
  { createNode: () => new Text( 'B' ) },
  { createNode: () => new Text( 'C' ) }
];

const carousel = new Carousel( items, {
  itemsPerPage: 2,
  // Forwarded straight through to the two CarouselButtons Carousel creates.
  buttonOptions: {
    baseColor: 'rgb( 220, 220, 220 )',
    arrowSize: new Dimension2( 16, 6 )
  },
  tandem: Tandem.REQUIRED
} );
```

::: tip In practice, configure it through `Carousel`'s `buttonOptions`
The snippet above imports `CarouselButton` only conceptually — you rarely instantiate it yourself. `Carousel` creates two internally (previous/next), passing your `buttonOptions` through to both while filling in `arrowDirection` itself based on `orientation`.
:::

## Options

`CarouselButtonOptions` is `RectangularPushButtonOptions` (minus `content`, corner-radius-per-corner options, and pointer-area shift options, which `CarouselButton` computes itself) plus:

| Option | Default | Effect |
| --- | --- | --- |
| `arrowDirection` | `'up'` | `'up'` \| `'down'` \| `'left'` \| `'right'` — `Carousel` sets this for you based on `orientation` and which button (previous/next) it is |
| `arrowSize` | `Dimension2( 20, 7 )` | Size of the arrow when pointing up, before rotation |
| `arrowPathOptions` | `{ stroke: 'black', lineWidth: 3, lineCap: 'round' }` | Styling of the arrow shape itself |

`CarouselButton` also derives its corner radii automatically: whichever corners face "outward" (away from the carousel's item area) get `cornerRadius`, and the inward-facing corners are square — so the two buttons look like they belong to the carousel's rounded frame rather than being independently rounded rectangles. It similarly halves and shifts touch/mouse area dilation on the inward side, so the buttons' hit targets don't overlap the carousel's scrollable content.

::: warning Corner-radius and pointer-shift options are computed, not settable
`CarouselButtonOptions` omits `leftTopCornerRadius`/etc. and `touchAreaXShift`/etc. from `RectangularPushButtonOptions` for exactly this reason — `CarouselButton` needs to control them itself based on `arrowDirection` to keep the "belongs to the frame" look consistent.
:::


========================================================================
Page: CarouselComboBox
URL: https://veillette.github.io/Almanach/api/sun/carousel-combo-box
Source: docs/api/sun/carousel-combo-box.md
Category: API | Tags: sun, CarouselComboBox, ComboBox, Carousel, PageControl | Status: complete
========================================================================

# CarouselComboBox

`CarouselComboBox<T>` (from `scenerystack/sun`) behaves like [`ComboBox`](/api/sun/combo-box) from the outside — a button showing the current selection, bound to a `Property<T>` over a fixed set of `ComboBoxItem<T>`s — but its popup is a [`Carousel`](/api/sun/carousel) with a [`PageControl`](/api/sun/page-control) instead of a scrolling list box. `ComboBox`'s own list box has no pagination, so once an item list gets long enough that it would overflow the screen, `CarouselComboBox` lets users page through it instead.

```ts
import { CarouselComboBox, type ComboBoxItem } from 'scenerystack/sun';
import { Text } from 'scenerystack/scenery';
import { Property } from 'scenerystack/axon';
import { Tandem } from 'scenerystack/tandem';

type Element = 'hydrogen' | 'helium' | 'lithium' | 'beryllium' | 'boron' | 'carbon';
const elementProperty = new Property<Element>( 'hydrogen' );

const items: ComboBoxItem<Element>[] = [
  { value: 'hydrogen', createNode: () => new Text( 'Hydrogen' ) },
  { value: 'helium', createNode: () => new Text( 'Helium' ) },
  { value: 'lithium', createNode: () => new Text( 'Lithium' ) },
  { value: 'beryllium', createNode: () => new Text( 'Beryllium' ) },
  { value: 'boron', createNode: () => new Text( 'Boron' ) },
  { value: 'carbon', createNode: () => new Text( 'Carbon' ) }
];

const elementComboBox = new CarouselComboBox( elementProperty, items, {
  carouselOptions: { itemsPerPage: 4 },
  tandem: Tandem.REQUIRED
} );
```

Unlike `ComboBox`, `CarouselComboBox` needs no separate `listParent` argument — the carousel pops open as a sibling `Node` inside `CarouselComboBox` itself, toggled visible/invisible by the button, rather than being added to an ancestor near the top of the scene graph.

::: warning "Think twice before using this in a sim"
That's a direct warning from the SceneryStack source: `CarouselComboBox` was built to solve internal demo apps with dozens of options, and PhET's own design guidance is to avoid long option lists in real sims. If you're reaching for `CarouselComboBox`, first consider whether a [radio button group](/api/sun/radio-button-group), a shorter list, or restructuring the UI would give users a better experience than paging through a dropdown.
:::

## Options

| Option | Effect |
| --- | --- |
| `itemNodeOptions` | Passed to each carousel item's wrapper: `align`, `xMargin`/`yMargin`, `overColor` (pointer-over background), `selectedColor` (selected-item background) |
| `carouselOptions` | Forwarded to the internal `Carousel`; `orientation` must stay `'vertical'` (the only orientation supported) and defaults `itemsPerPage` to `15`, capped at the number of items |
| `pageControlOptions` | Forwarded to the internal `PageControl` (only created if there's more than one page); defaults `interactive: true` |
| `buttonOptions` | Forwarded to the internal `ComboBoxButton`; `arrowDirection` must stay `'down'` |
| `openedSoundPlayer` / `closedSoundPlayer` | Sounds played when the carousel is shown/hidden |

::: tip Same `ComboBoxItem<T>` shape as `ComboBox`
`CarouselComboBox` reuses `ComboBoxItem<T>` (`{ value, createNode, ... }`) directly — if you already have items defined for a `ComboBox`, they work unchanged here; only the container around them differs.
:::


========================================================================
Page: Checkbox
URL: https://veillette.github.io/Almanach/api/sun/checkbox
Source: docs/api/sun/checkbox.md
Category: API | Tags: sun, Checkbox, BooleanProperty | Status: verified
========================================================================

# Checkbox

`Checkbox` (from `scenerystack/sun`) is a standard checkbox bound to a `PhetioProperty<boolean>`, composed with an arbitrary `Node` as its label — there's no separate "checkbox label" string option, you pass any `Node` (typically a `Text`) as the `content` argument and `Checkbox` lays it out next to the box.

```ts
import { Checkbox } from 'scenerystack/sun';
import { Text } from 'scenerystack/scenery';
import { BooleanProperty } from 'scenerystack/axon';
import { Tandem } from 'scenerystack/tandem';

const gravityEnabledProperty = new BooleanProperty( true );

const gravityCheckbox = new Checkbox(
  gravityEnabledProperty,
  new Text( 'Gravity' ),
  { tandem: Tandem.REQUIRED }
);
```

<SceneryDemo demo="checkbox" />

Clicking anywhere on the checkbox (box or label) toggles `gravityEnabledProperty.value`; the box updates to reflect the Property whenever it changes, from any source.

## Options

| Option | Effect |
| --- | --- |
| `spacing` | Space between the box and `content` (default `5`) |
| `boxWidth` | Width/height of the box itself (default `21`) |
| `checkboxColor` | Color of the check mark and empty-box outline |
| `checkboxColorBackground` | Fill behind the check mark |
| `touchAreaXDilation` / `touchAreaYDilation` | Expand the touch hit area beyond the visual bounds |
| `checkedSoundPlayer` / `uncheckedSoundPlayer` | Sounds played on each transition |
| `enabledProperty` | Externally control interactivity |

```ts
const checkbox = new Checkbox( gravityEnabledProperty, new Text( 'Gravity' ), {
  boxWidth: 16,
  checkboxColor: 'blue',
  touchAreaXDilation: 6,
  touchAreaYDilation: 6,
  tandem: Tandem.REQUIRED
} );
```

::: tip `accessibleName` is inferred from your label
If `content` is (or contains) a `Text`/string-backed Node and you don't set `accessibleName` explicitly, `Checkbox` finds the label's string automatically for the accessible name — you usually don't need to duplicate the label text into `accessibleName` yourself.
:::

::: warning Don't decorate a `Checkbox` with extra children
`Checkbox`'s internal layout constraint manages exactly three children (the box, your `content`, and an invisible hit-target rectangle). Adding further children directly to the `Checkbox` instance breaks its layout and is explicitly disallowed — put anything else you need in a sibling `Node`, not inside the checkbox itself.
:::


========================================================================
Page: ColorConstants and SunConstants
URL: https://veillette.github.io/Almanach/api/sun/color-constants
Source: docs/api/sun/color-constants.md
Category: API | Tags: sun, ColorConstants, SunConstants | Status: complete
========================================================================

# ColorConstants and SunConstants

`ColorConstants` and `SunConstants` (both from `scenerystack/sun`) are small plain-object modules of shared default values reused across `scenerystack/sun` components — mainly so a handful of default colors and magic numbers exist in exactly one place rather than being copy-pasted into every button/slider/spinner that needs them. Neither is a class; both are `readonly`-style constant objects you read values from directly.

```ts
import { ColorConstants, SunConstants } from 'scenerystack/sun';
import { RectangularPushButton } from 'scenerystack/sun';

// Matches the default look of PhET's boxed buttons/radio buttons
const button = new RectangularPushButton( {
  baseColor: ColorConstants.LIGHT_BLUE
} );

console.log( SunConstants.VALUE_NAMED_PLACEHOLDER ); // '{{value}}'
```

## ColorConstants

| Constant | Value | Used for |
| --- | --- | --- |
| `LIGHT_BLUE` | `new Color( 153, 206, 255 )` | The default `baseColor` for most `scenerystack/sun` buttons, including [`RectangularRadioButton`](/api/sun/rectangular-radio-button) |
| `LIGHT_GRAY` | `new Color( 220, 220, 220 )` | The conventional "disabled" fill color used in several components |

Both are `Color` instances (from `scenerystack/scenery`), so they support the usual `Color` methods (`brighterColor`, `darkerColor`, `withAlpha`, …) if you want a variant rather than the exact default.

## SunConstants

| Constant | Value | Used for |
| --- | --- | --- |
| `VALUE_NAMED_PLACEHOLDER` | `'{{value}}'` | The named placeholder convention for value-substitution string patterns (used with `StringUtils.fillIn`), e.g. in a `NumberDisplay`'s format string |
| `VALUE_NUMBERED_PLACEHOLDER` | `'{0}'` | The older numbered-placeholder convention (used with `StringUtils.format`); **deprecated** — prefer named placeholders in new code |
| `SLIDER_VERTICAL_ROTATION` | `-Math.PI / 2` | The rotation angle [`Slider`](/api/sun/slider) applies internally to lay out a vertical slider using the same horizontal-authored geometry |

::: tip These are defaults, not requirements
Nothing forces you to use `ColorConstants.LIGHT_BLUE` or `SunConstants.VALUE_NAMED_PLACEHOLDER` — components fall back to them only when you don't supply your own `baseColor`/format string. They're documented here mainly so custom components can match PhET's conventional look-and-feel intentionally, rather than by guessing at hardcoded hex values.
:::


========================================================================
Page: ComboBox
URL: https://veillette.github.io/Almanach/api/sun/combo-box
Source: docs/api/sun/combo-box.md
Category: API | Tags: sun, ComboBox | Status: verified
========================================================================

# ComboBox

::: tip Scope: start here for dropdown selectors
This page documents the `ComboBox` control simulation authors use. The internal popup list (`ComboBoxListBox`) is documented separately in [ComboBoxListBox](/api/sun/list-box) only because understanding what backs the dropdown clarifies which options belong on `ComboBox` versus the list it constructs internally.
:::

`ComboBox` (from `scenerystack/sun`) is a dropdown selector: a button showing the current selection, which opens a popup list box of items when pressed. It's bound to a settable `Property<T>` over a fixed, enumerated set of values — reach for it instead of a [radio button group](/api/sun/radio-button-group) when there are too many options (or too little screen space) to show them all at once.

```ts
import { ComboBox, type ComboBoxItem } from 'scenerystack/sun';
import { Text, Node } from 'scenerystack/scenery';
import { Property } from 'scenerystack/axon';
import { Tandem } from 'scenerystack/tandem';

type Units = 'meters' | 'feet';
const unitsProperty = new Property<Units>( 'meters' );

// The list box pops up above this Node, so it renders in front of everything else.
const listParent = new Node();

const items: ComboBoxItem<Units>[] = [
  { value: 'meters', createNode: () => new Text( 'meters' ) },
  { value: 'feet', createNode: () => new Text( 'feet' ) }
];

const unitsComboBox = new ComboBox( unitsProperty, items, listParent, {
  tandem: Tandem.REQUIRED
} );

// listParent must be added to the scene graph as an ancestor of unitsComboBox,
// typically near the top of the ScreenView so the popup list isn't clipped.
screenView.addChild( unitsComboBox );
screenView.addChild( listParent );
```

## Constructor arguments

| Argument | Effect |
| --- | --- |
| `property` | The settable `Property<T>` whose value the combo box displays and controls |
| `items` | `ComboBoxItem<T>[]` — `{ value, createNode, tandemName?, accessibleName?, soundPlayer? }`, in the order they appear in the list |
| `listParent` | The `Node` the popup list box is added to; give it an ancestor high enough in the scene graph that the list isn't clipped or drawn behind other content |

## Options

| Option | Effect |
| --- | --- |
| `listPosition` | `'above'` or `'below'` the button (default `'below'`) |
| `align` | `'left'` \| `'right'` \| `'center'` alignment of each item within the button/list |
| `buttonFill` / `buttonStroke` | Button appearance |
| `listFill` / `listStroke` | List box appearance |
| `highlightFill` | Highlight shown behind the item under the pointer |
| `cornerRadius` | Applied to both button and list box |
| `xMargin` / `yMargin` | Margins around content in the button and list |
| `buttonTouchAreaXDilation` / `buttonTouchAreaYDilation` | Expand the button's touch hit area |

::: warning `createNode`, not a shared `node`
Each `ComboBoxItem` supplies a `createNode: ( tandem ) => Node` factory, not a pre-built `Node` instance — `ComboBox` calls it once per item to create the Node actually placed in the list. This lets the same item description be reused safely and lets each item's Node be tandem-instrumented individually.
:::


========================================================================
Page: ComboBoxListBox
URL: https://veillette.github.io/Almanach/api/sun/list-box
Source: docs/api/sun/list-box.md
Category: API | Tags: sun, ComboBoxListBox, ComboBox, listbox | Status: verified
========================================================================

# ComboBoxListBox

::: tip Scope: internal popup machinery for ComboBox
This page documents `ComboBoxListBox`, the popup `Panel` [`ComboBox`](/api/sun/combo-box) constructs internally — not a standalone widget. Start with [ComboBox](/api/sun/combo-box) unless you need to understand which options are forwarded into the list box.
:::

There's no standalone `ListBox` export in `scenerystack/sun` — the real class is `ComboBoxListBox<T>`, and it's the popup `Panel` subclass that [`ComboBox`](/api/sun/combo-box) constructs internally to hold its items when the dropdown is open. `ComboBox`'s constructor builds one `ComboBoxListBox` from the same `items`/`property` you pass it and stores it as a private field; you never construct a `ComboBoxListBox` yourself in application code — it's documented here because understanding what backs the dropdown clarifies which options actually belong to `ComboBox` versus the list box it delegates to.

```ts
import { ComboBox } from 'scenerystack/sun';

// You interact with ComboBox directly; ComboBoxListBox is what appears
// when the user presses the button, built internally from the same items.
const unitsComboBox = new ComboBox( unitsProperty, items, listParent, {
  tandem: Tandem.REQUIRED
} );
```

Structurally, `ComboBoxListBox` extends [`Panel`](/api/sun/panel) — the list of items is a `VBox` of `ComboBoxListItemNode`s, wrapped in the same rounded-rectangle background `Panel` provides elsewhere in `sun`. It handles its own keyboard navigation (arrow keys move focus between visible items, `Home`/`End` jump to the first/last, `Escape`/`Tab` close the list and return focus to the combo box's button) and its own opened/closed/selection sound generation.

## Options that flow through from ComboBox

`ComboBox` forwards several of its own options straight into the `ComboBoxListBox` it creates — these are documented as `ComboBox` options (see [ComboBox's Options](/api/sun/combo-box#options)) but are actually consumed here:

| Option (on `ComboBox`) | Effect on the list box |
| --- | --- |
| `listFill` / `listStroke` | The list box `Panel`'s background/border |
| `highlightFill` | Fill behind the item under the pointer or keyboard focus |
| `xMargin` / `yMargin` | Margin between items and the list box edge (`ComboBoxListBox` halves these to account for highlight overlap) |
| `cornerRadius` | Rounding applied to both the list box and the highlight behind each item |

## Why it isn't instrumented for PhET-iO

`ComboBoxListBox` is deliberately not given its own PhET-iO instrumentation — its position in the scene graph isn't meaningful until it's actually popped up, so instrumenting it would expose state that's only valid while the dropdown happens to be open. `ComboBox` itself, and the `Property` it controls, are the instrumented surface; the list box is treated as transient view machinery underneath them.

::: warning Not a general-purpose "list of items" widget
Because `ComboBoxListBox` is constructed by `ComboBox` with callbacks (`hideListBoxCallback`, `focusButtonCallback`) tightly coupled to a specific combo box instance, it isn't designed to be reused as a standalone scrollable list elsewhere. If you need a freestanding selectable list independent of a dropdown button, compose your own `VBox` of pressable items rather than trying to repurpose `ComboBoxListBox`.
:::


========================================================================
Page: ExpandCollapseButton
URL: https://veillette.github.io/Almanach/api/sun/expand-collapse-button
Source: docs/api/sun/expand-collapse-button.md
Category: API | Tags: sun, ExpandCollapseButton, button | Status: verified
========================================================================

# ExpandCollapseButton

`ExpandCollapseButton` (from `scenerystack/sun`) is a small square button that shows a `+` or `-` symbol and toggles a `Property<boolean>` — it's a thin, specialized wrapper around [`BooleanRectangularToggleButton`](/api/sun/toggle-button) with the plus/minus content, coloring (green when collapsed, orange when expanded), and `aria-expanded` PDOM attribute built in. [`AccordionBox`](/api/sun/accordion-box) constructs one of these internally for its own expand/collapse control (via its `expandCollapseButtonOptions`) — reach for `ExpandCollapseButton` directly only when you want that exact plus/minus affordance somewhere other than an `AccordionBox` title bar.

```ts
import { ExpandCollapseButton } from 'scenerystack/sun';
import { BooleanProperty } from 'scenerystack/axon';
import { Tandem } from 'scenerystack/tandem';

const detailsExpandedProperty = new BooleanProperty( false );

const detailsButton = new ExpandCollapseButton( detailsExpandedProperty, {
  sideLength: 20,
  tandem: Tandem.REQUIRED
} );
```

Pressing the button flips `detailsExpandedProperty.value`; the button's fill and `+`/`-` symbol update automatically, from any source that changes the Property, not just from a button press.

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `sideLength` | `25` | Length of one side of the square button; the `+`/`-` symbol and margins scale proportionally |
| `touchAreaXDilation` / `touchAreaYDilation` | `5` / `5` | Expand the touch-friendly hit area beyond the visual bounds |
| `stroke` | `'black'` | Outline color of the square button |

`ExpandCollapseButtonOptions` otherwise accepts the same `BooleanRectangularToggleButtonOptions` as documented in [Toggle Buttons](/api/sun/toggle-button#options), minus `cornerRadius`/`xMargin`/`yMargin`/`buttonAppearanceStrategy` — those four are fixed internally so the plus/minus symbol always renders correctly relative to `sideLength`.

::: tip It's exactly what `AccordionBox` uses under the hood
If you're building a custom expandable panel that isn't quite an `AccordionBox` (e.g. different layout for the title/content), you can drop in an `ExpandCollapseButton` bound to your own `expandedProperty` and get the same visual language users already recognize from every `AccordionBox` in the sim, without reimplementing the plus/minus icon yourself.
:::


========================================================================
Page: HSlider
URL: https://veillette.github.io/Almanach/api/sun/hslider
Source: docs/api/sun/hslider.md
Category: API | Tags: sun, HSlider, slider | Status: verified
========================================================================

# HSlider

`HSlider` (from `scenerystack/sun`) is a horizontal slider bound to a numeric `Property` and a `Range` — dragging the thumb (or clicking the track) sets `valueProperty.value`, clamped to the range, and the thumb's position updates automatically if the value or range changes elsewhere. `HSlider` is a thin convenience wrapper around the more general `Slider` (which also supports a vertical orientation via `VSlider`) that always fixes `orientation: Orientation.HORIZONTAL`.

```ts
import { HSlider } from 'scenerystack/sun';
import { NumberProperty } from 'scenerystack/axon';
import { Range } from 'scenerystack/dot';
import { Tandem } from 'scenerystack/tandem';

const temperatureProperty = new NumberProperty( 20, {
  range: new Range( 0, 100 )
} );

const slider = new HSlider( temperatureProperty, new Range( 0, 100 ), {
  tandem: Tandem.REQUIRED
} );
```

<SceneryDemo demo="hslider" />

The `Range` passed to the constructor is the *track's* full range; pass a `Property<Range>` instead of a plain `Range` if you want the enabled portion of the track to change dynamically without moving the track's endpoints (see `enabledRangeProperty`, below).

## Options

`HSliderOptions` is `SliderOptions` with `orientation` removed (it's always horizontal). The ones you'll reach for most:

| Option | Effect |
| --- | --- |
| `trackSize` | `Dimension2` for the track (default `100 x 5`) |
| `thumbSize` | `Dimension2` for the default thumb (default `17 x 34`) |
| `thumbFill` / `thumbFillHighlighted` | Thumb color, normal and pointer-over |
| `trackFillEnabled` / `trackFillDisabled` | Track color in each enabled state |
| `constrainValue` | `( value: number ) => number`, e.g. to snap to a grid before the value is set |
| `enabledRangeProperty` | A `Property<Range>` narrower than the full track range — lets you shrink the interactive range (e.g. disable values above a threshold) without moving the track |
| `trackNode` / `thumbNode` | Fully custom track/thumb `Node`s, replacing the defaults |
| `startDrag` / `drag` / `endDrag` | Hooks into the drag lifecycle |

## Adding tick marks

```ts
slider.addMajorTick( 0, new Text( '0°' ) );
slider.addMajorTick( 100, new Text( '100°' ) );
slider.addMinorTick( 50 );
```

| Method | Effect |
| --- | --- |
| `addMajorTick( value, label? )` | Adds a labeled tick mark, longer stroke |
| `addMinorTick( value, label? )` | Adds an unlabeled (by default) tick mark, shorter stroke |
| `setMajorTicksVisible( visible )` / `setMinorTicksVisible( visible )` | Toggle tick visibility |

::: warning The value clamps to `enabledRangeProperty`, not just the constructor `Range`
If you never touch `enabledRangeProperty`, it defaults to the full `Range` you passed in and behaves as you'd expect. But if you narrow `enabledRangeProperty` later (e.g. to lock the slider above some model-dependent value), the *track* stays the same visual length — only the interactive/enabled portion shrinks, and `valueProperty` is clamped into the new enabled range immediately.
:::


========================================================================
Page: MenuItem
URL: https://veillette.github.io/Almanach/api/sun/menu-item
Source: docs/api/sun/menu-item.md
Category: API | Tags: sun, MenuItem, FireListener, Voicing | Status: complete
========================================================================

# MenuItem

`MenuItem` (from `scenerystack/sun`) is a single row used by PhET's built-in `PhetMenu` (the "hamburger" options menu every published sim has) — a label, a hover highlight, an optional checkmark, and a [`FireListener`](/api/scenery/fire-listener) that closes the menu and runs a callback. It's documented here because it's exported from `scenerystack/sun` and usable on its own if you're building a custom popup menu that should look and behave consistently with PhET's, not because most sim code constructs `PhetMenu` items directly.

```ts
import { MenuItem } from 'scenerystack/sun';
import { Property, StringProperty } from 'scenerystack/axon';

const closeMyMenu = () => { myMenuPopup.visible = false; };

const soundEnabledProperty = new Property<boolean>( true );
const labelStringProperty = new StringProperty( 'Enable Sound' );

const soundMenuItem = new MenuItem(
  event => closeMyMenu(),               // closeCallback
  labelStringProperty,                  // labelStringProperty
  event => {                            // callback, run after closeCallback
    soundEnabledProperty.value = !soundEnabledProperty.value;
  },
  true,                                  // present
  false,                                 // shouldBeHiddenWhenLinksAreNotAllowed
  {
    checkedProperty: soundEnabledProperty
  }
);
```

The constructor is positional and PhET-menu-specific: `closeCallback` runs first (typically hiding the menu popup), then `callback` runs the item's actual action. `present` lets a menu build a consistent, fixed set of `MenuItem`s across runtimes while hiding ones that don't apply in a given context (rather than conditionally omitting them, which would change PhET-iO's API shape). `shouldBeHiddenWhenLinksAreNotAllowed` ties the item's `visibleProperty` to `scenerystack/scenery`'s `allowLinksProperty`, for items whose action is a link that some embedding contexts must suppress.

## Options

| Option | Effect |
| --- | --- |
| `separatorBefore` | Draws a horizontal rule between this item and the previous one |
| `checkedProperty` | If provided, shows/hides a checkmark to the left of the label based on this `boolean` Property |
| `textFill` | Fill for the label `Text` (default `'black'`) |

`MenuItem` mixes in [`WidthSizable`](/api/scenery/sizable-mixins), so its highlight rectangle stretches to fill whatever `localPreferredWidth` a parent layout container assigns it — every item in a menu ends up the same width even though their labels differ.

::: tip Read as a `Voicing`-enabled `Node` for accessibility, not a bespoke widget
`MenuItem` extends `WidthSizable( Voicing( Node ) )`, using the exact same [Voicing](/api/scenery/voicing) mixin pattern as other interactive `sun`/`scenery` components — its `voicingNameResponse` is kept in sync with the label string automatically, so you don't need to set it by hand if you reuse `MenuItem` in your own popup.
:::


========================================================================
Page: Momentary Buttons
URL: https://veillette.github.io/Almanach/api/sun/momentary-button
Source: docs/api/sun/momentary-button.md
Category: API | Tags: sun, RectangularMomentaryButton, RoundMomentaryButton, MomentaryButtonModel, button | Status: complete
========================================================================

# Momentary Buttons

A momentary button sets a bound `Property<T>` to `valueOn` while the pointer holds it down, and back to `valueOff` the instant it's released — unlike [Sticky Toggle Buttons](/api/sun/sticky-toggle-button), it never latches. `scenerystack/sun` exports `RectangularMomentaryButton<T>` and `RoundMomentaryButton<T>`, both built on the shared `MomentaryButtonModel<T>`. Reach for these for "hold to activate" controls — a horn, a temporary boost, a press-and-hold camera shutter — where releasing should immediately undo the effect.

```ts
import { RectangularMomentaryButton } from 'scenerystack/sun';
import { Text } from 'scenerystack/scenery';
import { Property } from 'scenerystack/axon';
import { Tandem } from 'scenerystack/tandem';

const hornStateProperty = new Property<'off' | 'on'>( 'off' );

const hornButton = new RectangularMomentaryButton(
  hornStateProperty,
  'off', // valueOff
  'on',  // valueOn
  {
    content: new Text( 'Horn' ),
    baseColor: 'orange',
    tandem: Tandem.REQUIRED
  }
);
```

`RoundMomentaryButton` has the identical `(property, valueOff, valueOn, options?)` constructor — only the button shape differs, same as `RoundPushButton`/`RectangularPushButton`.

## `MomentaryButtonModel`

Both classes construct a `MomentaryButtonModel<T>` internally, the non-visual model (extending the shared `ButtonModel` base documented on [PushButtonModel](/api/sun/push-button-model), not `PushButtonModel` itself) that owns the on/off logic: `downProperty` transitioning to `true` sets `valueProperty` to `valueOn`; transitioning to `false` sets it back to `valueOff`. For alternative-input (keyboard/switch) activation, it behaves like a toggle instead — one activation turns it on, the next turns it off — and it always reverts to `valueOff` if the button loses focus while on.

`Property.valueComparisonStrategy` must be `'reference'` (the default) for the bound Property, since the model compares `valueProperty.value` against `valueOn`/`valueOff` with `===`.

## Options

Both classes accept the same appearance options as their non-momentary counterparts ([`RectangularButtonOptions`](/api/sun/rectangular-button#options) / [`RoundButtonOptions`](/api/sun/round-button#options)) plus:

| Option | Effect |
| --- | --- |
| `valueOffSoundPlayer` | Sound played when the button releases back to `valueOff` (default: shared `'toggleOff'` player) |
| `valueOnSoundPlayer` | Sound played when the button is pressed to `valueOn` (default: shared `'toggleOn'` player) |
| `accessibleContextResponseValueOn` / `accessibleContextResponseValueOff` | Alertable spoken/announced content for each transition |

::: warning Momentary buttons render `aria-pressed`, not a toggle-switch semantic
Both classes set the `aria-pressed` PDOM attribute to reflect whether `property.value === valueOn`, but the underlying interaction is still "hold to activate" — don't confuse this with [Sticky Toggle Buttons](/api/sun/sticky-toggle-button), which use `ariaRole: 'switch'` and latch until pressed again.
:::


========================================================================
Page: NumberPicker
URL: https://veillette.github.io/Almanach/api/sun/number-picker
Source: docs/api/sun/number-picker.md
Category: API | Tags: sun, NumberPicker, NumberProperty | Status: complete
========================================================================

# NumberPicker

`NumberPicker` (from `scenerystack/sun`) shows a number flanked by an increment arrow above and a decrement arrow below, both drawn directly on the top and bottom halves of the value's own rounded background — the compact, classic "PhET number picker" look used throughout older sims. It's bound to a `Property<number>` and a `TReadOnlyProperty<Range>`, exactly like [`NumberSpinner`](/api/sun/number-spinner). Despite the different name, `NumberPicker` and `NumberSpinner` are **not** distinguished by accessibility — both mix in the same `AccessibleNumberSpinner`, so both support keyboard arrow-key/PDOM interaction out of the box. The real difference is visual construction and configurability: `NumberSpinner` composes separate `ArrowButton` instances positioned around a `NumberDisplay` (configurable via `arrowsPosition` — above/below, beside, or both-right/both-bottom), while `NumberPicker`'s arrows are painted directly onto the two halves of its own background shape, with less layout flexibility but a smaller footprint.

```ts
import { NumberPicker } from 'scenerystack/sun';
import { NumberProperty, Property } from 'scenerystack/axon';
import { Range } from 'scenerystack/dot';
import { Tandem } from 'scenerystack/tandem';

const countProperty = new NumberProperty( 3, {
  numberType: 'Integer',
  range: new Range( 0, 10 )
} );

const countRangeProperty = new Property( new Range( 0, 10 ) );

const countPicker = new NumberPicker( countProperty, countRangeProperty, {
  tandem: Tandem.REQUIRED
} );
```

As with `NumberSpinner`, the range argument is a `TReadOnlyProperty<Range>` (not a plain `Range`), so the picker can respond if the allowed bounds change dynamically.

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `color` / `pressedColor` | blue / a darker derived shade | Arrow and background-gradient color, normal and while pressed |
| `backgroundColor` | `'white'` | Background color when the pointer isn't over it |
| `cornerRadius` | `6` | Corner radius of the value background |
| `xMargin` / `yMargin` | `3` / `3` | Margin between the value text and the background edges |
| `decimalPlaces` | `0` | Digits shown after the decimal point (via the default `formatValue`) |
| `font` | `PhetFont(24)` | Font for the displayed value |
| `incrementFunction` / `decrementFunction` | `v => v + 1` / `v => v - 1` | Custom step logic, e.g. non-uniform steps |
| `align` | `'center'` | Horizontal alignment of the value text: `'center'`, `'left'`, or `'right'` |
| `touchAreaXDilation` / `touchAreaYDilation` | `10` / `10` | Expand each arrow's touch hit area |
| `mouseAreaXDilation` / `mouseAreaYDilation` | `0` / `5` | Expand each arrow's mouse hit area |
| `incrementEnabledFunction` / `decrementEnabledFunction` | Disables at `range.max`/`range.min` | Predicates controlling when each arrow is enabled |
| `formatValue` | pads to `decimalPlaces` | `( value: number ) => string` — custom value formatting |
| `onInput` | no-op | `( event: SceneryEvent \| null, oldValue: number ) => void`, called on any user-driven value change |
| `valueChangedSoundPlayer` / `boundarySoundPlayer` | shared default sound players | Sounds for an ordinary change vs. hitting the range's min/max |

## Methods

| Method | Effect |
| --- | --- |
| `setArrowsVisible( visible )` | Shows/hides both arrows, interrupting any in-progress press when hidden |
| `NumberPicker.createIcon( value, options? )` | Static — builds a non-interactive `NumberPicker` instance for use as an icon, with `pickable: false` and removed from the PDOM by default |

::: tip Arrows disable themselves automatically at the range's edges — same as NumberSpinner
`NumberPicker` derives `incrementEnabledProperty`/`decrementEnabledProperty` from `incrementEnabledFunction`/`decrementEnabledFunction` and keeps each arrow's `pickable` state (and its keyboard equivalent) in sync automatically. If you need non-default enabling logic — e.g. disabling early before the true range boundary — override these two functions rather than trying to intercept `onInput`.
:::


========================================================================
Page: NumberSpinner
URL: https://veillette.github.io/Almanach/api/sun/number-spinner
Source: docs/api/sun/number-spinner.md
Category: API | Tags: sun, NumberSpinner, NumberProperty | Status: verified
========================================================================

# NumberSpinner

`NumberSpinner` (from `scenerystack/sun`) pairs a `NumberDisplay` with increment/decrement `ArrowButton`s, bound to an integer-valued `Property<number>` and a `TReadOnlyProperty<Range>` for the allowed bounds. Use it instead of [`HSlider`](/api/sun/hslider) when discrete, one-at-a-time steps make more sense than continuous dragging — a "number of particles" or "index of item" control is the typical case.

```ts
import { NumberSpinner } from 'scenerystack/sun';
import { NumberProperty, Property } from 'scenerystack/axon';
import { Range } from 'scenerystack/dot';
import { Tandem } from 'scenerystack/tandem';

const countProperty = new NumberProperty( 3, {
  numberType: 'Integer',
  range: new Range( 0, 10 )
} );

const countRangeProperty = new Property( new Range( 0, 10 ) );

const countSpinner = new NumberSpinner(
  countProperty,
  countRangeProperty,
  { tandem: Tandem.REQUIRED }
);
```

The range argument is a `Property<Range>` (not a plain `Range`) so the spinner can respond if the allowed bounds change dynamically — e.g. disabling further increments once a dependent quantity runs out. Both `numberProperty.value` and the range's min/max must be integers; `NumberSpinner` asserts on construction if the initial value falls outside the initial range.

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `arrowsPosition` | `'bothRight'` | Layout of the two arrow buttons: `'leftRight'`, `'topBottom'`, `'bothRight'`, or `'bothBottom'` |
| `deltaValue` | `1` | Amount each press changes the value by (ignored if `incrementFunction`/`decrementFunction` are supplied) |
| `incrementFunction` / `decrementFunction` | `v => v + deltaValue` / `v => v - deltaValue` | Custom step logic, e.g. non-uniform steps |
| `xSpacing` / `ySpacing` | `5` / `3` | Spacing between the arrow buttons and the number display |
| `numberDisplayOptions` | `{ cornerRadius: 5, backgroundStroke: 'black' }` | Options forwarded to the internal `NumberDisplay` |
| `arrowButtonOptions` | — | Options forwarded to both `ArrowButton`s (color, stroke, etc.) |
| `touchAreaXDilation` / `touchAreaYDilation` | `0` / `0` | Expand the arrow buttons' touch hit areas |

## Methods

| Method | Effect |
| --- | --- |
| `setNumberFill( fill: TPaint )` | Sets the color of the displayed number text |

::: tip The arrow buttons disable themselves automatically at the range's edges
`NumberSpinner` links to both the value and the range Property internally and keeps each arrow button's `enabled` in sync — the increment button disables itself when `incrementFunction(value) > range.max`, and correspondingly for decrement. You don't need to wire this up yourself, even if the range changes dynamically.
:::


========================================================================
Page: OnOffSwitch
URL: https://veillette.github.io/Almanach/api/sun/on-off-switch
Source: docs/api/sun/on-off-switch.md
Category: API | Tags: sun, OnOffSwitch, BooleanProperty | Status: verified
========================================================================

# OnOffSwitch

`OnOffSwitch` (from `scenerystack/sun`) is a sliding switch bound to a `Property<boolean>` — off on the left, on on the right, styled like iOS's `UISwitch`. It's a thin subclass of the more general `ToggleSwitch<T>` with `leftValue`/`rightValue` fixed to `false`/`true`. `scenerystack/sun` gives you three different affordances for the exact same "toggle a boolean" pattern, and they read differently to users:

| Component | Reads as | Typical use |
| --- | --- | --- |
| [`Checkbox`](/api/sun/checkbox) | A labeled option to enable/disable | A settings list, "Show velocity vectors" |
| [`BooleanRectangularToggleButton`](/api/sun/toggle-button) | A momentary-feeling control with two icon states | Play/pause, mute/unmute |
| `OnOffSwitch` | A physical on/off switch | A single prominent power/enable toggle, sound on/off |

```ts
import { OnOffSwitch } from 'scenerystack/sun';
import { BooleanProperty } from 'scenerystack/axon';
import { Tandem } from 'scenerystack/tandem';

const soundEnabledProperty = new BooleanProperty( true );

const soundSwitch = new OnOffSwitch( soundEnabledProperty, {
  tandem: Tandem.REQUIRED
} );
```

Unlike `Checkbox`, `OnOffSwitch` has no separate label argument — pair it with your own `Text` (or an `HBox`/`AlignBox` layout) if you need one, and use `accessibleName` for the accessible label.

## Interaction

`OnOffSwitch` (via its `ToggleSwitch` base) supports both click-to-toggle and drag-to-set: clicking anywhere on the switch toggles the value; dragging the thumb past the track's midpoint and releasing snaps it to whichever side it's closest to; dragging the thumb far enough outside the track toggles the value immediately, even before release.

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `size` | `60 x 30` | `Dimension2` for the switch; use `2 x height` for width if you want a circular thumb |
| `trackFillLeft` | `'white'` | Track fill when the Property is `false` (off) |
| `trackFillRight` | `'rgb( 0, 200, 0 )'` | Track fill when the Property is `true` (on) |
| `thumbFill` / `thumbStroke` | computed gradient / `'black'` | Thumb appearance |
| `toggleWhileDragging` | `null` | `null`: iOS-style (change on far drag); `true`: change as soon as thumb crosses center; `false`: only change on release |
| `thumbTouchAreaXDilation` / `thumbTouchAreaYDilation` | `8` / `8` | Expand the thumb's touch hit area |
| `accessibleSwitch` | `true` | Adds `role="switch"` and `aria-checked` PDOM semantics; set `false` if you need non-boolean-style ARIA |

::: warning `OnOffSwitch` requires reference-equality Properties
Both `OnOffSwitch` and its `ToggleSwitch` base assert that the bound `Property`'s `valueComparisonStrategy` is `'reference'` (the default for `BooleanProperty`) — they compare `property.value` against `true`/`false` with `===`. If you've customized `valueComparisonStrategy` on the Property you're binding, `OnOffSwitch` will fail its assertion.
:::


========================================================================
Page: PageControl
URL: https://veillette.github.io/Almanach/api/sun/page-control
Source: docs/api/sun/page-control.md
Category: API | Tags: sun, PageControl, Carousel | Status: complete
========================================================================

# PageControl

`PageControl` (from `scenerystack/sun`) renders the classic iOS "row of dots" pagination indicator: one dot per page, with the current page's dot drawn distinctly. It's driven by two Properties rather than owning any paging state itself, which is exactly the shape [`Carousel`](/api/sun/carousel) exposes — `pageNumberProperty` and `numberOfPagesProperty` — so the two are typically constructed together, with `PageControl` reflecting (and, if `interactive`, controlling) which page of the carousel is showing.

```ts
import { Carousel, PageControl, type CarouselItem } from 'scenerystack/sun';
import { Text, VBox } from 'scenerystack/scenery';
import { Tandem } from 'scenerystack/tandem';

const items: CarouselItem[] = [
  { createNode: () => new Text( 'Apple' ) },
  { createNode: () => new Text( 'Banana' ) },
  { createNode: () => new Text( 'Cherry' ) },
  { createNode: () => new Text( 'Date' ) },
  { createNode: () => new Text( 'Elderberry' ) }
];

const fruitCarousel = new Carousel( items, {
  itemsPerPage: 2,
  tandem: Tandem.REQUIRED.createTandem( 'fruitCarousel' )
} );

const pageControl = new PageControl(
  fruitCarousel.pageNumberProperty,
  fruitCarousel.numberOfPagesProperty,
  {
    interactive: true, // clicking a dot jumps to that page
    tandem: Tandem.REQUIRED.createTandem( 'pageControl' )
  }
);

const carouselWithPaging = new VBox( {
  spacing: 6,
  children: [ fruitCarousel, pageControl ]
} );
```

`pageNumberProperty` must be a settable `TProperty<number>` (not just readable) precisely because `PageControl` writes to it when `interactive: true` and a dot is clicked — `Carousel.pageNumberProperty` satisfies this directly.

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `interactive` | `false` | Whether clicking a dot navigates to that page |
| `orientation` | `'horizontal'` | `'horizontal'` (dots left-to-right) or `'vertical'` (top-to-bottom); match your carousel's `orientation` |
| `dotRadius` | `3` | Radius of each dot |
| `dotSpacing` | `10` | Space between adjacent dots |
| `lineWidth` | `1` | Stroke width, if `currentPageStroke`/`pageStroke` are set |
| `dotTouchAreaDilation` / `dotMouseAreaDilation` | `4` / `4` | Pointer-area dilation beyond each dot's radius, when `interactive` |
| `currentPageFill` / `currentPageStroke` | `'black'` / `null` | Appearance of the dot for the current page |
| `pageFill` / `pageStroke` | `'rgb( 200, 200, 200 )'` / `null` | Appearance of every other dot |

::: tip Dots are recreated whenever the page count changes
`PageControl` rebuilds its dots from scratch every time `numberOfPagesProperty` fires — including at construction — so it stays correct if a `Carousel`'s visible item count changes at runtime (e.g. via `Carousel.setItemVisible`), without any extra wiring on your part.
:::


========================================================================
Page: Panel
URL: https://veillette.github.io/Almanach/api/sun/panel
Source: docs/api/sun/panel.md
Category: API | Tags: sun, Panel | Status: verified
========================================================================

# Panel

`Panel` (from `scenerystack/sun`) draws a rounded, stroked/filled rectangle around a single content `Node`, resizing itself automatically as the content's bounds change. It's the standard way to visually group related controls — a cluster of checkboxes, a slider with its label — into one bordered region.

```ts
import { Panel } from 'scenerystack/sun';
import { VBox, Text } from 'scenerystack/scenery';
import { Checkbox } from 'scenerystack/sun';

const controls = new VBox( {
  spacing: 8,
  align: 'left',
  children: [
    new Text( 'Options' ),
    new Checkbox( gravityEnabledProperty, new Text( 'Gravity' ), { tandem: Tandem.REQUIRED } )
  ]
} );

const controlPanel = new Panel( controls, {
  fill: '#f0f0f0',
  stroke: 'black',
  xMargin: 10,
  yMargin: 10
} );
```

`Panel` takes exactly one content `Node` — group multiple controls with a layout container (`VBox`, `HBox`, `GridBox`, …) first, then wrap that container in a `Panel`.

## Options

| Option | Effect |
| --- | --- |
| `fill` | Background fill (default `'white'`) |
| `stroke` | Border color (default `'black'`) |
| `lineWidth` | Border width (default `1`) |
| `xMargin` / `yMargin` | Space between content and the background edge (default `5` each) |
| `cornerRadius` | Rounded-corner radius (default `10`) |
| `align` | Horizontal alignment of content when it's narrower than `minWidth`: `'left'` (default) \| `'center'` \| `'right'` |
| `minWidth` / `minHeight` | Minimum panel size, even if content is smaller |
| `resize` | If `false`, the panel stops automatically resizing when content bounds change (default `true`) |

## Changing fill/stroke after construction

```ts
controlPanel.fill = '#e0e0e0';
controlPanel.stroke = null; // no border
```

`fill` and `stroke` are both plain getter/setter properties (backed by `setFill`/`getFill`, `setStroke`/`getStroke`).

::: tip `align` only matters when the panel is wider than its content
If content already fills the panel's `minWidth`, all three `align` values look identical — `align` only becomes visible when `minWidth` (or a sibling panel's wider content, if you're manually matching widths) forces extra horizontal space.
:::


========================================================================
Page: PushButtonModel
URL: https://veillette.github.io/Almanach/api/sun/push-button-model
Source: docs/api/sun/push-button-model.md
Category: API | Tags: sun, PushButtonModel, ButtonModel, button | Status: complete
========================================================================

# PushButtonModel

`PushButtonModel` (from `scenerystack/sun`) is the non-visual model behind [`RectangularPushButton`](/api/sun/rectangular-push-button) and [`RoundPushButton`](/api/sun/round-push-button) — it owns the fire-on-press-or-release logic, the fire-on-hold repeat timer, and the listener list, with no knowledge of what the button looks like. Every button in `sun` follows this split: a `ButtonModel` subclass tracks interaction state and decides *when* to act, while a `ButtonNode` subclass (`RectangularButton`/`RoundButton`) turns that state into pixels. You'll construct `PushButtonModel` directly only if you're building a fully custom button `Node` that doesn't fit any of `RectangularPushButton`/`RoundPushButton`/`ArrowButton`/etc.

## `ButtonModel`, the shared base

`ButtonModel` (also exported from `scenerystack/sun`) is what `PushButtonModel`, `ToggleButtonModel`, `StickyToggleButtonModel`, and `MomentaryButtonModel` all extend. It provides the Properties every button interaction is built from:

| Property | Meaning |
| --- | --- |
| `overProperty` | Pointer is over the button (read-only) |
| `downProperty` | Pointer is currently down on the button |
| `focusedProperty` | Button has PDOM focus |
| `looksPressedProperty` | Whether the button should render as pressed (down, or an in-progress a11y click) |
| `isOverOrFocusedProperty` | Pointer over, or focused with highlights shown |
| `enabledProperty` | From the `EnabledComponent` mixin `ButtonModel` extends |
| `fireCompleteEmitter` | Emits after the button has fully fired — the hook sound generators and Voicing responses listen to |

`ButtonModel.createPressListener( options? )` builds and returns a `PressListener` wired up to these Properties; a `ButtonNode` subclass calls it once and adds the result as an input listener on itself.

## `PushButtonModel`

`PushButtonModel` adds the actual momentary-action firing behavior on top of `ButtonModel`:

```ts
import { PushButtonModel, RectangularButton, PushButtonInteractionStateProperty } from 'scenerystack/sun';
import { Tandem } from 'scenerystack/tandem';

// What RectangularPushButton does internally — only write this directly when building
// a custom button Node that RectangularButton/RoundButton don't already cover.
const buttonModel = new PushButtonModel( {
  fireOnDown: false,
  listener: () => console.log( 'fired!' ),
  tandem: Tandem.REQUIRED.createTandem( 'buttonModel' )
} );

const interactionStateProperty = new PushButtonInteractionStateProperty( buttonModel );
```

`RectangularPushButton` and `RoundPushButton` construct exactly this pair (a `PushButtonModel` plus a `PushButtonInteractionStateProperty`) and hand them to `RectangularButton`/`RoundButton`'s `super()` — which is why both button shapes share identical firing options (`fireOnDown`, `fireOnHold`, `listener`, `addListener`/`removeListener`) despite having unrelated visual implementations.

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `listener` | `null` | Convenience for one fire listener, `() => void` |
| `fireOnDown` | `false` | Fire on pointer-down instead of pointer-up-while-over |
| `fireOnHold` | `false` | Enable press-and-hold repeat firing |
| `fireOnHoldDelay` | `400` | Milliseconds held before repeat firing starts |
| `fireOnHoldInterval` | `100` | Milliseconds between repeat fires once started |
| `interruptListener` | `null` | Runs before other fire listeners, purely to interrupt other pointers (helps multitouch) |
| `startCallback` / `endCallback` | (inherited from `ButtonModel`) | Called on pointer down / up, independent of whether the button actually fires |

## Methods

| Method | Effect |
| --- | --- |
| `addListener( listener )` / `removeListener( listener )` | Add/remove a fire listener, called with no arguments |
| `fire()` | Fires all listeners immediately; public so PhET-iO and accessibility code can trigger it directly |

::: tip `isFiringProperty` guards against re-entrant firing
`PushButtonModel.fire()` asserts if called while already firing (`isFiringProperty.value` is `true`) — a listener that tries to fire the same button again synchronously (e.g. from within its own fire callback) will hit that assertion rather than silently recursing.
:::


========================================================================
Page: Radio Button Groups
URL: https://veillette.github.io/Almanach/api/sun/radio-button-group
Source: docs/api/sun/radio-button-group.md
Category: API | Tags: sun, radio-button-group | Status: verified
========================================================================

# Radio Button Groups

A radio button group binds a settable `Property<T>` to a fixed set of mutually-exclusive options, exactly one of which is ever selected. `scenerystack/sun` exports two visual styles: `RectangularRadioButtonGroup<T>` (boxed buttons, each showing a Node — icons or text) and `AquaRadioButtonGroup<T>` (the classic circular radio-button look, each with an associated label Node). Use rectangular groups when the options are best shown as buttons (icons, short labels); use Aqua groups for a traditional list of labeled options.

```ts
import { RectangularRadioButtonGroup, type RectangularRadioButtonGroupItem } from 'scenerystack/sun';
import { Text } from 'scenerystack/scenery';
import { Property } from 'scenerystack/axon';
import { Tandem } from 'scenerystack/tandem';

type Shape = 'circle' | 'square';
const shapeProperty = new Property<Shape>( 'circle' );

const items: RectangularRadioButtonGroupItem<Shape>[] = [
  { value: 'circle', createNode: () => new Text( 'Circle' ) },
  { value: 'square', createNode: () => new Text( 'Square' ) }
];

const shapeRadioButtonGroup = new RectangularRadioButtonGroup( shapeProperty, items, {
  orientation: 'horizontal',
  tandem: Tandem.REQUIRED
} );
```

`AquaRadioButtonGroup` has the same `(property, items, options?)` shape, but each item's `createNode` supplies the *label* shown next to the round button, not the button's own content:

```ts
import { AquaRadioButtonGroup, type AquaRadioButtonGroupItem } from 'scenerystack/sun';

const items: AquaRadioButtonGroupItem<Shape>[] = [
  { value: 'circle', createNode: () => new Text( 'Circle' ) },
  { value: 'square', createNode: () => new Text( 'Square' ) }
];

const aquaGroup = new AquaRadioButtonGroup( shapeProperty, items, {
  orientation: 'vertical', // the default
  tandem: Tandem.REQUIRED
} );
```

`HorizontalAquaRadioButtonGroup` and `VerticalAquaRadioButtonGroup` are convenience subclasses that fix `orientation` for you, if you'd rather not pass it explicitly.

## Options

Both groups are laid out as a `FlowBox`, so `orientation`, `spacing`, and alignment options apply directly. Group-specific highlights:

| Option | Group | Effect |
| --- | --- | --- |
| `orientation` | both | `'horizontal'` or `'vertical'` (default `'vertical'` for both) |
| `spacing` | both | Space between adjacent buttons |
| `radioButtonOptions` | both | Options applied to every individual button (e.g. `baseColor`, `cornerRadius` for rectangular; `radius` for Aqua) |
| `labelAlign` | rectangular | Where an item's optional `label` (outside the button) appears: `'top'`\|`'bottom'`\|`'left'`\|`'right'` |
| `labelSpacing` | rectangular | Space between the button and its optional external `label` |
| `touchAreaXDilation` / `touchAreaYDilation` | both | Expand each button's touch hit area |
| `soundPlayers` | rectangular | Array of one `TSoundPlayer` per button, overriding the default selection sounds |

Every item requires a unique `value`, and the group asserts that `property.value` matches one of the supplied items' values at construction time — there is no "nothing selected" state.

::: tip Rectangular items can have an external `label` too
`RectangularRadioButtonGroupItem` supports an optional `label: Node` in addition to `createNode` — that label is placed *outside* the button (per `labelAlign`), which is handy when the button itself is just an icon and you want a caption beneath it.
:::

::: warning Aqua vs. rectangular items mean different things
For `RectangularRadioButtonGroupItem`, `createNode` builds the button's own content (what's inside the box). For `AquaRadioButtonGroupItem`, `createNode` builds the *label beside* the round button — the round indicator itself is drawn by `AquaRadioButtonGroup`, not by your Node. Swapping the two styles isn't a drop-in replacement.
:::


========================================================================
Page: RectangularButton
URL: https://veillette.github.io/Almanach/api/sun/rectangular-button
Source: docs/api/sun/rectangular-button.md
Category: API | Tags: sun, RectangularButton, ButtonNode, button | Status: complete
========================================================================

# RectangularButton

`RectangularButton` (from `scenerystack/sun`) is the visual base class every rectangular button in `sun` is built from — `RectangularPushButton`, `RectangularToggleButton`/`BooleanRectangularToggleButton`, `RectangularStickyToggleButton`, `RectangularMomentaryButton`, `RectangularRadioButton`, `ArrowButton`, and `CarouselButton` all extend it. It in turn extends `ButtonNode`, the shared base of *both* rectangular and round buttons. You won't construct either class directly in normal sim code — they're both `protected` constructors — but understanding the split matters when you need a fully custom button that none of the concrete subclasses quite covers, and when you're deciphering an options type like `RectangularPushButtonOptions` that's actually assembled from several layers.

## The layering

| Class | Owns | Notes |
| --- | --- | --- |
| `ButtonModel` | Non-visual interaction state (`overProperty`, `downProperty`, `enabledProperty`, `looksPressedProperty`) | See [PushButtonModel](/api/sun/push-button-model) for the concrete subclasses |
| `ButtonNode` | Content layout, `baseColor`, `buttonAppearanceStrategy`, `contentAppearanceStrategy`, PDOM/Voicing wiring | Shape-agnostic; takes a pre-built `buttonBackground` Path |
| `RectangularButton` | The rectangular `buttonBackground` shape itself, corner radii, `size`/`minWidth`/`minHeight`, pointer-area dilation | This page |
| `RectangularPushButton`, etc. | Wires a specific `ButtonModel` subclass to `RectangularButton` | The classes you actually construct |

Every concrete rectangular button constructs its own `ButtonModel` subclass and a `TReadOnlyProperty<ButtonInteractionState>`, then passes both to `super()` — that's the seam `RectangularButton`'s `protected constructor` exposes to its subclasses:

```ts
import { RectangularButton, ButtonModel, ButtonInteractionState } from 'scenerystack/sun';
import type { TReadOnlyProperty } from 'scenerystack/axon';
import { Tandem } from 'scenerystack/tandem';

// Sketch of the seam RectangularPushButton, RectangularToggleButton, etc. all use internally —
// write a subclass like this only when none of the built-in ones fit.
class MyCustomRectangularButton extends RectangularButton {
  public constructor( buttonModel: ButtonModel, interactionStateProperty: TReadOnlyProperty<ButtonInteractionState> ) {
    super( buttonModel, interactionStateProperty, {
      baseColor: 'orange',
      cornerRadius: 8,
      tandem: Tandem.REQUIRED
    } );
  }
}
```

In practice, reach for [`PushButtonModel`](/api/sun/push-button-model) (or `ToggleButtonModel`, `StickyToggleButtonModel`, `MomentaryButtonModel`) plus a matching `*InteractionStateProperty` only when building a genuinely new interaction pattern — for anything that fires once, toggles, latches, or is momentary, the ready-made subclasses in [RectangularPushButton](/api/sun/rectangular-push-button), [Toggle Buttons](/api/sun/toggle-button), [Sticky Toggle Buttons](/api/sun/sticky-toggle-button), and [Momentary Buttons](/api/sun/momentary-button) already cover it.

## Options

`RectangularButtonOptions` (shape) combines with `ButtonNodeOptions` (appearance/content), and this combination is what every concrete `RectangularButtonOptions`-based type (`RectangularPushButtonOptions`, `RectangularToggleButtonOptions`, …) is built from:

| Option | Layer | Effect |
| --- | --- | --- |
| `content` | `ButtonNode` | The `Node` shown on the button |
| `xMargin` / `yMargin` | `ButtonNode` | Margin between `content` and the button's edge (defaults `8`/`5`, deliberately asymmetric) |
| `baseColor` | `ButtonNode` | Background color other colors are derived from |
| `buttonAppearanceStrategy` | `ButtonNode` | `RectangularButton.ThreeDAppearanceStrategy` (default, gradient/shaded look) or `ButtonNode.FlatAppearanceStrategy` (flat, color-swap-only look used by e.g. `CarouselButton`) |
| `size` | `RectangularButton` | Fixed `Dimension2`; `content` is scaled to fit instead of sizing the button to `content` |
| `cornerRadius` | `RectangularButton` | Applied to all four corners (default `4`) |
| `leftTopCornerRadius` / `rightTopCornerRadius` / `leftBottomCornerRadius` / `rightBottomCornerRadius` | `RectangularButton` | Per-corner overrides of `cornerRadius` — this is how `CarouselButton` gets square inner corners and rounded outer ones |
| `stroke` / `lineWidth` | `RectangularButton` | When `stroke` is `null` (default), one is derived from `baseColor` |
| `touchAreaXDilation` / `touchAreaYDilation` / `mouseAreaXDilation` / `mouseAreaYDilation` | `RectangularButton` | Expand the pointer-area rectangle beyond the visual bounds |

::: warning `buttonAppearanceStrategy` decides the whole look
Swapping `buttonAppearanceStrategy` from the default `ThreeDAppearanceStrategy` to `ButtonNode.FlatAppearanceStrategy` changes far more than "flat vs. gradient" — it also changes which sub-options (`overStroke`, `selectedLineWidth`, `deselectedFill`, …) inside `buttonAppearanceStrategyOptions` actually apply, since each strategy defines its own set. `CarouselButton` uses the flat strategy so its arrow buttons read as part of the carousel's chrome rather than as a shaded, standalone button.
:::


========================================================================
Page: RectangularPushButton
URL: https://veillette.github.io/Almanach/api/sun/rectangular-push-button
Source: docs/api/sun/rectangular-push-button.md
Category: API | Tags: sun, RectangularPushButton, button | Status: verified
========================================================================

# RectangularPushButton

`RectangularPushButton` (from `scenerystack/sun`) is the workhorse momentary-action button: it fires a `listener` once per press (or once per release, depending on `fireOnDown`) and holds no state of its own. Use it for one-shot actions like "step forward" or "randomize" — for a button that tracks on/off state, see [Toggle Buttons](/api/sun/toggle-button) instead.

```ts
import { RectangularPushButton } from 'scenerystack/sun';
import { Text } from 'scenerystack/scenery';
import { Tandem } from 'scenerystack/tandem';

const stepButton = new RectangularPushButton( {
  content: new Text( 'Step' ),
  baseColor: 'yellow',
  listener: () => {
    model.step( 0.1 );
  },
  tandem: Tandem.REQUIRED
} );
```

<SceneryDemo demo="rectangular-push-button" />

`content` accepts any `Node`, so an icon (e.g. a `Path` built from a shape) works just as well as text. If your button's content is specifically a text label, [`TextPushButton`](/api/sun/text-push-button) saves you the boilerplate of constructing a `Text` node yourself.

## Options

`RectangularPushButtonOptions` combines options from three layers: the button's own `RectangularButton` shape options, the shared `ButtonNode` appearance options, and `PushButtonModel`'s firing behavior. The most commonly used:

| Option | Effect |
| --- | --- |
| `content` | The `Node` shown on the button (icon, text, etc.); `null` requires an explicit `size` |
| `listener` | Convenience for adding a single fire listener, `() => void` |
| `baseColor` | Background color the 3D appearance gradients are derived from |
| `xMargin` / `yMargin` | Margin between `content` and the button's edge |
| `cornerRadius` | Corner radius, applied to all four corners unless overridden per-corner |
| `size` | Fixed `Dimension2` for the button; `content` is scaled down to fit |
| `fireOnDown` | `true` fires on pointer-down instead of pointer-up (default `false`) |
| `fireOnHold` / `fireOnHoldDelay` / `fireOnHoldInterval` | Enables press-and-hold repeat firing |
| `enabledProperty` | Externally control whether the button can be pressed |
| `touchAreaXDilation` / `touchAreaYDilation` | Expand the touch-friendly hit area beyond the visual bounds |

## Methods

| Method | Effect |
| --- | --- |
| `addListener( listener: () => void )` | Adds another fire listener |
| `removeListener( listener: () => void )` | Removes a previously added listener |

::: tip Prefer `listener` for the common case
`addListener`/`removeListener` exist for adding or removing listeners after construction. If you just need one listener and never remove it, pass `listener` in the options object — it's equivalent and shorter.
:::

::: warning `tandem` is required
Every sun component in a real PhET-iO-instrumented sim needs a `tandem` — `RectangularPushButton` will assert if one isn't supplied. Even outside PhET-iO builds, it's good practice to always pass one.
:::


========================================================================
Page: RectangularRadioButton
URL: https://veillette.github.io/Almanach/api/sun/rectangular-radio-button
Source: docs/api/sun/rectangular-radio-button.md
Category: API | Tags: sun, RectangularRadioButton, RadioButtonGroup | Status: complete
========================================================================

# RectangularRadioButton

`RectangularRadioButton<T>` (from `scenerystack/sun/buttons`, re-exported from `scenerystack/sun`) is a single boxed, flat-appearance button that changes a `Property<T>` to a fixed value when pressed and shows itself as "selected" when the Property already equals that value. It's the individual button [`RectangularRadioButtonGroup`](/api/sun/radio-button-group) creates one of per item — you construct it directly only for a standalone boxed toggle outside of a managed group. Compare with [`AquaRadioButton`](/api/sun/aqua-radio-button), the flat circular equivalent used by `AquaRadioButtonGroup`.

```ts
import { RectangularRadioButton } from 'scenerystack/sun';
import { Text } from 'scenerystack/scenery';
import { Property } from 'scenerystack/axon';
import { Tandem } from 'scenerystack/tandem';

type Shape = 'circle' | 'square';
const shapeProperty = new Property<Shape>( 'circle' );

const circleButton = new RectangularRadioButton( shapeProperty, 'circle', {
  content: new Text( 'Circle' ),
  tandem: Tandem.REQUIRED
} );
```

The constructor is `( property, value, options? )` — unlike `AquaRadioButton`, there's no dedicated label argument; the button's own visible content is set via the `content` option (inherited from `RectangularButton`), same as any other rectangular button. `property` must use the default `'reference'` `valueComparisonStrategy` (`RectangularRadioButton` compares with `===`).

## Options

`RectangularRadioButtonOptions` is `RectangularButtonOptions` with a few PhET-iO/accessibility-only options trimmed off (they don't make sense on a single radio button — e.g. `enabledProperty`), plus:

| Option | Default | Effect |
| --- | --- | --- |
| `content` | — | The `Node` shown inside the button (icon, `Text`, …) |
| `baseColor` | `ColorConstants.LIGHT_BLUE` | Fill color, modulated by selection/hover/press state |
| `soundPlayer` | `null` (falls back to the shared `'pushButton'` sound) | Sound played when this button is pressed |
| `buttonAppearanceStrategy` | `RectangularRadioButton.FlatAppearanceStrategy` | How fill/stroke/opacity change across selected/deselected/over/pressed states |
| `contentAppearanceStrategy` | `RectangularRadioButton.ContentAppearanceStrategy` | How the `content` Node's opacity changes across those same states |

`buttonAppearanceStrategyOptions` on `FlatAppearanceStrategy` controls the specific stroke/opacity values per state — see [Radio Button Groups](/api/sun/radio-button-group) for the more commonly used group-level `radioButtonOptions` that forward into these.

::: tip You'll rarely reach for this class directly
Almost all boxed-radio-button UI in a simulation goes through [`RectangularRadioButtonGroup`](/api/sun/radio-button-group), which handles laying out several `RectangularRadioButton`s, giving them a shared `property`, sizing them uniformly, and wiring up keyboard navigation between them. Construct `RectangularRadioButton` directly only when you need exactly one boxed toggle outside that managed layout.
:::


========================================================================
Page: RoundButton
URL: https://veillette.github.io/Almanach/api/sun/round-button
Source: docs/api/sun/round-button.md
Category: API | Tags: sun, RoundButton, ButtonNode, button | Status: complete
========================================================================

# RoundButton

`RoundButton` (from `scenerystack/sun`) is the circular counterpart to [`RectangularButton`](/api/sun/rectangular-button): the shared visual base class for `RoundPushButton`, `RoundToggleButton`/`BooleanRoundToggleButton`, `RoundStickyToggleButton`, and `RoundMomentaryButton`. Like `RectangularButton`, it extends `ButtonNode` (which owns content layout and appearance strategies) and adds the shape-specific parts: a circular `buttonBackground`, `radius`, and radius-based pointer-area dilation. Its constructor is `protected` — you build one of the concrete subclasses, not `RoundButton` itself, unless you're implementing an entirely new round interaction pattern (see [PushButtonModel](/api/sun/push-button-model) for when that's warranted).

## Sizing: `radius`, not `size`

The biggest practical difference from `RectangularButton` is how sizing works: there's no `size` option, just `radius`. If you supply `content` and no `radius`, the button sizes itself to fit the content plus margins (whichever of width/height is larger determines the radius); if you supply `radius` explicitly, `content` is scaled down to fit inside it.

```ts
import { RoundButton } from 'scenerystack/sun'; // for type reference only — construct a concrete subclass
import { RoundPushButton } from 'scenerystack/sun';
import { Path } from 'scenerystack/scenery';
import { Tandem } from 'scenerystack/tandem';
import iconShape from './iconShape.js';

// A concrete RoundButton-based class, sized explicitly rather than by content:
const iconButton = new RoundPushButton( {
  content: new Path( iconShape, { fill: 'black', maxWidth: 20 } ),
  radius: 24,
  baseColor: 'yellow',
  listener: () => model.reset(),
  tandem: Tandem.REQUIRED
} );
```

## Options

`RoundButtonOptions` combines with `ButtonNodeOptions` the same way `RectangularButtonOptions` does — this combination is what `RoundPushButtonOptions`, `RoundToggleButtonOptions`, etc. are built from:

| Option | Effect |
| --- | --- |
| `content` | The `Node` shown on the button; if omitted, `radius` must be supplied |
| `radius` | Fixed radius; `null` (with `content` set) sizes the button to the content |
| `xMargin` / `yMargin` | Minimum margin between `content` and the circular edge (default `5`/`5`) |
| `baseColor` / `buttonAppearanceStrategy` | Same appearance-layer options as `RectangularButton` — `RoundButton.ThreeDAppearanceStrategy` is the default |
| `stroke` / `lineWidth` | When `stroke` is `null` (default), derived from `baseColor` |
| `touchAreaDilation` / `mouseAreaDilation` | Radius dilation of the pointer areas beyond the visual circle |
| `touchAreaXShift` / `touchAreaYShift` / `mouseAreaXShift` / `mouseAreaYShift` | Offset the (dilated) pointer-area circle away from the button's center |

::: warning A round button can be sizable in at most one dimension
`RoundButton` asserts if both `widthSizable` and `heightSizable` are set at once — a circle's width and height are coupled through its single `radius`, so a layout container can drive at most one of them (the other is derived to match). This is the same constraint noted on [RoundPushButton](/api/sun/round-push-button#options).
:::


========================================================================
Page: RoundPushButton
URL: https://veillette.github.io/Almanach/api/sun/round-push-button
Source: docs/api/sun/round-push-button.md
Category: API | Tags: sun, RoundPushButton, button | Status: verified
========================================================================

# RoundPushButton

`RoundPushButton` (from `scenerystack/sun`) is the circular counterpart to [`RectangularPushButton`](/api/sun/rectangular-push-button): same momentary-action behavior — fires a `listener` once per press or release and holds no state of its own — just a round `RoundButton` shape instead of a rectangular one. Reach for it for icon-only actions (play, a single glyph) where a circular affordance reads better than a rectangle, e.g. a play button or a single-icon "randomize" control.

```ts
import { RoundPushButton } from 'scenerystack/sun';
import { Path } from 'scenerystack/scenery';
import { Tandem } from 'scenerystack/tandem';
import playIconShape from './playIconShape.js';

const playButton = new RoundPushButton( {
  content: new Path( playIconShape, { fill: 'black' } ),
  baseColor: 'rgb( 0, 200, 0 )',
  listener: () => {
    model.play();
  },
  tandem: Tandem.REQUIRED
} );
```

Both `RoundPushButton` and `RectangularPushButton` construct the same `PushButtonModel` internally and expose the identical `addListener`/`removeListener`/`fireOnDown`/`fireOnHold*` firing behavior — the only real difference between the two classes is which button shape (`RoundButton` vs. `RectangularButton`) they extend, so switching between them later is a one-line change.

## Options

`RoundPushButtonOptions` combines `RoundButton`'s shape options with the shared `ButtonNode` appearance options and `PushButtonModel`'s firing behavior:

| Option | Default | Effect |
| --- | --- | --- |
| `content` | `null` | The `Node` shown on the button; if omitted, `radius` must be supplied explicitly |
| `radius` | `30` (or `null` if `content` given) | Fixed radius; when `null` and `content` is set, the button sizes itself to fit the content plus margins |
| `listener` | — | Convenience for adding a single fire listener, `() => void` |
| `baseColor` | — | Background color the 3D gradient appearance is derived from |
| `xMargin` / `yMargin` | `5` / `5` | Minimum margin between `content` and the button's circular edge |
| `fireOnDown` | `false` | `true` fires on pointer-down instead of pointer-up |
| `fireOnHold` / `fireOnHoldDelay` / `fireOnHoldInterval` | `false` / … | Enables press-and-hold repeat firing |
| `touchAreaDilation` / `mouseAreaDilation` | `0` / `0` | Radius dilation of the touch/mouse hit area beyond the visual circle |
| `enabledProperty` | — | Externally control whether the button can be pressed |

## Methods

| Method | Effect |
| --- | --- |
| `addListener( listener: () => void )` | Adds another fire listener |
| `removeListener( listener: () => void )` | Removes a previously added listener |

::: tip A single sizable dimension only
`RoundButton` (the shared base of `RoundPushButton` and the round toggle/radio buttons) asserts if you try to make it sizable in both width and height at once — a round button's width and height are inherently coupled through its radius, so pick at most one dimension to be layout-driven.
:::


========================================================================
Page: Slider
URL: https://veillette.github.io/Almanach/api/sun/slider
Source: docs/api/sun/slider.md
Category: API | Tags: sun, Slider, HSlider, VSlider, Orientation | Status: complete
========================================================================

# Slider

`Slider` (from `scenerystack/sun`) is the class that actually implements dragging a thumb along a track, clamped to a `Range` and written into a numeric `Property` — [`HSlider`](/api/sun/hslider) and `VSlider` are both thin subclasses that only fix `orientation`. Reach for `HSlider`/`VSlider` for ordinary fixed-orientation sliders; use `Slider` directly when the orientation itself needs to vary at runtime (e.g. a control that flips between a horizontal and vertical layout depending on screen size), or when writing code generic over `Orientation` that shouldn't have to pick between two classes.

```ts
import { Slider } from 'scenerystack/sun';
import { NumberProperty } from 'scenerystack/axon';
import { Range } from 'scenerystack/dot';
import { Orientation } from 'scenerystack/phet-core';
import { Tandem } from 'scenerystack/tandem';

const volumeProperty = new NumberProperty( 50, { range: new Range( 0, 100 ) } );

const slider = new Slider( volumeProperty, new Range( 0, 100 ), {
  orientation: Orientation.VERTICAL,
  tandem: Tandem.REQUIRED
} );
```

`Slider`'s constructor signature, `positionProperty`/`Range` handling, tick marks (`addMajorTick`/`addMinorTick`), and most options are identical to what [`HSlider`](/api/sun/hslider) documents — that page's options table (`trackSize`, `thumbSize`, `enabledRangeProperty`, `constrainValue`, `trackNode`/`thumbNode`, …) all come from `Slider` itself. The one option `HSliderOptions` removes that `Slider` still has is `orientation`.

## What `HSlider`/`VSlider` fix

| Class | Fixes |
| --- | --- |
| `HSlider` | `orientation: Orientation.HORIZONTAL` |
| `VSlider` | `orientation: Orientation.VERTICAL` |
| `Slider` | Neither — `orientation` defaults to `Orientation.HORIZONTAL` but can be set (or swapped) explicitly |

When `orientation` is `Orientation.VERTICAL`, `Slider` swaps `trackSize`/`thumbSize` and the touch/mouse-area dilation options internally (since you always describe dimensions as if the slider were horizontal, then it's rotated), so client code doesn't need its own orientation-swapping logic.

## Public API worth knowing beyond HSlider's table

| Member | Meaning |
| --- | --- |
| `enabledRangeProperty` | A `TReadOnlyProperty<Range>` narrower than or equal to the full track range — this is what actually constrains the value, same as documented on `HSlider` |
| `thumbDragListener` | The internal [`DragListener`](/api/scenery/drag-listener) driving the thumb — public so client code can inspect its `isPressedProperty`/`isHoveringProperty` |
| `trackDragListener` | The internal `DragListener` for clicking/dragging directly on the track |
| `addMajorTick( value, label? )` / `addMinorTick( value, label? )` | Same tick API as `HSlider` |
| `setMajorTicksVisible` / `setMinorTicksVisible` | Toggle tick visibility |

`Slider` also mixes in [`Sizable`](/api/scenery/sizable-mixins) — internally it makes itself non-sizable on whichever axis isn't its orientation (a horizontal slider sets `heightSizable = false`) and sizable on the other, so it can participate in a [`FlowBox`](/api/scenery/flow-box)'s `stretch`/`grow` layout along its own axis.

::: tip Most code should still reach for HSlider or VSlider
`Slider` is documented separately mainly so the shared implementation is clear, and so generic/orientation-swapping code has somewhere to import from. For an ordinary fixed-orientation slider, `HSlider`/`VSlider` communicate intent more clearly and remove one option you'd otherwise have to remember to set.
:::


========================================================================
Page: SliderTrack, DefaultSliderTrack, and SliderThumb
URL: https://veillette.github.io/Almanach/api/sun/slider-track-and-thumb
Source: docs/api/sun/slider-track-and-thumb.md
Category: API | Tags: sun, SliderTrack, DefaultSliderTrack, SliderThumb, Slider | Status: complete
========================================================================

# SliderTrack, DefaultSliderTrack, and SliderThumb

[`HSlider`](/api/sun/hslider)/`VSlider`/[`Slider`](/api/sun/slider) build their visuals from two swappable pieces: a track (the line the thumb moves along, handling click-and-drag-to-set-value) and a thumb (the draggable handle). `DefaultSliderTrack` and the default rectangular thumb are what you get out of the box; pass `trackNode`/`thumbNode` to any slider constructor to replace either one with your own `Node` while keeping the drag-to-value behavior.

```ts
import { HSlider, DefaultSliderTrack } from 'scenerystack/sun';
import { NumberProperty, Property } from 'scenerystack/axon';
import { Range, Dimension2 } from 'scenerystack/dot';
import { Tandem } from 'scenerystack/tandem';

const volumeProperty = new NumberProperty( 50, { range: new Range( 0, 100 ) } );
const rangeProperty = new Property( new Range( 0, 100 ) );

const customTrack = new DefaultSliderTrack( volumeProperty, rangeProperty, {
  size: new Dimension2( 160, 3 ),
  fillEnabled: 'green',
  fillDisabled: 'lightgray',
  cornerRadius: 1.5,
  enabledRangeProperty: rangeProperty,
  tandem: Tandem.REQUIRED.createTandem( 'trackNode' )
} );

const slider = new HSlider( volumeProperty, new Range( 0, 100 ), {
  trackNode: customTrack,
  tandem: Tandem.REQUIRED
} );
```

::: tip Prefer the plain options first
Most visual changes — track color, track size, thumb color, thumb size — are exposed directly as `HSlider`/`Slider` options (`trackFillEnabled`, `trackSize`, `thumbFill`, `thumbSize`, …; see [`HSlider`](/api/sun/hslider)). Reach for `trackNode`/`thumbNode` only when you need a shape or behavior the built-in appearance can't express, e.g. a gradient track or a custom-shaped thumb icon.
:::

## SliderTrack (abstract base)

`SliderTrack` implements the shared mechanics every track needs — mapping a pixel position to a value along a `Range`, a `DragListener` for click-and-drag-to-set, and sound-on-click — but takes an arbitrary `Node` as its visual. Constructing `SliderTrack` directly means supplying that visual `Node` yourself:

```ts
import { SliderTrack } from 'scenerystack/sun';
import { Rectangle } from 'scenerystack/scenery';

const visual = new Rectangle( 0, 0, 160, 3, { fill: 'purple' } );
const track = new SliderTrack( volumeProperty, visual, new Range( 0, 100 ), {
  size: new Dimension2( 160, 3 )
} );
```

| Constructor argument | Meaning |
| --- | --- |
| `valueProperty` | The numeric `Property` the track writes to on click/drag |
| `trackNode` | The visual `Node` to display and drag on |
| `range` | A `Range` or `TReadOnlyProperty<Range>` mapping pixel position to value |

| Option | Effect |
| --- | --- |
| `size` | `Dimension2` used for layout math (the visual `Node` isn't resized automatically to match) |
| `enabledRangeProperty` | Narrower range that actually constrains dragging; defaults to the full `range` |
| `constrainValue` | `(value: number) => number`, applied before the value is set |
| `startDrag` / `drag` / `endDrag` | Hooks into the drag lifecycle |
| `soundGenerator` | A `ValueChangeSoundPlayer`, or `null` to silence click/drag sounds |

## DefaultSliderTrack

`DefaultSliderTrack` extends `SliderTrack`, supplying the visual itself: two stacked `Rectangle`s — a full-range "disabled" rectangle behind an "enabled" rectangle that shrinks to match `enabledRangeProperty`, so narrowing the enabled range visibly grays out the excluded portion. This is what `HSlider`/`VSlider`/`Slider` construct when you don't pass a `trackNode`.

| Option | Default | Effect |
| --- | --- | --- |
| `fillEnabled` | `'white'` | Fill of the enabled (interactive) portion |
| `fillDisabled` | `'gray'` | Fill of the disabled portion |
| `stroke` | `'black'` | Stroke on both rectangles |
| `lineWidth` | `1` | Stroke width |
| `cornerRadius` | `0` | Corner radius on both rectangles |

`size` and `enabledRangeProperty` are required for `DefaultSliderTrack` (they're optional on the base `SliderTrack`).

## SliderThumb

`SliderThumb` is a `Rectangle`-based thumb with a vertical center line, sized and colored by options — the default thumb every `HSlider`/`VSlider`/`Slider` uses unless you pass `thumbNode`. It highlights itself on pointer-over via an internal `PressListener`.

| Option | Default | Effect |
| --- | --- | --- |
| `size` | `22 x 45` | Thumb dimensions (pass `2 x height` for width to get a square-ish/circular-feeling thumb) |
| `fill` | `'rgb( 50, 145, 184 )'` | Normal fill |
| `fillHighlighted` | `'rgb( 71, 207, 255 )'` | Fill while the pointer is over or dragging the thumb |
| `stroke` | `'black'` | Thumb stroke |
| `centerLineStroke` | `'white'` | Color of the vertical center line |
| `cornerRadius` | `0.25 * size.width` | Corner rounding |

::: warning A custom `thumbNode`/`trackNode` gets its position managed for you
When you supply `trackNode`/`thumbNode` to a slider, the slider still owns positioning and drag wiring — don't add your own `DragListener` to a custom track/thumb `Node` you pass in, and don't reposition it manually; use the appearance-only options (fills, strokes, size) and let the slider's internal `SliderTrack`/thumb-positioning logic handle placement.
:::


========================================================================
Page: Sticky Toggle Buttons
URL: https://veillette.github.io/Almanach/api/sun/sticky-toggle-button
Source: docs/api/sun/sticky-toggle-button.md
Category: API | Tags: sun, RectangularStickyToggleButton, RoundStickyToggleButton, StickyToggleButtonModel, button | Status: complete
========================================================================

# Sticky Toggle Buttons

A sticky toggle button pops down (`valueUp`) or stays pressed down (`valueDown`) — pressing it while up latches it down, and pressing it again while down releases it back up. This is the "record button" or "power button" pattern: unlike [Momentary Buttons](/api/sun/momentary-button), releasing the pointer does *not* undo the state change. `scenerystack/sun` exports `RectangularStickyToggleButton<T>` and `RoundStickyToggleButton<T>`, both built on the shared `StickyToggleButtonModel<T>`.

```ts
import { RoundStickyToggleButton } from 'scenerystack/sun';
import { Path } from 'scenerystack/scenery';
import { Property } from 'scenerystack/axon';
import { Tandem } from 'scenerystack/tandem';
import recordIconShape from './recordIconShape.js';

type RecordState = 'up' | 'down';
const recordButtonStateProperty = new Property<RecordState>( 'up' );

const recordButton = new RoundStickyToggleButton(
  recordButtonStateProperty,
  'up',   // valueUp
  'down', // valueDown
  {
    content: new Path( recordIconShape, { fill: 'red' } ),
    baseColor: 'white',
    tandem: Tandem.REQUIRED
  }
);
```

`RectangularStickyToggleButton` has the identical `(valueProperty, valueUp, valueDown, options?)` constructor — only the button shape differs.

## `StickyToggleButtonModel`

Both classes construct a `StickyToggleButtonModel<T>` internally (extending the shared `ButtonModel` base documented on [PushButtonModel](/api/sun/push-button-model)), which owns the latch logic: pressing while `valueProperty.value === valueUp` immediately toggles it to `valueDown`; releasing while down and *not* part of the same press-release action toggles it back to `valueUp`. `Property.valueComparisonStrategy` must be `'reference'` — the model asserts this at construction, since it compares against `valueUp`/`valueDown` with `===`.

## Options

Both classes accept the same appearance options as their non-sticky counterparts ([`RectangularButtonOptions`](/api/sun/rectangular-button#options) / [`RoundButtonOptions`](/api/sun/round-button#options)) plus:

| Option | Effect |
| --- | --- |
| `soundPlayer` | Sound played on every toggle, in either direction (default: shared `'pushButton'` player) |

Both classes default `ariaRole` to `'switch'` and set both `aria-pressed` and `aria-checked` PDOM attributes to reflect `valueProperty.value === valueDown` — screen readers announce these as a switch rather than a momentary button.

::: tip Prefer `OnOffSwitch` for a plain boolean on/off control
If your state is just `boolean` and you want the classic iOS-style sliding switch rather than a button that visually "sticks down," see [`OnOffSwitch`](/api/sun/on-off-switch) instead — it's a different visual metaphor for a similar two-state idea.
:::

::: warning Releasing during the same press doesn't release the latch
`StickyToggleButtonModel` tracks whether the button was pressed while already down as part of the *same* continuous action — releasing right after the press that latched it down does not immediately un-latch it. You have to press and release again to pop it back up. This is what makes the interaction feel like a real latch rather than a simple boolean toggle-on-tap.
:::


========================================================================
Page: TextPushButton
URL: https://veillette.github.io/Almanach/api/sun/text-push-button
Source: docs/api/sun/text-push-button.md
Category: API | Tags: sun, TextPushButton, button | Status: verified
========================================================================

# TextPushButton

`TextPushButton` (from `scenerystack/sun`) is a convenience subclass of [`RectangularPushButton`](/api/sun/rectangular-push-button) that builds its own `Text` content node for you, instead of requiring you to pass one via `content`. Reach for it whenever a button's label is plain text — it saves the boilerplate of constructing and styling a `Text` node yourself.

```ts
import { TextPushButton } from 'scenerystack/sun';
import { Tandem } from 'scenerystack/tandem';

const resetButton = new TextPushButton( 'Reset', {
  baseColor: 'orange',
  listener: () => {
    model.reset();
  },
  tandem: Tandem.REQUIRED
} );
```

The first constructor argument is the string (or a `TReadOnlyProperty<string>`, for translated/dynamic text) — everything else is passed as options, identical to [`RectangularPushButtonOptions`](/api/sun/rectangular-push-button) minus `content`, which `TextPushButton` builds internally.

## Options

`TextPushButtonOptions` adds a few text-specific options on top of everything `RectangularPushButton` accepts (`baseColor`, `listener`, `xMargin`, `cornerRadius`, `fireOnHold`, and so on — see [the RectangularPushButton reference](/api/sun/rectangular-push-button#options)):

| Option | Effect |
| --- | --- |
| `font` | `Font` used for the label (default `Font.DEFAULT`) |
| `textFill` | Text color (default `'black'`) |
| `maxTextWidth` | Caps the label width, scaling it down if a translation runs long |
| `textNodeOptions` | Additional options passed straight through to the underlying `Text` node |

```ts
import { Font } from 'scenerystack/scenery';

const button = new TextPushButton( 'Randomize', {
  font: new Font( { size: 16, weight: 'bold' } ),
  textFill: 'white',
  baseColor: 'purple',
  maxTextWidth: 120,
  tandem: Tandem.REQUIRED
} );
```

::: tip Translated strings need `maxTextWidth`
A string that fits comfortably in English can overflow the button in another language. Always set `maxTextWidth` on a `TextPushButton` whose label comes from a translated `StringProperty`, so the text scales down instead of spilling outside the button's bounds.
:::


========================================================================
Page: Toggle Buttons
URL: https://veillette.github.io/Almanach/api/sun/toggle-button
Source: docs/api/sun/toggle-button.md
Category: API | Tags: sun, toggle-button, BooleanProperty | Status: verified
========================================================================

# Toggle Buttons

Unlike [`RectangularPushButton`](/api/sun/rectangular-push-button), a toggle button is bound directly to a `Property` and reflects (and controls) its current value — pressing it flips the Property between two states, and the button's appearance updates automatically if the Property changes elsewhere. `scenerystack/sun` exports four classes for this: `BooleanRectangularToggleButton` and `BooleanRoundToggleButton` (the common case, swapping between two `Node`s based on a `BooleanProperty`), and the generic `RectangularToggleButton<T>` / `RoundToggleButton<T>` (toggling any `Property<T>` between two arbitrary values, with one fixed piece of content).

```ts
import { BooleanRectangularToggleButton } from 'scenerystack/sun';
import { Path } from 'scenerystack/scenery';
import { BooleanProperty } from 'scenerystack/axon';
import { Tandem } from 'scenerystack/tandem';
import playIconShape from './playIconShape.js';
import pauseIconShape from './pauseIconShape.js';

const isPlayingProperty = new BooleanProperty( false );

const playPauseButton = new BooleanRectangularToggleButton(
  isPlayingProperty,
  new Path( pauseIconShape, { fill: 'black' } ), // shown when isPlayingProperty === true
  new Path( playIconShape, { fill: 'black' } ),  // shown when isPlayingProperty === false
  {
    baseColor: 'yellow',
    tandem: Tandem.REQUIRED
  }
);
```

`BooleanRoundToggleButton` has the identical constructor signature and is used exactly the same way — only the button shape differs.

## The generic form

`RectangularToggleButton<T>` and `RoundToggleButton<T>` toggle a `Property<T>` between two specific values of any type (not just `boolean`), sharing one `content` Node for both states:

```ts
import { RoundToggleButton } from 'scenerystack/sun';
import { Property } from 'scenerystack/axon';
import { Text } from 'scenerystack/scenery';

type Speed = 'normal' | 'slow';
const speedProperty = new Property<Speed>( 'normal' );

const speedButton = new RoundToggleButton(
  speedProperty,
  'normal', // valueOff
  'slow',   // valueOn
  { content: new Text( 'x' ), tandem: Tandem.REQUIRED }
);
```

`Property.valueComparisonStrategy` must be `'reference'` for the bound Property (the default) — the toggle buttons compare `property.value` against `valueOff`/`valueOn` with `===`.

## Options

All four classes accept the same button-appearance options as [`RectangularPushButton`](/api/sun/rectangular-push-button#options) / the round-button equivalents (`baseColor`, `xMargin`, `yMargin`, `cornerRadius`, pointer-area dilations, `enabledProperty`), plus:

| Option | Effect |
| --- | --- |
| `valueOffSoundPlayer` | Sound played when the bound value becomes the "off" value |
| `valueOnSoundPlayer` | Sound played when the bound value becomes the "on" value |

`BooleanRectangularToggleButton`/`BooleanRoundToggleButton` additionally derive a default `accessibleName` from the `trueNode`/`falseNode` content if neither has one set explicitly and you don't provide `accessibleName` yourself.

::: tip Toggle buttons don't need resetting themselves
A toggle button has no state of its own — it only reflects the bound `Property`. To make a play/pause or mute/unmute control participate correctly in "Reset All," reset the underlying `BooleanProperty`, not the button; see the [Reset All pattern](/patterns/reset-all-pattern).
:::


========================================================================
Page: ToggleNode and BooleanToggleNode
URL: https://veillette.github.io/Almanach/api/sun/toggle-node
Source: docs/api/sun/toggle-node.md
Category: API | Tags: sun, ToggleNode, BooleanToggleNode | Status: complete
========================================================================

# ToggleNode and BooleanToggleNode

`ToggleNode<T>` (from `scenerystack/sun`) shows exactly one of several child `Node`s at a time, chosen by which value in a list matches a `TReadOnlyProperty<T>`'s current value — useful for swapping an icon, a message, or an entire sub-scene based on model state without manually managing `visible` on each child yourself. `BooleanToggleNode` is a convenience subclass for the common two-state (`true`/`false`) case.

```ts
import { ToggleNode, type ToggleNodeElement } from 'scenerystack/sun';
import { Text } from 'scenerystack/scenery';
import { Property } from 'scenerystack/axon';

type Phase = 'solid' | 'liquid' | 'gas';
const phaseProperty = new Property<Phase>( 'liquid' );

const elements: ToggleNodeElement<Phase>[] = [
  { value: 'solid', createNode: () => new Text( 'Solid' ) },
  { value: 'liquid', createNode: () => new Text( 'Liquid' ) },
  { value: 'gas', createNode: () => new Text( 'Gas' ) }
];

const phaseNode = new ToggleNode( phaseProperty, elements );
```

Each `ToggleNodeElement`'s `createNode()` builds the Node shown for that value; exactly one must match `phaseProperty.value` at all times (`ToggleNode` asserts on a mismatch count). When the Property changes, `ToggleNode` shows the matching child and hides the rest.

## BooleanToggleNode

`BooleanToggleNode` fixes the two-state case so you don't need to build the `ToggleNodeElement[]` array yourself — pass the `true`-state and `false`-state `Node`s directly:

```ts
import { BooleanToggleNode } from 'scenerystack/sun';
import { Path } from 'scenerystack/scenery';
import { BooleanProperty } from 'scenerystack/axon';

const isPlayingProperty = new BooleanProperty( false );

const playPauseIcon = new BooleanToggleNode(
  isPlayingProperty,
  new Path( pauseShape ),  // shown when isPlayingProperty is true
  new Path( playShape )    // shown when isPlayingProperty is false
);
```

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `alignChildren` | `ToggleNode.CENTER` | A function `(children) => void` run whenever children resize, to align them relative to each other. Static alternatives: `ToggleNode.CENTER_X`, `CENTER_Y`, `LEFT`, `RIGHT`, `BOTTOM`, `CENTER_BOTTOM`, `NONE` |
| `unselectedChildrenSceneGraphStrategy` | `'included'` | `'included'`: unselected children stay in the scene graph, hidden via `visible: false` (bounds are the union of all children); `'excluded'`: unselected children are removed entirely, so bounds match only the currently-selected child, which can improve performance |

::: warning Don't add or remove children yourself after construction
`ToggleNode` manages its own `children` array to track visibility per value; adding/removing children directly on a `ToggleNode` instance after construction isn't supported and will break its internal bookkeeping. If the *set* of possible values needs to change, construct a new `ToggleNode`.
:::

::: tip Reach for `BooleanToggleNode` over `Checkbox`/`OnOffSwitch` for content, not controls
`ToggleNode`/`BooleanToggleNode` swap *what's displayed* based on a Property someone else changes — they have no click/drag interaction of their own. If you need the user to be able to flip the Property by interacting with the Node itself, use [`Checkbox`](/api/sun/checkbox) or [`OnOffSwitch`](/api/sun/on-off-switch) instead (or alongside — it's common to pair a `BooleanToggleNode` icon with an `OnOffSwitch` control for the same Property).
:::


========================================================================
Page: ToggleSwitch
URL: https://veillette.github.io/Almanach/api/sun/toggle-switch
Source: docs/api/sun/toggle-switch.md
Category: API | Tags: sun, ToggleSwitch, OnOffSwitch | Status: complete
========================================================================

# ToggleSwitch

`ToggleSwitch<T>` (from `scenerystack/sun`) is the generic iOS-style sliding switch that [`OnOffSwitch`](/api/sun/on-off-switch) specializes: rather than being fixed to `false`/`true`, `ToggleSwitch` takes any two values of type `T` and slides between them. Reach for `ToggleSwitch` directly when the two states aren't naturally boolean (e.g. two named modes) but should still read visually as an on/off-style switch; use `OnOffSwitch` for ordinary boolean toggles, since it communicates intent more directly and removes two constructor arguments.

```ts
import { ToggleSwitch } from 'scenerystack/sun';
import { Property } from 'scenerystack/axon';
import { Tandem } from 'scenerystack/tandem';

type Units = 'metric' | 'imperial';
const unitsProperty = new Property<Units>( 'metric' );

const unitsSwitch = new ToggleSwitch( unitsProperty, 'metric', 'imperial', {
  tandem: Tandem.REQUIRED
} );
```

The constructor is `( property, leftValue, rightValue, options? )` — the switch renders on the left when `property.value === leftValue` and on the right when it equals `rightValue`. As with [`OnOffSwitch`](/api/sun/on-off-switch), `property` must use the default `'reference'` `valueComparisonStrategy`, since `ToggleSwitch` compares with `===`.

## Interaction

Clicking anywhere on the switch toggles between `leftValue`/`rightValue`; dragging the thumb past the track's midpoint and releasing snaps to the closer side; dragging far enough outside the track toggles the value immediately, even before release. This is exactly the interaction [`OnOffSwitch`](/api/sun/on-off-switch) documents, since `OnOffSwitch` is a thin subclass with `leftValue`/`rightValue` fixed to `false`/`true`.

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `size` | `60 x 30` | `Dimension2` for the switch; use `2 x height` for width for a circular-looking thumb |
| `trackFillLeft` / `trackFillRight` | computed gradient | Track fill in each state |
| `thumbFill` / `thumbStroke` | computed gradient / `'black'` | Thumb appearance |
| `toggleWhileDragging` | `null` | `null`: iOS-style, change on far drag; `true`: change as soon as the thumb crosses center; `false`: only change on release |
| `dragThreshold` | `3` | View-space distance a drag must cover before it's treated as a drag rather than a click/tap |
| `toggleThreshold` | `1` | Thumb-widths past the track edge before dragging immediately toggles the value |
| `thumbTouchAreaXDilation` / `thumbTouchAreaYDilation` | `8` / `8` | Expand the thumb's touch hit area |
| `accessibleSwitch` | `true` | Adds `role="switch"` plus `aria-pressed`/`aria-checked` PDOM semantics |
| `accessibleContextResponseLeftValue` / `accessibleContextResponseRightValue` | `null` | Spoken/announced responses when the switch lands on each side |

::: tip `OnOffSwitch` is almost always what you want
`scenerystack/sun` gives boolean toggles three different affordances — see the comparison table on the [`OnOffSwitch`](/api/sun/on-off-switch) page. `ToggleSwitch` exists underneath `OnOffSwitch` mainly so a two-non-boolean-value switch has somewhere to come from; for `true`/`false` state, use `OnOffSwitch` directly.
:::


========================================================================
Page: VerticalCheckboxGroup
URL: https://veillette.github.io/Almanach/api/sun/vertical-checkbox-group
Source: docs/api/sun/vertical-checkbox-group.md
Category: API | Tags: sun, VerticalCheckboxGroup, Checkbox | Status: complete
========================================================================

# VerticalCheckboxGroup

`VerticalCheckboxGroup` (from `scenerystack/sun`) is a `VBox` of several [`Checkbox`](/api/sun/checkbox)es, each bound to its own independent `PhetioProperty<boolean>` — unlike a radio button group, there's no shared selection Property; each checkbox in the list can be checked or unchecked independently. Reach for it whenever you'd otherwise construct several `Checkbox`es and a `VBox` by hand and want consistent spacing/pointer-area dilation across all of them for free.

```ts
import { VerticalCheckboxGroup, type VerticalCheckboxGroupItem } from 'scenerystack/sun';
import { Text } from 'scenerystack/scenery';
import { BooleanProperty } from 'scenerystack/axon';
import { Tandem } from 'scenerystack/tandem';

const gravityEnabledProperty = new BooleanProperty( true );
const frictionEnabledProperty = new BooleanProperty( false );

const items: VerticalCheckboxGroupItem[] = [
  { property: gravityEnabledProperty, createNode: () => new Text( 'Gravity' ), tandemName: 'gravityCheckbox' },
  { property: frictionEnabledProperty, createNode: () => new Text( 'Friction' ), tandemName: 'frictionCheckbox' }
];

const optionsGroup = new VerticalCheckboxGroup( items, {
  tandem: Tandem.REQUIRED
} );
```

Each `VerticalCheckboxGroupItem` needs its own `property` and a `createNode()` that builds the checkbox's label — this is the same `createNode`-per-item shape used by `ToggleNode`, `AquaRadioButtonGroup`, and `RectangularRadioButtonGroup` elsewhere in `scenerystack/sun`.

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `spacing` | `10` | Vertical spacing between checkboxes (this is a `VBoxOptions` passthrough) |
| `checkboxOptions` | — | Options applied to every individual `Checkbox` (`boxWidth`, `checkboxColor`, …) |
| `touchAreaXDilation` | `5` | X dilation of each checkbox's touch area (Y dilation is computed automatically from `spacing`) |
| `mouseAreaXDilation` | `5` | Same, for mouse areas |
| `align` | `'left'` | Inherited `VBoxOptions` default — left-aligns all checkboxes |

Per-item `options` (on each `VerticalCheckboxGroupItem`) override `checkboxOptions` for that one checkbox, same precedence as `RectangularRadioButtonGroupItem.options` overriding `radioButtonOptions`.

::: tip Each checkbox keeps its own PhET-iO identity
Give every item a `tandemName` (e.g. `'gravityCheckbox'`) rather than relying on index-based naming — `VerticalCheckboxGroup` creates each `Checkbox`'s tandem via `options.tandem.createTandem( item.tandemName )` when supplied, or falls back to `Tandem.OPTIONAL` otherwise.
:::

::: warning This is a layout convenience, not a mutually-exclusive group
Because each checkbox is bound to its own `Property<boolean>`, any number of them (including zero or all) can be checked simultaneously. If you need exactly-one-of-N selection, reach for [Radio Button Groups](/api/sun/radio-button-group) instead — `VerticalCheckboxGroup` and radio button groups solve different problems despite the similar vertical-list appearance.
:::


========================================================================
Page: VSlider
URL: https://veillette.github.io/Almanach/api/sun/v-slider
Source: docs/api/sun/v-slider.md
Category: API | Tags: sun, VSlider, slider | Status: verified
========================================================================

# VSlider

`VSlider` (from `scenerystack/sun`) is [`HSlider`](/api/sun/hslider)'s vertical twin: both are thin convenience wrappers around the general `Slider` class that fix its `orientation` option, `VSlider` to `Orientation.VERTICAL` and `HSlider` to `Orientation.HORIZONTAL`. Every option, tick-mark method, and the `enabledRangeProperty` behavior documented on [`HSlider`](/api/sun/hslider) applies identically here — only the layout axis differs, so reach for `VSlider` purely as a layout choice (e.g. a volume fader or a vertical thermometer-style control) rather than as a separately-behaving component.

```ts
import { VSlider } from 'scenerystack/sun';
import { NumberProperty } from 'scenerystack/axon';
import { Range } from 'scenerystack/dot';
import { Tandem } from 'scenerystack/tandem';

const volumeProperty = new NumberProperty( 50, {
  range: new Range( 0, 100 )
} );

const volumeSlider = new VSlider( volumeProperty, new Range( 0, 100 ), {
  tandem: Tandem.REQUIRED
} );
```

As with `HSlider`, dragging the thumb (now vertically) or clicking the track sets `volumeProperty.value`, clamped to the range; the thumb's position updates automatically whenever the value or the enabled range changes elsewhere.

## Options

`VSliderOptions` is `SliderOptions` with `orientation` removed (it's always vertical) — the same table documented on [HSlider's Options](/api/sun/hslider#options) applies: `trackSize`, `thumbSize`, `thumbFill`/`thumbFillHighlighted`, `trackFillEnabled`/`trackFillDisabled`, `constrainValue`, `enabledRangeProperty`, `trackNode`/`thumbNode`, and the `startDrag`/`drag`/`endDrag` hooks.

## Adding tick marks

Tick marks work identically to `HSlider` — `addMajorTick`/`addMinorTick` place ticks perpendicular to the (now vertical) track:

```ts
volumeSlider.addMajorTick( 0, new Text( '0%' ) );
volumeSlider.addMajorTick( 100, new Text( '100%' ) );
```

::: tip `trackSize` swaps meaning with orientation
For a vertical slider, `trackSize`'s `width` is the track's thickness and `height` is its length along the direction of travel — the opposite of how the same `Dimension2` reads for `HSlider`. If you're sharing a `trackSize` constant between horizontal and vertical sliders in the same sim, remember to swap its dimensions rather than reusing it as-is.
:::


========================================================================
Page: How tambo's Sound Generation Fits Together
URL: https://veillette.github.io/Almanach/api/tambo/sound-generation-guide
Source: docs/api/tambo/sound-generation-guide.md
Category: API | Tags: tambo, sound, WebAudio, soundManager, SoundGenerator, overview | Status: verified
========================================================================

# How tambo's Sound Generation Fits Together

`tambo` (`scenerystack/tambo`) is SceneryStack's sound-generation library. This page connects the pieces documented individually elsewhere — [`soundManager`](/api/tambo/sound-manager), [`SoundClip`](/api/tambo/sound-clip), [`SoundClipPlayer`](/api/tambo/sound-clip-player), and [`PitchedPopGenerator`](/api/tambo/pitched-pop-generator) — into one mental model. It's written as a synthesized overview rather than a single-class reference, so treat it as a map rather than an exhaustive spec; verify specifics against the individual class pages or source.

## The mixer/registry: soundManager

Everything routes through the single `soundManager` singleton. It owns the shared `AudioContext` signal chain — a limiter, a reverb send, per-category gain nodes, and a "ducking" stage that reduces overall volume while, say, Voicing speech is playing — and every sound generator connects into that graph via `soundManager.addSoundGenerator(generator, { categoryName? })`. Nothing plays until a sim calls `soundManager.initialize(...)` once at startup; calls to `addSoundGenerator` made before that are queued and flushed automatically.

## The sound generators: implementations you register

`SoundGenerator` is the abstract base class (also exported from `scenerystack/tambo` for anyone building a custom one). The concrete implementations documented here are all subclasses of it:

- **`SoundClip`** plays a pre-recorded, decoded audio buffer — one-shot or looping. Most sim sound effects (clicks, boundary boops, ambient loops) are `SoundClip`s.
- **`SoundClipPlayer`** wraps a `SoundClip` and self-registers with `soundManager`, exposing only `play()`/`stop()` — meant for a sound that's reused across many unrelated call sites and shouldn't have its output level or rate mutated ad hoc from any one of them.
- **`PitchedPopGenerator`** synthesizes a short oscillator "pop" at a pitch chosen per-call from a configurable range, rather than playing recorded audio — a good fit for sonifying a value moving along a continuum (sliders, spinners) without needing one recorded file per pitch step.

Other `SoundGenerator` subclasses exist in the real package (`NoiseGenerator`, `MultiClip`, `OscillatorSoundGenerator`, `CompositeSoundClip`, and more) but aren't covered on this pass — see `tambo.ts`'s exports if you need one of those.

## Enabled-state gating: why a registered sound might still be silent

Every `SoundGenerator` computes a `fullyEnabledProperty` by combining several signals — not just its own on/off switch:

1. `soundManager.enabledProperty` — the sim-wide sound master switch.
2. The sound generator's own `enabledProperty` (inherited from `EnabledComponent`).
3. Whether the sim is currently mid-"reset all" (`isResettingAllProperty`) — most sounds are suppressed during a reset unless `enabledDuringReset` was set.
4. Whether PhET-iO state is currently being restored (`isSettingPhetioStateProperty`) — sounds are suppressed unless `enabledDuringPhetioStateSetting` was set.
5. Whether an optional `associatedViewNode` is currently displayed — a looping sound tied to a Node that just became invisible is automatically muted.
6. Its `sonificationLevel` (`BASIC` or `EXTRA`) versus `soundManager.extraSoundEnabledProperty` — `EXTRA`-level sounds only play when the sim's "extra sound" preference is on.

A `SoundClip` or `PitchedPopGenerator` being "registered" with `soundManager` is therefore necessary but not sufficient for it to actually make noise — all of the above must also line up. `SoundClip` additionally auto-stops any in-progress one-shot the instant `fullyEnabledProperty` goes false.

## Categories and output levels

`soundManager.initialize()` sets up named gain-node "categories" (default `sim-specific` and `user-interface`); passing `categoryName` to `addSoundGenerator` routes that generator through its category's gain node, so `setOutputLevelForCategory('user-interface', 0.3)` can turn down all UI clicks without touching sim-specific sound effects.

::: tip Start from soundManager, not from the generator classes
When wiring up sound in a new screen, the natural order is: decide what should make sound, pick a `SoundGenerator` subclass for it, construct it, then call `soundManager.addSoundGenerator(...)`. Skipping the registration step is the most common way a sound "silently doesn't work" — the generator plays into a disconnected gain node until it's added.
:::


========================================================================
Page: PitchedPopGenerator
URL: https://veillette.github.io/Almanach/api/tambo/pitched-pop-generator
Source: docs/api/tambo/pitched-pop-generator.md
Category: API | Tags: tambo, PitchedPopGenerator, sound, WebAudio, oscillator | Status: verified
========================================================================

# PitchedPopGenerator

`PitchedPopGenerator` (from `scenerystack/tambo`, in `sound-generators/PitchedPopGenerator.ts`) is a `SoundGenerator` that synthesizes its sound rather than playing a pre-recorded clip: a short sine-oscillator "pop" whose pitch is chosen at play time from within a configurable frequency range. It's a good fit for sonifying a value that moves along a continuum — e.g. a slider or number spinner — where you want a distinct pop per step whose pitch tracks the value, without needing dozens of pre-recorded audio files.

Internally it pools several oscillator+gain pairs (`numPopGenerators`, default 8) and cycles through them round-robin, so overlapping pops (e.g. rapid keyboard repeat) don't cut each other off, and routes them through a `DynamicsCompressorNode` to avoid clipping when several play close together.

```ts
import { PitchedPopGenerator, soundManager } from 'scenerystack/tambo';
import { Range } from 'scenerystack/dot';
```

## A minimal example

```ts
const popGenerator = new PitchedPopGenerator( {
  pitchRange: new Range( 220, 660 )
} );

soundManager.addSoundGenerator( popGenerator );

// relativePitch is 0-1 within pitchRange, e.g. mapping a NumberProperty's normalized value
someNumberProperty.link( value => {
  const relativePitch = ( value - range.min ) / ( range.max - range.min );
  popGenerator.playPop( relativePitch );
} );
```

## Constructor

```ts
new PitchedPopGenerator( providedOptions?: PitchedPopGeneratorOptions )
```

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `pitchRange` | `new Range( 220, 660 )` | The frequency range (in Hz) that `playPop`'s `relativePitch` argument maps into |
| `numPopGenerators` | `8` | Size of the pooled oscillator/gain pairs; raise it if pops need to overlap more than 8 at once |
| `initialOutputLevel`, `sonificationLevel`, `associatedViewNode`, ... | — | Inherited from the base `SoundGenerator` — see [How tambo's Sound Generation Fits Together](/api/tambo/sound-generation-guide) |

## Methods

| Method | Effect |
| --- | --- |
| `playPop( relativePitch: number, duration = 0.02 )` | Plays a pop at the frequency corresponding to `relativePitch` (`0` = `pitchRange.min`, `1` = `pitchRange.max`); ignored entirely if the generator isn't `fullyEnabled` |

::: tip `relativePitch` is normalized, not a raw frequency
`playPop` takes a `0`-`1` proportion of `pitchRange`, not a frequency in Hz — you're responsible for normalizing your model value (e.g. `(value - min) / (max - min)`) before calling it. Passing a value outside `[0, 1]` fails an assertion.
:::


========================================================================
Page: SoundClip
URL: https://veillette.github.io/Almanach/api/tambo/sound-clip
Source: docs/api/tambo/sound-clip.md
Category: API | Tags: tambo, SoundClip, sound, WebAudio | Status: verified
========================================================================

# SoundClip

`SoundClip` (from `scenerystack/tambo`, in `sound-generators/SoundClip.ts`) is the workhorse `SoundGenerator` for playing pre-recorded audio — a decoded `AudioBuffer` wrapped in a `WrappedAudioBuffer` (the object produced by a `*_mp3.js`/`*_wav.js` sound asset import). It can be played as a single one-shot or looped continuously, supports multiple overlapping plays of the same clip, and exposes a settable playback rate.

```ts
import { SoundClip, soundManager, boundaryReached_mp3, saturatedSineLoop220Hz_mp3 } from 'scenerystack/tambo';
```

## A minimal example

```ts
const boundarySound = new SoundClip( boundaryReached_mp3, {
  initialOutputLevel: 0.6
} );

soundManager.addSoundGenerator( boundarySound, { categoryName: 'sim-specific' } );

// Later, in response to some model event:
boundarySound.play();
```

A looping clip works the same way, just with `loop: true`, and is started/stopped rather than fired-and-forgotten:

```ts
const humSound = new SoundClip( saturatedSineLoop220Hz_mp3, { loop: true } );
soundManager.addSoundGenerator( humSound );

motorIsRunningProperty.link( isRunning => {
  isRunning ? humSound.play() : humSound.stop();
} );
```

## Constructor

```ts
new SoundClip( wrappedAudioBuffer: WrappedAudioBuffer, providedOptions?: SoundClipOptions )
```

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `loop` | `false` | Whether the clip wraps around and repeats, rather than playing once |
| `trimSilence` | `true` | Detects and skips leading/trailing silence in the audio buffer when playing/looping |
| `initialPlaybackRate` | `1` | Multiplier on playback speed (and pitch) — `0.5` is an octave down, `2` is an octave up |
| `initiateWhenDisabled` | `false` | If `true`, a one-shot sound already in flight can still start even while the generator isn't fully enabled (ignored for loops) |
| `rateChangesAffectPlayingSounds` | `true` | Whether `setPlaybackRate()` retunes buffers that are already playing, or only future plays |
| `initialOutputLevel`, `sonificationLevel`, `associatedViewNode`, `enabledDuringReset`, ... | — | Inherited from the base `SoundGenerator` — see [How tambo's Sound Generation Fits Together](/api/tambo/sound-generation-guide) |

## Methods

| Method | Effect |
| --- | --- |
| `play( delay = 0 )` | Starts playback (after an optional delay, in seconds). If the shared `AudioContext` is still `suspended`, the call is deferred and fired once it resumes |
| `stop( delay = 0.1 )` | Fades out and stops all currently-playing instances of this clip; the delay avoids audible clicks |
| `setPlaybackRate( rate, timeConstant? )` / `getPlaybackRate()` / `.playbackRate` | Get/set the playback-rate multiplier |
| `get isPlaying` / `isPlayingProperty` | Whether the clip currently has an active buffer source |
| `getNumberOfPlayingInstances()` | How many overlapping instances of this clip are currently sounding — useful for capping concurrent plays |

::: tip One-shots are cut off when the generator becomes disabled
A non-looping `SoundClip` calls `this.stop()` automatically whenever `fullyEnabledProperty` transitions to `false` (e.g. sound gets globally disabled mid-playback) — unless `initiateWhenDisabled` changes the calculus for newly-started sounds. Loops are never auto-stopped this way; you're expected to call `stop()` yourself when the looping condition ends.
:::


========================================================================
Page: SoundClipPlayer
URL: https://veillette.github.io/Almanach/api/tambo/sound-clip-player
Source: docs/api/tambo/sound-clip-player.md
Category: API | Tags: tambo, SoundClipPlayer, sound, WebAudio | Status: verified
========================================================================

# SoundClipPlayer

`SoundClipPlayer` (from `scenerystack/tambo`) wraps a `SoundClip` and automatically registers it with [`soundManager`](/api/tambo/sound-manager) at construction time, exposing only `play()` and `stop()`. It exists for sounds that are reused in many unrelated places in a sim (a common click, a boundary-reached boop) where you don't want every call site to construct and register its own `SoundClip`, and don't want that shared instance's output level or playback rate to be casually mutated from far-flung code.

```ts
import { SoundClipPlayer, click_mp3 } from 'scenerystack/tambo';
```

## A minimal example

```ts
const clickSoundPlayer = new SoundClipPlayer( click_mp3, {
  soundClipOptions: { initialOutputLevel: 0.5 },
  soundManagerOptions: { categoryName: 'user-interface' }
} );

// Anywhere in the sim that needs this sound:
clickSoundPlayer.play();
```

## Constructor

```ts
new SoundClipPlayer( wrappedAudioBuffer: WrappedAudioBuffer, providedOptions?: SoundClipPlayerOptions )
```

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `soundClipOptions` | `{}` | Forwarded to the internal `SoundClip` constructor — e.g. `loop`, `initialOutputLevel`, `initialPlaybackRate` |
| `soundManagerOptions` | `{}` | Forwarded to `soundManager.addSoundGenerator()` — e.g. `categoryName` |

## Methods

| Method | Effect |
| --- | --- |
| `play()` | Plays the wrapped `SoundClip` |
| `stop()` | Stops the wrapped `SoundClip` if it's playing; a no-op otherwise |

::: tip It intentionally doesn't expose the underlying SoundClip
`SoundClipPlayer` only supports `play()` and `stop()` by design — it's meant to keep a shared sound's output level and playback rate from being altered ad hoc by whichever code happens to call it. If you need to control output level, playback rate, or looping behavior per call site, construct your own [`SoundClip`](/api/tambo/sound-clip) instead and register it with `soundManager` directly.
:::


========================================================================
Page: soundManager
URL: https://veillette.github.io/Almanach/api/tambo/sound-manager
Source: docs/api/tambo/sound-manager.md
Category: API | Tags: tambo, soundManager, sound, singleton, WebAudio | Status: verified
========================================================================

# soundManager

`soundManager` (from `scenerystack/tambo`) is a singleton — not a class you instantiate — that every tambo sound generator ultimately connects through. It owns the shared `AudioContext` signal chain (a dynamics compressor limiter, a convolver-based reverb send, per-category gain nodes, and a "ducking" gain stage), and exposes the register/unregister API that individual `SoundGenerator` instances (like `SoundClip` and `PitchedPopGenerator`) use to reach the speakers. A sim must call `soundManager.initialize(...)` once before any sound generator can be added; until then, `addSoundGenerator` calls are queued and flushed automatically on initialization.

```ts
import { soundManager } from 'scenerystack/tambo';
import { SoundClip } from 'scenerystack/tambo';
import myClick_mp3 from './myClick_mp3.js';
```

## Registering a sound generator

```ts
const clickSound = new SoundClip( myClick_mp3, { initialOutputLevel: 0.7 } );

// Connects clickSound into the shared audio graph (reverb + dry paths).
soundManager.addSoundGenerator( clickSound, {
  categoryName: 'user-interface' // one of the categories passed to initialize(), or omit for the default routing
} );

// Later, if the sound generator is disposed:
soundManager.removeSoundGenerator( clickSound );
```

If `soundManager.initialize()` hasn't run yet (e.g. sound isn't supported in this sim), `addSoundGenerator` silently queues the request rather than throwing — it's flushed once `initialize()` completes.

## Key members

| Member | Description |
| --- | --- |
| `enabledProperty` | `BooleanProperty` — master on/off switch for all sound; sound generators go silent (via their own `fullyEnabledProperty`) when this is `false` |
| `extraSoundEnabledProperty` | `BooleanProperty` — enables sound generators registered at the "extra" sonification level (see `SoundLevelEnum`), used for supplementary sounds aimed at learners with visual disabilities |
| `initialized` | `boolean` — becomes `true` after `initialize()` runs; sound generators can't be meaningfully added before this |
| `mainOutputLevel` / `getMainOutputLevel()` / `setMainOutputLevel(level)` | Overall gain (0-1) applied to all registered sound, when `enabledProperty` is true |
| `reverbLevel` / `getReverbLevel()` / `setReverbLevel(level)` | Wet/dry mix (0-1) for the shared convolver-based reverb send |

## Methods

| Method | Effect |
| --- | --- |
| `initialize(simConstructionCompleteProperty, audioEnabledProperty, simVisibleProperty, simActiveProperty, simSettingPhetioStateProperty, options?)` | One-time setup: builds the audio graph, wires the gain-shutoff `Multilink`, and flushes any queued sound generators. `options.categories` (default `['sim-specific', 'user-interface']`) defines the category names available to `addSoundGenerator` |
| `hasSoundGenerator(soundGenerator)` | Returns whether a given sound generator is currently registered |
| `addSoundGenerator(soundGenerator, options?)` | Connects the sound generator into the graph — either a named `categoryName` gain node or the default convolver/dry paths — and adds it to the internal list |
| `removeSoundGenerator(soundGenerator)` | Disconnects and removes a previously-added sound generator |
| `setOutputLevelForCategory(categoryName, level)` / `getOutputLevelForCategory(categoryName)` | Per-category gain control, e.g. turning down all `'user-interface'` sounds independent of `'sim-specific'` ones |
| `addDuckingProperty(property)` / `removeDuckingProperty(property)` | Registers a `TReadOnlyProperty<boolean>` that, when `true`, temporarily reduces overall output (used so sound effects duck under Voicing speech) |

::: tip Sound generators still gate themselves
`soundManager.enabledProperty` being `true` doesn't guarantee a given `SoundClip` or `PitchedPopGenerator` actually plays — each `SoundGenerator` computes its own `fullyEnabledProperty` from `soundManager.enabledProperty` **and** its own `enabledProperty`, sonification level, associated-view-node visibility, and whether the sim is mid-reset or setting PhET-iO state. See [How tambo's Sound Generation Fits Together](/api/tambo/sound-generation-guide) for how these layers compose.
:::


========================================================================
Page: Built-in IOTypes
URL: https://veillette.github.io/Almanach/api/tandem/built-in-io-types
Source: docs/api/tandem/built-in-io-types.md
Category: API | Tags: tandem, phet-io, IOType, BooleanIO, NumberIO, StringIO, ReferenceIO, ArrayIO, EnumerationIO, MapIO, NullableIO, ObjectLiteralIO, OrIO, Float64ArrayIO, VoidIO | Status: complete
========================================================================

# Built-in IOTypes

`scenerystack/tandem` ships a set of ready-made [`IOType`](/api/tandem/io-type) instances covering JS primitives and the handful of container shapes PhET-iO serialization needs over and over — so most `phetioValueType`/`phetioType` options in sim code reference one of these rather than a hand-authored `IOType`. Some are plain constants (`BooleanIO`); others are parametric *functions* that build (and cache) a fresh `IOType` for a given parameter type the first time you call them with it (`ArrayIO( NumberIO )`).

```ts
import {
  BooleanIO, NumberIO, StringIO, ReferenceIO, ArrayIO, EnumerationIO,
  MapIO, NullableIO, ObjectLiteralIO, OrIO, Float64ArrayIO, VoidIO
} from 'scenerystack/tandem';
```

## Non-parametric IOTypes

| IOType | Wraps | Notes |
| --- | --- | --- |
| `BooleanIO` | JS `boolean` | Identity serialization; state schema is a plain `'boolean'` value |
| `NumberIO` | JS `number` | Identity serialization; rejects `NaN` and `±Infinity` in its state-object validity check (see `InfiniteNumberIO` if you need to allow those) |
| `StringIO` | JS `string` | Identity serialization |
| `ObjectLiteralIO` | A plain object literal (`Object.getPrototypeOf(x) === Object.prototype`) | For ad hoc data bags that aren't worth a dedicated class; identity serialization |
| `VoidIO` | "no value" | Used to mark a function's return type (in an `IOType`'s `methods`) as having nothing meaningful to serialize back to the client |

## Parametric IOTypes (call them with parameter type(s))

| IOType | Signature | Notes |
| --- | --- | --- |
| `ArrayIO` | `ArrayIO( elementType )` | State is `elementType.toStateObject(x)` mapped over the array; validates every element against `elementType`'s validator |
| `NullableIO` | `NullableIO( parameterType )` | Adds `null` on top of `parameterType`'s existing behavior — `toStateObject`/`fromStateObject` both special-case `null` before delegating |
| `ReferenceIO` | `ReferenceIO( parameterType )` | Serializes to `{ phetioID }` (the referenced element's address) rather than its data — see warning below |
| `MapIO` | `MapIO( keyType, valueType )` | Serializes a JS `Map` as an array of `[keyState, valueState]` tuples |
| `OrIO` | `OrIO( [ typeA, typeB, … ] )` | A composite for "one of several types" — tries each `parameterType`'s validator in order and tags the serialized state with which one matched (`{ index, state }`) |
| `EnumerationIO` | `EnumerationIO( MyEnumeration )` | Given a `phet-core` `Enumeration`, serializes each value as its string key (e.g. `'HIGH'`) |
| `Float64ArrayIO` | (non-parametric, but listed here since it wraps a typed array) | Serializes a `Float64Array` as a plain `number[]`; supports `applyState` for updating an existing typed array in place |

## When to use a built-in IOType vs. defining a custom one

Composing built-in `IOType`s covers almost everything: a `Property<number>` uses `phetioValueType: NumberIO`; a `Property<number | null>` uses `NullableIO( NumberIO )`; a `Property<MyEnum>` uses `EnumerationIO( MyEnumeration )`. You reach for a **custom** `IOType` (as described in [IOType](/api/tandem/io-type)) only when:

- Your class isn't a `Property` wrapping one of these shapes — it's a [`PhetioObject`](/api/tandem/phetio-object) subclass with several fields that together need one composite `stateSchema`.
- You need custom `methods` exposed to PhET-iO clients (the built-in types expose none).
- None of the built-ins compose to describe your shape — e.g. a fixed-shape object (not a `Map`/`Array`) with several typed fields is usually better served by a `stateSchema` object literal (`{ x: NumberIO, y: NumberIO }`) directly on a custom `IOType`, rather than `ObjectLiteralIO`, which validates only that the value is *some* plain object with no schema at all.

::: warning `ReferenceIO` only works for instrumented `PhetioObject`s
`ReferenceIO(SomeIOType).toStateObject(x)` asserts that `x.isPhetioInstrumented()` is `true` under `Tandem.VALIDATION` — it serializes to `{ phetioID: x.tandem.phetioID }`, a pointer, not the object's data. If you reach for `ReferenceIO` for a value that isn't itself a real PhET-iO Element with a stable `phetioID` (e.g. a plain data object), you want a data-type `IOType` (with a real `toStateObject`/`stateSchema`) instead — `ReferenceIO` will look like it works until you try to deserialize state and hit `CouldNotYetDeserializeError` for an element that was never registered.
:::


========================================================================
Page: Disposable
URL: https://veillette.github.io/Almanach/api/tandem/disposable
Source: docs/api/tandem/disposable.md
Category: API | Tags: tandem, axon, Disposable, dispose, lifecycle | Status: verified
========================================================================

# Disposable

`Disposable`'s real import is `scenerystack/axon`, not `scenerystack/tandem` — but it's documented in this section because [`PhetioObject`](/api/tandem/phetio-object) extends it directly, making it the base of the dispose lifecycle for every instrumented class in the tandem/phet-io world (and, transitively, every `Node`, `Property`, and UI component built on `PhetioObject`). If you're calling `super.dispose()` inside an overridden `dispose()` method anywhere in a `PhetioObject` subclass, this is the class whose `dispose()` you eventually reach at the top of the chain.

```ts
import { Disposable, type DisposableOptions } from 'scenerystack/axon';

class MyResource extends Disposable {
  public constructor( providedOptions?: DisposableOptions ) {
    super( providedOptions );
  }

  public override dispose(): void {
    // ...clean up anything this class uniquely created...
    super.dispose(); // marks isDisposed, fires disposeEmitter
  }
}
```

Most SceneryStack code never extends `Disposable` directly — you get it for free through `Node` or `PhetioObject` — but understanding it clarifies exactly what `dispose()` guarantees you across the whole class hierarchy. See [Dispose and Memory Management](/patterns/dispose-and-memory-management) for the broader convention of when *you* need to write disposal code at all.

## What `dispose()` guarantees

- `isDisposed` flips to `true` only after `disposeEmitter` has fired — so a `disposeEmitter` listener always runs on a not-yet-`isDisposed` instance.
- Disposing twice is a hard error: `dispose()` asserts if called on an already-disposed instance.
- `disposeEmitter` fires *after* all prototype `dispose()` methods up the chain have run (i.e., after your subclass's own cleanup logic), so don't assume the object's fields are already torn down inside a `disposeEmitter` listener registered from outside the class.

## Instance members

| Member | Description |
| --- | --- |
| `isDisposed` | `true` once `dispose()` has completed |
| `isDisposable` | Settable flag; set to `false` to make this instance assert if anyone tries to dispose it |
| `disposeEmitter` | `TReadOnlyEmitter` that fires once, after disposal completes |
| `dispose()` | Runs cleanup and fires `disposeEmitter`; override to add your own logic, always calling `super.dispose()` |
| `addDisposable( ...disposables )` | Registers other `{ dispose(): void }` objects to be disposed automatically when this instance is |

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `isDisposable` | `true` | If `false`, this instance can never be disposed — useful for objects meant to exist for the sim's entire lifetime, where an accidental `dispose()` call should fail loudly instead of silently tearing down a permanent object |

::: tip `isDisposable: false` turns "should never be disposed" into an enforced invariant
Rather than just documenting that some long-lived singleton (an "About" dialog, a top-level model) should never be disposed, set `isDisposable: false` on it. Any accidental `dispose()` call anywhere in the codebase then fails an assertion immediately at the call site, instead of silently corrupting state or being caught only by manual review.
:::


========================================================================
Page: IOType
URL: https://veillette.github.io/Almanach/api/tandem/io-type
Source: docs/api/tandem/io-type.md
Category: API | Tags: tandem, phet-io, IOType | Status: verified
========================================================================

# IOType

`IOType` (from `scenerystack/tandem`) is the class behind every `phetioType` option you pass to a [`PhetioObject`](/api/tandem/phetio-object) — it declares how a PhET-iO Element serializes to/from state, what public methods it exposes to the wrapper frame, and how it documents itself in Studio, all independent of the class's actual TypeScript implementation. `scenerystack/tandem` ships one for nearly every JS primitive (`BooleanIO`, `NumberIO`, `StringIO`, `ArrayIO`, `NullableIO`, …); you construct your own only when a custom class needs to describe serialization that composing existing `IOType`s doesn't already cover.

```ts
import { IOType, NumberIO } from 'scenerystack/tandem';

type PositionStateObject = { x: number; y: number };

const PositionIO = new IOType<Position, PositionStateObject>( 'PositionIO', {
  valueType: Position,
  documentation: 'A 2D position with x and y in model coordinates.',
  stateSchema: {
    x: NumberIO,
    y: NumberIO
  },
  toStateObject: position => ( { x: position.x, y: position.y } ),
  applyState: ( position, state ) => {
    position.x = state.x;
    position.y = state.y;
  }
} );
```

Every `IOType`'s name must end in `IO` (parametric types append their parameter in angle brackets, e.g. `PhetioGroupIO<ParticleIO>`) — `IOType` asserts this convention when computing a type's "core" name for documentation.

## The type hierarchy: `supertype`

`IOType`s form their own hierarchy via the `supertype` option, defaulting to `IOType.ObjectIO` (the root of the entire tree). Fields like `toStateObject`, `applyState`, and `methods` are inherited from `supertype` unless overridden at this level — so a `stateSchema` composed of already-declared `IOType`s (like `NumberIO` above) usually gets a working default `toStateObject`/`applyState` for free, without writing either function by hand.

## Key options

| Option | Default | Effect |
| --- | --- | --- |
| `supertype` | `IOType.ObjectIO` | Parent in the IOType hierarchy; inherited serialization/methods flow from here |
| `valueType` | — | A validator (constructor, string, or array of either) checking that instances are the expected runtime type |
| `documentation` | auto-generated | HTML-flavored text shown to PhET-iO clients in Studio |
| `stateSchema` | `null` | Either a composite object of `{ key: IOType }` pairs, or `StateSchema.asValue(...)` for primitive-like types (see `BooleanIO`) |
| `toStateObject` / `fromStateObject` | `null` | Explicit serialize/deserialize functions; often unnecessary if `stateSchema` is composite |
| `applyState` | `null` | Mutates an existing instance to match a deserialized state, used when setting PhET-iO state on a live object |
| `methods` | `{}` | Public methods exposed to PhET-iO clients, each with `parameterTypes`, `returnType`, and an `implementation` |
| `parameterTypes` | `[]` | For parametric types like `PhetioGroupIO<T>` — the `IOType`(s) this type is parameterized over |
| `events` | `[]` | Names of events this level of the hierarchy can emit to the data stream |

## Static member

| Member | Description |
| --- | --- |
| `IOType.ObjectIO` | The root of the entire `IOType` hierarchy; every other `IOType`'s `supertype` chain eventually reaches this |

::: tip Most simulations never author a custom `IOType`
Composing already-instrumented `Property`s inside a plain model class (each `Property` carrying its own built-in `IOType` like `NumberIO`/`BooleanProperty`'s `BooleanIO`) covers the overwhelming majority of PhET-iO instrumentation needs — see [PhET-iO and Instrumentation](/guides/phet-io-and-instrumentation#iotype-describing-serialization). Reach for a hand-written `IOType` only when a class holds state that isn't already expressed as instrumented `Property`s, such as the dynamic-element containers [`PhetioGroup`](/api/tandem/phetio-group) and [`PhetioCapsule`](/api/tandem/phetio-capsule).
:::


========================================================================
Page: PhetioCapsule
URL: https://veillette.github.io/Almanach/api/tandem/phetio-capsule
Source: docs/api/tandem/phetio-capsule.md
Category: API | Tags: tandem, phet-io, PhetioCapsule, dynamic-elements | Status: verified
========================================================================

# PhetioCapsule

`PhetioCapsule` (from `scenerystack/tandem`) manages a single, lazily-created [`PhetioObject`](/api/tandem/phetio-object) that can be created, disposed, and recreated over a simulation's lifetime — the PhET-iO-aware way to say "this dialog/panel doesn't exist until the user first needs it," while still giving PhET-iO a stable identity and API surface to describe before it's ever built. It shares its "build an archetype first" mechanics with [`PhetioGroup`](/api/tandem/phetio-group), but holds at most one element instead of an indexed collection.

```ts
import { PhetioCapsule } from 'scenerystack/tandem';
import { Tandem } from 'scenerystack/tandem';
import { Dialog } from 'scenerystack/sun';

const preferencesDialogCapsule = new PhetioCapsule(
  tandem => new Dialog( preferencesContentNode, { tandem } ),
  [], // defaultArguments for building the archetype
  { tandem: Tandem.REQUIRED.createTandem( 'preferencesDialogCapsule' ) }
);

// Only actually constructs the Dialog the first time it's requested:
const preferencesDialog = preferencesDialogCapsule.getElement();
preferencesDialog.show();
```

As with `PhetioGroup`, `createElement` is called once up front with `defaultArguments` to build a hidden archetype so PhET-iO can describe the element's API before it's ever really created, and again — lazily, on first `getElement()` — to build the real instance.

## Methods

| Method | Effect |
| --- | --- |
| `getElement( ...args )` | Creates the element on first call (using `args`), then returns the same instance on subsequent calls |
| `hasElement()` | Whether the element currently exists |
| `create( args, fromStateSetting? )` | Lower-level create, primarily for internal/PhET-iO state-engine use — prefer `getElement()` |
| `disposeElement()` | Disposes the current element (used by the PhET-iO state engine when recreating the capsule's contents from saved state) |
| `clear( options? )` | Disposes the element if `disposeOnClear` is set (the default) |

## Options specific to PhetioCapsule

| Option | Default | Effect |
| --- | --- | --- |
| `disposeOnClear` | `true` | If `false`, `clear()` is a no-op and the element is never disposed — appropriate for something like an "About" dialog that, once built, should persist for the sim's lifetime rather than being torn down and rebuilt |
| `disposeCreatedOnStateSet` | `false` | If `true`, forces disposal-and-recreation on every PhET-iO state set rather than reusing an existing element — only needed for capsules holding heterogeneous element types |

::: tip Reach for `PhetioCapsule` for "at most one, lazily built," not for permanent singletons
If something is constructed once at startup and lives for the sim's entire lifetime (most `Screen`-level view components), it doesn't need `PhetioCapsule` at all — just construct it directly. `PhetioCapsule` earns its keep specifically when construction is deferred (to avoid startup cost) or when the element can be destroyed and rebuilt later, and you still want PhET-iO to know about its shape ahead of time via the archetype.
:::


========================================================================
Page: PhetioGroup
URL: https://veillette.github.io/Almanach/api/tandem/phetio-group
Source: docs/api/tandem/phetio-group.md
Category: API | Tags: tandem, phet-io, PhetioGroup, dynamic-elements | Status: verified
========================================================================

# PhetioGroup

`PhetioGroup` (from `scenerystack/tandem`) manages a dynamically-growing/shrinking collection of same-shaped [`PhetioObject`](/api/tandem/phetio-object)s — the PhET-iO-aware equivalent of `const particles: Particle[] = []` for state you want save/restore, API validation, and Studio visibility on. Use it whenever a sim creates and destroys an unbounded, indexed set of instrumented elements at runtime — particles, balloons, graph points — rather than pushing/splicing a plain array yourself.

```ts
import { PhetioGroup } from 'scenerystack/tandem';
import { Tandem } from 'scenerystack/tandem';

class Particle {
  public constructor( public readonly tandem: Tandem, public x: number ) {}
}

const particleGroup = new PhetioGroup(
  ( tandem, x: number ) => new Particle( tandem, x ), // createElement
  [ 0 ],                                              // defaultArguments, used to build the archetype
  { tandem: Tandem.REQUIRED.createTandem( 'particleGroup' ) }
);

const particle = particleGroup.createNextElement( 10 );
// ...later, when the particle should disappear:
particleGroup.disposeElement( particle );
```

The `createElement` function is called once up front (with `defaultArguments`) to build a hidden "archetype" — a template instance PhET-iO uses to know the group's element API and baseline metadata before any real elements exist — and again for every element you actually create via `createNextElement`. Elements are named `<groupName>_0`, `<groupName>_1`, … automatically, indexed from `groupElementStartingIndex` (default `1`).

## Methods

| Method | Effect |
| --- | --- |
| `createNextElement( ...args )` | Creates and adds an element at the next available index |
| `disposeElement( element )` | Removes an element from the group and disposes it, updating `countProperty` |
| `getArray()` / `getArrayCopy()` | Reference to (or a defensive copy of) the underlying elements array |
| `clear( options? )` | Disposes every element currently in the group |
| `forEach( action )` / `map( f )` / `filter( predicate )` / `find( predicate )` | Array-like iteration helpers over the group's elements |
| `includes( element )` / `indexOf( element )` | Membership/position queries |
| `getElement( index )` / `getLastElement()` | Direct indexed access |

## Key state

| Member | Description |
| --- | --- |
| `countProperty` | Read-only, PhET-iO-instrumented `NumberProperty` tracking the current element count |

## PhetioGroup vs. PhetioCapsule

Both are "dynamic element container" subclasses of the shared `PhetioDynamicElementContainer` base, and both build an archetype the same way — the difference is cardinality. `PhetioGroup` manages *many* same-shaped elements at once (an indexed, growable array); [`PhetioCapsule`](/api/tandem/phetio-capsule) manages *at most one* element that can be created, disposed, and recreated over the sim's lifetime (e.g. a lazily-created dialog). Reach for `PhetioGroup` when you're modeling "a collection," and `PhetioCapsule` when you're modeling "one optional/lazy thing."

::: warning `PhetioGroup` itself is not disposable
Calling `.dispose()` on the group container asserts — a `PhetioGroup` is meant to exist for the lifetime of the sim (or its owning screen), even as the *elements inside it* are created and disposed freely via `createNextElement`/`disposeElement`. If you need the container itself to go away, you're likely looking for a differently-scoped structure, not a disposed `PhetioGroup`.
:::


========================================================================
Page: PhetioIDUtils and Tandem Naming Conventions
URL: https://veillette.github.io/Almanach/api/tandem/phetio-id-utils-and-naming
Source: docs/api/tandem/phetio-id-utils-and-naming.md
Category: API | Tags: tandem, phet-io, PhetioIDUtils, Tandem, phetioID | Status: complete
========================================================================

# PhetioIDUtils and Tandem Naming Conventions

`PhetioIDUtils` (from `scenerystack/tandem`) is a static-only utility class (its constructor asserts if called) providing string operations over `phetioID`s — the dotted addresses [`Tandem`](/api/tandem/tandem) builds as you call `createTandem()` down a tree. You reach for it when you need to manipulate a `phetioID` as a string directly — building one from parts, extracting the last segment, walking up to a parent — rather than through a live `Tandem` instance.

```ts
import { PhetioIDUtils } from 'scenerystack/tandem';
```

## Building and inspecting IDs

| Method | Example | Result |
| --- | --- | --- |
| `PhetioIDUtils.append( phetioID, ...names )` | `append( 'myScreen.myControlPanel', 'myComboBox' )` | `'myScreen.myControlPanel.myComboBox'` |
| `PhetioIDUtils.getComponentName( phetioID )` | `getComponentName( 'myScreen.myControlPanel.myComboBox' )` | `'myComboBox'` |
| `PhetioIDUtils.getParentID( phetioID )` | `getParentID( 'myScreen.myControlPanel.myComboBox' )` | `'myScreen.myControlPanel'` (or `null` at the root) |
| `PhetioIDUtils.getScreenID( phetioID )` | `getScreenID( 'sim.myScreen.model.property' )` | `'sim.myScreen'` (or `null` if no component name ends in `'Screen'`) |
| `PhetioIDUtils.isAncestor( ancestorID, descendantID )` | `isAncestor( 'sim.myScreen', 'sim.myScreen.model' )` | `true` (strictly an ancestor, not the same ID) |
| `PhetioIDUtils.getArchetypalPhetioID( phetioID )` | `getArchetypalPhetioID( 'sim.screen.group.particle_4.massProperty' )` | `'sim.screen.group.archetype.massProperty'` — replaces dynamic-element terms (containing `_`) with the literal `'archetype'` |
| `PhetioIDUtils.getGroupElementIndex( componentName )` | `getGroupElementIndex( 'particle_4' )` | `4` |

`PhetioIDUtils` never constructs or mutates a `Tandem` — it operates purely on the dotted string, which is why it's useful in PhET-iO client/wrapper code that only has the string address, not a live `Tandem` tree.

## Well-known static separators and component names

| Static member | Value | Used for |
| --- | --- | --- |
| `SEPARATOR` | `'.'` | Joins components into a `phetioID` |
| `GROUP_SEPARATOR` | `'_'` | Separates a dynamic element's group name from its index, e.g. `particle_4` |
| `INTER_TERM_SEPARATOR` | `'-'` | Joins terms within a single component when one `phetioID` references another, e.g. `sim-global-otherID` |
| `ARCHETYPE` | `'archetype'` | The placeholder component name `getArchetypalPhetioID` substitutes for dynamic-element terms |
| `CAPSULE_SUFFIX` | `'Capsule'` | Marks a component name as a `PhetioCapsule` container, so its next term maps to `ARCHETYPE` too |
| `GENERAL_COMPONENT_NAME` / `GLOBAL_COMPONENT_NAME` | `'general'` / `'global'` | The component names under which `Tandem.GENERAL_MODEL`/`GENERAL_VIEW`/etc. and `Tandem.GLOBAL_MODEL`/`GLOBAL_VIEW` nest |
| `MODEL_COMPONENT_NAME` / `VIEW_COMPONENT_NAME` / `CONTROLLER_COMPONENT_NAME` | `'model'` / `'view'` / `'controller'` | Conventional top-level component names within a screen's tandem subtree |

## Naming conventions built from a `Tandem` tree

A `phetioID` is just the dotted path of every `createTandem()` call made from `Tandem.ROOT` down to a specific element — `Tandem` builds these for you, but the shape follows fixed conventions `PhetioIDUtils` understands:

- **Screens** nest under a component name ending in `'Screen'` (`myScreen`, `secondScreen`) — this is what lets `getScreenID` find the screen boundary in an arbitrarily deep `phetioID`.
- **Model vs. view** code conventionally nests one level further under `model`/`view` (`MODEL_COMPONENT_NAME`/`VIEW_COMPONENT_NAME`), e.g. `sim.myScreen.model.temperatureProperty`.
- **Dynamic elements** (created at runtime by a `PhetioGroup`, indexed rather than named up front) get an underscore-joined index in their component name, e.g. `sim.myScreen.model.particles.particle_0` — `getGroupElementIndex` and `getArchetypalPhetioID` both key off that `_`.
- **Capsule contents** (a `PhetioCapsule`'s single dynamic element) follow the element name with the literal `'archetype'` when referring to the un-instantiated template instance, which is what `CAPSULE_SUFFIX` handling in `getArchetypalPhetioID` accounts for.

::: tip You almost never call `PhetioIDUtils` directly in sim code
Sim-author code builds `phetioID`s implicitly, by calling `tandem.createTandem( 'childName' )` — see [Tandem](/api/tandem/tandem) — not by concatenating strings with `PhetioIDUtils.append`. `PhetioIDUtils` matters most when you're writing PhET-iO wrapper/client code (Studio, the state engine, migration scripts) that only has a `phetioID` string to work with and needs to reason about its structure.
:::


========================================================================
Page: PhetioObject
URL: https://veillette.github.io/Almanach/api/tandem/phetio-object
Source: docs/api/tandem/phetio-object.md
Category: API | Tags: tandem, phet-io, PhetioObject | Status: verified
========================================================================

# PhetioObject

`PhetioObject` (from `scenerystack/tandem`) is the base class that gives any object PhET-iO instrumentation: a `tandem`, an `IOType` describing its serialization, and a fixed set of metadata flags (`phetioState`, `phetioReadOnly`, `phetioFeatured`, `phetioDocumentation`, …). You rarely instantiate it directly — `Property`, `Node`, `Emitter`, `Screen`, and most other instrumentable SceneryStack classes already extend it — but you extend it yourself when authoring a custom stateful class that needs its own PhET-iO presence rather than composing already-instrumented `Property`s.

```ts
import { PhetioObject, type PhetioObjectOptions, Tandem } from 'scenerystack/tandem';

type SelfOptions = { x?: number; y?: number };
type PositionOptions = SelfOptions & PhetioObjectOptions;

class Position extends PhetioObject {
  public x: number;
  public y: number;

  public constructor( providedOptions: PositionOptions ) {
    super( providedOptions );
    this.x = providedOptions.x ?? 0;
    this.y = providedOptions.y ?? 0;
  }
}

const origin = new Position( {
  x: 0, y: 0,
  tandem: Tandem.REQUIRED,
  phetioType: PositionIO // see IOType for how PositionIO would be declared
} );
```

`PhetioObject` extends [`Disposable`](/api/tandem/disposable), so every `PhetioObject` (and therefore every `Node`/`Property` built on it) already has `dispose()`, `isDisposed`, and `disposeEmitter` for free.

## Key behavior: initialization is conditional on being instrumented

The most important thing to understand about `PhetioObject` is that its PhET-iO machinery only fully activates when `PHET_IO_ENABLED && tandem.supplied` — that is, when the sim is actually running under the PhET-iO brand *and* a real (non-sentinel) `tandem` was passed in. Outside PhET-iO, `initializePhetioObject` returns early after recording the `tandem`/`phetioID` for tree-building purposes, without validating options or registering the object with the data stream. This is why getters like `phetioType`/`phetioState`/`phetioDocumentation` assert if you read them on an uninstrumented object — they're only meaningful once instrumentation actually happened.

## Constructor options

`PhetioObjectOptions` combines a handful of PhET-iO metadata fields with `DisposableOptions`:

| Option | Default | Effect |
| --- | --- | --- |
| `tandem` | `Tandem.OPTIONAL` | The instrumentation handle; subclasses often default this to `Tandem.REQUIRED` |
| `phetioType` | `IOType.ObjectIO` | Declares serialization/methods for this instance — see [IOType](/api/tandem/io-type) |
| `phetioState` | `true` | Whether this object's state is included in PhET-iO save/restore |
| `phetioReadOnly` | `false` | If `true`, external PhET-iO clients can read but not set this object |
| `phetioDocumentation` | `''` | Client-facing documentation shown in PhET-iO Studio; must not contain literal newlines (`<br>` instead) |
| `phetioFeatured` | `false` | Marks this element as one of the "featured" elements surfaced by default in Studio |
| `phetioEventType` | `EventType.MODEL` | Category tag applied to events this object emits via `phetioStartEvent`/`phetioEndEvent` |
| `tandemNameSuffix` | `null` | If set, asserts the tandem's name ends with this suffix (or an array of allowed suffixes) |

## Methods

| Method | Effect |
| --- | --- |
| `isPhetioInstrumented()` | `true` only if a real, supplied `tandem` was provided |
| `addLinkedElement( element, options? )` | Creates a one-way "symbolic link" to another `PhetioObject`, shown in Studio as a hyperlink — used by e.g. `NumberSpinner`/`NumberControl` to link their display to the `Property` they control |
| `phetioStartEvent( event, options? )` / `phetioEndEvent()` | Emits a nested event to the PhET-iO data stream, a no-op outside PhET-iO |
| `getMetadata( object? )` | Returns the plain-object metadata (`phetioTypeName`, `phetioState`, etc.) describing this instance or a metadata-shaped input |

::: warning `initializePhetioObject` can run after the constructor
Classes like `Node` need to support `mutate()`-style deferred configuration, so `PhetioObject` allows a subclass to call `super()` with no options and invoke `initializePhetioObject` later once real options are known. If you're authoring a subclass this way, keep in mind that `tandem`/`phetioID`/metadata all read as their un-instrumented defaults until that second call happens — don't read `phetioType`/`phetioDocumentation` in between.
:::


========================================================================
Page: Tandem
URL: https://veillette.github.io/Almanach/api/tandem/tandem
Source: docs/api/tandem/tandem.md
Category: API | Tags: tandem, phet-io, Tandem | Status: verified
========================================================================

# Tandem

`Tandem` (from `scenerystack/tandem`) is a node in a naming tree that gives every PhET-iO-instrumented element (a `Property`, a `Node`, a button, a `Screen`, …) a stable, hierarchical address like `mySim.myScreen.model.temperatureProperty`. You don't build a `Tandem` tree by hand for every element — you pass a parent `tandem` option down through your model/view and call `createTandem()` to extend it one level at a time as you construct children.

```ts
import { Tandem } from 'scenerystack/tandem';
```

## A minimal example

```ts
const screenTandem = Tandem.ROOT.createTandem( 'myScreen' );

class MyModel {
  public constructor( tandem: Tandem ) {
    const temperatureTandem = tandem.createTandem( 'temperatureProperty' );
    // pass temperatureTandem to a Property, button, etc. via its `tandem` option
  }
}

const model = new MyModel( screenTandem.createTandem( 'model' ) );
```

Each call to `createTandem( name )` returns (or reuses, if already created) a child `Tandem` whose `phetioID` is the parent's `phetioID` plus `.name` — you never construct a bare `new Tandem(...)` directly in sim code.

## Constructor

```ts
new Tandem( parentTandem: Tandem | null, name: string, providedOptions?: TandemOptions )
```

Sim code essentially never calls this directly — always use `someTandem.createTandem( 'childName' )` instead, which handles reuse and validation for you.

## Instance members

| Member | Description |
| --- | --- |
| `name` | The last path segment, e.g. `'temperatureProperty'` |
| `phetioID` | The fully-qualified dotted address, e.g. `'mySim.myScreen.model.temperatureProperty'` |
| `required` | Whether an object using this tandem must actually be supplied one (see `Tandem.REQUIRED`) |
| `supplied` | Whether a real (non-sentinel) tandem was actually provided |
| `createTandem( name, options? )` | Returns a child `Tandem`, creating it if it doesn't exist yet |
| `createGroupTandem( name, initialIndex? )` | Returns a `GroupTandem` for naming dynamically-created, indexed elements (`electron0`, `electron1`, …) |
| `hasAncestor( ancestor )` | Whether `ancestor` is somewhere above this tandem in the tree |
| `equals( tandem )` | Compares by `phetioID` |

## Well-known static tandems

| Static member | Use it for |
| --- | --- |
| `Tandem.ROOT` | The single root of the tree for this sim — the base every other tandem descends from |
| `Tandem.REQUIRED` | Default `tandem` value for common-code components that must be instrumented (e.g. buttons); throws in validated PhET-iO builds if never overridden with a real tandem |
| `Tandem.OPTIONAL` (alias `Tandem.OPT_OUT`) | Default for components that support instrumentation but don't require it |
| `Tandem.GENERAL_MODEL` / `Tandem.GENERAL_VIEW` / `Tandem.GENERAL_CONTROLLER` | Elements common to every sim, not specific to one screen |
| `Tandem.GLOBAL_MODEL` / `Tandem.GLOBAL_VIEW` | Sim-specific elements that don't belong to any one screen |
| `Tandem.PHET_IO_ENABLED` | Whether the sim is running under the PhET-iO brand at all |

::: tip `Tandem.REQUIRED` is a sentinel, not "no tandem needed"
Components like `ResetAllButton` or `NumberControl` default their `tandem` option to `Tandem.REQUIRED` precisely so that forgetting to supply a real one is loud (an assertion failure) rather than silently producing an uninstrumented, unaddressable element. Always pass a real `tandem.createTandem( '...' )` down from the screen's root tandem, even in a sim you never intend to run under PhET-iO.
:::


========================================================================
Page: VibrationIndicator and ContinuousPatternVibrationController
URL: https://veillette.github.io/Almanach/api/tappi/vibration-indicator-and-controller
Source: docs/api/tappi/vibration-indicator-and-controller.md
Category: API | Tags: tappi, VibrationIndicator, ContinuousPatternVibrationController, vibration, haptics | Status: verified
========================================================================

# VibrationIndicator and ContinuousPatternVibrationController

`VibrationIndicator` and `ContinuousPatternVibrationController` (both from `scenerystack/tappi`) are the UI and control-flow pieces alongside [`vibrationManager`](/api/tappi/vibration-manager-and-patterns): `VibrationIndicator` is a `Node` that visually represents whether vibration is currently active (useful for development/QA on a desktop where you can't feel the device vibrate), and `ContinuousPatternVibrationController` manages smooth transitions between vibration patterns so a pattern change doesn't feel like an abrupt jolt.

```ts
import { VibrationIndicator, ContinuousPatternVibrationController } from 'scenerystack/tappi';
import { BooleanProperty } from 'scenerystack/axon';
```

## A minimal example — VibrationIndicator

```ts
const vibratingProperty = new BooleanProperty( false );

// A small phone icon whose screen color and zig-zag "vibration lines" reflect vibratingProperty.
const vibrationIndicator = new VibrationIndicator( vibratingProperty );

this.addChild( vibrationIndicator );

// In your animation-frame loop:
vibrationIndicator.step( dt ); // dt in seconds -- jostles the icon while vibratingProperty is true
```

## Constructor — VibrationIndicator

```ts
new VibrationIndicator( vibratingProperty: Property<boolean> )
```

Takes no options object — it draws a fixed-size phone icon (a dark panel, a white phone body, a screen, a home button, a speaker, and two zig-zag "vibration" `Path`s) and links directly to `vibratingProperty` to toggle the screen color (`'lightblue'` vibrating / `'grey'` idle) and the visibility of the zig-zag lines.

### VibrationIndicator methods

| Member | Description |
| --- | --- |
| `step( dt )` | While `vibratingProperty` is `true`, jostles the two vibration-line `Path`s with a sinusoidal offset so they visibly shake; a no-op (net-zero motion) while idle |

## A minimal example — ContinuousPatternVibrationController

```ts
// NOTE: requires a VibrationManageriOS instance -- see the warning below.
const controller = new ContinuousPatternVibrationController( vibrationManageriOS, {
  activePattern: [ 0.1, 0.1, 0.1, 0.3 ], // on/off intervals, in seconds
  repeat: true
} );

controller.start();
// In your animation-frame loop:
controller.step( dt ); // dt in seconds

// Queue up a different pattern -- it takes effect at the end of the current loop, not mid-pattern.
controller.setPattern( [ 0.05, 0.05 ] );

controller.stop();
```

## Constructor — ContinuousPatternVibrationController

```ts
new ContinuousPatternVibrationController( vibrationManageriOS: VibrationManageriOS, providedOptions: ContinuousPatternVibrationControllerOptions )
```

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `activePattern` | `[]` | Initial on/off interval pattern, in **seconds** (unlike `vibrationManager`'s millisecond patterns); even indices are "on" |
| `repeat` | `true` | Whether the active pattern loops after finishing |
| `intensity` | `1` | Forwarded to `vibrationManageriOS.vibrateContinuous()` during "on" intervals |
| `sharpness` | `1` | Forwarded to `vibrationManageriOS.vibrateContinuous()` during "on" intervals |

## Methods

| Member | Description |
| --- | --- |
| `start()` | Begins playing `activePattern` from the beginning |
| `stop()` | Stops vibration and resets pattern position |
| `step( dt )` | Advances pattern timing (`dt` in seconds); must be called every frame while running |
| `setPattern( pattern )` | Sets a new pattern. If nothing is currently running, it becomes the active pattern immediately; if a pattern is running, it becomes "pending" and swaps in only once the current pattern loop finishes, to avoid an audible/tactile stutter mid-pattern |
| `setNewActivePattern( pattern )` | Forces the active pattern immediately (used internally by `setPattern`/`step` at a loop boundary) |
| `setIntensity( intensity )` / `setSharpness( sharpness )` | Update the values forwarded to `vibrationManageriOS.vibrateContinuous()` for subsequent "on" intervals |
| `setRepeat( repeat )` | Toggles whether the active pattern loops |

::: warning `ContinuousPatternVibrationController` depends on a class that isn't exported
Its constructor requires a `VibrationManageriOS` instance — the class that bridges to a native iOS WebView vibration handler. `VibrationManageriOS`'s own source marks it `@deprecated - This strategy is being abandoned for an android specific solution`, and it is **not** re-exported from `tappi.ts` — so there's no supported way to construct one from outside the SceneryStack repository itself. `VibrationIndicator` was verified against `scenerystack@3.0.0` source; `ContinuousPatternVibrationController` is documented here from source for completeness but is not usable through the public API.
:::


========================================================================
Page: vibrationManager and VibrationPatterns
URL: https://veillette.github.io/Almanach/api/tappi/vibration-manager-and-patterns
Source: docs/api/tappi/vibration-manager-and-patterns.md
Category: API | Tags: tappi, vibrationManager, VibrationPatterns, Intensity, vibration, haptics | Status: verified
========================================================================

# vibrationManager and VibrationPatterns

`vibrationManager` (from `scenerystack/tappi`, lowercase — a pre-constructed singleton instance, not a class) is the shared object that drives device vibration through the browser's [Web Vibration API](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/vibrate) (`navigator.vibrate`). It must be advanced every frame with `step( dt )`, and vibration is expressed as a repeating on/off interval pattern rather than a single duration. `VibrationPatterns` is a companion plain object of ready-made interval arrays (`FLUTTER`, `HEARTBEAT`, `HZ_10`, …) meant to be passed straight into `vibrationManager.startVibrate()`.

```ts
import { vibrationManager, VibrationPatterns, Intensity } from 'scenerystack/tappi';
```

## A minimal example

```ts
// Somewhere in your framework's step/animation-frame loop:
vibrationManager.step( dt ); // dt in seconds

// Begin a repeating vibration pattern (on/off intervals, in ms).
vibrationManager.startVibrate( VibrationPatterns.FLUTTER );

// ...later...
vibrationManager.stopVibrate();

// Or run a pattern for a fixed duration and have it stop automatically.
vibrationManager.startTimedVibrate( 2000, VibrationPatterns.HEARTBEAT );

// Intensity is a two-valued EnumerationValue enumeration (HIGH / LOW); vibrationManager
// mimics "low" intensity by rapidly toggling the motor on and off.
vibrationManager.setVibrationIntensity( Intensity.LOW );
```

## `vibrationManager` methods

| Member | Description |
| --- | --- |
| `initialize( simVisibleProperty, simActiveProperty )` | Wires up internal listeners so vibration stops automatically when the sim becomes invisible/inactive; intended to be called once by the hosting framework, not per-use |
| `startVibrate( pattern )` | Starts a repeating vibration described by `pattern` — an array of millisecond on/off durations (even indices are "on") that repeats indefinitely until `stopVibrate()` is called. Falls back to continuous vibration if `pattern` is falsy |
| `startTimedVibrate( time, pattern )` | Like `startVibrate`, but automatically calls `stopVibrate()` once `time` milliseconds have elapsed |
| `startRepeatingVibrationPattern( pattern )` | An alternate, more experimental path (noted as such in source) that expands `pattern` into a long repeated sequence and hands it to `navigator.vibrate()` directly, rather than driving the motor via `step()` |
| `stopRepeatingVibrationPattern()` | Stops a pattern started with `startRepeatingVibrationPattern()` |
| `stopVibrate()` | Immediately stops any running pattern |
| `setVibrationIntensity( intensity )` | Sets `Intensity.HIGH` (continuous motor-on) or `Intensity.LOW` (rapid on/off toggling to simulate lower intensity) |
| `isVibrating()` | Whether the motor should be actively on right now (accounts for pattern downtime) |
| `isRunningPattern()` | Whether a pattern is active at all, including during its "off" intervals |
| `step( dt )` | Advances internal pattern timing; `dt` is in seconds. Must be called every frame for `startVibrate`/`startTimedVibrate` patterns to progress |

## `VibrationPatterns` entries

| Pattern | Shape |
| --- | --- |
| `HZ_2_5`, `HZ_5`, `HZ_10`, `HZ_25`, `HZ_50`, `HZ_200` | Even on/off interval pairs approximating that frequency (the source notes `HZ_50`/`HZ_200` are faster than 60fps and may not render reliably through `step()`-driven timing) |
| `QUICK_BALL_ROLL`, `SLOW_BALL_ROLL` | Short two-value patterns suggesting a rolling motion |
| `FLUTTER` | A long, irregular multi-interval pattern |
| `SLOW_DOWN` | A pattern with increasing interval lengths |
| `HEARTBEAT`, `QUICK_HEARTBEAT` | Two-beat patterns with a long pause, approximating a heartbeat |
| `MOTOR_CALL` | `null` — shorthand for "no pattern," i.e. plain continuous vibration |
| `interactionSuccess( vibrationManageriOS )` | A function (not a pattern array) that fires three rapid transient vibrations; takes a `VibrationManageriOS` instance, a separate iOS-bridge class — see the warning below |

::: warning `VibrationPatterns.interactionSuccess` is not usable through the public API
`VibrationPatterns.interactionSuccess` takes a `VibrationManageriOS` parameter — a class whose own source marks it `@deprecated` and which is **not** re-exported from `tappi.ts`, so it isn't constructable via the public `scenerystack/tappi` API. All other exports and methods on this page were verified against `scenerystack@3.0.0` source.
:::


========================================================================
Page: Animation and Easing
URL: https://veillette.github.io/Almanach/api/twixt/animation
Source: docs/api/twixt/animation.md
Category: API | Tags: twixt, Animation, Easing | Status: verified
========================================================================

# Animation and Easing

`Animation` (from `scenerystack/twixt`) smoothly interpolates a Property's value — or an object attribute, or an arbitrary getter/setter pair — from a starting value to an ending value over time, instead of jumping to the new value instantly. `Easing` supplies the interpolation curve (linear, quadratic, cubic, …) that controls how the animation accelerates and decelerates.

```ts
import { Animation, Easing } from 'scenerystack/twixt';
import { NumberProperty } from 'scenerystack/axon';
```

## A minimal example

```ts
const opacityProperty = new NumberProperty( 1 );

const fadeOutAnimation = new Animation( {
  property: opacityProperty,
  to: 0,
  duration: 0.5, // seconds
  easing: Easing.QUADRATIC_IN_OUT
} );

fadeOutAnimation.start();
```

By default, `Animation` drives itself off axon's shared `stepTimer`, so once `start()` is called it advances every frame with no further wiring — no ScreenView or model `step()` call is required unless you pass `stepEmitter: null` and step it manually.

## Constructor

`Animation` takes a single config object — there's no separate positional-argument form:

```ts
new Animation( providedOptions: AnimationOptions )
```

## Options

Exactly one target-binding style and exactly one length source are required; `Animation` asserts if you provide zero or more than one of each.

| Option | Default | Effect |
| --- | --- | --- |
| `property` | — | An axon `Property` to animate directly (mutually exclusive with `object`/`setValue`/`targets`) |
| `object` + `attribute` | — | Animates `object[ attribute ]` in place |
| `setValue` (+ optional `getValue`) | — | Custom setter/getter pair, for values that aren't a Property or plain attribute |
| `targets` | `null` | An array of per-target configs (each shaped like the options above) to animate multiple values in lockstep from one `Animation` |
| `to` | — | The end value (mutually exclusive with `delta`) |
| `delta` | — | Animates by this much relative to the starting value, instead of to an absolute value |
| `duration` | `null` | Length of the animation in seconds — provide this **or** a `speed` on a target, never both |
| `delay` | `0` | Seconds to wait after `start()` before the value actually begins changing |
| `easing` | `Easing.CUBIC_IN_OUT` (via `AnimationTarget`) | Controls the rate of change over the animation's course |
| `from` | — | Overrides the starting value instead of reading the current value |
| `stepEmitter` | axon's `stepTimer` | The `Emitter<[number]>` that drives stepping; pass `null` to step manually via `.step( dt )` |

## Public state and events

| Member | Description |
| --- | --- |
| `runningProperty` | `true` for the whole run, including any initial `delay` |
| `animatingProperty` | `true` only once the value itself is actively changing (after the delay elapses) |
| `startEmitter` | Fires when `start()` is called |
| `beginEmitter` | Fires when the delay elapses and value interpolation begins |
| `updateEmitter` | Fires after each step's value update |
| `finishEmitter` | Fires `(overflowDt)` when the animation completes naturally |
| `stopEmitter` | Fires only if `stop()` is called before completion |
| `endedEmitter` | Fires whenever the animation ends, whether finished or stopped |

## Methods

| Method | Effect |
| --- | --- |
| `start( dt? )` | Begins the animation (or restarts the delay); no-op if already running |
| `stop()` | Immediately halts the animation, leaving the value wherever it was |
| `step( dt )` | Manually advances by `dt` seconds — only needed if `stepEmitter: null` |
| `then( animation )` | Chains another `Animation` to start when this one finishes naturally; returns the chained animation for further chaining |

## `Easing`

| Static member | Curve |
| --- | --- |
| `Easing.LINEAR` | Constant rate |
| `Easing.QUADRATIC_IN` / `_OUT` / `_IN_OUT` | t², eased in / out / both |
| `Easing.CUBIC_IN` / `_OUT` / `_IN_OUT` | t³ |
| `Easing.QUARTIC_IN` / `_OUT` / `_IN_OUT` | t⁴ |
| `Easing.QUINTIC_IN` / `_OUT` / `_IN_OUT` | t⁵ |

For a custom degree, use the static factories `Easing.polynomialEaseIn( n )`, `polynomialEaseOut( n )`, or `polynomialEaseInOut( n )`.

::: tip Chain animations instead of listening for completion yourself
`a.then( b )` starts `b` automatically when `a` finishes (not when `a.stop()` is called), and returns `b` so chains read left-to-right: `first.then( second ).then( third )`. This is the idiomatic way to build back-and-forth or multi-step animations, rather than manually subscribing to `finishEmitter`.
:::


========================================================================
Page: AnimationTarget and Easing
URL: https://veillette.github.io/Almanach/api/twixt/animation-target-and-easing
Source: docs/api/twixt/animation-target-and-easing.md
Category: API | Tags: twixt, AnimationTarget, Easing, Animation | Status: complete
========================================================================

# AnimationTarget and Easing

[`Animation`](/api/twixt/animation) is what sim code constructs directly, but its per-value logic — "how do I get/set this value," "what do I animate toward," "what curve controls the interpolation" — is implemented by two smaller pieces from `scenerystack/twixt`: `AnimationTarget` (one config object per animated value) and `Easing` (the interpolation curve, shared by all targets in an `Animation` unless overridden per-target). You'll construct `Easing`s directly all the time (as shown on the [`Animation`](/api/twixt/animation) page); you'll construct `AnimationTarget` directly only when using `Animation`'s `targets` array to animate several independent values in lockstep from one `Animation` instance.

```ts
import { Animation, AnimationTarget, Easing } from 'scenerystack/twixt';
import { NumberProperty } from 'scenerystack/axon';

const xProperty = new NumberProperty( 0 );
const yProperty = new NumberProperty( 0 );

// Animate two Properties together, each described by its own AnimationTargetOptions,
// with a shared duration but independently-tunable easing per target.
const moveAnimation = new Animation( {
  duration: 0.75,
  targets: [
    { property: xProperty, to: 100, easing: Easing.QUADRATIC_IN_OUT },
    { property: yProperty, to: 50, easing: Easing.LINEAR }
  ]
} );

moveAnimation.start();
```

Each entry in `targets` is exactly the shape of `AnimationTargetOptions` — the same `property`/`object`+`attribute`/`setValue`+`getValue`, `to`/`delta`, `from`, `easing`, `blend`, `distance`, and `add` options documented for `Animation` itself, just scoped to one value instead of the whole animation. `Animation` constructs one `AnimationTarget` per array entry (or exactly one, from its own top-level options, when `targets` isn't used).

## `AnimationTarget`

```ts
new AnimationTarget( providedConfig: AnimationTargetOptions<T, Obj> )
```

Exactly one way of setting the value (`property`, `object` + `attribute`, or `setValue` [+ `getValue`]) and exactly one way of determining the end value (`to` or `delta`) must be provided — `AnimationTarget` asserts otherwise, same as `Animation`.

| Option | Default | Effect |
| --- | --- | --- |
| `property` | `null` | A settable axon `Property<T>` to read from and write to |
| `object` + `attribute` | `null` | Reads/writes `object[ attribute ]` directly |
| `setValue` (+ `getValue`) | `null` | Custom setter (and, unless `from` is given, getter) for values that aren't a `Property` or plain attribute |
| `to` | `null` | Absolute end value |
| `delta` | `null` | End value computed as `add( startingValue, delta )` |
| `speed` | `null` | Seconds per unit of `distance()` between start and end — lets this target determine the animation's duration instead of a fixed `duration` |
| `from` | `null` | Overrides the starting value instead of calling `getValue()` |
| `easing` | `Easing.CUBIC_IN_OUT` | This target's interpolation curve |
| `blend` | number/`Vector2`/`Vector3`/`Vector4`/`Color`-aware default | `(start, end, ratio) => value` — how to interpolate between the start and end values |
| `distance` | number/`Vector2`/`Vector3`/`Vector4`-aware default | `(a, b) => number` — used only when `speed` determines duration |
| `add` | number/`Vector2`/`Vector3`/`Vector4`-aware default | `(start, delta) => value` — used only when `delta` is provided |

The default `blend`/`distance`/`add` implementations already handle `number`, `Vector2`, `Vector3`, `Vector4`, and (for `blend`) `Color` — supply your own only for other value types, or types whose objects don't already implement `.blend()`/`.distance()`/`.plus()`.

`AnimationTarget` also exposes `computeStartEnd()` (resolves `startingValue`/`endingValue` right before the animation begins, so `getValue()` reflects the value at start time, not construction time), `update( ratio )` (applies `blend(start, end, easing.value(ratio))` via `setValue`), `hasPreferredDuration()`, and `getPreferredDuration()` — all called internally by `Animation`, not typically by sim code.

## `Easing`

```ts
new Easing( value: (t: number) => number, derivative: (t: number) => number, secondDerivative: (t: number) => number )
```

An `Easing` is a triple of functions over `[0, 1] -> [0, 1]` (`value`), plus its first and second derivatives — the derivatives exist so `Animation` chains and speed-based durations can reason about velocity/acceleration at the boundaries, not just position. In practice you reach for one of the built-in static instances rather than constructing one from raw functions:

| Static member | Curve |
| --- | --- |
| `Easing.LINEAR` | Constant rate (`t`) |
| `Easing.QUADRATIC_IN` / `_OUT` / `_IN_OUT` | t² |
| `Easing.CUBIC_IN` / `_OUT` / `_IN_OUT` | t³ |
| `Easing.QUARTIC_IN` / `_OUT` / `_IN_OUT` | t⁴ |
| `Easing.QUINTIC_IN` / `_OUT` / `_IN_OUT` | t⁵ |

For any other polynomial degree `n` (not necessarily an integer), use the static factories directly: `Easing.polynomialEaseIn( n )`, `Easing.polynomialEaseOut( n )`, `Easing.polynomialEaseInOut( n )` — this is in fact how all of the named statics above are defined (e.g. `Easing.CUBIC_IN_OUT` is exactly `Easing.polynomialEaseInOut( 3 )`).

::: tip Use `targets` when several values must animate on the same timeline
A single `Animation` with a `targets` array keeps multiple values (e.g. `x` and `y`, or position and opacity) synchronized to one `start()`/`stop()`/chain lifecycle and one set of `startEmitter`/`finishEmitter` events, rather than juggling several independent `Animation` instances that could drift out of sync if one is interrupted.
:::

::: warning Only one target may use `speed` to determine duration
`Animation` requires exactly one length source overall — either its own `duration` option, or exactly one target's `speed`. Giving multiple targets a `speed`, or combining `speed` with a top-level `duration`, is not a supported configuration.
:::


========================================================================
Page: DampedAnimation
URL: https://veillette.github.io/Almanach/api/twixt/damped-animation
Source: docs/api/twixt/damped-animation.md
Category: API | Tags: twixt, DampedAnimation, animation, physics | Status: complete
========================================================================

# DampedAnimation

`DampedAnimation` (from `scenerystack/twixt`) animates a single numeric value toward a `targetValue` using damped-harmonic-oscillator physics, rather than [`Animation`](/api/twixt/animation)'s fixed-duration `Easing` curves. Instead of specifying "reach the target in 0.5 seconds using this easing curve," you specify a `damping` and `force` coefficient, and the motion — including how much it overshoots and oscillates, if at all — falls out of the physics. It has no notion of a fixed duration: you `step()` it every frame indefinitely, and it asymptotically approaches `targetValue` (exactly reaching it only in the limit).

```ts
import { DampedAnimation } from 'scenerystack/twixt';
import { NumberProperty } from 'scenerystack/axon';
```

## A minimal example

```ts
const positionProperty = new NumberProperty( 0 );

const dampedAnimation = new DampedAnimation( {
  valueProperty: positionProperty,
  damping: 1,      // critically damped: fastest approach with no overshoot
  force: 4,
  targetValue: 100
} );

// In your animation-frame loop:
dampedAnimation.step( dt ); // dt in seconds -- updates positionProperty and its velocity

// Change the target at any time; the current position/velocity carry over smoothly.
dampedAnimation.targetValue = 250;
```

## Constructor

```ts
new DampedAnimation( providedOptions?: DampedAnimationOptions )
```

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `valueProperty` | a private `TinyProperty( 0 )` | The `TProperty<number>` driven by the animation — pass your own `NumberProperty` (or similar) to observe the value as it animates |
| `velocityProperty` | a private `TinyProperty( 0 )` | The `TProperty<number>` tracking the current rate of change; pass your own to read/observe velocity |
| `damping` | `1` | Damping ratio relative to critical damping: `1` critically damped (fastest approach, no overshoot), `< 1` underdamped (overshoots with decaying oscillation), `> 1` overdamped (slower exponential approach, no oscillation) |
| `force` | `1` | Coefficient for the "pull" toward the target, proportional to the current distance from it — larger values pull harder/faster |
| `targetValue` | `0` | The value being animated toward |

## Methods and properties

| Member | Description |
| --- | --- |
| `valueProperty` (readonly) | The `TProperty<number>` being animated — read it directly, or link to it, to observe the current value |
| `velocityProperty` (readonly) | The `TProperty<number>` tracking the current derivative |
| `targetValue` (getter/setter) | Reading returns the current target; setting it re-derives the internal harmonic model from the current value/velocity, so the transition to the new target stays smooth (no jump) |
| `damping` (getter/setter) | Setting recomputes the internal harmonic model, same as `targetValue` |
| `force` (getter/setter) | Setting recomputes the internal harmonic model, same as `targetValue` |
| `step( dt )` | Advances `timeElapsed` by `dt` (seconds) and updates `valueProperty`/`velocityProperty` from the closed-form `DampedHarmonic` solution — no manual re-triggering needed between steps |
| `timeElapsed` | Public field tracking seconds since the harmonic model was last recomputed (i.e. since construction or the last `targetValue`/`damping`/`force` change) |

::: warning Upstream marks this a prototype
`DampedAnimation`'s own source carries the comment `WARNING: PROTOTYPE ... Not fully documented or stabilized. May be deleted.` It is a real, currently-exported class, but treat it as less battle-tested than [`Animation`](/api/twixt/animation) — verify behavior carefully (especially repeated `targetValue` changes in quick succession) before relying on it in production sim code.
:::


========================================================================
Page: TransitionNode
URL: https://veillette.github.io/Almanach/api/twixt/transition-node
Source: docs/api/twixt/transition-node.md
Category: API | Tags: twixt, TransitionNode, Transition, Animation, Node | Status: verified
========================================================================

# TransitionNode

`TransitionNode` (from `scenerystack/twixt`) is a scenery `Node` that holds one piece of "current content" and can animate to a replacement, using a slide, wipe, or dissolve effect — the kind of transition used when swapping between screens, panels, or major UI states so the change doesn't feel abrupt. Internally it builds and runs a `Transition` (also from `scenerystack/twixt`), which is itself an [`Animation`](/api/twixt/animation) subclass specialized to animate two Nodes at once (one out, one in) instead of a single value.

```ts
import { TransitionNode } from 'scenerystack/twixt';
import { Node, Rectangle } from 'scenerystack/scenery';
import { Property } from 'scenerystack/axon';

const visibleBoundsProperty = new Property( screenView.visibleBoundsProperty.value );

const panelA = new Rectangle( 0, 0, 400, 300, { fill: 'lightblue' } );
const panelB = new Rectangle( 0, 0, 400, 300, { fill: 'lightgreen' } );

const transitionNode = new TransitionNode( visibleBoundsProperty, {
  content: panelA
} );

// Later, animate to panelB with a leftward slide:
transitionNode.slideLeftTo( panelB, { duration: 0.5 } );
```

`TransitionNode` isn't self-stepping the way [`Animation`](/api/twixt/animation) is by default — call `transitionNode.step( dt )` from your `ScreenView`'s (or model's) `step()` callback for as long as the Node is displayed, so any in-progress transition actually advances.

## Constructor

```ts
new TransitionNode( transitionBoundsProperty: TReadOnlyProperty<Bounds2>, providedOptions?: TransitionNodeOptions )
```

`transitionBoundsProperty` should generally be a `ScreenView`'s `visibleBoundsProperty` — it tells `TransitionNode` the bounds that slides/wipes should traverse, and is also used as the default `clipArea` so content doesn't render outside those bounds mid-transition.

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `content` | `null` | The initial child Node shown before any transition starts |
| `useBoundsClip` | `true` | Whether to set `clipArea` to `transitionBoundsProperty`'s value automatically, so transitioning content doesn't visibly overflow |
| `cachedNodes` | `[]` | Nodes to add as permanent (initially invisible) children up front, instead of adding/removing them from the scene graph on every transition — avoids repeated add/remove cost for content you'll transition to/from repeatedly |

`TransitionNodeOptions` also accepts ordinary `NodeOptions`, except `children` — `TransitionNode` manages its own children internally and asserts if `children` is provided directly.

## Methods

Each `*To` method starts a new transition to `content` (or to nothing, if `content` is `null`) and returns the underlying `Transition` for chaining `.then(...)` or listening to `endedEmitter`:

| Method | Effect |
| --- | --- |
| `slideLeftTo/slideRightTo/slideUpTo/slideDownTo( content, config? )` | Slides the current content out and the new content in, in the named direction |
| `wipeLeftTo/wipeRightTo/wipeUpTo/wipeDownTo( content, config? )` | Reveals the new content via a moving clip-area wipe, in the named direction |
| `dissolveTo( content, config? )` | Cross-fades opacity between the current and new content |
| `step( dt )` | Advances any in-progress transition by `dt` seconds — call this every frame |
| `interrupt()` | Immediately stops the current transition (if any), leaving both Nodes at their current animated values |

`config` in each case is the same shape as the corresponding `Transition` static factory's options (`SlideTransitionOptions`, `WipeTransitionOptions`, or `DissolveTransitionOptions`) — in practice, usually just `{ duration, easing }`.

::: tip Transition vs. Animation
`Transition` is not a separate concept from [`Animation`](/api/twixt/animation) — it *is* an `Animation` subclass that always animates two `targets` (the outgoing and incoming Node) in lockstep and resets both Nodes' animated attributes (`x`/`y`/`opacity`/`clipArea`, depending on the transition type) once it ends. You will rarely construct `Transition` directly; `TransitionNode`'s `*To` methods call `Transition`'s static factories (`Transition.slideLeft`, `Transition.dissolve`, etc.) for you and handle adding/removing the Nodes from the scene graph around the animation.
:::


========================================================================
Page: Announcer, AriaLiveAnnouncer, and SpeechSynthesisAnnouncer
URL: https://veillette.github.io/Almanach/api/utterance-queue/announcers
Source: docs/api/utterance-queue/announcers.md
Category: API | Tags: utterance-queue, Announcer, AriaLiveAnnouncer, SpeechSynthesisAnnouncer, voicing, accessibility | Status: verified
========================================================================

# Announcer, AriaLiveAnnouncer, and SpeechSynthesisAnnouncer

An `Announcer` (from `scenerystack/utterance-queue`) is the output side of [`UtteranceQueue`](/api/utterance-queue/utterance-queue): the queue resolves an [`Utterance`](/api/utterance-queue/utterance)'s alert content, then calls `announcer.announce( utterance, resolvedResponse )`. Concrete subclasses implement *how* the text reaches the user — via hidden `aria-live` elements (`AriaLiveAnnouncer`) or the browser's Web Speech API (`SpeechSynthesisAnnouncer`).

```ts
import {
  UtteranceQueue,
  AriaLiveAnnouncer,
  SpeechSynthesisAnnouncer,
  Utterance
} from 'scenerystack/utterance-queue';
```

## A minimal example — AriaLiveAnnouncer

Interactive Description alerts typically use `AriaLiveAnnouncer`, which cycles through a small pool of off-screen `<p aria-live="…">` elements to avoid VoiceOver interrupting consecutive alerts:

```ts
const announcer = new AriaLiveAnnouncer();
document.body.appendChild( announcer.ariaLiveContainer ); // required once

const queue = new UtteranceQueue( announcer );
queue.addToBack( new Utterance( { alert: 'Temperature increased' } ) );
```

## A minimal example — SpeechSynthesisAnnouncer

Voicing features use `SpeechSynthesisAnnouncer`, which drives `window.speechSynthesis`:

```ts
const announcer = new SpeechSynthesisAnnouncer();
await announcer.initialize(); // picks a voice, handles browser quirks

const queue = new UtteranceQueue( announcer );
queue.addToBack( new Utterance( { alert: 'Beaker is half full' } ) );
```

## Shared `Announcer` contract

| Member | Description |
| --- | --- |
| `readyToAnnounce` | When `false`, `UtteranceQueue` waits before sending the next utterance — subclasses set this while output is in progress |
| `hasSpoken` | Whether this announcer has successfully spoken at least once (used to gate first-speech initialization) |
| `announcementCompleteEmitter` | Subclasses emit when a given `Utterance` finishes speaking so the queue can dequeue the next one |
| `respectResponseCollectorProperties` | Whether `ResponsePacket` alerts honor `responseCollector` feature toggles (Interactive Description vs. Voicing) |

`Announcer` extends `PhetioObject` and is abstract — simulation code normally receives a configured instance from the framework rather than subclassing it.

## `AriaLive` priority

`AriaLiveAnnouncer` accepts an `ariaLivePriority` option on each `announce()` call, using the `AriaLive` enumeration:

| Value | Effect |
| --- | --- |
| `AriaLive.POLITE` | Updates a polite `aria-live` region — waits for a pause in screen-reader speech |
| `AriaLive.ASSERTIVE` | Updates an assertive region — interrupts current speech |

## Choosing an announcer

| Class | Channel | Typical use |
| --- | --- | --- |
| `AriaLiveAnnouncer` | Hidden DOM `aria-live` regions | Interactive Description alerts independent of focus |
| `SpeechSynthesisAnnouncer` | Web Speech API | Voicing spoken responses |

Both plug into the same [`UtteranceQueue`](/api/utterance-queue/utterance-queue) API — the queue handles timing, priority, and stability; the announcer handles platform output.


========================================================================
Page: ResponsePacket and ResponsePatternCollection
URL: https://veillette.github.io/Almanach/api/utterance-queue/response-packet-and-patterns
Source: docs/api/utterance-queue/response-packet-and-patterns.md
Category: API | Tags: utterance-queue, ResponsePacket, ResponsePatternCollection, voicing, accessibility | Status: verified
========================================================================

# ResponsePacket and ResponsePatternCollection

`ResponsePacket` (from `scenerystack/utterance-queue`) is the standard way to give an `Utterance` structured content for the Voicing feature instead of a single flat string. It splits a response into four independently-enable-able categories — **name**, **object**, **context**, and **hint** — so a user's response-level preferences (toggling "hear hints" off, say) apply automatically without every call site re-implementing the logic. `ResponsePatternCollection` supplies the string template used to stitch whichever categories are enabled into one final string, controlling their order and punctuation.

```ts
import { ResponsePacket, ResponsePatternCollection, Utterance } from 'scenerystack/utterance-queue';
```

## A minimal example

```ts
const packet = new ResponsePacket( {
  nameResponse: 'Ball',
  objectResponse: 'now at the left wall',
  contextResponse: 'Sound is playing',
  hintResponse: 'Press space to launch again'
} );

const utterance = new Utterance( { alert: packet } );
utteranceQueue.addToBack( utterance );
```

When the `Utterance` is announced, its content is resolved through the process-wide `responseCollector`, which reads each category's Property (e.g. "are hints enabled") and assembles only the enabled parts using the matching pattern from `packet.responsePatternCollection` — by default `ResponsePatternCollection.DEFAULT_RESPONSE_PATTERNS`, e.g. `'{{NAME}}, {{OBJECT}}, {{CONTEXT}} {{HINT}}'` when all four are present.

## `ResponsePacketOptions`

| Option | Default | Effect |
| --- | --- | --- |
| `nameResponse` | `null` | Labels the element — usually the same content as its accessible name |
| `objectResponse` | `null` | Describes the element's current state (e.g. a slider's value) |
| `contextResponse` | `null` | Describes surrounding effects of the interaction |
| `hintResponse` | `null` | A hint about how to interact further |
| `ignoreProperties` | `false` | If `true`, all four responses are always spoken regardless of `responseCollector`'s enable/disable Properties |
| `responsePatternCollection` | `ResponsePatternCollection.DEFAULT_RESPONSE_PATTERNS` | Which template set to combine enabled categories with |

Each of the four responses accepts a plain string/number, a `TReadOnlyProperty<string>`, or a zero-arg function returning either (`VoicingResponse`) — evaluated fresh each time the packet is spoken, so a response can reflect live model state.

## Methods

| Method | Description |
| --- | --- |
| `.nameResponse` / `.objectResponse` / `.contextResponse` / `.hintResponse` (getters) | Resolve the corresponding field to its current text/value |
| `setNameResponse()` / `setObjectResponse()` / `setContextResponse()` / `setHintResponse()` | Replace a field's content in place, so one long-lived `ResponsePacket` can be reused as state changes |
| `copy()` | Returns a new `ResponsePacket` with the same (resolved) field values |
| `serialize()` | Returns a plain options object with all four fields resolved, plus `ignoreProperties` and `responsePatternCollection` |

## `ResponsePatternCollection`

A `ResponsePatternCollection` holds one template string per possible combination of the four categories (`name`, `nameObject`, `nameObjectContextHint`, ..., 15 combinations total), keyed with `{{NAME}}`/`{{OBJECT}}`/`{{CONTEXT}}`/`{{HINT}}` placeholders. Construct one with only the templates you want to override — anything omitted falls back to `DEFAULT_RESPONSE_PATTERNS`'s value for that key:

```ts
const packet = new ResponsePacket( {
  nameResponse: 'Ball',
  objectResponse: 'moving fast',
  responsePatternCollection: ResponsePatternCollection.OBJECT_RESPONSE_FIRST_PATTERNS
} );
```

| Static instance | Behavior |
| --- | --- |
| `ResponsePatternCollection.DEFAULT_RESPONSE_PATTERNS` | Name, then object, then context, then hint |
| `ResponsePatternCollection.OBJECT_RESPONSE_FIRST_PATTERNS` | Object response spoken before the name response |
| `ResponsePatternCollection.CONTEXT_RESPONSE_FIRST_PATTERNS` | Context response spoken before both name and object |

::: tip Mutate the packet, not the Utterance, as state changes
Because `ResponsePacket`'s setters let you update `nameResponse`/`objectResponse`/etc. in place, the idiomatic pattern is one long-lived `ResponsePacket` (often owned by the Node it describes) whose fields you update as model state changes, wrapped once in a long-lived `Utterance` that gets re-added to the queue — mirroring the same "reuse the instance" pattern `Utterance` itself expects. Building a brand-new `ResponsePacket` and `Utterance` on every change works but discards the queue's ability to recognize "this is the same alert, just updated."
:::


========================================================================
Page: Utterance
URL: https://veillette.github.io/Almanach/api/utterance-queue/utterance
Source: docs/api/utterance-queue/utterance.md
Category: API | Tags: utterance-queue, Utterance, voicing, description, accessibility | Status: verified
========================================================================

# Utterance

`Utterance` (from `scenerystack/utterance-queue`) wraps a piece of alert content — a string, a `TReadOnlyProperty<string>`, a function returning either, or a `ResponsePacket` — so that an `UtteranceQueue` can decide *when* and *whether* to speak it. A single `Utterance` instance can be re-added to a queue repeatedly (e.g. once per model step); the queue treats a re-add as "this content changed again," resetting its stability timer rather than piling up duplicate announcements.

```ts
import { Utterance } from 'scenerystack/utterance-queue';
```

## A minimal example

```ts
const utterance = new Utterance( {
  alert: 'Ball moved to the left wall',
  alertStableDelay: 500 // wait for rapid re-adds to settle before speaking
} );

// Re-adding the same Utterance while it changes resets its stability timer instead of queuing duplicates.
utteranceQueue.addToBack( utterance );
```

Changing what will be spoken next time just reassigns `alert`:

```ts
utterance.alert = 'Ball moved to the right wall';
utteranceQueue.addToBack( utterance );
```

## Constructor

```ts
new Utterance( providedOptions?: UtteranceOptions )
```

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `alert` | `null` | The content to speak: a string, `TReadOnlyProperty<string>`, a function returning either, or a `ResponsePacket` |
| `predicate` | `() => true` | Checked right before announcing; if it returns `false` the Utterance is silently dropped, no retry |
| `canAnnounceProperties` | `[]` | All must be `true` for this Utterance to announce at all (feeds `canAnnounceProperty`) |
| `descriptionCanAnnounceProperties` | `[]` | Additional gate specific to `AriaLiveAnnouncer`/description output |
| `voicingCanAnnounceProperties` | `[]` | Additional gate specific to `SpeechSynthesisAnnouncer`/voicing output |
| `alertStableDelay` | `200` (ms) | How long the Utterance must go un-re-added before it's considered "stable" and eligible to speak |
| `alertMaximumDelay` | `Number.MAX_VALUE` (ms) | Upper bound — forces announcement even if the Utterance never stabilizes |
| `announcerOptions` | `{}` | Forwarded verbatim to the `Announcer`'s `announce()` call |
| `priority` | `Utterance.DEFAULT_PRIORITY` (`1`) | See priority statics below |

## Methods and properties

| Member | Description |
| --- | --- |
| `getAlertText( respectResponseCollectorProperties? )` | Resolves the current alert to text (running functions/reading Properties/collecting the `ResponsePacket` as needed) |
| `.alert` (getter) / `getAlert()` | Returns the raw wrapped content **unresolved** — whatever was set (a string, `TReadOnlyProperty`, function, or `ResponsePacket`), not text. Use `getAlertText()` to resolve to a string |
| `.alert` (setter) / `setAlert( alert )` | Replaces the wrapped content |
| `priorityProperty` | `TProperty<number>` — mutate live to reprioritize an Utterance already sitting in a queue |
| `setAlertStableDelay( delay )` | Changes `alertStableDelay` after construction |
| `reset()` | Clears the cached "previous alert text"; does not affect the queue |
| `dispose()` | Disposes the internal control Properties; call when the Utterance is no longer needed |

## Priority statics

| Static | Value |
| --- | --- |
| `Utterance.TOP_PRIORITY` | `10` |
| `Utterance.HIGH_PRIORITY` | `5` |
| `Utterance.MEDIUM_PRIORITY` | `2` |
| `Utterance.DEFAULT_PRIORITY` | `1` |
| `Utterance.LOW_PRIORITY` | `0` |

A higher-priority Utterance interrupts a lower-priority one currently being spoken by an `UtteranceQueue`; use the statics rather than raw numbers so intent stays readable at call sites.

::: tip Re-adding the same instance is the intended debouncing mechanism
Because `UtteranceQueue.addToBack` recognizes an already-queued `Utterance` by identity and refreshes its position/timing instead of duplicating it, the idiomatic pattern for "announce this changing value" is to keep one long-lived `Utterance` per changing thing and call `addToBack` on every change, relying on `alertStableDelay` to coalesce rapid changes into a single spoken result — not to create a fresh `Utterance` per change.
:::


========================================================================
Page: UtteranceQueue
URL: https://veillette.github.io/Almanach/api/utterance-queue/utterance-queue
Source: docs/api/utterance-queue/utterance-queue.md
Category: API | Tags: utterance-queue, UtteranceQueue, Announcer, voicing, description, accessibility | Status: verified
========================================================================

# UtteranceQueue

`UtteranceQueue` (from `scenerystack/utterance-queue`) manages a first-in-first-out queue of `Utterance`s and drives an `Announcer` (such as `AriaLiveAnnouncer` or `SpeechSynthesisAnnouncer`) to actually speak them. It is generic over the announcer type — `UtteranceQueue<A extends Announcer = Announcer>` — and is what's wired up under the hood for PhET's Interactive Description and Voicing features; simulation code almost never constructs one directly, but understanding it explains why alerts appear delayed, reordered, or dropped.

```ts
import { UtteranceQueue, AriaLiveAnnouncer, Utterance } from 'scenerystack/utterance-queue';
```

## A minimal example

```ts
const announcer = new AriaLiveAnnouncer();
const utteranceQueue = new UtteranceQueue( announcer );

// Somewhere the announcer's aria-live elements need to be in the document,
// and stepTimer needs to be stepped each frame for the queue to advance.

utteranceQueue.addToBack( 'Simulation reset' );

const scoreUtterance = new Utterance( { alert: 'Score: 3' } );
utteranceQueue.addToBack( scoreUtterance ); // re-adding later updates timing instead of duplicating
```

`UtteranceQueue.fromFactory()` is a convenience factory that wires up an `AriaLiveAnnouncer`, appends its live-region container to `document.body`, and drives `stepTimer` off `requestAnimationFrame` — useful outside a full `Sim`, where `joist` already does this wiring for you.

## Constructor

```ts
new UtteranceQueue<A extends Announcer>( announcer: A, providedOptions?: UtteranceQueueOptions )
```

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `debug` | `false` | Logs queue activity (`addToBack`, `announcing`, etc.) to the console |
| `initialize` | `true` | If `false`, the queue is never stepped (no `stepTimer` listener is added) and `addToBack()`/`addToFront()`/`announceImmediately()` become no-ops (via `initializedAndEnabled`) — useful for a feature flag that disables announcing entirely without branching call sites. Methods like `removeUtterance()`/`clear()` are unaffected |
| `featureSpecificAnnouncingControlPropertyName` | `null` | `'descriptionCanAnnounceProperty'` or `'voicingCanAnnounceProperty'` — additionally gates announcing on that Utterance-level Property, on top of `canAnnounceProperty` |

## Methods

| Method | Description |
| --- | --- |
| `addToBack( utterance )` | Enqueues an `Utterance` (or raw `TAlertable` content, auto-wrapped). Removes any existing occurrence of the same `Utterance` instance first |
| `announceImmediately( utterance )` | Bypasses queue ordering, subject to `priorityProperty`: if nothing is currently announcing, or this Utterance should cancel what is, it's moved to the front of the queue and announced synchronously (or left queued at the front if the announcer isn't ready yet); otherwise it is dropped without being queued at all. Needed for effects that must originate from a synchronous user gesture (browser speech-synthesis restrictions) |
| `removeUtterance( utterance )` | Removes a specific `Utterance` from the queue (not gated by `enabled`) |
| `hasUtterance( utterance )` | Whether the given `Utterance` is currently queued |
| `cancelUtterance( utterance )` | Removes it from the queue, and asks the announcer to stop if it's currently being spoken |
| `clear()` | Empties the queue without touching in-progress announcement (not gated by `enabled`) |
| `cancel()` | `clear()` plus tells the announcer to stop speaking entirely |
| `.muted` / `setMuted()` / `getMuted()` | While muted, Utterances still move through the queue and their timers still run, but nothing is sent to the announcer |
| `.enabled` / `setEnabled()` / `isEnabled()` | While disabled, `addToBack()`/`addToFront()`/`announceImmediately()` no-op and the queue no longer steps toward announcing anything; explicit `removeUtterance()`/`clear()` calls still work |
| `.length` | Number of Utterances currently queued |
| `UtteranceQueue.fromFactory()` | Static convenience constructor described above |

## How ordering works

Utterances are announced first-in-first-out, but only once "stable" — see `Utterance`'s `alertStableDelay`/`alertMaximumDelay` — and `priorityProperty` can reorder or interrupt: a higher-priority `Utterance` added while a lower-priority one is being spoken cancels it outright; a higher-priority `Utterance` already ahead in the queue causes newly-added lower-priority ones to be dropped rather than piling up behind it.

::: warning `addToFront()` is deprecated — don't reach for it
`addToFront()` logs a deprecation warning and rarely does what it looks like it should, because ordering is driven by time-in-queue and priority, not insertion position. To make something speak sooner, use `announceImmediately()`, raise its `Utterance.priorityProperty`, or `clear()` the queue before adding the important alert — not `addToFront()`.
:::


========================================================================
Page: AllLevelsCompletedNode
URL: https://veillette.github.io/Almanach/api/vegas/all-levels-completed-node
Source: docs/api/vegas/all-levels-completed-node.md
Category: API | Tags: vegas, AllLevelsCompletedNode, game, dialog, Panel | Status: verified
========================================================================

# AllLevelsCompletedNode

`AllLevelsCompletedNode` (from `scenerystack/vegas`) is a pseudo-dialog `Node` — a `Panel` wrapping a smiley `FaceNode`, a "you completed all levels" message, and a "Done" button — shown when a player finishes every level of a game. It's a plain `Node` rather than a true `Dialog`, so the caller is responsible for showing/hiding/positioning it (typically inside a semi-transparent overlay).

**Why this page exists instead of `RewardNode`**: `RewardNode` is real source in the SceneryStack repository (`vegas/js/RewardNode.ts`), but it is **not** re-exported from `vegas.ts`, the barrel file that defines what's actually importable via `scenerystack/vegas` — so `import { RewardNode } from 'scenerystack/vegas'` does not work against the published package. `AllLevelsCompletedNode` is a real, exported, and conceptually adjacent class (both are shown at a game-completion moment), so it was substituted here.

```ts
import { AllLevelsCompletedNode } from 'scenerystack/vegas';
```

## A minimal example

```ts
const allLevelsCompletedNode = new AllLevelsCompletedNode( () => {
  // 'Done' was pressed - dismiss the dialog and return to the level-selection screen
  this.showLevelSelectionScreen();
}, {
  center: this.layoutBounds.center
} );

this.addChild( allLevelsCompletedNode );
```

## Constructor

```ts
new AllLevelsCompletedNode( listener: PushButtonListener, providedOptions?: AllLevelsCompletedNodeOptions )
```

`listener` is called when the "Done" button is pressed; the class itself does not remove or hide the Node afterward.

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `faceDiameter` | `160` | Diameter of the smiley `FaceNode` |
| `maxTextWidth` | `300` | Constrains both the message `RichText` and the "Done" button's `Text` |

`AllLevelsCompletedNodeOptions` otherwise extends the standard `NodeOptions` (position, visibility, pickability, etc. — the constructor calls `this.mutate(options)` at the end).

::: tip It's not a modal Dialog — you own the overlay
Unlike `sun`'s `Dialog`, `AllLevelsCompletedNode` doesn't dim the background, trap focus, or remove itself on close. Wrap it yourself (e.g. behind a semi-transparent `Rectangle` covering the screen) if you need modal behavior, and remove/hide it explicitly from the `listener` callback passed to the constructor.
:::


========================================================================
Page: ElapsedTimeNode
URL: https://veillette.github.io/Almanach/api/vegas/elapsed-time-node
Source: docs/api/vegas/elapsed-time-node.md
Category: API | Tags: vegas, ElapsedTimeNode, GameTimer, game, HBox | Status: verified
========================================================================

# ElapsedTimeNode

`ElapsedTimeNode` (from `scenerystack/vegas`) is an `HBox` pairing a small clock icon with a `Text` readout, meant to sit inside a game's status bar (PhET's `FiniteStatusBar`) to show how long the current level has taken. It doesn't own a timer itself — you give it a `ReadOnlyProperty<number>` of elapsed seconds (typically a [`GameTimer`](/api/vegas/game-timer)'s `elapsedTimeProperty`) and it keeps its text in sync, formatting the value the same way `GameTimer.formatTime()` does.

```ts
import { ElapsedTimeNode, GameTimer } from 'scenerystack/vegas';

const gameTimer = new GameTimer();
gameTimer.start();

const elapsedTimeNode = new ElapsedTimeNode( gameTimer.elapsedTimeProperty, {
  clockIconRadius: 15,
  textFill: 'black'
} );
```

## Constructor

```ts
new ElapsedTimeNode( elapsedTimeProperty: ReadOnlyProperty<number>, providedOptions?: ElapsedTimeNodeOptions )
```

## Options

`ElapsedTimeNodeOptions` combines `HBoxOptions` (minus `children`, which `ElapsedTimeNode` sets internally) with:

| Option | Default | Effect |
| --- | --- | --- |
| `clockIconRadius` | `15` | Radius of the clock icon (a `SimpleClockIcon`) placed before the text |
| `font` | `StatusBar.DEFAULT_FONT` | Font for the elapsed-time text |
| `textFill` | `'black'` | Fill for the elapsed-time text |

The `HBox` itself defaults `spacing: 8` between the icon and text.

## Formatting

The displayed text is produced by [`GameTimer.formatTime()`](/api/vegas/game-timer) — `H:MM:SS` once the elapsed time reaches an hour, otherwise `M:SS` — and re-renders automatically whenever `elapsedTimeProperty` changes, since `ElapsedTimeNode` links to it internally via a `Multilink` (also re-running if the localized time-format pattern strings change).

::: tip `ElapsedTimeNode` is display-only
It has no `start()`/`stop()`/`reset()` of its own — those belong to whatever `ReadOnlyProperty<number>` you hand it, normally a [`GameTimer`](/api/vegas/game-timer). Call `dispose()` on the `ElapsedTimeNode` (not the timer) when the status bar it's part of is torn down, to release its internal `Multilink`.
:::


========================================================================
Page: FiniteStatusBar and InfiniteStatusBar
URL: https://veillette.github.io/Almanach/api/vegas/status-bars
Source: docs/api/vegas/status-bars.md
Category: API | Tags: vegas, FiniteStatusBar, InfiniteStatusBar, StatusBar, game, score | Status: verified
========================================================================

# FiniteStatusBar and InfiniteStatusBar

`FiniteStatusBar` and `InfiniteStatusBar` (both from `scenerystack/vegas`) are the two standard game-screen status bars: a `Rectangle` bar, floated against the top of the screen, that keeps a score display (and other UI) aligned to its left and right edges as the browser window resizes. Both extend `scenery-phet`'s `StatusBar` base class, which handles the resize-following geometry; each subclass only decides *what content* goes in the bar.

- **`FiniteStatusBar`** is for games with a fixed number of challenges per level — it shows "Level N", an optional "Challenge N of M", a score display, an optional elapsed-time display, and a "Start Over" button.
- **`InfiniteStatusBar`** is for open-ended games with no fixed challenge count — it shows a back button, an arbitrary `messageNode` (typically a `Text`), and a score display, with no level/challenge/timer/start-over concepts at all.

```ts
import { FiniteStatusBar, InfiniteStatusBar } from 'scenerystack/vegas';
import { NumberProperty } from 'scenerystack/axon';
import { Text } from 'scenerystack/scenery';
```

## A minimal example

```ts
const scoreProperty = new NumberProperty( 0 );
const levelNumberProperty = new NumberProperty( 1 );

// Finite: fixed challenges per level.
const finiteStatusBar = new FiniteStatusBar( this.layoutBounds, this.visibleBoundsProperty, scoreProperty, {
  levelNumberProperty: levelNumberProperty,
  challengeNumberProperty: new NumberProperty( 1 ),
  numberOfChallengesProperty: new NumberProperty( 10 )
} );

// Infinite: open-ended, no challenge count.
const infiniteStatusBar = new InfiniteStatusBar(
  this.layoutBounds,
  this.visibleBoundsProperty,
  new Text( 'Explore freely' ),
  scoreProperty,
  { backButtonListener: () => this.showLevelSelectionScreen() }
);
```

## Constructors

```ts
new FiniteStatusBar(
  layoutBounds: Bounds2,
  visibleBoundsProperty: TReadOnlyProperty<Bounds2>,
  scoreProperty: ReadOnlyProperty<number>,
  providedOptions?: FiniteStatusBarOptions
)

new InfiniteStatusBar(
  layoutBounds: Bounds2,
  visibleBoundsProperty: TReadOnlyProperty<Bounds2>,
  messageNode: Node,
  scoreProperty: ReadOnlyProperty<number>,
  providedOptions?: InfiniteStatusBarOptions
)
```

Both take the `ScreenView`'s `layoutBounds` and `visibleBoundsProperty` first, so the bar can stretch to match the browser's actual visible width even when it differs from `layoutBounds`.

## Options

| Option | Class | Default | Effect |
| --- | --- | --- | --- |
| `levelNumberProperty` | `FiniteStatusBar` | `null` | If set (and `levelNumberVisible`), shows a "Level N" label |
| `challengeNumberProperty` / `numberOfChallengesProperty` | `FiniteStatusBar` | `null` / `null` | Must both be set or both be `null` (asserted); shows "Challenge N of M" |
| `elapsedTimeProperty` / `timerEnabledProperty` | `FiniteStatusBar` | `null` / `null` | If both set, shows an `ElapsedTimeNode`, visible only while `timerEnabledProperty` is `true` |
| `createScoreDisplay` | both | `ScoreDisplayLabeledNumber` (`FiniteStatusBar`) / `ScoreDisplayNumberAndStar` (`InfiniteStatusBar`) | Factory building the score-display `Node` — swap in any member of the [ScoreDisplay family](/api/vegas/score-display-family) |
| `startOverButtonText` / `startOverButtonOptions` | `FiniteStatusBar` | localized "Start Over" string / `{}` | Text and extra options for the "Start Over" `TextPushButton` |
| `backButtonListener` | `InfiniteStatusBar` | no-op | Called when the back button (a `BackButton`) is pressed |
| `messageNode` (constructor parameter) | `InfiniteStatusBar` | — | Arbitrary `Node` shown next to the back button, e.g. a `Text` describing the current activity |
| `font` / `textFill` | `FiniteStatusBar` | `StatusBar.DEFAULT_FONT` / `StatusBar.DEFAULT_TEXT_FILL` | Applied to the level/challenge/score/timer text |
| `barFill` / `barStroke` (inherited `StatusBarOptions`) | both | `'lightGray'` / `null` | The bar rectangle's own paint |
| `floatToTop` (inherited `StatusBarOptions`) | both | `false` | `true` floats the bar to the top of the browser's visible bounds instead of `layoutBounds`' top |

## Methods

Both classes are otherwise thin: all layout happens in the constructor via a `Multilink`/`link` on `positioningBoundsProperty` (from `StatusBar`) plus the content's own bounds. The only public member beyond inherited `Node` API is:

| Member | Description |
| --- | --- |
| `dispose()` | Disposes internally-created `Text`/score-display/timer/button children and their string-Property links, then calls `StatusBar.dispose()` |

::: tip Picking between the two is about challenge structure, not visual polish
The deciding factor is whether "Challenge N of M" is meaningful for your game. If challenges are counted and finite, use `FiniteStatusBar` (which also gives you "Start Over" and an optional timer). If play is open-ended — no fixed challenge count to report — use `InfiniteStatusBar`, and pass whatever `messageNode` best describes the current state instead.
:::


========================================================================
Page: GameAudioPlayer
URL: https://veillette.github.io/Almanach/api/vegas/game-audio-player
Source: docs/api/vegas/game-audio-player.md
Category: API | Tags: vegas, GameAudioPlayer, sound, game, tambo | Status: verified
========================================================================

# GameAudioPlayer

`GameAudioPlayer` (from `scenerystack/vegas`) is a small class that owns five fixed [`SoundClip`](/api/tambo/sound-clip)s — `ding`, `boing`, `trumpet`, `cheer`, and `organ` — registers them with [`soundManager`](/api/tambo/sound-manager) the first time any instance is constructed, and exposes named methods for the standard game-feedback moments instead of making callers manage the clips themselves.

```ts
import { GameAudioPlayer } from 'scenerystack/vegas';
```

## A minimal example

```ts
const gameAudioPlayer = new GameAudioPlayer();

// when the user answers a challenge:
isCorrect ? gameAudioPlayer.correctAnswer() : gameAudioPlayer.wrongAnswer();

// when a level's challenges are all done:
gameAudioPlayer.challengeComplete();

// at the end of a level, based on the final score:
if ( score === 0 ) {
  gameAudioPlayer.gameOverZeroScore();
}
else if ( score === perfectScore ) {
  gameAudioPlayer.gameOverPerfectScore();
}
else {
  gameAudioPlayer.gameOverImperfectScore();
}
```

## Constructor

```ts
new GameAudioPlayer()
```

Takes no options. Constructing an instance registers the five underlying sound clips with `soundManager` (only once, regardless of how many `GameAudioPlayer` instances are created), since `addSoundsToSoundGenerator()` is guarded by a module-level `isInitialized` flag.

## Methods

| Method | Plays |
| --- | --- |
| `correctAnswer()` | `ding` — a correct answer |
| `wrongAnswer()` | `boing` — an incorrect answer |
| `challengeComplete()` | `organ` — a single challenge finished |
| `gameOverZeroScore()` | `boing` — game ended with no points earned |
| `gameOverImperfectScore()` | `trumpet` — game ended with a mixed (non-zero, non-perfect) score |
| `gameOverPerfectScore()` | `cheer` — game ended with a perfect score |

::: tip The five clips are module-level singletons, not per-instance
Every `GameAudioPlayer` you construct plays the same shared `ding`/`boing`/`trumpet`/`cheer`/`organ` clips — there's no per-instance customization of output level or which sound file is used. If a sim needs different game sounds, that's a case for building custom [`SoundClip`](/api/tambo/sound-clip)s directly rather than configuring `GameAudioPlayer`.
:::


========================================================================
Page: GameTimer
URL: https://veillette.github.io/Almanach/api/vegas/game-timer
Source: docs/api/vegas/game-timer.md
Category: API | Tags: vegas, GameTimer, game, timer | Status: verified
========================================================================

# GameTimer

`GameTimer` (from `scenerystack/vegas`) tracks how long a game level has been in progress, counting whole seconds via axon's shared `stepTimer` rather than being driven by a simulation's per-frame `step()`. Its frame rate (once per second) is deliberately coarse — fine for a "time to complete this level" readout, not for driving smooth animation. [`ElapsedTimeNode`](/api/vegas/elapsed-time-node) is the usual way to display its value.

```ts
import { GameTimer } from 'scenerystack/vegas';

const gameTimer = new GameTimer();

function startLevel(): void {
  gameTimer.start(); // resets elapsedTimeProperty to 0 and begins counting
}

function levelComplete(): void {
  gameTimer.stop();
  console.log( `Finished in ${GameTimer.formatTime( gameTimer.elapsedTimeProperty.value )}` );
}
```

## Constructor

```ts
new GameTimer( tandem = Tandem.OPT_OUT )
```

`GameTimer` is a `PhetioObject`; pass a real `tandem` only if the timer itself needs PhET-iO instrumentation (its `isRunningProperty` and `elapsedTimeProperty` are each given sub-tandems and are `phetioReadOnly` — a sim changes them by calling `start()`/`stop()`/`restart()`, not by writing the Properties directly).

## Public state

| Member | Description |
| --- | --- |
| `elapsedTimeProperty` | `Property<number>` — whole seconds elapsed since the last `start()`, integer-valued, range `[0, Infinity)` |
| `isRunning` | Getter mirroring the internal `isRunningProperty` |

## Methods

| Method | Effect |
| --- | --- |
| `start()` | Resets `elapsedTimeProperty` to `0` and begins counting up once per second; no-op if already running |
| `stop()` | Halts counting, leaving `elapsedTimeProperty` at its current value; no-op if already stopped |
| `restart()` | `stop()` followed by `start()` — convenience for "start this level over" |
| `reset()` | Resets both `isRunningProperty` and `elapsedTimeProperty` to their initial values and clears any pending interval |
| `GameTimer.formatTime( time )` *(static)* | Formats a number of seconds as a localized `H:MM:SS` string once `time` reaches an hour, otherwise `M:SS` |

::: tip `GameTimer` counts in whole seconds, not fractional time
Internally it uses `stepTimer.setInterval( ..., 1000 )`, incrementing `elapsedTimeProperty` by exactly `1` every second rather than accumulating a `dt`. If a game needs sub-second precision, `GameTimer` isn't the right tool — track elapsed time yourself with a per-frame `step()` and use `GameTimer.formatTime()` only for the display formatting.
:::

::: warning `start()` always resets the elapsed time to zero
Calling `start()` on an already-stopped `GameTimer` does not resume from where it left off — it restarts from `0`. Use `restart()` when that's the intended behavior (e.g. the user pressed "Try Again"); don't call `stop()` then `start()` expecting to pause and resume, since `start()` alone is a no-op while already running and a fresh start when not.
:::


========================================================================
Page: LevelCompletedNode
URL: https://veillette.github.io/Almanach/api/vegas/level-completed-node
Source: docs/api/vegas/level-completed-node.md
Category: API | Tags: vegas, LevelCompletedNode, game, Panel, score | Status: verified
========================================================================

# LevelCompletedNode

`LevelCompletedNode` (from `scenerystack/vegas`) is a `Panel` shown when a player finishes **one level** of a game: a congratulatory title (which varies with how well they did), a `ScoreDisplayStars` progress indicator, the level number, the numeric score out of the perfect score, an optional elapsed/best-time readout, and a "Continue" button. All of its content is computed once from plain numbers passed into the constructor — it does not observe live `Property` values itself (aside from the string Properties it builds internally for i18n).

**This is distinct from [`AllLevelsCompletedNode`](/api/vegas/all-levels-completed-node)**: `LevelCompletedNode` reports the result of *one level* and offers "Continue" (to the next level or back to level selection), whereas `AllLevelsCompletedNode` is shown once every level in the game has been completed and offers only "Done". A typical game shows `LevelCompletedNode` after every level, and `AllLevelsCompletedNode` only after the last one.

```ts
import { LevelCompletedNode } from 'scenerystack/vegas';
```

## A minimal example

```ts
const levelCompletedNode = new LevelCompletedNode(
  3,        // level
  8,        // score
  10,       // perfectScore
  4,        // numberOfStars
  true,     // timerEnabled
  95,       // elapsedTime, in seconds
  110,      // bestTimeAtThisLevel, in seconds (or null)
  false,    // isNewBestTime
  () => this.showNextLevel(),
  { center: this.layoutBounds.center }
);

this.addChild( levelCompletedNode );
```

## Constructor

```ts
new LevelCompletedNode(
  level: number,
  score: number,
  perfectScore: number,
  numberOfStars: number,
  timerEnabled: boolean,
  elapsedTime: number,
  bestTimeAtThisLevel: number | null,
  isNewBestTime: boolean,
  continueFunction: PushButtonListener,
  providedOptions?: LevelCompletedNodeOptions
)
```

| Parameter | Meaning |
| --- | --- |
| `level` | The level number just completed (shown as "Level N" unless `levelVisible: false`) |
| `score` / `perfectScore` | Used both for the "Score: N of M" text and to compute the title ("Excellent!"/"Great"/"Good"/"Keep Trying") from `score / perfectScore` |
| `numberOfStars` | Passed to the internal `ScoreDisplayStars` |
| `timerEnabled`, `elapsedTime`, `bestTimeAtThisLevel`, `isNewBestTime` | If `timerEnabled` is `true`, a time readout is shown — with a "Your New Best!" or "Your Best: MM:SS" second line depending on `isNewBestTime` and whether `bestTimeAtThisLevel` is non-null |
| `continueFunction` | Called when the "Continue" button is pressed |

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `levelVisible` | `true` | Whether the "Level N" line is shown at all |
| `starDiameter` | `62` | Diameter used to size the inner/outer radii passed to the `ScoreDisplayStars`' `StarNode`s |
| `contentMaxWidth` | `400` | Applied as `maxWidth` to each child `Text`/`RichText`/button individually (not to the `Panel`'s content as a whole) |
| `titleFont` / `infoFont` / `buttonFont` | bold 28px / bold 22px / 26px `PhetFont` | Fonts for the title, the info lines (level/score/time), and the "Continue" button |
| `buttonFill` | `PhetColorScheme.BUTTON_YELLOW` | Fill color of the "Continue" button |
| `fill` / `stroke` / `cornerRadius` (inherited `PanelOptions`) | `'rgb(180,205,255)'` / `'black'` / `35` | The panel's own background styling |

## Methods

| Member | Description |
| --- | --- |
| `dispose()` | Disposes the internally-created string `DerivedStringProperty`s and every `VBox` child (title, stars, level/score/time text, button), then calls `Panel.dispose()` |

::: tip The title text is chosen automatically from the score ratio
You don't pass a title string directly — `LevelCompletedNode` computes `score / perfectScore` and picks "Excellent!" (>0.95), "Great" (>0.75), "Good" (\>=0.5), or "Keep Trying" (below that) for you. If you need different thresholds or wording, you'll need to build a custom results panel rather than configuring this one; there's no option to override the title text or its breakpoints.
:::


========================================================================
Page: LevelSelectionButton
URL: https://veillette.github.io/Almanach/api/vegas/level-selection-button
Source: docs/api/vegas/level-selection-button.md
Category: API | Tags: vegas, LevelSelectionButton, game, button, RectangularPushButton | Status: verified
========================================================================

# LevelSelectionButton

`LevelSelectionButton` (from `scenerystack/vegas`) is a `RectangularPushButton` subclass built for a game's level-selection screen: an icon on top, a score display (by default a `ScoreDisplayStars`) in a bordered panel below it, sized to a fixed `buttonWidth`/`buttonHeight`. It's typically not constructed one-by-one but produced by `LevelSelectionButtonGroup`, which lays out a row/grid of them.

```ts
import { LevelSelectionButton, ScoreDisplayNumberAndStar } from 'scenerystack/vegas';
import { NumberProperty } from 'scenerystack/axon';
```

## A minimal example

```ts
const scoreProperty = new NumberProperty( 0 );

const levelButton = new LevelSelectionButton( levelIconNode, scoreProperty, {
  buttonWidth: 150,
  buttonHeight: 150,
  createScoreDisplay: score => new ScoreDisplayNumberAndStar( score ),
  listener: () => selectLevel( 1 ),
  tandem: tandem.createTandem( 'level1Button' )
} );
```

## Constructor

```ts
new LevelSelectionButton( icon: Node, scoreProperty: ReadOnlyProperty<number>, providedOptions?: LevelSelectionButtonOptions )
```

`icon` appears above the score display, scaled (via the static `createSizedImageNode`) to fit the available space.

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `buttonWidth` / `buttonHeight` | `150` / `150` | Overall size of the button; icon and score-display area are both derived from these |
| `createScoreDisplay` | `scoreProperty => new ScoreDisplayStars(scoreProperty)` | Factory for the score-display Node — swap in [`ScoreDisplayNumberAndStar`](/api/vegas/score-display-number-and-star) or another display for a different look |
| `scoreDisplayProportion` | `0.2` | Fraction (0, 0.5] of `buttonHeight` given to the score-display background |
| `scoreDisplayMinXMargin` / `scoreDisplayMinYMargin` | `10` / `5` | Minimum margin between the score display and its background panel |
| `iconToScoreDisplayYSpace` | `10` | Vertical gap between the icon and the score-display panel |
| `soundPlayerIndex` | `0` | Selects a pitch-shifted variant of the default level-selection sound (semitone steps via `soundConstants.TWELFTH_ROOT_OF_TWO`); ignored if `soundPlayer` is provided directly |
| `cornerRadius` | `10` | `RectangularPushButtonOptions` styling, overridden here (not the plain `RectangularPushButton` default) |
| `baseColor` | `'rgb( 242, 255, 204 )'` | Pale yellow-green, `LevelSelectionButton`'s own default rather than `RectangularPushButton`'s |
| `xMargin` / `yMargin` | `10` / `10` | Also overridden by `LevelSelectionButton`, not inherited unchanged from `RectangularPushButtonOptions` |

## Static methods

| Static member | Purpose |
| --- | --- |
| `LevelSelectionButton.createSizedImageNode( icon, size )` | Scales a Node to fit a `Dimension2` and centers it over a background of that exact size — used internally for the icon, but public for reuse |

::: tip `soundPlayerIndex` assumes zero-based, contiguous levels
The default sound player pitches the shared `levelSelectionButton_mp3` clip up by `soundPlayerIndex` semitones, so level buttons sound progressively higher. If your levels aren't zero-indexed or contiguous, either pass an explicit `soundPlayerIndex` per button or provide your own `soundPlayer` and ignore the option entirely.
:::


========================================================================
Page: LevelSelectionButtonGroup
URL: https://veillette.github.io/Almanach/api/vegas/level-selection-button-group
Source: docs/api/vegas/level-selection-button-group.md
Category: API | Tags: vegas, LevelSelectionButtonGroup, LevelSelectionButton, game, FlowBox | Status: verified
========================================================================

# LevelSelectionButtonGroup

`LevelSelectionButtonGroup` (from `scenerystack/vegas`) is a `Node` that builds a whole set of [`LevelSelectionButton`](/api/vegas/level-selection-button)s from a declarative array of items, rather than you constructing and laying out each button by hand. It handles three things a level-select screen otherwise has to duplicate: instantiating one button per item, giving every button in the group a uniform `buttonWidth`/`buttonHeight`, and arranging them (a single horizontal row by default, via an internal `FlowBox`).

```ts
import { LevelSelectionButtonGroup, type LevelSelectionButtonGroupItem } from 'scenerystack/vegas';
import { NumberProperty } from 'scenerystack/axon';
import { Text } from 'scenerystack/scenery';
import { Tandem } from 'scenerystack/tandem';

const level1Score = new NumberProperty( 0 );
const level2Score = new NumberProperty( 0 );

const items: LevelSelectionButtonGroupItem[] = [
  { icon: new Text( '1', { fontSize: 40 } ), scoreProperty: level1Score },
  { icon: new Text( '2', { fontSize: 40 } ), scoreProperty: level2Score }
];

const buttonGroup = new LevelSelectionButtonGroup( items, {
  levelSelectionButtonOptions: {
    listener: () => { /* look up which level was pressed via buttonGroup.buttons */ }
  },
  groupButtonWidth: 120,
  groupButtonHeight: 120,
  gameLevels: [ 1, 2 ], // value of the sim's gameLevels query parameter
  tandem: Tandem.REQUIRED.createTandem( 'levelSelectionButtonGroup' )
} );
```

## Constructor

```ts
new LevelSelectionButtonGroup( items: LevelSelectionButtonGroupItem[], providedOptions?: LevelSelectionButtonGroupOptions )
```

`items` must be non-empty, ordered by increasing level number (level 1 first) — `tandemName`s and the default `level${N}Button` naming both assume that ordering.

### `LevelSelectionButtonGroupItem`

| Field | Required | Description |
| --- | --- | --- |
| `icon` | yes | The icon `Node` for this level's button |
| `scoreProperty` | yes | `ReadOnlyProperty<number>` shown on the button |
| `tandemName` | no | Overrides the default `level${N}Button` tandem name |
| `options` | no | Per-button `LevelSelectionButtonOptions` overrides (everything `LevelSelectionButtonOptions` accepts except `tandem`/`buttonHeight`/`buttonWidth`, which the group controls) |

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `levelSelectionButtonOptions` | — | Options applied to every button in the group; a specific item's `options` overrides these |
| `flowBoxOptions` | `{ orientation: 'horizontal', spacing: 10 }` | Options for the default `FlowBox` layout; ignored if `createLayoutNode` is provided |
| `createLayoutNode` | default `FlowBox` builder | `( buttons: LevelSelectionButton[] ) => LayoutNode` — supply this for a custom arrangement (multiple rows, a grid, etc.) instead of the default single row |
| `gameLevels` | **required** | Array of positive integers (1-based) — only buttons whose level number appears in this array are made `visible`. All buttons are still constructed (so the PhET-iO API doesn't change conditionally), just hidden. Set this from your sim's `gameLevels` query parameter |
| `groupButtonWidth` / `groupButtonHeight` | — | Uniform size applied to every button via `LevelSelectionButtonOptions.buttonWidth`/`buttonHeight` |

## Public API

| Member | Description |
| --- | --- |
| `buttons` | The constructed `LevelSelectionButton[]`, ordered by increasing level number |
| `focusLevelSelectionButton( level )` | Moves keyboard focus to the button for the given 1-based level number — call this when returning to the level-select UI (e.g. after a "Back" or "Start Over" action) so keyboard traversal resumes somewhere sensible |

::: tip Build a custom layout with `createLayoutNode`, not by bypassing the group
If a single row doesn't fit your design (multiple rows, an irregular grid), provide `createLayoutNode` rather than constructing `LevelSelectionButton`s yourself — you still get the group's uniform sizing, `gameLevels` visibility handling, and `buttons`/`focusLevelSelectionButton()` API for free.
:::

::: warning `gameLevels` is required, and levels are 1-indexed
Unlike most options, `gameLevels` has no built-in default — omitting it (in TypeScript) is a type error, and passing an empty array asserts. Level numbers start at `1` to match the convention used by the `gameLevels` query parameter, not `0`.
:::


========================================================================
Page: ScoreDisplay Family
URL: https://veillette.github.io/Almanach/api/vegas/score-display-family
Source: docs/api/vegas/score-display-family.md
Category: API | Tags: vegas, ScoreDisplayLabeledNumber, ScoreDisplayLabeledStars, ScoreDisplayStars, score, game, HBox | Status: verified
========================================================================

# ScoreDisplay Family

`ScoreDisplayLabeledNumber`, `ScoreDisplayLabeledStars`, and `ScoreDisplayStars` (all from `scenerystack/vegas`) are three more ways to render a score, siblings of the compact [`ScoreDisplayNumberAndStar`](/api/vegas/score-display-number-and-star). All four share the same basic contract — a `ReadOnlyProperty<number>` in, a `Node` (usually an `HBox`) out, redrawing whenever the score `Property` changes — and differ only in how much text/how many stars they show:

| Class | Renders | Extends |
| --- | --- | --- |
| `ScoreDisplayLabeledNumber` | `"Score: N"` (a single localized, formatted number) | `Node` |
| `ScoreDisplayLabeledStars` | `"Score:" ` followed by a `ScoreDisplayStars` row | `HBox` |
| `ScoreDisplayStars` | A row of `numberOfStars` `StarNode`s, filled/partially-filled/empty according to `score / perfectScore` | `HBox` |
| `ScoreDisplayNumberAndStar` (see [its own page](/api/vegas/score-display-number-and-star)) | `"N ★"` — a number plus a single star | `HBox` |

```ts
import { ScoreDisplayLabeledNumber, ScoreDisplayLabeledStars, ScoreDisplayStars } from 'scenerystack/vegas';
import { NumberProperty } from 'scenerystack/axon';
```

## A minimal example

```ts
const scoreProperty = new NumberProperty( 6 );

// "Score: 6"
const labeledNumber = new ScoreDisplayLabeledNumber( scoreProperty );

// "Score:" + a row of stars
const labeledStars = new ScoreDisplayLabeledStars( scoreProperty, {
  scoreDisplayStarsOptions: { numberOfStars: 10, perfectScore: 10 }
} );

// Just the star row, no label -- e.g. for LevelCompletedNode's progress indicator
const bareStars = new ScoreDisplayStars( scoreProperty, {
  numberOfStars: 10,
  perfectScore: 10
} );
```

## Constructors

```ts
new ScoreDisplayLabeledNumber( scoreProperty: ReadOnlyProperty<number>, providedOptions?: ScoreDisplayLabeledNumberOptions )
new ScoreDisplayLabeledStars( scoreProperty: ReadOnlyProperty<number>, providedOptions?: ScoreDisplayLabeledStarsOptions )
new ScoreDisplayStars( scoreProperty: ReadOnlyProperty<number>, providedOptions?: ScoreDisplayStarsOptions )
```

## Options

| Option | Class | Default | Effect |
| --- | --- | --- | --- |
| `font` / `textFill` | `ScoreDisplayLabeledNumber`, `ScoreDisplayLabeledStars` | `StatusBar.DEFAULT_FONT` / `'black'` | Styling for the "Score: N" or "Score:" text |
| `scoreDecimalPlaces` | `ScoreDisplayLabeledNumber` | `0` | Decimal places shown for the number |
| `scoreDisplayStarsOptions` | `ScoreDisplayLabeledStars` | `undefined` | Forwarded to the internal `ScoreDisplayStars` (e.g. `numberOfStars`, `perfectScore`) |
| `numberOfStars` | `ScoreDisplayStars` | `1` | Total stars in the row |
| `perfectScore` | `ScoreDisplayStars` | `1` | The score corresponding to all stars filled; `score / perfectScore` determines how many stars are filled, partially filled, or empty |
| `starNodeOptions` | `ScoreDisplayStars` (and forwarded through `ScoreDisplayLabeledStars`) | `{ starShapeOptions: { outerRadius: 10, innerRadius: 5 }, filledLineWidth: 1.5, emptyLineWidth: 1.5 }` | Passed to each `StarNode` |
| `spacing` (inherited `HBoxOptions`) | `ScoreDisplayLabeledStars`, `ScoreDisplayStars` | `5` / `3` | Horizontal gap between children |

## Methods

All four are driven entirely by listening to `scoreProperty` — none exposes a manual `update()`. The only member worth calling out beyond standard `Node`/`HBox` API is:

| Member | Description |
| --- | --- |
| `dispose()` | Unlinks the internal `scoreProperty` listener (and disposes any `DerivedStringProperty`, for `ScoreDisplayLabeledNumber`/`ScoreDisplayLabeledStars`) |

::: warning `ScoreDisplayStars` asserts if `score` exceeds `perfectScore`
`ScoreDisplayStars`' internal listener runs `assert( score <= perfectScore, ... )` on every score change — a score that overshoots `perfectScore` (e.g. from a bonus not accounted for in `perfectScore`) throws with assertions enabled rather than silently drawing extra-full stars. Make sure `perfectScore` reflects the true maximum before wiring up a live `scoreProperty`.
:::


========================================================================
Page: ScoreDisplayNumberAndStar
URL: https://veillette.github.io/Almanach/api/vegas/score-display-number-and-star
Source: docs/api/vegas/score-display-number-and-star.md
Category: API | Tags: vegas, ScoreDisplayNumberAndStar, score, game, HBox | Status: verified
========================================================================

# ScoreDisplayNumberAndStar

`ScoreDisplayNumberAndStar` (from `scenerystack/vegas`) is an `HBox` that renders a score as "`N` ★" — a number followed by a single star icon. When the score is `0`, the number is omitted and the star is drawn grayed-out (empty). It's a compact alternative to `ScoreDisplayStars` (which draws one star per point) for contexts where space is limited, such as inside a [`LevelSelectionButton`](/api/vegas/level-selection-button)'s `createScoreDisplay` option.

```ts
import { ScoreDisplayNumberAndStar } from 'scenerystack/vegas';
import { NumberProperty } from 'scenerystack/axon';
```

## A minimal example

```ts
const scoreProperty = new NumberProperty( 0 );

const scoreDisplay = new ScoreDisplayNumberAndStar( scoreProperty, {
  font: new PhetFont( 20 ),
  scoreDecimalPlaces: 0
} );
```

The display listens to `scoreProperty` directly and rebuilds its children whenever the score changes — there's no separate `update()` call to make.

## Constructor

```ts
new ScoreDisplayNumberAndStar( scoreProperty: ReadOnlyProperty<number>, providedOptions?: ScoreDisplayNumberAndStarOptions )
```

## Options

| Option | Default | Effect |
| --- | --- | --- |
| `font` | `StatusBar.DEFAULT_FONT` | Font for the numeric text |
| `textFill` | `'black'` | Fill color for the numeric text |
| `scoreDecimalPlaces` | `0` | Decimal places shown for the score number |
| `starNodeOptions` | `{ starShapeOptions: { outerRadius: 10, innerRadius: 5 }, filledLineWidth: 1.5, emptyLineWidth: 1.5 }` | Forwarded to the internal `StarNode` |
| `spacing` (HBox) | `5` | Horizontal space between the number and the star |

::: tip It's an HBox, so it participates in layout like any other Node
`ScoreDisplayNumberAndStar extends HBox` — you can set `maxWidth`/`maxHeight` on it to constrain it inside a fixed-size background (which is exactly how `LevelSelectionButton` uses it), and its `boundsProperty` fires whenever the score changes and the child count (1 child — just the grayed-out star — when the score is `0`, vs. 2 children — the number plus a filled star — otherwise) flips.
:::


========================================================================
Page: Avoiding Property Leaks
URL: https://veillette.github.io/Almanach/patterns/avoiding-property-leaks
Source: docs/patterns/avoiding-property-leaks.md
Category: Patterns | Tags: axon, Property, memory, dispose, listeners | Status: verified
========================================================================

# Avoiding Property Leaks

[Dispose and Memory Management](/patterns/dispose-and-memory-management) covers the general rule: dynamically created objects must be disposed. This page is the specific failure mode that rule is guarding against for `Property`-based code — a `link`/`lazyLink` call is a strong reference in *both* directions, so a forgotten `unlink` doesn't just leak a listener, it can keep an entire object graph alive indefinitely, invisibly, with no error and no crash.

## How a Property leak actually happens

```ts
// A per-item Node created and destroyed as the list changes.
class ItemNode extends Node {
  public constructor( item: Item, sharedTotalProperty: NumberProperty ) {
    super();

    // sharedTotalProperty now holds a reference to this listener, which closes
    // over `this` (the ItemNode) - as long as sharedTotalProperty exists, so does this ItemNode.
    sharedTotalProperty.link( total => {
      this.opacity = total > 100 ? 0.5 : 1;
    } );
  }
  // No dispose() override - the listener above is never removed.
}
```

```ts
const itemNode = new ItemNode( item, model.totalProperty );
itemsLayer.addChild( itemNode );

// Later, the item is removed from the list...
itemsLayer.removeChild( itemNode );
itemNode.dispose(); // Node.dispose() runs, but the closure above is still linked to
                     // model.totalProperty, which lives for the sim's lifetime - itemNode
                     // (and everything it references) is kept alive forever.
```

`itemNode.dispose()` disposes the Node's own built-in Properties, but it does nothing about a listener `itemNode`'s constructor registered on someone *else's* Property — that link has to be undone explicitly, by the object that created it.

## The fix: track and unlink every listener you register

```ts
class ItemNode extends Node {

  private readonly disposeItemNode: () => void;

  public constructor( item: Item, sharedTotalProperty: NumberProperty ) {
    super();

    const totalListener = ( total: number ) => {
      this.opacity = total > 100 ? 0.5 : 1;
    };
    sharedTotalProperty.link( totalListener );

    this.disposeItemNode = () => sharedTotalProperty.unlink( totalListener );
  }

  public override dispose(): void {
    this.disposeItemNode();
    super.dispose();
  }
}
```

The `{ disposer }` option is the same fix with less boilerplate, when the removal should happen automatically whenever `this` is disposed:

```ts
sharedTotalProperty.link( total => {
  this.opacity = total > 100 ? 0.5 : 1;
}, { disposer: this } ); // unlinked automatically when this ItemNode is disposed - no unlink() call needed
```

## The three shapes this takes

| Construct | What leaks if not cleaned up | Cleanup |
| --- | --- | --- |
| `property.link(listener)` / `lazyLink(listener)` | `listener` and everything it closes over, kept alive by `property` | `property.unlink(listener)`, or `{ disposer: this }` on the `link` call |
| `DerivedProperty`/`new Multilink(...)` created locally | The `DerivedProperty`/`Multilink` itself holds listeners on *its* dependencies, keeping the whole chain alive | `derivedProperty.dispose()`; `Multilink.unmultilink(multilink)` — see [The Multilink Pattern](/patterns/multilink-pattern) |
| `Emitter.addListener(listener)` | Same shape as `link` — the Emitter, not the Property, holds the reference | `emitter.removeListener(listener)` |

Every one of these is invisible in normal testing — the object *looks* garbage-collectable, the sim doesn't crash, memory just grows slowly across many create/destroy cycles until a long play session degrades. That's what makes this class of bug worth a dedicated discipline rather than "fix it when it shows up."

::: warning A leak only exists when lifetimes differ
None of this applies to a `link` call where the listener and the Property it's listening to share the same lifetime (a model linking its own Properties in its own constructor, live for the sim's duration) — see [Dispose and Memory Management](/patterns/dispose-and-memory-management)'s table. The risk is specifically when a *shorter-lived* object (a popup, a list item, anything created after startup and removed before the sim closes) links to a *longer-lived* Property. Audit every `link`/`addListener` call in a dynamically-created class by asking "does what I'm linking to outlive me?" — if yes, it needs an explicit unlink in `dispose()`.
:::


========================================================================
Page: Command/Undo Pattern for Interactive Sims
URL: https://veillette.github.io/Almanach/patterns/command-undo-pattern
Source: docs/patterns/command-undo-pattern.md
Category: Patterns | Tags: architecture, undo, Property, state, command-pattern | Status: complete
========================================================================

# Command/Undo Pattern for Interactive Sims

Most PhET-style simulations don't implement undo — [Reset All](/patterns/reset-all-pattern) covers the overwhelming majority of "let the user get back to a known state" needs, and continuous interactions (dragging, a slider) are their own undo in practice: dragging something back is usually as easy as the original drag. This page is for the minority of cases where a simulation genuinely needs step-by-step undo of discrete user actions (placing an object, applying an operation to build up a construction) — a structure to reach for *if* you need it, not something to build preemptively into every sim.

## Why undo needs more structure than reset

`reset()` is the degenerate, simplest case of restoring state: everything goes back to one fixed, known configuration (see [Reset All](/patterns/reset-all-pattern) and [State Persistence and Save/Restore Patterns](/patterns/state-persistence-and-save-restore-patterns)). Undo is harder because it needs to restore to any of several *previous* states, one step at a time, in response to discrete user actions rather than a single reset button — which means something has to record, for every undoable action, both what changed and how to reverse it.

## The command object shape

Structure each undoable user action as a small object (or plain function pair) with a `do`/`execute` step and a matching `undo` step, and push it onto a stack as the user performs actions:

```ts
import type { Property } from 'scenerystack/axon';

interface Command {
  execute(): void;
  undo(): void;
}

class SetValueCommand<T> implements Command {
  private readonly previousValue: T;

  public constructor(
    private readonly property: Property<T>,
    private readonly newValue: T
  ) {
    this.previousValue = property.value;
  }

  public execute(): void {
    this.property.value = this.newValue;
  }

  public undo(): void {
    this.property.value = this.previousValue;
  }
}
```

```ts
class CommandStack {
  private readonly undoStack: Command[] = [];
  private readonly redoStack: Command[] = [];

  public do( command: Command ): void {
    command.execute();
    this.undoStack.push( command );
    this.redoStack.length = 0; // a fresh action invalidates any previously-undone redo history
  }

  public undo(): void {
    const command = this.undoStack.pop();
    if ( command ) {
      command.undo();
      this.redoStack.push( command );
    }
  }

  public redo(): void {
    const command = this.redoStack.pop();
    if ( command ) {
      command.execute();
      this.undoStack.push( command );
    }
  }
}
```

Every user action that should be undoable goes through `commandStack.do( new SomeCommand( ... ) )` instead of mutating model Properties directly — the same discipline as never bypassing `model.reset()` from [Reset All](/patterns/reset-all-pattern), applied per-action instead of only at reset time.

## Why this depends on Property-based state

This structure only works cleanly because of the same precondition [State Persistence and Save/Restore Patterns](/patterns/state-persistence-and-save-restore-patterns) already establishes: model state lives in enumerable `Property` values, not scattered plain fields or closures. A `SetValueCommand` capturing "the previous value of this Property" and restoring it later is exactly the "capture now, restore later" operation that page describes — undo is just that same mechanism triggered per discrete action instead of by one save/restore button. A model with state hidden outside `Property`s has nothing for a command object to capture in the first place.

## What belongs in a command, and what doesn't

| Belongs in a command | Doesn't belong in a command |
| --- | --- |
| A discrete, user-initiated change to model state (placing an object, setting a value, applying an operation) | Continuous interaction in progress (an active drag) — undo the *result* of the drag as one command on release, not every intermediate frame |
| Enough captured state to fully reverse the change (`previousValue` above) | View-only state with no model consequence — nothing to undo if nothing in the model changed |
| Composite actions, as a single command wrapping several Property changes that should undo together atomically | Anything already covered by [Reset All](/patterns/reset-all-pattern) — don't build a parallel "undo everything" when a reset button already exists for that |

::: tip Most sims should not build this speculatively
Undo/redo is real architectural surface area — every discrete action needs a command object, the stack needs disposal discipline of its own (see [Dispose and Memory Management](/patterns/dispose-and-memory-management) if commands hold references to disposable Properties or Nodes), and testing has to cover do/undo/redo sequences, not just the forward path. Build this structure when a simulation's design genuinely calls for step-by-step undo — a construction/building tool is the common case — not by default. For everything else, [Reset All](/patterns/reset-all-pattern) is sufficient and dramatically simpler.
:::


========================================================================
Page: Composing View Nodes
URL: https://veillette.github.io/Almanach/patterns/composing-view-nodes
Source: docs/patterns/composing-view-nodes.md
Category: Patterns | Tags: scenery, Node, ScreenView, composition, architecture | Status: verified
========================================================================

# Composing View Nodes

A `ScreenView` is a `Node` like any other, which makes it tempting to build a screen by adding dozens of `Circle`/`Text`/`HBox` children directly to it in one long constructor. Instead, treat the `ScreenView` as an assembly point: each visually or behaviorally distinct piece of the screen — a control panel, a graph, a single draggable body — is its own `Node` subclass, constructed once and added as a child. The `ScreenView` wires them to the model and to each other; it doesn't contain their internals.

## The anti-pattern: one giant ScreenView

```ts
// Don't do this - every control lives inline, the constructor keeps growing,
// and nothing here is reusable or independently testable.
export default class ProjectileScreenView extends ScreenView {
  public constructor( model: ProjectileModel, providedOptions: ScreenViewOptions ) {
    super( providedOptions );

    const angleSlider = new HSlider( model.angleProperty, new Range( 0, 90 ) );
    const angleLabel = new Text( 'Angle' );
    const speedSlider = new HSlider( model.speedProperty, new Range( 0, 20 ) );
    const speedLabel = new Text( 'Speed' );
    const controlPanel = new Panel( new VBox( {
      children: [ new HBox( { children: [ angleLabel, angleSlider ] } ),
                  new HBox( { children: [ speedLabel, speedSlider ] } ) ]
    } ) );
    // ...forty more lines of graph axes, a launch button, a trajectory path...

    this.children = [ controlPanel, /* ... */ ];
  }
}
```

Every new control adds to a single constructor that mixes layout, styling, and model-wiring concerns for the whole screen, and none of it can be unit-tested or reused without instantiating the entire `ScreenView`.

## The pattern: one Node subclass per concern

```ts
// view/ProjectileControlPanel.ts
import { Panel, type PanelOptions } from 'scenerystack/sun';
import { VBox } from 'scenerystack/scenery';
import { HSlider } from 'scenerystack/sun';
import type ProjectileModel from '../model/ProjectileModel.js';

export default class ProjectileControlPanel extends Panel {
  public constructor( model: ProjectileModel, providedOptions?: PanelOptions ) {
    const content = new VBox( {
      spacing: 8,
      children: [
        new HSlider( model.angleProperty, model.angleProperty.range ),
        new HSlider( model.speedProperty, model.speedProperty.range )
      ]
    } );

    super( content, providedOptions );
  }
}
```

```ts
// view/ProjectileScreenView.ts
import { ScreenView, type ScreenViewOptions } from 'scenerystack/sim';
import ProjectileControlPanel from './ProjectileControlPanel.js';
import ProjectileBodyNode from './ProjectileBodyNode.js';
import type ProjectileModel from '../model/ProjectileModel.js';

export default class ProjectileScreenView extends ScreenView {
  public constructor( model: ProjectileModel, providedOptions: ScreenViewOptions ) {
    super( providedOptions );

    const controlPanel = new ProjectileControlPanel( model, {
      right: this.layoutBounds.maxX - 20,
      top: this.layoutBounds.minY + 20
    } );

    const bodyNode = new ProjectileBodyNode( model );

    this.children = [ bodyNode, controlPanel ];
  }
}
```

The `ScreenView` now reads as a table of contents for the screen: what exists, and roughly where it sits. Each piece — `ProjectileControlPanel`, `ProjectileBodyNode` — can be constructed and inspected in isolation, and a change to how the control panel lays itself out never touches the `ScreenView` at all.

## How to decide where the seam goes

- **A visually distinct region** (a panel, a graph, a toolbar) is its own `Node` subclass, even if it's only used once — the goal isn't reuse, it's keeping each constructor's responsibility narrow.
- **A repeated element** (one item per array entry, one body per particle) is unconditionally its own class; see also [Composing View Nodes](#the-pattern-one-node-subclass-per-concern) applied per-item and [Avoiding Property Leaks](/patterns/avoiding-property-leaks) for cleanup when those items are created and destroyed dynamically.
- **Pure layout glue** with no independent identity (a one-off `HBox` grouping two Nodes that are otherwise unrelated) can stay inline in the parent — composing a `Node` subclass for every last spacer is its own anti-pattern.
- Each subclass still follows [Model-View Separation](/patterns/model-view-separation): it takes the model (or the one Property it needs) as a constructor argument and never reaches into sibling view classes directly.

::: tip A Node subclass's constructor argument list is its interface
Prefer passing exactly the model (or Properties) a view Node needs, not the whole screen's model plus a grab-bag of siblings. A `ProjectileBodyNode` that only takes `model.positionProperty` documents, by its signature, that it doesn't care about the control panel's state — and it's trivial to construct in a test or a Storybook-style harness later.
:::


========================================================================
Page: Constants File Pattern
URL: https://veillette.github.io/Almanach/patterns/constants-file-pattern
Source: docs/patterns/constants-file-pattern.md
Category: Patterns | Tags: conventions, constants, architecture, SceneryPhetConstants, SunConstants | Status: complete
========================================================================

# Constants File Pattern

A single, project-wide module — conventionally named `MySimConstants.ts` — holds every shared magic number, color, and font a simulation's view code depends on, exported as one plain object and imported by name everywhere that value is needed. [Spacing and Sizing Constants](/styling/spacing-and-sizing-constants) already covers the layout-dimension slice of this convention in depth; this page is the general pattern it's one application of — the same "one file, referenced by name, never retyped" rule applies just as much to colors, fonts, and any other sim-wide constant, not spacing alone.

## The pattern, generalized beyond spacing

```ts
// MySimConstants.ts
import { PhetFont } from 'scenerystack/scenery-phet';

const MySimConstants = {

  // Spacing/sizing - see Spacing and Sizing Constants for this slice in depth
  SCREEN_MARGIN: 15,
  PANEL_CORNER_RADIUS: 10,

  // Color
  CONTROL_PANEL_FILL: '#f0f0f0',
  ACCENT_COLOR: '#3182ce',

  // Font
  LABEL_FONT: new PhetFont( 16 ),
  TITLE_FONT: new PhetFont( { size: 22, weight: 'bold' } )
};

export default MySimConstants;
```

```ts
// Anywhere in view code - reference by name, never retype a literal color/font/number.
import MySimConstants from '../MySimConstants.js';
import { Panel } from 'scenerystack/sun';
import { Text } from 'scenerystack/scenery';

const panel = new Panel( content, {
  cornerRadius: MySimConstants.PANEL_CORNER_RADIUS,
  fill: MySimConstants.CONTROL_PANEL_FILL
} );

const title = new Text( 'My Sim', { font: MySimConstants.TITLE_FONT } );
```

The value of centralizing this goes up, not down, once colors and fonts are included alongside spacing: a color used in five places that's supposed to be "the sim's one accent color" is exactly the kind of value that silently drifts (one call site gets nudged during a design review, the other four don't) if it's retyped as a literal at each site, the same drift [Spacing and Sizing Constants](/styling/spacing-and-sizing-constants#the-anti-pattern-magic-numbers-at-each-call-site) describes for margins.

## Precedent: this is how SceneryStack's own libraries are structured

This isn't a convention invented for individual sim repos in isolation — it mirrors how `scenery-phet` and `sun` structure their own shared, cross-component constants: a `SceneryPhetConstants`-style module holds values common-code components across `scenery-phet` share (for instance, the default button radius `ResetAllButton` falls back to, referenced as `SceneryPhetConstants.DEFAULT_BUTTON_RADIUS` in that button's own option defaults — see [ResetAllButton](/api/scenery-phet/reset-all-button)), and a parallel `SunConstants`-style module plays the same role for `sun` (e.g. the default placeholder token `NumberDisplay` substitutes a value into, referenced as `SunConstants.VALUE_NAMED_PLACEHOLDER` — see [NumberDisplay](/api/scenery-phet/number-display)). A project's own `MySimConstants.ts` is the same idea applied one level down: instead of a library centralizing values shared across *its own* components, a sim centralizes values shared across *its own* screens.

## What belongs in the constants file

The same test [Spacing and Sizing Constants](/styling/spacing-and-sizing-constants#what-belongs-in-the-constants-file-and-what-doesnt) applies generalized beyond dimensions: a value belongs in the constants file if a design review would refer to it as "the project's standard X" — its accent color, its label font, its panel margin — regardless of whether X is a number, a color string, or a `Font` instance. A value that's genuinely local to one Node (the exact shade of one decorative flourish, a one-off font size nothing else shares) stays where it's used; promoting every literal in a codebase into the constants file regardless of whether it's actually shared just relocates the clutter instead of removing it.

::: tip One file per project, organized by category - not one file per screen
As [Multi-Screen Sim Structure](/patterns/multi-screen-sim-structure) establishes for shared code generally, a constants module belongs in `common/`, imported by every screen that needs it — never duplicated per-screen, and never one screen's constants file imported by a second screen out of convenience. Structure the file's contents by *kind* (spacing, color, font) rather than by which screen first needed a given value, the same guidance [Spacing and Sizing Constants](/styling/spacing-and-sizing-constants) gives for the spacing-only case.
:::


========================================================================
Page: Derived-Enablement Pattern
URL: https://veillette.github.io/Almanach/patterns/derived-enablement-pattern
Source: docs/patterns/derived-enablement-pattern.md
Category: Patterns | Tags: axon, DerivedProperty, EnabledComponent, EnabledProperty, enablement | Status: complete
========================================================================

# Derived-Enablement Pattern

Whenever a control's enabled/disabled state is a *function* of other model state — a "remove" button disabled when a list is empty, an "increase" button disabled once a value is already at its range maximum — compute that control's `enabledProperty` as a [`DerivedProperty`](/api/axon/derived-property) over the state it actually depends on, rather than imperatively setting `.enabled = true`/`false` from whatever code paths happen to change that state.

## The imperative anti-pattern

```ts
// Don't do this - every place valueProperty changes has to remember to also
// update the button, and it's easy for one call site to forget.
valueProperty.link( value => {
  incrementButton.enabled = value < valueProperty.range.max;
} );

// ...elsewhere, another listener on a *different* dependency has to remember too:
rangeProperty.link( range => {
  incrementButton.enabled = valueProperty.value < range.max;
} );
```

Two separate listeners computing the same boolean from overlapping inputs is exactly the shape that drifts out of sync the moment a third dependency (a "controls locked" flag, say) needs to factor in — every existing call site has to be found and updated, and it's easy to miss one.

## The pattern: derive it once

```ts
import { DerivedProperty, NumberProperty } from 'scenerystack/axon';
import { Range } from 'scenerystack/dot';

const valueProperty = new NumberProperty( 5, { range: new Range( 0, 10 ) } );

// One Property, computed from exactly the state it actually depends on.
const isAtMaxProperty = new DerivedProperty(
  [ valueProperty ],
  value => value >= valueProperty.range!.max
);

const canIncrementProperty = DerivedProperty.not( isAtMaxProperty );
```

```ts
import { RectangularPushButton } from 'scenerystack/sun';

const incrementButton = new RectangularPushButton( {
  content: /* ... */ null,
  enabledProperty: canIncrementProperty,
  listener: () => { valueProperty.value = Math.min( valueProperty.value + 1, valueProperty.range!.max ); }
} );
```

Every `sun` button accepts an `enabledProperty` option directly, so passing the derived Property in at construction is all that's needed — the button subscribes to it itself and updates its own visual/interactive enabled state, with no listener code of your own to write or keep in sync.

## Composing several conditions

`DerivedProperty`'s boolean-combinator static factories (see [DerivedProperty](/api/axon/derived-property#static-factories)) are the natural fit when a control's enablement depends on more than one independent condition — combine them instead of writing a multi-line derivation function by hand for what's really just "and"/"or" of simpler conditions:

```ts
const isUnlockedProperty = new BooleanProperty( true );

const canIncrementProperty = DerivedProperty.and( [
  DerivedProperty.not( isAtMaxProperty ),
  isUnlockedProperty
] );
```

Reading `DerivedProperty.and( [ ...conditions ] )` names *why* the button is disabled (which condition, or combination, is false) far more directly than a hand-written `( atMax, unlocked ) => !atMax && unlocked` buried inside a generic derivation callback.

## Relationship to EnabledComponent

[`EnabledComponent`](/api/axon/enabled-component) (and the base `enabledProperty` every `sun` component already has) is the *consumer* side of this pattern — it's what gives a component a settable `enabledProperty` in the first place, with PhET-iO instrumentation and disposal already handled. This pattern is about what you *supply* to that `enabledProperty`: rather than accepting the default auto-created one and setting `.enabled` imperatively, supply your own derived `TReadOnlyProperty<boolean>` via the `enabledProperty` option, and let it stay perpetually correct as its dependencies change. Recall from `EnabledComponent`'s own documentation that supplying your own `enabledProperty` opts you out of `EnabledComponent`'s automatic disposal of it — a `DerivedProperty` you construct yourself needs its own `.dispose()` call when it's no longer needed, per [Dispose and Memory Management](/patterns/dispose-and-memory-management).

::: tip Reach for Multilink instead if nothing needs the enabled *value* itself, only a side effect
This pattern assumes the enabled state is itself consumed as a `Property` (passed to a component's `enabledProperty` option, or read elsewhere). If instead you only need to run an imperative side effect when several Properties change together — with no `Property` value to hand anywhere — that's [The Multilink Pattern](/patterns/multilink-pattern), not this one; don't reach for a `DerivedProperty` you'll never actually pass anywhere as a value.
:::


========================================================================
Page: Dispose and Memory Management
URL: https://veillette.github.io/Almanach/patterns/dispose-and-memory-management
Source: docs/patterns/dispose-and-memory-management.md
Category: Patterns | Tags: dispose, memory, lifecycle | Status: verified
========================================================================

# Dispose and Memory Management

SceneryStack has no framework-managed component lifecycle — every long-lived object (`Node`, `Property`, `DerivedProperty`, `Multilink`, `PhetioObject`) has an explicit `dispose()` method, and every listener you register (`.link`, `.addListener`) is a strong reference that keeps its target alive until it's removed. If an object is created and destroyed *dynamically* (not for the lifetime of the whole sim), you are responsible for disposing it and unlinking anything it linked to — otherwise it, and everything it references, leaks.

## The core idea

```ts
import { DerivedProperty, NumberProperty } from 'scenerystack/axon';
import { Node, Circle } from 'scenerystack/scenery';

class TransientBadge extends Node {

  private readonly disposeTransientBadge: () => void;

  public constructor( scoreProperty: NumberProperty ) {
    super();

    const circle = new Circle( 10, { fill: 'gold' } );
    this.addChild( circle );

    // A derived Property created here holds a listener on scoreProperty
    // for as long as it lives.
    const isHighScoreProperty = new DerivedProperty( [ scoreProperty ], score => score > 100 );
    const listener = ( isHighScore: boolean ) => { circle.visible = isHighScore; };
    isHighScoreProperty.link( listener );

    // Anything this instance created that outlives its own scope must be torn
    // down explicitly, in reverse order of creation.
    this.disposeTransientBadge = () => {
      isHighScoreProperty.unlink( listener );
      isHighScoreProperty.dispose();
    };
  }

  public override dispose(): void {
    this.disposeTransientBadge();
    super.dispose();
  }
}
```

Create the badge and later remove it:

```ts
const badge = new TransientBadge( model.scoreProperty );
someParentNode.addChild( badge );

// When the badge is no longer needed:
someParentNode.removeChild( badge );
badge.dispose();
```

## What needs disposal, and what doesn't

| Object created for the sim's lifetime (one Screen, one model) | Object created/destroyed dynamically (a popup, a per-item Node in a list) |
| --- | --- |
| Never disposed — it lives as long as the sim does | **Must** be disposed when removed, and must dispose everything *it* uniquely created |

- `Property.link(listener)` keeps `listener` (and anything it closes over) alive for the Property's lifetime. Pair it with `unlink` in your `dispose()`, or use the `disposer` option (`link(listener, { disposer: this })`) so it's removed automatically when `this` is disposed.
- `DerivedProperty` and `Multilink` hold listeners on *their* dependencies — dispose them (`derivedProperty.dispose()`, `Multilink.unmultilink(multilink)`) or they keep the dependency chain alive indefinitely. See [The Multilink Pattern](/patterns/multilink-pattern).
- `Node.dispose()` already disposes the Node's own built-in Properties (`visibleProperty`, `enabledProperty`, etc.) and detaches it from parents/children — you only need to override it to clean up *extra* things your subclass created.

::: warning A Property/Node that is never disposed by design does not need a dispose() override
Most model and view objects in a one-screen sim are created once at startup and live until the tab closes — for those, skipping `dispose()` entirely is correct and is the common case in [Model-View Separation](/patterns/model-view-separation). Only add disposal logic to objects that are actually created and destroyed while the sim runs (list items, popups, transient UI). Adding unnecessary dispose plumbing to permanent objects is dead code that invites bugs.
:::


========================================================================
Page: Drag Listeners
URL: https://veillette.github.io/Almanach/patterns/drag-listeners
Source: docs/patterns/drag-listeners.md
Category: Patterns | Tags: scenery, input, DragListener, KeyboardDragListener, RichDragListener, interaction | Status: verified
========================================================================

# Drag Listeners

Dragging in SceneryStack follows the [model-view separation](/patterns/model-view-separation) pattern: the listener writes to a model `positionProperty` (in model coordinates), and the node's position updates through the normal observer wiring — the listener never moves the node directly.

## DragListener (pointer input)

```ts
import { DragListener } from 'scenerystack/scenery';

bodyNode.addInputListener( new DragListener( {

  // The model Property to write, in MODEL coordinates...
  positionProperty: body.positionProperty,

  // ...which works because the listener converts through this transform.
  transform: modelViewTransform,

  // Constrain dragging to a region, in model coordinates.
  dragBoundsProperty: model.dragBoundsProperty,

  start: () => body.userControlledProperty.set( true ),
  end: () => body.userControlledProperty.set( false )
} ) );
bodyNode.cursor = 'pointer';
```

Key options:

| Option | Effect |
| --- | --- |
| `positionProperty` | Property written during the drag (model coordinates when `transform` is provided) |
| `transform` | A `ModelViewTransform2`; converts pointer motion into model units |
| `dragBoundsProperty` | Clamps the position to bounds (same frame as `positionProperty`) |
| `start` / `drag` / `end` | Callbacks around the drag lifecycle |
| `useParentOffset` | Keeps the grab point fixed relative to the node instead of jumping its origin to the pointer |
| `allowTouchSnag` | Lets a touch that starts on the node immediately begin dragging (default `true`) |
| `targetNode` | Node whose coordinate frame is used, when the listener is attached elsewhere |

Setting `userControlledProperty` in `start`/`end` is the standard way to tell the model to stop animating a body while the user holds it.

## KeyboardDragListener (alternative input)

Pointer dragging alone is not accessible. `KeyboardDragListener` moves the same Property with arrow keys and WASD, and requires the node to be focusable in the [PDOM](/accessibility/pdom):

```ts
import { KeyboardDragListener } from 'scenerystack/scenery';

bodyNode.addInputListener( new KeyboardDragListener( {
  positionProperty: body.positionProperty,
  transform: modelViewTransform,
  dragBoundsProperty: model.dragBoundsProperty,
  dragSpeed: 150,       // model units per second while a key is held
  shiftDragSpeed: 50    // finer motion with shift held
} ) );

// PDOM: focusable with a meaningful accessible name
bodyNode.tagName = 'div';
bodyNode.focusable = true;
bodyNode.accessibleName = 'Planet';
```

## RichDragListener (both at once)

`RichDragListener` bundles a `DragListener` and a `KeyboardDragListener` behind one API, so every draggable gets pointer and keyboard support from a single declaration. Prefer it for new code:

```ts
import { RichDragListener } from 'scenerystack/scenery';

bodyNode.addInputListener( new RichDragListener( {
  positionProperty: body.positionProperty,
  transform: modelViewTransform,
  dragBoundsProperty: model.dragBoundsProperty,
  keyboardDragListenerOptions: {
    dragSpeed: 150
  }
} ) );
```

::: tip Checklist for a well-behaved draggable
1. Listener writes a **model** Property through `transform` — the node observes it back.
2. `dragBoundsProperty` keeps the object reachable (nothing draggable off-screen).
3. Keyboard path exists (`RichDragListener`, or `KeyboardDragListener` + focusable PDOM).
4. `cursor = 'pointer'` and, for touch, adequate `touchArea` / `mouseArea` dilation.
5. `userControlledProperty` toggled in `start`/`end` if the model animates the object.
:::


========================================================================
Page: Emitter vs. Property
URL: https://veillette.github.io/Almanach/patterns/emitter-vs-property
Source: docs/patterns/emitter-vs-property.md
Category: Patterns | Tags: axon, Emitter, Property, architecture | Status: verified
========================================================================

# Emitter vs. Property

The axon library gives you two different primitives for "something changed," and picking the wrong one is a common source of bugs: a **Property** holds a *value* that persists between reads (ask it "what is the current state?" any time), while an **Emitter** fires a *momentary event* that has no state at all — if nobody was listening when it fired, that information is gone. Model anything that answers "what is it right now?" as a Property; model anything that answers "did X just happen?" as an Emitter.

## The core idea

```ts
import { Property, BooleanProperty, Emitter } from 'scenerystack/axon';

class BallModel {

  // STATE: has a current value at every instant, observers can read .value at any time.
  public readonly positionProperty = new Property( 0 );
  public readonly isMovingProperty = new BooleanProperty( false );

  // EVENT: a discrete occurrence with no persisted value. A listener added
  // a moment after the bounce will simply never know it happened.
  public readonly bouncedEmitter = new Emitter<[ speed: number ]>( {
    parameters: [ { valueType: 'number' } ]
  } );

  public step( dt: number ): void {
    // ...advance the physics...
    const hitWall = false; // placeholder for a real collision check
    if ( hitWall ) {
      this.bouncedEmitter.emit( 3.2 ); // notify listeners of the bounce speed
    }
  }
}

const ball = new BallModel();
ball.positionProperty.link( position => console.log( 'position is now', position ) );
ball.bouncedEmitter.addListener( speed => console.log( 'bounced at', speed ) );
```

## Deciding which one to reach for

| Question | Use |
| --- | --- |
| "Can I ask for the current value at an arbitrary later time?" | `Property` (or `DerivedProperty` if it's computed from other Properties) |
| "Does a UI element need to bind to this (a slider, a checkbox, a readout)?" | `Property` — controls read and write `.value` |
| "Is this a one-time occurrence with no lasting value (a collision, a button press, 'level completed')?" | `Emitter` |
| "Would storing it as a boolean/enum Property force an awkward reset back to `false` right after reading it?" | `Emitter` — that's a sign it was never really state |

::: tip Don't fake an event with a Property
A common anti-pattern is a `collidedProperty: BooleanProperty` that gets set to `true` and then immediately reset to `false` so it can be "triggered" again. This is strictly worse than an `Emitter<[]>`: it forces every listener to use `lazyLink` and reason about ordering, and two collisions in the same frame collapse into one notification. If you find yourself resetting a Property right after setting it, it isn't state — model it as an `Emitter` instead.
:::


========================================================================
Page: Feature Flags and Preferences Pattern
URL: https://veillette.github.io/Almanach/patterns/feature-flags-and-preferences-pattern
Source: docs/patterns/feature-flags-and-preferences-pattern.md
Category: Patterns | Tags: query-parameters, Property, feature-flag, preferences | Status: verified
========================================================================

# Feature Flags and Preferences Pattern

[Preferences and Feature Flags](/guides/preferences-and-feature-flags) explains the two broad mechanisms SceneryStack gives you — the Preferences dialog and query parameters — and when to reach for each. This page is narrower: it's the one specific convention to follow *within* either mechanism so a codebase doesn't accumulate a dozen inconsistent ad hoc flags. The convention: **gate a feature behind exactly one boolean `Property`, named `<feature>FeatureEnabledProperty`, initialized once from a query parameter (or a `PreferencesModel` entry) and read everywhere the feature branches.**

## The convention

```ts
// MySimQueryParameters.ts
import { QueryStringMachine } from 'scenerystack/query-string-machine';

const MySimQueryParameters = QueryStringMachine.getAll( {
  // ?showVelocityVectors=true
  showVelocityVectors: {
    type: 'flag'
  }
} );

export default MySimQueryParameters;
```

```ts
// MySimFeatures.ts
import { BooleanProperty } from 'scenerystack/axon';
import MySimQueryParameters from './MySimQueryParameters.js';

const MySimFeatures = {
  // One boolean Property per feature, named consistently, initialized once at module load.
  velocityVectorsFeatureEnabledProperty: new BooleanProperty( MySimQueryParameters.showVelocityVectors )
};

export default MySimFeatures;
```

```ts
// Anywhere the feature branches - model or view - read the Property, never the raw query parameter.
import MySimFeatures from './MySimFeatures.js';

if ( MySimFeatures.velocityVectorsFeatureEnabledProperty.value ) {
  this.children.push( new VelocityVectorNode( model ) );
}
```

## Why a Property, and why one specific name shape

- **Consistency lets you grep for every feature flag in a codebase** with one pattern (`FeatureEnabledProperty`) instead of some code checking `MySimQueryParameters.showX` directly, other code checking a locally-scoped boolean, and a third piece checking a `PreferencesModel` field — three different shapes for the same kind of decision.
- **A `Property`, not a plain `boolean` constant**, means the same flag can later be promoted to a real user-facing Preferences toggle (see [Preferences and Feature Flags](/guides/preferences-and-feature-flags)) by changing only where the `Property`'s initial value comes from — every read site (`if ( ...FeatureEnabledProperty.value )` or `...FeatureEnabledProperty.link(...)`) is unaffected.
- **Reading the `Property` instead of the raw query parameter at every branch point** means a feature that later needs to be toggled at runtime (from Preferences, or from a debug menu) doesn't require hunting down every `MySimQueryParameters.showX` reference and swapping it for something reactive.

## Anti-pattern: branching on the raw query parameter everywhere

```ts
// Don't do this - MySimQueryParameters.showVelocityVectors is read directly in three
// unrelated files, with no single Property to promote to a real preference later,
// and no way to .link() a view update if the flag ever needs to change at runtime.
if ( MySimQueryParameters.showVelocityVectors ) {
  this.children.push( new VelocityVectorNode( model ) );
}
```

::: tip One flag, one Property, one name shape
Resist the temptation to special-case a flag's name ("just this one is `showFoo` instead of `fooFeatureEnabledProperty`") because it seemed temporary. Flags marked temporary are the ones most likely to still be in the codebase a year later — pay the small consistency cost up front so every feature flag in the project is discoverable the same way.
:::


========================================================================
Page: Grid-Snapping and Constrained-Dragging Pattern
URL: https://veillette.github.io/Almanach/patterns/grid-snapping-and-constrained-dragging-pattern
Source: docs/patterns/grid-snapping-and-constrained-dragging-pattern.md
Category: Patterns | Tags: scenery, DragListener, drag, constraint, grid-snapping | Status: complete
========================================================================

# Grid-Snapping and Constrained-Dragging Pattern

[Drag Listeners](/patterns/drag-listeners) covers the baseline pattern: a listener writes a model `positionProperty`, converted through a `ModelViewTransform2`, and the view updates by observing that Property like any other. Constrained dragging — snapping to a grid, clamping to bounds, restricting motion to one axis — is not a different mechanism from that baseline; it's a transformation applied to the value *before* it's written to the model Property. This page is about *when* and *why* to reach for a constraint, not the mechanics of writing one (see [Snapping a Draggable Node to a Grid](/cookbook/snapping-a-draggable-node-to-a-grid) for the concrete recipe).

## Where a constraint hooks in

[`DragListener`](/api/scenery/drag-listener) (and, by extension, [`RichDragListener`](/api/scenery/rich-drag-listener), which shares the same drag options) accepts both a `dragBoundsProperty` for clamping to a `Bounds2`, and a `mapPosition` option — `( point: Vector2 ) => Vector2`, applied *before* `dragBoundsProperty` — for arbitrary transformations of the dragged model position, which is exactly the hook a grid-snap function plugs into. This is the same shape [`HSlider`'s `constrainValue` option](/api/sun/hslider) uses to let a slider snap to a grid of values instead of continuous ones — a grid-snap, an axis lock, and a bounds clamp are all the same kind of hook applied with a different transformation function, none of them requiring a different listener class or a departure from the ordinary [drag-listener](/patterns/drag-listeners) wiring.

## Why constrain dragging at all

| Constraint | Solves |
| --- | --- |
| Snap to a grid | The model has a natural discrete structure (a board game's cells, a periodic table slot, integer-only positions) where "anywhere in between" is not a meaningful or valid state |
| Clamp to bounds (`dragBoundsProperty`) | Keeps a draggable object reachable and recoverable — nothing draggable off the visible play area with no way back, part of the [Drag Listeners](/patterns/drag-listeners) checklist for a well-behaved draggable |
| Restrict to one axis | The underlying model quantity is genuinely one-dimensional (a single slider-like value, a position along a fixed path) even though the visual control might otherwise invite two-dimensional dragging |

The unifying principle: a constraint exists because the **model** has a restriction the raw pointer position doesn't know about — free-form pointer motion is inherently continuous and two-dimensional, and a constraint is how that gets reconciled with a model whose valid states are a smaller set (a grid, a range, a line). Adding a constraint is a model-driven decision, not a view polish choice — reach for it because the model's state genuinely only makes sense in discrete/bounded/one-dimensional terms, not merely because snapping "feels nice."

## Snapping happens in model coordinates

Because the constraint is really about what the *model* considers a valid value, snapping/clamping logic should operate on the model-coordinate value the drag listener is about to write — after the `transform` option has converted from view pixels — not on raw view pixels before conversion. Snapping in view pixels ties the grid spacing to the current zoom/scale of the `ModelViewTransform2` in use; snapping the model value keeps the grid spacing meaningful (e.g. "snap to every 0.5 meters") independent of how many view pixels currently represent that distance. See [Working with Model-View Transforms](/guides/working-with-model-view-transforms) for why the transform boundary is where conversions like this belong.

## What constrained dragging doesn't change

A constraint doesn't alter anything else about the drag-listener pattern: the listener still writes a model `Property`, the view still only observes it, `dragBoundsProperty` and a constraint transform can be combined freely (clamp to bounds *and* snap to a grid within them), and the [Drag Listeners](/patterns/drag-listeners) checklist — keyboard path, `cursor`, touch area dilation, `userControlledProperty` toggling — still applies unchanged. Constraining the value is strictly additive on top of that baseline, not a parallel pattern to learn separately.

::: tip Don't snap harder than the model needs
A constraint should match the model's actual granularity — snapping to a finer or coarser grid than the model's valid states actually have either loses precision the model supports, or invites values the model doesn't consider meaningful. If the model's valid positions are continuous and only the *view* wants a tidier look, reconsider whether a constraint is the right tool at all, versus a purely visual layout decision that never touches the dragged Property's value.
:::


========================================================================
Page: Immutable vs. Mutable Model Data
URL: https://veillette.github.io/Almanach/patterns/immutable-vs-mutable-model-data
Source: docs/patterns/immutable-vs-mutable-model-data.md
Category: Patterns | Tags: dot, Vector2, Bounds2, Property, immutability, performance | Status: complete
========================================================================

# Immutable vs. Mutable Model Data

`Property<T>` notifies its listeners by comparing whether `.value` *changed* — for that comparison to mean anything, the value it holds needs to actually be a new, distinct value when something changes, not the same object with different contents. This is why SceneryStack's math types (`Vector2`, `Bounds2`, and the rest of `dot`) default to a functional style — `.plus()`, `.times()`, `.withMagnitude()` all return a *new* instance rather than modifying the receiver — and why the default, correct way to update a `Property<Vector2>` is replacing the whole value, not mutating the vector already sitting inside it.

## The default: replace, don't mutate

```ts
import { Vector2 } from 'scenerystack/dot';
import { Property } from 'scenerystack/axon';

const positionProperty = new Property( new Vector2( 0, 0 ) );

positionProperty.link( position => console.log( 'moved to', position.toString() ) );

// Correct: .plus() returns a new Vector2; assigning it to .value fires listeners.
positionProperty.value = positionProperty.value.plus( new Vector2( 1, 0 ) );
```

```ts
// Wrong: mutates the Vector2 already stored in the Property in place.
positionProperty.value.x += 1; // Property never fires - .value itself didn't change (same object).
```

The second example is the single most common bug this pattern guards against: `Property.set()` only notifies listeners when the *new* value differs from the old one by its equality check (by default, `!==` on the reference for object types) — mutating the existing object's fields in place leaves `.value` pointing at the exact same reference, so nothing fires, and every view observing `positionProperty` silently goes stale.

## Why the math types are built this way

`Vector2.plus( other )`, `Bounds2.dilated( amount )`, and their siblings across `dot` all return a new instance instead of mutating the receiver specifically so that "the model state changed" and "the object I'm holding was mutated" stay the same question, not two questions that can drift apart. If `.plus()` mutated the receiver, `positionProperty.value.plus( delta )` would silently corrupt the value already stored in the Property (correctly *changing* the model, but through a side channel `Property` never observed, so no listener would fire) — the functional style makes "did I actually get a new value" and "did I remember to reassign `.value`" the same act.

## When in-place mutation is the right call

Not everything should be wrapped in a fresh object on every change. In-place mutation is appropriate — and is what `dot`'s types offer via a parallel set of mutating methods (`vector.setXY( x, y )`, `vector.add( delta )`, `bounds.dilate( amount )`, consistently distinguished by name from their non-mutating counterparts — see [Vector2](/api/dot/vector2#immutable-vs-mutable-methods) and [Bounds2](/api/dot/bounds2) for the full immutable/mutable method tables) — when:

| Prefer mutating in place | Prefer replacing the value |
| --- | --- |
| The object is *not* itself a `Property`'s `.value` — it's a private working buffer/accumulator local to one method, never observed directly | The object *is* what a `Property` holds, and other code needs to be notified when it changes |
| A hot per-frame loop (particle simulation, many-body physics) where allocating a new `Vector2` per object per frame is a measurable performance cost | Correctness/observability matters more than the allocation cost — the overwhelming majority of simulation model state |
| The mutated object's identity genuinely doesn't matter to anyone downstream | Something (a view, a `DerivedProperty`, PhET-iO state capture) needs to react specifically to *this* value changing |

```ts
// A hot inner loop updating many particles' positions per frame: mutating in place
// avoids allocating a new Vector2 per particle per frame, and nothing observes
// each particle's position as an individual Property - only the aggregate render matters.
for ( const particle of particles ) {
  particle.position.add( particle.velocity.timesScalar( dt ) ); // in-place, by design
}
```

The distinguishing question is always the same: **is this value the thing a `Property` (or anything else) is watching for changes?** If yes, replace it and let the Property's own change-detection do its job. If it's a private, unobserved working value, in-place mutation is a legitimate and sometimes necessary optimization — just make sure it never leaks into being a `Property`'s `.value` by reference, where the same mutation would silently defeat change notification.

::: warning A mutated object inside a Property is a specific, easy-to-miss bug
Because `position.x += 1` and `positionProperty.value = position.plusXY( 1, 0 )` look similar and both "work" in the sense that `position.x` ends up correct either way, this bug doesn't show up as a crash — it shows up as a view that mysteriously stops updating, or a `DerivedProperty` that never recomputes, with no error anywhere. If a Property-backed value ever needs updating, reach for the non-mutating method (`.plus()`, `.with*()`) and reassign `.value`, never a mutating method (`.add()`, `.set*()`) called on `property.value` directly.
:::


========================================================================
Page: Lazy Initialization Pattern
URL: https://veillette.github.io/Almanach/patterns/lazy-initialization-pattern
Source: docs/patterns/lazy-initialization-pattern.md
Category: Patterns | Tags: performance, architecture, lazy-initialization | Status: complete
========================================================================

# Lazy Initialization Pattern

Some objects in a simulation are expensive enough to construct — a large procedurally-generated `Shape`, a chart pre-populated with a big dataset, a rarely-used dialog's entire Node subtree — that building every one of them unconditionally at startup measurably slows down the time before a user sees anything. Lazy initialization defers that cost until the object is *actually* needed, rather than eagerly during construction of whatever owns it.

## The general shape

The pattern is always the same regardless of what's being deferred: replace an eagerly-constructed field with a function that constructs (and caches) the value on first access, rather than a value already sitting there:

```ts
class SomeContainer {

  // Eager: pays the cost unconditionally, even if never used.
  // public readonly expensiveThing = buildExpensiveThing();

  // Lazy: cost is deferred until first access, and paid at most once.
  private _expensiveThing: ExpensiveThing | null = null;

  public getExpensiveThing(): ExpensiveThing {
    if ( this._expensiveThing === null ) {
      this._expensiveThing = buildExpensiveThing();
    }
    return this._expensiveThing;
  }
}
```

The essential property this preserves is that callers still get a single, consistent instance — `getExpensiveThing()` called twice returns the same object both times, exactly as if it had been constructed eagerly — the only thing that changed is *when* that construction happens.

## Where SceneryStack already relies on this

This isn't a novel technique layered on top of SceneryStack — it's the same shape [`Screen`](/api/joist/screen) itself is built around: a `Screen`'s `createModel`/`createView` factory functions are only invoked once `Sim` actually needs that screen, not eagerly when the `Screen` is constructed. A multi-screen sim's second and third screens don't pay their model/view construction cost until (or unless) the user navigates to them, which is exactly why a sim with many screens can still start up quickly — the *sum* of every screen's construction cost is never paid all at once.

## When to reach for it yourself

| Reach for lazy initialization | Skip it |
| --- | --- |
| The object is expensive to construct (measurable time or memory) *and* isn't guaranteed to be needed every session — a rarely-opened dialog, an alternate visualization mode, a large precomputed dataset | Construction is cheap — the overhead of the lazy-init machinery itself can exceed the cost it's supposedly saving |
| The cost shows up in a profile as part of startup, specifically (see [Performance and Profiling](/guides/performance-and-profiling)) | You're guessing an object "seems expensive" without having profiled — see the same page's warning against optimizing before measuring |
| The object's identity/singleton-ness matters (the same instance every time it's requested) | Every access legitimately needs a fresh instance — that's not memoization, it's just calling a constructor, and doesn't need the cached-field machinery at all |

For the single most common concrete case — deferring construction of an expensive `Node` until it first becomes visible — see [Lazily Creating an Expensive Node](/cookbook/lazily-creating-an-expensive-node) for the worked recipe; this page is the general principle behind that specific technique, which also applies to non-`Node` expensive objects (a precomputed dataset, a large `Shape`) the same way.

::: tip Don't lazily initialize something you'll need immediately anyway
If profiling shows an object is expensive *and* every session ends up needing it within the first few seconds regardless, deferring its construction doesn't reduce total work done — it just moves the same cost to a slightly later, potentially more visible moment (e.g. the first time a user opens the panel that needs it, instead of during an initial loading screen where the delay is expected). Lazy initialization pays off specifically when the object is *conditionally* needed — many sessions never touch it at all — not merely when it's expensive.
:::


========================================================================
Page: Model-View Separation
URL: https://veillette.github.io/Almanach/patterns/model-view-separation
Source: docs/patterns/model-view-separation.md
Category: Patterns | Tags: architecture, axon, Property, DerivedProperty, MVC | Status: verified
========================================================================

# Model-View Separation

Every SceneryStack application is built around a strict one-way dependency: the **model** is a plain TypeScript object graph whose state lives in axon `Property` instances, and the **view** is a scenery `Node` tree that *observes* the model. The model never imports from the view, never mentions pixels, and can run headless in a unit test.

## The model: axon Properties

```ts
import { NumberProperty, Property, DerivedProperty, type TReadOnlyProperty } from 'scenerystack/axon';
import { Vector2, Range } from 'scenerystack/dot';

export class ProjectileModel {

  // Mutable state is a Property. Physical units only — meters, seconds.
  public readonly positionProperty = new Property( new Vector2( 0, 0 ) );
  public readonly massProperty = new NumberProperty( 5, { range: new Range( 1, 20 ) } ); // kg

  // Derived state is a DerivedProperty: never stored redundantly, never stale.
  // Typed as TReadOnlyProperty, not DerivedProperty<...>, because DerivedProperty's own
  // generic parameters are positional per-dependency (T, T1, T2, ... T15), not a single
  // tuple - TReadOnlyProperty<number> is what you actually want to expose here.
  public readonly weightProperty: TReadOnlyProperty<number>;

  public constructor() {
    this.weightProperty = new DerivedProperty( [ this.massProperty ], mass => mass * 9.8 );
  }

  public step( dt: number ): void {
    // Advance physics in model units; observers update automatically.
  }

  public reset(): void {
    this.positionProperty.reset();
    this.massProperty.reset();
  }
}
```

Guidelines:

- Expose Properties as `public readonly`; mutate their `.value`, not the field.
- Anything computable from other state should be a `DerivedProperty`, not a second source of truth.
- Discrete events that aren't state (a collision, a reset) use `Emitter`.
- Provide a `reset()` that resets every Property — the standard Reset All button calls it.

## The view: observing, never owning state

```ts
import { Circle } from 'scenerystack/scenery';
import { ModelViewTransform2 } from 'scenerystack/phetcommon';

export class ProjectileNode extends Circle {
  public constructor( model: ProjectileModel, modelViewTransform: ModelViewTransform2 ) {
    super( 15, { fill: 'orange' } );

    // View subscribes to the model. Conversion to pixels happens here, at the
    // boundary, via the transform — see /api/phetcommon/model-view-transform.
    model.positionProperty.link( position => {
      this.translation = modelViewTransform.modelToViewPosition( position );
    } );
  }
}
```

When the view needs to *change* the model (a slider, a [drag listener](/patterns/drag-listeners)), it writes to the model's Properties — it does not keep its own copy:

```ts
massSlider = new HSlider( model.massProperty, model.massProperty.range );
```

The Property is the single source of truth; the slider both writes it and reacts to it, so external changes (reset, PhET-iO, another control) stay consistent for free.

## Why this matters at scale

- **Testability** — the model runs and is assertable without a DOM.
- **Multiple views** — a chart, a readout, and the scene graph can all observe the same Property without coordination.
- **Reset, undo, PhET-iO serialization** — all become mechanical when state is enumerable Properties instead of scattered fields.


========================================================================
Page: Multi-Screen Sim Structure
URL: https://veillette.github.io/Almanach/patterns/multi-screen-sim-structure
Source: docs/patterns/multi-screen-sim-structure.md
Category: Patterns | Tags: joist, Screen, Sim, architecture | Status: verified
========================================================================

# Multi-Screen Sim Structure

Each `Screen` owns exactly one model/view pair and is self-contained; the `Sim` itself does no screen-specific work — it only collects the screens and hands them a title. Code genuinely shared by more than one screen (a constants file, a reusable sub-model, a shared control) lives in a `common/` location that every screen imports from, never in one screen importing from another. This keeps a screen removable or reorderable without hunting for cross-screen dependencies.

## The core idea

```ts
import { Sim, Screen, ScreenView, ScreenIcon, onReadyToLaunch, type ScreenViewOptions } from 'scenerystack/sim';
import { Tandem } from 'scenerystack/tandem';
import { Property } from 'scenerystack/axon';
import { Rectangle, Text } from 'scenerystack/scenery';

// --- common/ : code shared by more than one screen ---
class SharedConstants {
  public static readonly PANEL_MARGIN = 10;
}

// --- intro/ : this screen's own model, never imported by other screens ---
class IntroModel {
  public reset(): void { /* reset this screen's Properties */ }
}

class IntroScreenView extends ScreenView {
  public constructor( model: IntroModel, providedOptions: ScreenViewOptions ) {
    super( providedOptions );
    const label = new Text( 'Intro', { font: '24px sans-serif' } );
    label.center = this.layoutBounds.center;
    this.addChild( label );
  }
}

function createIntroScreenIcon(): ScreenIcon {
  return new ScreenIcon( new Rectangle( 0, 0, 10, 10, { fill: 'blue' } ) );
}

// --- advanced/ : a second, independent screen ---
class AdvancedModel {
  public reset(): void { /* reset this screen's Properties */ }
}

class AdvancedScreenView extends ScreenView {
  public constructor( model: AdvancedModel, providedOptions: ScreenViewOptions ) {
    super( providedOptions );
    const label = new Text( 'Advanced', { font: '24px sans-serif' } );
    label.center = this.layoutBounds.center;
    this.addChild( label );
  }
}

function createAdvancedScreenIcon(): ScreenIcon {
  return new ScreenIcon( new Rectangle( 0, 0, 10, 10, { fill: 'red' } ) );
}

// --- top level: wire screens into the Sim, nothing screen-specific here ---
const introTandem = Tandem.ROOT.createTandem( 'introScreen' );
const introScreen = new Screen(
  () => new IntroModel(),
  model => new IntroScreenView( model, { tandem: introTandem.createTandem( 'view' ) } ),
  {
    name: new Property( 'Intro' ),
    homeScreenIcon: createIntroScreenIcon(),
    backgroundColorProperty: new Property( 'white' ),
    tandem: introTandem
  }
);

const advancedTandem = Tandem.ROOT.createTandem( 'advancedScreen' );
const advancedScreen = new Screen(
  () => new AdvancedModel(),
  model => new AdvancedScreenView( model, { tandem: advancedTandem.createTandem( 'view' ) } ),
  {
    name: new Property( 'Advanced' ),
    homeScreenIcon: createAdvancedScreenIcon(),
    backgroundColorProperty: new Property( 'white' ),
    tandem: advancedTandem
  }
);

onReadyToLaunch( () => {
  const sim = new Sim( new Property( 'My Multi-Screen Sim' ), [ introScreen, advancedScreen ] );
  sim.start();
} );
```

## What goes where

| Location | Contents |
| --- | --- |
| `common/` (or a shared module) | Constants, utility functions, and any sub-model/component genuinely used by two or more screens |
| `<screen-name>/model/` | That screen's model classes — imported only by that screen's own view and the top-level wiring |
| `<screen-name>/view/` | That screen's `ScreenView` subclass and any Nodes specific to it |
| Top level (where `Sim` is constructed) | Only the list of `Screen`s and the sim-wide title `Property` — no per-screen logic |

Each screen also gets its own `Tandem` subtree (`introTandem`, `advancedTandem` above), created from `Tandem.ROOT`, so PhET-iO's element tree mirrors the screen boundaries — see [The PhET-iO Instrumentation Pattern](/patterns/phet-io-instrumentation-pattern).

::: warning `name` and the icons are optional in the types, but silently degrade if omitted on a multi-screen sim
`Screen`'s `name` (a `TReadOnlyProperty<string>`, not a plain string) and its `homeScreenIcon`/`navigationBarIcon` may be omitted for a single-screen sim, since there is no home screen or navigation bar to show them in. Nothing throws if you omit them on a multi-screen sim either — `Screen` falls back to a blank name and a plain colored-rectangle icon (`navigationBarIcon` further falls back to a scaled copy of `homeScreenIcon`) — but the home screen and navigation bar become genuinely unusable that way, so supply a real `name` and `homeScreenIcon` for every screen once there's more than one.
:::


========================================================================
Page: PhET-iO Instrumentation Pattern
URL: https://veillette.github.io/Almanach/patterns/phet-io-instrumentation-pattern
Source: docs/patterns/phet-io-instrumentation-pattern.md
Category: Patterns | Tags: tandem, phet-io, architecture | Status: verified
========================================================================

# PhET-iO Instrumentation Pattern

::: tip Scope: conventions for wiring tandems
This is a **prescriptive pattern** for structuring instrumentation in model and view code. For the conceptual overview of PhET-iO, read [PhET-iO and Instrumentation](/guides/phet-io-and-instrumentation) first; for `PhetioGroup`/`PhetioCapsule` and custom `IOType`s, read [PhET-iO Deep Dive](/guides/phet-io-deep-dive).
:::

A `Tandem` is a stable, hierarchical name (like a file path) that a `PhetioObject` — a `Property`, a `Node`, a `Screen`, the `Sim` itself — carries so PhET-iO wrappers can find and control it from outside the sim. Every simulation carries this plumbing whether or not PhET-iO is ever enabled for it, so the convention is to always pass `tandem` down through your model and view constructors and let each state-bearing `Property` create its own child tandem — rather than deciding instrumentation is "a PhET-iO feature" to bolt on later, which in practice means rewriting the whole model.

## The core idea

```ts
import { NumberProperty, BooleanProperty, DerivedProperty, type TReadOnlyProperty } from 'scenerystack/axon';
import { Tandem, NumberIO } from 'scenerystack/tandem';
import { Range } from 'scenerystack/dot';

class ProjectileModel {

  // A state Property a PhET-iO client can read, save, and restore: instrumented.
  public readonly angleProperty: NumberProperty;

  // A state Property a PhET-iO client can also set from outside (a control, not just an output): instrumented.
  public readonly isRunningProperty: BooleanProperty;

  // Recomputed automatically from angleProperty - no independent state to save, so it needs
  // a phetioValueType but is marked phetioReadOnly (it is never *set* directly by a client).
  // Typed as TReadOnlyProperty, not DerivedProperty<...>, since DerivedProperty's own generic
  // parameters are positional per-dependency (T, T1, T2, ... T15), not a single type argument.
  public readonly heightAtLaunchProperty: TReadOnlyProperty<number>;

  public constructor( tandem: Tandem ) {

    this.angleProperty = new NumberProperty( 45, {
      range: new Range( 0, 90 ),
      tandem: tandem.createTandem( 'angleProperty' ),
      phetioDocumentation: 'Launch angle, in degrees above the horizontal.'
    } );

    this.isRunningProperty = new BooleanProperty( false, {
      tandem: tandem.createTandem( 'isRunningProperty' )
    } );

    this.heightAtLaunchProperty = new DerivedProperty( [ this.angleProperty ], angle => Math.sin( angle ), {
      tandem: tandem.createTandem( 'heightAtLaunchProperty' ),
      phetioValueType: NumberIO,
      phetioDocumentation: 'Derived from angleProperty; not independently settable.'
    } );
  }

  public reset(): void {
    this.angleProperty.reset();
    this.isRunningProperty.reset();
    // heightAtLaunchProperty needs no reset() call - it recomputes from angleProperty.
  }
}
```

Wiring the model's tandem in from its `Screen`, the way [Multi-Screen Sim Structure](/patterns/multi-screen-sim-structure) already threads `tandem` down to each screen's view:

```ts
import { Screen, ScreenView, type ScreenViewOptions } from 'scenerystack/sim';

class ProjectileScreenView extends ScreenView {
  public constructor( model: ProjectileModel, providedOptions: ScreenViewOptions ) {
    super( providedOptions );
  }
}

const screenTandem = Tandem.ROOT.createTandem( 'introScreen' );

const introScreen = new Screen(
  () => new ProjectileModel( screenTandem.createTandem( 'model' ) ),
  model => new ProjectileScreenView( model, { tandem: screenTandem.createTandem( 'view' ) } ),
  {
    tandem: screenTandem
    // ...name, icons, etc. - see Multi-Screen Sim Structure
  }
);
```

## Deciding what to instrument

| Instrument it | Leave it uninstrumented (no `tandem` option passed) |
| --- | --- |
| Model `Property`s a user can change or that represent saveable state (`angleProperty`, `isRunningProperty`) | Purely transient view state (a tooltip's hover flag, an in-progress animation position) |
| `DerivedProperty`s a client might want to read, even if read-only (`heightAtLaunchProperty`) | Internal implementation-detail Properties nothing outside the class ever needs to see |
| Every `Screen` and the `Sim` itself (required — `Screen`'s `tandem` option is `Tandem.REQUIRED` by default) | One-off local variables and closures that never outlive a single method call |

Each child tandem's name should describe what it names, not how it's implemented (`angleProperty`, not `_angle` or `p1`) — PhET-iO wrappers and the state-saving system address the object by that name, so renaming it later is a breaking change for anyone automating the sim.

::: tip Uninstrumented is the safe default; over-instrumenting is the expensive mistake
Passing `Tandem.REQUIRED` (or a real tandem) into every constructor and only actually calling `createTandem` for the state above costs nothing when PhET-iO is off. Instrumenting something that is really transient view state, on the other hand, makes it part of the sim's saved/restored PhET-iO state forever — removing it later is a compatibility break for any wrapper depending on it. When in doubt, leave it uninstrumented; it's cheap to add a tandem later, expensive to remove one.
:::


========================================================================
Page: Query Parameters Pattern
URL: https://veillette.github.io/Almanach/patterns/query-parameters-pattern
Source: docs/patterns/query-parameters-pattern.md
Category: Patterns | Tags: query-parameters, conventions | Status: verified
========================================================================

# Query Parameters Pattern

Optional or debug-only behavior (an initial screen selection, a background color override, a "show answers" cheat mode) is driven by URL query parameters rather than a build-time flag, parsed once at startup through a single schema object passed to `QueryStringMachine.getAll`. Declaring every parameter's type and default up front in one place — instead of reading `location.search` ad hoc wherever a flag is needed — is what gives each parameter type coercion, a documented default, and validation for free.

## The core idea

```ts
import { QueryStringMachine } from 'scenerystack/query-string-machine';

const myQueryParameters = QueryStringMachine.getAll( {

  // Background color of the sim's screens, in any CSS color format.
  backgroundColor: {
    type: 'string',
    defaultValue: 'white'
  },

  // Initial value for the model's speed multiplier.
  speed: {
    type: 'number',
    defaultValue: 1,
    isValidValue: ( value: number ) => value > 0
  },

  // A debug-only flag: present with no value means true, absent means false.
  showAnswers: {
    type: 'flag'
  }
} );

// myQueryParameters.backgroundColor: string
// myQueryParameters.speed: number
// myQueryParameters.showAnswers: boolean

if ( myQueryParameters.showAnswers ) {
  // reveal debug-only content
}
```

Reading `?speed=2&showAnswers` from the URL yields `{ backgroundColor: 'white', speed: 2, showAnswers: true }` — untouched parameters silently fall back to their `defaultValue`.

## Schema fields

| Field | Effect |
| --- | --- |
| `type` | `'flag'` \| `'boolean'` \| `'number'` \| `'string'` \| `'array'` \| `'custom'` — determines parsing and the resulting TypeScript type |
| `defaultValue` | Value used when the parameter is absent from the URL — omitting it is only safe for `type: 'flag'` (which defaults to `false`); for every other type, a parameter that's both absent from the URL and missing a `defaultValue` throws at parse time |
| `validValues` | Restrict to an enumerated set of values |
| `isValidValue` | Custom predicate the parsed value must satisfy |
| `public` | If `true`, an invalid value warns and falls back to the default instead of throwing |
| `private` | Only read from the URL for team members (gated by a `phetTeamMember` local-storage check) |

::: tip Verified against source; the module-location convention is still a reasonable default, not a confirmed house style
The exact call — `QueryStringMachine.getAll({ ... })` with `type`/`defaultValue`/`validValues`/`isValidValue`/`public`/`private` fields, including the runtime behavior of each (an absent `defaultValue` on a non-flag type throws unless the URL supplies the value; `public: true` downgrades an invalid value to a warning-plus-fallback instead of throwing; `private: true` gates URL reads on a `phetTeamMember` local-storage check) — was checked directly against `QueryStringMachineModule.ts` and real per-library usages (e.g. `sunQueryParameters.ts`, `SceneryQueryParameters.ts`) in the real `scenerystack` package source. What's *not* independently verified is the broader convention for where a sim-author-facing query-parameters module should live and how it should be named in application code outside the PhET repos themselves — treat that part as a reasonable default, not a confirmed house style.
:::


========================================================================
Page: Singleton and Namespace Conventions
URL: https://veillette.github.io/Almanach/patterns/singleton-and-namespace-conventions
Source: docs/patterns/singleton-and-namespace-conventions.md
Category: Patterns | Tags: singleton, conventions, dotRandom, animationFrameTimer, Namespace, architecture | Status: verified
========================================================================

# Singleton and Namespace Conventions

SceneryStack code reaches for two distinct shapes when a library needs to expose reusable, shared state: a **ready-made singleton instance** the library constructs and exports for you, versus a **class you construct your own instance of**, scoped to whatever owns it. Neither shape is "more correct" in general — the right one depends entirely on whether the thing in question has exactly one meaningful instance for the whole running sim, or many independent instances that would conflict if shared.

## Ready-made singletons: shared by construction

Some things are correct to share across an entire sim, and the library exports a single pre-built instance rather than a class you'd construct yourself:

```ts
import { dotRandom } from 'scenerystack/dot';
import { stepTimer, animationFrameTimer } from 'scenerystack/axon';
import { soundManager } from 'scenerystack/tambo';

dotRandom.nextDouble();                 // the one shared random source
stepTimer.setTimeout( () => {}, 500 );  // the one shared model-time scheduler
soundManager.addSoundGenerator( myClip ); // the one shared audio mixer
```

[`dotRandom`](/api/dot/random), [`stepTimer`/`animationFrameTimer`](/api/axon/timer), and `soundManager` (see [Working with Sound](/guides/working-with-sound)) all follow this shape, and for the same underlying reason in each case: there is exactly one meaningful instance for the whole sim, and constructing a second one would be actively wrong, not just redundant.

- **`dotRandom`** — a sim's randomness needs to funnel through one seed so PhET-iO's seeded/reproducible playback works; a `new Random()` constructed independently in one file has no relationship to the seed everything else uses.
- **`stepTimer`/`animationFrameTimer`** — there is one running sim loop; a second, independently-constructed `Timer` instance wouldn't be driven by anything and would simply never fire.
- **`soundManager`** — there is one audio output and one set of user sound preferences; two independent mixers would both try to own the same audio graph.

You don't construct these, and you never dispose them — they live for the sim's entire lifetime by definition, the "always constructed, never disposed" case from [Dispose and Memory Management](/patterns/dispose-and-memory-management)'s table applied to a library-level object instead of a sim-authored one.

## Constructing your own instance: scoped ownership

Everything else — a class exported *without* a matching pre-built singleton — is meant to be constructed per use, with the instance's lifetime and identity owned by whatever created it. `Random` itself is the clearest illustration of the contrast: `scenerystack/dot` exports both the class and the singleton, and choosing between them is exactly this decision. Reach for `new Random( { seed } )` instead of `dotRandom` only when you deliberately want an *isolated*, independently-seeded sequence — a self-contained test that must be reproducible regardless of what else in the sim also consumes randomness, for instance — precisely the case where sharing the sim-wide singleton would be wrong instead of merely unnecessary.

The same question — "is there conceptually one of these for the whole sim, or does each owner need its own independent instance?" — is what should decide the shape of a class you design yourself, not just which SceneryStack classes to reach for. A per-screen cache, a per-model helper object, or a per-Node piece of state should be constructed and owned by its containing class, the ordinary way; exporting it as a module-level singleton only makes sense if a second instance would genuinely be a bug, not just unnecessary object allocation.

## Namespace registration: a separate concern from singleton-vs-instance

A related but distinct convention in SceneryStack/PhET code is registering an exported class (not an instance) with that library's `Namespace` object — e.g. a library's top-level module calling `myLibrary.register( 'MyClass', MyClass )` once, at the bottom of the file that defines `MyClass`. This is orthogonal to the singleton-vs-constructed-instance question above: a `Namespace`-registered class is still ordinarily constructed per use (`new MyClass()` wherever it's needed) exactly like any other class — registration exists so tooling and debugging utilities can look a class up by name/namespace path at runtime, not to make the class itself shared or singleton-like. Don't conflate "this class is registered on its library's namespace" with "this class is a singleton" — the two conventions solve different problems and most registered classes are constructed freely, many times, throughout a sim's lifetime.

::: warning Namespace registration is a real PhET convention, not independently verified against Almanach's other pages
The general shape described above (`libraryNamespace.register( 'ClassName', ClassName )`, called once per class definition) reflects the real, long-standing PhET-repo convention, but no other page in Almanach currently documents `Namespace` itself in depth — treat the specifics here as a reasonable description pending a dedicated `api/phet-core/namespace` page, not a fully cross-checked reference.
:::

## Deciding which shape a *new* class of your own should take

| Question | If yes | If no |
| --- | --- | --- |
| Would a second instance conflict with (rather than merely duplicate) the first? | Ready-made singleton, exported once from a module | Constructed per owner |
| Does "the sim" as a whole (rather than one screen, one model, one Node) own this concept? | Likely a singleton | Likely constructed and scoped by whatever needs it |
| Does anything about it need per-owner configuration (a seed, a tandem, a specific range)? | Still may be a singleton if configuration is genuinely global | Constructed, so each owner can supply its own configuration |

A namespaced, individually-constructed class (a `Random`, a model class, a view `Node` subclass) is the default; treat exporting a shared singleton instance as the deliberate exception you reach for only when a second instance would be semantically wrong, not merely one more object in memory.

::: tip A shared singleton is still just a regular exported value
There's no special "singleton" keyword or base class involved — `dotRandom` is simply `export const dotRandom = new Random();` in the library's own module, and importing it twice from two different files gives you the same object both times because ES module instances are already singletons per module graph. The pattern is a naming/API-design convention (construct once, export the instance, document "use this instead of constructing your own") rather than a language feature to learn.
:::


========================================================================
Page: State Persistence and Save/Restore Patterns
URL: https://veillette.github.io/Almanach/patterns/state-persistence-and-save-restore-patterns
Source: docs/patterns/state-persistence-and-save-restore-patterns.md
Category: Patterns | Tags: tandem, phet-io, Property, state, persistence | Status: verified
========================================================================

# State Persistence and Save/Restore Patterns

::: tip Scope: save/load and PhET-iO state, not the Reset All button
This page is about **enumerating model state** so it can be serialized and restored (by PhET-iO or a custom feature). For wiring the in-sim Reset All button back to each Property's `initialValue`, see [The Reset-All Pattern](/patterns/reset-all-pattern).
:::

Any "save state now, restore it later" feature: **the model's entire mutable state is enumerable as a set of `Property` values**, with nothing important living in a local variable, a closure, or a field that isn't a `Property`. [Model-View Separation](/patterns/model-view-separation) already asks for this as an architecture rule; this page is about the save/restore consequence of following (or not following) it.

## Why Property-based state is what makes this mechanical

```ts
class ProjectileModel {
  public readonly angleProperty = new NumberProperty( 45 );
  public readonly speedProperty = new NumberProperty( 10 );
  public readonly isRunningProperty = new BooleanProperty( false );

  // Anything NOT expressed as a Property here (a plain field, a variable in step())
  // is state a generic save/restore mechanism cannot see and cannot capture.
}
```

Because every piece of state above is a `Property`, "capture the current state" and "restore a captured state" are both generic operations that don't need to know anything about `ProjectileModel` specifically:

```ts
// Capture: walk every state Property and record its value.
function captureState( model: ProjectileModel ) {
  return {
    angle: model.angleProperty.value,
    speed: model.speedProperty.value,
    isRunning: model.isRunningProperty.value
  };
}

// Restore: write each value back. Every observer (view, DerivedProperty, PhET-iO)
// updates itself automatically because it was already observing the Property, not
// a snapshot of it.
function restoreState( model: ProjectileModel, state: ReturnType<typeof captureState> ): void {
  model.angleProperty.value = state.angle;
  model.speedProperty.value = state.speed;
  model.isRunningProperty.value = state.isRunning;
}
```

If a simulation-specific save/restore feature is needed, this is roughly what it looks like hand-rolled — but in a PhET-iO-instrumented sim (see [PhET-iO Instrumentation Pattern](/patterns/phet-io-instrumentation-pattern)), the equivalent capture/restore already exists for every instrumented `Property`, driven by each one's `phetioType`/`phetioValueType`, with no simulation-specific code to write at all.

## What must NOT be state

| Belongs in a Property (save/restore sees it) | Does not belong in a Property (deliberately invisible to save/restore) |
| --- | --- |
| Anything the user set or that represents the model's condition (`angleProperty`, `isRunningProperty`) | Purely derived values recomputed from other state — see below |
| A `DerivedProperty`, marked `phetioReadOnly` if instrumented | View-only transient state (an in-progress drag offset, a tooltip's hover flag) |

A `DerivedProperty` is a special case: it *is* state a client can read, but it must never be independently restored — restoring its inputs is sufficient, and PhET-iO's state engine already knows not to treat a `phetioReadOnly` Property as settable. Trying to hand-restore a derived value directly just means it will immediately be overwritten (or worse, drift out of sync) the next time its dependencies change.

```ts
// Don't restore this directly - restoring angleProperty is enough; heightAtLaunchProperty
// recomputes itself from the DerivedProperty wiring set up in the constructor.
public readonly heightAtLaunchProperty = new DerivedProperty(
  [ this.angleProperty ],
  angle => Math.sin( angle )
);
```

## Reset is the smallest save/restore case

`reset()` (see [The Reset-All Pattern](/patterns/reset-all-pattern)) is the degenerate case of this same idea: "restore" a fixed, known state (each Property's `initialValue`) rather than an arbitrary captured one. A model that can correctly implement `reset()` by calling `.reset()` on every one of its Properties has, by construction, already satisfied the harder requirement of being fully save/restorable — which is a useful test to apply while designing a model, even in a sim that has no PhET-iO or save-feature plans yet.

::: tip Design for save/restore even if you never build a save feature
Keeping every piece of mutable state in a `Property` costs nothing extra to write and pays off in three unrelated ways at once: `reset()` becomes mechanical, PhET-iO state save/restore works with zero bespoke code if the sim is ever instrumented, and a future undo/redo feature has something to hang its capture step on. The alternative — state hidden in closures or plain fields — has to be refactored out retroactively the moment any of those three needs shows up.
:::


========================================================================
Page: Testing Model Logic Headlessly
URL: https://veillette.github.io/Almanach/patterns/testing-model-logic-headlessly
Source: docs/patterns/testing-model-logic-headlessly.md
Category: Patterns | Tags: testing, axon, Property, model, node.js | Status: verified
========================================================================

# Testing Model Logic Headlessly

Because [Model-View Separation](/patterns/model-view-separation) keeps every model class free of `scenery`/`sun` imports, a model can be constructed, stepped, and asserted against in plain Node.js — no `Display`, no DOM, no browser. Writing tests against the model directly (rather than driving the whole `Sim` or querying rendered Nodes) is what makes a test suite fast enough to run on every commit and precise enough to pinpoint a physics bug instead of a rendering symptom.

## What a headless model test looks like

```ts
// ProjectileModelTests.ts
import ProjectileModel from './ProjectileModel.js';

QUnit.module( 'ProjectileModel' );

QUnit.test( 'step advances position based on velocity', assert => {
  const model = new ProjectileModel();

  model.angleProperty.value = 0;   // launch horizontally
  model.speedProperty.value = 10;  // m/s
  model.launch();

  const initialX = model.positionProperty.value.x;
  model.step( 1 ); // 1 second

  assert.ok( model.positionProperty.value.x > initialX, 'projectile should move forward after stepping' );
} );

QUnit.test( 'reset restores every Property to its initial value', assert => {
  const model = new ProjectileModel();

  model.angleProperty.value = 45;
  model.speedProperty.value = 15;
  model.step( 2 );

  model.reset();

  assert.equal( model.angleProperty.value, model.angleProperty.initialValue );
  assert.equal( model.speedProperty.value, model.speedProperty.initialValue );
} );
```

Nothing here touches `scenerystack/scenery`. `ProjectileModel` is constructed the same way a real screen would construct it, `step` is called directly with an explicit `dt` instead of waiting on `requestAnimationFrame`, and assertions read `Property.value` — the same public surface the view observes.

::: tip Any test runner works — `QUnit` isn't part of the `scenerystack` package
`QUnit` is shown above because it's the convention in PhET's own repos, not because `scenerystack` bundles or requires it — it's not one of `scenerystack`'s own dependencies. A model built this way is equally testable from Jest, Vitest, `node:test`, or anything else that can call a constructor and read a `.value` — the headless-testability property comes from the model having no `scenery`/DOM imports, not from which test runner you point at it.
:::

## Why not test through the rendered view

| Testing the model directly | Testing by querying rendered Nodes/DOM |
| --- | --- |
| Runs in Node.js — no browser, no `Display`, fast enough for every commit | Needs a browser or headless-DOM environment; slower, flakier |
| A failure points at the model logic itself | A failure could be the model, the view's rendering of it, or layout — hard to tell which |
| Independent of any particular pixel/Node structure, so refactoring the view never breaks these tests | Brittle to view refactors that don't change behavior (renaming a Node, restructuring a panel) |

This isn't an argument against ever exercising the view — some things (does this Node actually appear, is this button reachable by keyboard) can only be verified with a `Display`. It's an argument for putting the *bulk* of behavioral coverage on the model, where it's cheap, and reserving view-level checks for things that are genuinely about rendering or interaction.

## Structuring a model to stay testable

- Give the model a `step( dt: number )` method that a test calls directly with a fixed `dt`, rather than relying on the sim's real animation frame timing.
- Expose enough state as `public readonly` Properties (per [Model-View Separation](/patterns/model-view-separation)) that a test can both drive the model (`model.speedProperty.value = 10`) and assert on the outcome without reaching into private fields.
- Keep randomness injectable (a seeded `Random` instance passed in, not `Math.random()` called inline) so tests can be deterministic.
- If a model class takes a `Tandem` (see [PhET-iO Instrumentation Pattern](/patterns/phet-io-instrumentation-pattern)), pass `Tandem.OPT_OUT` in tests that don't care about instrumentation, so the test isn't coupled to a particular tandem tree.

::: tip A model constructor with no scenery import is a testability signal, not just a layering rule
If writing a test for a model class turns out to require importing `scenerystack/scenery` or constructing a `Display`, that's usually a sign the class has taken on view responsibility it shouldn't have — see [Model-View Separation](/patterns/model-view-separation) — rather than a sign the test needs more setup.
:::


========================================================================
Page: The Enumeration Pattern
URL: https://veillette.github.io/Almanach/patterns/enumeration-pattern
Source: docs/patterns/enumeration-pattern.md
Category: Patterns | Tags: axon, EnumerationProperty, enumeration | Status: verified
========================================================================

# The Enumeration Pattern

When a piece of model state can only be one of a fixed, known set of values (a mode, a phase, a display style), model it as an `EnumerationValue` subclass plus `Enumeration`, not a string-literal union or a plain number. The pattern gives you real object identity for `===` comparisons and `switch`, automatic PhET-iO serialization, and a `Property` (`EnumerationProperty`) that validates writes against exactly that set of values at runtime — a raw `string` union only checks at compile time.

## The core idea

```ts
import { EnumerationValue, Enumeration } from 'scenerystack/phet-core';
import { EnumerationProperty } from 'scenerystack/axon';

// 1. One class instance per value. All static, declared before `enumeration`.
class Intensity extends EnumerationValue {
  public static readonly HIGH = new Intensity();
  public static readonly LOW = new Intensity();

  // 2. Must be declared last — collects every static instance defined above it.
  public static readonly enumeration = new Enumeration( Intensity );
}

// 3. A Property restricted to Intensity's values, validated at runtime.
const intensityProperty = new EnumerationProperty( Intensity.LOW );

intensityProperty.link( intensity => {
  console.log( 'intensity is now', intensity.toString() ); // 'HIGH' or 'LOW'
} );

intensityProperty.value = Intensity.HIGH; // fine
// intensityProperty.value = 'HIGH';      // compile-time AND runtime error - not an Intensity instance
```

Branch on values with `===` or `switch`, exactly like you would with a real enum:

```ts
function describe( intensity: Intensity ): string {
  switch( intensity ) {
    case Intensity.HIGH: return 'strong';
    case Intensity.LOW: return 'gentle';
    default: throw new Error( `unhandled Intensity: ${ intensity }` );
  }
}
```

## Why not a string union?

| | `'high' \| 'low'` string union | `EnumerationValue` + `Enumeration` |
| --- | --- | --- |
| Compile-time safety | Yes | Yes |
| Runtime validation (e.g. bad PhET-iO state, a typo from external code) | None | `EnumerationProperty` throws if the value isn't a member |
| Iterating all values | Requires a separately-maintained array | `Intensity.enumeration.values` (in declaration order) |
| PhET-iO serialization | Needs a hand-written `StringUnionIO` | Automatic `EnumerationIO` |

::: tip Declare `enumeration` last, and never construct new instances elsewhere
`Enumeration`'s constructor walks the class's static properties to find every `Intensity` instance, so `public static readonly enumeration = new Enumeration( Intensity )` must be the last static field in the class. `EnumerationValue`'s constructor also seals the class after construction — attempting `new Intensity()` from outside the class body throws, which is what guarantees `Intensity.HIGH` and `Intensity.LOW` are the only two instances that will ever exist.
:::


========================================================================
Page: The Multilink Pattern
URL: https://veillette.github.io/Almanach/patterns/multilink-pattern
Source: docs/patterns/multilink-pattern.md
Category: Patterns | Tags: axon, Multilink, DerivedProperty | Status: verified
========================================================================

# The Multilink Pattern

When a callback needs to react to *several* Properties at once, don't `link` to each one and re-run the same logic from multiple call sites — use `Multilink.multilink`, which fires once with the current value of every dependency, and again whenever any of them changes. It's the side-effecting sibling of `DerivedProperty`: use `DerivedProperty` when the combination produces a new value to store, use `Multilink` when it produces an effect (a repaint, a sound, a log line) with no value to keep.

## The core idea

```ts
import { Multilink, NumberProperty, BooleanProperty } from 'scenerystack/axon';

const massProperty = new NumberProperty( 5 );
const gravityProperty = new NumberProperty( 9.8 );
const isPausedProperty = new BooleanProperty( false );

// Fires immediately with the current values, then again on every subsequent change.
const multilink = Multilink.multilink(
  [ massProperty, gravityProperty, isPausedProperty ],
  ( mass, gravity, isPaused ) => {
    console.log( `weight = ${ mass * gravity } N, paused = ${ isPaused }` );
  }
);

// Later, if this reaction has a lifetime shorter than its dependencies:
Multilink.unmultilink( multilink );
```

`new Multilink( dependencies, callback, lazy? )` is the equivalent instance form — reach for it only when you need a handle without going through the static helper (for example, to pass `lazy: true` and skip the initial call). Prefer `Multilink.multilink` for the common case, since constructing a `Multilink` you never reference is just an unused variable with no compensating benefit.

## Multilink vs. DerivedProperty

| | `Multilink` | `DerivedProperty` |
| --- | --- | --- |
| Produces | Nothing — runs a callback | A new `TReadOnlyProperty<T>` value |
| Use when | The reaction is an effect (repaint a Node, play a sound) | The combination *is* state other code should read/observe |
| Disposal | `Multilink.unmultilink( multilink )` | `derivedProperty.dispose()` |

```ts
import { DerivedProperty } from 'scenerystack/axon';

// Prefer this over a Multilink when the combined value is itself state:
const weightProperty = new DerivedProperty(
  [ massProperty, gravityProperty ],
  ( mass, gravity ) => mass * gravity
);
```

::: tip Dispose Multilinks that outlive their dependencies
`Multilink.multilink` returns the `Multilink` instance so you can call `Multilink.unmultilink` on it. If the object doing the linking (a Node, a view) is disposed before its dependency Properties are, failing to unmultilink leaks a listener on each dependency — see [Dispose and Memory Management](/patterns/dispose-and-memory-management). If you don't need the handle because both sides share the same lifetime (e.g. a model linking its own Properties in its constructor), it's fine to ignore the return value.
:::


========================================================================
Page: The Options Pattern
URL: https://veillette.github.io/Almanach/patterns/options-pattern
Source: docs/patterns/options-pattern.md
Category: Patterns | Tags: options, typescript, conventions | Status: verified
========================================================================

# The Options Pattern

Every configurable class in SceneryStack takes one trailing `providedOptions` object rather than a long positional-parameter list, and merges it with defaults using `optionize` — a typed layer over `merge` that verifies at compile time that every optional field of your class's own options has a default, while options belonging to the superclass simply pass through untouched. Following this convention (instead of ad hoc destructuring or your own defaulting logic) is what lets a caller override exactly one option three subclasses deep without your class knowing about it.

## The core idea

```ts
import { optionize } from 'scenerystack/phet-core';
import { Path, PathOptions } from 'scenerystack/scenery';
import { Shape } from 'scenerystack/kite';

// 1. Options this class introduces itself.
type SelfOptions = {
  headHeight?: number;
  headWidth?: number;
  doubleHead?: boolean;
};

// 2. The public options type: self options plus everything the superclass accepts.
export type ArrowNodeOptions = SelfOptions & PathOptions;

export default class ArrowNode extends Path {

  public constructor( tailX: number, tailY: number, tipX: number, tipY: number, providedOptions?: ArrowNodeOptions ) {

    // 3. optionize<PublicOptions, SelfOptions, ParentOptions>()( defaults, providedOptions )
    //    - every optional key of SelfOptions MUST get a default here (checked at compile time)
    //    - PathOptions defaults are supplied too, since this class chooses its own (fill/stroke)
    const options = optionize<ArrowNodeOptions, SelfOptions, PathOptions>()( {
      headHeight: 10,
      headWidth: 10,
      doubleHead: false,

      // Path (superclass) options get defaults here too, when this class wants its own
      fill: 'black',
      stroke: 'black'
    }, providedOptions );

    super( new Shape() ); // build the actual arrow shape from tailX/tailY/tipX/tipY + options...

    this.mutate( options ); // hand remaining PathOptions (fill, stroke, ...) up to Path
  }
}
```

A caller only ever supplies what differs from the defaults, at any level of the hierarchy:

```ts
const arrow = new ArrowNode( 0, 0, 100, 0, {
  headHeight: 20,   // ArrowNode's own option
  stroke: 'red'      // inherited from PathOptions, passed straight through
} );
```

## Why not plain destructuring with defaults?

| | Manual `{ headHeight = 10 } = providedOptions ?? {}` | `optionize` |
| --- | --- | --- |
| Superclass options | Must be manually re-declared and forwarded | Flow through `ParentOptions` automatically |
| Missing a default | Silent `undefined` at runtime | Compile-time error — `optionize` requires a default for every optional `SelfOptions` key |
| Deep option overrides (option-of-an-option) | Easy to accidentally clobber a nested object | `combineOptions`/`optionize` merge one level, matching how PhET's option types are designed |

::: tip Name the type `<ClassName>Options`, export it
Every configurable class exports its options type (`ArrowNodeOptions`, `ScreenOptions`, `ResetAllButtonOptions`, ...) so that a *caller* building its own options object — or a subclass narrowing the type — can reference it. Keep `SelfOptions` un-exported (it's an internal implementation detail); export only the combined public type.
:::


========================================================================
Page: The Reset-All Pattern
URL: https://veillette.github.io/Almanach/patterns/reset-all-pattern
Source: docs/patterns/reset-all-pattern.md
Category: Patterns | Tags: reset, ResetAllButton, Property | Status: verified
========================================================================

# The Reset-All Pattern

::: tip Scope: in-sim reset, not external save/load
This pattern covers the **Reset All button** wiring every model `Property` back to its `initialValue`. For structuring state so PhET-iO (or a custom save/load feature) can serialize and restore it, see [State Persistence and Save/Restore Patterns](/patterns/state-persistence-and-save-restore-patterns).
:::

Every SceneryStack screen has exactly one `ResetAllButton`, and its `listener` calls exactly one method: the model's own `reset()`, which in turn resets every `Property` the model owns back to its `initialValue`. Individual view components never reset themselves independently — they simply observe the Properties the model just reset, the same way they observe any other change. Centralizing on `model.reset()` is what guarantees "reset" always means *everything goes back to how the sim started*, not "everything I remembered to wire up."

## The core idea

```ts
import { NumberProperty, Property } from 'scenerystack/axon';
import { Vector2 } from 'scenerystack/dot';

class ProjectileModel {
  public readonly positionProperty = new Property( new Vector2( 0, 0 ) );
  public readonly angleProperty = new NumberProperty( 45 ); // degrees
  public readonly speedProperty = new NumberProperty( 20 ); // m/s

  // One reset() that resets every Property this model owns. Nothing is forgotten
  // because every piece of state lives here, in one place - see Model-View Separation.
  public reset(): void {
    this.positionProperty.reset();
    this.angleProperty.reset();
    this.speedProperty.reset();
  }
}
```

```ts
import { ResetAllButton } from 'scenerystack/scenery-phet';

class ProjectileScreenView /* extends ScreenView */ {
  public constructor( model: ProjectileModel ) {

    const resetAllButton = new ResetAllButton( {
      listener: () => {
        model.reset();
        // view-only state (not Properties, e.g. a transient animation) resets here too, if any exists
      },
      right: /* layoutBounds.maxX */ 0 - 20,
      bottom: /* layoutBounds.maxY */ 0 - 20
    } );

    // this.addChild( resetAllButton );
  }
}
```

## What belongs in `reset()`

| Belongs in `model.reset()` | Does not belong |
| --- | --- |
| Every `Property` the model owns (`positionProperty.reset()`, ...) | View-only, non-`Property` state — rebuild it directly in the button's `listener`, not inside the model |
| Derived state — nothing, `DerivedProperty` recomputes automatically once its dependencies reset | Anything with its own persisted `Property` elsewhere — call that object's own `reset()` from here instead of duplicating logic |

If a screen composes several sub-models, each sub-model gets its own `reset()`, and the top-level model's `reset()` calls each in turn — the `ResetAllButton` still only ever calls the one top-level `reset()`.

::: tip Never reset the view directly
Resist the temptation to have `ResetAllButton`'s listener also manipulate view Nodes directly (hide a tooltip, reset a slider's visual thumb position). If the view is purely observing model Properties as described in [Model-View Separation](/patterns/model-view-separation), resetting the model is sufficient — the view updates itself through the same links it always uses. Reaching into the view from the reset listener is a sign a piece of state is being tracked outside the model.
:::


========================================================================
Page: Animation and Motion Design Conventions
URL: https://veillette.github.io/Almanach/styling/animation-and-motion-design-conventions
Source: docs/styling/animation-and-motion-design-conventions.md
Category: Styling | Tags: twixt, Animation, Easing, motion, transitions, conventions | Status: complete
========================================================================

# Animation and Motion Design Conventions

[Animation and Easing](/api/twixt/animation) covers the `Animation`/`Easing` mechanism itself — how to interpolate a Property over time. This page is the design layer on top of that mechanism: **when** a transition should animate at all, **how long** it should take, **which** `Easing` curve reads correctly for the kind of change happening, and how to avoid motion that distracts more than it clarifies.

## When to animate, and when not to

Animate a change when its *before* and *after* states are both meaningful and the viewer benefits from seeing the path between them — a panel expanding, a value smoothly settling, a highlight fading in. Snap a change instantly when the intermediate states carry no information, or when animating would fight the user's own input:

| Animate | Snap instantly |
| --- | --- |
| A panel opening/closing, a screen transition, a value drifting to a new target on its own | A value being actively dragged by the user (the pointer *is* the animation — adding easing on top makes the object lag behind the cursor) |
| A one-time state change the user should notice (a correct-answer highlight fading in and out) | A `reset()` — see the warning below |
| Smoothing a discrete jump (snapping to the nearest tick mark after a drag ends) | High-frequency updates (a live physics readout) — animating every frame's tiny change adds latency without adding clarity |

::: warning Don't animate `reset()`
[The Reset-All Pattern](/patterns/reset-all-pattern) restores every Property to its `initialValue` instantly. Animating a reset (easing every control back to its starting position over half a second) turns a deliberately abrupt, unambiguous action into something that looks like it might be undoable or still in progress. If a reset needs *any* visual acknowledgment, use a brief flash or fade on the reset button itself, not a tween of the restored values.
:::

## Choosing a duration

Short, UI-scale transitions (a highlight, a panel sliding open, a button's pressed-state feedback) read best in the **150-400ms** range — long enough to be perceived as motion rather than a flicker, short enough that the interface doesn't feel sluggish. Model-driven transitions (an object settling into a new position because the *model* changed, not because the user is actively controlling it) can reasonably run longer, up to a second or two, if the content being animated is large or the change is meant to be narratively noticeable (e.g. "watch this quantity settle to equilibrium"). Err short: a duration that feels slightly too fast on a fast rewatch is far less costly than one that feels sluggish on every single interaction.

```ts
import { Animation, Easing } from 'scenerystack/twixt';

// UI-scale: a panel's opacity fading in - short and snappy.
const panelFadeInAnimation = new Animation( {
  property: panelOpacityProperty,
  to: 1,
  duration: 0.25,
  easing: Easing.QUADRATIC_OUT
} );

// Model-scale: a value settling toward a target the user isn't actively dragging.
const settleAnimation = new Animation( {
  property: needlePositionProperty,
  to: targetPosition,
  duration: 0.8,
  easing: Easing.CUBIC_IN_OUT
} );
```

## Picking an `Easing` curve

`Easing`'s three families (`_IN`, `_OUT`, `_IN_OUT`) each read differently, and the wrong one for the situation is one of the most common ways a technically-correct animation still feels slightly wrong:

| Curve | Reads as | Use for |
| --- | --- | --- |
| `_OUT` (fast start, gentle finish) | The object was already moving and is arriving/settling | Something appearing, expanding, or coming to rest — a panel opening, a highlight fading in |
| `_IN` (gentle start, fast finish) | The object is departing/accelerating away | Something disappearing or being dismissed — a panel closing, a highlight fading out |
| `_IN_OUT` | A deliberate, self-contained move with its own beginning and end | A value moving from one settled state to another with the user not actively involved — the "model-scale" case above |
| `Easing.LINEAR` | Mechanical, constant-rate | Rarely what a UI transition should look like; reach for it only when the motion genuinely represents a constant real-world rate (a clock hand, a conveyor belt), not general-purpose UI polish |

`Easing.QUADRATIC_*` is a reasonable default weight for UI-scale motion; `CUBIC_*` or higher reads as more pronounced acceleration/deceleration and suits larger or slower model-scale transitions better than it suits a small, frequent UI transition.

## Avoiding unnecessary motion

Every animation has an ongoing cost: it holds a `stepTimer` listener alive for its duration, and — more importantly for the user — it delays the interface from reaching its final, readable state. Two guidelines keep motion in check as a project grows:

- **Don't animate purely decorative flourish** that isn't tied to a state change the user needs to track. A control panel that pulses gently at rest to "look alive" is the kind of motion that reads as polish once and as visual noise on the hundredth viewing.
- **Chain, don't overlap incidentally.** If two animations on related content need to run in sequence (a highlight fading in, *then* a value updating), use `firstAnimation.then( secondAnimation )` (see [Animation and Easing](/api/twixt/animation)) rather than starting both independently and hoping their durations happen to line up — durations that "happen to line up" drift the moment either one is tuned later.

## Respecting reduced-motion preferences

SceneryStack doesn't ship a dedicated reduced-motion API, but a project that wants to honor the platform-level `prefers-reduced-motion` preference (or offer its own "reduce motion" toggle) can do so with the same building blocks used for any other optional behavior: read `window.matchMedia( '(prefers-reduced-motion: reduce)' ).matches` (or a project-specific preference) once at startup, store it in a `BooleanProperty` following the [feature-flag naming convention](/patterns/feature-flags-and-preferences-pattern), and branch on it wherever an animation would otherwise start — either skipping straight to the `Animation`'s end value, or using a much shorter `duration`, instead of running the full transition.

```ts
import { Animation, Easing } from 'scenerystack/twixt';
import MySimFeatures from './MySimFeatures.js'; // reducedMotionFeatureEnabledProperty, per the feature-flag pattern

function animateToTarget( property: NumberProperty, target: number ): void {
  if ( MySimFeatures.reducedMotionFeatureEnabledProperty.value ) {
    property.value = target; // snap instantly rather than tween
    return;
  }

  new Animation( {
    property: property,
    to: target,
    duration: 0.8,
    easing: Easing.CUBIC_IN_OUT
  } ).start();
}
```

::: tip Motion should clarify a change, not just decorate it
Before adding an `Animation` to a transition, ask what the viewer learns from watching the intermediate frames. If the answer is "nothing — they just see the final state a fraction of a second later," the animation is decoration, not communication, and a shorter duration (or no animation at all) usually serves the interface better.
:::


========================================================================
Page: Color Profiles
URL: https://veillette.github.io/Almanach/styling/color-profiles
Source: docs/styling/color-profiles.md
Category: Styling | Tags: scenery, ProfileColorProperty, colorProfileProperty, projector-mode, colors | Status: verified
========================================================================

# Color Profiles

SceneryStack applications support multiple **color profiles** — named color schemes that can be switched at runtime. The canonical example is *projector mode*: a light-background scheme that stays legible on a washed-out classroom projector, versus the default dark-background scheme designed for screens.

The mechanism is `ProfileColorProperty` (from `scenerystack/scenery`): a `Property<Color>` whose value switches automatically when the global `colorProfileProperty` changes.

## The pattern: one Colors file per project

All colors live in a single namespace-style file, never inline in view code:

```ts
// MySimColors.ts
import { ProfileColorProperty } from 'scenerystack/scenery';
import mySim from './mySim.js';

const MySimColors = {

  screenBackgroundColorProperty: new ProfileColorProperty( mySim, 'screenBackground', {
    default: 'black',
    projector: 'white'
  } ),

  bodyFillProperty: new ProfileColorProperty( mySim, 'bodyFill', {
    default: 'rgb( 255, 200, 60 )',
    projector: 'rgb( 200, 130, 0 )'
  } ),

  gridLineColorProperty: new ProfileColorProperty( mySim, 'gridLine', {
    default: 'rgba( 255, 255, 255, 0.4 )',
    projector: 'rgba( 0, 0, 0, 0.4 )'
  } )
};

export default MySimColors;
```

Every entry must define `default`; other profiles (like `projector`) fall back to `default` when they don't override.

## Using the colors

Scenery fills and strokes accept a `Property<Color>` directly, so views stay declarative and update automatically on profile switches:

```ts
import { Circle } from 'scenerystack/scenery';
import MySimColors from './MySimColors.js';

const bodyNode = new Circle( 25, {
  fill: MySimColors.bodyFillProperty,          // live — no .value, no link needed
  stroke: MySimColors.gridLineColorProperty
} );
```

Screens take the background the same way:

```ts
new Screen( createModel, createView, {
  backgroundColorProperty: MySimColors.screenBackgroundColorProperty
} );
```

## Switching profiles

The active profile is the global `colorProfileProperty` (a `Property<string>` in `scenerystack/scenery`). In PhET simulations it is toggled from Preferences or the `colorProfile` query parameter; you can also set it programmatically:

```ts
import { colorProfileProperty } from 'scenerystack/scenery';

colorProfileProperty.value = 'projector';
```

::: tip Why not plain constants?
A `static readonly COLOR = 'black'` can never change at runtime and scatters color decisions across files. `ProfileColorProperty` gives you a single audit point for every color in the project, live profile switching for free, and (in PhET-iO contexts) external color customization — for the cost of one extra file.
:::


========================================================================
Page: High-Contrast / Projector-Mode Deep Dive
URL: https://veillette.github.io/Almanach/styling/high-contrast-projector-mode
Source: docs/styling/high-contrast-projector-mode.md
Category: Styling | Tags: scenery, ProfileColorProperty, projector-mode, contrast, colors | Status: verified
========================================================================

# High-Contrast / Projector-Mode Deep Dive

[Color Profiles](/styling/color-profiles) covers the mechanism — `ProfileColorProperty` and the `colorProfileProperty` switch. This page is about the design problem that mechanism exists to solve: a classroom projector is not just "a monitor with worse colors," it specifically crushes contrast, washes out saturated darks, and is usually viewed in a partially-lit room. A `projector` profile that's simply "the default profile but lighter" tends to still fail in an actual classroom. `visualOptions.supportsProjectorMode` on `PreferencesModel` (see [Preferences and Feature Flags](/guides/preferences-and-feature-flags)) is what surfaces the toggle to users — this page is about designing the palette that toggle switches into.

## What actually breaks on a projector

- **Dark backgrounds lose shadow detail.** The default profile's near-black background and dark, muted fills often render as a single flat gray blob under projector light falloff — projector mode should default to a light or white background, not a slightly-lightened dark one.
- **Low-saturation colors collapse into each other.** Two default-profile fills that are clearly distinct on a monitor (a muted teal and a muted gray-blue) can become visually identical when contrast is compressed. Projector-mode fills should be *more* saturated and higher-contrast against the background than a naive "just invert lightness" swap would produce, not merely relocated to the light end of the same palette.
- **Thin strokes and light gridlines disappear.** A `rgba(255,255,255,0.4)` gridline that reads fine on a dark background becomes nearly invisible as `rgba(0,0,0,0.4)` on white under projector glare — err toward higher alpha or a heavier stroke width specifically for the projector value, not just a hue-inverted color at the same alpha.

## Designing the pair, not just the default

Treat `default` and `projector` as two palettes designed together for the same semantic roles, not one palette with the other auto-derived:

```ts
// MySimColors.ts
import { ProfileColorProperty } from 'scenerystack/scenery';
import mySim from './mySim.js';

const MySimColors = {

  screenBackgroundColorProperty: new ProfileColorProperty( mySim, 'screenBackground', {
    default: 'black',
    projector: 'white'
  } ),

  // Not a simple lightness-inversion of the default value - chosen independently so it
  // stays clearly distinct from bodyBFillProperty and legible against a white background.
  bodyAFillProperty: new ProfileColorProperty( mySim, 'bodyAFill', {
    default: 'rgb( 255, 200, 60 )',
    projector: 'rgb( 180, 90, 0 )'
  } ),

  bodyBFillProperty: new ProfileColorProperty( mySim, 'bodyBFill', {
    default: 'rgb( 100, 180, 255 )',
    projector: 'rgb( 0, 70, 160 )'
  } ),

  // Gridlines need more opacity in projector mode to stay visible against glare,
  // not just an inverted hue at the same alpha.
  gridLineColorProperty: new ProfileColorProperty( mySim, 'gridLine', {
    default: 'rgba( 255, 255, 255, 0.4 )',
    projector: 'rgba( 0, 0, 0, 0.6 )'
  } )
};

export default MySimColors;
```

## A practical review checklist

- View every screen in `projector` mode side by side with `default`, not just spot-check one panel — set `colorProfileProperty.value = 'projector'` during development (see [Color Profiles](/styling/color-profiles)) rather than only exercising it through the Preferences UI.
- Check every pair of colors that must stay *distinguishable from each other* (two body colors, a selected-vs-unselected state), not just each color's contrast against the background individually — two colors can each individually pass a contrast check against white and still be indistinguishable from each other.
- Re-check thin strokes, gridlines, and low-opacity fills specifically — they're the elements most likely to have been carried over from the default profile with only a hue flip and no alpha/weight adjustment.
- If possible, view the actual projector-mode screen on a real projector (or a monitor with brightness/contrast pushed to a washed-out extreme) rather than trusting an accurate desktop monitor's rendering — the whole point of the mode is to compensate for a display class the palette author usually isn't looking at directly.

::: warning Projector mode is not "invert the default profile"
Every `ProfileColorProperty` entry needs its `projector` value chosen for its own legibility goal — high contrast against a light background, distinguishability from sibling colors, and visibility of thin/low-alpha elements — rather than mechanically computed from the `default` value. A palette where every projector color is `default`'s color run through a lightness inversion is the most common way this feature ships broken: it passes a quick glance in a bright office and fails in an actual classroom.
:::


========================================================================
Page: Icon Sizing and Button Padding Standards
URL: https://veillette.github.io/Almanach/styling/icon-sizing-and-button-padding-standards
Source: docs/styling/icon-sizing-and-button-padding-standards.md
Category: Styling | Tags: sun, styling, icons, touchArea, conventions, spacing | Status: complete
========================================================================

# Icon Sizing and Button Padding Standards

[Iconography Conventions](/styling/iconography-conventions) covers *building* an icon — reaching for a stock `scenery-phet` icon, drawing a custom one from a `kite` `Shape`, routing its color through the project's palette. This page is the next layer once icons exist: **standardizing their size and the padding around them** so every button in a sim reads as part of one consistent set, rather than each button's designer independently picking "something that looked about right."

## Pick a small icon-size scale, not a size per button

Just as [Spacing and Sizing Constants](/styling/spacing-and-sizing-constants) centralizes margins, a project should settle on two or three icon sizes — not one fixed size for every icon regardless of context, and not a bespoke size chosen freehand at each call site:

```ts
// MySimConstants.ts
const MySimConstants = {
  // Icon sizes: a small scale, not one-off numbers per button.
  SMALL_ICON_SIZE: 16,   // dense toolbars, inline icons next to text
  STANDARD_ICON_SIZE: 24, // the default for most push/toggle buttons
  LARGE_ICON_SIZE: 32     // a screen's one or two most prominent actions
};
```

```ts
import { GridIcon } from 'scenerystack/scenery-phet';
import MySimConstants from '../MySimConstants.js';

const gridToggleIcon = new GridIcon( {
  size: MySimConstants.STANDARD_ICON_SIZE
} );
```

A button's icon size should come from this scale based on the button's *role* (a dense toolbar of secondary actions vs. a screen's one primary action), not from what happens to look balanced in isolation — two buttons of the same visual weight and importance should use the same named size, even if they live on different screens.

## Standardize xMargin/yMargin per button "weight," not per button

`RectangularPushButton` (and every other `sun` button) exposes `xMargin`/`yMargin` — the padding between `content` and the button's edge (see [`RectangularPushButton`](/api/sun/rectangular-push-button)). Pair each icon size in the scale with a matching margin pair so the *ratio* of icon to button stays consistent, and reuse the pair via a shared options object:

```ts
// MySimConstants.ts
const MySimConstants = {
  STANDARD_ICON_SIZE: 24,

  STANDARD_BUTTON_OPTIONS: {
    xMargin: 8,
    yMargin: 8,
    cornerRadius: 6
  }
};

// Usage
import { RectangularPushButton } from 'scenerystack/sun';
import { GridIcon } from 'scenerystack/scenery-phet';
import MySimConstants from '../MySimConstants.js';

const gridToggleButton = new RectangularPushButton( {
  content: new GridIcon( { size: MySimConstants.STANDARD_ICON_SIZE } ),
  listener: () => model.toggleGrid(),
  ...MySimConstants.STANDARD_BUTTON_OPTIONS
} );
```

A button with a tiny icon and a huge margin (or a large icon crammed against the edge with almost no margin) both read as visually off in a way that's easy to miss reviewing one button at a time — comparing every button on a screen side by side is the practical way to catch a margin that drifted from the rest.

## Touch-target padding is a separate concern from visual padding

`xMargin`/`yMargin` control how much space content has *inside* the button's visible bounds — they affect appearance. `touchAreaXDilation`/`touchAreaYDilation` (also on `RectangularPushButton` and most other `sun` components) instead expand the *invisible* hit-testing region beyond the button's visible edge, so a visually compact button is still comfortably tappable on a touchscreen without looking oversized. These two are independent and both matter:

```ts
const compactIconButton = new RectangularPushButton( {
  content: new GridIcon( { size: MySimConstants.SMALL_ICON_SIZE } ),
  xMargin: 4,                  // visually tight - this button should look small
  yMargin: 4,
  touchAreaXDilation: 10,       // but still easy to tap - invisible, doesn't affect appearance
  touchAreaYDilation: 10,
  listener: () => model.toggleGrid()
} );
```

A common mistake is trying to solve the touch-target problem by inflating `xMargin`/`yMargin` instead — that makes the button visually larger too, which is often not the intended look for a dense toolbar. Reach for `touchAreaXDilation`/`touchAreaYDilation` (and the matching `mouseArea` dilation options, less critical but sometimes useful for small precision targets on desktop too) to solve touch-target size without changing how the button looks.

## A minimum touch target, applied consistently

A commonly cited baseline for a comfortably tappable control is roughly 44×44 CSS pixels (drawn from mobile platform accessibility guidance, not a SceneryStack-specific constant); treat it as a floor, not a target to hit exactly. Compute each button family's total dilated hit area against that floor once, store the dilation as a named constant, and apply it everywhere that button family appears, rather than tuning dilation per instance until each one "feels about right":

```ts
// MySimConstants.ts — a 24x24 visual button + xMargin/yMargin of 8 already reaches 40x40;
// a small additional dilation pushes every standard button comfortably past the ~44px floor.
const MySimConstants = {
  STANDARD_TOUCH_DILATION: 4
};
```

::: tip Audit sizes/margins across a whole screen at once, not button by button
Any single icon size or button margin looks "fine" reviewed in isolation — inconsistency across a set of buttons only becomes obvious when they're compared side by side. Periodically pull up every button on a screen at once (or in a shared component gallery, if the project has one) and check that same-role buttons genuinely share the same icon size and margin pair, rather than three subtly different numbers that each individually looked reasonable when they were written.
:::


========================================================================
Page: Iconography Conventions
URL: https://veillette.github.io/Almanach/styling/iconography-conventions
Source: docs/styling/iconography-conventions.md
Category: Styling | Tags: icons, styling, sun | Status: verified
========================================================================

# Iconography Conventions

Buttons, toggle buttons, and menu items in `sun` all take an arbitrary `Node` as their `content` — an icon is just a `Node` sized and styled to read clearly at button scale. This page covers the conventions for building that Node consistently, not the buttons themselves (see [`RectangularPushButton`](/api/sun/rectangular-push-button)).

## Reach for a stock icon before building your own

`scenery-phet` ships a set of ready-made icon `Node`s (all thin `Path` wrappers) for common actions — reuse these instead of redrawing the same shape:

```ts
import { PlusNode, MinusNode, BackspaceIcon, ReturnIcon, GridIcon } from 'scenerystack/scenery-phet';
import { RectangularPushButton } from 'scenerystack/sun';

const incrementButton = new RectangularPushButton( {
  content: new PlusNode(),
  listener: () => model.increment()
} );

const decrementButton = new RectangularPushButton( {
  content: new MinusNode(),
  listener: () => model.decrement()
} );
```

For a vector/callout arrow, use [`ArrowNode`](/api/scenery-phet/arrow-node) rather than a hand-built `Shape`.

## Sizing icons relative to their button, not in isolation

An icon's `size` (most stock icons take a `size` option, `PlusNode`/`MinusNode` take a `Dimension2`, `GridIcon` takes a number) should be chosen relative to the button it sits inside, not as an absolute constant reused everywhere — a 16px icon looks tiny in a large button and cramped in a small one. Set icon size as a fraction of the button's content area:

```ts
import { GridIcon } from 'scenerystack/scenery-phet';

const gridToggleIcon = new GridIcon( {
  size: 24,          // sized for this specific button's content area
  numberOfRows: 4
} );
```

## Custom icons: build from Shape, keep them monochrome

When no stock icon fits, build a small `Path` from a `kite` `Shape` rather than an `Image`/PNG — vector icons stay crisp at any zoom and can be recolored to match the color profile:

```ts
import { Shape } from 'scenerystack/kite';
import { Path } from 'scenerystack/scenery';

const triangleIconShape = new Shape()
  .moveTo( 0, 0 )
  .lineTo( 14, 7 )
  .lineTo( 0, 14 )
  .close();

const playTriangleIcon = new Path( triangleIconShape, {
  fill: 'black'
} );
```

Keep custom icons single-color (`fill` only, no gradients or strokes) unless the whole icon set uses the same embellishment — a mix of flat and outlined icons across a toolbar reads as inconsistent.

## Route icon colors through the project's color profile

Just as with [panels](/styling/panels-and-backgrounds), an icon's `fill`/`stroke` should come from the shared colors file rather than a literal, so disabled/enabled and projector-mode variants stay consistent:

```ts
import MySimColors from './MySimColors.js';

const playTriangleIcon = new Path( triangleIconShape, {
  fill: MySimColors.iconFillProperty
} );
```

## Icons inside toggle buttons: one Node per state

A toggle button (play/pause, sound on/off) needs a distinct icon per state — build both up front and let `BooleanToggleNode`/the toggle button's `trueNode`/`falseNode`-style options swap visibility, rather than mutating one icon's `Shape` on every toggle:

```ts
import { PlayIconShape, PauseIconShape } from 'scenerystack/scenery-phet';
import { Path } from 'scenerystack/scenery';

const playIcon = new Path( new PlayIconShape( 16, 18 ), { fill: 'black' } );
const pauseIcon = new Path( new PauseIconShape( 16, 18 ), { fill: 'black' } );
```

::: tip Match icon stroke weight to the project's line-styling conventions
If custom icons use strokes rather than solid fills, pick the same `lineWidth`/`lineJoin` as the rest of the project's line art — see [Stroke and Line Styling](/styling/stroke-and-line-styling). A toolbar mixing 1px and 3px icon outlines reads as visually noisy even when every icon is individually fine.
:::


========================================================================
Page: Layout Container Conventions
URL: https://veillette.github.io/Almanach/styling/layout-container-conventions
Source: docs/styling/layout-container-conventions.md
Category: Styling | Tags: scenery, layout, styling | Status: verified
========================================================================

# Layout Container Conventions

`VBox`, `HBox`, `FlowBox`, `GridBox`, and `AlignBox` (all from `scenerystack/scenery`) position children without you computing `x`/`y` by hand. This page is about the *conventions* for using them consistently, not their full option lists.

## Prefer VBox/HBox over raw FlowBox

`VBox` and `HBox` are just `FlowBox` pre-configured with `orientation: 'vertical'`/`'horizontal'`. Reach for `FlowBox` directly only when the orientation itself needs to change at runtime; otherwise `VBox`/`HBox` communicate intent at a glance:

```ts
import { VBox, HBox, Text, Checkbox } from 'scenerystack/scenery';

const controlsColumn = new VBox( {
  spacing: 8,
  align: 'left',
  children: [
    new Text( 'Options' ),
    new Checkbox( gravityEnabledProperty, new Text( 'Gravity' ) ),
    new Checkbox( frictionEnabledProperty, new Text( 'Friction' ) )
  ]
} );

const buttonRow = new HBox( {
  spacing: 12,
  children: [ playPauseButton, stepButton ]
} );
```

## One spacing scale per project

Pick a small set of spacing constants (commonly a tight value for closely related items and a looser one for grouped-but-distinct sections) and reuse them instead of scattering magic numbers:

```ts
// MySimConstants.ts
const MySimConstants = {
  CONTROL_SPACING: 8,     // between closely related controls (a checkbox list)
  PANEL_SPACING: 16,      // between distinct sections of a panel
  SCREEN_MARGIN: 15       // between content and the screen edge
};
```

## Alignment: say what you mean

`align` on a `VBox`/`HBox` controls cross-axis alignment (e.g. `align: 'left'` on a `VBox` left-aligns children of different widths). Set it explicitly rather than relying on the `'center'` default whenever children have varying sizes — a checkbox list that's meant to read as a left-aligned list looks unintentionally centered otherwise:

```ts
const checkboxList = new VBox( {
  spacing: 6,
  align: 'left',     // be explicit: this is a left-reading list, not a centered stack
  children: [ checkbox1, checkbox2, checkbox3 ]
} );
```

## Grids for tabular content, AlignBox for matching sizes

Use `GridBox` when content is genuinely tabular (rows and columns of related values), not as a substitute for nested `VBox`/`HBox`:

```ts
import { GridBox, Text } from 'scenerystack/scenery';

const readoutGrid = new GridBox( {
  xSpacing: 10,
  ySpacing: 4,
  rows: [
    [ new Text( 'Mass:' ), massReadout ],
    [ new Text( 'Speed:' ), speedReadout ]
  ]
} );
```

Use `AlignBox` (often paired with an `AlignGroup`) when several sibling Nodes of different natural sizes need to occupy matching bounds — e.g. making a row of buttons with icons of different aspect ratios all reserve the same width:

```ts
import { AlignGroup, AlignBox, HBox } from 'scenerystack/scenery';

const buttonGroup = new AlignGroup();

const row = new HBox( {
  spacing: 10,
  children: [
    new AlignBox( iconButtonA, { group: buttonGroup } ),
    new AlignBox( iconButtonB, { group: buttonGroup } )
  ]
} );
```

Each `AlignBox` sharing a `group` is resized to the union of all group members' bounds, so the buttons line up even though their icons differ in size.

## Margins live on the container, not the children

`FlowBox`/`GridBox` support `xMargin`/`yMargin` (uniform padding around every cell) in addition to `spacing` (the gap *between* cells). Prefer setting margins on the container over wrapping every child in its own spacer `Node`:

```ts
const paddedRow = new HBox( {
  spacing: 8,
  xMargin: 4,   // padding at the start/end of the row, per cell
  children: [ checkboxA, checkboxB ]
} );
```

::: tip Don't fight layout containers with manual positioning
Once a Node is a child of a `FlowBox`/`GridBox`, that container owns its `x`/`y` (via an internal layout constraint) — setting `x`/`y`/`left`/`top` on the child directly will be overwritten on the next layout pass. If a child needs a one-off offset, wrap it in its own `Node` (or use `layoutOptions`) rather than fighting the parent container.
:::


========================================================================
Page: Panels and Backgrounds
URL: https://veillette.github.io/Almanach/styling/panels-and-backgrounds
Source: docs/styling/panels-and-backgrounds.md
Category: Styling | Tags: sun, Panel, styling | Status: verified
========================================================================

# Panels and Backgrounds

[`Panel`](/api/sun/panel) and [`AccordionBox`](/api/sun/accordion-box) are the two standard ways to give a group of controls a visible background. This page is about *when to reach for which*, and how their appearance options should be set consistently across a project — not their full option lists.

## Panel for always-visible groups, AccordionBox for optional ones

Use `Panel` when the controls inside should always be visible — a persistent control panel in a screen's corner. Use `AccordionBox` when the content is secondary or optional and the user should be able to collapse it to reclaim space:

```ts
import { Panel, AccordionBox } from 'scenerystack/sun';
import { VBox, Text } from 'scenerystack/scenery';

// Always visible
const controlPanel = new Panel( controlsVBox, {
  fill: '#f0f0f0',
  stroke: 'black'
} );

// Collapsible, secondary content
const graphAccordionBox = new AccordionBox( graphContent, {
  titleNode: new Text( 'Graph' ),
  expandedDefaultValue: false
} );
```

Both take exactly one content `Node` — build the actual controls with a [layout container](/styling/layout-container-conventions) (`VBox`/`GridBox`) first, then wrap that in the `Panel`/`AccordionBox`.

## One appearance, reused everywhere

A project should settle on one `fill`/`stroke`/`cornerRadius`/`xMargin`/`yMargin` combination for its panels and reuse it via a shared options object, rather than repeating literals (or worse, drifting slightly) at every call site:

```ts
// MySimConstants.ts
const MySimConstants = {
  PANEL_OPTIONS: {
    fill: '#f0f0f0',
    stroke: 'black',
    lineWidth: 1,
    cornerRadius: 8,
    xMargin: 10,
    yMargin: 8
  }
};

// Usage
import { combineOptions } from 'scenerystack/phet-core';

const controlPanel = new Panel( controlsVBox, MySimConstants.PANEL_OPTIONS );

const wideControlPanel = new Panel( otherControlsVBox,
  combineOptions( {}, MySimConstants.PANEL_OPTIONS, { minWidth: 220 } )
);
```

`combineOptions` (from `scenerystack/phet-core`) merges a base options object with per-instance overrides without mutating the shared constant.

## Route panel fills through a colors file

Don't hard-code `fill: '#f0f0f0'` inline — pull it from the project's [color profile](/styling/color-profiles) file so the panel automatically adapts to projector mode:

```ts
import MySimColors from './MySimColors.js';

const controlPanel = new Panel( controlsVBox, {
  fill: MySimColors.panelFillProperty,
  stroke: MySimColors.panelStrokeProperty
} );
```

`Panel`'s `fill`/`stroke` accept a `Property<Color>` directly (like any scenery paint), so the panel updates live when the profile switches.

## Nesting panels sparingly

A `Panel` inside another `Panel` reads as visual clutter — two borders and two background tints stacked for no additional grouping information. If a sub-group truly needs separation, prefer a `HSeparator`/`VSeparator` line or extra `spacing` within a single outer `Panel` over nesting.

::: tip Match cornerRadius across the sitewide component set
`Panel` defaults to `cornerRadius: 10`; sun's buttons and other components have their own default corner radii. If a project's panels use a different radius than its buttons, the mismatch reads as an inconsistency even when nothing else changed — pick one radius (or a small set: e.g. panels slightly more rounded than buttons) and apply it everywhere via shared constants, as above.
:::


========================================================================
Page: Responsive Layout Strategies
URL: https://veillette.github.io/Almanach/styling/responsive-layout-strategies
Source: docs/styling/responsive-layout-strategies.md
Category: Styling | Tags: scenery, ScreenView, layoutBounds, FlowBox, GridBox, responsive | Status: verified
========================================================================

# Responsive Layout Strategies

A SceneryStack `ScreenView` does not resize its content to match the browser window pixel-for-pixel. Instead it works in one fixed coordinate space — `layoutBounds` — that scenery scales and letterboxes to fit whatever window the sim is actually running in. "Responsive" therefore means two separate things layered on top of each other: how the *whole screen* adapts to arbitrary aspect ratios (`layoutBounds` + letterboxing, handled for you), and how *content within that fixed space* rearranges itself when it doesn't fit (`FlowBox`/`GridBox` responsive options, which you configure).

## Layer 1: layoutBounds and letterboxing

Every `ScreenView` declares a `layoutBounds` — by default `ScreenView.DEFAULT_LAYOUT_BOUNDS`, a `1024x618` `Bounds2` — that you design against as if it were the only size the sim would ever run at:

```ts
import { ScreenView, type ScreenViewOptions } from 'scenerystack/sim';

export default class MyScreenView extends ScreenView {
  public constructor( providedOptions: ScreenViewOptions ) {
    super( providedOptions ); // layoutBounds defaults to 1024x618 unless overridden
    // Positioning below is always relative to this.layoutBounds, never the actual
    // browser window size.
  }
}
```

At runtime, scenery computes a uniform scale factor between `layoutBounds` and the actual browser viewport and applies it to the whole `ScreenView` — the content never stretches non-uniformly. Whatever doesn't fit the browser's aspect ratio (a very wide or very tall window relative to `layoutBounds`) is handled by extending the visible area symmetrically along one axis rather than distorting content; `this.visibleBoundsProperty` reports the actual visible region in the `ScreenView`'s local coordinates, which is wider or taller than `layoutBounds` on off-ratio windows.

```ts
// Anchor something to the true edge of the visible area (which may extend past
// layoutBounds on unusually wide/narrow windows), not just layoutBounds' own edge.
this.visibleBoundsProperty.link( visibleBounds => {
  backgroundRectangle.setRectBounds( visibleBounds );
} );
```

Use `layoutBounds` (not `visibleBoundsProperty`) for placing normal UI — control panels, buttons — so their position is stable and predictable; reserve `visibleBoundsProperty` for the rare case of something that should genuinely extend to fill whatever space exists (a full-bleed background).

## Layer 2: responsive content within layoutBounds

Within that fixed space, content still needs to react to its *container's* size — a control panel with a variable number of checkboxes, a row of buttons that needs to fit a narrower sidebar in one sim but not another. This is what `FlowBox`/`GridBox`'s `stretch` and `grow` options are for (see also [Layout Container Conventions](/styling/layout-container-conventions) for the non-responsive conventions):

```ts
import { HBox, Rectangle } from 'scenerystack/scenery';

const toolbar = new HBox( {
  spacing: 8,
  stretch: true,  // children are resized (in the perpendicular direction) to fill the container
  children: [
    new Rectangle( 0, 0, 10, 20, { fill: 'gray' } ),
    new Rectangle( 0, 0, 10, 20, { fill: 'gray' } )
  ]
} );

const spacer = new Rectangle( 0, 0, 1, 1 );
const rowWithFlexibleGap = new HBox( {
  spacing: 8,
  children: [ leftButton, spacer, rightButton ]
} );
spacer.layoutOptions = { grow: 1 }; // spacer expands to absorb all extra space, pushing rightButton to the far edge
```

`grow` distributes any leftover space in the container among cells proportional to their `grow` value (0 by default — a cell with `grow: 0` never expands); `stretch` resizes cells along the *cross* axis to match the container. Both only matter once the container itself has a size driven by something other than its own content — typically because it's inside another layout container, or explicitly sized with `preferredWidth`/`preferredHeight`.

## Putting the two layers together

A typical responsive screen: fixed `layoutBounds` for overall screen composition (so a control panel is always "near the top-right," regardless of window shape), with `FlowBox`/`GridBox` handling any internal region that itself needs to adapt (a panel whose row of icon buttons should redistribute if the panel's own width changes, e.g. because a Preferences option added or removed one).

::: tip Design against layoutBounds, verify against real aspect ratios
Build and position everything assuming `layoutBounds` is the only size that exists, then check the result against `?stringTest=long`-caliber extremes and the actual expected device range (phone portrait through desktop wide) using `visibleBoundsProperty`-driven elements — don't design *directly* against the browser window's live size, or every Node's position calculation has to account for a moving target.
:::


========================================================================
Page: Spacing and Sizing Constants
URL: https://veillette.github.io/Almanach/styling/spacing-and-sizing-constants
Source: docs/styling/spacing-and-sizing-constants.md
Category: Styling | Tags: scenery, constants, spacing, layout, conventions | Status: verified
========================================================================

# Spacing and Sizing Constants

[Layout Container Conventions](/styling/layout-container-conventions) already recommends picking a small spacing scale; this page is the general version of that convention applied to every hardcoded visual number in a project — margins, panel corner radii, icon dimensions, stroke widths — not spacing alone. The rule: a bare numeric literal for a visual dimension belongs in exactly one constants file, referenced everywhere by name, never retyped at each call site.

## The pattern: one constants file

```ts
// MySimConstants.ts
const MySimConstants = {

  // Spacing (see also Layout Container Conventions)
  CONTROL_SPACING: 8,       // between closely related controls
  PANEL_SPACING: 16,        // between distinct sections within a panel
  SCREEN_MARGIN: 15,        // between content and the screen edge

  // Sizing
  PANEL_CORNER_RADIUS: 10,
  CHECKBOX_ICON_SIZE: 24,
  SLIDER_TRACK_SIZE: { width: 150, height: 4 },

  // Stroke
  PANEL_STROKE: 'black',
  PANEL_LINE_WIDTH: 1
};

export default MySimConstants;
```

```ts
// Anywhere in view code, reference the constant by name - never retype "16" or "10".
import MySimConstants from '../MySimConstants.js';
import { Panel } from 'scenerystack/sun';

const controlPanel = new Panel( content, {
  xMargin: MySimConstants.PANEL_SPACING,
  cornerRadius: MySimConstants.PANEL_CORNER_RADIUS,
  stroke: MySimConstants.PANEL_STROKE,
  lineWidth: MySimConstants.PANEL_LINE_WIDTH
} );
```

## The anti-pattern: magic numbers at each call site

```ts
// Don't do this - three panels each retype "roughly 15" with no shared source of
// truth, so nudging the project's margin convention means hunting every call site
// and hoping none were missed.
const panelA = new Panel( contentA, { xMargin: 15, cornerRadius: 8 } );
const panelB = new Panel( contentB, { xMargin: 14, cornerRadius: 10 } ); // already drifted
const panelC = new Panel( contentC, { xMargin: 16, cornerRadius: 8 } );  // already drifted
```

Once a number like this is retyped at more than one call site, the values silently drift apart the first time only one of them gets tweaked during a design pass — there is no longer a single "the project's panel margin" to point to, just several similar-looking numbers that happened to start out equal.

## What belongs in the constants file, and what doesn't

| Centralize it | Leave it local |
| --- | --- |
| Any dimension reused across more than one class, or that represents a project-wide convention ("this project's standard panel margin") | A dimension that is genuinely specific to one Node and unlikely to ever be reused (the exact radius of one decorative flourish) |
| Values a designer/reviewer would think of as "the project's spacing scale" | Values derived by computation from other constants (compute those inline from the constant, don't duplicate the computed result as its own constant) |

A value doesn't need to be reused *today* to earn a place in the constants file — if it's the kind of number a design review would refer to as "the standard spacing," it belongs there so the next screen that needs "the standard spacing" finds it instead of guessing a new number that happens to look similar.

::: tip Group by role, not by screen
Structure the constants file by what each value *is* (spacing, sizing, stroke) rather than by which screen introduced it. A `MySimConstants.SCREEN_MARGIN` used by every screen is more discoverable than a `IntroScreenConstants.MARGIN` that a second screen either duplicates or, worse, imports from the first screen's file out of convenience.
:::


========================================================================
Page: Stroke and Line Styling
URL: https://veillette.github.io/Almanach/styling/stroke-and-line-styling
Source: docs/styling/stroke-and-line-styling.md
Category: Styling | Tags: kite, scenery, stroke, styling | Status: verified
========================================================================

# Stroke and Line Styling

Every scenery `Path` (and its subclasses `Rectangle`, `Circle`, `Line`, …) draws its outline using six line-style options mixed in from `Paintable`: `lineWidth`, `lineCap`, `lineJoin`, `miterLimit`, `lineDash`, and `lineDashOffset`. This page covers conventions for choosing consistent values, not the mechanics of `stroke`/`fill` themselves.

## A small set of stroke widths, not arbitrary numbers

Pick two or three `lineWidth` values for a whole project — thin (grid lines, dividers), standard (shape outlines, panel borders), and occasionally heavy (emphasis/selection) — and reuse them via shared constants, the same way as [typography sizes](/styling/typography-and-fonts):

```ts
// MySimConstants.ts
const MySimConstants = {
  THIN_LINE_WIDTH: 1,
  STANDARD_LINE_WIDTH: 2,
  EMPHASIS_LINE_WIDTH: 4
};

import { Line } from 'scenerystack/scenery';

const gridLine = new Line( 0, 0, 0, 300, {
  stroke: 'gray',
  lineWidth: MySimConstants.THIN_LINE_WIDTH
} );
```

## lineCap and lineJoin: pick one style and hold it

`lineCap` (`'butt'` | `'round'` | `'square'`) controls how a stroke ends; `lineJoin` (`'miter'` | `'round'` | `'bevel'`) controls how two segments meet at a corner. Mixing cap/join styles across a scene reads as sloppy — settle on one pair (commonly `lineCap: 'round'` for hand-drawn-feeling curves and cables, or the defaults `'butt'`/`'miter'` for precise geometric diagrams) and apply it project-wide:

```ts
import { Path } from 'scenerystack/scenery';
import { Shape } from 'scenerystack/kite';

const cablePath = new Path( cableShape, {
  stroke: 'black',
  lineWidth: 6,
  lineCap: 'round',
  lineJoin: 'round'   // avoid sharp miter spikes on a soft/organic shape
} );
```

`miterLimit` (default `10`) only matters when `lineJoin: 'miter'`: past this ratio of miter length to line width, a sharp corner is automatically drawn as a bevel instead, so a very acute angle doesn't spike out unboundedly. Lower it (e.g. `miterLimit: 3`) for shapes with intentionally sharp corners you don't want to over-emphasize.

## Dash patterns: reserve them for one meaning

`lineDash` (an array of on/off segment lengths, e.g. `[ 8, 4 ]` for 8px dashes with 4px gaps) is most legible when a project uses it for exactly one recurring meaning — e.g. "this is a projected/predicted path" or "this is a hidden/reference boundary" — rather than varying dash patterns arbitrarily between shapes:

```ts
const predictedPathNode = new Path( predictedPathShape, {
  stroke: 'blue',
  lineWidth: 2,
  lineDash: [ 8, 4 ]   // reserved sitewide for "predicted / projected" paths
} );

const referenceBoundary = new Path( boundaryShape, {
  stroke: 'gray',
  lineWidth: 1,
  lineDash: [ 2, 2 ]   // reserved sitewide for "non-interactive reference geometry"
} );
```

`lineDashOffset` shifts where the pattern starts; it's mainly useful for animating a "marching ants" effect by incrementing it each frame.

## Strokes on filled shapes: keep width proportional to size

A `lineWidth` that looks right on a 200px panel border can overwhelm a 12px icon. When the same stroke style is reused across very different scales (see [Iconography Conventions](/styling/iconography-conventions)), scale `lineWidth` down for small Nodes rather than keeping one constant everywhere:

```ts
const panelBorder = { stroke: 'black', lineWidth: 2 };   // fine at panel scale
const iconOutline = { stroke: 'black', lineWidth: 1 };   // 2 would look heavy at icon scale
```

::: tip lineWidth: 0 is not the same as stroke: null
Setting `lineWidth: 0` still incurs the (small) cost of stroke computation and `Path` correctly treats it as "no visible stroke," but the clearer and cheaper way to say "this shape has no stroke" is `stroke: null` — reserve `lineWidth` tuning for shapes that are actually stroked.
:::


========================================================================
Page: Typography and Fonts
URL: https://veillette.github.io/Almanach/styling/typography-and-fonts
Source: docs/styling/typography-and-fonts.md
Category: Styling | Tags: scenery-phet, PhetFont, typography | Status: verified
========================================================================

# Typography and Fonts

Every piece of text in a SceneryStack application should be built from [`PhetFont`](/api/scenery-phet/phet-font) rather than scenery's plain `Font`. This page covers the conventions for *which* sizes and weights to reach for, not the mechanics of the class itself (see the linked API page for that).

## The core idea

`PhetFont` guarantees the standard PhET typeface and a `sans-serif` fallback. Pick a size, optionally a weight, and hand the result to a `Text` or `RichText`:

```ts
import { PhetFont } from 'scenerystack/scenery-phet';
import { Text } from 'scenerystack/scenery';

// Convenience shorthand: just a size
const bodyFont = new PhetFont( 16 );

// Full options form when you also need weight/style
const titleFont = new PhetFont( { size: 22, weight: 'bold' } );

const title = new Text( 'Gravity and Orbits', { font: titleFont } );
const label = new Text( 'Mass (kg)', { font: bodyFont } );
```

## A shared type-scale, not ad-hoc sizes

Rather than sprinkling `new PhetFont( 17 )`, `new PhetFont( 18 )`, `new PhetFont( 15 )` across a codebase, define a small, named scale once (alongside a project's [colors file](/styling/panels-and-backgrounds)) and reuse it everywhere:

```ts
// MySimConstants.ts
import { PhetFont } from 'scenerystack/scenery-phet';

const MySimConstants = {
  TITLE_FONT: new PhetFont( { size: 22, weight: 'bold' } ),
  CONTROL_PANEL_TITLE_FONT: new PhetFont( { size: 16, weight: 'bold' } ),
  CONTROL_FONT: new PhetFont( 16 ),
  READOUT_FONT: new PhetFont( 18 )
};

export default MySimConstants;
```

A handful of sizes is normally enough: a screen/title size, a panel-heading size (usually bold at the same or one step down from body text), a body/control size, and occasionally a larger "readout" size for prominent numeric displays. Resist introducing a new size for a single label — reuse the nearest existing one.

## Weight and emphasis

`PhetFont`'s `weight` option (part of scenery's `FontOptions`) takes any valid CSS font-weight, but in practice PhET sims only use two: the default (regular) weight and `'bold'` for headings or emphasis. Avoid `italic` for emphasis — it reads poorly at small sizes on projectors; use `weight: 'bold'` or a color/size change instead.

## Sizing for fit, not just readability

Text inside a fixed-width control (a [`Panel`](/styling/panels-and-backgrounds) title, a button label) needs to fit the available space at every supported browser width. Two common techniques:

```ts
import { RichText } from 'scenerystack/scenery';

// MaxWidth: scenery scales the Node down (preserving aspect ratio) if it would
// otherwise exceed this width, rather than clipping or overflowing.
const readout = new RichText( speedStringProperty, {
  font: MySimConstants.READOUT_FONT,
  maxWidth: 120
} );
```

`maxWidth` (and its vertical counterpart `maxHeight`) are `Node` options available on `Text`/`RichText` — they matter especially for translated strings, which can run much longer than the English source string.

::: tip Don't hand-roll font strings
Never construct a raw CSS font string (`'bold 16px Arial'`) or use scenery's plain `Font` class directly. `PhetFont` is the one audit point for the project's typography, and skipping it means losing the guaranteed `sans-serif` fallback documented on the [`PhetFont` API page](/api/scenery-phet/phet-font).
:::


========================================================================
Page: Visual Debugging Aids
URL: https://veillette.github.io/Almanach/styling/visual-debugging-aids
Source: docs/styling/visual-debugging-aids.md
Category: Styling | Tags: scenery, debugging, query-parameters, showPointerAreas, showHitAreas, dev | Status: complete
========================================================================

# Visual Debugging Aids

Every SceneryStack simulation ships with a set of debug-overlay query parameters, wired into the shared `joist`/`chipper` startup path so no extra setup is needed to use them — just append the parameter to the dev URL (see [Running and Building a Simulation](/getting-started/running-and-building-a-simulation)). [Performance and Profiling](/guides/performance-and-profiling) covers the subset of these aimed at *speed* (`?profiler`, `?showFittedBlockBounds`). This page is about the subset aimed at **spotting layout and hit-area problems during development** — cases where something looks positioned correctly but doesn't respond to input where you'd expect, or vice versa.

## The overlay query parameters

| Query parameter | Shows | Use it to catch |
| --- | --- | --- |
| `?showPointerAreas` | Each Node's `mouseArea`/`touchArea` as an overlay | A touch target that's smaller (or larger) than intended — see [Icon Sizing and Button Padding Standards](/styling/icon-sizing-and-button-padding-standards) for the dilation options these overlays are visualizing |
| `?showHitAreas` | The actual hit-testing region scenery is using for pointer input, which may differ from the drawn shape for a `Path` with a custom `mouseArea`/hit-testing override — see [Hit-Testing and Picking](/api/scenery/hit-testing-and-picking) for the `pickable`/`mouseArea`/`touchArea` mechanics these overlays are visualizing | An interactive region that's misaligned with what's drawn — a draggable whose grabbable area doesn't match its visible bounds |
| `?showCanvasNodeBounds` | Bounds overlays specifically for `CanvasNode` subtrees | A `CanvasNode` whose declared `canvasBounds` doesn't match what it actually paints — content clipped at the overlay's edge is a sign the bounds are too small |
| `?showFittedBlockBounds` | The boundaries of scenery's internal Canvas/SVG/WebGL rendering blocks | Unexpected repaint/relayout scope — see [Performance and Profiling](/guides/performance-and-profiling) |
| `?dev` | A bundle of internal developer-facing overlays and checks | A general first pass when narrowing down where in the tree a problem lives, before reaching for a more specific flag above |

```
http://localhost:5173/?ea&showPointerAreas&showHitAreas
```

Combining `?showPointerAreas` and `?showHitAreas` is the most common pairing: the first shows *where you configured* input to be accepted, the second shows what scenery is *actually* using, and a mismatch between the two overlays is the fastest way to spot a stale or incorrectly-scoped `mouseArea`/`touchArea` override.

## A typical debugging session

A draggable Node that feels "hard to grab" near its edges is a good candidate for this workflow:

1. Load the sim with `?showPointerAreas` and look at the draggable's overlay. If the overlay is noticeably smaller than the Node's visible bounds, its `touchAreaXDilation`/`touchAreaYDilation` (see [Drag Listeners](/patterns/drag-listeners) and [Icon Sizing and Button Padding Standards](/styling/icon-sizing-and-button-padding-standards)) may be unset or too small.
2. Add `showHitAreas` alongside it. If the two overlays disagree, something is overriding the effective hit-testing region beyond the plain `mouseArea`/`touchArea` you'd expect — worth checking for a custom `Shape`-based hit area or a `pickable`/`inputEnabled` override on an ancestor.
3. If the region looks right but the Node still doesn't respond, the problem is more likely in the input-listener wiring itself (see [Drag Listeners](/patterns/drag-listeners)) than in geometry — the overlays only diagnose *where* scenery is willing to accept input, not whether a listener is actually attached and firing.

## Combine with `?ea` while debugging

These overlay parameters are purely visual and don't themselves validate anything — pair them with `?ea` (enabling SceneryStack's runtime assertions, see [Running and Building a Simulation](/getting-started/running-and-building-a-simulation)) so that an invalid option value or API misuse surfaces as an assertion failure rather than a silently wrong overlay.

::: tip These overlays are dev-only by convention, not stripped automatically
Nothing prevents a user from appending `?showPointerAreas` to a production build's URL — these are ordinary query parameters, not something gated behind a build flag. Treat them as a development workflow rather than assuming they're inaccessible outside of local dev; don't rely on their *absence* as a security or content-hiding mechanism.
:::


========================================================================
Page: Accessible Descriptions for Charts and Graphs
URL: https://veillette.github.io/Almanach/accessibility/accessible-descriptions-for-charts-and-graphs
Source: docs/accessibility/accessible-descriptions-for-charts-and-graphs.md
Category: Accessibility | Tags: bamboo, pdom, description, ChartTransform, accessibility, charts | Status: complete
========================================================================

# Accessible Descriptions for Charts and Graphs

A `bamboo` chart (a [`ChartTransform`](/api/bamboo/chart-transform) plus a [`LinePlot`](/api/bamboo/line-plot)/`BarPlot`/`ScatterPlot`) is, to a screen reader, just a collection of `Path`/`Rectangle`/`Circle` Nodes drawing pixels — nothing about the visual line or bars is inherently meaningful without a description. Giving the chart a bare `descriptionContent` of `"A chart"` satisfies an automated PDOM checker but tells a screen-reader user nothing they couldn't already infer. This page is about writing chart description content that instead conveys **the trend and the values that matter**, following the same mechanisms [Describing Dynamic State](/accessibility/describing-dynamic-state) already establishes for any changing model value.

## Describe the trend, not the mechanism

The single most useful sentence a chart's description can contain says what's *happening in the data*, in plain language — rising, falling, oscillating, leveling off — rather than a literal restatement of the axes:

```ts
// Weak: technically accurate, communicates nothing about the data's shape.
descriptionContent: 'A line chart showing temperature versus time.'

// Better: leads with the trend a sighted user would notice at a glance.
descriptionContent: 'Temperature is rising steadily, from 15 to 42 degrees Celsius over the last 10 seconds.'
```

The second version is what a sighted user actually gets "for free" by glancing at the plot's slope — a screen-reader user should get the equivalent information from the description, not a lower-fidelity restatement of the chart's title and axis labels (which, if present, are already conveyed by the chart's own `labelContent`/surrounding text).

## Derive the description from the same data driving the plot

Because a bamboo chart's `dataSet` already lives in ordinary TypeScript (an array, or values read off model `Property`s), a `DerivedProperty` can compute a trend description from exactly the same source the `LinePlot` renders from — the two are guaranteed to agree, and the description updates automatically as the chart does:

```ts
import { DerivedProperty } from 'scenerystack/axon';
import { ChartTransform, LinePlot } from 'scenerystack/bamboo';
import { Node } from 'scenerystack/scenery';
import { StringUtils } from 'scenerystack/phetcommon';
import { Range } from 'scenerystack/dot';

const chartTransform = new ChartTransform( {
  viewWidth: 400,
  viewHeight: 200,
  modelXRange: new Range( 0, 10 ),
  modelYRange: new Range( 0, 50 )
} );

const linePlot = new LinePlot( chartTransform, temperatureModel.dataSetProperty.value );

// Same underlying data the LinePlot renders from - description and visual can't drift apart.
const chartDescriptionProperty = new DerivedProperty(
  [ temperatureModel.dataSetProperty ],
  dataSet => {
    const first = dataSet[ 0 ];
    const last = dataSet[ dataSet.length - 1 ];
    const direction = last.y > first.y ? 'rising' : last.y < first.y ? 'falling' : 'holding steady';
    return StringUtils.fillIn(
      'Temperature is {{direction}}, from {{start}} to {{end}} degrees Celsius.', {
        direction: direction,
        start: first.y.toFixed( 0 ),
        end: last.y.toFixed( 0 )
      }
    );
  }
);

const chartNode = new Node( {
  children: [ /* ChartRectangle, linePlot, axes, ... */ ],
  tagName: 'div',
  labelTagName: 'h3',
  labelContent: 'Temperature Over Time',
  descriptionContent: chartDescriptionProperty
} );
```

Recompute the description on meaningful transitions in the data (a full step of new readings, a completed run) rather than on every single point added to a live-scrolling chart — a description that rewrites itself every animation frame is as unhelpful read aloud as it would be if a sighted user had to re-read a full paragraph every frame (see the "keep dynamic descriptions concise" guidance in [Describing Dynamic State](/accessibility/describing-dynamic-state#choosing-between-the-two)).

## Announce notable events as they happen, separately from the resting description

A resting `descriptionContent` is only read when something visits the chart (initial focus, screen-reader navigation). A notable event *while looking at other content* — the plotted value crossing a threshold, a data-collection run finishing — needs `addAccessibleResponse` instead, exactly as in [Describing Dynamic State](/accessibility/describing-dynamic-state#announcing-changes-as-they-happen-with-addaccessibleresponse):

```ts
temperatureModel.temperatureProperty.link( ( temperature, previousTemperature ) => {
  if ( previousTemperature !== null && temperature >= 100 && previousTemperature < 100 ) {
    chartNode.addAccessibleResponse( 'Boiling point reached.' );
  }
} );
```

## What to include, and what to leave out

| Include | Leave out (or keep secondary) |
| --- | --- |
| The overall trend/shape in plain language ("rising," "leveling off," "oscillating") | The chart type as the leading clause ("a line chart of…") — useful context, but not the headline |
| Start/end or current values, rounded to a sensible precision | Every individual data point — a screen reader user doesn't need (and can't usefully absorb) the full `dataSet` read aloud point by point |
| Units, matching whatever's shown on the visible axis labels | Pixel/view-coordinate detail (`viewWidth`, chart position on screen) — irrelevant to the data itself |
| Notable features a sighted glance would catch — a peak, a crossing of zero, a plateau | Implementation detail about `ChartTransform`/plot type — not meaningful to the reader |

::: tip A chart's description is a summary, not a data dump
Resist the urge to make the description "complete" by enumerating values — a sighted user doesn't read every pixel of a line either; they perceive its shape. Write the description to convey the same *summary-level* understanding a glance provides, and let a data table or export feature (if the sim has one) carry the full precision for users who need it.
:::


========================================================================
Page: Alternative Input Overview
URL: https://veillette.github.io/Almanach/accessibility/alternative-input-overview
Source: docs/accessibility/alternative-input-overview.md
Category: Accessibility | Tags: scenery, alternative-input | Status: verified
========================================================================

# Alternative Input Overview

"Alternative input" is scenery's term for any non-mouse way of interacting with a scene — keyboard, switch devices, and other assistive technology (AT) — as opposed to conventional pointer input (mouse/touch/pen). The key architectural fact is that **all of these route through the same `TInputListener` interface and the same `addInputListener` call**: a Node doesn't need separate code paths for "mouse users" and "keyboard users."

## One listener interface, multiple input sources

Every scenery input listener (`DragListener`, `PressListener`, `FireListener`, `KeyboardListener`, `KeyboardDragListener`) implements `TInputListener` (from `scenerystack/scenery`). Pointer events (`down`, `up`, `move`, …) and keyboard events (`keydown`, `keyup`, …) are both dispatched through the same listener-array mechanism on a Node — a listener just implements the callback names it cares about:

```ts
import { Node, PressListener } from 'scenerystack/scenery';

const button = new Node( { tagName: 'button', focusable: true } );

button.addInputListener( new PressListener( {
  press: () => model.activate()  // fires for pointer press AND (via focusable + Enter/Space) keyboard activation
} ) );
```

Interactive `sun` components (buttons, sliders, checkboxes) already wire this up for you — the same `PressListener`/button model responds whether the user clicked, tapped, or pressed <kbd>Enter</kbd> while focused.

## Pointers, including the PDOM pointer

Pointer input itself is represented by `Pointer` subclasses — `Mouse`, `Touch`, `Pen` — but there is also a `PDOMPointer`, which represents interactions coming from the Parallel DOM (see [The Parallel DOM](/accessibility/pdom)): keyboard activation, and AT-generated synthetic events (a screen reader's virtual cursor, a switch-access scanner) all arrive at scenery as events on the `PDOMPointer`. This is why a `Node` only needs `tagName`/`focusable`/`accessibleName` to become reachable by keyboard and AT — it's being added to the same dispatch system pointer input already uses, not a separate accessibility layer.

## Dragging: the RichDragListener pattern

The clearest example of "one interaction, multiple input modalities" is dragging. `RichDragListener` (from `scenerystack/scenery`) composes a pointer-based `DragListener` and a keyboard-based `KeyboardDragListener` into a single listener implementing `TInputListener`, so one `addInputListener` call supports both:

```ts
import { Node, RichDragListener } from 'scenerystack/scenery';

// A focusable Node that can be dragged with pointer or keyboard.
const draggableNode = new Node( {
  tagName: 'div',
  focusable: true
} );

const richDragListener = new RichDragListener( {
  positionProperty: modelElement.positionProperty,
  transform: modelViewTransform
} );

draggableNode.addInputListener( richDragListener );
```

Options specific to only one modality are namespaced under `dragListenerOptions`/`keyboardDragListenerOptions`; options common to both (like `positionProperty`, `transform`) are given directly.

## What this buys you

- **No parallel code paths.** A single `press`/`fire`/`drag` callback runs regardless of what device triggered it.
- **Accessibility is additive, not a rewrite.** Adding `tagName`/`focusable` to an existing Node with pointer listeners is usually enough to bring keyboard/AT support online, because the listener was already written against the shared interface.
- **Focus becomes the organizing concept for non-pointer input**, which is why [focus highlights](/accessibility/focus-highlights) and `pdomOrder` matter so much — see [The Parallel DOM](/accessibility/pdom) for `pdomOrder`, and [Keyboard Input and Hotkeys](/accessibility/keyboard-input-and-hotkeys) for shortcuts beyond dragging.

::: tip Design for keyboard first, not as an afterthought
Because pointer and keyboard input share one dispatch system, retrofitting keyboard support onto a pointer-only interaction later usually means restructuring the listener anyway. It's less work overall to reach for `RichDragListener`/`KeyboardListener` from the start than to add a pointer-only `DragListener` and bolt on keyboard support afterward.
:::


========================================================================
Page: Cognitive Accessibility Considerations
URL: https://veillette.github.io/Almanach/accessibility/cognitive-accessibility-considerations
Source: docs/accessibility/cognitive-accessibility-considerations.md
Category: Accessibility | Tags: accessibility, cognitive-load, plain-language, conventions | Status: complete
========================================================================

# Cognitive Accessibility Considerations

Most of Almanach's accessibility content — [the PDOM](/accessibility/pdom), [Voicing](/accessibility/voicing), [focus highlights](/accessibility/focus-highlights), [sound design](/accessibility/sound-design) — addresses *sensory and motor* accessibility: can the content be perceived and operated without sight, without a mouse, without hearing. **Cognitive accessibility** is a distinct axis: can the content be *understood and used without unnecessary mental effort*, independent of whether the user can see the screen or operate a mouse just fine. A sim can pass every PDOM/keyboard/contrast check and still be needlessly hard to use for a learner who is overwhelmed by cluttered layout, jargon-heavy labels, or an unexplained countdown.

## Why this doesn't reduce to the other accessibility axes

A screen-reader test confirms that a control has a name and is reachable; it says nothing about whether that name is written in plain language. A keyboard test confirms every control is operable; it says nothing about whether the *number* of controls on screen is more than a first-time user can hold in mind at once. Treat cognitive accessibility as its own review pass — reading a screen's layout and copy specifically for clarity and load — rather than assuming it's covered as a side effect of PDOM/keyboard work.

## Clear language over technically-precise jargon

Prefer the plain-language term a general audience already knows over the internally-precise term a domain expert would reach for, unless the sim is specifically *teaching* the precise term:

| Prefer | Over, unless the precise term is the learning goal |
| --- | --- |
| "Speed" | "Velocity magnitude" |
| "How heavy" / "Weight" | "Gravitational force" (when the sim isn't specifically about force vs. weight) |
| "Turn this on to see arrows" | "Toggle vector field visualization overlay" |

This is the same discipline [Internationalized Accessible Names](/accessibility/internationalized-accessible-names) already asks for on `accessibleName`/`accessibleHelpText` strings — every user-facing string, PDOM or visible, should be reviewed for plain language, not just for whether it's routed through the translation pipeline correctly.

## Consistent layout over novel-per-screen arrangement

A returning user (or a user moving between a sim's several screens) benefits from controls staying in roughly the same place and using the same visual language throughout — a reset button that's bottom-right on one screen and top-left on another forces the user to relearn the layout instead of transferring what they already know. [Layout Container Conventions](/styling/layout-container-conventions) already asks for one spacing scale and consistent alignment for its own visual-polish reasons; the same consistency also directly reduces cognitive load, since a predictable layout is one less thing a user has to think about before they can focus on the content itself.

## Avoid unnecessary complexity

Every control, every simultaneously-moving element, and every additional decision a screen asks of the user has a cognitive cost, separate from whatever screen space and code it costs to build. Before adding a control or a visual embellishment, ask whether it serves the sim's learning goal or is incidental complexity:

- **Progressive disclosure**: show the minimum needed to get started, and reveal advanced options (via an `AccordionBox` — see [Panels and Backgrounds](/styling/panels-and-backgrounds)) only once a user has engaged with the basics, rather than presenting every control at once on first load.
- **One clear primary action per screen.** If several controls compete visually for attention, a user has to work out which one matters right now — reserve the strongest visual weight (size, color, position) for the action the screen is actually about.
- **Avoid simultaneous unrelated motion.** Several independently-animating elements on screen at once (see [Animation and Motion Design Conventions](/styling/animation-and-motion-design-conventions)) force a user to divide attention across all of them; sequence or group related motion instead of letting everything move freely at once.

## Timers and time pressure

A countdown or a time-limited challenge adds cognitive load on top of whatever the sim is actually teaching — the user is now managing "the clock" as a second task alongside the content itself. Where a timer isn't itself the point of the activity (a genuine speed/reaction-time exercise), avoid unnecessary time pressure:

- Prefer **self-paced** interaction wherever a timer isn't essential to the learning goal.
- If a game/reward system (see [vegas](/api/vegas/level-selection-button)) includes a timer, make it optional or clearly signposted, and never silently penalize a user for taking time to think.
- A visible, predictable countdown (if a timer is genuinely needed) is less stressful than an unexplained or invisible one — the user should always be able to tell how much time remains and what happens when it runs out, well before it runs out.

## Prefer showing over describing, where both are possible

Combined with concrete language, a labeled example, an icon paired with text, or a short demonstration reduces the inferential work a user has to do compared with an abstract instruction alone — "drag the ball to launch it," paired with a visual arrow or a brief animated hint, communicates faster than a paragraph of instructions a user must first read and mentally translate into an action.

::: tip Cognitive load is a design review category, not a checkbox
Unlike PDOM/keyboard correctness, there's no automated check for "is this screen too complex" or "is this label plain enough." Build a deliberate review pass for it — walk through each screen asking "what does a first-time user have to hold in mind here, and is any of it avoidable" — rather than assuming it falls out of passing the sim's other accessibility checks.
:::


========================================================================
Page: Describing Dynamic State
URL: https://veillette.github.io/Almanach/accessibility/describing-dynamic-state
Source: docs/accessibility/describing-dynamic-state.md
Category: Accessibility | Tags: pdom, description, accessibility | Status: verified
========================================================================

# Describing Dynamic State

Static `descriptionContent` (see [The Parallel DOM](/accessibility/pdom)) is enough for content that never changes, but most simulation state does change — a ball's speed, a switch's position, a count of selected items. This page covers the two mechanisms for keeping description content in sync with that state: **reactive description strings** (read on demand, e.g. when focus lands) and **`addAccessibleResponse`** (announced proactively, the instant something changes).

## Reactive descriptions with a derived string Property

Every PDOM text option (`descriptionContent`, `accessibleParagraph`, `accessibleName`, `innerContent`, …) accepts either a plain `string` or a `TReadOnlyProperty<string>`. Passing a `DerivedProperty` means the description text updates automatically whenever its dependencies change — no manual re-assignment needed:

```ts
import { DerivedProperty } from 'scenerystack/axon';
import { Node } from 'scenerystack/scenery';
import { StringUtils } from 'scenerystack/phetcommon';

const speedDescriptionProperty = new DerivedProperty(
  [ ball.speedProperty ],
  speed => StringUtils.fillIn( 'The ball is moving at {{speed}} meters per second.', {
    speed: speed.toFixed( 1 )
  } )
);

const ballNode = new Node( {
  tagName: 'div',
  descriptionContent: speedDescriptionProperty
} );
```

`StringUtils.fillIn` (from `scenerystack/phetcommon`) fills `{{placeholder}}` tokens in a template string — the standard way to build description sentences that embed a formatted value, and it composes cleanly with i18n since the template itself can be a translated `StringProperty`.

Because `descriptionContent` is just bound to the `Property`, this same pattern works for `accessibleParagraph`, `accessibleHelpText`, or `accessibleName` on any Node.

## Announcing changes as they happen with addAccessibleResponse

A reactive description only gets *read* the next time something visits it (focus, PDOM tab order, a screen reader's virtual cursor). Some state changes need to be spoken immediately, regardless of where focus is — e.g. "Boundary reached" when a draggable object hits the edge of its play area. For that, call `addAccessibleResponse` on any Node, which queues the text on that `Display`'s `descriptionUtteranceQueue` (an `aria-live="polite"` region by default — pass an `Utterance` with `announcerOptions: { ariaLivePriority: AriaLive.ASSERTIVE }` if a response must interrupt) for every accessible `Display` the Node is connected to:

```ts
class BallNode extends Node {
  private checkBoundary(): void {
    if ( this.model.isAtBoundary() ) {
      this.addAccessibleResponse( 'Boundary reached.' );
    }
  }
}
```

`addAccessibleResponse` accepts a plain string, a `TReadOnlyProperty<string>`, or an `Utterance` (from `scenerystack/utterance-queue`) if you need finer control over interruption/priority behavior. It silently no-ops if the Node (or an ancestor) is currently invisible, so you don't need to guard calls with a visibility check yourself.

## Choosing between the two

| Situation | Mechanism |
| --- | --- |
| Description should reflect current state whenever it's read (focus, screen-reader navigation) | Reactive `Property<string>` on `descriptionContent`/`accessibleParagraph` |
| Something just happened and the user should hear about it right now, independent of focus | `addAccessibleResponse( ... )` |
| Both — e.g. state changed *and* it's worth updating what's read later too | Do both: update the derived Property (or the underlying model Property it derives from) and call `addAccessibleResponse` for the immediate announcement |

## The spoken (Voicing) analog

`addAccessibleResponse` writes to the PDOM's description-utterance queue, which screen readers consume. [Voicing](/accessibility/voicing) is a separate, PhET-specific system for the same *kind* of problem — speaking content in response to interaction — but through direct speech synthesis rather than the PDOM's aria-live mechanism, and only when the user has explicitly enabled it. A component's dynamic-state announcements often need to be written for both systems with similar (not necessarily identical) wording.

::: tip Keep dynamic descriptions concise
A `DerivedProperty` that recomputes a long sentence on every tiny model change (every animation frame, say) produces noisy, hard-to-follow description content. Recompute only on meaningful state transitions — round values, and prefer `addAccessibleResponse` for a one-off "it happened" announcement over trying to make static description content narrate continuous motion.
:::


========================================================================
Page: Focus Highlights
URL: https://veillette.github.io/Almanach/accessibility/focus-highlights
Source: docs/accessibility/focus-highlights.md
Category: Accessibility | Tags: scenery, focus, accessibility | Status: verified
========================================================================

# Focus Highlights

Any focusable Node in scenery is automatically outlined with a focus highlight when it receives keyboard focus — a double-stroked "glow" (an outer lighter stroke and an inner darker one) drawn just outside the Node's bounds. You rarely need to customize this, but when the default rectangular-bounds highlight is wrong for a Node's shape, `focusHighlight` (from `ParallelDOM`, the mixin behind every Node's accessibility options) lets you replace it.

## The default highlight is automatic

```ts
import { Rectangle } from 'scenerystack/scenery';

const resetButton = new Rectangle( 0, 0, 40, 40, {
  tagName: 'button',
  accessibleName: 'Reset'
} );
```

No `focusHighlight` option is needed here — scenery draws a highlight sized to `resetButton`'s bounds whenever it has focus, and removes it on blur.

## Customizing the shape with HighlightFromNode

The most common customization is sizing the highlight around a *different* Node than the focusable one — e.g. a small hit-target Node whose highlight should instead trace a larger visual icon. `HighlightFromNode` (from `scenerystack/scenery`) builds a highlight from any Node's bounds and keeps it updated as that Node's bounds change:

```ts
import { Node, Path, HighlightFromNode } from 'scenerystack/scenery';

const iconNode = new Path( iconShape );
const draggableIcon = new Node( {
  children: [ iconNode ],
  tagName: 'div',
  focusable: true,
  accessibleName: 'Movable planet'
} );

// Highlight traces iconNode's bounds, not draggableIcon's (which may be larger, e.g. for touch area)
draggableIcon.focusHighlight = new HighlightFromNode( iconNode );
```

## Fully custom highlight shapes

For a highlight that isn't just "these bounds, dilated," set `focusHighlight` to any `Shape` or `Node` directly — most often a `HighlightPath` built from a custom `kite` `Shape`:

```ts
import { HighlightPath } from 'scenerystack/scenery';
import { Shape } from 'scenerystack/kite';

const customHighlight = new HighlightPath( Shape.circle( 0, 0, 30 ) );

circularButton.focusHighlight = customHighlight;
```

`HighlightPath` renders the same two-tone outer/inner stroke look as the default highlight, just around whatever `Shape` you give it, so custom highlights stay visually consistent with the rest of the application.

## Group focus highlights

A container of several small focusable Nodes (e.g. cells in a grid) can additionally get an outer highlight around the whole group, shown while focus is *anywhere inside* the group — set `groupFocusHighlight` on the container Node:

```ts
grid.groupFocusHighlight = true; // or a custom Node/Shape, same as focusHighlight
```

## Options

| Option | Effect |
| --- | --- |
| `focusHighlight` | `Shape \| Node \| 'invisible' \| null` — the highlight shown when this Node has focus; `null`/omitted uses the automatic bounds-based highlight, `'invisible'` suppresses it entirely |
| `focusHighlightLayerable` | If `true`, you take responsibility for placing the highlight Node in the scene graph yourself (e.g. to draw it behind other content) instead of scenery's overlay drawing it on top of everything |
| `groupFocusHighlight` | `Node \| boolean` — an additional highlight shown around this Node while focus is anywhere within its subtree |

::: tip Don't suppress highlights to "clean up" the visuals
Setting `focusHighlight: 'invisible'` removes the only visual indicator that keyboard focus has moved to a Node — do this only when a custom highlight is drawn some other way (e.g. a semantically equivalent selected-state look), never simply because the default highlight looks visually busy. See [Alternative Input Overview](/accessibility/alternative-input-overview) for why focus is the organizing concept for all non-pointer input.
:::


========================================================================
Page: Internationalized Accessible Names
URL: https://veillette.github.io/Almanach/accessibility/internationalized-accessible-names
Source: docs/accessibility/internationalized-accessible-names.md
Category: Accessibility | Tags: accessibility, pdom, accessibleName, localization, i18n, StringProperty | Status: verified
========================================================================

# Internationalized Accessible Names

[Translation and Localization](/guides/translation-and-localization) establishes the rule for visible text: every user-facing string is a `StringProperty`, never a literal, so translation is a matter of swapping the value underneath an existing Property. PDOM strings — `accessibleName`, `accessibleHelpText`, `descriptionContent`, `labelContent` — are just as user-facing as a `Text` node's content, and are exactly as easy to accidentally leave outside that pipeline, because they're set as string-shaped options rather than displayed inline where a translation review would notice them.

## The mechanism already supports it

Scenery's PDOM string options accept `PDOMValueType`, which is `string | TReadOnlyProperty<string> | null` — the identical shape `Text`/`RichText` accept for visible content. Passing a `StringProperty` (or a `DerivedProperty`/`PatternStringProperty` built from one) to `accessibleName` is not a workaround; it's the intended, idiomatic usage:

```ts
import { Rectangle } from 'scenerystack/scenery';
import MySimStrings from '../MySimStrings.js'; // generated StringProperty module, see Translation and Localization

// Correct: the same StringProperty that would be used for a visible label works
// here too, and updates automatically if the locale changes at runtime.
const resetButton = new Rectangle( 0, 0, 40, 40, {
  tagName: 'button',
  accessibleName: MySimStrings.resetMassesStringProperty,
  accessibleHelpText: MySimStrings.resetMassesHelpTextStringProperty
} );
```

## The anti-pattern: a hardcoded English literal

```ts
// Don't do this - accessibleName here will never be translated, even if every
// visible Text node on the same screen goes through the full string pipeline.
// A screen-reader user in any non-English locale hears English regardless of
// what locale the rest of the sim launched in.
const resetButton = new Rectangle( 0, 0, 40, 40, {
  tagName: 'button',
  accessibleName: 'Reset Masses'
} );
```

This is easy to miss in review because it doesn't look wrong — the visible parts of the screen are correctly localized, and a literal string passed to `accessibleName` compiles and works exactly like the correct version during development in the sim's default locale. The gap only becomes audible when a screen-reader user actually launches the sim in a translated locale.

## Where this applies

Every PDOM string option that accepts `PDOMValueType` is in scope, not just `accessibleName`:

| Option | Also needs a `StringProperty`, not a literal |
| --- | --- |
| `accessibleName` | Yes — same string pipeline as any visible label |
| `accessibleHelpText` | Yes — supplementary guidance is still user-facing text |
| `labelContent` / `descriptionContent` | Yes |
| [Voicing](/accessibility/voicing) response strings (`voicingNameResponse`, etc.) | Yes — these are spoken words, subject to the same localization requirement as PDOM strings, even though they're a separate system from the PDOM |

## Interpolated accessible names

An `accessibleName` that includes a dynamic value (an item's index, a current reading) has the same pluralization/word-order hazard as any other translated interpolated string — use `PatternStringProperty` rather than a template literal, exactly as [Translation and Localization](/guides/translation-and-localization#interpolating-values-into-translated-strings) prescribes for visible text:

```ts
import { PatternStringProperty } from 'scenerystack/axon';
import MySimStrings from '../MySimStrings.js';

// pattern (translated): '{{name}} slider, currently {{value}}'
const sliderAccessibleNameProperty = new PatternStringProperty(
  MySimStrings.namedSliderPatternStringProperty,
  { name: itemNameProperty, value: currentValueProperty }
);

slider.accessibleName = sliderAccessibleNameProperty;
```

::: tip Review PDOM strings the same way you'd review visible strings
When checking a PR (your own or someone else's) for stray hardcoded English, grep for `accessibleName:`, `accessibleHelpText:`, `labelContent:`, `descriptionContent:`, and `voicing*Response:` followed by a quoted literal, the same way you'd look for a bare string passed to `new Text(...)`. Nothing about these options makes a literal *look* wrong at a glance — the only way to catch it is to specifically look.
:::


========================================================================
Page: Keyboard Input and Hotkeys
URL: https://veillette.github.io/Almanach/accessibility/keyboard-input-and-hotkeys
Source: docs/accessibility/keyboard-input-and-hotkeys.md
Category: Accessibility | Tags: scenery, KeyboardListener, keyboard | Status: verified
========================================================================

# Keyboard Input and Hotkeys

`KeyboardDragListener` covers keyboard-driven dragging (see [The Parallel DOM](/accessibility/pdom)), but many interactions need arbitrary keyboard shortcuts that aren't a drag — deleting a selected item, opening a menu, stepping a simulation forward one frame. `KeyboardListener` (from `scenerystack/scenery`) is the general-purpose tool for that, built on top of the lower-level `Hotkey` class.

## A focus-scoped shortcut

Attach a `KeyboardListener` with `addInputListener` and it only fires while the target Node (or a descendant) has focus — the normal scenery input-dispatch behavior:

```ts
import { Node, KeyboardListener } from 'scenerystack/scenery';

const deletableItem = new Node( {
  tagName: 'div',
  focusable: true,
  accessibleName: 'Selected item'
} );

deletableItem.addInputListener( new KeyboardListener( {
  keys: [ 'delete', 'backspace' ],
  fire: ( event, keysPressed ) => {
    model.deleteSelectedItem();
  }
} ) );
```

Each entry in `keys` is a combination like `'shift+t'` or `'alt+shift+r'` — `+` separates the keys that must be held together, and the last key in the combination is the one that must be freshly pressed. `fire` receives which combination fired as `keysPressed`, so one listener can handle several related shortcuts:

```ts
new KeyboardListener( {
  keys: [ 'arrowRight', 'shift+arrowRight' ],
  fire: ( event, keysPressed ) => {
    const step = keysPressed === 'shift+arrowRight' ? 10 : 1;
    model.advance( step );
  }
} );
```

## Global shortcuts

A shortcut that should work regardless of where focus currently is (a "step simulation" key, a global help overlay) uses `KeyboardListener.createGlobal` instead of `addInputListener`. It registers `Hotkey`s on the shared `globalHotkeyRegistry` and must be disposed when no longer needed:

```ts
import { KeyboardListener } from 'scenerystack/scenery';

const globalStepListener = KeyboardListener.createGlobal( screenView, {
  keys: [ 'k' ],
  fire: () => model.stepOnce( 0.1 )
} );

// later, e.g. in the ScreenView's dispose:
globalStepListener.dispose();
```

## Options

| Option | Effect |
| --- | --- |
| `keys` | Array of key combinations (`'a+b'`, `'shift+arrowLeft'`, …) that fire the callback |
| `fire` | `( event, keysPressed, listener ) => void`, called when the combination fires |
| `press` / `release` | Called on initial press / on release, independent of fire-on-hold behavior |
| `fireOnDown` | `true` (default) fires on initial press; `false` fires on release instead |
| `fireOnHold` | Enables press-and-hold repeated firing |
| `fireOnHoldTiming` | `'browser'` (default, relies on native key-repeat) or `'custom'` (uses `fireOnHoldCustomDelay`/`fireOnHoldCustomInterval`) |
| `overlapBehavior` | How this listener behaves when another active listener shares keys: `'handle'` (default — closest listener wins), `'allow'`, or `'prevent'` (asserts on overlap) |

## Ignoring modifier keys

By default, an active modifier key (like `shift`) blocks other combinations that don't include it from firing — pressing `shift` alone can prevent a plain `'y'` listener from firing. Use `?` to opt a modifier out of that blocking behavior:

```ts
new KeyboardListener( {
  keys: [ 'shift?+y' ],   // fires on 'y' whether or not shift happens to be down
  fire: () => model.toggle()
} );
```

## Hotkey: the lower-level building block

`KeyboardListener` constructs `Hotkey` instances internally; reach for `Hotkey` directly (from `scenerystack/scenery`) only when you need a single dynamic key combination described by a `Property`, or need to add it straight to a Node's `inputListeners`/the `globalHotkeyRegistry` without the rest of `KeyboardListener`'s machinery:

```ts
import { Hotkey, globalHotkeyRegistry } from 'scenerystack/scenery';
import { Property } from 'scenerystack/axon';

const helpHotkey = new Hotkey( {
  keyStringProperty: new Property( 'shift+h' ),
  fire: () => model.showHelp()
} );

globalHotkeyRegistry.add( helpHotkey );
// ...later
globalHotkeyRegistry.remove( helpHotkey );
```

::: tip Test every combination on a real keyboard layout
Some key combinations can't be physically pressed together on certain keyboards ("key ghosting" — commonly affects simultaneous arrow keys). Always verify custom hotkeys on more than one keyboard before shipping, and prefer combinations that don't stack many simultaneous non-modifier keys.
:::


========================================================================
Page: Mobile Screen-Reader Testing Notes
URL: https://veillette.github.io/Almanach/accessibility/mobile-screen-reader-testing-notes
Source: docs/accessibility/mobile-screen-reader-testing-notes.md
Category: Accessibility | Tags: accessibility, pdom, screen-reader, voiceover, talkback, mobile, testing | Status: verified
========================================================================

# Mobile Screen-Reader Testing Notes

[The Screen-Reader Testing Checklist](/accessibility/screen-reader-testing-checklist) covers what to verify regardless of platform — reachability, naming, state-change announcements, focus behavior. This page is narrower: the practical, platform-specific notes for actually running that checklist on a phone or tablet with **VoiceOver** (iOS/iPadOS, paired with Safari) or **TalkBack** (Android, paired with Chrome), and the ways that session differs from a desktop VoiceOver/NVDA pass.

## Touch exploration replaces linear Tab navigation

The biggest structural difference from desktop testing: there is no <kbd>Tab</kbd> key. Both VoiceOver and TalkBack are driven primarily by **touch exploration** (dragging a finger around the screen, with the screen reader speaking whatever's currently under it) and **swipe gestures** (typically swipe-right/left to move to the next/previous element in the same order `pdomOrder` would drive on desktop). This means:

- A layout that "reads fine" via swipe navigation can still be confusing to explore by touch if visually-adjacent elements are far apart in `pdomOrder` — a user exploring by touch expects the element under their finger to roughly match what swiping would have reached next.
- Test **both** modes: a full swipe-through pass (this exercises the same `pdomOrder` logic as a desktop Tab pass) and a touch-exploration pass (this is closer to how a mobile screen-reader user often actually works a new screen, scanning by feel before committing to linear navigation).

## Activation gestures differ from desktop

Where a desktop screen-reader user presses <kbd>Enter</kbd>/<kbd>Space</kbd> on a focused element, mobile screen readers use a **double-tap** (anywhere on the screen, while the target element is selected) to activate the currently-focused/selected element, rather than a direct tap on the element itself — a direct single tap while the screen reader is running instead moves selection to whatever's at that point, the same as touch-exploring. This is easy to trip over the first time you test on a phone: tapping a button the way a sighted user would just re-selects it and speaks its name again, rather than activating it.

## Custom draggables need extra attention on mobile

[Drag Listeners](/patterns/drag-listeners) and [Alternative Input Overview](/accessibility/alternative-input-overview) already establish that a draggable Node needs a keyboard path (arrow keys via `KeyboardDragListener`/`RichDragListener`) in addition to pointer dragging. On a touchscreen with a screen reader running, ordinary touch-drag gestures are intercepted by the screen reader for exploration, so reaching the object's keyboard-equivalent movement typically requires the screen reader's own gesture for adjusting a selected element's value (on VoiceOver, swiping up/down while an adjustable element is selected commonly maps to incrementing/decrementing, mirroring how a native `<input type="range">` behaves) — verify a sim's draggable/adjustable custom elements actually respond to that gesture, rather than only testing them with a physical keyboard.

## Platform and browser pairing matters more than on desktop

Where desktop testing has two dominant pairings (VoiceOver+Safari, NVDA+Firefox/Chrome), mobile compounds the variables: OS version, browser (Safari is the primary target on iOS; Chrome is the primary target on Android, though other browsers exist on both), and the screen reader's own version can each independently change announcement behavior. Record all three (OS version, browser, screen-reader-implied-by-OS-version) alongside any issue found, the same way [the checklist](/accessibility/screen-reader-testing-checklist#filing-what-you-find) asks for on desktop — a mobile-specific bug report without the OS/browser pairing is often not reproducible by whoever picks it up.

## Rotor/heading navigation exists, but is discovered differently

Desktop screen readers commonly support jumping directly to headings (`labelTagName: 'h3'`, etc. — see [The Parallel DOM](/accessibility/pdom)) via a dedicated keystroke. VoiceOver's mobile equivalent is the **rotor** (a gesture — typically a two-finger twist — that opens a menu of navigation modes including headings, links, and form controls); TalkBack has an analogous but differently-invoked heading/reading-controls menu. Confirm the sim's heading structure is actually reachable through the platform's rotor-equivalent, not just assumed to carry over identically from a desktop pass, since the discovery mechanism itself is unfamiliar to many first-time testers.

## What still transfers directly from desktop testing

Not everything changes on mobile — the underlying PDOM structure a sim builds is the same regardless of input surface, so these desktop-checklist items still apply unchanged:

- Accessible names still need to identify the control without relying on visual context (see [the checklist](/accessibility/screen-reader-testing-checklist#the-checklist)).
- Dynamic content changes still need to be communicated via [reactive descriptions or `addAccessibleResponse`](/accessibility/describing-dynamic-state), not silently rendered.
- A rapidly-changing live value still needs throttling so the screen reader isn't spammed — this is, if anything, more noticeable on a phone's smaller, closer speaker.

::: tip Confirm platform gestures against current OS documentation
The SceneryStack-specific claims on this page (`pdomOrder`, keyboard-drag alternatives, reactive descriptions) were verified against Almanach's other verified pages and `scenerystack@3.0.0`. VoiceOver/TalkBack gesture names reflect commonly documented conventions; confirm against Apple's or Google's current accessibility docs (or a real device) when filing bugs tied to a specific OS version.
:::


========================================================================
Page: Screen-Reader Testing Checklist
URL: https://veillette.github.io/Almanach/accessibility/screen-reader-testing-checklist
Source: docs/accessibility/screen-reader-testing-checklist.md
Category: Accessibility | Tags: accessibility, pdom, screen-reader, voiceover, nvda, testing | Status: verified
========================================================================

# Screen-Reader Testing Checklist

[The Parallel DOM](/accessibility/pdom) explains what the PDOM is and how to structure it; this page assumes that and covers something no amount of reading the option table replaces: actually turning on a screen reader and going through a screen with it. A `tagName`/`accessibleName` set correctly in code can still read badly out loud — announcement order, redundant chatter, and confusing groupings only surface once you listen to the real output.

## Before you start

- Test with an actual screen reader, not just the PDOM's rendered HTML structure in devtools. A `pdomOrder` that looks right in the accessibility tree inspector can still sound wrong — screen readers summarize, elide, and reorder in ways that only show up audibly.
- Cover more than one screen reader/browser pairing if the sim will reach a broad audience. VoiceOver (macOS/iOS, paired with Safari) and NVDA (Windows, paired with Firefox or Chrome) are the two most commonly targeted; they don't always announce identical content identically.
- Turn your monitor off (or close your eyes) for at least one full pass. Sighted screen-reader testing is easy to do halfway — glancing at the screen to confirm what "should" have been announced instead of confirming what actually *was*.

## The checklist

**Reachability**
- [ ] Every interactive element (button, slider, checkbox, custom draggable) is reachable by moving forward through the screen reader's normal navigation, without needing to know where it is in advance.
- [ ] Nothing that should be interactive is skipped over silently, and nothing decorative is announced as if it were interactive.
- [ ] Tab order and screen-reader reading order agree with the visual reading order a sighted user would expect — driven by `pdomOrder`, not left to default scene-graph order (see [The Parallel DOM](/accessibility/pdom#focus-order-with-pdomorder)).

**Naming and description**
- [ ] Every interactive element announces a name (`accessibleName`) that identifies what it does without requiring the visual label as context — "Reset Masses" reads correctly on its own; "Button" or a name duplicated across three unrelated controls does not.
- [ ] `accessibleHelpText`/description content is heard when expected and isn't redundant with the name (a help text that just repeats the accessible name verbatim is noise, not guidance).
- [ ] Headings (`labelTagName: 'h3'`, etc.) let a screen-reader user jump between sections using heading navigation, the way they would on a well-structured web page.

**State changes**
- [ ] A value change (a slider moving, a checkbox toggling) is announced promptly and legibly — not just on initial focus, but every time it changes while focused.
- [ ] Dynamic content changes that happen *without* focus moving (a readout updating in response to another control) are still communicated somehow — via [live-region-style dynamic descriptions](/accessibility/describing-dynamic-state) or Voicing, not silently rendered and never announced.
- [ ] Nothing over-announces — a rapidly-changing value (a live physics readout) doesn't spam the screen reader with an announcement every animation frame; check that updates are throttled to something a user can actually follow.

**Focus and highlights**
- [ ] Every focusable element shows a visible focus highlight for sighted low-vision users navigating by keyboard alongside the screen reader (see [Focus Highlights](/accessibility/focus-highlights)) — screen-reader and keyboard-only usage overlap heavily in practice.
- [ ] Focus never gets trapped in a sub-region (a dialog, a popup) without an announced, working way out.
- [ ] Opening/closing a dialog moves focus predictably (into the dialog on open, back to the triggering control on close) rather than leaving focus on a now-hidden or now-destroyed element.

**Voicing (if enabled)**
- [ ] If the sim also supports [Voicing](/accessibility/voicing), test it as a *separate* pass from screen-reader testing — Voicing is a distinct opt-in feature aimed at sighted users, not a replacement for PDOM correctness, and testing them together makes it easy to mistake one system's announcement for the other's.

## Filing what you find

Note the exact screen reader, browser, and OS version alongside each issue — screen-reader behavior is notoriously version- and pairing-specific, and "VoiceOver announced X" without the browser is often not reproducible by whoever picks up the fix.

::: tip Automated PDOM checks catch structure, not experience
A validator can confirm every interactive element has a `tagName` and an `accessibleName` set. It cannot tell you the reading order is confusing, that two elements have the same name, or that a live update is spammy. Treat automated checks as a floor, and this checklist's manual pass as the thing that actually determines whether the experience is usable.
:::


========================================================================
Page: Sound Design
URL: https://veillette.github.io/Almanach/accessibility/sound-design
Source: docs/accessibility/sound-design.md
Category: Accessibility | Tags: tambo, sound, accessibility | Status: verified
========================================================================

# Sound Design

Non-speech sound ("sonification") is a third accessibility channel alongside the [PDOM](/accessibility/pdom) and [Voicing](/accessibility/voicing): short audio cues that confirm an interaction happened or reflect continuous state, independent of whether the user is looking at the screen or using a screen reader. `tambo` (`scenerystack/tambo`) is the sound-generation library used for this; it registers individual **sound generators** with a single global `soundManager`, which owns overall enable/disable, per-category gain, and visibility-based muting.

::: tip soundManager is a ready-made singleton
`soundManager` (and the `sharedSoundPlayers` registry built on top of it) is instantiated once per module and registered by `tambo` itself — a simulation doesn't construct or initialize it; `joist`'s sim-lifecycle code enables it based on the `supportsSound`/`extraSoundInitiallyEnabled` query parameters. View code just imports the singleton and calls `addSoundGenerator`/`get` on it, as below.
:::

## Reuse a shared sound player for common UI sounds

For standard interactions — checkbox toggles, button presses, reset — reach for `sharedSoundPlayers` (from `scenerystack/tambo`) before creating a custom sound. Shared players are created lazily on first use, are automatically registered with `soundManager`, and keep the sound experience consistent (and memory usage low) across every checkbox/button in a project:

```ts
import { sharedSoundPlayers } from 'scenerystack/tambo';

const checkboxSoundPlayer = sharedSoundPlayers.get( 'checkboxChecked' );

gravityEnabledProperty.link( enabled => {
  if ( enabled ) {
    checkboxSoundPlayer.play();
  }
} );
```

Available shared player names include `'checkboxChecked'`, `'checkboxUnchecked'`, `'pushButton'`, `'resetAll'`, `'grab'`, `'release'`, `'boundaryReached'`, `'stepForward'`, `'stepBackward'`, and more — one per common PhET-wide interaction.

## Custom one-shot or looping sounds with SoundClip

For a sound specific to a single simulation, wrap an audio asset in a `SoundClip` (from `scenerystack/tambo`) and add it to `soundManager` directly:

```ts
import { SoundClip, soundManager } from 'scenerystack/tambo';
import collisionSound_mp3 from './sounds/collisionSound_mp3.js';

const collisionSoundClip = new SoundClip( collisionSound_mp3, {
  initialOutputLevel: 0.7
} );

soundManager.addSoundGenerator( collisionSoundClip, {
  categoryName: 'sim-specific'
} );

// Play it when a collision happens in the model
model.collisionEmitter.addListener( () => collisionSoundClip.play() );
```

`SoundClip` supports `loop: true` for continuous sounds (e.g. an ambient hum tied to a running motor) in addition to the default one-shot playback.

## Categories and global control

`soundManager` groups sound generators into categories (by default `'sim-specific'` and `'user-interface'`) so a user's sound preferences can control them independently — e.g. muting UI click sounds while keeping sim-specific feedback. Pass `categoryName` in `addSoundGenerator`'s options to assign a generator to one:

```ts
soundManager.addSoundGenerator( myUiSoundClip, { categoryName: 'user-interface' } );
soundManager.addSoundGenerator( mySimSoundClip, { categoryName: 'sim-specific' } );
```

`soundManager.enabledProperty` and `soundManager.extraSoundEnabledProperty` control sound globally and for "extra"/basic sonification levels respectively; simulations typically expose these through Preferences rather than sound generators managing their own on/off state.

## Relationship to Voicing and the PDOM

Sound design is a distinct, complementary channel: [Voicing](/accessibility/voicing) speaks words, the PDOM structures content for screen readers, and `tambo` sounds are non-verbal cues (a click, a chime, a boundary "boop") that work for every user regardless of whether speech or screen-reader output is enabled. A well-designed interaction often layers a sound (immediate, wordless feedback) with a Voicing/PDOM response (a fuller description) rather than choosing one over the other.

::: tip Don't build custom sounds for interactions sun already covers
Most common component sounds (checkboxes, push buttons, radio buttons, sliders) are wired up by `sun`'s components themselves through `sharedSoundPlayers` — check whether the built-in sound already covers an interaction before adding a redundant custom `SoundClip`.
:::


========================================================================
Page: The Parallel DOM (PDOM)
URL: https://veillette.github.io/Almanach/accessibility/pdom
Source: docs/accessibility/pdom.md
Category: Accessibility | Tags: scenery, pdom, accessibility, a11y, screen-reader, tagName, accessibleName | Status: verified
========================================================================

# The Parallel DOM (PDOM)

::: tip API reference vs. author guide
This page explains **why and how** simulation authors opt Nodes into the PDOM. For the full list of `ParallelDOM` trait options and accessors on `Node`, see [ParallelDOM](/api/scenery/parallel-dom-deep-dive).
:::

Scenery draws to Canvas/SVG/WebGL: To make applications accessible, scenery maintains a **Parallel DOM**: a hidden tree of real HTML elements that mirrors the interactive structure of the scene graph. Screen readers read it, keyboard focus moves through it, and input events on it are routed back to the corresponding Nodes.

You opt each Node into the PDOM with accessibility options — no separate accessibility tree to maintain.

## Basic options

```ts
import { Node, Rectangle } from 'scenerystack/scenery';

// A heading + paragraph in the PDOM
const infoSection = new Node( {
  tagName: 'div',
  labelTagName: 'h3',
  labelContent: 'Mass Controls',
  descriptionContent: 'Adjust the mass of each body, in kilograms.'
} );

// An interactive element: focusable, named, with help text
const resetShape = new Rectangle( 0, 0, 40, 40, {
  tagName: 'button',
  accessibleName: 'Reset Masses',
  accessibleHelpText: 'Return both masses to their starting values.'
} );
```

| Option | Meaning |
| --- | --- |
| `tagName` | HTML element representing this Node (`'div'`, `'button'`, `'ul'`, …). Setting it is what places the Node in the PDOM |
| `innerContent` | Text content inside the element |
| `labelTagName` / `labelContent` | A sibling label element (e.g. an `h3` before the content) |
| `descriptionContent` | A sibling description paragraph |
| `accessibleName` | The name announced by screen readers (higher-level API; prefer this) |
| `accessibleHelpText` | Supplementary guidance announced with the element |
| `focusable` | Whether the element is in the tab order (interactive `tagName`s like `'button'` already are) |

Common UI components from `sun` (buttons, sliders, checkboxes) come with sensible PDOM structure built in — you typically only supply `accessibleName` and `accessibleHelpText`.

## Focus order with pdomOrder

By default, PDOM order follows scene-graph order, which is a *rendering* order and often wrong for traversal. Set `pdomOrder` on a parent to control it explicitly:

```ts
screenView.pdomOrder = [
  massControlPanel,
  bodyNode,        // draggable — see /patterns/drag-listeners
  gridCheckbox,
  resetAllButton
];
```

Nodes omitted from `pdomOrder` follow afterwards in their natural order; `null` may be used as a placeholder for "everything else here".

## Custom interactions

A Node that implements its own interaction (like a custom draggable) needs three things:

```ts
bodyNode.tagName = 'div';
bodyNode.focusable = true;
bodyNode.accessibleName = 'Movable planet';
bodyNode.addInputListener( new KeyboardDragListener( { /* ... */ } ) );
```

1. A `tagName` so it exists in the PDOM,
2. `focusable: true` so keyboard users can reach it,
3. listeners that respond to keyboard input, not just pointers — see [Drag Listeners](/patterns/drag-listeners).

::: tip Test with the keyboard first
Before reaching for a screen reader, unplug your mouse: every interactive element should be reachable with <kbd>Tab</kbd>, operable with <kbd>Enter</kbd>/<kbd>Space</kbd>/arrows, and show a visible focus highlight (scenery draws these automatically for focusable Nodes).
:::


========================================================================
Page: Voicing
URL: https://veillette.github.io/Almanach/accessibility/voicing
Source: docs/accessibility/voicing.md
Category: Accessibility | Tags: scenery, voicing, speech | Status: verified
========================================================================

# Voicing

Voicing is scenery's feature for speaking descriptions aloud via HTML5 `SpeechSynthesis`, layered on top of the [Parallel DOM](/accessibility/pdom) rather than replacing it — a screen reader user gets the PDOM as usual, while a sighted user who enables Voicing (a PhET-specific preference, distinct from running a full screen reader) hears the same kind of information spoken directly by the simulation.

## The four response categories

Voicing organizes what's spoken into four kinds of response, all optional:

| Response | Describes |
| --- | --- |
| `voicingNameResponse` | What the object is (analogous to `accessibleName`) |
| `voicingObjectResponse` | The object's current state |
| `voicingContextResponse` | What changed elsewhere as a result of interacting with it |
| `voicingHintResponse` | Supporting guidance on how to interact with it |

## Adding Voicing to a Node

`Voicing` is a trait (mixin) applied to a `Node` subclass — most simulation code instead reaches for the ready-made `VoicingText` (from `scenerystack/scenery`) for static labeled content, or mixes `Voicing` directly into an interactive component:

```ts
import { VoicingText } from 'scenerystack/scenery';

// Speaks its own text on request (e.g. via a "read" gesture in Voicing mode)
const instructions = new VoicingText( 'Drag the ball to launch it.' );
```

For an interactive Node, compose `Voicing` with `Node` and set the response strings as options:

```ts
import { Node, Voicing } from 'scenerystack/scenery';

class LaunchButtonNode extends Voicing( Node ) {
  public constructor() {
    super( {
      tagName: 'button',
      accessibleName: 'Launch',
      voicingNameResponse: 'Launch',
      voicingHintResponse: 'Launches the ball at the current angle and speed.'
    } );
  }
}
```

Every Node that composes `Voicing` speaks its full response automatically when it receives focus — you don't need to call anything for the focus case.

## Speaking on demand

For responses tied to something other than focus (a value change, a button press), call one of the `voicingSpeak*` methods directly. Update the response content first, then speak it — this is the same pattern used throughout `sun` components:

```ts
class CountDisplay extends Voicing( Node ) {
  public updateCount( count: number ): void {
    this.voicingObjectResponse = `${count} items selected`;
    this.voicingSpeakResponse( { objectResponse: this.voicingObjectResponse } );
  }
}
```

| Method | Speaks |
| --- | --- |
| `voicingSpeakFullResponse( options? )` | All four response categories assigned to the Node |
| `voicingSpeakResponse( options? )` | Only whatever is passed in `options` — none of the Node's assigned responses by default |
| `voicingSpeakNameResponse( options? )` | The name response (plus anything else passed in `options`) |
| `voicingSpeakObjectResponse( options? )` | The object response |
| `voicingSpeakContextResponse( options? )` | The context response |
| `voicingSpeakHintResponse( options? )` | The hint response |

Each speak call still respects the user's response-category preferences (via `responseCollector`) — if the user has disabled hints, `voicingHintResponse` content is silently skipped even when included.

## Voicing vs. the PDOM

Voicing content and PDOM content (`accessibleName`, `descriptionContent`, `accessibleHelpText`; see [The Parallel DOM](/accessibility/pdom)) are deliberately separate systems that often carry *similar but not identical* wording — the PDOM is read by conventional screen readers with their own navigation model, while Voicing content is spoken directly by the sim in response to specific gestures/focus. Most components set both, and it's fine (often correct) for the phrasing to differ slightly given the different context each is heard in.

::: tip Voicing requires an explicit user opt-in
Voicing speech only plays once the user has enabled it via preferences (it is not the same as a screen reader, and is off by default) — during development, remember that a `Voicing`-enabled Node's responses are silent until Voicing is turned on, even though the response strings are already assigned.
:::


========================================================================
Page: A 3D Scene with Mobius
URL: https://veillette.github.io/Almanach/examples/3d-scene-with-mobius
Source: docs/examples/3d-scene-with-mobius.md
Category: Examples | Tags: example, mobius, ThreeStage, ThreeNode, three.js, 3d, webgl | Status: complete
========================================================================

# A 3D Scene with Mobius

[Three.js Integration](/examples/three-js-integration) already walks through the most common mobius setup — subclassing `MobiusScreenView` for a full-screen isometric 3D stage. [`ThreeStage`](/api/mobius/scene-and-camera-setup) and [`ThreeUtils`](/api/mobius/three-utils-helpers) document the lower-level pieces underneath that path. This page builds directly on both: it repeats the full-screen `MobiusScreenView` shape briefly for contrast, then focuses on the other common shape — a **fixed-size 3D viewport** (`ThreeNode`) placed as one ordinary child alongside 2D scenery content, which is the better fit when 3D content is a small part of a screen rather than its entire backdrop.

No new mobius APIs are introduced here beyond what [Three.js Integration](/examples/three-js-integration), [ThreeStage](/api/mobius/scene-and-camera-setup), and [ThreeNode, ThreeInstrumentable, and ThreeObject3DPhetioObject](/api/mobius/node-wrapping-conventions) already document.

## Option A: full-screen isometric stage (MobiusScreenView)

For 3D content that *is* the screen — the shape [Three.js Integration](/examples/three-js-integration) covers in depth — subclass `MobiusScreenView`, which builds a `ThreeIsometricNode` (`this.sceneNode`) sized to the screen automatically:

```ts
import { MobiusScreenView, type MobiusScreenViewOptions } from 'scenerystack/sim';
import { THREE } from 'scenerystack/mobius';

class OrbitScreenView extends MobiusScreenView {
  private readonly planet: THREE.Mesh;

  public constructor( providedOptions: MobiusScreenViewOptions ) {
    super( providedOptions );

    const geometry = new THREE.SphereGeometry( 0.4, 32, 16 );
    const material = new THREE.MeshNormalMaterial();
    this.planet = new THREE.Mesh( geometry, material );
    this.sceneNode.stage.threeScene.add( this.planet );
    this.sceneNode.stage.threeScene.add( new THREE.DirectionalLight( 0xffffff, 1 ) );
  }

  public override step( dt: number ): void {
    this.planet.rotation.y += dt * 0.5;
    super.step( dt ); // re-renders the stage
  }
}
```

Reach for this when 3D content occupies the whole screen and should pan/scale with the layout the way [Three.js Integration](/examples/three-js-integration) describes.

## Option B: a fixed-size viewport alongside 2D content (ThreeNode)

When 3D content is one element among ordinary scenery Nodes — a small rotating preview next to a control panel, say — [`ThreeNode`](/api/mobius/node-wrapping-conventions#threenode-a-fixed-size-three-js-viewport) is the better fit: it hosts its own `ThreeStage` at a fixed pixel size and behaves like any other Node for layout purposes.

```ts
import { ScreenView, type ScreenViewOptions } from 'scenerystack/sim';
import { VBox, Text } from 'scenerystack/scenery';
import { ThreeNode, THREE } from 'scenerystack/mobius';
import { Vector3 } from 'scenerystack/dot';
import { Checkbox } from 'scenerystack/sun';
import { BooleanProperty } from 'scenerystack/axon';

// The model itself has nothing 3D-specific about it - it just owns a Property the view reads.
class MoleculePreviewModel {
  public readonly rotationEnabledProperty = new BooleanProperty( true );
  public reset(): void {
    this.rotationEnabledProperty.reset();
  }
}

class MoleculePreviewScreenView extends ScreenView {
  private readonly model: MoleculePreviewModel;
  private readonly moleculeThreeNode: ThreeNode;
  private readonly moleculeMesh: THREE.Mesh;

  public constructor( model: MoleculePreviewModel, providedOptions: ScreenViewOptions ) {
    super( providedOptions );
    this.model = model;

    this.moleculeThreeNode = new ThreeNode( 300, 300, {
      cameraPosition: new Vector3( 0, 0, 3 )
    } );

    const geometry = new THREE.IcosahedronGeometry( 0.6, 0 );
    const material = new THREE.MeshNormalMaterial();
    this.moleculeMesh = new THREE.Mesh( geometry, material );
    this.moleculeThreeNode.stage.threeScene.add( this.moleculeMesh );
    this.moleculeThreeNode.stage.threeScene.add( new THREE.DirectionalLight( 0xffffff, 1 ) );

    // ThreeNode is a plain Node - it composes with ordinary 2D layout containers.
    const rotateCheckbox = new Checkbox( model.rotationEnabledProperty, new Text( 'Rotate' ), {
      tandem: this.tandem.createTandem( 'rotateCheckbox' )
    } );

    const controlsColumn = new VBox( {
      spacing: 10,
      align: 'left',
      children: [ this.moleculeThreeNode, rotateCheckbox ],
      center: this.layoutBounds.center
    } );

    this.children = [ controlsColumn ];

    // ThreeNode needs an explicit layout() call once its position in the global
    // scene graph is settled, unlike MobiusScreenView (which handles this for you).
    this.moleculeThreeNode.layout();
  }

  public step( dt: number ): void {
    if ( this.model.rotationEnabledProperty.value ) {
      this.moleculeMesh.rotation.y += dt;
    }
    this.moleculeThreeNode.render();
  }
}
```

A few things worth noticing:

| Piece | Why it's there |
| --- | --- |
| `ThreeNode( 300, 300, ... )` | A fixed pixel size, unlike `MobiusScreenView`'s screen-filling `ThreeIsometricNode` — see the constructor signature on [ThreeNode](/api/mobius/node-wrapping-conventions#threenode-constructor) |
| `moleculeThreeNode` as a `VBox` child | `ThreeNode` extends `scenery`'s `Node`, so it participates in [layout containers](/styling/layout-container-conventions) exactly like any 2D Node — no special-casing needed in the layout code |
| `.layout()` called once, explicitly | Recomputes the stage's pixel dimensions from the Node's current global bounds; call it again after any transform change that affects `moleculeThreeNode`'s placement, since (unlike `MobiusScreenView`) nothing calls it for you automatically |
| `.render()` called every `step()` | `ThreeNode` doesn't render itself on a timer — the hosting `ScreenView`'s `step(dt)` is responsible, the same as `MobiusScreenView.step()` does internally for its own stage |

## Instrumenting a mesh for PhET-iO, if needed

If a specific `THREE.Object3D` needs its own PhET-iO identity (so Studio can select or reference it), wrap its constructor with `ThreeInstrumentable` rather than trying to attach a `tandem` to the plain three.js object directly — three.js objects have no PhET-iO concept of their own (see [ThreeNode, ThreeInstrumentable, and ThreeObject3DPhetioObject](/api/mobius/node-wrapping-conventions#instrumenting-individual-three-js-objects)):

```ts
import { ThreeInstrumentable, THREE } from 'scenerystack/mobius';

const InstrumentedMesh = ThreeInstrumentable( THREE.Mesh );

const instrumentedMolecule = new InstrumentedMesh( geometry, material, {
  tandem: this.tandem.createTandem( 'moleculeMesh' )
} );
this.moleculeThreeNode.stage.threeScene.add( instrumentedMolecule );
```

This only gives PhET-iO Studio an address for the object to select — it does **not** save/restore its position or rotation on state restore; model that state as ordinary `Property`s if it needs to survive a PhET-iO save/load.

## Choosing between the two options

| Use `MobiusScreenView` (full-screen) | Use `ThreeNode` (fixed-size) |
| --- | --- |
| 3D content is the entire screen's subject | 3D content is a small part of a larger, mostly-2D screen |
| Isometric framing that adapts to the layout bounds is wanted | A fixed pixel footprint next to ordinary controls is wanted |
| No 2D scenery siblings need to share layout with the 3D content | The 3D viewport needs to sit inside a `VBox`/`HBox`/`Panel` with 2D Nodes |

::: tip Both paths share the same ThreeStage underneath
Whichever Node you reach for, the actual three.js objects (`THREE.Scene`, `THREE.PerspectiveCamera`, `THREE.WebGLRenderer`) live on the same `ThreeStage` type — `.stage` is available on both `ThreeIsometricNode`/`MobiusScreenView.sceneNode` and `ThreeNode`. Anything documented on [ThreeStage](/api/mobius/scene-and-camera-setup) (projecting points, checking `isWebGLEnabled()`, disposing) works identically regardless of which hosting Node you chose.
:::

## Where to go next

- [Three.js Integration](/examples/three-js-integration) — the full-screen `MobiusScreenView` path in depth
- [ThreeStage](/api/mobius/scene-and-camera-setup) — the scene/camera/renderer object both options above share
- [ThreeUtils](/api/mobius/three-utils-helpers) — coordinate conversions and the `isWebGLEnabled()` guard
- [ThreeNode, ThreeInstrumentable, and ThreeObject3DPhetioObject](/api/mobius/node-wrapping-conventions) — the fixed-size viewport and PhET-iO instrumentation details used above


========================================================================
Page: A Chart-Driven Simulation with Bamboo
URL: https://veillette.github.io/Almanach/examples/chart-driven-simulation-with-bamboo
Source: docs/examples/chart-driven-simulation-with-bamboo.md
Category: Examples | Tags: example, bamboo, ChartTransform, LinePlot, chart | Status: complete
========================================================================

# A Chart-Driven Simulation with Bamboo

This page builds a small, complete screen where a model `Property` drives a live-updating [`LinePlot`](/api/bamboo/line-plot) through a shared [`ChartTransform`](/api/bamboo/chart-transform) — the same pieces documented individually in `api/bamboo/`, wired together end to end, including axes, gridlines, and an accessible chart description. The scenario: a cooling cup of coffee, whose temperature decays toward room temperature over time, plotted as temperature vs. elapsed time.

## The model

The model owns the temperature Property and appends a new (time, temperature) sample every `step()`, following [model-view separation](/patterns/model-view-separation):

```ts
import { NumberProperty, Property } from 'scenerystack/axon';
import { Range, Vector2 } from 'scenerystack/dot';
import { Tandem } from 'scenerystack/tandem';

class CoolingCupModel {
  public readonly temperatureProperty: NumberProperty;
  public readonly dataSetProperty: Property<Vector2[]>;

  private elapsedTime = 0;
  private static readonly ROOM_TEMPERATURE = 22; // Celsius
  private static readonly COOLING_RATE = 0.05;   // per second

  public constructor( tandem: Tandem ) {
    this.temperatureProperty = new NumberProperty( 90, {
      range: new Range( 22, 100 ),
      tandem: tandem.createTandem( 'temperatureProperty' )
    } );

    // The full dataset the chart plots - not just the current value, so the LinePlot
    // has a history to draw a line through, not a single point.
    this.dataSetProperty = new Property<Vector2[]>( [ new Vector2( 0, this.temperatureProperty.value ) ] );
  }

  public step( dt: number ): void {
    this.elapsedTime += dt;

    const roomTemperature = CoolingCupModel.ROOM_TEMPERATURE;
    const decay = Math.exp( -CoolingCupModel.COOLING_RATE * this.elapsedTime );
    this.temperatureProperty.value = roomTemperature + ( 90 - roomTemperature ) * decay;

    // Append a sample; reassigning (not mutating in place) so the Property fires.
    this.dataSetProperty.value = [
      ...this.dataSetProperty.value,
      new Vector2( this.elapsedTime, this.temperatureProperty.value )
    ];
  }

  public reset(): void {
    this.elapsedTime = 0;
    this.temperatureProperty.reset();
    this.dataSetProperty.reset();
  }
}
```

`dataSetProperty` is reassigned to a new array each step rather than mutated in place — `Property` only notifies listeners on `.value =`/`.set()`, so appending to the existing array with `.push()` would silently fail to trigger a redraw.

## The view: chart, axes, and an accessible description

```ts
import { ScreenView, type ScreenViewOptions } from 'scenerystack/sim';
import { Node, Text } from 'scenerystack/scenery';
import { ChartTransform, ChartRectangle, LinePlot, AxisLine, GridLineSet, TickLabelSet } from 'scenerystack/bamboo';
import { Orientation } from 'scenerystack/phet-core';
import { Range } from 'scenerystack/dot';
import { DerivedProperty } from 'scenerystack/axon';
import { StringUtils } from 'scenerystack/phetcommon';
import { ResetAllButton } from 'scenerystack/scenery-phet';

class CoolingCupScreenView extends ScreenView {
  public constructor( model: CoolingCupModel, providedOptions: ScreenViewOptions ) {
    super( providedOptions );

    const chartTransform = new ChartTransform( {
      viewWidth: 500,
      viewHeight: 250,
      modelXRange: new Range( 0, 120 ),   // seconds
      modelYRange: new Range( 20, 100 )   // degrees Celsius
    } );

    const chartRectangle = new ChartRectangle( chartTransform, {
      fill: 'white',
      stroke: 'black'
    } );

    const temperaturePlot = new LinePlot( chartTransform, model.dataSetProperty.value, {
      stroke: 'orangered',
      lineWidth: 2
    } );
    model.dataSetProperty.link( dataSet => temperaturePlot.setDataSet( dataSet ) );

    const xAxis = new AxisLine( chartTransform, Orientation.HORIZONTAL, { value: 20 } );
    const yAxis = new AxisLine( chartTransform, Orientation.VERTICAL, { value: 0 } );
    const horizontalGridLines = new GridLineSet( chartTransform, Orientation.VERTICAL, 20, { stroke: 'lightGray' } );
    const xTickLabels = new TickLabelSet( chartTransform, Orientation.HORIZONTAL, 20, { edge: 'min' } );

    // Description content derived from the SAME dataSetProperty the plot renders from,
    // so the two can never drift apart - see Accessible Descriptions for Charts and Graphs.
    const chartDescriptionProperty = new DerivedProperty(
      [ model.dataSetProperty ],
      dataSet => {
        const first = dataSet[ 0 ];
        const last = dataSet[ dataSet.length - 1 ];
        return StringUtils.fillIn(
          'Temperature is falling, from {{start}} to {{current}} degrees Celsius over {{seconds}} seconds.', {
            start: first.y.toFixed( 0 ),
            current: last.y.toFixed( 0 ),
            seconds: last.x.toFixed( 0 )
          }
        );
      }
    );

    const chartNode = new Node( {
      children: [ chartRectangle, horizontalGridLines, xAxis, yAxis, temperaturePlot, xTickLabels ],
      tagName: 'div',
      labelTagName: 'h3',
      labelContent: 'Coffee Temperature Over Time',
      descriptionContent: chartDescriptionProperty,
      center: this.layoutBounds.center
    } );

    const temperatureReadout = new Text( '', { font: '20px sans-serif' } );
    model.temperatureProperty.link( temperature => {
      temperatureReadout.string = `${temperature.toFixed( 1 )} °C`;
    } );
    temperatureReadout.left = chartNode.left;
    temperatureReadout.bottom = chartNode.top - 10;

    const resetAllButton = new ResetAllButton( {
      listener: () => model.reset(),
      right: this.layoutBounds.maxX - 20,
      bottom: this.layoutBounds.maxY - 20,
      tandem: this.tandem.createTandem( 'resetAllButton' )
    } );

    this.children = [ temperatureReadout, chartNode, resetAllButton ];
    this.pdomOrder = [ chartNode, resetAllButton ];
  }
}
```

A few things worth noticing:

| Piece | Why it's there |
| --- | --- |
| `dataSetProperty` reassigned (not mutated) every step | The only thing that makes both `temperaturePlot` and `chartDescriptionProperty` redraw/recompute automatically |
| `chartDescriptionProperty` derives from `dataSetProperty` | Same source data as the plot itself — the description can never say something the chart doesn't show, following [Accessible Descriptions for Charts and Graphs](/accessibility/accessible-descriptions-for-charts-and-graphs) |
| `xAxis` pinned at `value: 20` | Since `modelYRange` starts at `20`, not `0`, drawing the x axis at the *true* y-origin (`0`) would put it off-chart — see the `value`-is-on-the-opposite-axis note in [AxisLine and AxisArrowNode](/api/bamboo/axis-nodes) |
| `chartNode.tagName = 'div'` with `labelTagName`/`descriptionContent` | The chart's whole visual (background, gridlines, plot, ticks) is grouped as one PDOM node — a screen reader encounters "Coffee Temperature Over Time" plus the trend sentence, not each drawn Path individually |

## Wiring the Screen and Sim

```ts
import { Sim, Screen, onReadyToLaunch } from 'scenerystack/sim';
import { Property } from 'scenerystack/axon';
import { Tandem } from 'scenerystack/tandem';

const screenTandem = Tandem.ROOT.createTandem( 'coolingCupScreen' );

const coolingCupScreen = new Screen(
  () => new CoolingCupModel( screenTandem.createTandem( 'model' ) ),
  model => new CoolingCupScreenView( model, { tandem: screenTandem.createTandem( 'view' ) } ),
  {
    name: new Property( 'Cooling Cup' ),
    backgroundColorProperty: new Property( 'white' ),
    tandem: screenTandem
  }
);

onReadyToLaunch( () => {
  const sim = new Sim( new Property( 'Chart Demo' ), [ coolingCupScreen ] );
  sim.start();
} );
```

::: tip Reassign, don't mutate, any Property holding an array or object
This example's most important detail is easy to miss: `model.dataSetProperty.value = [ ...oldArray, newSample ]` fires listeners; `model.dataSetProperty.value.push( newSample )` does not. Every downstream consumer here — the `LinePlot`, the `DerivedProperty` feeding the chart's description — depends on the reassignment, not just the array's contents changing.
:::

## Where to go next

- [ChartTransform](/api/bamboo/chart-transform) — the coordinate-mapping object every piece above shares
- [GridLineSet, TickMarkSet, and TickLabelSet](/api/bamboo/gridlines-and-tick-marks) — more on the repeating-decoration primitives used here
- [Accessible Descriptions for Charts and Graphs](/accessibility/accessible-descriptions-for-charts-and-graphs) — the general pattern this example's `chartDescriptionProperty` follows
- [Demo Simulation Walkthrough](/examples/demo-simulation-walkthrough) — the same model/view/Screen/Sim shape without a chart


========================================================================
Page: A Full Accessible Multi-Screen Sim
URL: https://veillette.github.io/Almanach/examples/full-accessible-multi-screen-sim
Source: docs/examples/full-accessible-multi-screen-sim.md
Category: Examples | Tags: example, accessibility, joist, pdom, voicing, multi-screen | Status: verified
========================================================================

# A Full Accessible Multi-Screen Sim

[Building a Two-Screen Simulation](/examples/building-a-two-screen-simulation) covers how to structure independent model/view code across screens; [Accessible Control Panel Example](/examples/accessible-control-panel-example) covers labeling and focus order for one panel of controls. This page doesn't repeat either — it's about the layer that has to run through *both screens of that structure at once*: making every screen keyboard-navigable and voiced from the moment its `ScreenView` is written, not as a pass applied after the visuals are "done."

The reason this has to be designed in, not bolted on, is structural: `ScreenView` itself reserves the accessibility shape for you (see below), and retrofitting a screen that was built pointer-only usually means restructuring its listeners anyway — see [Migrating a Legacy Sim to RichDragListener](/examples/migrating-to-rich-drag-listener) for exactly how much rework that retrofit costs.

## The structural hook: every ScreenView already has a PDOM shape

`ScreenView` (from `scenerystack/sim`) builds its own PDOM scaffold in its constructor: an `<h1>` title, a `ScreenSummaryNode`, and two protected organizing Nodes — `pdomPlayAreaNode` and `pdomControlAreaNode` — always in that order, on every screen of every sim. This is why `ScreenView` **throws** if you call `pdomOrder` on it directly: the real per-screen accessible order goes on those two Nodes instead, from inside your `ScreenView` subclass (they're `protected`, so only reachable there):

```ts
import { ScreenView, type ScreenViewOptions } from 'scenerystack/sim';

class MotionScreenView extends ScreenView {
  public constructor( model: MotionModel, providedOptions: ScreenViewOptions ) {
    super( providedOptions );

    // ... build ballNode, controlPanel, resetAllButton (below) ...

    // Order content WITHIN the play area and control area, not on `this`.
    this.pdomPlayAreaNode.pdomOrder = [ ballNode ];
    this.pdomControlAreaNode.pdomOrder = [ controlPanel, resetAllButton ];
  }
}
```

Because every screen is forced through the same two buckets, a keyboard/screen-reader user gets the same top-level heading structure ("Play Area", then "Control Area") no matter which screen they're on — a consistency the sim author doesn't have to design, only populate correctly per screen.

## Screen 1: "Motion" — an accessible, voiced draggable

The model is an ordinary `positionProperty`; nothing about the model changes for accessibility — only the view:

```ts
// MotionModel.ts
import { Vector2Property, Vector2, Bounds2 } from 'scenerystack/dot';
import { Property } from 'scenerystack/axon';
import { Tandem } from 'scenerystack/tandem';

export default class MotionModel {
  public readonly positionProperty: Vector2Property;
  public readonly dragBoundsProperty: Property<Bounds2>;

  public constructor( tandem: Tandem ) {
    this.positionProperty = new Vector2Property( new Vector2( 0, 0 ), {
      tandem: tandem.createTandem( 'positionProperty' )
    } );
    this.dragBoundsProperty = new Property( new Bounds2( -200, -150, 200, 150 ) );
  }

  public reset(): void {
    this.positionProperty.reset();
  }
}
```

The view wires `RichDragListener` (pointer + keyboard in one declaration — see [Drag Listeners](/patterns/drag-listeners)), the PDOM options that make the ball focusable and named, and `Voicing` so the same interaction is *spoken* when the user has that feature enabled (see [Voicing](/accessibility/voicing)):

```ts
// BallNode.ts
import { Circle, RichDragListener, Voicing } from 'scenerystack/scenery';
import type MotionModel from './MotionModel';

export default class BallNode extends Voicing( Circle ) {
  public constructor( model: MotionModel ) {
    super( 20, {
      fill: 'steelblue',
      cursor: 'pointer',

      // PDOM: focusable and named from the start, not added once dragging "works"
      tagName: 'div',
      focusable: true,
      accessibleName: 'Ball',
      accessibleHelpText: 'Move with arrow keys, or drag with a mouse or touch.',

      // Voicing: spoken automatically on focus, once the user enables Voicing
      voicingNameResponse: 'Ball',
      voicingHintResponse: 'Move with arrow keys, or drag with a mouse or touch.'
    } );

    model.positionProperty.link( position => {
      this.translation = position;
    } );

    this.addInputListener( new RichDragListener( {
      positionProperty: model.positionProperty,
      dragBoundsProperty: model.dragBoundsProperty,
      end: () => {
        if ( !model.dragBoundsProperty.value.containsPoint( model.positionProperty.value ) ) {
          // Announced immediately, regardless of where focus currently is —
          // see /accessibility/describing-dynamic-state
          this.addAccessibleResponse( 'Boundary reached.' );
        }
      }
    } ) );
  }
}
```

`RichDragListener` is what makes both halves of this one declaration: without it, pointer dragging would work immediately but the ball would need a second, separately-maintained `KeyboardDragListener` to be reachable by keyboard at all — see [Alternative Input Overview](/accessibility/alternative-input-overview) for why that composition is possible.

The `ScreenView` also supplies a `screenSummaryContent`, which feeds *both* the PDOM's screen-summary paragraph and the Voicing toolbar's "Overview"/"Details"/"Hint" buttons from the same content:

```ts
import { ScreenSummaryContent } from 'scenerystack/sim';
import { DerivedProperty } from 'scenerystack/axon';
import { Property } from 'scenerystack/axon';

const positionDescriptionProperty = new DerivedProperty(
  [ model.positionProperty ],
  position => `The ball is at ${position.x.toFixed( 0 )}, ${position.y.toFixed( 0 )}.`
);

const screenSummaryContent = new ScreenSummaryContent( {
  playAreaContent: new Property( 'A ball you can move around an empty play area.' ),
  currentDetailsContent: [ positionDescriptionProperty ],
  interactionHintContent: new Property( 'Move the ball with arrow keys, or drag it with a mouse or touch.' )
} );
```

Passed as `providedOptions.screenSummaryContent` up to `super()`, this content is what a screen-reader user hears first on arriving at the screen, and what a Voicing user hears on demand — written once, for both systems.

## Screen 2: "Forces" — an accessible control panel

[Accessible Control Panel Example](/examples/accessible-control-panel-example) already builds a fully-labeled panel (slider, checkbox, radio group, reset button) with `accessibleName`/`accessibleHelpText` on every control — reuse that pattern verbatim for this screen's panel rather than duplicating it here. The only two things specific to *this* screen's accessibility layer are:

1. Ordering the panel under `pdomControlAreaNode`, alongside whatever's in the play area:

```ts
class ForcesScreenView extends ScreenView {
  public constructor( model: ForcesModel, providedOptions: ScreenViewOptions ) {
    super( providedOptions );

    const ballNode = new BallNode( model.ballModel );
    const controlPanel = createPanelContent( model, this.tandem.createTandem( 'panel' ) ); // from the panel example

    this.pdomPlayAreaNode.pdomOrder = [ ballNode ];
    this.pdomControlAreaNode.pdomOrder = [ controlPanel ];
  }
}
```

2. Giving *this* screen's `ScreenSummaryContent` a `controlAreaContent` describing the panel, since "Forces" has controls "Motion" doesn't:

```ts
const screenSummaryContent = new ScreenSummaryContent( {
  playAreaContent: new Property( 'A ball affected by the forces you configure.' ),
  controlAreaContent: new Property( 'Controls for adjusting speed, enabling gravity, and choosing the ball\'s shape.' )
} );
```

## What's threaded through every screen, and what's per-screen

| Concern | Every screen (same shape) | Per-screen (different content) |
| --- | --- | --- |
| PDOM structure | `pdomPlayAreaNode` before `pdomControlAreaNode`, forced by `ScreenView` itself | Which Nodes go in each, via that screen's own `pdomOrder` assignment |
| Focus on screen entry | The screen's `<h1>` title is focused automatically when the screen becomes visible | The title text itself, supplied via the sim's screen `name` |
| Screen summary / Voicing toolbar | Same `ScreenSummaryContent` mechanism, feeding both PDOM and Voicing | `playAreaContent`/`controlAreaContent`/`currentDetailsContent`/`interactionHintContent` strings, written per screen |
| Draggable objects | `RichDragListener` + PDOM + `Voicing` composed the same way | Which object, and what `accessibleName`/`voicingHintResponse` describes it |
| Reset | One `ResetAllButton` per screen, under that screen's own `pdomControlAreaNode` order | Which model Properties `reset()` touches |

## Testing across all screens

The checklist from [Accessible Interaction Tutorial](/guides/accessible-interaction-tutorial) and [Accessible Control Panel Example](/examples/accessible-control-panel-example) still applies *per screen*, plus two things that only show up with more than one screen:

1. **Tab from the Home screen into each screen separately.** Each screen's own PDOM tree only exists while that screen is selected — verify the tab order restarts sensibly (title, then play area, then control area) every time you switch screens, not just on the first one you happen to test.
2. **Voicing toolbar content differs per screen.** Press the Voicing toolbar's "Overview"/"Details"/"Hint" buttons on *every* screen, not just one — since `screenSummaryContent` is set per `ScreenView`, it's easy to wire it up thoroughly on the first screen built and forget it on the second.

::: warning `pdomOrder` cannot be set on `ScreenView` itself
`ScreenView.setPDOMOrder()` throws — the real per-screen order goes on the protected `pdomPlayAreaNode`/`pdomControlAreaNode` members instead, set from within your `ScreenView` subclass's own constructor. This is what guarantees every screen in every sim gets the same top-level heading structure for screen readers.
:::

## Where to go next

- [Building a Two-Screen Simulation](/examples/building-a-two-screen-simulation) — the model/view structure this page's accessibility layer runs through
- [Accessible Control Panel Example](/examples/accessible-control-panel-example) — the full panel-labeling pattern reused by the "Forces" screen
- [Migrating a Legacy Sim to RichDragListener](/examples/migrating-to-rich-drag-listener) — what it costs to retrofit a pointer-only screen instead of building it accessible from the start
- [The Parallel DOM (PDOM)](/accessibility/pdom) — the option reference behind `accessibleName`/`accessibleHelpText`/`descriptionContent`
- [Voicing](/accessibility/voicing) — the four response categories used on `BallNode` above
- [Describing Dynamic State](/accessibility/describing-dynamic-state) — the derived-Property pattern behind `positionDescriptionProperty` and `addAccessibleResponse`


========================================================================
Page: A Game-Style Sim with Vegas Scoring
URL: https://veillette.github.io/Almanach/examples/game-style-sim-with-vegas-scoring
Source: docs/examples/game-style-sim-with-vegas-scoring.md
Category: Examples | Tags: example, vegas, LevelSelectionButton, ScoreDisplayNumberAndStar, GameAudioPlayer, AllLevelsCompletedNode, game | Status: complete
========================================================================

# A Game-Style Sim with Vegas Scoring

`vegas` (`scenerystack/vegas`) supplies the recurring pieces of a PhET-style game: a level-selection screen, a score display, standard game-feedback sounds, and an end-of-game dialog. Each is documented individually in `api/vegas/`; this page combines four of them — [`LevelSelectionButton`](/api/vegas/level-selection-button), [`ScoreDisplayNumberAndStar`](/api/vegas/score-display-number-and-star), [`GameAudioPlayer`](/api/vegas/game-audio-player), and [`AllLevelsCompletedNode`](/api/vegas/all-levels-completed-node) — into one minimal two-level game: a level-selection grid, a trivial "answer correctly" challenge per level, and a completion dialog once every level's been played.

## The model: per-level scores plus overall progress

```ts
import { NumberProperty, BooleanProperty, DerivedProperty, type TReadOnlyProperty } from 'scenerystack/axon';
import { Tandem } from 'scenerystack/tandem';

class GameModel {
  public static readonly NUMBER_OF_LEVELS = 2;
  public static readonly PERFECT_SCORE = 3;

  public readonly levelScoreProperties: NumberProperty[];
  public readonly allLevelsCompletedProperty: TReadOnlyProperty<boolean>;
  private readonly levelCompletedProperties: BooleanProperty[];

  public constructor( tandem: Tandem ) {
    this.levelScoreProperties = [];
    this.levelCompletedProperties = [];

    for ( let level = 1; level <= GameModel.NUMBER_OF_LEVELS; level++ ) {
      const levelTandem = tandem.createTandem( `level${level}` );
      this.levelScoreProperties.push( new NumberProperty( 0, {
        tandem: levelTandem.createTandem( 'scoreProperty' )
      } ) );
      this.levelCompletedProperties.push( new BooleanProperty( false, {
        tandem: levelTandem.createTandem( 'completedProperty' )
      } ) );
    }

    this.allLevelsCompletedProperty = DerivedProperty.and( this.levelCompletedProperties );
  }

  public answerCorrectly( levelIndex: number ): void {
    const scoreProperty = this.levelScoreProperties[ levelIndex ];
    scoreProperty.value = Math.min( scoreProperty.value + 1, GameModel.PERFECT_SCORE );
    if ( scoreProperty.value === GameModel.PERFECT_SCORE ) {
      this.levelCompletedProperties[ levelIndex ].value = true;
    }
  }

  public reset(): void {
    this.levelScoreProperties.forEach( property => property.reset() );
    this.levelCompletedProperties.forEach( property => property.reset() );
  }
}
```

## The level-selection screen

Rather than one bespoke button per level, build a row of `LevelSelectionButton`s from the model's arrays — each wired to its own `scoreProperty` and displaying it with the compact [`ScoreDisplayNumberAndStar`](/api/vegas/score-display-number-and-star):

```ts
import { ScreenView, type ScreenViewOptions } from 'scenerystack/sim';
import { HBox, Text, Node } from 'scenerystack/scenery';
import { LevelSelectionButton, ScoreDisplayNumberAndStar, AllLevelsCompletedNode } from 'scenerystack/vegas';

class GameScreenView extends ScreenView {
  private readonly levelSelectionNode: Node;
  private readonly challengeNode: Node;
  private readonly allLevelsCompletedNode: AllLevelsCompletedNode;

  public constructor( model: GameModel, providedOptions: ScreenViewOptions ) {
    super( providedOptions );

    const levelButtons = model.levelScoreProperties.map( ( scoreProperty, levelIndex ) =>
      new LevelSelectionButton( new Text( `${levelIndex + 1}`, { font: '32px sans-serif' } ), scoreProperty, {
        buttonWidth: 120,
        buttonHeight: 120,
        createScoreDisplay: score => new ScoreDisplayNumberAndStar( score ),
        listener: () => this.showChallenge( levelIndex ),
        tandem: this.tandem.createTandem( `level${levelIndex + 1}Button` )
      } )
    );

    this.levelSelectionNode = new HBox( {
      spacing: 20,
      children: levelButtons,
      center: this.layoutBounds.center
    } );

    // A stand-in "challenge" view - in a real game this would be the actual question UI.
    this.challengeNode = new Node( { visible: false } );

    // Shown once model.allLevelsCompletedProperty flips true - see the .link() call below.
    this.allLevelsCompletedNode = new AllLevelsCompletedNode( () => {
      this.allLevelsCompletedNode.visible = false;
      this.levelSelectionNode.visible = true;
    }, {
      center: this.layoutBounds.center,
      visible: false
    } );

    this.children = [ this.levelSelectionNode, this.challengeNode, this.allLevelsCompletedNode ];

    model.allLevelsCompletedProperty.link( allCompleted => {
      if ( allCompleted ) {
        this.levelSelectionNode.visible = false;
        this.allLevelsCompletedNode.visible = true;
      }
    } );
  }

  private showChallenge( levelIndex: number ): void {
    this.levelSelectionNode.visible = false;
    this.challengeNode.visible = true;
    // ...build/show the actual per-level challenge here.
  }
}
```

## Wiring GameAudioPlayer to the standard game moments

[`GameAudioPlayer`](/api/vegas/game-audio-player) supplies the shared sound vocabulary for a game's feedback moments — correct/incorrect answers and the three game-over shapes — so the model's challenge-resolution code plays the standard sound instead of the view constructing its own `SoundClip`s:

```ts
import { GameAudioPlayer } from 'scenerystack/vegas';

class ChallengeController {
  private readonly gameAudioPlayer = new GameAudioPlayer();

  public constructor( private readonly model: GameModel, private readonly levelIndex: number ) {}

  public submitAnswer( isCorrect: boolean ): void {
    if ( isCorrect ) {
      this.gameAudioPlayer.correctAnswer();
      this.model.answerCorrectly( this.levelIndex );

      const scoreProperty = this.model.levelScoreProperties[ this.levelIndex ];
      if ( scoreProperty.value === GameModel.PERFECT_SCORE ) {
        this.gameAudioPlayer.gameOverPerfectScore();
      }
    }
    else {
      this.gameAudioPlayer.wrongAnswer();
    }
  }
}
```

A single `GameAudioPlayer` instance is enough for the whole sim — its five underlying sound clips are module-level singletons (see [`GameAudioPlayer`](/api/vegas/game-audio-player#a-minimal-example)), so there's no benefit to constructing more than one.

## Wiring the Screen and Sim

```ts
import { Sim, Screen, onReadyToLaunch } from 'scenerystack/sim';
import { Property } from 'scenerystack/axon';
import { Tandem } from 'scenerystack/tandem';

const screenTandem = Tandem.ROOT.createTandem( 'gameScreen' );

const gameScreen = new Screen(
  () => new GameModel( screenTandem.createTandem( 'model' ) ),
  model => new GameScreenView( model, { tandem: screenTandem.createTandem( 'view' ) } ),
  {
    name: new Property( 'Game' ),
    backgroundColorProperty: new Property( 'white' ),
    tandem: screenTandem
  }
);

onReadyToLaunch( () => {
  const sim = new Sim( new Property( 'Vegas Game Demo' ), [ gameScreen ] );
  sim.start();
} );
```

| Piece | Role in the composition |
| --- | --- |
| One `LevelSelectionButton` per level, built from `model.levelScoreProperties` | The entry point into each level, showing its live score without the view hand-tracking button state |
| `ScoreDisplayNumberAndStar` as `createScoreDisplay` | The compact score readout fits `LevelSelectionButton`'s small footprint better than the default `ScoreDisplayStars` once more than a couple of points are possible |
| `GameAudioPlayer`, one instance, called from wherever a challenge resolves | Standard sounds for standard moments — no bespoke `SoundClip` wiring needed for the common correct/incorrect/game-over cases (see [A Sound-Rich Simulation with Tambo](/examples/sound-rich-simulation-with-tambo) for building *custom* sounds when the standard set isn't enough) |
| `AllLevelsCompletedNode`, shown/hidden manually based on `model.allLevelsCompletedProperty` | Not a `Dialog` — this example owns showing/hiding it itself, exactly as documented on the [`AllLevelsCompletedNode`](/api/vegas/all-levels-completed-node) page |

::: tip Model owns "which levels are complete," not the buttons
`model.allLevelsCompletedProperty` is a `DerivedProperty` over the model's own per-level completion state — the view only *reacts* to it (showing `AllLevelsCompletedNode`) rather than deciding for itself when the game is finished. This keeps [model-view separation](/patterns/model-view-separation) intact even though the "game is over" condition spans every level's state at once.
:::

## Where to go next

- [LevelSelectionButton](/api/vegas/level-selection-button) — the button's full option list, including `soundPlayerIndex` for per-level pitch variation
- [GameAudioPlayer](/api/vegas/game-audio-player) — the complete set of standard game sounds used above
- [AllLevelsCompletedNode](/api/vegas/all-levels-completed-node) — why it's a plain `Node`, not a `Dialog`, and what that means for ownership
- [A Sound-Rich Simulation with Tambo](/examples/sound-rich-simulation-with-tambo) — building custom sounds for interactions vegas doesn't already cover


========================================================================
Page: A PhET-iO State-Restorable Sim
URL: https://veillette.github.io/Almanach/examples/phet-io-state-restorable-sim
Source: docs/examples/phet-io-state-restorable-sim.md
Category: Examples | Tags: example, tandem, phet-io, PhetioGroup, state, persistence | Status: complete
========================================================================

# A PhET-iO State-Restorable Sim

[PhET-iO Instrumented Sim Example](/examples/phet-io-instrumented-sim-example) instruments a fixed set of `Property`s — enough for PhET-iO to read and write each one, but every piece of state there has a name and a tandem fixed at construction time. [State Persistence and Save/Restore Patterns](/patterns/state-persistence-and-save-restore-patterns) explains *why* that's the requirement for a full save/restore to work mechanically. This page goes one step further: a model where **saving and restoring the entire sim state** — including a list whose length changes at runtime — requires zero bespoke save/restore code, by following that pattern all the way through, including the one case ordinary `Property` instrumentation doesn't cover on its own: a runtime-created collection, via `PhetioGroup`.

The scenario: a simple particle-collector sim. A user can add particles (each with its own mass), toggle whether the simulation is running, and adjust a global "field strength" — and the *entire* resulting state, including however many particles currently exist, must round-trip through a PhET-iO save/restore intact.

## Every fixed piece of state is a Property

Following [State Persistence and Save/Restore Patterns](/patterns/state-persistence-and-save-restore-patterns#why-property-based-state-is-what-makes-this-mechanical), nothing here lives in a plain field:

```ts
import { NumberProperty, BooleanProperty } from 'scenerystack/axon';
import { Range } from 'scenerystack/dot';
import { Tandem } from 'scenerystack/tandem';

class FieldSettings {
  public readonly fieldStrengthProperty: NumberProperty;
  public readonly isRunningProperty: BooleanProperty;

  public constructor( tandem: Tandem ) {
    this.fieldStrengthProperty = new NumberProperty( 1, {
      range: new Range( 0, 5 ),
      tandem: tandem.createTandem( 'fieldStrengthProperty' ),
      phetioFeatured: true
    } );

    this.isRunningProperty = new BooleanProperty( false, {
      tandem: tandem.createTandem( 'isRunningProperty' ),
      phetioFeatured: true
    } );
  }

  public reset(): void {
    this.fieldStrengthProperty.reset();
    this.isRunningProperty.reset();
  }
}
```

Nothing about this differs from [PhET-iO Instrumented Sim Example](/examples/phet-io-instrumented-sim-example) — it's the baseline every instrumented model needs, restated briefly because the interesting part of this page is what comes next.

## The part fixed Properties can't cover: a runtime-created list

A user adding particles at runtime is exactly the case [PhET-iO Deep Dive](/guides/phet-io-deep-dive#the-problem-with-dynamic-elements) flags: no tandem can be assigned to "the third particle" at construction time, because there is no third particle yet at construction time. `PhetioGroup` (from `scenerystack/tandem`) is what makes this restorable anyway — it owns both creation and tandem-naming for every element it produces, and critically, the PhET-iO state engine can *re-invoke the same creation function* during a restore to rebuild however many elements existed at save time, before applying each one's saved state:

```ts
import { PhetioObject, type PhetioObjectOptions } from 'scenerystack/tandem';
import { PhetioGroup, Tandem, IOType, NumberIO } from 'scenerystack/tandem';
import { NumberProperty } from 'scenerystack/axon';

class Particle extends PhetioObject {
  public readonly massProperty: NumberProperty;

  public constructor( tandem: Tandem, initialMass: number ) {
    super( { tandem, phetioType: Particle.ParticleIO } );

    this.massProperty = new NumberProperty( initialMass, {
      tandem: tandem.createTandem( 'massProperty' )
    } );
  }

  // Delegates entirely to massProperty's own IOType - see PhET-iO Deep Dive's
  // "Authoring a custom IOType" section for when ReferenceIO is the better fit instead.
  public static readonly ParticleIO = new IOType<Particle, unknown>( 'ParticleIO', {
    valueType: Particle,
    stateSchema: {
      massProperty: NumberIO
    }
  } );
}

class ParticleCollectorModel {
  public readonly fieldSettings: FieldSettings;
  public readonly particleGroup: PhetioGroup<Particle>;

  public constructor( tandem: Tandem ) {
    this.fieldSettings = new FieldSettings( tandem.createTandem( 'fieldSettings' ) );

    this.particleGroup = new PhetioGroup(
      ( particleTandem: Tandem, initialMass: number ) => new Particle( particleTandem, initialMass ),
      [ 1 ], // default constructor arguments, used only to build the group's PhET-iO archetype
      {
        tandem: tandem.createTandem( 'particleGroup' ),
        phetioDocumentation: 'The collection of particles currently in the field.'
      }
    );
  }

  public addParticle( mass: number ): Particle {
    return this.particleGroup.createNextElement( mass );
  }

  public reset(): void {
    this.fieldSettings.reset();
    this.particleGroup.clear(); // removes every element the user created, restoring the empty starting collection
  }
}
```

`particleGroup.clear()` (or the equivalent element-by-element `disposeElement` calls, if a group needs partial clearing) belongs in `reset()` for exactly the same reason every ordinary `Property` does: without it, particles created before a reset would silently survive, contradicting the "reset means back to how the sim started" invariant from [The Reset-All Pattern](/patterns/reset-all-pattern).

## Why this combination is what makes *full* state restorable

Walk through what a PhET-iO save/restore actually needs to reproduce, and check each is covered:

| To restore... | This model provides |
| --- | --- |
| `fieldStrengthProperty`/`isRunningProperty`'s exact values | Ordinary instrumented `Property`s — restored via their built-in `IOType`s, no custom code |
| However many particles existed, each with the right mass | `particleGroup`'s saved state records the element count; the state engine re-invokes `createElement` that many times (see [how state save/restore actually works](/guides/phet-io-deep-dive#how-state-save-restore-actually-works)) *before* applying each particle's own `massProperty` state |
| Nothing left over from a previous run bleeding into a freshly-restored state | `reset()`'s `particleGroup.clear()` — restore itself also removes stale elements first, but a correct `reset()` is what keeps the *interactive* (non-PhET-iO) reset path consistent with what a state restore produces |

If `Particle` had instead been built as a plain class with a `massProperty` living in an ordinary uninstrumented array, none of this would be visible to PhET-iO at all — a save would silently omit every particle, and a restore would silently produce zero of them. The `PhetioGroup` wrapper is not an optional enhancement here; it's the specific piece that makes a *variable-length* collection round-trip at all, the same way a plain instrumented `Property` is what makes a single fixed value round-trip.

## What the sim itself does *not* need to do

Nothing shown above calls a "save" or "restore" method directly — that's deliberate. Triggering an actual state save/restore is the job of the PhET-iO wrapper suite (Studio, or a custom wrapper) driving the sim from outside via `?phetioStandalone`, not something application code inside the sim initiates itself. The work above is entirely about making sure that *when* an external save/restore happens, every piece of state — fixed or dynamic — is actually captured; see [PhET-iO Deep Dive](/guides/phet-io-deep-dive#how-state-save-restore-actually-works) for what the wrapper side of that exchange looks like.

::: tip A model is state-restorable by construction, not by a separate save/restore feature you build
Nothing in `ParticleCollectorModel` was written *for* save/restore specifically — every piece exists because it's also what the model needs for ordinary interactive use (instrumented `Property`s for PhET-iO visibility, `PhetioGroup` because particles are genuinely created at runtime, `reset()` for the ordinary reset button). Full state-restorability falls out as a consequence of following [State Persistence and Save/Restore Patterns](/patterns/state-persistence-and-save-restore-patterns) throughout, rather than being a separate feature bolted on afterward.
:::

## Where to go next

- [PhET-iO Instrumented Sim Example](/examples/phet-io-instrumented-sim-example) — the simpler, fixed-shape instrumentation case this page builds on
- [State Persistence and Save/Restore Patterns](/patterns/state-persistence-and-save-restore-patterns) — the general architecture rule this example follows end to end
- [PhET-iO Deep Dive](/guides/phet-io-deep-dive) — `PhetioGroup`/`PhetioCapsule` in full, and the mechanics of how a state save/restore actually walks the tandem tree
- [The Reset-All Pattern](/patterns/reset-all-pattern) — why `particleGroup.clear()` belongs in `reset()`, not just in a PhET-iO-specific code path


========================================================================
Page: A Sim Using Cookbook Recipes End-to-End
URL: https://veillette.github.io/Almanach/examples/sim-using-cookbook-recipes-end-to-end
Source: docs/examples/sim-using-cookbook-recipes-end-to-end.md
Category: Examples | Tags: example, cookbook, DragListener, mapPosition, SoundClip, tooltip | Status: complete
========================================================================

# A Sim Using Cookbook Recipes End-to-End

Each `cookbook/` recipe solves one narrow task in isolation. This page combines four of them into a single coherent mini-scenario, to show what composing already-documented recipes actually looks like in practice, rather than each staying a standalone snippet: a token that can be dragged within a fixed area ([bounded dragging](/cookbook/draggable-node-bounded-to-an-area)), snaps to a grid while being dragged ([grid snapping](/cookbook/snapping-a-draggable-node-to-a-grid)), plays a short sound each time it snaps into a *new* cell ([a custom sound effect on interaction](/cookbook/custom-sound-effect-on-interaction)), and shows its current grid coordinates in a small tooltip on hover ([a tooltip-style hover Node](/cookbook/tooltip-style-hover-node)).

## The model: a bounded, grid-snapped position

The model owns the token's position and the bounds it's confined to, following [model-view separation](/patterns/model-view-separation) — the grid-cell math lives here too, since "which cell is this" is model-level information the tooltip and the sound effect both need, not something the view should recompute independently:

```ts
import { Vector2Property, Vector2, Bounds2 } from 'scenerystack/dot';
import { Tandem } from 'scenerystack/tandem';

class GridTokenModel {
  public static readonly GRID_CELL_SIZE = 20;
  public static readonly PLAY_AREA_BOUNDS = new Bounds2( -100, -100, 100, 100 );

  public readonly positionProperty: Vector2Property;

  public constructor( tandem: Tandem ) {
    this.positionProperty = new Vector2Property( new Vector2( 0, 0 ), {
      validBounds: GridTokenModel.PLAY_AREA_BOUNDS,
      tandem: tandem.createTandem( 'positionProperty' )
    } );
  }

  // The cell coordinates the tooltip displays - derived from positionProperty,
  // not tracked as separate state, since it's fully determined by the position.
  public getGridCell(): Vector2 {
    const cellSize = GridTokenModel.GRID_CELL_SIZE;
    return new Vector2(
      Math.round( this.positionProperty.value.x / cellSize ),
      Math.round( this.positionProperty.value.y / cellSize )
    );
  }

  public reset(): void {
    this.positionProperty.reset();
  }
}
```

## The view: all four recipes on one Node

```ts
import { DragListener, Circle, Node, Text } from 'scenerystack/scenery';
import { roundToInterval, Vector2 } from 'scenerystack/dot';
import { Property } from 'scenerystack/axon';
import { SoundClip, soundManager } from 'scenerystack/tambo';
import { Tandem } from 'scenerystack/tandem';
import gridSnap_mp3 from './gridSnap_mp3.js';

const model = new GridTokenModel( Tandem.REQUIRED );
const cellSize = GridTokenModel.GRID_CELL_SIZE;

// --- recipe 3: a custom sound effect on interaction ---
// Registered once, up front - see Adding a Custom Sound Effect on Interaction.
const gridSnapSound = new SoundClip( gridSnap_mp3, { initialOutputLevel: 0.5 } );
soundManager.addSoundGenerator( gridSnapSound, { categoryName: 'user-interface' } );

const tokenNode = new Circle( 10, {
  fill: 'mediumseagreen',
  cursor: 'pointer'
} );

// --- recipe 4: a tooltip-style hover Node ---
// Hidden until hover; repositioned and re-worded every time it's shown.
const tooltip = new Text( '', {
  fill: 'black',
  visible: false,
  pickable: false // never lets the tooltip itself intercept pointer events
} );

function updateTooltipText(): void {
  const cell = model.getGridCell();
  tooltip.string = `Cell (${cell.x}, ${cell.y})`;
}

tokenNode.addInputListener( {
  enter: () => {
    updateTooltipText();
    tooltip.visible = true;
    tooltip.leftBottom = tokenNode.rightTop.plusXY( 4, -4 );
  },
  exit: () => {
    tooltip.visible = false;
  }
} );

model.positionProperty.link( position => {
  tokenNode.translation = position;
  if ( tooltip.visible ) {
    updateTooltipText(); // keep the tooltip's cell readout in sync while hovering AND dragging
    tooltip.leftBottom = tokenNode.rightTop.plusXY( 4, -4 );
  }
} );

// --- recipes 1 and 2: bounded dragging + grid snapping, composed on one DragListener ---
let previousCell = model.getGridCell();

tokenNode.addInputListener( new DragListener( {
  positionProperty: model.positionProperty,

  // Recipe 1: confine the token to the play area.
  dragBoundsProperty: new Property( GridTokenModel.PLAY_AREA_BOUNDS ),

  // Recipe 2: snap every candidate position to the nearest grid intersection
  // BEFORE the dragBoundsProperty clamp runs - see Snapping a Draggable Node
  // to a Grid for why mapPosition and dragBoundsProperty compose in this order.
  mapPosition: ( point: Vector2 ) => new Vector2(
    roundToInterval( point.x, cellSize ),
    roundToInterval( point.y, cellSize )
  ),

  drag: () => {
    // Recipe 3, composed with recipe 2's snapping: only play the sound on the
    // transition into a NEW cell, not on every drag event within the same cell.
    const currentCell = model.getGridCell();
    if ( !currentCell.equals( previousCell ) ) {
      gridSnapSound.play();
      previousCell = currentCell;
    }
  },

  tandem: Tandem.REQUIRED
} ) );

const sceneRoot = new Node( { children: [ tokenNode, tooltip ] } );
```

## How the four recipes actually compose

| Recipe | What it contributes here | The seam with its neighbors |
| --- | --- | --- |
| [Bounded dragging](/cookbook/draggable-node-bounded-to-an-area) | `dragBoundsProperty` keeps the token inside `PLAY_AREA_BOUNDS` | Runs *after* `mapPosition` clamps to the grid, so a snapped position just outside the play area is still pulled back in — the same ordering [Snapping a Draggable Node to a Grid](/cookbook/snapping-a-draggable-node-to-a-grid#combining-with-drag-bounds) documents |
| [Grid snapping](/cookbook/snapping-a-draggable-node-to-a-grid) | `mapPosition` rounds every candidate position to a cell | Feeds `model.getGridCell()`, which both the sound-transition check and the tooltip text depend on — grid snapping isn't just cosmetic here, it's the source of truth for "which cell is this" |
| [Sound on interaction](/cookbook/custom-sound-effect-on-interaction) | `gridSnapSound.play()`, guarded by `previousCell` | Needs the *transition* into a new cell, not every `drag` event — without grid snapping upstream, there'd be no discrete "cell" to detect a transition between |
| [Hover tooltip](/cookbook/tooltip-style-hover-node) | Shows the current cell coordinates near the token | Reads `model.getGridCell()` on both `enter` and on every `positionProperty` change while already visible, so the readout stays correct whether the pointer just arrived or the token is being dragged under an already-hovering pointer |

Notice that none of the four recipes needed to be modified to combine — each already exposed exactly the hook the others needed (`mapPosition`'s output feeding both the sound guard and the tooltip; `positionProperty` as the one shared source every consumer reads).

::: tip Composing recipes is about shared state, not shared code
The interesting part of this example isn't any single recipe — each is unchanged from its own page — it's that `model.getGridCell()` gives the sound-effect guard and the tooltip text the *same* answer to "which cell is the token in right now," computed once. Composing recipes usually means finding the one piece of derived state (here, the current cell) that several independent behaviors all need, and computing it in exactly one place.
:::

## Where to go next

- [Making Any Node Draggable and Bounded to an Area](/cookbook/draggable-node-bounded-to-an-area) — recipe 1 on its own
- [Snapping a Draggable Node to a Grid](/cookbook/snapping-a-draggable-node-to-a-grid) — recipe 2 on its own
- [Adding a Custom Sound Effect on Interaction](/cookbook/custom-sound-effect-on-interaction) — recipe 3 on its own
- [A Tooltip-Style Hover Node](/cookbook/tooltip-style-hover-node) — recipe 4 on its own
- [Drag Listeners](/patterns/drag-listeners) — the broader pattern all the dragging-related recipes specialize


========================================================================
Page: A Sound-Rich Simulation with Tambo
URL: https://veillette.github.io/Almanach/examples/sound-rich-simulation-with-tambo
Source: docs/examples/sound-rich-simulation-with-tambo.md
Category: Examples | Tags: example, tambo, SoundClip, PitchedPopGenerator, soundManager, sound | Status: complete
========================================================================

# A Sound-Rich Simulation with Tambo

[How tambo's Sound Generation Fits Together](/api/tambo/sound-generation-guide) explains the pieces individually — `soundManager`, `SoundClip`, `PitchedPopGenerator`, `sharedSoundPlayers`. This page wires several of them into one small screen at once, each covering a different *kind* of interaction, so the differences between them show up concretely rather than in isolation.

The scenario: a draggable ball on a number line, where dragging plays a pitch that tracks position, hitting either boundary plays a boundary sound, a "launch" button plays a standard UI click, and a reset plays the shared reset sound — four sound-generation techniques, one small sim.

## Enabling sound for the sim

Sound is off unless a `PreferencesModel` declares support for it — this is a `Sim`-level setting, not something each sound generator configures itself:

```ts
import { Sim, onReadyToLaunch, PreferencesModel } from 'scenerystack/sim';
import { Property } from 'scenerystack/axon';

const preferencesModel = new PreferencesModel( {
  audioOptions: {
    supportsSound: true
  }
} );
```

## The model

The ball's position is a `Vector2Property` confined to a thin horizontal strip via `validBounds` — matching the shape `DragListener`/`RichDragListener` expect (see [Drag Listeners](/patterns/drag-listeners)), even though only the x-coordinate is actually meaningful here:

```ts
import { Vector2Property, Vector2, Bounds2 } from 'scenerystack/dot';
import { Tandem } from 'scenerystack/tandem';

class SoundDemoModel {
  public readonly positionProperty: Vector2Property;
  public static readonly DRAG_BOUNDS = new Bounds2( -200, -5, 200, 5 );

  public constructor( tandem: Tandem ) {
    this.positionProperty = new Vector2Property( new Vector2( 0, 0 ), {
      validBounds: SoundDemoModel.DRAG_BOUNDS,
      tandem: tandem.createTandem( 'positionProperty' )
    } );
  }

  public reset(): void {
    this.positionProperty.reset();
  }
}
```

## Four sound-generation techniques in one view

```ts
import { ScreenView, type ScreenViewOptions } from 'scenerystack/sim';
import { Circle, RichDragListener } from 'scenerystack/scenery';
import { RectangularPushButton } from 'scenerystack/sun';
import { ResetAllButton } from 'scenerystack/scenery-phet';
import { SoundClip, PitchedPopGenerator, soundManager } from 'scenerystack/tambo';
import { Vector2, Range } from 'scenerystack/dot';
import { Property } from 'scenerystack/axon';
import launchSound_mp3 from './launchSound_mp3.js';
import boundaryReached_mp3 from './boundaryReached_mp3.js';

class SoundDemoScreenView extends ScreenView {
  public constructor( model: SoundDemoModel, providedOptions: ScreenViewOptions ) {
    super( providedOptions );

    // 1. sharedSoundPlayers - the standard, reused-everywhere reset sound.
    //    No SoundClip/registration to write; this is already wired up sitewide.
    const resetAllButton = new ResetAllButton( {
      listener: () => model.reset(),
      right: this.layoutBounds.maxX - 20,
      bottom: this.layoutBounds.maxY - 20,
      tandem: this.tandem.createTandem( 'resetAllButton' )
    } );

    // 2. SoundClip - a one-shot custom sound tied to a specific button press.
    const launchSound = new SoundClip( launchSound_mp3, { initialOutputLevel: 0.7 } );
    soundManager.addSoundGenerator( launchSound, { categoryName: 'user-interface' } );

    const launchButton = new RectangularPushButton( {
      content: new Circle( 8, { fill: 'white' } ),
      listener: () => {
        model.positionProperty.value = Vector2.ZERO;
        launchSound.play();
      },
      centerX: this.layoutBounds.centerX,
      top: 20,
      tandem: this.tandem.createTandem( 'launchButton' )
    } );

    // 3. Another SoundClip - a boundary cue, played only on the transition INTO a boundary.
    const boundarySound = new SoundClip( boundaryReached_mp3, { initialOutputLevel: 0.6 } );
    soundManager.addSoundGenerator( boundarySound );

    const dragBounds = SoundDemoModel.DRAG_BOUNDS;
    let wasAtBoundary = false;
    model.positionProperty.link( position => {
      const isAtBoundary = position.x === dragBounds.minX || position.x === dragBounds.maxX;
      if ( isAtBoundary && !wasAtBoundary ) {
        boundarySound.play();
      }
      wasAtBoundary = isAtBoundary;
    } );

    // 4. PitchedPopGenerator - a synthesized pop whose pitch tracks the ball's position
    //    continuously while dragging, rather than one pre-recorded file per position.
    const dragPopGenerator = new PitchedPopGenerator( {
      pitchRange: new Range( 220, 880 )
    } );
    soundManager.addSoundGenerator( dragPopGenerator );

    const ballNode = new Circle( 15, {
      fill: 'cornflowerblue',
      cursor: 'pointer',
      centerY: this.layoutBounds.centerY + 60
    } );
    model.positionProperty.link( position => {
      ballNode.centerX = this.layoutBounds.centerX + position.x;
    } );

    ballNode.addInputListener( new RichDragListener( {
      positionProperty: model.positionProperty,
      dragBoundsProperty: new Property( dragBounds ),
      drag: () => {
        const relativePitch = ( model.positionProperty.value.x - dragBounds.minX ) /
                               ( dragBounds.maxX - dragBounds.minX );
        dragPopGenerator.playPop( relativePitch );
      }
    } ) );

    this.children = [ ballNode, launchButton, resetAllButton ];
    this.pdomOrder = [ launchButton, ballNode, resetAllButton ];
  }
}
```

| Technique | Trigger | Why this one, not another |
| --- | --- | --- |
| `sharedSoundPlayers.get('resetAll')` (used automatically by `ResetAllButton`) | Any reset-all action across the whole sim | Standard, sitewide interaction — reusing the shared player keeps the sound consistent with every other reset button in any PhET-style sim, with zero registration code |
| `SoundClip` (`launchSound`) | One specific button press | A single custom one-shot tied to one interaction — the ordinary case for [Adding a Custom Sound Effect on Interaction](/cookbook/custom-sound-effect-on-interaction) |
| `SoundClip` (`boundarySound`), guarded by `wasAtBoundary` | A model-state *transition*, not a continuous condition | Fires once per crossing rather than replaying on every position update while already at the boundary — the same one-shot-on-transition pattern used for a "success" chime |
| `PitchedPopGenerator` | Continuous drag, many times per second | The position varies continuously; a `SoundClip` per discrete pitch would need dozens of recorded files, where `playPop(relativePitch)` synthesizes the right pitch on demand |

## Wiring the Screen and Sim

```ts
import { Sim, Screen, onReadyToLaunch } from 'scenerystack/sim';
import { Property } from 'scenerystack/axon';
import { Tandem } from 'scenerystack/tandem';

const screenTandem = Tandem.ROOT.createTandem( 'soundDemoScreen' );

const soundDemoScreen = new Screen(
  () => new SoundDemoModel( screenTandem.createTandem( 'model' ) ),
  model => new SoundDemoScreenView( model, { tandem: screenTandem.createTandem( 'view' ) } ),
  {
    name: new Property( 'Sound Demo' ),
    backgroundColorProperty: new Property( 'white' ),
    tandem: screenTandem
  }
);

onReadyToLaunch( () => {
  const sim = new Sim( new Property( 'Sound Demo' ), [ soundDemoScreen ], { preferencesModel } );
  sim.start();
} );
```

::: tip Match the sound-generation technique to how the triggering value changes
The four techniques above aren't interchangeable by preference — they map to four different *shapes* of trigger: a reused sitewide event (`sharedSoundPlayers`), a one-off discrete event (`SoundClip`), a state transition that must not repeat while the state holds (`SoundClip` plus a guard flag), and a continuously-varying value (`PitchedPopGenerator`). Picking the wrong one for a given trigger is the most common way custom sound design in a sim ends up either silent, spammy, or needlessly bloated with recorded assets.
:::

## Where to go next

- [How tambo's Sound Generation Fits Together](/api/tambo/sound-generation-guide) — the conceptual overview this example assembles
- [Adding a Custom Sound Effect on Interaction](/cookbook/custom-sound-effect-on-interaction) — the same `SoundClip` patterns as standalone recipes
- [Sound Design](/accessibility/sound-design) — sound as a distinct accessibility channel alongside Voicing and the PDOM
- [Drag Listeners](/patterns/drag-listeners) — the `RichDragListener` wiring used for the ball above


========================================================================
Page: Accessible Control Panel Example
URL: https://veillette.github.io/Almanach/examples/accessible-control-panel-example
Source: docs/examples/accessible-control-panel-example.md
Category: Examples | Tags: example, accessibility, sun | Status: verified
========================================================================

# Accessible Control Panel Example

`sun` components come with sensible PDOM structure built in, but a *panel* of several controls still needs its own labeling, grouping, and keyboard traversal order to be genuinely accessible — those are the reader's responsibility, not something `Panel` gives you for free. This page builds one worked control panel — a slider, a checkbox, a radio button group, and a reset button — with every accessibility seam filled in.

## The model

```ts
import { NumberProperty, BooleanProperty, StringProperty } from 'scenerystack/axon';
import { Range } from 'scenerystack/dot';
import { Tandem } from 'scenerystack/tandem';

// 'circle' | 'square' are this Property's only ever-valid values (enforced at runtime by
// validValues below), but the Property itself is still typed as StringProperty (Property<string>)
// so it lines up with RectangularRadioButtonGroupItem<string> below without extra casting.
class PanelModel {
  public readonly speedProperty: NumberProperty;
  public readonly gravityEnabledProperty: BooleanProperty;
  public readonly shapeProperty: StringProperty;

  public constructor( tandem: Tandem ) {
    this.speedProperty = new NumberProperty( 1, {
      range: new Range( 0, 5 ),
      tandem: tandem.createTandem( 'speedProperty' )
    } );
    this.gravityEnabledProperty = new BooleanProperty( true, {
      tandem: tandem.createTandem( 'gravityEnabledProperty' )
    } );
    this.shapeProperty = new StringProperty( 'circle', {
      validValues: [ 'circle', 'square' ],
      tandem: tandem.createTandem( 'shapeProperty' )
    } );
  }

  public reset(): void {
    this.speedProperty.reset();
    this.gravityEnabledProperty.reset();
    this.shapeProperty.reset();
  }
}
```

## The panel content

Each control gets an `accessibleName` — the string a screen reader announces — and, where the visible label doesn't already say everything a keyboard/screen-reader user needs, `accessibleHelpText`:

```ts
import { VBox, Text } from 'scenerystack/scenery';
import { Panel } from 'scenerystack/sun';
import { HSlider, Checkbox, RectangularRadioButtonGroup, type RectangularRadioButtonGroupItem } from 'scenerystack/sun';
import { ResetAllButton } from 'scenerystack/scenery-phet';
import { Range } from 'scenerystack/dot';
import { Tandem } from 'scenerystack/tandem';

function createPanelContent( model: PanelModel, tandem: Tandem ) {

  const speedSlider = new HSlider( model.speedProperty, new Range( 0, 5 ), {
    accessibleName: 'Speed',
    accessibleHelpText: 'Adjust how fast objects move.',
    tandem: tandem.createTandem( 'speedSlider' )
  } );

  const gravityCheckbox = new Checkbox(
    model.gravityEnabledProperty,
    new Text( 'Gravity' ),
    {
      // accessibleName is inferred from the Text label here - see Checkbox's own docs -
      // but accessibleHelpText still needs to be supplied explicitly.
      accessibleHelpText: 'Toggle whether gravity pulls objects downward.',
      tandem: tandem.createTandem( 'gravityCheckbox' )
    }
  );

  const shapeItems: RectangularRadioButtonGroupItem<string>[] = [
    { value: 'circle', createNode: () => new Text( 'Circle' ) },
    { value: 'square', createNode: () => new Text( 'Square' ) }
  ];
  const shapeRadioButtonGroup = new RectangularRadioButtonGroup( model.shapeProperty, shapeItems, {
    orientation: 'horizontal',
    accessibleName: 'Object shape',
    tandem: tandem.createTandem( 'shapeRadioButtonGroup' )
  } );

  const resetAllButton = new ResetAllButton( {
    listener: () => model.reset(),
    tandem: tandem.createTandem( 'resetAllButton' )
  } );

  const content = new VBox( {
    spacing: 12,
    align: 'left',
    children: [
      new Text( 'Speed', { tagName: 'label' } ),
      speedSlider,
      gravityCheckbox,
      new Text( 'Shape', { tagName: 'label' } ),
      shapeRadioButtonGroup,
      resetAllButton
    ]
  } );

  return new Panel( content, {
    xMargin: 15,
    yMargin: 15,
    // A heading before the panel's content, so screen-reader users hear "Controls" before the individual settings.
    labelTagName: 'h3',
    labelContent: 'Controls'
  } );
}
```

## Explicit focus order

Scene-graph order determines *paint* order, which is not always the order a keyboard user should traverse controls in — set `pdomOrder` on the `ScreenView` (or any ancestor `Node`) to make the two independent, as described in [The Parallel DOM](/accessibility/pdom):

```ts
import { ScreenView, type ScreenViewOptions } from 'scenerystack/sim';

class PanelScreenView extends ScreenView {
  public constructor( model: PanelModel, providedOptions: ScreenViewOptions ) {
    super( providedOptions );

    const panel = createPanelContent( model, this.tandem.createTandem( 'panel' ) );
    panel.rightTop = this.layoutBounds.rightTop.plusXY( -20, 20 );
    this.addChild( panel );

    // speedSlider, gravityCheckbox, etc. would need to be exposed from createPanelContent
    // to be listed here explicitly; omitted controls simply follow in scene-graph order.
    this.pdomOrder = [ panel ];
  }
}
```

::: tip Every control needs BOTH a visible label and an `accessibleName`
`sun` components render a visible label (the `Text` you pass as `content`, or an adjacent `Text`) and expose an `accessibleName` to the PDOM — but these are two different things, set two different ways. `Checkbox` infers `accessibleName` from a `Text`/string-backed `content` automatically; `HSlider` and `RectangularRadioButtonGroup` do not derive their own name from anything visual and need `accessibleName` set explicitly, or a screen reader announces nothing useful when the control receives focus.
:::

::: warning `accessibleHelpText` supplements `accessibleName`, it doesn't replace it
`accessibleHelpText` is read *after* the accessible name, as supplementary guidance — a control with `accessibleHelpText` but no `accessibleName` is still poorly labeled. Set both, even when the visible label seems self-explanatory to a sighted user.
:::

## Where to go next

- [The Parallel DOM](/accessibility/pdom) — the full set of PDOM options used here
- [Checkbox](/api/sun/checkbox) — how `accessibleName` inference from a label works
- [The Reset-All Pattern](/patterns/reset-all-pattern) — why `resetAllButton` calls exactly one method
- [Demo Simulation Walkthrough](/examples/demo-simulation-walkthrough) — this panel embedded in a complete running sim


========================================================================
Page: Building a Two-Screen Simulation
URL: https://veillette.github.io/Almanach/examples/building-a-two-screen-simulation
Source: docs/examples/building-a-two-screen-simulation.md
Category: Examples | Tags: example, joist, multi-screen | Status: verified
========================================================================

# Building a Two-Screen Simulation

[Your First Simulation](/getting-started/your-first-simulation) builds one `Screen`; the moment a sim has two or more, a `HomeScreen` and screen-selector buttons appear automatically, and each `Screen` must supply icons for both. This page walks through a two-screen sim — "Intro" and "Lab" — that share a model constant and a common view convention, but otherwise have independent models and views.

The scenario: both screens show a circle whose radius is bound to a `NumberProperty`, sharing the same valid `Range`; "Lab" additionally lets the user change the circle's color, a feature "Intro" intentionally omits.

## Shared code

Code used by more than one screen lives in its own module, imported by both — it is not a third "shared screen":

```ts
// SharedConstants.ts - imported by both screens, owned by neither
import { Range } from 'scenerystack/dot';

const SharedConstants = {
  RADIUS_RANGE: new Range( 10, 100 ),
  SCREEN_VIEW_BACKGROUND: 'white'
};

export default SharedConstants;
```

## The Intro screen

```ts
// IntroModel.ts
import { NumberProperty } from 'scenerystack/axon';
import { Tandem } from 'scenerystack/tandem';
import SharedConstants from './SharedConstants';

export default class IntroModel {
  public readonly radiusProperty: NumberProperty;

  public constructor( tandem: Tandem ) {
    this.radiusProperty = new NumberProperty( 30, {
      range: SharedConstants.RADIUS_RANGE,
      tandem: tandem.createTandem( 'radiusProperty' )
    } );
  }

  public reset(): void {
    this.radiusProperty.reset();
  }

  public step( dt: number ): void {
    // Intro has no time-dependent behavior.
  }
}
```

```ts
// IntroScreenView.ts
import { ScreenView, type ScreenViewOptions } from 'scenerystack/sim';
import { Circle } from 'scenerystack/scenery';
import { ResetAllButton } from 'scenerystack/scenery-phet';
import type IntroModel from './IntroModel';

export default class IntroScreenView extends ScreenView {
  public constructor( model: IntroModel, providedOptions: ScreenViewOptions ) {
    super( providedOptions );

    const circle = new Circle( model.radiusProperty.value, { fill: 'cornflowerblue' } );
    model.radiusProperty.link( radius => { circle.radius = radius; } );
    circle.center = this.layoutBounds.center;

    const resetAllButton = new ResetAllButton( {
      listener: () => model.reset(),
      right: this.layoutBounds.maxX - 20,
      bottom: this.layoutBounds.maxY - 20,
      tandem: this.tandem.createTandem( 'resetAllButton' )
    } );

    this.children = [ circle, resetAllButton ];
  }
}
```

## The Lab screen

"Lab" reuses the same `RADIUS_RANGE`, but its model additionally tracks a color, and its view adds a color control the Intro screen doesn't have:

```ts
// LabModel.ts
import { NumberProperty, StringProperty } from 'scenerystack/axon';
import { Tandem } from 'scenerystack/tandem';
import SharedConstants from './SharedConstants';

export default class LabModel {
  public readonly radiusProperty: NumberProperty;
  public readonly colorProperty: StringProperty;

  public constructor( tandem: Tandem ) {
    this.radiusProperty = new NumberProperty( 30, {
      range: SharedConstants.RADIUS_RANGE,
      tandem: tandem.createTandem( 'radiusProperty' )
    } );
    this.colorProperty = new StringProperty( 'cornflowerblue', {
      tandem: tandem.createTandem( 'colorProperty' )
    } );
  }

  public reset(): void {
    this.radiusProperty.reset();
    this.colorProperty.reset();
  }

  public step( dt: number ): void {
    // Lab has no time-dependent behavior either, but could.
  }
}
```

```ts
// LabScreenView.ts
import { ScreenView, type ScreenViewOptions } from 'scenerystack/sim';
import { Circle, VBox } from 'scenerystack/scenery';
import { RectangularRadioButtonGroup, type RectangularRadioButtonGroupItem } from 'scenerystack/sun';
import { ResetAllButton } from 'scenerystack/scenery-phet';
import { Text } from 'scenerystack/scenery';
import type LabModel from './LabModel';

export default class LabScreenView extends ScreenView {
  public constructor( model: LabModel, providedOptions: ScreenViewOptions ) {
    super( providedOptions );

    const circle = new Circle( model.radiusProperty.value, { fill: model.colorProperty.value } );
    model.radiusProperty.link( radius => { circle.radius = radius; } );
    model.colorProperty.link( color => { circle.fill = color; } );
    circle.center = this.layoutBounds.center;

    const colorItems: RectangularRadioButtonGroupItem<string>[] = [
      { value: 'cornflowerblue', createNode: () => new Text( 'Blue' ) },
      { value: 'orangered', createNode: () => new Text( 'Red' ) }
    ];
    const colorRadioButtonGroup = new RectangularRadioButtonGroup( model.colorProperty, colorItems, {
      orientation: 'horizontal',
      tandem: this.tandem.createTandem( 'colorRadioButtonGroup' )
    } );

    const resetAllButton = new ResetAllButton( {
      listener: () => model.reset(),
      tandem: this.tandem.createTandem( 'resetAllButton' )
    } );

    const controls = new VBox( {
      spacing: 15,
      children: [ colorRadioButtonGroup, resetAllButton ],
      right: this.layoutBounds.maxX - 20,
      bottom: this.layoutBounds.maxY - 20
    } );

    this.children = [ circle, controls ];
  }
}
```

## Wiring both Screens and the Sim

Each `Screen` needs its own `Tandem` subtree, its own `homeScreenIcon`/`navigationBarIcon`, and a translated `name`:

```ts
import { Sim, Screen, ScreenIcon, onReadyToLaunch } from 'scenerystack/sim';
import { Property } from 'scenerystack/axon';
import { Rectangle } from 'scenerystack/scenery';
import { Tandem } from 'scenerystack/tandem';
import IntroModel from './IntroModel';
import IntroScreenView from './IntroScreenView';
import LabModel from './LabModel';
import LabScreenView from './LabScreenView';

function createIcon( fill: string ): ScreenIcon {
  return new ScreenIcon( new Rectangle( 0, 0, 100, 100, { fill } ), {
    maxIconWidthProportion: 1,
    maxIconHeightProportion: 1
  } );
}

const introTandem = Tandem.ROOT.createTandem( 'introScreen' );
const introScreen = new Screen(
  () => new IntroModel( introTandem.createTandem( 'model' ) ),
  model => new IntroScreenView( model, { tandem: introTandem.createTandem( 'view' ) } ),
  {
    name: new Property( 'Intro' ),
    homeScreenIcon: createIcon( 'cornflowerblue' ),
    navigationBarIcon: createIcon( 'cornflowerblue' ),
    backgroundColorProperty: new Property( 'white' ),
    tandem: introTandem
  }
);

const labTandem = Tandem.ROOT.createTandem( 'labScreen' );
const labScreen = new Screen(
  () => new LabModel( labTandem.createTandem( 'model' ) ),
  model => new LabScreenView( model, { tandem: labTandem.createTandem( 'view' ) } ),
  {
    name: new Property( 'Lab' ),
    homeScreenIcon: createIcon( 'orangered' ),
    navigationBarIcon: createIcon( 'orangered' ),
    backgroundColorProperty: new Property( 'white' ),
    tandem: labTandem
  }
);

onReadyToLaunch( () => {
  const sim = new Sim( new Property( 'Two-Screen Demo' ), [ introScreen, labScreen ] );
  sim.start();
} );
```

::: warning `homeScreenIcon` and `navigationBarIcon` are optional, but the fallback is a plain colored rectangle
If you omit either icon, `Screen` synthesizes a default from `backgroundColorProperty` (a bare rectangle, no `navigationBarIcon` falls back to whatever `homeScreenIcon` resolved to) rather than throwing — so a multi-screen sim without real icons still runs, it just shows indistinguishable blank rectangles on the home screen and nav bar. Supply real icons for any sim with more than one screen so it stays usable, even though nothing enforces it for you.
:::

## What's shared vs. per-screen

| Concern | Shared | Per-screen |
| --- | --- | --- |
| `SharedConstants.RADIUS_RANGE` | Yes — both models validate against the same `Range` | — |
| Model class (`IntroModel` / `LabModel`) | No | Each screen owns its own model class and `Tandem` subtree |
| View class | No | Each screen owns its own `ScreenView` subclass |
| `ResetAllButton` wiring | Conceptually (both call `model.reset()`) | Instantiated once per screen, under that screen's own tandem |

## Where to go next

- [Demo Simulation Walkthrough](/examples/demo-simulation-walkthrough) — the same one-screen shape in more annotated detail
- [Model-View Separation](/patterns/model-view-separation) — why `SharedConstants` holds data, not behavior
- [PhET-iO Instrumented Sim Example](/examples/phet-io-instrumented-sim-example) — instrumenting a sim like this one fully


========================================================================
Page: Demo Simulation Walkthrough
URL: https://veillette.github.io/Almanach/examples/demo-simulation-walkthrough
Source: docs/examples/demo-simulation-walkthrough.md
Category: Examples | Tags: example, joist, walkthrough | Status: verified
========================================================================

# Demo Simulation Walkthrough

[Your First Simulation](/getting-started/your-first-simulation) shows the smallest possible `Sim`/`Screen`/`ScreenView` skeleton with a static `Text` node. This page walks through a slightly larger, fully working demo — a single screen with a real model, a slider-controlled view, accessibility, and a reset button — annotated section by section so you can see how the pieces named in other pages fit into one file.

The scenario: a circle whose radius is driven by a `NumberProperty`, controlled by an `HSlider`, restorable with a `ResetAllButton`, and reachable from the keyboard.

## The model

The model owns exactly one piece of state and knows nothing about scenery:

```ts
import { NumberProperty } from 'scenerystack/axon';
import { Range } from 'scenerystack/dot';
import { Tandem } from 'scenerystack/tandem';

class DemoModel {
  public readonly radiusProperty: NumberProperty;

  public constructor( tandem: Tandem ) {
    this.radiusProperty = new NumberProperty( 30, {
      range: new Range( 10, 100 ),
      tandem: tandem.createTandem( 'radiusProperty' )
    } );
  }

  public reset(): void {
    this.radiusProperty.reset();
  }

  // No time-dependent behavior in this demo, but step() is where it would go.
  public step( dt: number ): void {
    // nothing to advance
  }
}
```

This is the [model-view separation](/patterns/model-view-separation) discipline: `DemoModel` could be unit-tested with no DOM at all.

## The view

The `ScreenView` observes `radiusProperty` and lays out its controls with a `VBox`. The circle's radius is driven purely by the link — nothing else ever assigns `circle.radius` directly:

```ts
import { ScreenView, type ScreenViewOptions } from 'scenerystack/sim';
import { Circle, VBox } from 'scenerystack/scenery';
import { HSlider } from 'scenerystack/sun';
import { ResetAllButton } from 'scenerystack/scenery-phet';
import { Range } from 'scenerystack/dot';
import { Tandem } from 'scenerystack/tandem';

class DemoScreenView extends ScreenView {
  public constructor( model: DemoModel, providedOptions: ScreenViewOptions ) {
    super( providedOptions );

    // The circle is a pure function of the model - the view never writes radiusProperty.
    const circle = new Circle( model.radiusProperty.value, {
      fill: 'cornflowerblue'
    } );
    model.radiusProperty.link( radius => {
      circle.radius = radius;
    } );

    // The one place radiusProperty IS written: user interaction with the slider.
    const slider = new HSlider( model.radiusProperty, new Range( 10, 100 ), {
      accessibleName: 'Circle radius',
      tandem: this.tandem.createTandem( 'slider' )
    } );

    const resetAllButton = new ResetAllButton( {
      listener: () => model.reset(),
      tandem: this.tandem.createTandem( 'resetAllButton' )
    } );

    const controls = new VBox( {
      spacing: 15,
      children: [ slider, resetAllButton ],
      right: this.layoutBounds.maxX - 20,
      bottom: this.layoutBounds.maxY - 20
    } );

    circle.center = this.layoutBounds.center;

    this.children = [ circle, controls ];

    // Explicit PDOM traversal order: circle isn't interactive, so it's left out entirely.
    this.pdomOrder = [ slider, resetAllButton ];
  }
}
```

A few things worth noticing:

| Piece | Why it's there |
| --- | --- |
| `model.radiusProperty.link(...)` | The *only* code path that moves the circle — see [Model-View Separation](/patterns/model-view-separation) |
| `HSlider`'s second argument | The `Range`, matching the one given to `NumberProperty` — see [HSlider](/api/sun/hslider) |
| `accessibleName` on the slider | Sliders and buttons already have PDOM structure from `sun`; you only need to name them — see [The Parallel DOM](/accessibility/pdom) |
| `resetAllButton.listener` calling `model.reset()` | The [reset-all pattern](/patterns/reset-all-pattern): the button never touches Properties directly |
| `this.pdomOrder` | Explicit keyboard-traversal order, independent of scene-graph (paint) order |

## Wiring the Screen and Sim

```ts
import { Sim, Screen, onReadyToLaunch } from 'scenerystack/sim';
import { Property } from 'scenerystack/axon';
import { Tandem } from 'scenerystack/tandem';

const screenTandem = Tandem.ROOT.createTandem( 'demoScreen' );

const demoScreen = new Screen(
  () => new DemoModel( screenTandem.createTandem( 'model' ) ),
  model => new DemoScreenView( model, { tandem: screenTandem.createTandem( 'view' ) } ),
  {
    name: new Property( 'Demo' ),
    backgroundColorProperty: new Property( 'white' ),
    tandem: screenTandem
  }
);

onReadyToLaunch( () => {
  const sim = new Sim( new Property( 'Demo Simulation' ), [ demoScreen ] );
  sim.start();
} );
```

::: tip Every path from a click to a pixel change goes through a Property
Trace the demo end to end: the slider writes `radiusProperty`, the `link` callback assigns `circle.radius`, and scenery repaints. There is no code anywhere that assigns to `circle.radius` outside that one `link` — that's what makes `resetAllButton`'s single call to `model.reset()` sufficient to restore the *entire* view.
:::

## Where to go next

- [Building a Two-Screen Simulation](/examples/building-a-two-screen-simulation) — the same shape, scaled to multiple screens
- [Scenery Layout Examples](/examples/scenery-layout-examples) — more on `VBox`/`FlowBox`/`GridBox` arrangements
- [Accessible Control Panel Example](/examples/accessible-control-panel-example) — a deeper PDOM-focused control cluster
- [PhET-iO Instrumented Sim Example](/examples/phet-io-instrumented-sim-example) — instrumenting this same shape of sim fully


========================================================================
Page: Migrating a Legacy Sim to RichDragListener
URL: https://veillette.github.io/Almanach/examples/migrating-to-rich-drag-listener
Source: docs/examples/migrating-to-rich-drag-listener.md
Category: Examples | Tags: example, scenery, DragListener, RichDragListener, KeyboardDragListener, migration, accessibility | Status: verified
========================================================================

# Migrating a Legacy Sim to RichDragListener

A common maintenance task is taking a sim view written years ago — a `Node` with a plain `DragListener` and nothing else — and bringing it up to current accessibility expectations without touching the model. This page walks through exactly that migration, grounded in what `DragListener` and `RichDragListener` actually do differently per source (`scenery/js/listeners/DragListener.ts` and `scenery/js/listeners/RichDragListener.ts`), not a hypothetical API.

## Before: pointer-only DragListener

A typical older view — draggable, but with no keyboard path at all:

```ts
// LegacyBallNode.ts — pointer dragging only
import { Circle, DragListener } from 'scenerystack/scenery';
import { Tandem } from 'scenerystack/tandem';
import type BallModel from './BallModel';

export default class LegacyBallNode extends Circle {
  public constructor( model: BallModel, tandem: Tandem ) {
    super( 20, { fill: 'cornflowerblue', cursor: 'pointer' } );

    this.addInputListener( new DragListener( {
      positionProperty: model.positionProperty,
      transform: model.modelViewTransform,
      dragBoundsProperty: model.dragBoundsProperty,
      allowTouchSnag: true,
      start: () => model.userControlledProperty.set( true ),
      end: () => model.userControlledProperty.set( false ),
      tandem: tandem.createTandem( 'dragListener' )
    } ) );
  }
}
```

This works fine for a mouse or touch user. There is no way to reach `LegacyBallNode` with <kbd>Tab</kbd>, and no way to move it with the keyboard — `DragListener` only implements the pointer-facing part of `TInputListener` (`down`, `up`, `move`, `click`, …). Per the class doc comment in `DragListener.ts`, it is deliberately a `PressListener` subtype "customized for handling most drag-related listener needs" for pointer input; keyboard support was never in scope for it.

## After: RichDragListener

`RichDragListener` doesn't extend `DragListener` — per its source, it *composes* an internal `DragListener` and an internal `KeyboardDragListener` and implements `TInputListener` itself, forwarding each callback to whichever internal listener applies. Migrating means three real changes, not just a class-name swap:

```ts
// BallNode.ts — pointer + keyboard dragging
import { Circle, RichDragListener } from 'scenerystack/scenery';
import { Tandem } from 'scenerystack/tandem';
import type BallModel from './BallModel';

export default class BallNode extends Circle {
  public constructor( model: BallModel, tandem: Tandem ) {
    super( 20, {
      fill: 'cornflowerblue',
      cursor: 'pointer',

      // 1. The Node must now be reachable and identifiable in the PDOM —
      //    DragListener never needed this, because it has no keyboard path to gate.
      tagName: 'div',
      focusable: true,
      accessibleName: 'Ball'
    } );

    this.addInputListener( new RichDragListener( {

      // Shared options move up to the top level unchanged.
      positionProperty: model.positionProperty,
      transform: model.modelViewTransform,
      dragBoundsProperty: model.dragBoundsProperty,

      // 2. start/end now fire for EITHER input type - this is a behavior change,
      //    not just a rename. If start/end need to distinguish pointer from
      //    keyboard, check event.isFromPDOM() inside the callback.
      start: () => model.userControlledProperty.set( true ),
      end: () => model.userControlledProperty.set( false ),

      // 3. Listener-specific options move into namespaced sub-options instead
      //    of sitting at the top level. allowTouchSnag only means anything for
      //    pointer input, so it goes under dragListenerOptions now.
      dragListenerOptions: {
        allowTouchSnag: true
      },
      keyboardDragListenerOptions: {
        dragSpeed: 150,
        shiftDragSpeed: 50
      },

      // 4. Pass the BARE tandem, not tandem.createTandem('dragListener').
      //    RichDragListener creates its own 'dragListener' and
      //    'keyboardDragListener' child tandems internally (see below) -
      //    the old manual suffix would now double up the path.
      tandem: tandem.createTandem( 'richDragListener' )
    } ) );
  }
}
```

## What actually changes, per source

| Aspect | `DragListener` | `RichDragListener` |
| --- | --- | --- |
| Input modality | Pointer only (`Mouse`/`Touch`/`Pen`) | Pointer **and** keyboard, via one internal `DragListener` + one internal `KeyboardDragListener` |
| Relationship to `TInputListener` | Implements the pointer-relevant callbacks directly, as a `PressListener` subtype | Implements `TInputListener` itself and *forwards* every callback to whichever internal listener owns it (`keydown`/`focusin`/`focusout`/`cancel` → keyboard listener; `down`/`up`/`click`/`move`/`pointerMove` → pointer listener) |
| Node requirements | None beyond a hit-testable shape | Node must additionally be in the PDOM (`tagName`, `focusable`, an `accessibleName`) or the keyboard half never receives focus |
| Shared options | `positionProperty`, `transform`, `dragBoundsProperty`, `mapPosition`, `translateNode`, `start`/`drag`/`end` | Same names, but now apply to **both** internal listeners at once |
| Listener-specific options | Set directly (`allowTouchSnag`, `useParentOffset`, …) | Moved into `dragListenerOptions` (pointer-only options) or `keyboardDragListenerOptions` (`dragSpeed`, `dragDelta`, `keyboardDragDirection`, …) |
| Mutual exclusion | N/A — only one modality exists | Starting a drag via one internal listener calls `interrupt()` on the other, so a drag is never simultaneously driven by both (handled internally, not something you write) |
| `isPressedProperty` | True while the pointer drag is active | `DerivedProperty.or(...)` of both internal listeners' `isPressedProperty` — true if *either* is active |
| `hotkeys` | Not applicable | Exposes `keyboardDragListener.hotkeys` at the top level, since `RichDragListener` participates in scenery's hotkey system |
| Tandem shape | One tandem, used as-is | Split internally into `tandem.createTandem('dragListener')` and `tandem.createTandem('keyboardDragListener')` — pass the parent tandem, don't pre-suffix it |
| Disposal | `dispose()` disposes the one listener | `dispose()` disposes `isPressedProperty` plus both internal listeners |

## Checking the migration worked

Two checks catch the mistakes this migration most commonly introduces:

1. **Tab to the object.** If `BallNode` isn't reachable by keyboard, the most likely cause is a missing `tagName`/`focusable` on the Node itself — `RichDragListener` supplies the *listener* half of keyboard support, not the PDOM half.
2. **Drag with arrow keys once focused.** If focus works but arrow keys do nothing, check that `keyboardDragListenerOptions` (or the shared `positionProperty`/`transform`) reached the internal `KeyboardDragListener` — a common copy/paste mistake is leaving keyboard-only options like `dragSpeed` at the top level, where `RichDragListener`'s options type doesn't recognize them.

::: warning Don't keep a manually-suffixed tandem from the old `DragListener` call
If the legacy code passed `tandem.createTandem( 'dragListener' )` to `DragListener`, migrating to `RichDragListener` and keeping that same suffixed tandem produces a `.../dragListener/dragListener` path once `RichDragListener` adds its own child tandem. Pass the parent tandem (e.g. `tandem.createTandem( 'richDragListener' )`) and let `RichDragListener` create its own children.
:::

## Where to go next

- [Drag Listeners](/patterns/drag-listeners) — the general pattern this migration example specializes, including the full options checklist
- [RichDragListener](/api/scenery/rich-drag-listener) — full options and members reference
- [KeyboardDragListener](/api/scenery/keyboard-drag-listener) — the internal listener that supplies the new keyboard behavior
- [Alternative Input Overview](/accessibility/alternative-input-overview) — why pointer and keyboard input share one dispatch system, which is what makes this composition possible
- [The Parallel DOM (PDOM)](/accessibility/pdom) — the `tagName`/`focusable`/`accessibleName` options this migration adds to the Node


========================================================================
Page: PhET-iO Instrumented Sim Example
URL: https://veillette.github.io/Almanach/examples/phet-io-instrumented-sim-example
Source: docs/examples/phet-io-instrumented-sim-example.md
Category: Examples | Tags: example, tandem, phet-io | Status: verified
========================================================================

# PhET-iO Instrumented Sim Example

Every `Screen` in [Your First Simulation](/getting-started/your-first-simulation) already requires a `Tandem` — but a *minimally* instrumented sim and a *fully* instrumented one differ in how deliberately every piece of state, every `IOType`, and every UI control is wired into that one `Tandem` tree. This page builds a small sim end to end where every stateful `Property` and every user-facing control is instrumented, so its full state can be saved, restored, and controlled externally by the PhET-iO wrapper suite.

The scenario: a "Temperature" screen with a `NumberProperty` for the reading, a `DerivedProperty` classifying it as `'cold'`/`'warm'`/`'hot'`, and a `Checkbox` toggling whether the reading is shown in Celsius or Fahrenheit — three different instrumentation shapes in one small model.

## The Tandem tree

Every instrumented object's `Tandem` is a child of another, forming a tree that mirrors the sim's structure. Start from `Tandem.ROOT` and branch per screen, then per model/view:

```ts
import { Tandem } from 'scenerystack/tandem';

const screenTandem = Tandem.ROOT.createTandem( 'temperatureScreen' );
const modelTandem = screenTandem.createTandem( 'model' );
const viewTandem = screenTandem.createTandem( 'view' );
```

`createTandem` is idempotent for the same name — calling it twice with the same string returns the same child `Tandem`, so it's safe to derive a sub-tandem in more than one place as long as the name matches.

## The model: three kinds of instrumented state

```ts
import { NumberProperty, BooleanProperty, DerivedProperty, type TReadOnlyProperty } from 'scenerystack/axon';
import { Range } from 'scenerystack/dot';
import { StringIO, Tandem } from 'scenerystack/tandem';

type Category = 'cold' | 'warm' | 'hot';

class TemperatureModel {
  // 1. Directly-instrumented numeric state - PhET-iO can read AND write this.
  public readonly temperatureProperty: NumberProperty;

  // 2. Directly-instrumented boolean state - a user-facing toggle.
  public readonly useFahrenheitProperty: BooleanProperty;

  // 3. A read-only DERIVED value - PhET-iO can read it (for state save/restore
  //    and data logging) but never write it directly; it always tracks its dependency.
  //    Typed as TReadOnlyProperty since DerivedProperty's own generic parameters are
  //    positional per-dependency (see the DerivedProperty API page) rather than a single tuple.
  public readonly categoryProperty: TReadOnlyProperty<Category>;

  public constructor( tandem: Tandem ) {
    this.temperatureProperty = new NumberProperty( 20, {
      range: new Range( -20, 45 ),
      tandem: tandem.createTandem( 'temperatureProperty' ),
      phetioFeatured: true,
      phetioDocumentation: 'The current temperature reading, in Celsius.'
    } );

    this.useFahrenheitProperty = new BooleanProperty( false, {
      tandem: tandem.createTandem( 'useFahrenheitProperty' ),
      phetioFeatured: true,
      phetioDocumentation: 'Whether the readout is displayed in Fahrenheit instead of Celsius.'
    } );

    this.categoryProperty = new DerivedProperty(
      [ this.temperatureProperty ],
      ( temperature: number ): Category => temperature < 10 ? 'cold' : temperature < 25 ? 'warm' : 'hot',
      {
        tandem: tandem.createTandem( 'categoryProperty' ),
        phetioValueType: StringIO,
        phetioDocumentation: 'A qualitative classification of temperatureProperty, derived automatically.'
      }
    );
  }

  public reset(): void {
    this.temperatureProperty.reset();
    this.useFahrenheitProperty.reset();
    // categoryProperty needs no reset() call - it recomputes from temperatureProperty automatically.
  }
}
```

Every `Property` constructor above takes `tandem` plus documentation options; a `DerivedProperty` additionally requires `phetioValueType` the moment it's instrumented (there's no default value type PhET-iO can infer for a derived value the way `NumberProperty` defaults to `NumberIO`).

## The view: instrumenting the controls, not just the model

```ts
import { ScreenView, type ScreenViewOptions } from 'scenerystack/sim';
import { Text, VBox } from 'scenerystack/scenery';
import { Checkbox } from 'scenerystack/sun';
import { ResetAllButton } from 'scenerystack/scenery-phet';

class TemperatureScreenView extends ScreenView {
  public constructor( model: TemperatureModel, providedOptions: ScreenViewOptions ) {
    super( providedOptions );

    const readoutText = new Text( '', { font: '20px sans-serif' } );
    const updateReadout = () => {
      const celsius = model.temperatureProperty.value;
      const displayValue = model.useFahrenheitProperty.value ? celsius * 9 / 5 + 32 : celsius;
      const unit = model.useFahrenheitProperty.value ? '°F' : '°C';
      readoutText.string = `${displayValue.toFixed( 1 )}${unit} (${model.categoryProperty.value})`;
    };
    model.temperatureProperty.link( updateReadout );
    model.useFahrenheitProperty.link( updateReadout );

    const fahrenheitCheckbox = new Checkbox(
      model.useFahrenheitProperty,
      new Text( 'Show in Fahrenheit' ),
      { tandem: this.tandem.createTandem( 'fahrenheitCheckbox' ) }
    );

    const resetAllButton = new ResetAllButton( {
      listener: () => model.reset(),
      tandem: this.tandem.createTandem( 'resetAllButton' )
    } );

    this.children = [
      new VBox( {
        spacing: 15,
        align: 'left',
        center: this.layoutBounds.center,
        children: [ readoutText, fahrenheitCheckbox, resetAllButton ]
      } )
    ];
  }
}
```

`fahrenheitCheckbox` is instrumented under `this.tandem` (the *view's* tandem) even though it controls model state — the convention is that a `Property` is instrumented once, under the model, and every UI control that reads/writes it is instrumented separately, under the view, at the point it's created. PhET-iO's data stream can then distinguish "the model value changed" from "this specific control changed it."

## Wiring the Sim

```ts
import { Sim, Screen, onReadyToLaunch } from 'scenerystack/sim';
import { Property } from 'scenerystack/axon';
import { Tandem } from 'scenerystack/tandem';

const screenTandem = Tandem.ROOT.createTandem( 'temperatureScreen' );

const temperatureScreen = new Screen(
  () => new TemperatureModel( screenTandem.createTandem( 'model' ) ),
  model => new TemperatureScreenView( model, { tandem: screenTandem.createTandem( 'view' ) } ),
  {
    name: new Property( 'Temperature' ),
    backgroundColorProperty: new Property( 'white' ),
    tandem: screenTandem
  }
);

onReadyToLaunch( () => {
  const sim = new Sim( new Property( 'Temperature Demo' ), [ temperatureScreen ] );
  sim.start();
} );
```

Nothing about launching an instrumented sim differs from an uninstrumented one — instrumentation is a property of the `Tandem`s you create and pass in, not a separate mode `Sim` is put into. The same code runs identically whether or not a PhET-iO wrapper is attached; passing `?phetioStandalone` (or driving it from a PhET-iO wrapper) is what actually activates state save/restore against the tandem tree built here.

::: tip `phetioFeatured` marks what matters to PhET-iO users, not what's instrumented
Every `Property` above has a `tandem` and is therefore part of the PhET-iO API. `phetioFeatured: true` is a *further* signal: "this is one of the handful of elements a PhET-iO user is likely to want to see by default," used to build curated, filtered views of a large API surface. Don't set it on every Property reflexively — reserve it for state that's genuinely central to the sim, the same way `temperatureProperty` and `useFahrenheitProperty` are here but `categoryProperty` (purely derived, not independently controllable) is not.
:::

::: warning A `DerivedProperty` needs `phetioValueType`, a plain `NumberProperty`/`BooleanProperty` does not
`NumberProperty` and `BooleanProperty` already know their own value's `IOType` (`NumberIO`/`BooleanIO`) and set it for you. `DerivedProperty` (and plain `Property`) don't know what they'll compute ahead of time, so instrumenting one without an explicit `phetioValueType` fails validation the moment PhET-iO tries to serialize it — as shown above with `phetioValueType: StringIO` for `categoryProperty`.
:::

## Where to go next

- [Demo Simulation Walkthrough](/examples/demo-simulation-walkthrough) — the same shape without the instrumentation detail
- [DerivedProperty](/api/axon/derived-property) — more on when a derived value needs its own `IOType`
- [The Reset-All Pattern](/patterns/reset-all-pattern) — why `reset()` only needs to touch `temperatureProperty` and `useFahrenheitProperty`, not `categoryProperty`


========================================================================
Page: Scenery Layout Examples
URL: https://veillette.github.io/Almanach/examples/scenery-layout-examples
Source: docs/examples/scenery-layout-examples.md
Category: Examples | Tags: example, scenery, layout | Status: verified
========================================================================

# Scenery Layout Examples

Scenery ships two layout containers — `FlowBox` (one-dimensional, CSS-flexbox-like) and `GridBox` (two-dimensional, CSS-grid-like) — that automatically reposition their children whenever a child's bounds change, so you stop computing `x`/`y` by hand. This page works through four arrangements that come up in almost every simulation: a horizontal toolbar, a vertical control stack, a labeled settings grid, and nesting the two together.

`HBox` and `VBox` are just `FlowBox` with `orientation` fixed to `'horizontal'`/`'vertical'` — the examples below use them directly since that's what you reach for day to day, and switch to a bare `FlowBox` only when the orientation itself needs to change.

## A horizontal toolbar (HBox)

Evenly spaced buttons, vertically centered on each other regardless of individual height:

```ts
import { HBox } from 'scenerystack/scenery';
import { RectangularPushButton } from 'scenerystack/sun';
import { Text } from 'scenerystack/scenery';

const toolbar = new HBox( {
  spacing: 8,
  align: 'center',
  children: [
    new RectangularPushButton( { content: new Text( 'Undo' ) } ),
    new RectangularPushButton( { content: new Text( 'Redo' ) } ),
    new RectangularPushButton( { content: new Text( 'Clear' ) } )
  ]
} );
```

`align: 'center'` controls placement on the *cross* axis (vertical, since this box is horizontal) — every button's vertical center lines up even if one has taller content.

## A vertical control stack (VBox)

Controls of varying width, all left-aligned, with each control's own left edge sharing one column:

```ts
import { VBox } from 'scenerystack/scenery';
import { HSlider } from 'scenerystack/sun';
import { NumberProperty } from 'scenerystack/axon';
import { Range } from 'scenerystack/dot';

const speedProperty = new NumberProperty( 1, { range: new Range( 0, 5 ) } );
const volumeProperty = new NumberProperty( 0.5, { range: new Range( 0, 1 ) } );

const controlStack = new VBox( {
  spacing: 12,
  align: 'left',
  children: [
    new HSlider( speedProperty, new Range( 0, 5 ) ),
    new HSlider( volumeProperty, new Range( 0, 1 ) )
  ]
} );
```

Reordering `children`, adding, or removing an item automatically reflows everything below it — nothing needs to be repositioned by hand.

## A labeled settings grid (GridBox)

`GridBox` places each child at an explicit `row`/`column` using per-child `layoutOptions`, rather than relying purely on array order — handy for a two-column "label, control" settings form:

```ts
import { GridBox, Node, Text } from 'scenerystack/scenery';
import { Checkbox, ComboBox } from 'scenerystack/sun';
import { BooleanProperty, Property } from 'scenerystack/axon';

const soundEnabledProperty = new BooleanProperty( true );
const languageProperty = new Property( 'en' );

// The ComboBox's popup list is added here, high enough in the scene graph to avoid being clipped.
const listParent = new Node();

const settingsGrid = new GridBox( {
  xSpacing: 20,
  ySpacing: 10,
  xAlign: 'left',
  children: [
    new Text( 'Sound' , { layoutOptions: { row: 0, column: 0 } } ),
    new Checkbox( soundEnabledProperty, new Text( 'Enabled' ), { layoutOptions: { row: 0, column: 1 } } ),

    new Text( 'Language', { layoutOptions: { row: 1, column: 0 } } ),
    new ComboBox( languageProperty, [
      { value: 'en', createNode: () => new Text( 'English' ) },
      { value: 'fr', createNode: () => new Text( 'Français' ) }
    ], listParent, { layoutOptions: { row: 1, column: 1 } } )
  ]
} );
```

`listParent` itself must still be added to the scene graph as an ancestor of `settingsGrid` (see [ComboBox](/api/sun/combo-box)) — it's omitted from `settingsGrid.children` on purpose so the popup list isn't laid out as a grid cell.

Every child's `layoutOptions.row`/`layoutOptions.column` places it in the grid; `xAlign`/`yAlign` control alignment *within* each cell, and `xSpacing`/`ySpacing` control the gaps between columns/rows.

::: tip `row`/`column` live in `layoutOptions`, not on the child directly
`GridBox` reads placement from each child's `layoutOptions` object (`{ row, column, horizontalSpan, verticalSpan }`), not from a constructor argument to `GridBox` itself. Setting `someNode.layoutOptions = { row: 2, column: 0 }` after construction re-triggers layout the same way changing `children` does.
:::

## Nesting FlowBox inside GridBox

Layout containers are themselves `Node`s, so they nest freely — a common shape is a `GridBox` of labeled rows where each row's control is itself an `HBox` (e.g. a slider plus a numeric readout):

```ts
import { GridBox, HBox, VBox, Text } from 'scenerystack/scenery';
import { HSlider } from 'scenerystack/sun';
import { NumberProperty } from 'scenerystack/axon';
import { Range } from 'scenerystack/dot';

const massProperty = new NumberProperty( 50, { range: new Range( 10, 200 ) } );

const massRow = new HBox( {
  spacing: 10,
  children: [
    new HSlider( massProperty, new Range( 10, 200 ) ),
    new Text( massProperty.value.toFixed( 0 ) ) // update via massProperty.link in real code
  ]
} );

const panelContent = new VBox( {
  spacing: 15,
  align: 'left',
  children: [
    new Text( 'Mass (kg)' ),
    massRow
  ]
} );
```

Wrap the result in a [`Panel`](/api/sun/panel) to give the whole cluster a border and background, as shown in the [Accessible Control Panel Example](/examples/accessible-control-panel-example).

::: warning `resize: false` freezes a layout container's own bounds, not its children's positions
By default (`resize: true`), a `FlowBox`/`GridBox` re-runs layout whenever a child's bounds change and updates its own bounds to match. Setting `resize: false` stops it from *resizing itself* after the first layout — it still repositions children on the next explicit layout pass, so use it deliberately (e.g. to reserve a fixed footprint) rather than as a general "stop updating" switch.
:::

## Where to go next

- [The Options Pattern](/patterns/options-pattern) — how `layoutOptions` and every other options object are typed and merged
- [Panel](/api/sun/panel) — bordering a layout container's output
- [The Parallel DOM](/accessibility/pdom) — controlling *keyboard* traversal order independently of layout order
- [Accessible Control Panel Example](/examples/accessible-control-panel-example) — a full worked panel combining these layouts with PDOM


========================================================================
Page: Standalone Scenery App Example
URL: https://veillette.github.io/Almanach/examples/standalone-scenery-app-example
Source: docs/examples/standalone-scenery-app-example.md
Category: Examples | Tags: example, scenery, standalone | Status: verified
========================================================================

# Standalone Scenery App Example

`Sim`/`Screen`/`ScreenView` (from `scenerystack/sim`) are optional — `scenery` itself is a general-purpose scene graph and rendering library, usable in any web page via its own `Display` class. This is the right choice for an embedded widget, a small interactive figure, or anything that isn't a full PhET-style application with a navigation bar and a home screen. This page builds a tiny standalone app: a `Display` rooted at a single `Node`, animated on every frame, with no `Sim` anywhere.

## Creating a Display

A `Display` takes a root `Node` and produces a real `HTMLElement` (`display.domElement`) that you attach to the page yourself:

```ts
import { Display, Node, Circle } from 'scenerystack/scenery';

const rootNode = new Node();

const display = new Display( rootNode, {
  width: 640,
  height: 480,
  backgroundColor: '#222'
} );

document.body.appendChild( display.domElement );
```

Unlike a `Sim`, nothing about `Display` assumes there is only one on the page — you can create as many as you have containers for.

## Model and view, the same as any SceneryStack app

[Model-view separation](/patterns/model-view-separation) still applies outside of joist — only the application shell is gone, not the architecture:

```ts
import { NumberProperty } from 'scenerystack/axon';
import { Range } from 'scenerystack/dot';
import { Vector2 } from 'scenerystack/dot';

const angleProperty = new NumberProperty( 0, {
  range: new Range( 0, 2 * Math.PI )
} );

// The Display's own center, in its 640x480 layout - independent of rootNode's (initially empty) bounds.
const origin = new Vector2( 320, 240 );

const dot = new Circle( 8, { fill: 'orange' } );
angleProperty.link( angle => {
  dot.center = origin.plus( new Vector2( Math.cos( angle ), Math.sin( angle ) ).timesScalar( 100 ) );
} );

rootNode.addChild( dot );
rootNode.addChild( new Circle( 2, { fill: 'white', center: origin } ) ); // origin marker
```

## Driving input and animation

A standalone `Display` needs to be told explicitly to listen for input and to step forward each frame — a `Sim` normally does both of these for you:

```ts
// Connect pointer/keyboard events to the scene graph.
display.initializeEvents();

// Advance the model and repaint on every animation frame.
display.updateOnRequestAnimationFrame( dt => {
  angleProperty.value = ( angleProperty.value + dt ) % ( 2 * Math.PI );
} );
```

`updateOnRequestAnimationFrame`'s callback receives `dt` in seconds and runs *before* the display repaints that frame — it's the standalone equivalent of a model's `step( dt )` method, called once per frame instead of once per sim.

Interactive listeners work exactly as documented in [Drag Listeners](/patterns/drag-listeners) and [The Parallel DOM](/accessibility/pdom) — both are properties of `Node`/`Display`, not of `Sim`:

```ts
import { DragListener } from 'scenerystack/scenery';

dot.cursor = 'pointer';
dot.addInputListener( new DragListener( {
  useParentOffset: true,
  drag: () => { /* e.g. pause the automatic animation while dragged */ }
} ) );
```

::: tip Resize the Display yourself
A `Sim` listens for window resizes and lays out the navigation bar and current screen automatically. A standalone `Display` does not — call `display.setWidthHeight( width, height )` (or recreate the `Display` with new dimensions) from your own `resize` listener if the container can change size, otherwise content is clipped or letterboxed at whatever size the `Display` was constructed with.
:::

## Where to go next

- [Scenery Layout Examples](/examples/scenery-layout-examples) — arranging multiple Nodes inside a standalone `Display`
- [Dispose and Memory Management](/patterns/dispose-and-memory-management) — cleaning up a `Display` and its listeners if the embedding page removes it
- [Demo Simulation Walkthrough](/examples/demo-simulation-walkthrough) — the equivalent shape wrapped in a full `Sim` instead


========================================================================
Page: Three.js Integration
URL: https://veillette.github.io/Almanach/examples/three-js-integration
Source: docs/examples/three-js-integration.md
Category: Examples | Tags: example, three.js, webgl | Status: verified
========================================================================

# Three.js Integration

SceneryStack's WebGL/3D integration layer is **mobius** (`scenerystack/mobius`), a thin bridge that embeds a real `THREE.Scene`/`THREE.PerspectiveCamera`/`THREE.WebGLRenderer` (mobius re-exports `three` itself as `THREE`, so no separate `three` dependency is needed) inside a scenery `Node`, so 3D content can sit in the scene graph next to ordinary 2D controls. This page walks through the joist-integrated path: subclassing `MobiusScreenView`, which wires up an isometric 3D stage (`ThreeIsometricNode`) as part of the `ScreenView` for you.

## Subclassing MobiusScreenView

`MobiusScreenView` (exported from `scenerystack/sim`, alongside `Sim`/`Screen`/`ScreenView` — see the [warning in Your First Simulation](/getting-started/your-first-simulation)) extends `ScreenView` and creates `this.sceneNode`, a `ThreeIsometricNode` sized to the screen's `layoutBounds`. Its own `step()` re-renders the 3D stage every frame, so a subclass only needs to add THREE objects to the scene and animate them:

```ts
import { MobiusScreenView, type MobiusScreenViewOptions } from 'scenerystack/sim';
import { THREE } from 'scenerystack/mobius';
import { Vector3 } from 'scenerystack/dot';

class CubeScreenView extends MobiusScreenView {
  private readonly cube: THREE.Mesh;

  public constructor( providedOptions: MobiusScreenViewOptions ) {
    super( providedOptions );

    // this.sceneNode (a ThreeIsometricNode) and this.sceneNode.stage.threeScene
    // come from MobiusScreenView - no separate Display/renderer setup needed.
    const geometry = new THREE.BoxGeometry( 0.3, 0.3, 0.3 );
    const material = new THREE.MeshNormalMaterial();
    this.cube = new THREE.Mesh( geometry, material );
    this.sceneNode.stage.threeScene.add( this.cube );

    const light = new THREE.DirectionalLight( 0xffffff, 1 );
    light.position.set( 0, 1, 1 );
    this.sceneNode.stage.threeScene.add( light );
  }

  public override step( dt: number ): void {
    // Animate before the superclass call, which is what actually re-renders the stage.
    this.cube.rotation.x += dt;
    this.cube.rotation.y += dt * 0.6;

    super.step( dt );
  }
}
```

`ThreeIsometricNode`'s constructor also accepts a `cameraPosition` (a `Vector3`, forwarded from `MobiusScreenViewOptions.sceneNodeOptions`) if the default isometric framing doesn't suit your content:

```ts
const cubeScreen = new CubeScreenView( {
  sceneNodeOptions: {
    cameraPosition: new Vector3( 0, 0.4, 2 )
  },
  tandem: screenTandem.createTandem( 'view' )
} );
```

## Wiring it into a Screen

Otherwise, a mobius-backed screen is an ordinary `Screen` — the model doesn't need to know THREE.js exists at all:

```ts
import { Screen } from 'scenerystack/sim';
import { Property } from 'scenerystack/axon';
import { Tandem } from 'scenerystack/tandem';

class CubeModel {
  public reset(): void { /* no state in this minimal example */ }
  public step( dt: number ): void { /* handled in the view for this example */ }
}

const screenTandem = Tandem.ROOT.createTandem( 'cubeScreen' );

const cubeScreen = new Screen(
  () => new CubeModel(),
  model => new CubeScreenView( { tandem: screenTandem.createTandem( 'view' ) } ),
  {
    name: new Property( 'Cube' ),
    backgroundColorProperty: new Property( 'black' ),
    tandem: screenTandem
  }
);
```

::: tip Checked against source, not against a running sim
Every class, method, and option shown here (`MobiusScreenView.sceneNode`/`step`/`showWebGLWarning`, `ThreeIsometricNode.stage`, `ThreeStage.threeScene`, `cameraPosition` on `ThreeIsometricNodeOptions` via `ThreeStageOptions`, mobius's re-export of `three` as `THREE`, and `phet.joist.sim.dimensionProperty` feeding `MobiusScreenView.layout()`) was independently confirmed against the real `mobius`/`joist` source, not just this page's own prior claims. What hasn't been exercised is the actual rendered output in a browser — the isometric camera framing and animation timing are worth a visual check in a running sim before relying on exact values.
:::

## Where to go next

- [Your First Simulation](/getting-started/your-first-simulation) — the `Sim`/`Screen`/`ScreenView` shell this example builds on
- [Vector3](/api/dot/vector3) — the type used for 3D camera and mesh positions
- [Standalone Scenery App Example](/examples/standalone-scenery-app-example) — running scenery (and, in principle, mobius) without a `Sim` at all


========================================================================
Page: A Colorblind-Safe Palette
URL: https://veillette.github.io/Almanach/cookbook/colorblind-safe-palette
Source: docs/cookbook/colorblind-safe-palette.md
Category: Cookbook | Tags: scenery, Color, ProfileColorProperty, accessibility, styling | Status: complete
========================================================================

# A Colorblind-Safe Palette

**Task:** a sim distinguishes several categories by color alone (particle types, chart series, on/off states) and needs to stay usable for the ~8% of men and ~0.5% of women with red-green color-vision deficiency (the most common forms: deuteranopia/protanopia), without requiring a whole colorimetry background to get right.

The two practical rules that cover almost every case: **never make red vs. green the only distinguishing signal**, and **pair color with a second channel** (shape, position, a text label, a line pattern) wherever color is conveying information a user must act on. Everything below is applying those two rules through Almanach's existing color tools — [`Color`](/api/scenery/color) and [`ProfileColorProperty`](/styling/color-profiles) — not a separate palette system.

## A palette that avoids the classic failure mode

The most common colorblind-safe palette strategy is picking hues that stay separated along the blue-yellow axis (which red-green color blindness doesn't affect), rather than relying on red-vs-green separation:

```ts
// MySimColors.ts
import { ProfileColorProperty } from 'scenerystack/scenery';
import mySim from './mySim.js';

const MySimColors = {

  // A three-category palette (e.g. particle types) chosen so no two entries
  // rely on red/green alone to be told apart - blue, orange, and a distinct
  // purple remain distinguishable under deuteranopia/protanopia/tritanopia.
  categoryAColorProperty: new ProfileColorProperty( mySim, 'categoryA', {
    default: 'rgb( 0, 114, 178 )',   // blue
    projector: 'rgb( 0, 90, 140 )'
  } ),
  categoryBColorProperty: new ProfileColorProperty( mySim, 'categoryB', {
    default: 'rgb( 230, 159, 0 )',   // orange
    projector: 'rgb( 200, 130, 0 )'
  } ),
  categoryCColorProperty: new ProfileColorProperty( mySim, 'categoryC', {
    default: 'rgb( 204, 121, 167 )', // reddish-purple
    projector: 'rgb( 170, 90, 140 )'
  } )
};

export default MySimColors;
```

This is the same "one Colors file per project" pattern documented in [Color Profiles](/styling/color-profiles) — the colorblind-safe requirement changes *which* hues you pick, not the mechanism for declaring or switching them.

## Pairing color with a second channel

Wherever a color distinction is the only way a user tells two things apart, add a redundant, non-color signal alongside it:

```ts
import { Circle, Rectangle, Node, Text } from 'scenerystack/scenery';
import MySimColors from './MySimColors.js';

// Not just color - shape also differs, so the distinction survives even if
// the two fills become indistinguishable to a given viewer.
const categoryAToken = new Circle( 10, { fill: MySimColors.categoryAColorProperty } );
const categoryBToken = new Rectangle( -8, -8, 16, 16, { fill: MySimColors.categoryBColorProperty } );

// A chart legend that repeats the distinction as text, not just a color swatch.
const legendEntry = ( swatch: Node, label: string ) => {
  const swatchAndLabel = new Node( { children: [ swatch, new Text( label, { x: 20 } ) ] } );
  return swatchAndLabel;
};
```

For line charts specifically (see [LinePlot](/api/bamboo/line-plot)), pairing color with `lineDash` (a dashed vs. solid stroke) is the equivalent move — two series that are only distinguished by hue in a legend become distinguishable by dash pattern too.

## A quick checklist

| Check | Why |
| --- | --- |
| No two categories differ *only* by red vs. green | The most common color-vision deficiencies collapse exactly that distinction |
| Every color-coded distinction has a second channel (shape, position, dash pattern, text) | Redundant coding means the information survives even for a viewer who can't perceive the color difference at all |
| Palette is defined once via `ProfileColorProperty`, not inline literals | Lets an accessibility review swap the whole palette without hunting through view code — see [Color Profiles](/styling/color-profiles) |
| Checked under at least one simulation of deuteranopia/protanopia | Confirms the intended separation actually holds, rather than relying on the choice of hues alone |

::: tip Use `Color.isDarkColor`/`isLightColor` for text-on-swatch contrast, not for category separation
[`Color`](/api/scenery/color)'s luminance helpers (`Color.isDarkColor`, `Color.getLuminance`) are the right tool for "is this background dark enough that its label text should be white" — they say nothing about whether two different hues are distinguishable to a colorblind viewer, which is a separate concern from contrast against a background.
:::

::: warning This is practical guidance, not a substitute for testing with real users
The palette above follows a widely-used qualitative strategy (blue/orange/purple hues that stay separated for the common red-green deficiencies), but no fixed palette is guaranteed safe for every form and severity of color-vision deficiency. Treat it as a strong default, and verify any color-coded UI that matters with an actual colorblindness simulator or user testing before treating "colorblind-safe" as fully confirmed.
:::


========================================================================
Page: A Custom Focus Highlight Shape
URL: https://veillette.github.io/Almanach/cookbook/custom-focus-highlight-shape
Source: docs/cookbook/custom-focus-highlight-shape.md
Category: Cookbook | Tags: scenery, HighlightPath, HighlightFromNode, focus, accessibility, kite, Shape | Status: complete
========================================================================

# A Custom Focus Highlight Shape

**Task:** a focusable Node isn't rectangular (a circular token, an irregular icon), and the default bounds-based focus highlight — a rectangle sized to the Node's bounding box — looks visually wrong sitting around it.

Set the Node's `focusHighlight` option to a `HighlightPath` built from any `kite` `Shape` (or from another Node's bounds, via `HighlightFromNode`). This is the same mechanism documented in depth on [Focus Highlights](/accessibility/focus-highlights) and [Highlight Rendering](/api/scenery/highlight-rendering) — this recipe is the narrow "I just need a circular/custom-shaped highlight" version of that.

## The solution

```ts
import { Circle, HighlightPath } from 'scenerystack/scenery';
import { Shape } from 'scenerystack/kite';

const tokenNode = new Circle( 20, {
  fill: 'goldenrod',
  tagName: 'div',
  focusable: true,
  accessibleName: 'Token'
} );

// A circular highlight matching tokenNode's actual shape, instead of the
// default rectangle sized to its bounding box.
tokenNode.focusHighlight = new HighlightPath( Shape.circle( 0, 0, 26 ) );
```

`HighlightPath` draws the same two-tone outer/inner "glow" stroke as the default highlight — only the underlying `Shape` differs — so a custom highlight built this way still visually reads as "a focus highlight" and stays consistent with the rest of the application.

## Matching the highlight to a different Node than the focusable one

A common variant: the focusable Node has a larger hit area than its visible icon (for easier touch/pointer targeting), and the highlight should trace the *visible* icon, not the larger hit target. `HighlightFromNode` handles this and keeps the highlight updated automatically if that Node's bounds ever change:

```ts
import { Node, Path, HighlightFromNode } from 'scenerystack/scenery';
import { Shape } from 'scenerystack/kite';

const starShape = new Shape().moveTo( 0, -14 ).lineTo( 4, -4 ).lineTo( 14, -4 )
  .lineTo( 6, 3 ).lineTo( 9, 14 ).lineTo( 0, 7 ).lineTo( -9, 14 )
  .lineTo( -6, 3 ).lineTo( -14, -4 ).lineTo( -4, -4 ).close();

const iconNode = new Path( starShape, { fill: 'orange' } );

const draggableIcon = new Node( {
  children: [ iconNode ],
  // A larger, invisible hit target than the icon itself:
  mouseArea: iconNode.localBounds.dilated( 10 ),
  touchArea: iconNode.localBounds.dilated( 20 ),
  tagName: 'div',
  focusable: true,
  accessibleName: 'Star'
} );

draggableIcon.focusHighlight = new HighlightFromNode( iconNode );
```

## Options used here

| Option | Effect |
| --- | --- |
| `focusHighlight` | `Shape \| Node \| 'invisible' \| null` on any focusable Node; `null`/omitted uses the automatic bounds-based rectangle |
| `HighlightPath`'s `dashed` | Set `true` for PhET's convention of "this is currently being manipulated" (see [Highlight Rendering](/api/scenery/highlight-rendering)) |
| `HighlightPath`'s `outerStroke` / `innerStroke` | Override the highlight's two stroke colors, if the default theme doesn't read well against a particular background |

::: tip Reach for `HighlightFromNode` before building a raw `Shape` by hand
Most "the highlight doesn't match this Node's visual shape" cases are really "the highlight should trace a *different, already-existing* Node's bounds" (an icon smaller than its hit target) rather than a genuinely custom outline — `HighlightFromNode` covers that case with no `Shape` math at all, and keeps itself updated if that Node's bounds change later. Reach for a hand-built `Shape` (as in the circular example above) only when no existing Node's bounds already describe the outline you want.
:::

::: warning A non-rectangular highlight is a visual fix only — it doesn't change hit-testing
Setting `focusHighlight` changes what's *drawn* on focus; it has no effect on `mouseArea`/`touchArea`/pickability. If the goal is also making the effective clickable region match a custom shape (not just its highlight), that's a separate change to `mouseArea`/`touchArea` or `hitTestShape`-style Node options, not something `focusHighlight` provides.
:::


========================================================================
Page: A Custom Slider Thumb and Track
URL: https://veillette.github.io/Almanach/cookbook/custom-slider-thumb-and-track
Source: docs/cookbook/custom-slider-thumb-and-track.md
Category: Cookbook | Tags: sun, HSlider, VSlider, slider | Status: complete
========================================================================

# A Custom Slider Thumb and Track

**Task:** the default rectangular thumb and plain track of an `HSlider`/`VSlider` don't match a sim's visual style — a circular thumb, a gradient track, or icon-based thumb artwork is needed instead.

`HSlider`/`VSlider` (thin, orientation-fixed wrappers around the shared `Slider` class) accept `trackNode` and `thumbNode` options that replace the default-drawn track/thumb entirely with any `Node` you supply — you're not limited to tweaking colors on the built-in shapes.

## The solution

```ts
import { HSlider } from 'scenerystack/sun';
import { NumberProperty } from 'scenerystack/axon';
import { Range } from 'scenerystack/dot';
import { Circle, Rectangle } from 'scenerystack/scenery';
import { Tandem } from 'scenerystack/tandem';

const volumeProperty = new NumberProperty( 50, {
  range: new Range( 0, 100 )
} );

// A custom track: a thin, rounded gradient-free bar (styling only - Slider
// still handles hit-testing and positioning based on its bounds).
const customTrack = new Rectangle( 0, 0, 160, 6, {
  fill: 'lightGray',
  cornerRadius: 3
} );

// A custom thumb: a plain circle instead of the default beveled rectangle.
const customThumb = new Circle( 12, {
  fill: 'dodgerblue',
  stroke: 'black',
  lineWidth: 1,
  cursor: 'pointer'
} );

const volumeSlider = new HSlider( volumeProperty, new Range( 0, 100 ), {
  trackNode: customTrack,
  thumbNode: customThumb,
  tandem: Tandem.REQUIRED
} );
```

`Slider` takes ownership of `customTrack`'s and `customThumb`'s sizing/positioning from here on — it reads their bounds to compute track length and thumb travel, and attaches its own drag handling to `customThumb`, so you don't add input listeners to either Node yourself.

## Giving the thumb a highlighted/pressed look

The default thumb supports `thumbFill`/`thumbFillHighlighted` for pointer-over feedback; a fully custom `thumbNode` needs to implement the equivalent itself, since those two options only apply to the *default* thumb shape. Track the slider's own pressed state via the underlying `Property`-observing pattern most `sun` controls use, or layer a `PressListener`-driven highlight directly on the custom Node:

```ts
// Slider already attaches its own drag listener to customThumb, so add a
// plain hover listener alongside it rather than another PressListener
// competing to attach to the same pointer.
customThumb.addInputListener( {
  over: () => { customThumb.fill = 'royalblue'; },
  out: () => { customThumb.fill = 'dodgerblue'; }
} );
```

This is usually enough for a hover cue and avoids fighting with `Slider`'s own internal drag listener over pointer attachment (see `attach` on [`PressListener`](/api/scenery/fire-listener) for why two `attach: true` listeners on one pointer is normally avoided).

## Options used here

| Option | Effect |
| --- | --- |
| `trackNode` | Replaces the default track `Node` entirely |
| `thumbNode` | Replaces the default thumb `Node` entirely |
| `trackSize` / `thumbSize` | Only apply to the *default* track/thumb — ignored once `trackNode`/`thumbNode` is supplied, since the custom Node's own bounds determine size |
| `thumbFill` / `thumbFillHighlighted` | Also only apply to the default thumb shape |

::: tip Everything else about `HSlider` still works unchanged
Tick marks (`addMajorTick`/`addMinorTick`), `enabledRangeProperty`, and `constrainValue` all keep working normally with a custom `trackNode`/`thumbNode` — only the two Nodes' *appearance* changes, not the slider's value/range/enabled-range behavior. See [HSlider](/api/sun/hslider) for the full option set this composes with.
:::

::: warning `trackSize`'s swapped meaning still matters when picking a `VSlider` thumb/track
If you're building the vertical counterpart with [`VSlider`](/api/sun/v-slider), remember your custom `trackNode` needs to actually be tall (not wide) — `VSlider` doesn't rotate a horizontal-shaped custom track for you, it expects the `Node` you pass to already be laid out along the vertical axis.
:::


========================================================================
Page: A Resizable/Collapsible Panel
URL: https://veillette.github.io/Almanach/cookbook/resizable-collapsible-panel
Source: docs/cookbook/resizable-collapsible-panel.md
Category: Cookbook | Tags: sun, Panel, AccordionBox, BooleanProperty | Status: complete
========================================================================

# A Resizable/Collapsible Panel

**Task:** a group of controls (a settings cluster, a "graph" section) should be collapsible down to just a title bar, reclaiming screen space, while still being bordered and styled consistently with the rest of the sim's non-collapsible panels.

[`AccordionBox`](/api/sun/accordion-box) *is* the collapsible panel — it already draws its own bordered background (styled the same way [`Panel`](/api/sun/panel) is) and handles the expand/collapse interaction and layout resizing. You reach for a plain `Panel` only for a group that's never collapsible; reach for `AccordionBox` directly when collapsibility itself is the requirement, rather than trying to wrap a `Panel` in some separate show/hide mechanism.

## The solution

```ts
import { AccordionBox } from 'scenerystack/sun';
import { VBox, Text } from 'scenerystack/scenery';
import { Checkbox } from 'scenerystack/sun';
import { BooleanProperty } from 'scenerystack/axon';
import { Tandem } from 'scenerystack/tandem';

// --- model-owned state the controls act on ---
const gravityEnabledProperty = new BooleanProperty( true );
const frictionEnabledProperty = new BooleanProperty( false );

// --- the collapsible state itself is also a Property, owned externally so
// it can be read/reset alongside the rest of the screen's state ---
const isControlsExpandedProperty = new BooleanProperty( true );

const controlsContent = new VBox( {
  spacing: 8,
  align: 'left',
  children: [
    new Checkbox( gravityEnabledProperty, new Text( 'Gravity' ), { tandem: Tandem.REQUIRED } ),
    new Checkbox( frictionEnabledProperty, new Text( 'Friction' ), { tandem: Tandem.REQUIRED } )
  ]
} );

const controlsAccordionBox = new AccordionBox( controlsContent, {
  titleNode: new Text( 'Controls' ),
  expandedProperty: isControlsExpandedProperty,
  cornerRadius: 8,
  titleAlignX: 'left',
  tandem: Tandem.REQUIRED
} );
```

Clicking the title bar (or its expand/collapse button) toggles `isControlsExpandedProperty`, which collapses `controlsAccordionBox` down to just the title row — `controlsContent`'s children are hidden, not destroyed, so re-expanding shows the same live controls with no rebuilding.

## Resetting the collapsed state with the rest of the screen

Because `isControlsExpandedProperty` is supplied externally (rather than using `expandedDefaultValue`), it needs to be reset explicitly alongside the model's own Properties — `AccordionBox.reset()` is a no-op for externally-supplied Properties:

```ts
class MyScreenModel {
  public reset(): void {
    gravityEnabledProperty.reset();
    frictionEnabledProperty.reset();
  }
}

// in the ResetAllButton's listener (see The Reset-All Pattern):
resetAllButton = new ResetAllButton( {
  listener: () => {
    model.reset();
    isControlsExpandedProperty.reset(); // view-owned, but still reset with everything else
  }
} );
```

If you don't need to observe or reset the expanded state from outside, skip the external `Property` entirely and just pass `expandedDefaultValue: false` — `AccordionBox` will create and own its own `expandedProperty`, and `controlsAccordionBox.reset()` resets it for you.

## Options used here

| Option | Effect |
| --- | --- |
| `titleNode` | Node shown in the always-visible title bar |
| `expandedProperty` | Externally-owned `Property<boolean>` driving expanded/collapsed state |
| `expandedDefaultValue` | Alternative to `expandedProperty` — lets `AccordionBox` own and reset its own Property |
| `cornerRadius` / `titleAlignX` | Visual styling, matching the conventions of a plain [`Panel`](/api/sun/panel) |

::: tip Collapsed width defaults to matching the expanded width
`useExpandedBoundsWhenCollapsed` defaults to `true`, so the collapsed title bar stays exactly as wide as the box is when expanded — this keeps a column of accordion boxes (or an accordion box next to a fixed-width sibling panel) visually aligned regardless of expanded state, instead of the collapsed row shrinking to just the title text's width.
:::

::: warning Don't nest a `Panel` inside an `AccordionBox`'s content expecting a second border
`AccordionBox` already draws the same kind of bordered background `Panel` does — wrapping `controlsContent` in its own `Panel` before passing it to `AccordionBox` just produces a border-within-a-border. Pass the bare content (a `VBox`/`GridBox` of controls) directly, as shown above.
:::


========================================================================
Page: A Simple Score/Level-Selection Screen
URL: https://veillette.github.io/Almanach/cookbook/simple-score-and-level-selection-screen
Source: docs/cookbook/simple-score-and-level-selection-screen.md
Category: Cookbook | Tags: vegas, LevelSelectionButton, ScoreDisplayNumberAndStar, game, HBox | Status: complete
========================================================================

# A Simple Score/Level-Selection Screen

**Task:** a game needs a level-selection screen — a row (or grid) of buttons, one per level, each showing that level's icon and current score, that launches into the chosen level on press.

[`LevelSelectionButton`](/api/vegas/level-selection-button) (from `scenerystack/vegas`) already bundles an icon, a score display, and a level-specific sound into one `RectangularPushButton`-based Node — building a level-selection screen is mostly laying out one `LevelSelectionButton` per level in an `HBox`/`GridBox` and wiring each one's `listener` to switch levels.

## The solution

```ts
import { LevelSelectionButton, ScoreDisplayNumberAndStar } from 'scenerystack/vegas';
import { HBox, Circle, Text } from 'scenerystack/scenery';
import { NumberProperty, Property } from 'scenerystack/axon';
import { Tandem } from 'scenerystack/tandem';

const NUMBER_OF_LEVELS = 3;

// --- model: one score per level, plus which level (if any) is being played ---
const levelScoreProperties = Array.from(
  { length: NUMBER_OF_LEVELS },
  () => new NumberProperty( 0 )
);

const selectedLevelProperty = new Property<number | null>( null ); // null = on the selection screen

function createLevelIcon( levelNumber: number ): Circle {
  const colors = [ 'crimson', 'goldenrod', 'seagreen' ];
  const icon = new Circle( 24, { fill: colors[ levelNumber - 1 ] } );
  icon.addChild( new Text( `${levelNumber}`, { fill: 'white', center: icon.center } ) );
  return icon;
}

const levelSelectionButtons = levelScoreProperties.map( ( scoreProperty, index ) => {
  const levelNumber = index + 1;

  return new LevelSelectionButton( createLevelIcon( levelNumber ), scoreProperty, {
    buttonWidth: 120,
    buttonHeight: 120,
    createScoreDisplay: score => new ScoreDisplayNumberAndStar( score ),
    listener: () => {
      selectedLevelProperty.value = levelNumber;
    },
    soundPlayerIndex: index, // levels are zero-indexed and contiguous here
    tandem: Tandem.REQUIRED
  } );
} );

const levelSelectionRow = new HBox( {
  spacing: 20,
  children: levelSelectionButtons
} );
```

`levelSelectionRow` is now a complete, self-contained level-selection screen's content: pressing any button sets `selectedLevelProperty`, which the sim's top-level view uses to switch between "showing the selection screen" and "showing the chosen level" (typically the same `selectedLevelProperty === null` check, driving each level view's `visible` option or a `Node` swap).

## Returning to the selection screen and updating scores

Once a level is played, update that level's own `scoreProperty` from wherever the game logic lives, and provide a way back to `null`:

```ts
function onLevelCompleted( levelNumber: number, pointsEarned: number ): void {
  levelScoreProperties[ levelNumber - 1 ].value += pointsEarned;
  selectedLevelProperty.value = null; // back to the selection screen
}
```

Because `LevelSelectionButton` takes `scoreProperty` directly (not a snapshot), each button's score display updates automatically the next time the selection screen is shown — there's no manual refresh step.

## Options used here

| Option | Effect |
| --- | --- |
| `buttonWidth` / `buttonHeight` | Fixed size for every level button; icon and score-display area both derive from these |
| `createScoreDisplay` | Factory for the score-display Node — [`ScoreDisplayNumberAndStar`](/api/vegas/score-display-number-and-star) is a compact choice; see the [ScoreDisplay family](/api/vegas/score-display-family) for labeled-number/labeled-stars alternatives |
| `soundPlayerIndex` | Pitches the shared level-selection sound up per index, for zero-indexed contiguous levels |
| `listener` | Fired on press; the standard place to set which level is now selected |

::: tip Reach for `FiniteStatusBar` once you're inside a level, not on the selection screen itself
The level-selection screen shown here only needs `LevelSelectionButton`; once a level is actually being played, [`FiniteStatusBar`](/api/vegas/status-bars) is the standard way to show that level's own running score, "Level N" label, and a "Start Over" button pinned to the top of the `ScreenView` — a different, complementary piece from the selection screen itself.
:::

::: warning Keep the level-selection screen itself outside any one level's `Tandem` subtree
Each `LevelSelectionButton`'s tandem, and each level's own `scoreProperty`, should live under a tandem naming scheme that's stable regardless of how many levels exist or which one is currently selected (e.g. `gameScreen.model.level1.scoreProperty`) — see [Multi-Screen Sim Structure](/patterns/multi-screen-sim-structure) for the broader convention of keeping each self-contained unit under its own tandem subtree.
:::


========================================================================
Page: A Tooltip-Style Hover Node
URL: https://veillette.github.io/Almanach/cookbook/tooltip-style-hover-node
Source: docs/cookbook/tooltip-style-hover-node.md
Category: Cookbook | Tags: scenery, Node, input, tooltip | Status: complete
========================================================================

# A Tooltip-Style Hover Node

**Task:** hovering the pointer over some Node (an icon, a data point on a graph) should reveal a small info Node nearby — a label, a value readout — that disappears again once the pointer leaves.

Scenery's `enter`/`exit` input events are the right tool here rather than `over`/`out`: `enter`/`exit` fire once per subtree (when the pointer crosses into or out of the Node's bounds at all), while `over`/`out` can fire repeatedly as the pointer crosses child boundaries within the same subtree — for a single tooltip, `enter`/`exit` avoids the flicker that `over`/`out` on a Node with children can cause.

## The solution

```ts
import { Node, Circle, Text } from 'scenerystack/scenery';

const dataPoint = new Circle( 6, { fill: 'royalblue', cursor: 'pointer' } );

const tooltip = new Text( 'Value: 42', {
  fill: 'black',
  visible: false // hidden until hovered
} );

dataPoint.addInputListener( {
  enter: () => {
    tooltip.visible = true;
    tooltip.leftBottom = dataPoint.rightTop.plusXY( 4, -4 );
  },
  exit: () => {
    tooltip.visible = false;
  }
} );

// tooltip must be added high enough in the scene graph that it isn't
// clipped by dataPoint's own parent, and drawn after (on top of) neighboring
// content that might otherwise overlap it.
const sceneRoot = new Node( { children: [ /* ...other content..., */ dataPoint, tooltip ] } );
```

Positioning `tooltip` relative to `dataPoint`'s bounds (`dataPoint.rightTop`) on `enter` — rather than fixing its position once at construction — keeps it correctly placed even if `dataPoint` itself later moves (e.g. it's also draggable).

## Following the pointer instead of anchoring to the Node

For a tooltip that should track the exact hover position rather than sit in a fixed spot relative to the hovered Node (useful when the hovered Node is large, like a chart background), read the position off the event in `move` instead:

```ts
chartBackground.addInputListener( {
  enter: () => { tooltip.visible = true; },
  exit: () => { tooltip.visible = false; },
  move: event => {
    // event.pointer.point is in the global (Display root) frame; convert to
    // whatever Node's parent frame the tooltip is positioned in.
    tooltip.leftTop = sceneRoot.globalToLocalPoint( event.pointer.point ).plusXY( 12, 12 );
  }
} );
```

## Updating tooltip content dynamically

If the tooltip's text depends on what's being hovered (different data per point), rebuild or re-link its content in `enter` rather than assuming one static string:

```ts
import { PatternStringProperty, TinyProperty, NumberProperty } from 'scenerystack/axon';

const pointValueProperty = new NumberProperty( 42 );

const tooltipTextProperty = new PatternStringProperty(
  new TinyProperty( 'Value: {{value}}' ),
  { value: pointValueProperty }
);
const tooltip = new Text( tooltipTextProperty );
```

See [Placeholder Values in a Translated String](/cookbook/placeholder-values-in-a-translated-string) if the tooltip's text needs to stay translatable.

## Options and events used here

| Event | Fires |
| --- | --- |
| `enter` | Once, when the pointer moves into this Node's subtree (not re-fired for motion between children) |
| `exit` | Once, when the pointer leaves this Node's subtree entirely |
| `move` | Repeatedly while the pointer is over this Node — use only if the tooltip needs to track the exact pointer position |

::: tip Tooltips are a pointer-only convention — don't rely on them for essential information
`enter`/`exit` never fire for keyboard-driven interaction (there is no "hovering" concept for a keyboard user) — a tooltip built this way is invisible to keyboard/AT users entirely. If the tooltip's content is more than a nice-to-have, also expose it through the [Parallel DOM](/accessibility/pdom) (e.g. as part of the hovered Node's `accessibleName`/`descriptionContent`) so the same information reaches keyboard and screen-reader users. See [Detecting Touch vs. Mouse vs. Keyboard Input](/cookbook/detecting-touch-mouse-keyboard-input) for checking input modality more generally.
:::

::: warning `pickable: false` the tooltip itself
Give the tooltip Node `pickable: false` if it's positioned so it could ever overlap the hovered Node or another interactive Node — otherwise the tooltip itself can intercept pointer events (e.g. triggering its own spurious `enter`/`exit` on neighboring listeners) once it appears directly under the pointer.
:::


========================================================================
Page: Adding a Custom Sound Effect on Interaction
URL: https://veillette.github.io/Almanach/cookbook/custom-sound-effect-on-interaction
Source: docs/cookbook/custom-sound-effect-on-interaction.md
Category: Cookbook | Tags: tambo, SoundClip, soundManager, sound, RectangularPushButton | Status: complete
========================================================================

# Adding a Custom Sound Effect on Interaction

**Task:** play a short sound effect when the user presses a button, and a different one automatically whenever some model `Property` crosses into a new state — without hand-managing `AudioContext` plumbing.

Both cases use the same building block: a [`SoundClip`](/api/tambo/sound-clip) wrapping a decoded audio asset, registered once with the [`soundManager`](/api/tambo/sound-manager) singleton, then `.play()`ed from wherever the triggering event happens — a button's `listener`, or a `Property` listener.

## Playing a sound on a button press

```ts
import { SoundClip, soundManager } from 'scenerystack/tambo';
import { RectangularPushButton } from 'scenerystack/sun';
import { Text } from 'scenerystack/scenery';
import { Tandem } from 'scenerystack/tandem';
import buttonClick_mp3 from './buttonClick_mp3.js'; // a WrappedAudioBuffer from an audio asset import

const buttonClickSound = new SoundClip( buttonClick_mp3, {
  initialOutputLevel: 0.7
} );

soundManager.addSoundGenerator( buttonClickSound, {
  categoryName: 'user-interface'
} );

const launchButton = new RectangularPushButton( {
  content: new Text( 'Launch' ),
  listener: () => {
    model.launch();
    buttonClickSound.play();
  },
  tandem: Tandem.REQUIRED
} );
```

`SoundClip.play()` fires the clip as a one-shot; calling it again while a previous play is still finishing starts an overlapping instance rather than cutting the first one off, which is normally what you want for rapid button presses.

## Playing a sound on a Property change

For a sound that should follow model state rather than a specific user gesture — a "success" chime when a value enters a target range, a click each time a counter increments — link the sound to the `Property` instead of a button `listener`:

```ts
import { SoundClip, soundManager } from 'scenerystack/tambo';
import { NumberProperty } from 'scenerystack/axon';
import successChime_mp3 from './successChime_mp3.js';

const scoreProperty = new NumberProperty( 0 );
const targetScore = 100;

const successSound = new SoundClip( successChime_mp3, {
  initialOutputLevel: 0.8
} );
soundManager.addSoundGenerator( successSound );

let wasAtTarget = false;
scoreProperty.link( score => {
  const isAtTarget = score >= targetScore;
  if ( isAtTarget && !wasAtTarget ) {
    successSound.play(); // fires only on the transition into the target range
  }
  wasAtTarget = isAtTarget;
} );
```

Guarding with a `wasAtTarget` flag (rather than playing on every `link` call where `score >= targetScore`) is what makes the sound fire once on the transition, instead of replaying every time an already-high score changes slightly.

## A looping sound tied to a boolean state

A continuous sound (a motor hum, an alarm) uses `loop: true` and is started/stopped rather than played once — see [SoundClip](/api/tambo/sound-clip#a-minimal-example) for the full pattern:

```ts
const isRunningProperty = model.isRunningProperty; // a BooleanProperty
const motorHumSound = new SoundClip( motorHum_mp3, { loop: true } );
soundManager.addSoundGenerator( motorHumSound );

isRunningProperty.link( isRunning => {
  isRunning ? motorHumSound.play() : motorHumSound.stop();
} );
```

::: tip Register every sound generator once, up front
`soundManager.addSoundGenerator` should be called once per `SoundClip` at construction time, not on every play — `soundManager` handles overlapping/looping playback internally. Calling `addSoundGenerator` repeatedly on the same clip is unnecessary and will register it more than once.
:::

::: warning Sounds queued before `soundManager.initialize()` don't play until it runs
If `addSoundGenerator` is called before the sim has called `soundManager.initialize(...)`, the call is silently queued rather than dropped — but nothing plays until initialization completes. This is normally handled by sim startup code once, not per-feature, so most cookbook-level code (as above) doesn't need to worry about ordering.
:::


========================================================================
Page: Adding a Screen to an Existing Multi-Screen Sim
URL: https://veillette.github.io/Almanach/cookbook/adding-a-screen-to-an-existing-multi-screen-sim
Source: docs/cookbook/adding-a-screen-to-an-existing-multi-screen-sim.md
Category: Cookbook | Tags: joist, Screen, Sim, ScreenIcon, Tandem | Status: complete
========================================================================

# Adding a Screen to an Existing Multi-Screen Sim

**Task:** an existing multi-screen sim, already following [Multi-Screen Sim Structure](/patterns/multi-screen-sim-structure), needs one more `Screen` added — without touching the existing screens' own model/view code.

Because each screen is fully self-contained (its own model, view, and `Tandem` subtree), adding one is almost entirely additive: build the new screen's model/view/icon the same way the existing ones are built, then add exactly one entry to the array passed to `new Sim(...)`.

## The steps

**1. Create the new screen's model and view, in their own module(s) — never importing from another screen:**

```ts
// advanced2/AdvancedTwoModel.ts
class AdvancedTwoModel {
  public reset(): void { /* reset this screen's own Properties */ }
}
```

```ts
// advanced2/AdvancedTwoScreenView.ts
import { ScreenView, type ScreenViewOptions } from 'scenerystack/sim';
import { Text } from 'scenerystack/scenery';
import AdvancedTwoModel from './AdvancedTwoModel.js';

export default class AdvancedTwoScreenView extends ScreenView {
  public constructor( model: AdvancedTwoModel, providedOptions: ScreenViewOptions ) {
    super( providedOptions );
    const label = new Text( 'Advanced Two', { font: '24px sans-serif' } );
    label.center = this.layoutBounds.center;
    this.addChild( label );
  }
}
```

**2. Build a `ScreenIcon` for it** (see [Building a Custom ScreenIcon](/cookbook/building-a-custom-screen-icon) for more than a placeholder):

```ts
import { ScreenIcon } from 'scenerystack/sim';
import { Rectangle } from 'scenerystack/scenery';

function createAdvancedTwoScreenIcon(): ScreenIcon {
  return new ScreenIcon( new Rectangle( 0, 0, 10, 10, { fill: 'purple' } ) );
}
```

**3. Give the screen its own `Tandem` subtree, created from `Tandem.ROOT` exactly like the existing screens:**

```ts
import { Screen } from 'scenerystack/sim';
import { Property } from 'scenerystack/axon';
import { Tandem } from 'scenerystack/tandem';
import AdvancedTwoModel from './advanced2/AdvancedTwoModel.js';
import AdvancedTwoScreenView from './advanced2/AdvancedTwoScreenView.js';

const advancedTwoTandem = Tandem.ROOT.createTandem( 'advancedTwoScreen' );

const advancedTwoScreen = new Screen(
  () => new AdvancedTwoModel(),
  model => new AdvancedTwoScreenView( model, { tandem: advancedTwoTandem.createTandem( 'view' ) } ),
  {
    name: new Property( 'Advanced Two' ),
    homeScreenIcon: createAdvancedTwoScreenIcon(),
    backgroundColorProperty: new Property( 'white' ),
    tandem: advancedTwoTandem
  }
);
```

**4. Add exactly one entry to the array passed to `Sim`, in the position you want it to appear in the navigation bar:**

```ts
import { Sim, onReadyToLaunch } from 'scenerystack/sim';

onReadyToLaunch( () => {
  const sim = new Sim( new Property( 'My Multi-Screen Sim' ), [
    introScreen,
    advancedScreen,
    advancedTwoScreen // the new screen, appended (or inserted wherever it belongs)
  ] );
  sim.start();
} );
```

Nothing about `introScreen`/`advancedScreen`'s own code changes — `createModel`/`createView` are still called lazily by `Sim`, only when each screen is actually selected, so adding a third screen doesn't add startup cost to the existing two.

## What to double-check afterward

| Check | Why |
| --- | --- |
| The new screen's tandem name is unique and doesn't collide with an existing one | `Tandem.createTandem` on an already-used name reuses the existing child rather than erroring loudly in every case — a typo'd duplicate name can silently misname the new screen's tree |
| `homeScreenIcon` (and, if built separately, `navigationBarIcon`) share the same aspect ratio | `Screen` asserts this at construction — see [Building a Custom ScreenIcon](/cookbook/building-a-custom-screen-icon) |
| The new screen's `name` is genuinely translatable (a real string `Property`, not a raw string) | Every other screen's name already goes through the sim's string/locale pipeline; a plain string here is the one screen that silently won't translate |
| Nothing in the new screen's model/view imports from `advanced/` or `intro/` directly | Anything two screens both need belongs in `common/`, not screen-to-screen imports — see [Multi-Screen Sim Structure](/patterns/multi-screen-sim-structure#what-goes-where) |

::: tip Screen order in the array is navigation-bar order
`allSimScreens` (the array passed to `Sim`) is rendered left-to-right in the navigation bar in exactly the order given — inserting the new screen in the middle of the array, rather than always appending, is a completely normal way to control where it appears without reordering any other screen's code.
:::

::: warning A sim with more than one screen actually needs `name` and icons
A single-screen sim can omit `name`/`homeScreenIcon` since there's no home screen or navigation bar to show them in — but the moment a second (or third) screen exists, every screen (including ones added earlier) needs a real `name` and `homeScreenIcon`, or the home screen and navigation bar degrade to blank names and placeholder rectangle icons. If the sim you're adding to was previously single-screen, double check the *existing* screen didn't skip these.
:::


========================================================================
Page: Animating a Property Value on a Timer
URL: https://veillette.github.io/Almanach/cookbook/animating-a-property-value-on-a-timer
Source: docs/cookbook/animating-a-property-value-on-a-timer.md
Category: Cookbook | Tags: twixt, Animation, Easing, NumberProperty | Status: complete
========================================================================

# Animating a Property Value on a Timer

**Task:** a model value should visibly transition over some duration — a needle sweeping to a new reading, a value fading toward a target — instead of a view snapping to the new value the instant the underlying `Property` changes.

[`Animation`](/api/twixt/animation) (from `scenerystack/twixt`) tweens a `Property`'s value from its current value to a target over a fixed duration, using an `Easing` curve to control acceleration. It drives itself off axon's shared `stepTimer` once started, so no manual per-frame stepping is required.

## The solution

```ts
import { Animation, Easing } from 'scenerystack/twixt';
import { NumberProperty } from 'scenerystack/axon';

const needleValueProperty = new NumberProperty( 0 );

function animateNeedleTo( targetValue: number ): void {
  const animation = new Animation( {
    property: needleValueProperty,
    to: targetValue,
    duration: 0.6, // seconds
    easing: Easing.QUADRATIC_IN_OUT
  } );

  animation.start();
}

// Later, e.g. when a new sensor reading arrives:
animateNeedleTo( 72 );
```

`needleValueProperty` now sweeps smoothly to `72` over 0.6 seconds instead of jumping there instantly — any view observing `needleValueProperty` (a `link`-driven needle rotation, a `NumberDisplay`) updates every intermediate frame exactly as it would for a normal value change, with no special-casing needed on the view side.

## Interrupting an in-flight animation with a new target

If a new target value can arrive before the previous animation finishes (a fast-changing sensor), stop the old one before starting the new one, rather than letting two animations fight over the same `Property`:

```ts
let currentAnimation: Animation | null = null;

function animateNeedleTo( targetValue: number ): void {
  currentAnimation?.stop();

  currentAnimation = new Animation( {
    property: needleValueProperty,
    to: targetValue,
    duration: 0.6,
    easing: Easing.QUADRATIC_IN_OUT
  } );
  currentAnimation.start();
}
```

`stop()` halts the animation immediately, leaving `needleValueProperty` wherever it currently is — the next `Animation` then tweens from that in-progress value to the new target, rather than jumping back to the old animation's starting point first.

## Chaining a return trip

For a "go there, then come back" effect (a highlight that pulses out and back), chain a second `Animation` with `.then(...)` rather than listening for completion yourself:

```ts
const highlightOpacityProperty = new NumberProperty( 0 );

const pulseOut = new Animation( {
  property: highlightOpacityProperty,
  to: 1,
  duration: 0.15,
  easing: Easing.QUADRATIC_OUT
} );

const pulseBack = new Animation( {
  property: highlightOpacityProperty,
  to: 0,
  duration: 0.3,
  easing: Easing.QUADRATIC_IN
} );

pulseOut.then( pulseBack );
pulseOut.start();
```

## Options used here

| Option | Effect |
| --- | --- |
| `property` | The `Property` being animated directly |
| `to` | The end value the Property tweens toward |
| `duration` | Length of the tween, in seconds |
| `easing` | The interpolation curve; `Easing.QUADRATIC_IN_OUT` is a reasonable general-purpose default |

::: tip No manual stepping required for the common case
`Animation` defaults `stepEmitter` to axon's shared `stepTimer`, which already advances every frame — `start()` is enough to get a running animation with no `step()` calls to wire up yourself, unless the animation needs to be paused/driven by something other than real time (e.g. paused while the sim itself is paused), in which case pass `stepEmitter: null` and call `.step( dt )` from your own per-frame model step.
:::

::: warning `stop()` leaves the value wherever it was, it doesn't snap to `to`
Calling `animation.stop()` partway through does **not** jump the Property the rest of the way to its target — it halts exactly where the value currently is. If a caller needs "finish immediately at the target value," set the Property directly (`needleValueProperty.value = targetValue`) after calling `stop()`, rather than assuming `stop()` completes the tween.
:::


========================================================================
Page: Binding a Bamboo Chart Axis to Live Model Data
URL: https://veillette.github.io/Almanach/cookbook/binding-a-bamboo-chart-axis-to-live-data
Source: docs/cookbook/binding-a-bamboo-chart-axis-to-live-data.md
Category: Cookbook | Tags: bamboo, ChartTransform, LinePlot, NumberProperty, chart | Status: complete
========================================================================

# Binding a Bamboo Chart Axis to Live Model Data

**Task:** a chart plotting a value over time (a running sensor reading, an accumulating measurement) needs its visible x-axis range to keep up with the data as it grows, rather than being fixed to a static range decided at construction time — a "scrolling" or "auto-expanding" chart.

A [`ChartTransform`](/api/bamboo/chart-transform) is a plain object holding the chart's current model ranges; every bamboo rendering primitive listens to its `changedEmitter` and redraws automatically whenever a range changes. Binding the axis to live data is a matter of listening to the model `Property` that's actually changing (elapsed time, most recent x value) and calling `chartTransform.setModelXRange(...)` in response — never assigning `chartTransform.modelXRange` directly, since that skips the emitter that tells plots to redraw.

## The solution

```ts
import { ChartTransform, ChartRectangle, LinePlot } from 'scenerystack/bamboo';
import { Range, Vector2 } from 'scenerystack/dot';
import { NumberProperty } from 'scenerystack/axon';

const WINDOW_WIDTH = 10; // seconds of history visible at once

// --- model ---
const timeProperty = new NumberProperty( 0 ); // advances every step()
const dataSet: ( Vector2 | null )[] = [];

function step( dt: number ): void {
  timeProperty.value += dt;
  dataSet.push( new Vector2( timeProperty.value, Math.sin( timeProperty.value ) ) );

  // Keep the dataset from growing unboundedly - drop points that have
  // scrolled out of the visible window.
  while ( dataSet.length > 0 && dataSet[ 0 ] !== null && dataSet[ 0 ].x < timeProperty.value - WINDOW_WIDTH ) {
    dataSet.shift();
  }
}

// --- view ---
const chartTransform = new ChartTransform( {
  viewWidth: 400,
  viewHeight: 200,
  modelXRange: new Range( 0, WINDOW_WIDTH ),
  modelYRange: new Range( -1, 1 )
} );

const chartRectangle = new ChartRectangle( chartTransform, { fill: 'white', stroke: 'black' } );
const linePlot = new LinePlot( chartTransform, dataSet, { stroke: 'blue' } );

// The x axis "scrolls": always showing the most recent WINDOW_WIDTH seconds.
timeProperty.link( time => {
  chartTransform.setModelXRange( new Range( time - WINDOW_WIDTH, time ) );
  linePlot.setDataSet( dataSet ); // dataSet was mutated in place in step(), above
} );
```

Every frame, `timeProperty`'s listener slides `modelXRange` forward to keep the most recent `WINDOW_WIDTH` seconds visible; `setModelXRange` fires `chartTransform.changedEmitter`, which `chartRectangle` and `linePlot` are both already listening to, so both redraw with no additional wiring. `linePlot.setDataSet(...)` is called separately since mutating the `dataSet` array in place doesn't itself trigger a redraw — only `setDataSet`/the transform's `changedEmitter` do.

## Auto-expanding instead of scrolling

For a chart that should keep the full history visible and simply widen as data accumulates (rather than scrolling a fixed-width window), grow `modelXRange`'s upper bound instead of sliding the whole window:

```ts
import { Orientation } from 'scenerystack/phet-core';

timeProperty.link( time => {
  const currentRange = chartTransform.getModelRange( Orientation.HORIZONTAL );
  if ( time > currentRange.max ) {
    chartTransform.setModelXRange( new Range( currentRange.min, time ) );
  }
} );
```

(`Orientation` here comes from `scenerystack/phet-core`, the same enum bamboo's axis Nodes use — see [AxisLine and AxisArrowNode](/api/bamboo/axis-nodes).)

## Options and methods used here

| Member | Effect |
| --- | --- |
| `setModelXRange( range )` | Updates the chart's x-axis model range and fires `changedEmitter` if it actually changed |
| `getModelRange( orientation )` | Reads back the current `modelXRange`/`modelYRange` |
| `changedEmitter` | What every plot/axis/grid listens to; you never need to call anything on the plots directly when only the transform changes |
| `LinePlot.setDataSet( dataSet )` | Replaces the dataset and immediately redraws — needed alongside `setModelXRange` since the two are independent triggers |

::: tip Trim the dataset, not just the visible range
Sliding `modelXRange` forward only changes what's *drawn* — an ever-growing `dataSet` array still keeps every point in memory and still costs time to iterate every redraw. For a genuinely long-running scrolling chart, drop points that have scrolled out of the window (as `step()` does above) rather than relying on the chart's clipping to hide the problem.
:::

::: warning Never assign `chartTransform.modelXRange = ...` directly
`modelXRange` is a plain public field, readable and directly writable — but assigning it directly does **not** fire `changedEmitter`, so `chartRectangle`/`linePlot`/any axis Nodes silently keep drawing the old range. Always go through `setModelXRange()` (or the equivalent setter for whichever dimension changed), exactly as called out on [ChartTransform](/api/bamboo/chart-transform#methods).
:::


========================================================================
Page: Building a Custom ScreenIcon
URL: https://veillette.github.io/Almanach/cookbook/building-a-custom-screen-icon
Source: docs/cookbook/building-a-custom-screen-icon.md
Category: Cookbook | Tags: joist, ScreenIcon, Screen, sim | Status: complete
========================================================================

# Building a Custom ScreenIcon

**Task:** a `Screen` needs a `homeScreenIcon` (and usually a matching `navigationBarIcon`) that represents it visually on the home screen and in the navigation bar — built from your own icon artwork rather than a placeholder rectangle.

[`ScreenIcon`](/api/joist/screen-icon) is a `Node` wrapper that takes any icon `Node`, centers it on a fixed-size background, and scales it to fit — you build the icon content once as ordinary scenery Nodes, then hand it to `ScreenIcon` instead of computing scale factors yourself.

## The solution

```ts
import { Screen, ScreenIcon } from 'scenerystack/sim';
import { Circle, Rectangle, Node } from 'scenerystack/scenery';
import { Property } from 'scenerystack/axon';
import { Tandem } from 'scenerystack/tandem';

// Build the icon's content out of ordinary scenery Nodes - here, a simple
// "ball on a ramp" glyph representing an Intro screen.
function createIntroIconNode(): Node {
  const ramp = new Rectangle( 0, 20, 80, 8, { fill: 'saddlebrown' } );
  const ball = new Circle( 12, { fill: 'crimson', x: 60, y: 8 } );
  return new Node( { children: [ ramp, ball ] } );
}

const homeScreenIcon = new ScreenIcon( createIntroIconNode(), {
  fill: 'white',
  maxIconWidthProportion: 0.85,
  maxIconHeightProportion: 0.85
} );

const introTandem = Tandem.ROOT.createTandem( 'introScreen' );

const introScreen = new Screen(
  () => ( {} ), // createModel - real sims pass an actual model factory
  () => ( {} ), // createView - real sims pass a ScreenView factory
  {
    name: new Property( 'Intro' ),
    homeScreenIcon: homeScreenIcon,
    // navigationBarIcon is omitted - Screen defaults it to a scaled copy of
    // homeScreenIcon, which is correct as long as one icon reads fine at
    // both sizes. Build a separate one only if it doesn't (see below).
    backgroundColorProperty: new Property( 'white' ),
    tandem: introTandem
  }
);
```

`ScreenIcon`'s constructor makes the icon `Node` `pickable: false` and keeps it centered/re-scaled automatically if its bounds ever change later (e.g. because a child Text label's string changes with locale) — you never need to recompute the centering yourself.

## Building a separate navigation-bar icon

The navigation bar renders its icon much smaller than the home screen does, so a detailed icon that reads fine at home-screen size can turn into a blur in the nav bar. When that happens, build a second, simplified `ScreenIcon` sized for the nav bar explicitly:

```ts
const navigationBarIcon = new ScreenIcon( createIntroIconNode(), {
  size: Screen.MINIMUM_NAVBAR_ICON_SIZE,
  fill: 'white'
} );
```

`homeScreenIcon` and `navigationBarIcon` must share the same aspect ratio — `Screen` asserts this at construction, so only pass a separate `navigationBarIcon` with the same width/height ratio as `Screen.MINIMUM_NAVBAR_ICON_SIZE` implies (it already shares an aspect ratio with `Screen.MINIMUM_HOME_SCREEN_ICON_SIZE`, so simply passing `size` is normally enough).

## Options used here

| Option | Effect |
| --- | --- |
| `size` | Background rectangle size; defaults to `Screen.MINIMUM_HOME_SCREEN_ICON_SIZE`, pass `Screen.MINIMUM_NAVBAR_ICON_SIZE` for a nav-bar-specific icon |
| `maxIconWidthProportion` / `maxIconHeightProportion` | Max fraction of the background the icon is scaled to fill (both default `0.85`) |
| `fill` / `stroke` | Background rectangle styling |

::: tip Reach for stock icon-building Nodes first
Before hand-drawing shapes for icon content, check [Iconography Conventions](/styling/iconography-conventions) for `scenery-phet`'s ready-made icon Nodes (`PlusNode`, `ArrowNode`, etc.) — a `ScreenIcon`'s content is just a `Node`, so any of those compose into it exactly like the custom `Node` above.
:::

::: warning Icon content should be static, not dynamic UI
`ScreenIcon`'s content is rendered once and displayed as a snapshot of what the screen looks like — don't pass live model-connected Nodes (things that would themselves need `dispose()` or ongoing Property links) as icon content. Build a small, self-contained decorative `Node` purely for the icon, as shown above.
:::


========================================================================
Page: Debugging a Layout That Won't Auto-Size
URL: https://veillette.github.io/Almanach/cookbook/debugging-a-layout-that-wont-auto-size
Source: docs/cookbook/debugging-a-layout-that-wont-auto-size.md
Category: Cookbook | Tags: scenery, FlowBox, GridBox, Sizable, layout, layoutOptions, debugging | Status: complete
========================================================================

# Debugging a Layout That Won't Auto-Size

**Task:** a child inside a `FlowBox`/`GridBox` is supposed to grow or shrink to fill available space (`stretch: true`, `grow: 1`), but stays stuck at its natural content size — or the container itself doesn't shrink/grow the way a resizable parent's `preferredWidth` implies it should.

This is a checklist, not a single fix — auto-sizing failures almost always come down to one of four causes, roughly in order of how often each one is the actual culprit.

## 1. The per-child option is set in the wrong place

`stretch`, `grow`, `align`, and margins are read from each child's **`layoutOptions`**, not from options passed to the child's own constructor:

```ts
// Wrong - align/grow here do nothing; FlowBox never looks at the child's own options.
const badChild = new Rectangle( 0, 0, 20, 20, { fill: 'teal', grow: 1 } as any );

// Right - set on layoutOptions, which the parent FlowBox/GridBox actually reads.
const goodChild = new Rectangle( 0, 0, 20, 20, { fill: 'teal' } );
goodChild.layoutOptions = { grow: 1, stretch: true };
```

This is the single most common cause — see the warning on [FlowBox](/api/scenery/flow-box#options): "Setting `someChild.align = 'center'` does nothing."

## 2. The child isn't actually resizable, only positionable

`stretch`/`grow` tell the *container* to try to give a child more space — but a plain `Node`/`Path`/`Rectangle` has no concept of "be this size," only "here is my content's natural size." Only a Node that mixes in `WidthSizable`/`HeightSizable`/`Sizable` (see [Sizable, WidthSizable, and HeightSizable](/api/scenery/sizable-mixins)) can actually grow or shrink in response to a `preferredWidth`/`preferredHeight` the layout container sets:

```ts
import { Node, Rectangle, Sizable } from 'scenerystack/scenery';

// A plain Rectangle can never really "stretch" - its rectWidth is whatever
// you set it to, and nothing reacts to a parent's preferredWidth.
class PlainBar extends Node { /* ... */ }

// A Sizable Node CAN stretch - it reacts to preferredWidthProperty.
class StretchyBar extends Sizable( Node ) {
  private readonly background = new Rectangle( 0, 0, 0, 20, { fill: 'teal' } );

  public constructor() {
    super();
    this.addChild( this.background );
    this.mutate( { minimumWidth: 20 } ); // set AFTER super(), not in super()'s options
    this.preferredWidthProperty.link( preferredWidth => {
      this.background.rectWidth = preferredWidth ?? this.minimumWidth ?? 0;
    } );
  }
}
```

If the child in question is a `sun`/`scenery-phet` component, check whether that specific class documents itself as sizable at all before assuming `stretch: true` should do anything to it — many fixed-content components (an icon, a `Text`) are deliberately not resizable, and `stretch`/`grow` on them is a no-op by design, not a bug.

## 3. Nothing upstream ever gave the container a `preferredWidth` to distribute

`stretch`/`grow` only have leftover space to distribute if the *container itself* has been given a `preferredWidth`/`preferredHeight` from somewhere — usually its own parent, or an explicit `layoutBounds`-derived size on a top-level container. A `FlowBox` whose own bounds are purely content-driven (nobody set `preferredWidth` on it) has no "extra space" for a `grow: 1` child to claim, so the child sits at its minimum size even though it's genuinely resizable:

```ts
import { HBox } from 'scenerystack/scenery';

const row = new HBox( { children: [ stretchyBar ], stretch: true } );
row.layoutOptions = { grow: 1 }; // still does nothing unless row's OWN parent gives it a preferredWidth

// Something has to be the source of a fixed size for the chain to have
// anything to distribute - e.g. explicitly setting a container width:
row.preferredWidth = 400; // now stretchyBar has 400 px (minus siblings) to grow into
```

See [Advanced Layout Techniques](/guides/advanced-layout-techniques#nesting-flowbox-and-gridbox) for the same issue showing up when nesting: an inner container's `stretch: true` children have nothing to do if the outer container's own `align` never gives the inner container a `preferredWidth` in the first place.

## 4. A GridBox child's `row`/`column` is missing or wrong

For `GridBox` specifically, a child that appears in the wrong cell (or seems to not participate in the grid at all) is usually a `layoutOptions.row`/`layoutOptions.column` that's missing, duplicated with another child, or set on the wrong Node (e.g. on a wrapper `Node` instead of the actual visible child):

```ts
// Two children accidentally targeting the same cell - the second overwrites the first visually.
labelText.layoutOptions = { row: 0, column: 0 };
checkbox.layoutOptions = { row: 0, column: 0 }; // bug: should be column: 1
```

## The checklist

| Symptom | Likely cause | Where to look |
| --- | --- | --- |
| `stretch`/`grow`/`align` set but nothing changes | Option set on the child's own constructor, not `layoutOptions` | [FlowBox options](/api/scenery/flow-box#options) |
| Child has `layoutOptions.stretch: true` but never actually grows | Child isn't `WidthSizable`/`HeightSizable`/`Sizable` | [Sizable, WidthSizable, and HeightSizable](/api/scenery/sizable-mixins) |
| A `Sizable` child still doesn't grow, even inside a container with `stretch: true` | The container itself was never given a `preferredWidth`/`preferredHeight` to distribute | [Advanced Layout Techniques](/guides/advanced-layout-techniques) |
| A `GridBox` child is missing or in the wrong cell | Missing, duplicated, or misassigned `layoutOptions.row`/`column` | [GridBox](/api/scenery/grid-box) |
| A `Sizable` Node's `minimumWidth`/`preferredWidth` mutation throws an assertion | Sizable options passed directly to `super()` instead of a later `mutate()` call | The warning on [Sizable, WidthSizable, and HeightSizable](/api/scenery/sizable-mixins) |

::: tip Work from the leaf outward, not the container inward
When a deeply nested layout doesn't resize as expected, start by confirming the actual leaf child is `Sizable` and has `layoutOptions` set correctly, then check one container level up at a time for a missing `preferredWidth` — rather than guessing at the top-level container's options first. The break is almost always at exactly one level of the chain, and working outward from the leaf finds it faster than auditing every container at once.
:::

::: warning `resize: false` looks like a sizing bug but is an intentional freeze
If a `FlowBox`/`GridBox` was deliberately constructed with `resize: false` (to reserve a fixed footprint), it stops re-running layout on its own bounds after the first pass — a child added or resized afterward won't reflow until something calls `updateLayout()` explicitly. Check for `resize: false` before assuming a genuine `Sizable`/`layoutOptions` bug when a container that *should* be dynamic seems frozen.
:::


========================================================================
Page: Detecting Touch vs. Mouse vs. Keyboard Input
URL: https://veillette.github.io/Almanach/cookbook/detecting-touch-mouse-keyboard-input
Source: docs/cookbook/detecting-touch-mouse-keyboard-input.md
Category: Cookbook | Tags: scenery, Pointer, SceneryEvent, Mouse, Touch, input | Status: complete
========================================================================

# Detecting Touch vs. Mouse vs. Keyboard Input

**Task:** most interactions should behave identically regardless of input device, but occasionally a behavior genuinely needs to differ — a bigger visual "grab" affordance only for touch, a hover tooltip that makes no sense on a touchscreen, a log line that records which modality triggered an action.

Every scenery input event ultimately traces back to a `Pointer` — a `Mouse`, `Touch`, `Pen`, or, for keyboard/AT-driven input, a `PDOMPointer` (see [Alternative Input Overview](/accessibility/alternative-input-overview)). A [`SceneryEvent`](/api/scenery/scenery-event) passed to any input listener callback carries the triggering `Pointer` as `event.pointer`, and its `type` field is exactly the discriminator to branch on.

## Branching on `event.pointer.type`

```ts
import { Node, Circle } from 'scenerystack/scenery';

const draggableIcon = new Circle( 20, { fill: 'crimson', cursor: 'pointer' } );

draggableIcon.addInputListener( {
  down: event => {
    switch( event.pointer.type ) {
      case 'touch':
        // Touch presses benefit from a visibly larger "being held" affordance.
        draggableIcon.scale( 1.15 );
        break;
      case 'mouse':
        draggableIcon.cursor = 'grabbing';
        break;
      case 'pdom':
        // Keyboard/AT-driven activation - no pointer-specific visual needed.
        break;
      default:
        break;
    }
  },
  up: event => {
    draggableIcon.scale( 1 );
    draggableIcon.cursor = 'pointer';
  }
} );
```

`event.pointer.type` is a plain string (`'mouse'`, `'touch'`, `'pen'`, or `'pdom'` for PDOM-driven input) — see [Pointer, Mouse, and Touch](/api/scenery/pointer-mouse-touch-pen) for the full set of `Pointer` subclasses this corresponds to, and [SceneryEvent](/api/scenery/scenery-event) for the rest of what's available on the event object (`event.trail`, `event.domEvent`, etc.).

## Type-specific listener callback names

For the common case of "run this only for touch" (or only for mouse), scenery also dispatches type-specific event names directly, so you don't need an `if`/`switch` inside a generic `down`/`up` callback:

```ts
draggableIcon.addInputListener( {
  touchdown: event => {
    // Fires only for Touch pointers - equivalent to checking
    // event.pointer.type === 'touch' inside a plain `down` handler.
    draggableIcon.scale( 1.15 );
  },
  mousedown: event => {
    draggableIcon.cursor = 'grabbing';
  }
} );
```

Every generic event (`down`, `up`, `move`, `enter`, `exit`, `over`, `out`, `cancel`) has `mouse`/`touch`/`pen`-prefixed variants (`mousedown`, `touchdown`, `pendown`, …) — use whichever reads more clearly for the listener you're writing; both approaches dispatch from the same underlying `Pointer` type.

## Detecting keyboard/PDOM-driven interaction specifically

Keyboard activation doesn't flow through `down`/`up` pointer events at all — a focusable Node driven by keyboard/switch input receives `keydown`/`keyup` (and, for structured listeners, `press`/`release` via the same `TInputListener` interface pointer input uses; see [Alternative Input Overview](/accessibility/alternative-input-overview)). To confirm an interaction happened via keyboard rather than a pointer, check for the `PDOMPointer` case in a pointer-based listener, or simply attach a `focus`/`keydown` listener instead:

```ts
draggableIcon.tagName = 'div';
draggableIcon.focusable = true;
draggableIcon.accessibleName = 'Movable token';

draggableIcon.addInputListener( {
  focus: () => {
    // A focus event only ever originates from keyboard/AT navigation, not a pointer.
    draggableIcon.stroke = 'black';
  },
  blur: () => {
    draggableIcon.stroke = null;
  }
} );
```

## Where each check makes sense

| Situation | What to check |
| --- | --- |
| A pointer-driven listener needs to special-case touch's larger fingertip | `event.pointer.type === 'touch'`, or the `touchdown`/`touchup`/… callback names |
| Code needs to know "was this triggered by keyboard/AT, not a pointer at all" | `event.pointer.type === 'pdom'`, or simply react to `focus`/`keydown` instead of `down` |
| A visual affordance (tooltip, hover highlight) should only show for non-touch pointers | Check `event.pointer.type !== 'touch'` in `over`/`out`, since touch has no true "hover" state |

::: warning Don't gate core functionality on input type
Branching on `event.pointer.type` is appropriate for *presentation* differences (a bigger grab handle, skipping a hover-only tooltip) — never for whether an interaction works at all. An interaction that only works for one pointer type, or that has no keyboard-accessible equivalent, fails [Alternative Input Overview](/accessibility/alternative-input-overview)'s core requirement that every listener implement the same shared `TInputListener` interface regardless of what triggers it.
:::


========================================================================
Page: Fuzz-Testing a Simulation Locally
URL: https://veillette.github.io/Almanach/cookbook/fuzz-testing-a-simulation-locally
Source: docs/cookbook/fuzz-testing-a-simulation-locally.md
Category: Cookbook | Tags: query-parameters, fuzz, testing, qa | Status: verified
========================================================================

# Fuzz-Testing a Simulation Locally

**Task:** before shipping a change, you want automated confidence that no sequence of rapid, unexpected input (fast clicking, dragging mid-transition, hammering a keyboard shortcut) throws an uncaught exception — without writing a hand-crafted test for every such sequence.

SceneryStack simulations have a built-in fuzzer: appending `?fuzz` to the sim's URL drives a continuous stream of randomized pointer and keyboard events at the running sim, and reports the first uncaught exception it triggers. This is [layer 3 of the testing strategy](/guides/testing-and-qa-strategy-overview) — a crash-finder, not a correctness-checker — and complements headless model tests and manual QA rather than replacing either.

## Running a basic fuzz pass

```
http://localhost:5173/my-sim/my-sim_en.html?fuzz&ea
```

- `fuzz` turns on the randomized input stream.
- `ea` ("enable assertions") is normally paired with it, so an invalid internal state throws immediately at the point it first goes wrong, rather than silently corrupting further state and surfacing as a confusing, unrelated exception minutes later.

Let it run for a few minutes while watching the browser console; a clean run producing no console errors is the pass condition. A thrown exception's stack trace points at the code path the fuzzer happened to stumble into — that's the bug to fix, not the fuzzer's behavior to work around.

## Narrowing which input modality is exercised

If a fuzz run finds a crash, narrowing which kind of input is being generated helps isolate whether the bug is in pointer handling, keyboard handling, or both:

| Parameter | Effect |
| --- | --- |
| `fuzz` | Randomizes all input modalities together (pointer and keyboard) |
| `fuzzMouse` | Randomizes only simulated mouse input |
| `fuzzTouch` | Randomizes only simulated touch input |
| `fuzzBoard` | Randomizes only keyboard input, exercising focus movement and hotkeys instead of pointer events |
| `fuzzRate` | Controls how frequently fuzz events are generated (higher values fire events faster) |

Combine one of the modality-specific flags with `ea` the same way as the general case, e.g. `?fuzzBoard&ea` to stress-test keyboard-only interaction paths (useful right after adding a new `KeyboardListener`/`KeyboardDragListener`, to catch a hotkey that assumes some state that a rapid, out-of-order key sequence violates).

## Reproducing a fuzz-found failure

Fuzzing is randomized, so a crash found in one run may not reproduce with the same seed by default — if a failure needs to be isolated for debugging, note the exact console error and stack trace from the run that found it, and use it to write a targeted, deterministic unit test (see [Testing Model Logic Headlessly](/patterns/testing-model-logic-headlessly)) covering that specific input sequence instead of relying on fuzzing to reproduce it again. Fuzzing is best treated as a discovery tool for the *existence* of a bug, not as the regression test that then guards against it recurring.

## Where this fits in a release checklist

| Layer | What it catches | This recipe |
| --- | --- | --- |
| Headless unit tests | Logic/physics bugs in model code | Not this — see [Testing Model Logic Headlessly](/patterns/testing-model-logic-headlessly) |
| Manual QA | Visual/UX/accessibility issues | Not this — a human still needs to look at and navigate the sim |
| Fuzz-testing | Crashes from unexpected/rapid input sequences | This recipe, and running it in CI — see [Continuous Integration for SceneryStack Projects](/guides/continuous-integration-for-scenerystack-projects) |

::: tip Run it after any change to input handling, not just before a release
A few minutes of `?fuzz&ea` locally, right after adding or modifying a `DragListener`/`KeyboardListener`/custom input listener, catches the class of bug fuzzing is good at — an unexpected state transition mid-interaction — while the change is still fresh in mind, rather than waiting for a pre-release fuzz pass to surface it days or weeks later.
:::

The `fuzz`, `fuzzMouse`, `fuzzTouch`, `fuzzBoard`, `fuzzRate`, and `ea` flags are registered in SceneryStack's built-in query-parameter schema (`chipper/js/browser/initialize-globals.js` in `scenerystack@3.0.0`); `SimDisplay` reads them when driving the input and keyboard fuzzers.


========================================================================
Page: Keyboard Shortcuts on a Custom Node
URL: https://veillette.github.io/Almanach/cookbook/keyboard-shortcuts-on-a-custom-node
Source: docs/cookbook/keyboard-shortcuts-on-a-custom-node.md
Category: Cookbook | Tags: scenery, KeyboardListener, keyboard, accessibility, hotkey | Status: complete
========================================================================

# Keyboard Shortcuts on a Custom Node

**Task:** a custom `Node` you've built (a selectable item, a rotatable dial) needs a keyboard shortcut beyond simple activation or dragging — deleting the item with <kbd>Delete</kbd>, rotating it a fixed step with <kbd>[</kbd>/<kbd>]</kbd>, and so on.

[`KeyboardListener`](/api/scenery/keyboard-listener) (from `scenerystack/scenery`) is the general-purpose tool for this: declare the key combination(s) as strings, attach it via `addInputListener`, and the Node must be focusable (`tagName`/`focusable`) so it participates in the [Parallel DOM](/accessibility/pdom) at all — the listener only fires while its target (or a descendant) has focus.

## The solution

```ts
import { Node, Path, KeyboardListener } from 'scenerystack/scenery';
import { Shape } from 'scenerystack/kite';
import { NumberProperty } from 'scenerystack/axon';

class RotatableDial extends Node {

  public readonly angleProperty = new NumberProperty( 0 ); // radians

  public constructor() {
    super( {
      tagName: 'div',
      focusable: true,
      accessibleName: 'Dial'
    } );

    const dialShape = new Path( Shape.circle( 0, 0, 30 ), {
      fill: 'lightGray',
      stroke: 'black'
    } );
    const pointer = new Path( Shape.lineSegment( 0, 0, 0, -28 ), { stroke: 'crimson', lineWidth: 3 } );
    this.children = [ dialShape, pointer ];

    this.angleProperty.link( angle => {
      pointer.rotation = angle;
    } );

    const ROTATE_STEP = Math.PI / 12; // 15 degrees

    this.addInputListener( new KeyboardListener( {
      keys: [ '[', ']' ],
      fire: ( event, keysPressed ) => {
        const direction = keysPressed === ']' ? 1 : -1;
        this.angleProperty.value += direction * ROTATE_STEP;
      },
      fireOnHold: true // holding the key keeps rotating, not just one step per press
    } ) );
  }
}
```

Pressing <kbd>[</kbd>/<kbd>]</kbd> while `RotatableDial` (or a descendant) has focus rotates `angleProperty` by a fixed step each time; `fireOnHold: true` lets holding the key repeat the rotation instead of requiring separate presses.

## A delete/remove shortcut

The same pattern covers a "remove this selected item" shortcut, listening for either of two keys with one `KeyboardListener`:

```ts
selectedItemNode.addInputListener( new KeyboardListener( {
  keys: [ 'delete', 'backspace' ],
  fire: () => {
    model.removeItem( item );
  }
} ) );
```

## Handling a modifier variant of the same key

If the same key should do something different when a modifier is held (a larger step with <kbd>Shift</kbd>+<kbd>]</kbd>), list both combinations and branch on `keysPressed`:

```ts
this.addInputListener( new KeyboardListener( {
  keys: [ ']', 'shift+]' ],
  fire: ( event, keysPressed ) => {
    const step = keysPressed === 'shift+]' ? ROTATE_STEP * 4 : ROTATE_STEP;
    this.angleProperty.value += step;
  }
} ) );
```

## Options used here

| Option | Effect |
| --- | --- |
| `keys` | Array of key combination strings this listener responds to |
| `fire` | `( event, keysPressed, listener ) => void`, called when a combination fires; `keysPressed` says which one |
| `fireOnHold` | Whether holding the combination repeats `fire` (default `false`) |

::: tip Document the shortcut, don't rely on discovery
A hotkey with no visible affordance is easy for a keyboard user to never find. Real sims register their custom shortcuts with the sim-wide keyboard-help dialog content (built from the same `HotkeyData`/`KeyboardListener` machinery) so they show up in the help dialog every screen already provides — see [Keyboard Input and Hotkeys](/accessibility/keyboard-input-and-hotkeys) for the lower-level `Hotkey`/`HotkeyData` building blocks this integrates with.
:::

::: warning A hotkey with no matching pointer/PDOM-visible affordance is only half the interaction
Adding `[`/`]` rotation via `KeyboardListener` doesn't by itself give a mouse/touch user any way to rotate the dial — make sure an equivalent pointer interaction exists too (e.g. a `DragListener` on the dial itself), the same "every interaction needs both an input modality and its accessible equivalent" principle covered in [Alternative Input Overview](/accessibility/alternative-input-overview).
:::


========================================================================
Page: Lazily Creating an Expensive Node
URL: https://veillette.github.io/Almanach/cookbook/lazily-creating-an-expensive-node
Source: docs/cookbook/lazily-creating-an-expensive-node.md
Category: Cookbook | Tags: scenery, Node, dispose, lazy-initialization | Status: complete
========================================================================

# Lazily Creating an Expensive Node

**Task:** some piece of a screen is expensive to construct — a detailed graph with many plotted points, a large `Image`, a subtree with dozens of children — but is only shown conditionally (an `AccordionBox` section a user may never open, a dialog, a rarely-visited game state). Building it eagerly at startup pays that cost for every user, even ones who never see it.

The fix is to defer construction until the Node is actually needed — typically the first time some `visibleProperty` (or similar gate) becomes `true` — and keep a `null`-able reference until then, rather than constructing every child up front in the containing Node's constructor.

## The solution

```ts
import { Node, type NodeOptions } from 'scenerystack/scenery';
import { BooleanProperty } from 'scenerystack/axon';

class ExpensiveGraphNode extends Node {
  public constructor() {
    super();
    // ...expensive plots, gridlines, many child Nodes...
  }
}

class ScreenSection extends Node {

  private readonly isGraphSectionVisibleProperty = new BooleanProperty( false );

  // Undefined until first built; explicitly typed so callers can't forget the
  // not-yet-created case.
  private expensiveGraphNode: ExpensiveGraphNode | null = null;

  public constructor( providedOptions?: NodeOptions ) {
    super( providedOptions );

    this.isGraphSectionVisibleProperty.link( isVisible => {
      if ( isVisible && this.expensiveGraphNode === null ) {
        // Build it exactly once, on first actual need.
        this.expensiveGraphNode = new ExpensiveGraphNode();
        this.addChild( this.expensiveGraphNode );
      }

      // Once built, subsequent toggles just show/hide - no rebuilding.
      if ( this.expensiveGraphNode !== null ) {
        this.expensiveGraphNode.visible = isVisible;
      }
    } );
  }

  public override dispose(): void {
    this.expensiveGraphNode?.dispose();
    super.dispose();
  }
}
```

The constructor for `ScreenSection` now does none of `ExpensiveGraphNode`'s work — that cost is only paid the first time `isGraphSectionVisibleProperty` flips to `true`. Every toggle afterward is a cheap `visible` assignment, not a rebuild, since `expensiveGraphNode` is retained (not disposed and reconstructed) once created.

## When to dispose instead of hide

If the expensive Node's memory footprint matters more than the cost of rebuilding it (e.g. it holds many `Image` resources you don't want to keep around once collapsed again), dispose it on hide instead of just toggling `visible`, and let the same lazy-construction branch rebuild it on the next need:

```ts
this.isGraphSectionVisibleProperty.link( isVisible => {
  if ( isVisible ) {
    if ( this.expensiveGraphNode === null ) {
      this.expensiveGraphNode = new ExpensiveGraphNode();
      this.addChild( this.expensiveGraphNode );
    }
  }
  else if ( this.expensiveGraphNode !== null ) {
    // Trade rebuild cost for memory: fully tear down instead of just hiding.
    this.removeChild( this.expensiveGraphNode );
    this.expensiveGraphNode.dispose();
    this.expensiveGraphNode = null;
  }
} );
```

Pick the "hide, keep alive" version by default — it's simpler and avoids repeated construction cost — and only switch to "dispose on hide" once profiling shows the retained memory is actually a problem. See [Performance and Profiling](/guides/performance-and-profiling) for how to check.

## Dispose considerations

| Situation | What to do |
| --- | --- |
| The lazy Node is never disposed until the containing Node is | Dispose it conditionally in the container's own `dispose()` (`this.expensiveGraphNode?.dispose()`), since it may never have been created at all |
| The lazy Node links to Properties owned outside itself | Make sure `ExpensiveGraphNode.dispose()` unlinks those listeners — see [Dispose and Memory Management](/patterns/dispose-and-memory-management) — the same as any other dynamically-created Node |
| The gating condition can flip many times per session | Prefer "hide, keep alive" (first version above) so repeated toggles don't pay construction cost more than once |

::: tip The optional-chaining `dispose()` call is doing real work
`this.expensiveGraphNode?.dispose()` is not just defensive style here — it's the load-bearing check for "was this ever actually constructed." Skipping the `?.` and calling `.dispose()` unconditionally would throw whenever the section was collapsed for an entire session and `expensiveGraphNode` stayed `null`.
:::

::: warning Don't lazily construct Nodes PhET-iO needs to see unconditionally
If the expensive Node carries PhET-iO-instrumented state (its own `tandem`), lazily creating it means that state doesn't exist until the gating condition first fires — which can be a problem for PhET-iO state restoration (a saved state expecting the element to already exist). Reserve this pattern for purely visual, uninstrumented subtrees, and instrument the underlying model data unconditionally instead if a PhET-iO client needs to observe it before the view ever appears.
:::


========================================================================
Page: Making Any Node Draggable and Bounded to an Area
URL: https://veillette.github.io/Almanach/cookbook/draggable-node-bounded-to-an-area
Source: docs/cookbook/draggable-node-bounded-to-an-area.md
Category: Cookbook | Tags: scenery, DragListener, dragBoundsProperty, drag, Bounds2 | Status: complete
========================================================================

# Making Any Node Draggable and Bounded to an Area

**Task:** you have a `Node` (an icon, a body, a token) that should follow the pointer while dragged, but never leave a fixed rectangular region — the play area, a container's interior, the visible screen bounds.

The tool for this is a plain [`DragListener`](/api/scenery/drag-listener) (from `scenerystack/scenery`) with two options set together: `positionProperty` (the model `Property` the drag writes to) and `dragBoundsProperty` (constrains the position to a `Bounds2`, via `closestPointTo`). This is a narrower slice of [Drag Listeners](/patterns/drag-listeners) — that page also covers the keyboard-accessible listeners; this recipe is pointer-only and focused on the bounding step.

## The solution

```ts
import { DragListener, Circle } from 'scenerystack/scenery';
import { Property, NumberProperty } from 'scenerystack/axon';
import { Bounds2, Vector2 } from 'scenerystack/dot';
import { Tandem } from 'scenerystack/tandem';

// --- model ---
class TokenModel {
  public readonly positionProperty = new Property( new Vector2( 0, 0 ) );

  // The region the token is allowed to occupy, in model coordinates.
  // A Property (not a plain Bounds2) so it can change later, e.g. on a layout resize.
  public readonly dragBoundsProperty = new Property( new Bounds2( -200, -150, 200, 150 ) );

  public reset(): void {
    this.positionProperty.reset();
  }
}

// --- view ---
const model = new TokenModel();

const tokenNode = new Circle( 15, {
  fill: 'dodgerblue',
  cursor: 'pointer'
} );

// The view only ever reads positionProperty back - it never sets it directly.
model.positionProperty.link( position => {
  tokenNode.translation = position;
} );

tokenNode.addInputListener( new DragListener( {
  positionProperty: model.positionProperty,
  dragBoundsProperty: model.dragBoundsProperty,

  // No `transform` is passed here, so positionProperty is written in the
  // same (view/parent) coordinate frame tokenNode itself lives in. Pass a
  // ModelViewTransform2 via `transform` if your model uses different units.

  tandem: Tandem.REQUIRED
} ) );
```

Dragging `tokenNode` now sets `model.positionProperty` to the pointer's position every frame, clamped so it never leaves `(-200, -150)`–`(200, 200)`. Because the view only observes `positionProperty` (never writes it), any other code that changes the position — a "center token" button, a reset — moves the node the same way a drag would.

## Making the bounds themselves dynamic

Since `dragBoundsProperty` is a `Property<Bounds2>`, shrinking or growing the allowed region at runtime (e.g. to match a resizable container) is just setting a new `Bounds2` — the listener re-clamps on the next drag automatically, and also clamps the *current* value immediately if it's already outside the new bounds:

```ts
function onContainerResized( newInteriorBounds: Bounds2 ): void {
  model.dragBoundsProperty.value = newInteriorBounds;
}
```

## Options used here

| Option | Effect |
| --- | --- |
| `positionProperty` | The model `Property` written during the drag |
| `dragBoundsProperty` | A `Property<Bounds2>` the written position is clamped into, in the same coordinate frame as `positionProperty` |
| `transform` | A `ModelViewTransform2` to convert between model and view units; omit it when the model and view already share coordinates, as above |
| `tandem` | Required for PhET-iO-instrumented sims; see [Tandem](/api/tandem/tandem) |

::: tip Pointer-only is not the full story
This recipe intentionally covers only pointer dragging. A production control almost always also needs a keyboard path — either add a `KeyboardDragListener` alongside this `DragListener`, or replace both with a single `RichDragListener`, which accepts the same `positionProperty`/`dragBoundsProperty` options and adds arrow-key/WASD support for free. See the [full checklist](/patterns/drag-listeners#richdraglistener-both-at-once) for what else a well-behaved draggable needs (touch area dilation, `userControlledProperty` during animation).
:::

::: warning `dragBoundsProperty` needs `positionProperty` to know the current position
If you ever switch to `translateNode: true` instead of `positionProperty` (letting the listener move the Node's translation directly rather than a model Property), you must still supply one or the other — the listener has no other way to know what position to clamp. For model-bound dragging like this recipe, `positionProperty` alone is sufficient.
:::


========================================================================
Page: Placeholder Values in a Translated String
URL: https://veillette.github.io/Almanach/cookbook/placeholder-values-in-a-translated-string
Source: docs/cookbook/placeholder-values-in-a-translated-string.md
Category: Cookbook | Tags: axon, PatternStringProperty, DerivedProperty, i18n, strings | Status: complete
========================================================================

# Placeholder Values in a Translated String

**Task:** a UI string needs to include a dynamic value — "3 particles remaining", "Score: 42" — and that string must still be fully translatable, including handling of languages where the value's position in the sentence differs from English.

Concatenating strings by hand (`particlesRemaining + ' ' + count`) breaks translation, since a translator can't reorder pieces that are only ever joined in one fixed order in code. [`PatternStringProperty`](/api/axon/pattern-string-property) (from `scenerystack/axon`) is the fix: the translated string itself contains the `{{placeholder}}` token, in whatever position that language's grammar requires, and `PatternStringProperty` fills it in reactively as the underlying value changes.

## The solution

```ts
import { PatternStringProperty, NumberProperty, TinyProperty } from 'scenerystack/axon';
import { Text } from 'scenerystack/scenery';

const particleCountProperty = new NumberProperty( 3 );

// In real sim code this comes from a generated strings module backed by a
// translation file, e.g. MySimStrings.particlesRemainingStringProperty -
// a TinyProperty stands in here for a self-contained example.
const particlesRemainingPatternProperty = new TinyProperty( '{{count}} particles remaining' );

const particlesRemainingStringProperty = new PatternStringProperty(
  particlesRemainingPatternProperty,
  { count: particleCountProperty }
);

const particlesRemainingText = new Text( particlesRemainingStringProperty );
// particlesRemainingText reads "3 particles remaining"

particleCountProperty.value = 1;
// particlesRemainingText now reads "1 particles remaining" automatically -
// no manual re-render, and no separate singular/plural handling here (see below).
```

Because `particlesRemainingStringProperty` is itself a `TReadOnlyProperty<string>`, passing it straight to `Text`'s constructor is enough — `Text` accepts a string `Property` directly and updates its rendered content whenever the Property changes, so there's no `.link()` to write by hand.

## Multiple placeholders and derived formatting

`values` accepts as many placeholder names as the pattern string uses, and each can be a plain value or another `Property` (only the Property ones trigger re-derivation):

```ts
const scoreProperty = new NumberProperty( 0 );
const totalProperty = new NumberProperty( 10 );

const scorePatternProperty = new TinyProperty( 'Score: {{score}} of {{total}}' );

const scoreStringProperty = new PatternStringProperty( scorePatternProperty, {
  score: scoreProperty,
  total: totalProperty // a plain number here would also work, if the total never changes
} );
```

Use the `maps` option to convert a non-string/non-number value (or to round/rescale a numeric one) before substitution:

```ts
const distanceMetersProperty = new NumberProperty( 1234.5 );

const distanceStringProperty = new PatternStringProperty(
  new TinyProperty( '{{distance}} km' ),
  { distance: distanceMetersProperty },
  {
    maps: { distance: ( meters: number ) => meters / 1000 },
    decimalPlaces: 1
  }
);
// '1.2 km'
```

## Disposing dynamically-created instances

`PatternStringProperty` is a `DerivedProperty` under the hood, so an instance created for a transient piece of UI (a per-item label in a list) must be disposed when that UI goes away, the same as any other derived Property — see [Dispose and Memory Management](/patterns/dispose-and-memory-management):

```ts
const itemLabelStringProperty = new PatternStringProperty(
  new TinyProperty( '{{name}}: {{value}}' ),
  { name: item.nameProperty, value: item.valueProperty }
);
// ...later, when the item is removed:
itemLabelStringProperty.dispose();
```

## Options used here

| Option | Effect |
| --- | --- |
| `values` (second constructor argument) | Record mapping each `{{placeholder}}` name to a value or Property |
| `maps` | Per-key conversion functions run before substitution |
| `decimalPlaces` | Rounds numeric values (after any `map`) to a fixed number of decimals |

::: tip Plural forms need their own pattern string, not extra logic in code
English happily reads "1 particles remaining" without anyone noticing, but many languages have real plural-form grammar. `PatternStringProperty` itself doesn't solve plural forms — that's handled at the translation-string level (a translator provides a grammatically correct pattern for their language) together with the broader localization pipeline described in [Internationalization Deep Dive](/guides/internationalization-deep-dive), not by branching in application code on `count === 1`.
:::

::: warning The pattern must be a `Property`, not a plain string
`PatternStringProperty`'s first argument needs to be a `TReadOnlyProperty<string>` (typically a real translated `...StringProperty` from a generated strings module) so the whole derived string re-renders automatically if the locale changes at runtime — passing a plain string works at the type level for a `TinyProperty` wrapper but defeats the point if the real translated string Property is available and skipped in favor of a hardcoded literal.
:::


========================================================================
Page: Snapping a Draggable Node to a Grid
URL: https://veillette.github.io/Almanach/cookbook/snapping-a-draggable-node-to-a-grid
Source: docs/cookbook/snapping-a-draggable-node-to-a-grid.md
Category: Cookbook | Tags: scenery, DragListener, mapPosition, drag, dot, roundToInterval | Status: complete
========================================================================

# Snapping a Draggable Node to a Grid

**Task:** a draggable object (a puzzle piece, a graph point) should visually jump to the nearest cell of a fixed grid while being dragged, rather than following the pointer at arbitrary sub-pixel positions.

`DragListener` and `KeyboardDragListener` both accept a `mapPosition` option — a `( point: Vector2 ) => Vector2` hook that runs on every proposed position *before* it's written to `positionProperty` (and before `dragBoundsProperty` clamping). Returning a rounded point from `mapPosition` is the standard way to snap a drag to a grid without hand-rolling position math inside `drag`/`end` callbacks.

## The solution

```ts
import { DragListener, Rectangle } from 'scenerystack/scenery';
import { Property } from 'scenerystack/axon';
import { Vector2, roundToInterval } from 'scenerystack/dot';
import { Tandem } from 'scenerystack/tandem';

const GRID_CELL_SIZE = 20; // model units per grid cell

// --- model ---
const positionProperty = new Property( new Vector2( 0, 0 ) );

// --- view ---
const pieceNode = new Rectangle( -8, -8, 16, 16, {
  fill: 'mediumseagreen',
  cursor: 'pointer'
} );

positionProperty.link( position => {
  pieceNode.translation = position;
} );

pieceNode.addInputListener( new DragListener( {
  positionProperty: positionProperty,

  // Snap every candidate position to the nearest grid intersection before
  // it's written to positionProperty.
  mapPosition: ( point: Vector2 ) => new Vector2(
    roundToInterval( point.x, GRID_CELL_SIZE ),
    roundToInterval( point.y, GRID_CELL_SIZE )
  ),

  tandem: Tandem.REQUIRED
} ) );
```

`roundToInterval` (from `scenerystack/dot`, alongside the other numeric helpers documented in [Utils](/api/dot/dot-utils)) rounds a value to the nearest multiple of a given interval — exactly the "nearest grid line" computation, applied independently to `x` and `y`.

The Node now jumps between grid cells as it's dragged, rather than following the pointer continuously — try setting `GRID_CELL_SIZE` to `1` to confirm the un-snapped behavior is unchanged, and larger values (e.g. `50`) to make the snapping obvious.

## Combining with drag bounds

`mapPosition` and `dragBoundsProperty` compose — `mapPosition` runs first, then the result is clamped into `dragBoundsProperty` (see [Making Any Node Draggable and Bounded to an Area](/cookbook/draggable-node-bounded-to-an-area)) — so a snapped grid position that would fall just outside the play area is still pulled back in:

```ts
import { Bounds2 } from 'scenerystack/dot';

pieceNode.addInputListener( new DragListener( {
  positionProperty: positionProperty,
  dragBoundsProperty: new Property( new Bounds2( -100, -100, 100, 100 ) ),
  mapPosition: ( point: Vector2 ) => new Vector2(
    roundToInterval( point.x, GRID_CELL_SIZE ),
    roundToInterval( point.y, GRID_CELL_SIZE )
  ),
  tandem: Tandem.REQUIRED
} ) );
```

## Options used here

| Option | Effect |
| --- | --- |
| `mapPosition` | `( point: Vector2 ) => Vector2` — transforms a candidate drag position before it's written to `positionProperty`; runs before `dragBoundsProperty` clamping |
| `positionProperty` | The model `Property` receiving the (now snapped) position |

::: tip `mapPosition` works identically on `KeyboardDragListener` and `RichDragListener`
Because `mapPosition` is part of the shared `AllDragListenerOptions` every drag listener accepts, adding the same `mapPosition` function to a `KeyboardDragListener` (or the `keyboardDragListenerOptions` of a `RichDragListener`) snaps keyboard-driven dragging to the same grid, with no separate logic needed — see [Drag Listeners](/patterns/drag-listeners) for wiring up the keyboard-accessible variants.
:::

::: warning Round the point, not the delta
`mapPosition` receives and must return an absolute point (in the same coordinate frame as `positionProperty`), not a per-step delta — rounding a delta instead would snap relative to wherever the drag started rather than to a fixed grid, so cells would shift depending on the drag's starting position.
:::


========================================================================
Page: Wiring Up a New PhET-iO Instrumented Control
URL: https://veillette.github.io/Almanach/cookbook/wiring-a-new-phet-io-instrumented-control
Source: docs/cookbook/wiring-a-new-phet-io-instrumented-control.md
Category: Cookbook | Tags: tandem, phet-io, Tandem, IOType, Checkbox | Status: complete
========================================================================

# Wiring Up a New PhET-iO Instrumented Control

**Task:** a new UI control (a checkbox, a custom button, a new kind of control class) needs to be visible to PhET-iO — addressable by name, saved/restored in state, and controllable from a wrapper — instead of existing only as an opaque, uninstrumented view element.

For the overwhelming majority of controls, this is entirely about **plumbing a real `Tandem` down to the control and to the `Property` it operates on** — see [The PhET-iO Instrumentation Pattern](/patterns/phet-io-instrumentation-pattern) for the underlying convention. You reach for a hand-written [`IOType`](/api/tandem/io-type) only in the much rarer case where the control's own state isn't already fully expressed by instrumented `Property`s it wraps.

## The common case: a `sun` control with a real `Tandem`

```ts
import { Checkbox } from 'scenerystack/sun';
import { BooleanProperty } from 'scenerystack/axon';
import { Text } from 'scenerystack/scenery';
import { Tandem } from 'scenerystack/tandem';

class MyScreenModel {
  public readonly soundEnabledProperty: BooleanProperty;

  public constructor( tandem: Tandem ) {
    this.soundEnabledProperty = new BooleanProperty( true, {
      tandem: tandem.createTandem( 'soundEnabledProperty' ),
      phetioDocumentation: 'Whether interaction sounds are enabled for this screen.'
    } );
  }
}

class MyScreenView /* extends ScreenView */ {
  public constructor( model: MyScreenModel, viewTandem: Tandem ) {
    const soundCheckbox = new Checkbox(
      model.soundEnabledProperty,
      new Text( 'Sound' ),
      {
        tandem: viewTandem.createTandem( 'soundCheckbox' )
      }
    );
    // this.addChild( soundCheckbox );
  }
}
```

`soundEnabledProperty`'s own `BooleanIO` (its built-in `IOType`) is what actually gets serialized into PhET-iO state — `soundCheckbox`'s `tandem` mainly makes the *view element itself* addressable (so a wrapper can, for example, simulate a click on it), while the `Property`'s tandem is what makes the underlying *state* saveable and restorable. Both matter, and both come from the same `tandem.createTandem(...)` calls threaded down from the screen, exactly as in [The PhET-iO Instrumentation Pattern](/patterns/phet-io-instrumentation-pattern).

## Checklist for a new control

| Step | Why |
| --- | --- |
| Pass a real `tandem: someParentTandem.createTandem( 'meaningfulName' )`, not `Tandem.REQUIRED` left unfilled | `Tandem.REQUIRED` is a sentinel that asserts in a validated PhET-iO build if never overridden — see [Tandem](/api/tandem/tandem) |
| Give the `Property` the control operates on its own child tandem, named for what it represents | This is the actual state PhET-iO saves/restores/exposes to clients — the control's own tandem exposes the *element*, not the state |
| Add `phetioDocumentation` to the `Property` | Shown to PhET-iO clients in Studio; describe what the value means, not how it's implemented |
| Only reach for a custom `IOType` if the control holds state that isn't already an instrumented `Property` | See below — most controls never need this |

## When a custom control does need its own `IOType`

A hand-written [`IOType`](/api/tandem/io-type) is for classes that hold state PhET-iO needs to serialize but that isn't already expressed as instrumented child `Property`s — for example, a dynamic-element container. If your new control is a plain composition of already-instrumented `Property`s (as above), skip this section; you don't need it.

```ts
import { IOType, NumberIO } from 'scenerystack/tandem';

type DialSettingStateObject = { angleDegrees: number };

// Only needed if DialControl's meaningful state ISN'T already exposed via
// an instrumented child Property.
const DialControlIO = new IOType<DialControl, DialSettingStateObject>( 'DialControlIO', {
  valueType: DialControl,
  documentation: 'A rotary dial control, expressed as its angle in degrees.',
  stateSchema: {
    angleDegrees: NumberIO
  },
  toStateObject: dial => ( { angleDegrees: dial.angleDegrees } ),
  applyState: ( dial, state ) => {
    dial.angleDegrees = state.angleDegrees;
  }
} );
```

Pass this as the `phetioType` option on the control's constructor (a `PhetioObject` option, inherited by every `Node`) once it exists.

::: tip Uninstrumented is the safe default while a control is still being built
It's fine to leave a control's `tandem` at its default while iterating on behavior — instrument it once the control's shape has stabilized. Adding instrumentation later is cheap; removing instrumentation a PhET-iO wrapper has already come to depend on is a breaking change. See the tip in [The PhET-iO Instrumentation Pattern](/patterns/phet-io-instrumentation-pattern#deciding-what-to-instrument).
:::

::: warning Renaming a tandem after release breaks existing wrappers
Once a control's tandem name has shipped, treat it as a stable public identifier — a wrapper or a saved PhET-iO state file addresses the element by its `phetioID`, so renaming `soundCheckbox` to `soundToggle` later is exactly as breaking as renaming a public API method.
:::


========================================================================
Page: Authoring Guide
URL: https://veillette.github.io/Almanach/meta/authoring-guide
Source: docs/meta/authoring-guide.md
Category: Meta | Tags: conventions, frontmatter, contributing | Status: complete
========================================================================

# Authoring Guide

Almanach is designed to grow to hundreds of documents without any configuration edits. Everything — the sidebar, `llms.txt`, `llms-full.txt`, and `manifest.json` — is generated from the Markdown files and their frontmatter. Follow the conventions below and your page appears everywhere automatically.

If you're looking for open work rather than writing an ad hoc page, see [the Roadmap](/meta/roadmap#open-work) first — it tracks what's still `draft`, what's missing cross-links, and other concrete gaps.

## Adding a page

1. Create a `.md` file in the folder matching its category (see taxonomy below); for `api/`, also pick the library subfolder. Use kebab-case filenames: `model-view-transform.md`. [`meta/page-template.md`](/meta/page-template) is a copy-pasteable starting point.
2. Fill in the required frontmatter (schema below).
3. Run `npm run generate` — it validates every page and regenerates the LLM artifacts, failing loudly on schema violations.
4. Preview with `npm run dev`.

## Folder taxonomy

| Folder | Contents |
| --- | --- |
| `getting-started/` | Orientation, installation, first steps |
| `guides/` | Subsystem-level narrative walkthroughs — the layout system, the input system, localization, contributing. Broader in scope than `patterns`: explain how a whole subsystem works, not one narrow convention |
| `api/<library>/` | Reference pages for specific classes/functions, one subfolder per `scenerystack/*` subpath (`api/axon/`, `api/dot/`, `api/scenery/`, …) |
| `patterns/` | Narrow, prescriptive software patterns and architectural conventions — "how to structure X," one convention per page |
| `styling/` | Colors, typography, layout aesthetics, visual design conventions |
| `accessibility/` | PDOM, keyboard input, focus, voicing, sound-as-accessibility |
| `examples/` | Complete, runnable worked scenarios combining multiple concepts end-to-end |
| `cookbook/` | Short, task-oriented "how do I…" recipes that recombine already-documented APIs — narrower than `examples` (one task, not a full scenario) and more concrete than `patterns` (a recipe, not an architectural convention) |
| `meta/` | Documentation about Almanach itself |

New top-level folders may be added as Almanach grows; they appear in the sidebar automatically (add an entry to the `SECTIONS` maps in `docs/.vitepress/sidebar.ts` and `scripts/generate-llm-artifacts.ts` only to control their label and ordering).

**`api/` is subfoldered by library**, one directory per `scenerystack/*` subpath (e.g. `api/axon/property.md`, `api/scenery/node.md`). This is the one deliberate exception to "flat folder of pages": `api/` is expected to hold far more pages than any other category, across many distinct libraries, so it needs a second level of grouping to stay navigable. `docs/.vitepress/sidebar.ts`'s `collectPages` renders each library subfolder as its own collapsible sidebar group automatically — no config needed per library. Every other category stays flat.

Only document libraries that are simulation-author-facing. Internal build/branding subpaths (`chipper`, `perennial`, `brand`, `splash`, `init`, `assert`, `adapted-from-phet`) are out of scope.

## Frontmatter schema

Every page **must** begin with this frontmatter:

```yaml
---
title: ModelViewTransform2                  # required — page title, used in sidebar and indexes
description: One-sentence summary.          # required — shown in llms.txt and manifest.json
category: api                               # required — MUST equal the containing top-level folder name
library: phetcommon                         # required IFF category is "api" — MUST equal the containing subfolder name
tags: [dot, coordinates, transform]         # required — non-empty list of lowercase keywords (library names lowercase, class names PascalCase matching the real export)
status: complete                            # required — "stub" | "draft" | "complete" | "verified"
related:                                    # optional — unordered "see also", site-absolute paths
  - /patterns/model-view-separation
prerequisites:                              # optional — ordered "read this first", site-absolute paths
  - /getting-started/what-is-scenerystack
sourceRefs:                                 # optional — URLs grounding the page's technical claims
  - https://www.npmjs.com/package/scenerystack
---
```

`library` only applies to `api/` pages; omit it everywhere else.

### The `status` lifecycle

Four stages, each meaningful to an agent or human picking up work later:

| Status | Meaning |
| --- | --- |
| `stub` | Page is scaffolded (frontmatter + a one-paragraph placeholder) — reserves the topic so parallel writers don't duplicate it. Not yet real content. |
| `draft` | Full content is written, but not yet checked against the real SceneryStack source. |
| `complete` | Full content, internally consistent, the author is confident in it. |
| `verified` | `complete`, plus an independent pass has cross-checked the technical claims against real SceneryStack source or the [official reference](https://scenerystack.org/reference/). |

Progress is tracked by reading these real frontmatter values across the tree (see [the Roadmap](/meta/roadmap) and `npm run coverage:status`) — there is no separate hand-maintained checklist to keep in sync.

Validation rules (enforced by `npm run generate`, and by CI on every push):

- `title` and `description` are non-empty strings.
- `category` matches the top-level folder the file lives in.
- If `category` is `api`, `library` is required and must match the immediate subfolder.
- `tags` is a non-empty array of strings.
- `status` is one of `stub`, `draft`, `complete`, `verified`.
- Every `related` and `prerequisites` entry resolves to an existing document — broken cross-references fail the build.
- `sourceRefs`, if present, is an array of URL strings (not resolution-checked — they point outside Almanach).

VitePress additionally fails the build on dead Markdown links, so inline links like `[Drag Listeners](/patterns/drag-listeners)` are also checked.

## Writing style

- **One concept per page.** Small, focused pages retrieve better — for search engines, humans, and LLM context windows alike.
- **Lead with what and why**, then show a complete, runnable TypeScript snippet using real `scenerystack/*` imports.
- **Cross-link generously** with site-absolute paths (`/api/phetcommon/model-view-transform`), and mirror the most important links in `related` (unordered "see also") or `prerequisites` (ordered "read this first").
- Use tables for option/method summaries and `::: tip` / `::: warning` containers for the one thing readers must not miss.

## Live interactive demos

Some pages embed a real SceneryStack control via the globally registered `<SceneryDemo>` component (see `docs/.vitepress/theme/` and `docs/.vitepress/demos/`). Demos are **supplementary UI** — they do not replace the runnable TypeScript snippet above them. `llms-full.txt` and other generated indexes contain only Markdown; agents never execute the embed.

### When to add a demo

Add a live embed when the page documents an **interactive control** (button, slider, checkbox, composite control) where seeing or trying the widget helps more than reading options tables. Skip demos for non-visual APIs (`Range`, `Vector2`, model patterns, meta pages).

### Authoring a new demo

1. Create `docs/.vitepress/demos/<demo-id>.ts` exporting `createDemo( rootNode )` and optional `width` / `height`. Use `Tandem.OPTIONAL` (not `Tandem.REQUIRED`) — Almanach embeds are not PhET-iO instrumented sims.
2. Register the id in `docs/.vitepress/demos/registry.ts`.
3. Add `<SceneryDemo demo="<demo-id>" />` to the Markdown page **after** its primary code snippet.
4. Run `npm run demos:check` and `npm run build`.

`createDemo` must return a dispose function that tears down listeners, Properties, and Nodes — see [Dispose and Memory Management](/patterns/dispose-and-memory-management). Use helpers in `docs/.vitepress/demos/shared/` for common layout (centering in the fixed-size canvas via `centerInDisplay`).

Fixed canvas dimensions (typically 400×120–180) prevent layout shift in the VitePress page chrome. Demos load SceneryStack **client-side only** via dynamic `import()`; do not add static `scenerystack/*` imports to theme components.

Almanach pins `scenerystack@3.0.0` as a devDependency for demos; bump it together with [SceneryStack Version Compatibility Notes](/meta/scenerystack-version-compatibility).

## Generated artifacts

`npm run generate` (also run automatically as part of `npm run build`) writes three files into `docs/public/`, which are served at the site root:

| File | Contents |
| --- | --- |
| `/llms.txt` | Per-page links + descriptions, grouped by category ([llms.txt convention](https://llmstxt.org/)) |
| `/llms-full.txt` | Full text of every page with source-path headers |
| `/manifest.json` | All frontmatter metadata plus URLs and word counts |

These files are committed to the repository so agents browsing GitHub get them without a build step; regenerate them whenever content changes (CI verifies the build regardless).


========================================================================
Page: FAQ
URL: https://veillette.github.io/Almanach/meta/faq
Source: docs/meta/faq.md
Category: Meta | Tags: faq, conventions, contributing | Status: complete
========================================================================

# FAQ

## Is this the same as PhET Simulations?

No, though they're closely related. [PhET Interactive Simulations](https://phet.colorado.edu) is the project that publishes the free interactive science/math sims at phet.colorado.edu. **SceneryStack** is the open-source TypeScript framework PhET built those sims on top of and later packaged for outside use — a scene graph, a reactive-state library, UI components, and an application shell (see [What is SceneryStack?](/getting-started/what-is-scenerystack)). **Almanach** documents SceneryStack, the framework, for anyone building their own interactive with it — not the PhET sims themselves, and not the PhET organization's internal engineering conventions beyond what's needed to use the published package.

## Do I need to know PhET's internal repo structure to use scenerystack?

No. The published `scenerystack` npm package re-exports the simulation-author-facing parts of PhET's many internal repositories as flat subpaths (`scenerystack/scenery`, `scenerystack/axon`, …) — you don't need to know that `Sim`/`ScreenView` originate in a repo called `joist`, or that the package bundles work from a dozen-plus separate source repositories at all. Almanach deliberately keeps to that same boundary: per [the Roadmap](/meta/roadmap), internal build/branding/rendering-primitive subpaths (`chipper`, `perennial`, `brand`, `splash`, `init`, `assert`, `adapted-from-phet`, `alpenglow`) are explicitly out of scope for documentation here, because they're not part of the simulation-author-facing surface.

## Which package version does Almanach document?

`scenerystack` **v3.0.0** (see [`npmjs.com/package/scenerystack`](https://www.npmjs.com/package/scenerystack)). Code samples throughout Almanach use real imports checked against that version's source. If you're using a materially newer or older major version, treat class/option names here as a strong starting point, not a guarantee — check the [official reference](https://scenerystack.org/reference/) for anything version-sensitive, and see [SceneryStack Version Compatibility Notes](/meta/scenerystack-version-compatibility) for when a re-verification pass is due.

## How current is this documentation?

It varies page by page, by design. Every page carries a `status` of `stub`, `draft`, `complete`, or `verified` in its frontmatter — `stub` reserves a topic with placeholder content, `draft` is fully written but not yet checked against real source, `complete` is internally consistent and confident, and `verified` has had an independent pass cross-check its technical claims against real SceneryStack source or the official reference. See [the Authoring Guide](/meta/authoring-guide#the-status-lifecycle) for the full lifecycle, and [the Roadmap](/meta/roadmap#open-work) for how many pages currently sit at each status and what's still open.

## Is this an official SceneryStack or PhET resource?

Treat it as a community-maintained reference grounded in the real published package and the official [scenerystack.org/reference](https://scenerystack.org/reference/) site, rather than assuming it's the canonical source — when Almanach and the official reference disagree, the official reference wins. Every page's `sourceRefs` frontmatter field (where present) links to what its technical claims were checked against.

## Can I use SceneryStack outside of a PhET-style multi-screen sim?

Yes — `scenery` (the scene graph) and the reactive-state libraries (`axon`, `dot`) are usable as a standalone rendering/state library without `joist`'s `Sim`/`Screen` application shell at all. See [Scenery Application vs. Standalone Library](/getting-started/scenery-application-vs-standalone-library) for the two shapes and when to reach for each, and [Standalone Scenery App Example](/examples/standalone-scenery-app-example) for a worked example.

## Why do some libraries only have a page or two, while others (axon, scenery) have dozens?

Coverage is intentionally uneven rather than uniform, per [the Roadmap](/meta/roadmap): the libraries most simulation authors touch daily (`axon, dot, kite, scenery, sun, scenery-phet, joist, twixt, tandem, phetcommon`) go deepest, at a "most commonly used classes" depth. A handful of real-but-less-explored libraries (`tambo, bamboo, vegas, mobius, utterance-queue, phet-core, query-string-machine, nitroglycerin, tappi`) only have first-pass coverage, and some of their pages are lower-confidence until independently verified — check a given page's `status` before treating it as settled.

## Why does a page say `status: draft` or `status: stub` instead of finished content?

Both are intentional, visible markers, not an oversight — see [The `status` lifecycle](/meta/authoring-guide#the-status-lifecycle). A `stub` reserves a topic so parallel contributors don't duplicate it; a `draft` is complete prose that simply hasn't had its technical claims checked against real source yet. Neither means "ignore this page," but both mean "verify anything load-bearing yourself before relying on it," especially for a `sourceRefs` link pointing only at the npm package listing rather than a specific verified detail.

## How do I contribute a page, or fix something wrong on an existing one?

Read [the Authoring Guide](/meta/authoring-guide) for the frontmatter schema and folder taxonomy, then [the Roadmap](/meta/roadmap#open-work) for what's already covered versus open. Every page's frontmatter and cross-links are validated by `npm run generate` (and by CI), so a page that doesn't follow the schema, or that links to a path that doesn't exist, fails the build loudly rather than silently shipping broken.

## Where do I report a bug in SceneryStack itself, as opposed to Almanach?

Almanach doesn't own SceneryStack's source — file framework bugs against the upstream project (see the `bugs`/`homepage` links on [the npm package page](https://www.npmjs.com/package/scenerystack)), and reserve issues in Almanach's own repository for problems with the documentation itself (a wrong claim, a broken cross-link, a missing page).

## My import or build isn't working — is that covered here?

Almanach documents the API surface, not project setup and tooling failures — for those, see [Troubleshooting Common Setup Errors](/getting-started/troubleshooting-common-setup-errors) (Node version mismatches, wrong import subpaths, `tsconfig.json` module resolution) and [Supported Browsers](/getting-started/supported-browsers) for platform-level compatibility questions.

## Is Almanach usable by an LLM agent, not just a human?

Yes, deliberately. `npm run generate` writes `/llms.txt` (per-page links and descriptions), `/llms-full.txt` (the full text of every page), and `/manifest.json` (all frontmatter plus computed metadata) into the site root, so an agent can fetch a single file for the whole knowledge base's content instead of crawling pages one at a time — see [Generated artifacts](/meta/authoring-guide#generated-artifacts).

::: tip Start at "What is SceneryStack?" if you're new to the framework itself
This FAQ assumes you already know roughly what SceneryStack is; if you don't, [What is SceneryStack?](/getting-started/what-is-scenerystack) is the actual starting point, with [the Glossary](/meta/glossary) as a reference for any unfamiliar term you hit along the way.
:::


========================================================================
Page: Glossary
URL: https://veillette.github.io/Almanach/meta/glossary
Source: docs/meta/glossary.md
Category: Meta | Tags: glossary, reference, terminology, conventions | Status: complete
========================================================================

# Glossary

Definitions for terms Almanach uses repeatedly without re-explaining every time. Each entry links to the page where the concept is covered in full — this page is for "what does that word mean," not a replacement for reading the linked page.

## accessibleHelpText

Supplementary guidance announced alongside an element's `accessibleName`, for detail the visible label doesn't already convey. Supplements the accessible name; it never replaces it. See [Accessible Control Panel Example](/examples/accessible-control-panel-example).

## accessibleName

The string a screen reader announces for a focusable element in the PDOM — the accessibility equivalent of a visible label, set as a `Node` option. See [The Parallel DOM](/accessibility/pdom).

## brand

A build-time flag (`phet` vs. `phet-io`, among others) that determines which features compile into a sim — notably whether PhET-iO instrumentation is active. See [Tandem](/api/tandem/tandem).

## DerivedProperty

A read-only `Property` whose value is automatically recomputed from one or more other Properties whenever any of them change — you never call `.value =` on it yourself. See [DerivedProperty](/api/axon/derived-property) and [Emitter vs. Property](/patterns/emitter-vs-property).

## dispose()

The explicit cleanup method every long-lived `Node`/`Property`/`DerivedProperty`/`Multilink`/`PhetioObject` exposes, since SceneryStack has no framework-managed component lifecycle — objects created and destroyed dynamically must be disposed, or they (and anything they linked to) leak. See [Dispose and Memory Management](/patterns/dispose-and-memory-management).

## Display

The scenery object that owns a root `Node`, drives the render loop, and turns the scene graph into pixels (and the PDOM into real DOM). See [Display](/api/scenery/display).

## DragListener

A pointer-only (mouse/touch/pen) input listener that writes to a model `positionProperty`, typically through a `transform`. Superseded for new code by `RichDragListener`, which adds keyboard support. See [Drag Listeners](/patterns/drag-listeners).

## Emitter

An axon primitive for a momentary event with no persisted value — "did X just happen?" as opposed to a `Property`'s "what is it right now?" See [Emitter](/api/axon/emitter) and [Emitter vs. Property](/patterns/emitter-vs-property).

## EnumerationValue / Enumeration

The pattern for modeling a closed set of values (a mode, a phase) as real object instances with identity, instead of a string-literal union — gives runtime-validated `EnumerationProperty` writes and automatic PhET-iO serialization. See [The Enumeration Pattern](/patterns/enumeration-pattern).

## Hotkey

The lower-level building block behind `KeyboardListener` and `KeyboardDragListener`: a single dynamic key combination (optionally described by a `Property`) that can be registered directly on a Node's input listeners or on the shared `globalHotkeyRegistry`. See [Keyboard Input and Hotkeys](/accessibility/keyboard-input-and-hotkeys).

## KeyboardDragListener

The keyboard-driven equivalent of pointer dragging — moves a `positionProperty` with arrow keys or WASD. Composed together with `DragListener` inside `RichDragListener`. See [KeyboardDragListener](/api/scenery/keyboard-drag-listener).

## Model-View Separation

The foundational architecture every page in Almanach assumes: model classes hold state as `Property`/`Emitter` and know nothing about scenery; view classes (`Node` subclasses) observe that state and never hold state of their own. See [Model-View Separation](/patterns/model-view-separation).

## ModelViewTransform2

A `phetcommon` class mapping between a model coordinate frame and a view (pixel) coordinate frame, most often passed as the `transform` option to a drag listener. See [ModelViewTransform2](/api/phetcommon/model-view-transform).

## Multilink

A utility that observes several Properties at once and fires a single callback when any of them change, without manually chaining multiple `.link()` calls. See [Multilink](/api/axon/multilink) and [The Multilink Pattern](/patterns/multilink-pattern).

## Node

The base class of every visual (and, via the PDOM, every accessible) element in a scenery scene graph. See [Node](/api/scenery/node).

## options pattern / optionize

The convention of configuring a class through one trailing `providedOptions` object, merged with compile-time-checked defaults via `optionize`, rather than a positional-parameter list or ad hoc destructuring. See [The Options Pattern](/patterns/options-pattern).

## PDOM (Parallel DOM)

Scenery's hidden tree of real HTML elements, mirroring the scene graph's interactive structure, so screen readers and keyboard focus can operate on content that otherwise renders to Canvas/SVG/WebGL. See [The Parallel DOM (PDOM)](/accessibility/pdom).

## phet-io / PhET-iO

PhET's instrumentation and interoperability system: giving simulation elements a stable, addressable identity (via `Tandem`) so external wrappers can inspect, control, save, and restore sim state. See [The PhET-iO Instrumentation Pattern](/patterns/phet-io-instrumentation-pattern).

## PhetioObject

The base class (from `tandem`) that gives an object PhET-iO identity — a `Tandem`, serialization hooks, and lifecycle events — when it's instrumented. `Property`, `Node`, `Screen`, and `Sim` are all `PhetioObject`s. See [Tandem](/api/tandem/tandem).

## Property

A reactive container for a single value that persists between reads — the fundamental "state" primitive in axon, observed with `.link()` and read/written with `.value`. See [Property](/api/axon/property) and [Emitter vs. Property](/patterns/emitter-vs-property).

## query parameter

A URL parameter driving optional or debug-only sim behavior, declared through a single schema object and parsed via `QueryStringMachine.getAll`, rather than reading `location.search` ad hoc. See [Query Parameters Pattern](/patterns/query-parameters-pattern).

## Reset-All Pattern

The convention that every screen has exactly one `ResetAllButton`, whose listener calls exactly one method: the model's own `reset()`. See [The Reset-All Pattern](/patterns/reset-all-pattern).

## RichDragListener

The recommended default for new draggable code: composes an internal `DragListener` and `KeyboardDragListener` behind one `TInputListener`-implementing API, giving pointer and keyboard support from a single declaration. See [RichDragListener](/api/scenery/rich-drag-listener) and [Migrating a Legacy Sim to RichDragListener](/examples/migrating-to-rich-drag-listener).

## Screen

One self-contained model/view pair within a `Sim` — owns its own `Tandem` subtree, `homeScreenIcon`, `navigationBarIcon`, and translated `name`. See [Multi-Screen Sim Structure](/patterns/multi-screen-sim-structure) and [Screen](/api/joist/screen).

## ScreenView

The root `Node` of a `Screen`'s view; defines `layoutBounds` and reserves its own PDOM structure (`pdomPlayAreaNode`, `pdomControlAreaNode`) that a subclass populates rather than replaces. See [ScreenView](/api/joist/screen-view).

## Sim

The application shell that owns a list of `Screen`s, builds the home screen and navigation bar once there's more than one, and drives the top-level step loop. See [Sim](/api/joist/sim).

## Tandem

The naming-tree node that gives every PhET-iO-tracked element a stable, hierarchical address (`mySim.myScreen.model.temperatureProperty`), built up by calling `createTandem()` down through a model/view's constructors. See [Tandem](/api/tandem/tandem).

## TInputListener

The scenery interface every input listener implements (`DragListener`, `PressListener`, `KeyboardListener`, `RichDragListener`, …), letting pointer and keyboard/AT events dispatch through one shared mechanism instead of separate code paths per input modality. See [Alternative Input Overview](/accessibility/alternative-input-overview).

## Trail

An ordered path of `Node`s from a root to a descendant, used to disambiguate which instance of a `Node` is meant when a scene graph is a DAG rather than a strict tree — handed to you on every input event as `event.trail`. See [Trail](/api/scenery/trail).

## Voicing

PhET's speech-synthesis feature, layered on top of the PDOM rather than replacing it: an opt-in preference that speaks `voicingNameResponse`/`voicingObjectResponse`/`voicingContextResponse`/`voicingHintResponse` content aloud in response to interaction. See [Voicing](/accessibility/voicing).


========================================================================
Page: Page Template
URL: https://veillette.github.io/Almanach/meta/page-template
Source: docs/meta/page-template.md
Category: Meta | Tags: template, contributing, conventions | Status: complete
========================================================================

# Page Template

Copy the block below into a new file, fill it in, and delete anything that doesn't apply. See [the Authoring Guide](/meta/authoring-guide) for the full schema and folder taxonomy, and [the Roadmap](/meta/roadmap) if this page is claiming planned work.

## Frontmatter to copy

```yaml
---
title: ExactClassOrConceptName
description: One sentence: what this is and why it matters.
category: getting-started            # must equal the top-level folder this file lives in
# library: axon                      # required only when category is "api" — must equal the api/<library>/ subfolder
tags: [lowercase, keywords, PascalCaseClassNames]
status: stub                         # stub -> draft -> complete -> verified as the page matures
# related:
#   - /patterns/some-other-page
# prerequisites:
#   - /getting-started/what-is-scenerystack
# sourceRefs:
#   - https://www.npmjs.com/package/scenerystack
---
```

## Section skeleton

```md
# Title

One or two sentences: what this is, and why a reader should care. Lead with
the "what and why," not a history lesson.

## The core idea / a minimal example

A complete, runnable TypeScript snippet using real `scenerystack/*` subpath
imports — not pseudocode.

\`\`\`ts
import { Something } from 'scenerystack/some-library';
\`\`\`

## Options / methods (if applicable)

| Option | Effect |
| --- | --- |
| `exampleOption` | What it does |

::: tip One thing readers must not miss
Use a `::: tip` or `::: warning` container for the single most important
caveat — not a wall of bullet points.
:::
```

## Checklist before setting `status: complete`

- One concept per page — if you're covering two unrelated ideas, split the file.
- At least one complete, runnable code snippet using real imports.
- Cross-links added both as inline Markdown links and mirrored in `related`/`prerequisites`.
- `npm run generate` passes (frontmatter schema + no dead `related`/`prerequisites` links).
- If this is an `api/` page and you're not fully certain of the class's real shape, leave `status: draft` and add a `sourceRefs` entry so a later `verified` pass has something to check against.


========================================================================
Page: Roadmap
URL: https://veillette.github.io/Almanach/meta/roadmap
Source: docs/meta/roadmap.md
Category: Meta | Tags: roadmap, planning, contributing, conventions | Status: complete
========================================================================

# Roadmap

Almanach covers 19 simulation-author-facing `scenerystack/*` libraries across 9 top-level categories (`getting-started`, `guides`, `api`, `patterns`, `styling`, `accessibility`, `examples`, `cookbook`, `meta`) — 423 pages as of this writing. Run `npm run coverage:status` at any time for a live count broken down by category/library and frontmatter `status`.

**This document does not itself write the content.** It explains the taxonomy so a new page lands in the right place, and lists the concrete work still open so a contributor (human or agent) can pick something up instead of guessing.

## Taxonomy

- `getting-started/`, `patterns/`, `styling/`, `accessibility/`, `guides/`, `examples/`, and `meta/` are flat folders, one file per concept.
- **`api/` is subfoldered by library**: `api/axon/`, `api/dot/`, `api/scenery/`, etc. — one directory per `scenerystack/*` subpath. `docs/.vitepress/sidebar.ts` renders each subfolder as its own collapsible group automatically.
- **`cookbook/`** holds short, task-oriented "how do I…" recipes, one recipe per page, that recombine APIs documented elsewhere rather than introducing new ones. Narrower than `examples` (a full worked scenario) and more concrete than `patterns` (an architectural convention).

Full rationale and the frontmatter schema (`library`, `prerequisites`, `sourceRefs`, and the 4-stage `status` enum) live in [the Authoring Guide](/meta/authoring-guide) — read that before writing a page, this document is about *what's covered and what's missing*, not *how to write a page*.

**In-scope libraries** (confirmed against the installed `scenerystack` package's `exports` map and source): `axon, dot, kite, scenery, sun, scenery-phet, joist, twixt, tandem, phetcommon, tambo, bamboo, vegas, mobius, nitroglycerin, utterance-queue, phet-core, query-string-machine, tappi`. `adapted-from-phet, alpenglow, assert, brand, chipper, init, perennial, sim, splash` are internal build/branding/rendering-primitive concerns and are **out of scope** — don't create `api/<one of these>/` folders for them.

Coverage depth is intentionally uneven: the libraries most simulation authors touch daily (`axon, dot, kite, scenery, sun, scenery-phet, joist, twixt, tandem, phetcommon`) go deepest; libraries like `mobius`, `nitroglycerin`, and `tappi` have only first-pass coverage of their most central classes. Almanach documents "the classes and patterns a simulation author actually reaches for," not every export — `scenery` and `scenery-phet` alone have several hundred exports each, most of them internal helpers, string modules, or image/audio assets that don't warrant their own page.

## How to contribute a page

1. Read [the Authoring Guide](/meta/authoring-guide) and [the Page Template](/meta/page-template).
2. Run `npm run coverage:status` to see per-category/library page counts and which pages are still `stub`/`draft`, and check [Open work](#open-work) below for known gaps.
3. If you're adding coverage for a class not yet documented, verify it actually exists and matches your description by checking https://scenerystack.org/reference/ or introspecting the installed `scenerystack` package — don't invent plausible-sounding names.
4. Create the file with `status: stub` first if you're not finishing it in one pass — this reserves the topic for parallel contributors without claiming false completeness.
5. Write the page following the Authoring Guide's conventions (one concept, a real runnable snippet, cross-links). Move `status` to `draft`, then `complete` once you're confident, citing `sourceRefs` for anything you had to look up.
6. Run `npm run generate` (frontmatter + cross-link validation) and `npm run build` (adds dead-link checking) before considering a page done.

There is no separate checklist to tick — progress is read directly from frontmatter `status` values across the tree via `npm run coverage:status`. Don't hand-maintain a duplicate progress list; it will drift.

## Open work

- **Independent verification pass**: 182 pages are `status: complete` but haven't yet had an independent pass cross-check their technical claims against real SceneryStack source (`status: verified`). Highest concentrations: `api/scenery-phet/*`, `api/sun/*`, and `cookbook/*`. `npm run coverage:status` prints the live count — pick a library folder or category cluster and verify 5–10 pages at a time.
- **Cross-link gaps**: `npm run coverage:status` reports live counts for pages missing `prerequisites` or `sourceRefs` (most remaining `sourceRefs` gaps are `meta/*` pages, which intentionally don't cite SceneryStack source). `related` is fully populated across the tree.
- **Re-verification against newer `scenerystack` releases**: Almanach's content was checked against `scenerystack@3.0.0`; see [SceneryStack Version Compatibility Notes](/meta/scenerystack-version-compatibility) for what to do once a newer major version ships.
- **Deeper class-level coverage**: each in-scope library has more real exports than Almanach documents (internal helpers and asset modules aside). Find genuine gaps by introspecting the installed package (read its `src/<lib>.ts` barrel file, or inspect https://scenerystack.org/reference/) and cross-checking against what's already documented before adding a page.
- The 5 `meta/*` pages (`authoring-guide`, `faq`, `glossary`, `page-template`, this file) stay at `complete` rather than `verified` — that status is about checking claims against SceneryStack source, which doesn't apply to pages that are about Almanach itself.


========================================================================
Page: SceneryStack Version Compatibility Notes
URL: https://veillette.github.io/Almanach/meta/scenerystack-version-compatibility
Source: docs/meta/scenerystack-version-compatibility.md
Category: Meta | Tags: conventions, versioning, sourceRefs, contributing | Status: complete
========================================================================

# SceneryStack Version Compatibility Notes

Almanach documents the published `scenerystack` npm package, not a specific PhET source checkout — but "the published package" is a moving target. This page records which version backs Almanach's content, so a reader (or a contributor picking up further work) can tell how much to trust a given page's specifics against whatever `scenerystack` version they're actually running.

::: tip Almanach embeds SceneryStack for live demos
Almanach's `package.json` includes a pinned `scenerystack@3.0.0` devDependency used only by the optional `<SceneryDemo>` embeds on select pages. Prose and code snippets remain the source of truth for agents; the version note below describes what content was checked against during authoring.
:::

## What's verified against which version

Every `api/` page and most narrative pages in Almanach were checked — directly, by inspecting the installed package's `exports` map and TypeScript source, not by assumption — against `scenerystack@3.0.0` (see [the FAQ](/meta/faq#which-package-version-does-almanach-document)). A page whose `status` is `verified` had its technical claims independently cross-checked against that same source; Almanach has not (yet) been re-verified against a subsequent major release.

## When to revisit a page's status/sourceRefs

`scenerystack` is under active development; nothing here should be read as "this documents SceneryStack, forever." Treat each of these as a signal that a page needs re-checking, not just a version bump:

- **A new `scenerystack` major (or minor with breaking changes) release ships.** Renamed classes, changed default option values, and removed/added exports are exactly the class of inaccuracy an independent verification pass is built to catch — a new release re-opens that risk for any page whose claims were checked against the old version.
- **A page is still `draft`, not `complete`/`verified`.** Per [the `status` lifecycle](/meta/authoring-guide#the-status-lifecycle), `draft` already means "not yet checked against real source" — such a page should be checked against the *current* published version when someone picks it up, not necessarily `3.0.0` specifically. See [the Roadmap's open work](/meta/roadmap#open-work) for the current list of `draft` pages.
- **A page's `sourceRefs` only points at the generic npm package page**, rather than a specific class/source file or the official reference — that's a weaker citation than a page whose `sourceRefs` links to something checkable line-by-line, and is a lower-priority but real candidate for a future tightening pass.
- **The [official reference](https://scenerystack.org/reference/) disagrees with Almanach.** As [the FAQ](/meta/faq#is-this-an-official-scenerystack-or-phet-resource) already states, the official reference wins in any disagreement — treat that as a signal the page is stale for the version currently in use, not that the reference is wrong.

## What a future re-verification pass should do

A version-driven re-verification pass (triggered by a SceneryStack release rather than being the first pass) should:

1. Note the new version's number here, alongside `3.0.0`, once a meaningful fraction of Almanach has actually been re-checked against it — don't bump the version claimed above until the content backs it up.
2. Prioritize `api/` pages over narrative pages — class shapes, option names, and defaults are exactly what a version bump is most likely to change, where `patterns`/`guides`/`styling`/`accessibility` content tends to describe conventions that outlive a specific release.
3. Downgrade a page's `status` from `verified` back to `draft` (never leave it silently `verified` against stale claims) if re-checking surfaces a real discrepancy, and cite the new `sourceRefs` once corrected — consistent with how [the Authoring Guide](/meta/authoring-guide#the-status-lifecycle) defines what each status actually promises a reader.

::: warning `verified` describes a point-in-time check, not an ongoing guarantee
A `verified` page was checked against `scenerystack@3.0.0` at some point — it is not automatically re-checked when a new version ships. Nothing in Almanach's tooling currently detects "this page's claims are now stale because the package moved on"; that detection is exactly the gap this page exists to flag until a version-driven re-verification pass (see above) actually happens.
:::