@chris.araneo/cassette-canvas 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Krzysztof Pająk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,358 @@
-# Temporary Holding Version
+<h1 align="center">Cassette Canvas</h1>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">
+  <img src="https://raw.githubusercontent.com/ChrisAraneo/cassette-canvas/master/cassette.png" width="512px" height="256px"/>
+  <br>
+  <a href="https://github.com/ChrisAraneo/cassette-canvas/blob/master/package.json"><img src="https://img.shields.io/badge/version-v0.2.0-blue" alt="version"></a>
+  <a href="https://github.com/ChrisAraneo/cassette-canvas/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="@chris.araneo/cassette-canvas is released under the MIT license."></a>
+  <a href="https://github.com/ChrisAraneo/cassette-canvas/actions/workflows/ci.yml"><img alt="GitHub CI Status" src="https://img.shields.io/github/actions/workflow/status/ChrisAraneo/cassette-canvas/ci.yml?label=CI&logo=GitHub"></a>
+  <br>
+  <br>
+  <em>Retro rendering engine for the HTML canvas.</em>
+  <br>
+  <br>
+</p>
+
+- Sprites use 16 colors with 8 shades each (128 colors).
+- Pixels are large, and every sprite has the same size.
+- Ambient light and point lights use a scale of 32 shades per color. Sprites can cast shadows.
+- Retro monitor effect is always on: a soft glow around bright pixels, scanlines, film grain and a surface texture.
+
+## Installation
+
+```sh
+npm install @chris.araneo/cassette-canvas
+```
+
+The package is an ES module with TypeScript types included. It runs in the
+browser and needs WebGL.
+
+## Concepts
+
+| Concept            | Meaning                                                                                                                                                                                   |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Base colors**    | The 16 colors you provide, as `#rrggbb`.                                                                                                                                                  |
+| **Shade**          | Sprites can use 8 shades of each color (0 to 7). Shade 4 (`BASE_SHADE`) is the base color. Shades 0 to 3 are darker and 5 to 7 are lighter.                                               |
+| **Extended shade** | Lighting uses 32 shades of each color (0 to 31). 4 extended shades = 1 shade. The palette holds all 16 × 32 = 512 colors.                                                                 |
+| **Pixel**          | A number with the color in the high hex digit and the shade in the low hex digit. `0x35` is color 3, shade 5. `TRANSPARENT` (`-1`) draws nothing.                                         |
+| **Pixel size**     | The size of one logical pixel in canvas pixels, for example `4`. The screen size in logical pixels is the canvas size divided by the pixel size.                                          |
+| **Sprite**         | A flat array of `spriteSize × spriteSize` pixels, row by row from the top left.                                                                                                           |
+| **Screen**         | Immutable data: the background, sprites, lights and ambient light. Later sprites are drawn over earlier ones.                                                                             |
+| **Display**        | The canvas, its WebGL context, the monitor shader and the palette. You create it once.                                                                                                    |
+| **Ambient light**  | Shifts every pixel by a number of extended shades. `0` keeps the authored colors. `-16` (4 shades darker) looks like night.                                                               |
+| **Light**          | A point at `row`, `column`. At its center it lifts a pixel that daylight already lights by `intensity` extended shades, fading to nothing at `radius`.                                    |
+| **Stop**           | One doubling of light, worth `EXTENDED_SHADES_PER_STOP` (4) extended shades. Lights are added as light and then read off this scale, the way the eye does.                                |
+| **Shadow**         | A sprite with `castsShadow: true` blocks light. Pixels behind it get no light from that light, and the shadow's edge ramps rather than steps. Its side that faces the light is still lit. |
+| **Monitor effect** | A shader that adds a 2-pixel glow, scanlines, film grain and a surface texture. It uses full RGB color, not the palette.                                                                  |
+
+## Usage
+
+```ts
+import {
+  addLight,
+  addSprite,
+  createScreen,
+  drawScreen,
+  patchAmbient,
+  patchLight,
+  patchLightByOffset,
+  patchSprite,
+  patchSpriteByOffset,
+  toPixel,
+  toSprite,
+  tryCreateDisplay,
+} from '@chris.araneo/cassette-canvas';
+import { constant, noop, times } from 'lodash-es';
+import { pipe } from 'remeda';
+import { match, P } from 'ts-pattern';
+
+const display = tryCreateDisplay(canvas, {
+  colors: [
+    '#7f7f7f',
+    '#d23c3c',
+    '#e07a2e',
+    '#e6c23a',
+    '#98c93c',
+    '#3d9e4a',
+    '#2e9c8f',
+    '#3bb4d6',
+    '#4a8fe0',
+    '#3c56c8',
+    '#5b42c2',
+    '#8a45c8',
+    '#c045b4',
+    '#e0608f',
+    '#8c5a36',
+    '#d4a373',
+  ],
+  pixelSize: 4,
+  spriteSize: 8,
+});
+
+const HEART = toSprite(
+  [
+    '........',
+    '.rr..rr.',
+    'rRRrrrrr',
+    'rRrrrrrr',
+    '.rrrrrr.',
+    '..rrrr..',
+    '...rr...',
+    '........',
+  ],
+  { r: toPixel(1, 4), R: toPixel(1, 6) },
+);
+
+const screen = addSprite(createScreen(toPixel(10, 0)), 'heart', HEART, 20, 30);
+const moved = patchSpriteByOffset(screen, 'heart', 0, 5); // 5 pixels right
+const placed = patchSprite(moved, 'heart', { row: 40, column: 60 });
+```
+
+Draw the screen once per animation frame. Pass the time in milliseconds; it
+animates the film grain. `display` can be `undefined`, so check it first:
+
+```ts
+const { nonNullable } = P;
+
+requestAnimationFrame((time) =>
+  match(display)
+    .with(nonNullable, (ready) => drawScreen(ready, placed, time))
+    .otherwise(noop),
+);
+```
+
+`tryCreateDisplay` returns `undefined` if:
+
+- the canvas has no WebGL context,
+- the monitor shader cannot be set up,
+- `pixelSize` or `spriteSize` is not a positive whole number,
+- the canvas is smaller than one logical pixel.
+
+See [`apps/demo/src/main.ts`](https://github.com/ChrisAraneo/cassette-canvas/blob/master/apps/demo/src/main.ts)
+for a full animation loop.
+
+### Lights and shadows
+
+Sprites use 8 shades per color. Lighting uses 32 extended shades per color
+(`EXTENDED_SHADE_COUNT`). Shade `s` is extended shade `4 × s + 1`. Extended
+shade 0 is darker than shade 0, and extended shades 30 and 31 are lighter than
+shade 7. Only light can reach them.
+
+```
+extended  0  1  2  3  4  5 … 17 … 29 30 31
+shade        0           1    4    7
+             ↑ darkest            ↑ lightest a sprite can use
+```
+
+Light never changes a pixel's color, only its shade. Ambient light and light
+intensities are written in extended shades
+(`EXTENDED_SHADES_PER_SHADE` = 4 per shade), because that is what you see on
+screen. With ambient 0 and no lights, every pixel shows its authored color.
+
+**Lights add up as light, not as shade numbers.** Shade numbers are a
+brightness scale, and brightness scales do not add: a room with two lamps is
+not twice as bright to look at as a room with one. So the engine turns the
+ambient light and each light back into the amount of light behind it, adds
+those amounts, and reads the shade off the total. Every doubling of light is
+worth the same step on the scale, `EXTENDED_SHADES_PER_STOP` = 4 extended
+shades, which is how the eye reads brightness.
+
+What that gives you:
+
+- One light on an unlit scene moves a pixel by exactly its `intensity`, as it
+  always did.
+- A second light of the same intensity on the same spot adds one step, not
+  another full intensity. Ten lamps add a little over three steps.
+- A lamp in daylight hardly tells, and the same lamp at night carries the
+  whole scene. Nothing piles up into flat white, so sprites and tiles keep
+  their shading however many lights reach them.
+
+An `intensity` is therefore best read as _how many extended shades this light
+lifts a pixel that daylight already lights_. A lamp that is only there to
+light the night wants a small number, around 4 to 6; a flash or an explosion
+wants a large one. Ambient and intensity can be fractions; the total is
+rounded for each pixel and kept between extended shade 0 and 31.
+
+A light also thins out with distance the way light does in the world, so it
+leaves a bright core and a long dim halo rather than a flat disc, and the rim
+at `radius` fades out smoothly instead of ending in a visible circle.
+
+Shadow edges are soft. Every shadow carries a penumbra: its edge ramps from
+full light to full shadow over two pixels, the way an edge looks under a
+light that is not a single point. Only the edge softens, so the heart of a
+shadow stays as dark as it ever was and a shadow never fades out as it
+lengthens. `SHADOW_SOFTNESS` in `libs/engine/src/lighting/consts.ts` sets how
+far the ramp goes, and `0` brings back the hard edges of a point source.
+
+```ts
+const WALL = toSprite(times(8, constant('..oooo..')), { o: toPixel(0, 3) });
+
+const night = pipe(
+  createScreen(toPixel(8, 5), -16), // light-blue sky, 4 shades darker
+  (screen) => addSprite(screen, 'wall', WALL, 40, 60),
+  (screen) => patchSprite(screen, 'wall', { castsShadow: true }),
+  (screen) =>
+    addLight(screen, 'torch', {
+      row: 44,
+      column: 30,
+      radius: 40,
+      intensity: 5,
+    }),
+);
+
+const torchMoved = patchLightByOffset(night, 'torch', 0, 2);
+const flickered = patchLight(torchMoved, 'torch', { intensity: 4 });
+const dawn = patchAmbient(flickered, -3);
+```
+
+With ambient `-16` (night), that torch of intensity `5` lifts its core about
+18 extended shades above the night around it, a little past the authored
+colors, and fades back to night through many small steps. The same torch at
+noon lifts a pixel by 5. Flickering it down to `4` costs about 2 shades at
+the core, not 1, because near the center the light is strong and the eye
+notices less of it. A big number such as `16` is a flash or an explosion: it
+burns the core out to the lightest shade.
+
+A lit frame holds extended pixels:
+`toExtendedPixel(color, extendedShade)` = `color × 32 + extendedShade`. The
+palette is keyed by extended pixels. `toLitPixel(pixel, shadeOffset)` returns
+the extended pixel that a sprite pixel shows under that much light.
+`toLitPixel(pixel, 0)` returns its authored color.
+
+### API
+
+| Function                                                            | What it does                                                          |
+| ------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| `tryCreateDisplay(canvas, { colors, pixelSize, spriteSize })`       | Creates a display, or returns `undefined`                             |
+| `drawScreen(display, screen, time)`                                 | Draws the screen with the monitor effect and returns the display      |
+| `createScreen(background?, ambient?)`                               | Creates an empty screen (transparent, ambient `0` by default)         |
+| `addSprite(screen, id, sprite, row, column)`                        | Adds a sprite on top, replacing any sprite with the same id           |
+| `patchSprite(screen, id, { sprite?, row?, column?, castsShadow? })` | Changes a sprite's image (animation), position or shadow              |
+| `patchSpriteByOffset(screen, id, rowOffset, columnOffset)`          | Moves a sprite by an offset                                           |
+| `removeSprite(screen, id)`                                          | Removes a sprite                                                      |
+| `findSprite(screen, id)`                                            | Returns a sprite, or `undefined`                                      |
+| `addLight(screen, id, { row, column, radius, intensity })`          | Adds a light, replacing any light with the same id                    |
+| `patchLight(screen, id, { row?, column?, radius?, intensity? })`    | Changes a light                                                       |
+| `patchLightByOffset(screen, id, rowOffset, columnOffset)`           | Moves a light by an offset                                            |
+| `removeLight(screen, id)`                                           | Removes a light                                                       |
+| `findLight(screen, id)`                                             | Returns a light, or `undefined`                                       |
+| `patchAmbient(screen, ambient)`                                     | Sets the ambient light                                                |
+| `toSprite(rows, legend)`                                            | Builds a sprite from text art                                         |
+| `toPixel(color, shade)`                                             | Returns a pixel value                                                 |
+| `isPixel(value)`                                                    | Checks whether a value is a pixel                                     |
+| `toExtendedPixel(color, extendedShade)`                             | Returns an extended pixel                                             |
+| `toLitPixel(pixel, shadeOffset)`                                    | Returns the extended pixel a pixel shows under light                  |
+| `createPalette(colors)`                                             | Returns the 512 palette colors, keyed by extended pixel               |
+| `computeFrame(screen, spriteSize, width, height)`                   | Returns the lit frame as extended pixels, without drawing (for tests) |
+
+Screen functions never change the screen you pass in. They return a new one.
+
+## How drawing works
+
+`drawScreen` runs three steps:
+
+```
+screen
+  → computeFrame   draw the sprites, then apply light and shadows
+  → toFrameBytes   turn extended pixels into RGBA bytes
+  → drawCrt        upload the bytes as a texture and draw it with the shader
+```
+
+**`computeFrame`** fills the frame with the background and draws each sprite
+in order. It also records which pixels belong to sprites that cast shadows.
+Then it works out how much light reaches every pixel and moves the pixel to
+the matching extended shade.
+
+**Light.** Each light is turned into the amount of light it adds to every
+pixel it reaches. Those amounts are added to the ambient light, pixel by
+pixel, and the shade comes off the total at 4 extended shades per doubling.
+Pixels no light reaches skip that step and keep the ambient light exactly.
+
+**Shadows.** For each light, the engine visits pixels in rings, moving
+outward from the light. A pixel gets light if the next pixel toward the light
+gets light and does not cast a shadow. This costs one lookup per pixel
+instead of tracing a full line back to the light. For the penumbra, a pixel
+takes a quarter of its light from each side of that pixel, along the ring it
+sits on, which softens the edge of a shadow without touching what the shadow
+covers.
+
+**The shader** runs once for every canvas pixel. It:
+
+1. reads the logical pixel under it;
+2. adds glow where a pixel within 2 canvas pixels is brighter (flat areas do
+   not change);
+3. darkens the bottom of each pixel row (scanline);
+4. adds film grain, which changes 24 times per second, and a fixed surface
+   texture.
+
+The strength of each effect is a constant in `libs/engine/src/crt/consts.ts`.
+
+Everything before the WebGL calls is pure and unit-tested. The WebGL calls are
+the only side effects. Each one runs through `runEffect` in `drawCrt`.
+
+## Project layout
+
+```
+libs/
+├── common/src/        helpers for any lib (runEffect)
+└── engine/src/
+    ├── index.ts       the public API
+    ├── palette/       colors, shades and pixel values
+    ├── screen/        sprites, lights and ambient light
+    ├── lighting/      light amounts, the shade scale and shadows
+    ├── frame/         turns a screen into lit pixels
+    ├── crt/           the WebGL monitor shader
+    └── display/       draws to the canvas
+apps/
+└── demo/src/
+    ├── main.ts        the animation loop for both canvases
+    ├── art/           text art: sky, buildings, street, people, cars, font
+    ├── tiles/         cuts large art into sprites and places it
+    ├── day/           the time of day and how dark it is
+    ├── street/        the city street, composed from scratch every frame
+    ├── hud/           the palette swatches, the frame rate and the clock
+    └── fps/           measures the frame rate
+```
+
+## Demo
+
+Run `npm run dev` and open the page Vite prints. The demo draws two canvases,
+each with its own display:
+
+- **The street.** A city street with houses, trees, street lamps, people,
+  cars, clouds and a distant skyline. A day and night pass every 48 seconds.
+  The ambient light darkens at dusk, and the sun and then the moon cross the
+  sky behind the buildings. At night the stars come out, the lamps and
+  headlights light up, and people and cars cast shadows. Windows light up one
+  by one and go dark again later in the night.
+- **The HUD.** A swatch for each of the 128 sprite colors (16 colors × 8
+  shades), the frame rate, and the time of day on the street. It has no
+  ambient light, so the swatches always show their exact colors, even when it
+  is night on the street.
+
+The street does not keep sprites from one frame to the next. Every frame,
+`composeStreetScreen` builds a new screen for that moment from the scenery
+that never moves (built once) and from everything that does.
+
+## Performance
+
+Measured on the demo street at 1280×720 (320×180 logical pixels), in a
+Rolldown bundle run with Node 24. By day the street has 856 sprites and 1
+light; at night it has 1,013 sprites and 11 lights:
+
+| Step           | By day  | At night |
+| -------------- | ------- | -------- |
+| `computeFrame` | ~2.1 ms | ~4.8 ms  |
+| `toFrameBytes` | ~0.4 ms | ~0.4 ms  |
+
+Adding up light rather than shade numbers, and softening the shadow edges,
+costs nothing by day and about 0.1 ms a frame at night, where 11 lights reach
+44% of the screen.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Author
+
+Krzysztof Pająk (Chris Araneo) - chris.araneo@gmail.com

package/dist/lib/index.d.ts

@@ -0,0 +1,270 @@
+interface CrtUniforms {
+  readonly frame: WebGLUniformLocation;
+  readonly frameSize: WebGLUniformLocation;
+  readonly canvasSize: WebGLUniformLocation;
+  readonly pixelSize: WebGLUniformLocation;
+  readonly time: WebGLUniformLocation;
+}
+/**
+ * The WebGL objects the monitor effect needs: the shader program, the frame
+ * texture, the vertex buffer and the uniform locations.
+ */
+interface Crt {
+  readonly program: WebGLProgram;
+  readonly texture: WebGLTexture;
+  readonly vertices: WebGLBuffer;
+  readonly uniforms: CrtUniforms;
+}
+/**
+ * A point light centered on the logical pixel at `row` and `column`. At its
+ * center it brightens pixels by `intensity` extended shades (4 extended
+ * shades = 1 sprite shade). The effect fades evenly to zero at `radius`
+ * logical pixels. A negative intensity darkens. Sprites that cast shadows
+ * block it.
+ */
+interface Light {
+  readonly id: string;
+  readonly row: number;
+  readonly column: number;
+  readonly radius: number;
+  readonly intensity: number;
+}
+/**
+ * A sprite: `spriteSize * spriteSize` pixel values, row by row from the top
+ * left. Each value is a pixel such as `0x35` (color 3, shade 5) or
+ * `TRANSPARENT`.
+ */
+type Sprite = readonly number[];
+/**
+ * A sprite on the screen. `row` and `column` set its top-left pixel. If
+ * `castsShadow` is true, its non-transparent pixels block light.
+ */
+interface SpritePlacement {
+  readonly id: string;
+  readonly sprite: Sprite;
+  readonly row: number;
+  readonly column: number;
+  readonly castsShadow: boolean;
+}
+/**
+ * Everything a display draws: a background pixel, sprites and lights.
+ * Sprites are drawn in order, so later sprites cover earlier ones. `ambient`
+ * shifts every pixel by that many extended shades before lights are added:
+ * positive is lighter, negative is darker, and 0 keeps the authored colors.
+ * 4 extended shades = 1 sprite shade.
+ */
+interface Screen {
+  readonly background: number;
+  readonly ambient: number;
+  readonly sprites: readonly SpritePlacement[];
+  readonly lights: readonly Light[];
+}
+/** A color as red, green and blue values from 0 to 255. */
+interface Rgb {
+  readonly red: number;
+  readonly green: number;
+  readonly blue: number;
+}
+/**
+ * The 512 colors a display can draw (16 colors x 32 extended shades), keyed
+ * by extended pixel.
+ */
+type Palette = Readonly<Record<number, Rgb>>;
+/**
+ * A canvas set up for drawing screens. `width` and `height` are in logical
+ * pixels: the canvas size divided by `pixelSize`.
+ */
+interface Display {
+  readonly context: WebGLRenderingContext;
+  readonly crt: Crt;
+  readonly palette: Palette;
+  readonly pixelSize: number;
+  readonly spriteSize: number;
+  readonly width: number;
+  readonly height: number;
+}
+/**
+ * Draws the screen on the canvas. It composes and lights the frame, then
+ * draws it with the monitor effect. `time` is the current time in
+ * milliseconds, for example the `requestAnimationFrame` timestamp. It
+ * animates the film grain. Returns the same display.
+ */
+export declare const drawScreen: (display: Display, screen: Screen, time: number) => Display;
+/** A color in `#rrggbb` form, such as `#3c56c8`. */
+type HexColor = `#${string}`;
+/** Exactly 16 base colors. The first is color 0, the last is color 15. */
+type PaletteColors = readonly [HexColor, HexColor, HexColor, HexColor, HexColor, HexColor, HexColor, HexColor, HexColor, HexColor, HexColor, HexColor, HexColor, HexColor, HexColor, HexColor];
+/** The settings for creating a display. */
+interface DisplaySettings {
+  /** The 16 base colors. Sprites can use 8 shades of each. */
+  readonly colors: PaletteColors;
+  /** The width and height of one logical pixel, in canvas pixels. */
+  readonly pixelSize: number;
+  /** The width and height of every sprite, in logical pixels. */
+  readonly spriteSize: number;
+}
+/**
+ * Creates a display on the canvas.
+ *
+ * - `colors`: the 16 base colors.
+ * - `pixelSize`: the width and height of one logical pixel, in canvas pixels.
+ * - `spriteSize`: the width and height of every sprite, in logical pixels.
+ *
+ * The screen size in logical pixels is the canvas size divided by
+ * `pixelSize`. The display draws with WebGL, and the monitor effect is
+ * always on.
+ *
+ * Returns `undefined` if the canvas has no WebGL context, the monitor effect
+ * cannot be set up, a size is not a positive whole number, or the canvas is
+ * smaller than one logical pixel.
+ */
+export declare const tryCreateDisplay: (canvas: HTMLCanvasElement, { colors, pixelSize, spriteSize }: DisplaySettings) => Display | undefined;
+/**
+ * A composed and lit screen: one extended pixel per logical pixel, row by row
+ * from the top left. `TRANSPARENT` marks places where nothing is drawn.
+ */
+type Frame = readonly number[];
+/**
+ * Turns a screen into a frame of `width * height` extended pixels:
+ *
+ * 1. Fills the frame with the background.
+ * 2. Draws the sprites in order. Transparent pixels are skipped, and parts
+ *    outside the frame are cut off.
+ * 3. Lights every pixel: moves it along its 32-shade scale by the ambient
+ *    light plus each light that reaches it. Sprites that cast shadows block
+ *    light.
+ *
+ * With ambient 0 and no lights, every pixel keeps its authored color.
+ */
+export declare const computeFrame: (screen: Screen, spriteSize: number, width: number, height: number) => Frame;
+/** The number of base colors in a palette. */
+export declare const COLOR_COUNT = 16;
+/** The number of shades of each color that sprites and backgrounds use. */
+export declare const SHADE_COUNT = 8;
+/**
+ * The shade that shows a base color exactly as given. Lower shades are
+ * darker, higher shades are lighter.
+ */
+export declare const BASE_SHADE = 4;
+/**
+ * The number of shades of each color that lighting uses. The finer scale
+ * lets light fade in smaller steps than sprite shades.
+ */
+export declare const EXTENDED_SHADE_COUNT = 32;
+/** The number of extended shades in one sprite shade. */
+export declare const EXTENDED_SHADES_PER_SHADE: number;
+/** The pixel value that draws nothing. Whatever is below shows through. */
+export declare const TRANSPARENT = -1;
+/**
+ * Expands the 16 base colors into 512 colors: 32 extended shades per color,
+ * keyed by extended pixel.
+ *
+ * Sprite shade `s` is extended shade `4 * s + 1`. Shade `BASE_SHADE` is the
+ * base color itself. Darker shades are mixed with black, lighter shades with
+ * white. Only light reaches the extended shades between and beyond the
+ * sprite shades. A color that is not in `#rrggbb` form is read as black.
+ */
+export declare const createPalette: (colors: PaletteColors) => Palette;
+/**
+ * Returns `true` if the number is a pixel the palette can draw: a color from
+ * 0 to 15 in the high hex digit and a shade from 0 to 7 in the low hex digit.
+ * Returns `false` for `TRANSPARENT` and all other values.
+ */
+export declare const isPixel: (pixel: number) => boolean;
+/**
+ * Returns the extended pixel for a color (0 to 15) and an extended shade
+ * (0 to 31): `color * 32 + extendedShade`. Lit frames hold extended pixels,
+ * and the palette is keyed by them.
+ *
+ * Sprite shade `s` is extended shade `4 * s + 1`. Extended shades 0, 30 and
+ * 31 are outside the sprite shades; only light reaches them. Returns
+ * `TRANSPARENT` for out-of-range input.
+ */
+export declare const toExtendedPixel: (color: number, extendedShade: number) => number;
+/**
+ * Returns the extended pixel that a pixel shows under light. The color stays
+ * the same. The shade moves `shadeOffset` extended shades up or down
+ * (4 extended shades = 1 sprite shade). The result is rounded and stops at
+ * the darkest and lightest extended shade. `toLitPixel(pixel, 0)` returns
+ * the authored color. Returns `TRANSPARENT` for `TRANSPARENT` and for any
+ * value that is not a pixel.
+ */
+export declare const toLitPixel: (pixel: number, shadeOffset: number) => number;
+/**
+ * Returns the pixel value for a color (0 to 15) and a shade (0 to 7):
+ * `toPixel(3, 5)` is `0x35`. Returns `TRANSPARENT` for out-of-range input.
+ */
+export declare const toPixel: (color: number, shade: number) => number;
+/** All the fields of a light except its id. */
+type LightSettings = Omit<Light, 'id'>;
+/**
+ * Adds a light to the screen. If a light with the same id exists, it is
+ * replaced. Returns a new screen.
+ */
+export declare const addLight: (screen: Screen, id: string, { row, column, radius, intensity }: LightSettings) => Screen;
+/**
+ * Adds a sprite on top of the other sprites. `row` and `column` set its
+ * top-left pixel. If a sprite with the same id exists, it is removed first.
+ * The new sprite does not cast a shadow; to change that, call
+ * `patchSprite(screen, id, { castsShadow: true })`. Returns a new screen.
+ */
+export declare const addSprite: (screen: Screen, id: string, sprite: Sprite, row: number, column: number) => Screen;
+/**
+ * Creates an empty screen, with no sprites and no lights, filled with
+ * `background`. `ambient` shifts every pixel by that many extended shades
+ * (4 extended shades = 1 sprite shade). For example, a night scene could
+ * use -16.
+ */
+export declare const createScreen: (background?: number, ambient?: number) => Screen;
+/** Returns the light with the id, or `undefined` if there is none. */
+export declare const findLight: (screen: Screen, id: string) => Light | undefined;
+/** Returns the sprite with the id, or `undefined` if there is none. */
+export declare const findSprite: (screen: Screen, id: string) => SpritePlacement | undefined;
+/**
+ * Sets the ambient light: how many extended shades every pixel moves up
+ * (positive) or down (negative) before lights are added. Change it over time
+ * to fade between day and night. Returns a new screen.
+ */
+export declare const patchAmbient: (screen: Screen, ambient: number) => Screen;
+/** The light fields to change. Fields you leave out keep their values. */
+type LightChanges = Partial<LightSettings>;
+/**
+ * Changes a light's `row`, `column`, `radius` or `intensity`. Fields you
+ * leave out keep their values. Returns a new screen. If no light has the id,
+ * nothing changes.
+ */
+export declare const patchLight: (screen: Screen, id: string, changes: LightChanges) => Screen;
+/**
+ * Moves a light `rowOffset` pixels down and `columnOffset` pixels right.
+ * Negative values move it up and left. Returns a new screen. If no light has
+ * the id, nothing changes.
+ */
+export declare const patchLightByOffset: (screen: Screen, id: string, rowOffset: number, columnOffset: number) => Screen;
+/** The sprite fields to change. Fields you leave out keep their values. */
+type SpriteChanges = Partial<Pick<SpritePlacement, 'sprite' | 'row' | 'column' | 'castsShadow'>>;
+/**
+ * Changes a sprite's `sprite` (for animation), `row`, `column` or
+ * `castsShadow`. Fields you leave out keep their values. The sprite keeps its
+ * place in the drawing order. Returns a new screen. If no sprite has the id,
+ * nothing changes.
+ */
+export declare const patchSprite: (screen: Screen, id: string, changes: SpriteChanges) => Screen;
+/**
+ * Moves a sprite `rowOffset` pixels down and `columnOffset` pixels right.
+ * Negative values move it up and left. Returns a new screen. If no sprite
+ * has the id, nothing changes.
+ */
+export declare const patchSpriteByOffset: (screen: Screen, id: string, rowOffset: number, columnOffset: number) => Screen;
+/** Removes the light with the id. Returns a new screen. */
+export declare const removeLight: (screen: Screen, id: string) => Screen;
+/** Removes the sprite with the id. Returns a new screen. */
+export declare const removeSprite: (screen: Screen, id: string) => Screen;
+/** Maps each character of sprite text art to a pixel value. */
+type SpriteLegend = Readonly<Record<string, number>>;
+/**
+ * Builds a sprite from text art: one string per row, one character per
+ * pixel. Each character is looked up in `legend`. Characters that are not in
+ * the legend become transparent.
+ */
+export declare const toSprite: (rows: readonly string[], legend: SpriteLegend) => Sprite;
+export type { Crt, Display, DisplaySettings, Frame, HexColor, Light, LightChanges, LightSettings, Palette, PaletteColors, Rgb, Screen, Sprite, SpriteChanges, SpriteLegend, SpritePlacement };