js-game-zero 0.0.0-stage → 0.3.0

package/dist/reference/screen.md

@@ -0,0 +1,313 @@
+# Screen And Drawing
+
+`screen` is the global canvas surface. Everything you draw happens inside
+`draw()`, in screen pixels: `[0, 0]` is the top-left corner, x grows right,
+y grows down, and `[WIDTH, HEIGHT]` is the bottom-right corner.
+
+## Short forms
+
+Five short calls draw the most common shapes and text, with each position
+given as separate numbers rather than an `[x, y]` list:
+
+| Call                                             | Draws                                              |
+| ------------------------------------------------ | -------------------------------------------------- |
+| `screen.circle(x, y, radius, color)`             | a filled circle centered on `x, y`                 |
+| `screen.rect(x, y, width, height, color)`        | a filled rectangle whose top-left corner is `x, y` |
+| `screen.triangle(x1, y1, x2, y2, x3, y3, color)` | a filled triangle with those three corners         |
+| `screen.line(x1, y1, x2, y2, color, width = 1)`  | a line from `x1, y1` to `x2, y2`, `width` px thick |
+| `screen.text(text, x, y, color, size = 24)`      | text whose top-left corner is `x, y`, `size` tall  |
+
+`color` is optional and defaults to `"white"`; it takes any of the
+[colors](#colors) below.
+
+```js
+function draw() {
+  screen.clear();
+  screen.rect(0, 220, 400, 80, "green");
+  screen.circle(200, 150, 25, "gold");
+  screen.triangle(160, 40, 120, 120, 200, 120);
+  screen.line(20, 20, 200, 120, "white", 3);
+  screen.text("Score: " + score, 20, 30);
+}
+```
+
+`screen.text` takes words in quotes or a number. To place text by its
+center, wrap it or give it an outline, use
+[`screen.draw.text`](#screendrawtexttext-pos-options--screendrawtexttext-options).
+
+The short forms fill their shapes. The outline versions, and the versions
+that take `[x, y]` lists, stay under `screen.draw` below. Mind the names:
+**`screen.circle` fills, but `screen.draw.circle` draws only an outline**,
+and the same goes for `screen.rect` and `screen.draw.rect`.
+
+A wrong call throws a `TypeError` that says what to change. A list, as in
+`screen.circle([200, 150], 25)`, points to the `screen.draw` method that
+takes lists (here `screen.draw.filledCircle`). A missing or non-number
+argument is named, and an extra one, such as an outline width, points to
+the outline method.
+
+## Colors
+
+Every drawing method accepts a `Color`, which is either a CSS color string
+(`"white"`, `"#0f172a"`, `"rgb(20, 30, 40)"`) or an RGB/RGBA tuple of
+integers `0`–`255`: `[249, 115, 22]` or `[249, 115, 22, 128]` (the fourth
+value is alpha out of 255, not a `0`–`1` fraction). Passing anything else
+throws a `TypeError` that says what was wrong:
+
+- A misspelled color name suggests the right one: `"lightblu"` fails with
+  `Did you mean "lightblue"?`. (A canvas would otherwise ignore the color
+  and keep drawing in the previous one.)
+- A hex code needs 3 or 6 hex digits (or 4 or 8, with alpha).
+- A fractional alpha such as `[255, 0, 0, 0.5]` fails with the 0–255 value
+  to use instead (`128`).
+
+Drawing options are checked the same way: an option a method doesn't have,
+such as `{ colour: "red" }`, throws and names the closest real option.
+
+### `rgb(red, green, blue, alpha?)`
+
+Mixes a color from red, green and blue light, each `0`–`255`, with an
+optional alpha out of 255. It returns the matching list, so
+`rgb(255, 140, 105)` is `[255, 140, 105]` and works anywhere a color does.
+It's ready to use in a game file; in import mode, import it from
+`js-game-zero`.
+
+```js
+let coral = rgb(255, 140, 105);
+let glass = rgb(120, 200, 255, 128); // half see-through
+screen.circle(200, 150, 25, coral);
+```
+
+Its numbers are checked like a list's, with the same hints (a fractional
+alpha such as `0.5` names `128` instead), and a missing one is named:
+`rgb(255, 140)` fails with `rgb is missing blue`.
+
+## `screen.clear()`
+
+Resets the whole canvas to opaque black.
+
+```js
+function draw() {
+  screen.clear();
+}
+```
+
+## `screen.fill(color, bottomColor?)`
+
+Fills the canvas with a solid color, or a top-to-bottom gradient when a
+second color is given: `color` at the top fading to `bottomColor` at the
+bottom.
+
+```js
+screen.fill("#0f172a"); // solid
+screen.fill("#0f172a", "#164e63"); // gradient, dark at top to teal at bottom
+```
+
+## `screen.draw.image(image, pos)` / `screen.blit(image, pos)`
+
+`screen.draw.image` and `screen.blit` (Pygame Zero's name) do the same
+thing. Draws an already-loaded image (by asset name, or a `SurfaceLike` you already
+hold) at a position. `pos` is a `[x, y]` point for the image's top-left
+corner, or a rect-like value (its top-left corner is used; blit does not
+scale the image to the rect's size).
+
+```js
+screen.draw.image("player.svg", [40, 40]);
+```
+
+If the named image hasn't finished loading yet, nothing is drawn: it returns
+a `Promise` that resolves once the image has loaded, and the runtime holds
+the frames that follow until then, so the image shows from the next one.
+If it can't be loaded, the promise rejects and the run reports the missing
+image by name, so `draw()` needn't handle the promise itself.
+Images touched while the script starts up load before the first frame (see
+[`docs/reference/runtime.md`](runtime.md#preload-gate)).
+Prefer `Actor` for anything that moves or needs collision — drawing an image
+directly is for background art and tiles.
+
+## `screen.bounds()`
+
+Returns a `ZRect` covering the whole canvas (`[0, 0, WIDTH, HEIGHT]`), handy
+for clamping or collision against the screen edge.
+
+```js
+if (!screen.bounds().contains(player.rect()))
+  player.center = [WIDTH / 2, HEIGHT / 2];
+```
+
+## `PIXEL_DENSITY` and `screen.density`
+
+On a phone, one screen pixel covers several of the device's own pixels.
+The canvas has a pixel for each of them, so text, outlines and SVG pictures
+stay sharp. `screen.density` says how many canvas pixels make up one screen
+pixel along each side: between 2 and 3 on most phones and 1 on a computer
+monitor. Your game's numbers don't change with it: a game 360 pixels wide
+is 360 wide at any density.
+
+Set `PIXEL_DENSITY` next to `WIDTH` and `HEIGHT` to choose the density
+yourself. Without it, the game uses the device's own, up to 3.
+
+```js
+WIDTH = 360;
+HEIGHT = 640;
+PIXEL_DENSITY = 1; // one canvas pixel per screen pixel, even on a phone
+```
+
+See [pixel density](runtime.md#pixel-density) for how hosts size and read
+the canvas.
+
+## `screen.draw.line(start, end, color, width = 1)`
+
+```js
+screen.draw.line([20, 20], [200, 120], "white", 3);
+```
+
+## `screen.draw.circle(pos, radius, color, width = 1)` / `filledCircle(pos, radius, color)`
+
+`screen.draw.circle` draws an outline; `filledCircle` and the short form
+[`screen.circle`](#short-forms) fill.
+
+```js
+screen.draw.circle([160, 90], 40, "#38bdf8", 2); // outline
+screen.draw.filledCircle([160, 90], 40, "#38bdf8"); // filled
+```
+
+## `screen.draw.rect(rect, color, width = 1)` / `filledRect(rect, color)`
+
+`rect` accepts anything geometry accepts: a `Rect`, an `Actor` (via its
+`.rect()` duck type — see [`docs/reference/rect.md`](rect.md)), or a plain
+`[left, top, width, height]` tuple.
+
+```js
+screen.draw.filledRect([40, 40, 120, 60], "#f97316");
+screen.draw.rect(player.rect(), "yellow", 2); // highlight a hitbox
+```
+
+## `screen.draw.polygon(points, color, width = 1)` / `filledPolygon(points, color)`
+
+Needs at least three points.
+
+```js
+screen.draw.filledPolygon(
+  [
+    [238, 40],
+    [292, 64],
+    [270, 126],
+    [214, 118],
+  ],
+  "#f8fafc",
+);
+```
+
+## `screen.draw.text(text, pos?, options?)` / `screen.draw.text(text, options)`
+
+Draws text with a large set of beginner-friendly options — this is a
+JavaScript-native reimplementation of pgzero's `ptext` module, including its
+word-wrapping algorithm and gradient/outline/shadow effects.
+
+```js
+screen.draw.text("Score: 12", [16, 16], {
+  size: 24,
+  color: "white",
+});
+```
+
+When the options say where the text goes (`center`, `topRight`, ...), pass
+them second, in place of the position:
+
+```js
+screen.draw.text("Game Over", { center: [WIDTH / 2, HEIGHT / 2], size: 40 });
+```
+
+Several options have two names: a readable one, and the shorter one Pygame
+Zero uses. Either works, but not both at once:
+
+| Readable name   | Pygame Zero name |
+| --------------- | ---------------- |
+| `size`          | `fontsize`       |
+| `outline`       | `owidth`         |
+| `outlineColor`  | `ocolor`         |
+| `shadowColor`   | `scolor`         |
+| `gradientColor` | `gcolor`         |
+
+### Position options
+
+Give **exactly one** of the following ways to position the text (mixing
+them throws a `TypeError`):
+
+- `pos` (or the second positional argument) — a `[x, y]` point. Combined
+  with `anchor` (default `"topLeft"`) to decide which part of the text box
+  sits at that point.
+- A named anchor point directly: `topLeft`, `topRight`, `bottomLeft`,
+  `bottomRight`, `midTop`, `midLeft`, `midRight`, `midBottom`, `center` —
+  each takes a `[x, y]` point for that corner/edge/center of the text.
+- Scalar axis keywords, combined per-axis: `left`/`centerX`/`right` for the
+  horizontal position, `top`/`centerY`/`bottom` for the vertical position.
+  You can mix one horizontal and one vertical scalar (`{ right: 300, top: 10
+}`), or use just one axis and fall back to `pos` for the other.
+
+```js
+screen.draw.text("Game Over", {
+  center: [WIDTH / 2, HEIGHT / 2],
+  size: 40,
+});
+screen.draw.text("HUD", { right: WIDTH - 10, top: 10 }); // top-right corner, 10px margin
+```
+
+### Font options
+
+- `size` / `fontsize` (default `24`)
+- `fontname` — the stem of a font asset under `fonts/` (e.g. `"pixel"` for
+  `fonts/pixel.ttf`); loads asynchronously the first time it's used.
+- `sysfontname` — a literal CSS font family name instead (e.g. `"Georgia"`).
+  Mutually exclusive with `fontname`.
+- `bold`, `italic`, `underline` — booleans.
+- `color` (default `"white"`), `background` (fills a box behind the text).
+- `gradientColor` / `gcolor` — a second color for a top-to-bottom gradient
+  across the text.
+
+### Layout options
+
+- `width` — wraps text to fit this many pixels; without it, text is only
+  broken at explicit newlines (`\n`). Wrapping is greedy word-wrap: a single
+  word longer than `width` is placed on its own (overflowing) line rather
+  than being cut.
+- `widthem` — like `width`, but expressed as a multiple of `size`.
+- `lineheight` — pixels between lines (default `size * 1.2`).
+- `align` — `"left"` (default), `"center"`, or `"right"`, for multi-line text.
+  A [`textbox`](#screendrawtextboxtext-rect-options) follows its `anchor`
+  instead, so it centers by default.
+- `strip` — trims trailing spaces from each wrapped line (default `true`).
+- `anchor` — overrides which part of the text's bounding box sits at the
+  resolved position; either one of the named anchor strings above, or a
+  `[horizontal, vertical]` pair where each side is `"left"`/`"center"`/`"right"`,
+  `"top"`/`"center"`/`"bottom"`, or a literal pixel-offset number.
+- `angle` — rotates the text counterclockwise around the anchor point, in
+  degrees.
+
+### Effects
+
+- `outline` / `owidth` + `outlineColor` / `ocolor` — an outline stroke
+  around the glyphs, `outline` pixels thick.
+- `shadow` (a number or `[x, y]` offset) + `shadowColor` / `scolor`
+  (default `"black"`) — a drop shadow.
+- `alpha` — overall opacity, `0`–`1` (default `1`).
+
+## `screen.draw.textbox(text, rect, options?)`
+
+Like `draw.text`, but instead of a fixed `size` you give a rectangle and
+`textbox` picks the **largest font size that fits inside it** (shrinking
+down to `minSize`, default `4`, if necessary; `minFontsize` is another name
+for it, but not both at once). Text is centered in the rect by default.
+Pass `anchor` (e.g. `"topLeft"`) to place it elsewhere in the rect; its
+lines line up the same way (on the left for `"topLeft"`) unless you give
+`align`. The rect places the text, so `textbox` takes none of
+`draw.text`'s position options (`pos`, `center`, `topLeft`, `left`, ...)
+and no `width`; giving one throws a `TypeError` that says so.
+
+```js
+screen.draw.textbox("You win!", [40, 60, 240, 80], {
+  color: "white",
+  size: 48, // upper bound; shrinks to fit if "You win!" would overflow
+});
+```

package/dist/reference/storage.md

@@ -0,0 +1,90 @@
+# Storage
+
+`storage` is a persistent, dictionary-like object for saving small amounts
+of data between play sessions — high scores, unlocked levels, settings.
+
+```js
+let highScore = storage.get("highScore") ?? 0;
+
+function update() {
+  if (score > highScore) {
+    highScore = score;
+    storage.set("highScore", highScore);
+  }
+}
+```
+
+## Auto-load and auto-save
+
+You don't need to call `save()` or `load()` yourself in normal use:
+
+- **Auto-load**: the default browser adapter has a synchronous `loadSync()`
+  path, so a top-level read like `let score = storage.get("score") ?? 0`
+  sees previously-saved data immediately. So does a custom adapter with a
+  `loadSync()`, or whose `load()` returns its text rather than a Promise. A
+  custom asynchronous adapter is loaded once during startup and delays
+  frames/`handle.ready`, but cannot retroactively change values already
+  copied into top-level variables, and what it loads replaces anything the
+  top level stored before it arrived.
+- **Auto-save**: any mutation (`storage.set(...)`, `storage.score = 5`,
+  `storage.delete(...)`, `storage.clear()`) schedules a save a fraction of a
+  second later, and within a second even while the game keeps changing it
+  every frame; rapid changes coalesce into one write instead of saving on
+  every single mutation. Storage is also flushed immediately when the tab is
+  hidden or closed, and when the game stops, so nothing is lost. A change
+  inside a stored object or list, such as `storage.highScores.push(score)`,
+  is saved too, with the next of those saves; set the key again
+  (`storage.highScores = storage.highScores`) to save it sooner.
+
+## Reading and writing
+
+Two equivalent styles work — plain method calls, or attribute-style access
+through a proxy (closer to pgzero's `storage` object):
+
+```js
+storage.set("score", 10);
+storage.get("score"); // 10
+
+storage.score = 10; // same as storage.set("score", 10)
+storage.score; // 10
+```
+
+| Method                                  | Behavior                                                                                           |
+| --------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `storage.get(key, defaultValue?)`       | Returns the stored value, or `defaultValue` (`undefined` if omitted) if `key` isn't set.           |
+| `storage.set(key, value)`               | Stores `value` under `key`.                                                                        |
+| `storage.setDefault(key, defaultValue)` | Sets `key` to `defaultValue` only if it isn't already set; returns the resulting value either way. |
+| `storage.has(key)`                      | `boolean`.                                                                                         |
+| `storage.delete(key)`                   | Removes `key`; also works as `delete storage.key`. Returns `true` if something was removed.        |
+| `storage.clear()`                       | Removes everything.                                                                                |
+| `storage.keys()`                        | Every stored key, alphabetically sorted.                                                           |
+| `storage.path`                          | The backing location: a scoped `localStorage` key in the browser, or a file path in the sandbox.   |
+
+Values must be JSON-serializable — plain objects, arrays, strings, numbers,
+booleans, and `null`. Storing anything else (a class instance, a function,
+`undefined`, `NaN`, `Infinity`, a circular reference), anywhere inside the
+value, throws a `JsonStorageError` naming the offending path, e.g.
+`NaN is not a JSON value at storage.highScores[2].score`, and stores nothing.
+A value changed inside a stored object or list after it was stored is only
+checked when storage saves: until it's a JSON value again, saving fails,
+with a warning naming its path, and nothing in storage is saved.
+
+## Gotchas
+
+- **Don't shadow method names.** `storage.save`, `storage.load`, `storage.path`
+  and the other method names above are real properties on `storage` itself,
+  not just proxy-forwarded keys — writing `storage.save = 5` overwrites the
+  actual `save` method instead of storing a value, and another spelling of
+  a method, such as `storage.setdefault`, throws naming the method. Pick key
+  names that don't collide with the method list.
+- Storage is scoped per project: in the browser it's namespaced by project
+  id (so two different games on the same site don't share data, as long as
+  each has its own `projectId`; games run without one all share the id
+  `default`); in the sandbox it's a JSON file inside that project's own
+  directory.
+
+## Manual save/load
+
+For advanced cases — forcing an immediate write instead of waiting for the
+debounce, or working outside of `run()` — `storage.save()` and
+`storage.load()` are both available directly and return `Promise<void>`.

package/dist/rendering.d.ts

@@ -0,0 +1,188 @@
+import { type AssetLoader, type SurfaceLike } from "./assets.js";
+import { type Color } from "./color.js";
+import { ZRect, type Point, type RectLike } from "./geometry.js";
+export { normalizeColor } from "./color.js";
+export type { Color } from "./color.js";
+export type CanvasLike = {
+    readonly width: number;
+    readonly height: number;
+    getContext?: (contextId: "2d") => CanvasRenderingContext2D | null;
+};
+export type ScreenOptions = {
+    readonly imageLoader?: Pick<AssetLoader<SurfaceLike>, "load" | "get">;
+};
+export type TextAlignOption = "left" | "center" | "right";
+export type TextAnchor = "topLeft" | "topRight" | "bottomLeft" | "bottomRight" | "midTop" | "midLeft" | "midRight" | "midBottom" | "center" | readonly [number | HorizontalAnchor, number | VerticalAnchor];
+export type HorizontalAnchor = "left" | "center" | "middle" | "right";
+export type VerticalAnchor = "top" | "center" | "middle" | "bottom";
+export type TextOptions = {
+    readonly fontname?: string;
+    readonly sysfontname?: string;
+    readonly fontsize?: number;
+    /** Same as `fontsize`. */
+    readonly size?: number;
+    readonly bold?: boolean;
+    readonly italic?: boolean;
+    readonly underline?: boolean;
+    readonly color?: Color;
+    readonly background?: Color;
+    readonly pos?: Point;
+    readonly topLeft?: Point;
+    readonly topRight?: Point;
+    readonly bottomLeft?: Point;
+    readonly bottomRight?: Point;
+    readonly midTop?: Point;
+    readonly midLeft?: Point;
+    readonly midRight?: Point;
+    readonly midBottom?: Point;
+    readonly center?: Point;
+    readonly top?: number;
+    readonly left?: number;
+    readonly bottom?: number;
+    readonly right?: number;
+    readonly centerX?: number;
+    readonly centerY?: number;
+    readonly width?: number;
+    readonly widthem?: number;
+    readonly lineheight?: number;
+    readonly align?: TextAlignOption;
+    readonly strip?: boolean;
+    readonly owidth?: number;
+    /** Same as `owidth`. */
+    readonly outline?: number;
+    readonly ocolor?: Color;
+    /** Same as `ocolor`. */
+    readonly outlineColor?: Color;
+    readonly shadow?: number | Point;
+    readonly scolor?: Color;
+    /** Same as `scolor`. */
+    readonly shadowColor?: Color;
+    readonly gcolor?: Color;
+    /** Same as `gcolor`. */
+    readonly gradientColor?: Color;
+    readonly alpha?: number;
+    readonly anchor?: TextAnchor;
+    readonly angle?: number;
+};
+export type TextboxOptions = Omit<TextOptions, TextPositionKey | "width" | "widthem" | "top" | "left" | "bottom" | "right" | "centerX" | "centerY"> & {
+    readonly minFontsize?: number;
+    /** Same as `minFontsize`. */
+    readonly minSize?: number;
+};
+/**
+ * `screen.draw.text` takes its options either third, after a position, or
+ * second, in place of one: `text("Hi", [10, 10], { size: 20 })` and
+ * `text("Hi", { center: [160, 90], size: 20 })` both work.
+ */
+export type DrawText = {
+    (text: string, options?: TextOptions): void;
+    (text: string, pos: Point | undefined, options?: TextOptions): void;
+};
+export type TextLayout = {
+    readonly lines: readonly string[];
+    readonly font: string;
+    readonly fontSize: number;
+    readonly lineHeight: number;
+    readonly boxWidth: number;
+    readonly boxHeight: number;
+    readonly textWidth: number;
+    readonly align: TextAlignOption;
+    readonly topLeft: Point;
+    readonly anchorOffset: Point;
+    readonly alpha: number;
+};
+type TextPositionKey = "pos" | "topLeft" | "topRight" | "bottomLeft" | "bottomRight" | "midTop" | "midLeft" | "midRight" | "midBottom" | "center";
+/**
+ * Sizes the screen to `width` × `height` logical pixels with `density`
+ * canvas pixels each, and scales the context so every drawing call keeps
+ * working in logical pixels. A density change keeps what's on the canvas,
+ * rescaled; a new size starts blank, as setting a canvas's size does.
+ */
+export declare function resizeScreen(screen: Screen, width: number, height: number, density?: number): void;
+/**
+ * Restores the density scale if something reset the canvas since the last
+ * frame. Code outside the runtime that sets `canvas.width`/`height` means
+ * a logical size, so the screen adopts it at the same density.
+ */
+export declare function syncScreen(screen: Screen): void;
+/** A value a drawn thing reports, as JSON. */
+type DrawnValue = string | number | boolean | readonly number[];
+/**
+ * One thing a frame drew, as a host reads it through the inspector's
+ * `$drawn`: its kind (`fill`, `image`, `actor`, `circle`, `rect`, `polygon`,
+ * `line`, `text`, `clear`), and what it is and where, as the game gave them.
+ */
+export type DrawnThing = {
+    readonly kind: string;
+    readonly [key: string]: DrawnValue;
+};
+/** Starts recording what `screen` draws, afresh: the runtime calls it before each `draw()`. */
+export declare function beginDrawn(screen: Screen): void;
+/** What `screen`'s last `draw()` drew, in order; empty before its first. */
+export declare function drawnOn(screen: Screen): readonly DrawnThing[];
+/** Records one thing drawn, when the screen is recording. */
+export declare function recordDrawn(screen: Screen, thing: DrawnThing): void;
+export declare class Screen {
+    readonly canvas: CanvasLike;
+    readonly context: CanvasRenderingContext2D;
+    readonly imageLoader: Pick<AssetLoader<SurfaceLike>, "load" | "get">;
+    readonly draw: {
+        line: (start: Point, end: Point, color: Color, width?: number) => void;
+        circle: (pos: Point, radius: number, color: Color, width?: number) => void;
+        filledCircle: (pos: Point, radius: number, color: Color) => void;
+        polygon: (points: Point[], color: Color, width?: number) => void;
+        filledPolygon: (points: Point[], color: Color) => void;
+        rect: (rect: RectLike, color: Color, width?: number) => void;
+        filledRect: (rect: RectLike, color: Color) => void;
+        text: DrawText;
+        textbox: (text: string, rect: RectLike, options?: TextboxOptions) => void;
+        /** Same as `screen.blit`: draws an image with its top-left at `pos`. */
+        image: (image: string | SurfaceLike, pos: Point | RectLike) => Promise<void> | void;
+    };
+    constructor(canvas: CanvasLike, context?: CanvasRenderingContext2D | null, options?: ScreenOptions);
+    /** The screen's width in logical pixels: the game's `WIDTH`. */
+    get width(): number;
+    /** The screen's height in logical pixels: the game's `HEIGHT`. */
+    get height(): number;
+    /** Canvas pixels per logical pixel along each side. */
+    get density(): number;
+    bounds(): ZRect;
+    clear(): void;
+    fill(color: Color, gcolor?: Color): void;
+    blit(image: string | SurfaceLike, pos: Point | RectLike): Promise<void> | void;
+    /**
+     * The short forms take positions as separate numbers rather than `[x, y]`
+     * lists, fill their shapes, and default to white, so
+     * `screen.circle(200, 150, 25, "gold")` fits a phone-width line where
+     * `screen.draw.filledCircle([200, 150], 25, "gold")` doesn't. The
+     * outline versions stay under `screen.draw`.
+     */
+    circle(x: number, y: number, radius: number, color?: Color): void;
+    /** A filled rectangle whose top-left corner is at `x, y`. */
+    rect(x: number, y: number, width: number, height: number, color?: Color): void;
+    triangle(x1: number, y1: number, x2: number, y2: number, x3: number, y3: number, color?: Color): void;
+    line(x1: number, y1: number, x2: number, y2: number, color?: Color, width?: number): void;
+    /**
+     * Text whose top-left corner is at `x, y`, `size` pixels tall, so a score
+     * fits one short line: `screen.text("Score: " + score, 20, 30)`. A number
+     * is drawn as it reads. Placing by its center or any other option stays
+     * under `screen.draw.text`.
+     */
+    text(text: string | number, x: number, y: number, color?: Color, size?: number): void;
+    private drawSurface;
+    private drawLine;
+    private drawCircle;
+    private drawPolygon;
+    private drawRect;
+    private drawText;
+    private drawTextbox;
+}
+export declare function setScreen(screen: Screen | null): Screen | null;
+export declare function getScreen(): Screen;
+export declare const screen: Screen;
+export declare function layoutText(context: CanvasRenderingContext2D, text: string, pos: Point | undefined, options?: TextOptions): TextLayout;
+export declare function fitTextboxFontSize(context: CanvasRenderingContext2D, text: string, rectLike: RectLike, options?: TextboxOptions): {
+    fontSize: number;
+    lineHeight: number;
+    lines: readonly string[];
+};