@driftengine/core 3.61.0

package/dist/ui/frameRecorder.d.ts

@@ -0,0 +1,188 @@
+import type { LockableSurface } from './exportTarget.ts';
+import type { FrameOverlay } from './frameOverlay.ts';
+import type { FramePacingReport } from './framePacer.ts';
+export declare const DEFAULT_CLIP_FPS = 30;
+/**
+ * Recording what is on a canvas — or on a prepared export target — to a file.
+ *
+ * A convenience on top of the replay, not the feature. The replay itself is
+ * what makes a run worth posting; this saves the trouble of reaching for a
+ * screen recorder — and where the browser cannot do it, saying so plainly beats
+ * producing a file that will not play.
+ *
+ * Deliberately not a server-side render. That is the "proper" answer and it is
+ * a backend, a queue, a storage bill and a moderation problem, for something
+ * the browser already does.
+ *
+ * **The honest limit, and it belongs here rather than in a commit message:**
+ * `MediaRecorder` timestamps every frame by wall clock, and that is measured
+ * rather than assumed — a probe recording requested frames at gaps of 8.6 / 24.5 /
+ * 8.1 / 28.6 ms and `ffprobe` read the MP4's own timestamps back as 8.8 / 24.2 /
+ * 8.1 / 28.5 ms, `avg_frame_rate=7110000/120161`. Two things follow.
+ *
+ * An export has to run in real time: there is no in-browser way to render a clip
+ * slower than real time and have the audio line up, short of shipping our own
+ * muxer, which is a dependency and the standing rule says no. So the export can be
+ * *paced* (see `ExportTarget`) and *measured*, but it cannot be given more time.
+ *
+ * And a constant-rate file is not on offer either. What is on offer is a file whose
+ * frames are evenly spaced *and* hold moments the same distance apart, which is
+ * what a viewer reads as smooth — so the schedule captures every n-th animation
+ * frame and the content follows the wall clock. A device that cannot hold the
+ * target rate then produces a slower clip rather than a juddering one, and the
+ * measurement in `pacing` says which it was.
+ */
+export interface FrameRecorderOptions {
+    /**
+     * Record the canvas directly, at `fps`. Simple and appropriate for a debug
+     * capture; for a clip anybody else will see, prefer `stream` from an
+     * `ExportTarget`, which fixes the aspect, stamps the mark and paces the
+     * frames.
+     */
+    readonly canvas?: HTMLCanvasElement;
+    /** A prepared video stream, e.g. `ExportTarget.acquire()`. Wins over `canvas`. */
+    readonly stream?: MediaStream;
+    /** Mixed into the clip. Omit for a silent recording. */
+    readonly audio?: MediaStream | null;
+    /**
+     * Frames per second wanted — a floor, not a promise.
+     *
+     * The schedule counts animation frames (see `FramePacer`), so what comes out is
+     * the loop's own rate divided by a whole number. Asking for 60 on a 144 Hz panel
+     * records 72; asking for it on a loop that can only deliver 40 records 40.
+     */
+    readonly fps?: number;
+    /**
+     * Bits per second for video. Defaults to a figure scaled from the frame's
+     * pixel count and rate — a constant is generous at one size and starved at
+     * another, and a starved encoder on high-motion footage looks like stutter.
+     */
+    readonly videoBitsPerSecond?: number;
+    /**
+     * Record at a fixed frame size rather than at whatever the canvas happens to
+     * be, compositing the scene and an optional mark into it.
+     *
+     * This is what makes an export a *product* rather than a screen capture: the
+     * frame is the requested shape whatever the window is, the mark is inside the
+     * video where a DOM overlay could never be, and frames are handed over one at a
+     * time so none is ever recorded twice.
+     */
+    readonly target?: {
+        /** The canvas the scene is drawn into. */
+        readonly source: HTMLCanvasElement;
+        /** Whoever owns that canvas's drawing-buffer size — normally the renderer. */
+        readonly surface: LockableSurface;
+        readonly width: number;
+        readonly height: number;
+        readonly overlay?: FrameOverlay | ((width: number, height: number) => FrameOverlay);
+        /**
+         * Drawn live into every composed frame, after the scene and the baked mark.
+         *
+         * For anything that changes frame to frame — a speedometer, a clock — which the
+         * baked `overlay` cannot express at all. See `ExportTargetOptions.drawFrame`.
+         */
+        readonly drawFrame?: (ctx: CanvasRenderingContext2D, width: number, height: number) => void;
+        /**
+         * What the renderer is currently managing, frames per second. A device below
+         * the target rate records at a smaller frame instead: a slightly softer clip
+         * that holds its rate beats a full-size one that judders. Omit for no
+         * measurement, which is treated as no evidence rather than as bad news.
+         */
+        readonly measuredFps?: number;
+        /** Forwarded to `ExportTargetOptions.presentedFrames`; see `duplicateFrame` below. */
+        readonly presentedFrames?: () => number;
+    };
+}
+export declare class FrameRecorder {
+    private readonly options;
+    private recorder;
+    private chunks;
+    private readonly mime;
+    private target;
+    private targetStream;
+    constructor(options: FrameRecorderOptions);
+    get mimeType(): string;
+    /**
+     * Take over the render surface before recording starts.
+     *
+     * Separate from `start` because the aspect has to be in force *before* the
+     * first frame anybody records: the camera composes for `renderer.aspect`, so
+     * locking and recording in the same breath would put a screen-shaped shot in
+     * the first frames of a vertical clip. Returns the frame size that will be
+     * recorded, which is not always the one requested — see `measuredFps`.
+     */
+    prepare(): {
+        width: number;
+        height: number;
+        reduced: boolean;
+    } | null;
+    /**
+     * Whether the frame about to be drawn will be kept. True when there is no
+     * fixed target, so a caller can gate its render pass unconditionally.
+     *
+     * Call once per animation frame, drawing or not: the instant is kept and reused
+     * when the frame is handed over, so one clock decides and commits.
+     */
+    captureDue(nowMs: number): boolean;
+    /**
+     * One rendered frame, offered to the recording.
+     *
+     * Call at the very end of the render pass. Cheap and false when there is no
+     * fixed target, so a caller can hand every frame over unconditionally. Takes no
+     * instant — it uses the one `captureDue` was given for this frame.
+     */
+    frameRendered(): boolean;
+    /**
+     * What the pacing actually was, or null when recording the canvas directly.
+     *
+     * The measurement is the point rather than a diagnostic afterthought: an export
+     * that ran below its target rate produced a juddering file, and the only honest
+     * options are to say so or to have not measured.
+     */
+    get pacing(): FramePacingReport | null;
+    /**
+     * Whether the frame `frameRendered` just composited repeats the one before it.
+     *
+     * False without a target, and false when `presentedFrames` was never supplied — the same
+     * two "no evidence yet" cases `pacing` already has to account for. See
+     * `ExportTarget.duplicateFrame`, which this only forwards.
+     */
+    get duplicateFrame(): boolean;
+    /**
+     * Start the measurement over, keeping the schedule.
+     *
+     * For a caller that records a warm-up in front of the clip proper: what a device
+     * costs while an encoder gets going is not what the clip is like, and the report is
+     * what the export decides whether to warn the player on.
+     */
+    resetPacing(): void;
+    start(): void;
+    /**
+     * Resolves with the finished clip, or null if nothing was recorded.
+     *
+     * The surface goes back before the promise resolves either way. A cancelled
+     * export that left the drawing buffer pinned to 1080x1920 would leave the game
+     * rendering into the wrong shape for the rest of the session.
+     */
+    stop(): Promise<Blob | null>;
+    /** Give the render surface back. Safe at any point, and idempotent. */
+    release(): void;
+    /**
+     * Bitrate from whatever the frame's real size turns out to be.
+     *
+     * Read from the track where possible, because that is the authority: a stream
+     * from a composited target has nothing to do with the canvas that was passed
+     * in, and guessing from the wrong one is how a 1080x1920 clip ends up encoded
+     * at a bitrate chosen for a 400-pixel window.
+     */
+    private defaultBitrate;
+}
+/**
+ * Hand a file to the player.
+ *
+ * `navigator.share` where it exists, because on a phone that is one tap into
+ * the app they were going to post to anyway; a download otherwise. A file in
+ * the Downloads folder that nobody can find is most of the way to no export at
+ * all.
+ */
+export declare function offerClip(blob: Blob, filename: string): Promise<void>;

