@chris.araneo/cassette-canvas 0.0.0-stage → 0.1.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,281 @@
-# 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.1.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`. It brightens pixels by up to `intensity` extended shades at its center and fades to zero at `radius`. A negative intensity darkens. |
+| **Shadow**         | A sprite with `castsShadow: true` blocks light. Pixels behind it get no light from that light. 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. Each pixel moves by the
+ambient light plus every light that reaches it. Both are measured in extended
+shades (`EXTENDED_SHADES_PER_SHADE` = 4 per shade). The result is rounded to a
+whole extended shade and kept between 0 and 31. With ambient 0 and no lights,
+every pixel shows its authored color.
+
+```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: 16,
+    }),
+);
+
+const torchMoved = patchLightByOffset(night, 'torch', 0, 2);
+const flickered = patchLight(torchMoved, 'torch', { intensity: 13 });
+const dawn = patchAmbient(flickered, -3);
+```
+
+With ambient `-16` and a light with intensity `16`, pixels at the center of
+the light show their authored colors. Further away, the light fades back to
+night in 16 small steps instead of 4 large ones. Ambient and intensity can be
+fractions; the total is rounded for each pixel.
+
+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 computes a light level for every pixel and moves the pixel to the
+matching extended shade.
+
+**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.
+
+**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 levels and shadows
+    ├── frame/         turns a screen into lit pixels
+    ├── crt/           the WebGL monitor shader
+    └── display/       draws to the canvas
+apps/
+└── demo/              a Vite page: the palette, a day/night cycle, a lantern,
+                       a glowing heart and pillars that cast shadows
+```
+
+## Performance
+
+Measured on the demo scene at 1280×720 (320×180 logical pixels, 182 sprites,
+2 lights), in a Vite bundle run with Node 24:
+
+| Step           | Time per frame |
+| -------------- | -------------- |
+| `computeFrame` | ~1.3 ms        |
+| `toFrameBytes` | ~0.3 ms        |
+
+## 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 };