package/dist/ui/frameRecorder.js

@@ -0,0 +1,221 @@
+import { supportedClipMimeType } from './clipMime.js';
+import { ExportTarget, clipBitrate, exportSizeFor } from './exportTarget.js';
+export const DEFAULT_CLIP_FPS = 30;
+export class FrameRecorder {
+    options;
+    recorder = null;
+    chunks = [];
+    mime;
+    target = null;
+    targetStream = null;
+    constructor(options) {
+        this.options = options;
+        const mime = supportedClipMimeType();
+        if (mime === null)
+            throw new Error('This browser cannot record video.');
+        if (options.canvas === undefined &&
+            options.stream === undefined &&
+            options.target === undefined) {
+            throw new Error('A recording needs a canvas, a stream or a target.');
+        }
+        this.mime = mime;
+    }
+    get mimeType() {
+        return this.mime;
+    }
+    /**
+     * Take over the render surface before recording starts.
+     *
+     * Separate from `start` because the aspect has to be in force *before* the
+     * first frame anybody records: the camera composes for `renderer.aspect`, so
+     * locking and recording in the same breath would put a screen-shaped shot in
+     * the first frames of a vertical clip. Returns the frame size that will be
+     * recorded, which is not always the one requested — see `measuredFps`.
+     */
+    prepare() {
+        const options = this.options.target;
+        if (options === undefined)
+            return null;
+        if (this.target !== null) {
+            return { width: this.target.width, height: this.target.height, reduced: false };
+        }
+        const fps = this.options.fps ?? DEFAULT_CLIP_FPS;
+        // The measurement was taken while rendering the *window*, so it is handed in
+        // with the pixel count it was taken at — see `exportSizeFor`.
+        const size = exportSizeFor(options.width, options.height, options.measuredFps ?? 0, fps, options.source.width * options.source.height);
+        this.target = new ExportTarget({
+            source: options.source,
+            surface: options.surface,
+            width: size.width,
+            height: size.height,
+            fps,
+            ...(options.overlay === undefined ? {} : { overlay: options.overlay }),
+            ...(options.drawFrame === undefined ? {} : { drawFrame: options.drawFrame }),
+            ...(options.presentedFrames === undefined
+                ? {}
+                : { presentedFrames: options.presentedFrames }),
+        });
+        this.targetStream = this.target.acquire();
+        return size;
+    }
+    /**
+     * Whether the frame about to be drawn will be kept. True when there is no
+     * fixed target, so a caller can gate its render pass unconditionally.
+     *
+     * Call once per animation frame, drawing or not: the instant is kept and reused
+     * when the frame is handed over, so one clock decides and commits.
+     */
+    captureDue(nowMs) {
+        return this.target?.captureDue(nowMs) ?? true;
+    }
+    /**
+     * One rendered frame, offered to the recording.
+     *
+     * Call at the very end of the render pass. Cheap and false when there is no
+     * fixed target, so a caller can hand every frame over unconditionally. Takes no
+     * instant — it uses the one `captureDue` was given for this frame.
+     */
+    frameRendered() {
+        return this.target?.frameRendered() ?? false;
+    }
+    /**
+     * What the pacing actually was, or null when recording the canvas directly.
+     *
+     * The measurement is the point rather than a diagnostic afterthought: an export
+     * that ran below its target rate produced a juddering file, and the only honest
+     * options are to say so or to have not measured.
+     */
+    get pacing() {
+        return this.target === null ? null : this.target.pacing;
+    }
+    /**
+     * Whether the frame `frameRendered` just composited repeats the one before it.
+     *
+     * False without a target, and false when `presentedFrames` was never supplied — the same
+     * two "no evidence yet" cases `pacing` already has to account for. See
+     * `ExportTarget.duplicateFrame`, which this only forwards.
+     */
+    get duplicateFrame() {
+        return this.target?.duplicateFrame ?? false;
+    }
+    /**
+     * Start the measurement over, keeping the schedule.
+     *
+     * For a caller that records a warm-up in front of the clip proper: what a device
+     * costs while an encoder gets going is not what the clip is like, and the report is
+     * what the export decides whether to warn the player on.
+     */
+    resetPacing() {
+        this.target?.resetPacing();
+    }
+    start() {
+        if (this.recorder !== null)
+            return;
+        const { canvas, audio, fps = DEFAULT_CLIP_FPS } = this.options;
+        if (this.options.target !== undefined)
+            this.prepare();
+        const source = this.targetStream ?? this.options.stream ?? canvas?.captureStream(fps) ?? null;
+        if (source === null)
+            throw new Error('A recording needs a canvas, a stream or a target.');
+        /*
+         * A fresh stream rather than the source one. Adding the audio tracks to a
+         * stream the caller owns means stopping the recording would stop the audio
+         * graph's capture track too, and a second export would then come out silent.
+         */
+        const stream = new MediaStream();
+        for (const track of source.getVideoTracks())
+            stream.addTrack(track);
+        if (audio != null) {
+            for (const track of audio.getAudioTracks())
+                stream.addTrack(track);
+        }
+        this.chunks = [];
+        this.recorder = new MediaRecorder(stream, {
+            mimeType: this.mime,
+            videoBitsPerSecond: this.options.videoBitsPerSecond ?? this.defaultBitrate(stream, fps),
+        });
+        this.recorder.ondataavailable = (event) => {
+            if (event.data.size > 0)
+                this.chunks.push(event.data);
+        };
+        this.recorder.start();
+    }
+    /**
+     * Resolves with the finished clip, or null if nothing was recorded.
+     *
+     * The surface goes back before the promise resolves either way. A cancelled
+     * export that left the drawing buffer pinned to 1080x1920 would leave the game
+     * rendering into the wrong shape for the rest of the session.
+     */
+    async stop() {
+        const recorder = this.recorder;
+        if (recorder === null) {
+            this.release();
+            return null;
+        }
+        this.recorder = null;
+        await new Promise((resolve) => {
+            recorder.onstop = () => resolve();
+            try {
+                recorder.stop();
+            }
+            catch {
+                resolve();
+            }
+        });
+        this.release();
+        if (this.chunks.length === 0)
+            return null;
+        return new Blob(this.chunks, { type: this.mime });
+    }
+    /** Give the render surface back. Safe at any point, and idempotent. */
+    release() {
+        this.target?.release();
+        this.target = null;
+        this.targetStream = null;
+    }
+    /**
+     * Bitrate from whatever the frame's real size turns out to be.
+     *
+     * Read from the track where possible, because that is the authority: a stream
+     * from a composited target has nothing to do with the canvas that was passed
+     * in, and guessing from the wrong one is how a 1080x1920 clip ends up encoded
+     * at a bitrate chosen for a 400-pixel window.
+     */
+    defaultBitrate(stream, fps) {
+        const track = stream.getVideoTracks()[0];
+        const settings = track?.getSettings();
+        const width = settings?.width ?? this.options.canvas?.width ?? 1280;
+        const height = settings?.height ?? this.options.canvas?.height ?? 720;
+        return clipBitrate(width, height, fps);
+    }
+}
+/**
+ * Hand a file to the player.
+ *
+ * `navigator.share` where it exists, because on a phone that is one tap into
+ * the app they were going to post to anyway; a download otherwise. A file in
+ * the Downloads folder that nobody can find is most of the way to no export at
+ * all.
+ */
+export async function offerClip(blob, filename) {
+    const file = new File([blob], filename, { type: blob.type });
+    if (typeof navigator.canShare === 'function' && navigator.canShare({ files: [file] })) {
+        try {
+            await navigator.share({ files: [file] });
+            return;
+        }
+        catch {
+            // Cancelled, or refused. Fall through to a download rather than leaving
+            // the player with nothing.
+        }
+    }
+    const url = URL.createObjectURL(blob);
+    const link = document.createElement('a');
+    link.href = url;
+    link.download = filename;
+    link.click();
+    // Revoked on the next turn: doing it synchronously races the download in
+    // some browsers and produces an empty file.
+    setTimeout(() => URL.revokeObjectURL(url), 10_000);
+}

package/dist/ui/fullscreen.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Filling the screen on a handheld, from a gesture that is already happening.
+ *
+ * A browser tab on a phone keeps its URL bar, and the game keeps whatever is left.
+ * There is no declaration that changes that — no manifest key, no meta tag, and
+ * nothing anywhere on the web platform that marks a page as a game and is granted
+ * anything for it. A page fills a phone's screen in exactly two ways: it is an
+ * *installed* app whose manifest asks for `display: fullscreen`, or it calls
+ * `requestFullscreen` from a user gesture. This is the second one. The manifest is
+ * the consumer's to ship and covers the installed case; between them every Android
+ * entry point is covered, and iPhone Safari is covered by neither because it has no
+ * element fullscreen at all — only the installed route.
+ *
+ * Game-agnostic (AGENTS.md): an element and a gesture. It knows nothing about what
+ * is being drawn into the element.
+ *
+ * **Handheld only, and once.** Two restraints, both of them about not taking a
+ * decision away from somebody who has already made it:
+ *
+ * A desktop player has a window they chose the size of, and a key that toggles
+ * fullscreen whenever they want it. Seizing the whole display because they clicked
+ * a menu button is the behaviour every embedded video player has been hated for.
+ * So the request is made where the screen is small and there is no other way to
+ * reclaim the space, and nowhere else.
+ *
+ * And a player who leaves fullscreen — the back gesture, the notification shade,
+ * the system button — has said something. Asking again on their next tap would be
+ * an argument they cannot win, since every tap is another gesture and every gesture
+ * is another chance to ask. One attempt per page load, whether it is granted,
+ * refused or undone.
+ */
+/** What the decision needs to know. Every field is observed, none of it inferred. */
+export interface FullscreenConditions {
+    /**
+     * A handheld, decided by the pointer rather than by the user agent string.
+     *
+     * `(pointer: coarse)` is the property that actually matters — a finger, no
+     * hover, no window to speak of — and unlike a UA sniff it is right about a
+     * tablet, right about a phone in desktop-site mode, and right about a laptop
+     * with a touchscreen that is being driven by its trackpad.
+     */
+    readonly coarsePointer: boolean;
+    /** Whether the API exists here at all. False on iPhone Safari. */
+    readonly supported: boolean;
+    /** Already filling the screen: asking again is a no-op that can still reject. */
+    readonly alreadyFullscreen: boolean;
+    /** Asked once already this page load, granted or not. See the header. */
+    readonly askedBefore: boolean;
+}
+/**
+ * Whether to ask for fullscreen on the gesture currently being handled.
+ *
+ * Pure, so all four restraints are checkable without a browser — which is the whole
+ * of this module's logic. The call itself is one line and is verified by hand, per
+ * AGENTS.md's rule that DOM is not unit-tested.
+ */
+export declare function fullscreenWanted(conditions: FullscreenConditions): boolean;
+/**
+ * Ask for fullscreen on the next gesture of any kind, once, on a handheld.
+ *
+ * Returns the way to stop listening. The listeners are passive and in the capture
+ * phase, matching the audio unlock that shares this moment: a page whose first
+ * gesture has to both start the audio graph and claim the screen should do both from
+ * that one gesture, not ask for a second one.
+ *
+ * Failure is silence by design. `requestFullscreen` rejects when the browser is not
+ * satisfied that a gesture is in progress, when an ancestor iframe has no
+ * `allowfullscreen`, and on platforms that expose the method and refuse it anyway.
+ * None of those is worth a message to somebody who did not ask for fullscreen in the
+ * first place and whose game is running either way.
+ */
+export declare function requestFullscreenOnGesture(element: HTMLElement): () => void;

package/dist/ui/fullscreen.js

@@ -0,0 +1,92 @@
+/**
+ * Filling the screen on a handheld, from a gesture that is already happening.
+ *
+ * A browser tab on a phone keeps its URL bar, and the game keeps whatever is left.
+ * There is no declaration that changes that — no manifest key, no meta tag, and
+ * nothing anywhere on the web platform that marks a page as a game and is granted
+ * anything for it. A page fills a phone's screen in exactly two ways: it is an
+ * *installed* app whose manifest asks for `display: fullscreen`, or it calls
+ * `requestFullscreen` from a user gesture. This is the second one. The manifest is
+ * the consumer's to ship and covers the installed case; between them every Android
+ * entry point is covered, and iPhone Safari is covered by neither because it has no
+ * element fullscreen at all — only the installed route.
+ *
+ * Game-agnostic (AGENTS.md): an element and a gesture. It knows nothing about what
+ * is being drawn into the element.
+ *
+ * **Handheld only, and once.** Two restraints, both of them about not taking a
+ * decision away from somebody who has already made it:
+ *
+ * A desktop player has a window they chose the size of, and a key that toggles
+ * fullscreen whenever they want it. Seizing the whole display because they clicked
+ * a menu button is the behaviour every embedded video player has been hated for.
+ * So the request is made where the screen is small and there is no other way to
+ * reclaim the space, and nowhere else.
+ *
+ * And a player who leaves fullscreen — the back gesture, the notification shade,
+ * the system button — has said something. Asking again on their next tap would be
+ * an argument they cannot win, since every tap is another gesture and every gesture
+ * is another chance to ask. One attempt per page load, whether it is granted,
+ * refused or undone.
+ */
+/**
+ * Whether to ask for fullscreen on the gesture currently being handled.
+ *
+ * Pure, so all four restraints are checkable without a browser — which is the whole
+ * of this module's logic. The call itself is one line and is verified by hand, per
+ * AGENTS.md's rule that DOM is not unit-tested.
+ */
+export function fullscreenWanted(conditions) {
+    const { coarsePointer, supported, alreadyFullscreen, askedBefore } = conditions;
+    return coarsePointer && supported && !alreadyFullscreen && !askedBefore;
+}
+/**
+ * Ask for fullscreen on the next gesture of any kind, once, on a handheld.
+ *
+ * Returns the way to stop listening. The listeners are passive and in the capture
+ * phase, matching the audio unlock that shares this moment: a page whose first
+ * gesture has to both start the audio graph and claim the screen should do both from
+ * that one gesture, not ask for a second one.
+ *
+ * Failure is silence by design. `requestFullscreen` rejects when the browser is not
+ * satisfied that a gesture is in progress, when an ancestor iframe has no
+ * `allowfullscreen`, and on platforms that expose the method and refuse it anyway.
+ * None of those is worth a message to somebody who did not ask for fullscreen in the
+ * first place and whose game is running either way.
+ */
+export function requestFullscreenOnGesture(element) {
+    const events = ['pointerdown', 'keydown', 'touchstart'];
+    let asked = false;
+    function stop() {
+        for (const event of events)
+            window.removeEventListener(event, fire, true);
+    }
+    function fire() {
+        const wanted = fullscreenWanted({
+            coarsePointer: matchesCoarsePointer(),
+            supported: typeof element.requestFullscreen === 'function',
+            alreadyFullscreen: document.fullscreenElement !== null,
+            askedBefore: asked,
+        });
+        // Detached either way: on a desktop the answer will never change, and on a
+        // handheld the one attempt has now been made.
+        asked = true;
+        stop();
+        if (!wanted)
+            return;
+        // Floating deliberately. There is nothing to do with the rejection but ignore
+        // it, and awaiting it would hold up the gesture that is unlocking the audio.
+        void element.requestFullscreen().catch(() => {
+            /* Refused. The game is running regardless. */
+        });
+    }
+    for (const event of events)
+        window.addEventListener(event, fire, true);
+    return stop;
+}
+/** `(pointer: coarse)`, defensively — an engine without `matchMedia` is a test one. */
+function matchesCoarsePointer() {
+    if (typeof window.matchMedia !== 'function')
+        return false;
+    return window.matchMedia('(pointer: coarse)').matches;
+}

package/dist/ui/pixelCursor.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Pixel art from a string grid, as a CSS cursor value.
+ *
+ * Generated rather than shipped as a PNG. Two reasons, and the second is the
+ * one that matters: a generated cursor costs no asset and no request, and it
+ * can be recoloured at runtime — so it belongs to whatever palette the game is
+ * currently wearing instead of being a fixed image that clashes with half of
+ * them.
+ *
+ * Rendered at the device pixel ratio and declared through `image-set`, so it is
+ * crisp on a retina display. A bitmap authored at 1x is upscaled smoothly by
+ * the browser, which is precisely the wrong thing to do to pixel art.
+ */
+export interface PixelCursorOptions {
+    /** Device-independent pixels per art pixel. */
+    readonly scale?: number;
+    /** The art pixel that sits under the pointer. Defaults to the centre. */
+    readonly hotspotX?: number;
+    readonly hotspotY?: number;
+    /** Keyword used when the image cannot be built. */
+    readonly fallback?: string;
+}
+/**
+ * @param rows one string per row; each character indexes `palette`.
+ * @param palette character → CSS colour. A character absent from it is
+ *   transparent, which is what makes `' '` the natural empty cell.
+ */
+export declare function pixelCursor(rows: readonly string[], palette: Readonly<Record<string, string>>, options?: PixelCursorOptions): string;

package/dist/ui/pixelCursor.js

@@ -0,0 +1,66 @@
+/**
+ * @param rows one string per row; each character indexes `palette`.
+ * @param palette character → CSS colour. A character absent from it is
+ *   transparent, which is what makes `' '` the natural empty cell.
+ */
+export function pixelCursor(rows, palette, options = {}) {
+    const fallback = options.fallback ?? 'auto';
+    const height = rows.length;
+    const width = rows[0]?.length ?? 0;
+    if (width === 0 || height === 0)
+        return fallback;
+    const scale = Math.max(1, Math.round(options.scale ?? 3));
+    const dpr = Math.max(1, Math.round(globalThis.devicePixelRatio ?? 1));
+    const cssWidth = width * scale;
+    const cssHeight = height * scale;
+    const hotspotX = Math.round((options.hotspotX ?? (width - 1) / 2) * scale);
+    const hotspotY = Math.round((options.hotspotY ?? (height - 1) / 2) * scale);
+    const url = render(rows, palette, cssWidth * dpr, cssHeight * dpr, scale * dpr);
+    if (url === null)
+        return fallback;
+    /*
+     * `image-set` carries the pixel ratio the image was drawn at, so the browser
+     * displays it at the right physical size instead of treating device pixels as
+     * CSS pixels and rendering a cursor a third of the intended size.
+     *
+     * The bare `url()` in front is the fallback for engines without image-set in
+     * `cursor`; there the image is oversized on retina rather than absent, which
+     * is the better of the two failures.
+     */
+    const hotspot = `${hotspotX} ${hotspotY}`;
+    if (dpr === 1)
+        return `url(${url}) ${hotspot}, ${fallback}`;
+    return `image-set(url(${url}) ${dpr}x) ${hotspot}, url(${url}) ${hotspot}, ${fallback}`;
+}
+function render(rows, palette, pixelWidth, pixelHeight, cellSize) {
+    let canvas;
+    try {
+        canvas = document.createElement('canvas');
+    }
+    catch {
+        return null;
+    }
+    canvas.width = pixelWidth;
+    canvas.height = pixelHeight;
+    const ctx = canvas.getContext('2d');
+    if (ctx === null)
+        return null;
+    for (let y = 0; y < rows.length; y++) {
+        const row = rows[y] ?? '';
+        for (let x = 0; x < row.length; x++) {
+            const colour = palette[row[x] ?? ''];
+            if (colour === undefined)
+                continue;
+            ctx.fillStyle = colour;
+            // Filled as whole cells rather than drawn small and scaled up: this is
+            // what keeps the edges hard at any ratio.
+            ctx.fillRect(x * cellSize, y * cellSize, cellSize, cellSize);
+        }
+    }
+    try {
+        return canvas.toDataURL('image/png');
+    }
+    catch {
+        return null;
+    }
+}