Skip to content

Record your screen, ship a demo. Free and open-source, GPU-accelerated, no watermarks, no subscriptions. Windows, macOS, Linux. Actively maintained.

12.5 KB
Raw Blame
import type { NativeCursorType } from "@/native/contracts";

/**
 * A single themed cursor image override for one {@link NativeCursorType}.
 *
 * width/height/hotspot are in the same ~32-logical-pixel reference as the built-in
 * PRETTY_NATIVE_CURSOR_ASSETS, so a theme asset matches the default cursor's on-screen
 * size regardless of source PNG resolution. The PNG can be higher-res (e.g. 128x128)
 * and is downscaled at draw time for crisper retina output.
 */
export interface CursorThemeAsset {
	/** Path relative to the public asset root, e.g. "cursors/<id>/arrow.png". */
	assetPath: string;
	width: number;
	height: number;
	hotspotX: number;
	hotspotY: number;
	/** The compositor models this state in 3D (`crates/compositor/src/sculpt.rs`) instead of
	 *  extruding the flat asset, which stays the 2D art. */
	sculpted?: boolean;
	/** With the 3D option off too, the compositor draws this state as a lens of glass over the
	 *  picture (its 3D model seen face on), not the flat asset, which only shows in the picker. */
	glass?: boolean;
}

export interface CursorTheme {
	id: string;
	/** Display label. Proper nouns, so not run through i18n. */
	name: string;
	/** Attribution / origin for the artwork. */
	source?: string;
	/**
	 * Per-cursor-type overrides. Missing types fall back to the built-in default art,
	 * so a pack that only ships "arrow" and "pointer" is complete.
	 */
	assets: Partial<Record<NativeCursorType, CursorThemeAsset>>;
}

/** Sentinel id for the built-in cursor art (no theme override). */
export const DEFAULT_CURSOR_THEME_ID = "default";

/**
 * One sprite as the native compositor consumes it: a path under the public asset root,
 * plus the hotspot as a 0..1 fraction OF THAT IMAGE.
 *
 * The fraction is the whole point of the contract. The compositor scales the sprite to
 * the cursor-size setting, so an offset expressed in the source image's pixels would have
 * to be rescaled at draw time; a fraction survives any scale untouched. Getting this wrong
 * is what made an enlarged cursor drift further and further from what it points at.
 */
export interface CursorSprite {
	/** Path relative to the public asset root, e.g. "cursors/default/arrow.png". */
	assetPath: string;
	/** Hotspot as a fraction of the image width / height. */
	hotspotX: number;
	hotspotY: number;
	/** The compositor's sculpted model for this state in 3D, `"<theme>/<state>"`
	 *  (`crates/compositor/src/sculpt.rs`). Without it, 3D extrudes the sprite. */
	sculpt?: string;
	/** The glass model the compositor draws for this state with 3D off, `"<theme>/<state>"`, in
	 *  place of the sprite (see `CursorThemeAsset.glass`). */
	glass?: string;
}

/**
 * The built-in cursor art, rasterized from src/assets/cursors/*.svg — the native
 * compositor decodes png/jpeg from disk and cannot read those SVGs (they only exist as
 * bundler URLs in the renderer).
 *
 * Generated by scripts/generate-default-cursor-sprites.mjs; regenerate it rather than
 * hand-editing, so the PNGs and these hotspots can't drift apart.
 */
export const DEFAULT_CURSOR_SPRITES: Record<NativeCursorType, CursorSprite> = {
	arrow: { assetPath: "cursors/default/arrow.png", hotspotX: 0.1205, hotspotY: 0.0881 },
	text: { assetPath: "cursors/default/text.png", hotspotX: 0.4355, hotspotY: 0.5369 },
	pointer: { assetPath: "cursors/default/pointer.png", hotspotX: 0.3874, hotspotY: 0.0032 },
	crosshair: { assetPath: "cursors/default/crosshair.png", hotspotX: 0.4667, hotspotY: 0.4667 },
	"open-hand": { assetPath: "cursors/default/open-hand.png", hotspotX: 0.4375, hotspotY: 0.1724 },
	"closed-hand": {
		assetPath: "cursors/default/closed-hand.png",
		hotspotX: 0.3889,
		hotspotY: 0.4455,
	},
	"resize-ew": { assetPath: "cursors/default/resize-ew.png", hotspotX: 0.485, hotspotY: 0.4706 },
	"resize-ns": { assetPath: "cursors/default/resize-ns.png", hotspotX: 0.5, hotspotY: 0.5 },
	"resize-nesw": { assetPath: "cursors/default/resize-nesw.png", hotspotX: 0.5, hotspotY: 0.5 },
	"resize-nwse": { assetPath: "cursors/default/resize-nwse.png", hotspotX: 0.5, hotspotY: 0.5 },
	move: { assetPath: "cursors/default/move.png", hotspotX: 0.4437, hotspotY: 0.4437 },
	"not-allowed": { assetPath: "cursors/default/not-allowed.png", hotspotX: 0.5, hotspotY: 0.5 },
	wait: { assetPath: "cursors/default/wait.png", hotspotX: 0.5, hotspotY: 0.5 },
	"app-starting": {
		assetPath: "cursors/default/app-starting.png",
		hotspotX: 0.05,
		hotspotY: 0.0537,
	},
	help: { assetPath: "cursors/default/help.png", hotspotX: 0.0515, hotspotY: 0.0572 },
	"up-arrow": { assetPath: "cursors/default/up-arrow.png", hotspotX: 0.5, hotspotY: 0.069 },
};

/**
 * The cursors a project can draw as recorded or as the arrow, grouped the way they read on
 * screen: the four resize directions and the move cross are one "resize", the open and closed
 * hands one "grab". The arrow is not one of them: it is what the others turn into.
 */
export const CURSOR_KINDS = {
	pointer: ["pointer"],
	text: ["text"],
	grab: ["open-hand", "closed-hand"],
	resize: ["resize-ew", "resize-ns", "resize-nwse", "resize-nesw", "move"],
	busy: ["wait", "app-starting"],
	crosshair: ["crosshair"],
	"not-allowed": ["not-allowed"],
	help: ["help"],
	"up-arrow": ["up-arrow"],
} as const satisfies Record<string, readonly Exclude<NativeCursorType, "arrow">[]>;

export type CursorKind = keyof typeof CURSOR_KINDS;

export const CURSOR_KIND_IDS = Object.keys(CURSOR_KINDS) as CursorKind[];

/**
 * The kinds a project draws as the arrow, from what it stored: known ids only, once each, in
 * `CURSOR_KINDS` order, and `fallback` (the project default) when it stored no list.
 * `alwaysArrow` is the single switch that came before the kinds could be picked: on meant all of
 * them, off was its default and says nothing more than an absent list.
 */
export function readCursorAsArrow(
	asArrow: unknown,
	alwaysArrow: unknown,
	fallback: readonly CursorKind[],
): CursorKind[] {
	if (Array.isArray(asArrow)) return CURSOR_KIND_IDS.filter((kind) => asArrow.includes(kind));
	return alwaysArrow === true ? [...CURSOR_KIND_IDS] : [...fallback];
}

/**
 * Bundled cursor themes. These six packs are original OpenScreen artwork. Their raster
 * masters live in design/cursors/ and are prepared by scripts/generate-original-cursor-themes.mjs,
 * except Pixel Candy's pixel art, drawn as a grid in scripts/generate-pixel-candy-voxels.mjs, and
 * Glass Lens, whose picker PNGs scripts/generate-glass-lens-cursor.mjs draws from its 3D model.
 * The former Sweezy packs were removed
 * because their terms forbid redistribution without written permission.
 *
 * To add one: drop arrow.png/pointer.png into public/cursors/<id>/ and add an entry here
 * with hotspots normalized to the 32-logical reference (divide a 128px-pack hotspot by 4).
 * Mark an asset `sculpted` when the compositor has a 3D model for it (`sculpt.rs`; Prism Glow's
 * is a crystal mesh traced on its drawing, `prism_mesh.rs`); other states are extruded from their
 * sprite in 3D. Mark it `glass` when the compositor draws it as glass with 3D off as well (Glass
 * Lens, mode 19). An id that leaves this list reads back as the default art
 * through `normalizeCursorThemeId`, so a project saved with it still opens.
 */
export const CURSOR_THEMES: readonly CursorTheme[] = [
	{
		id: "studio-ink",
		name: "Studio Ink",
		assets: {
			arrow: {
				assetPath: "cursors/studio-ink/arrow.png",
				width: 32,
				height: 32,
				hotspotX: 6.2304,
				hotspotY: 2.0992,
				sculpted: true,
			},
			pointer: {
				assetPath: "cursors/studio-ink/pointer.png",
				width: 32,
				height: 32,
				hotspotX: 12.848,
				hotspotY: 2.0704,
				sculpted: true,
			},
		},
	},
	{
		id: "prism-glow",
		name: "Prism Glow",
		assets: {
			arrow: {
				assetPath: "cursors/prism-glow/arrow.png",
				width: 32,
				height: 32,
				hotspotX: 6.3456,
				hotspotY: 2.0672,
				sculpted: true,
			},
			pointer: {
				assetPath: "cursors/prism-glow/pointer.png",
				width: 32,
				height: 32,
				hotspotX: 11.968,
				hotspotY: 2.0352,
				sculpted: true,
			},
		},
	},
	{
		id: "pop-coral",
		name: "Pop Coral",
		assets: {
			arrow: {
				assetPath: "cursors/pop-coral/arrow.png",
				width: 32,
				height: 32,
				hotspotX: 10.4768,
				hotspotY: 2.1792,
				sculpted: true,
			},
			pointer: {
				assetPath: "cursors/pop-coral/pointer.png",
				width: 32,
				height: 32,
				hotspotX: 12.3456,
				hotspotY: 2,
				sculpted: true,
			},
		},
	},
	{
		id: "pixel-candy",
		name: "Pixel Candy",
		assets: {
			arrow: {
				assetPath: "cursors/pixel-candy/arrow.png",
				width: 32,
				height: 32,
				hotspotX: 6.5,
				hotspotY: 2,
				sculpted: true,
			},
			pointer: {
				assetPath: "cursors/pixel-candy/pointer.png",
				width: 32,
				height: 32,
				hotspotX: 10.75,
				hotspotY: 2,
				sculpted: true,
			},
		},
	},
	{
		id: "star-sprout",
		name: "Star Sprout",
		assets: {
			arrow: {
				assetPath: "cursors/star-sprout/arrow.png",
				width: 32,
				height: 32,
				hotspotX: 4.7232,
				hotspotY: 2.1152,
				sculpted: true,
			},
			pointer: {
				assetPath: "cursors/star-sprout/pointer.png",
				width: 32,
				height: 32,
				hotspotX: 13.1712,
				hotspotY: 2.0384,
				sculpted: true,
			},
		},
	},
	{
		id: "glass-lens",
		name: "Glass Lens",
		assets: {
			arrow: {
				assetPath: "cursors/glass-lens/arrow.png",
				width: 32,
				height: 32,
				hotspotX: 9.744,
				hotspotY: 0.816,
				sculpted: true,
				glass: true,
			},
			pointer: {
				assetPath: "cursors/glass-lens/pointer.png",
				width: 32,
				height: 32,
				hotspotX: 12.872,
				hotspotY: 0.816,
				sculpted: true,
				glass: true,
			},
		},
	},
];

/** All selectable theme ids, including the built-in default. */
export const CURSOR_THEME_IDS: ReadonlySet<string> = new Set([
	DEFAULT_CURSOR_THEME_ID,
	...CURSOR_THEMES.map((theme) => theme.id),
]);

/**
 * Paths the theme picker should show. `pointer` is set only when that artwork
 * differs from `arrow`, so a pack with its own hand is not previewed as arrow-only.
 */
export function themePickerPreviewAssets(theme: CursorTheme | null): {
	arrow: string;
	pointer: string | null;
} {
	if (!theme) {
		const arrow = DEFAULT_CURSOR_SPRITES.arrow.assetPath;
		const pointer = DEFAULT_CURSOR_SPRITES.pointer.assetPath;
		return { arrow, pointer: pointer !== arrow ? pointer : null };
	}
	const arrow = theme.assets.arrow?.assetPath ?? theme.assets.pointer?.assetPath ?? "";
	const pointer = theme.assets.pointer?.assetPath ?? null;
	return { arrow, pointer: pointer && pointer !== arrow ? pointer : null };
}

/** Returns the theme for `id`, or null for the default / unknown ids. */
export function getCursorTheme(id: string | null | undefined): CursorTheme | null {
	if (!id || id === DEFAULT_CURSOR_THEME_ID) {
		return null;
	}
	return CURSOR_THEMES.find((theme) => theme.id === id) ?? null;
}

/**
 * Normalizes a persisted/incoming theme id to a known value, falling back to the
 * default for anything unrecognized.
 */
export function normalizeCursorThemeId(id: unknown): string {
	return typeof id === "string" && CURSOR_THEME_IDS.has(id) ? id : DEFAULT_CURSOR_THEME_ID;
}

/**
 * The full sprite set for a theme: its own art where it has any, the built-in art for
 * every other cursor state.
 *
 * A pack may ship only an arrow and a pointer, but a recording moves through a dozen OS
 * states — text, resize, wait, grab. Serving the theme's arrow for all of them (what the
 * native path used to do) shows a resize handle as an arrow; serving nothing shows a
 * placeholder. Mixing in the built-in art per state keeps the pointer honest about what
 * the user was doing, and a pack that later adds a text.png slots straight in.
 */
export function resolveCursorSprites(
	themeId: string | null | undefined,
	asArrow: readonly CursorKind[] = [],
	model3d = false,
): Record<NativeCursorType, CursorSprite> {
	const sprites = { ...DEFAULT_CURSOR_SPRITES };
	for (const [type, asset] of Object.entries(getCursorTheme(themeId)?.assets ?? {})) {
		if (asset.width <= 0 || asset.height <= 0) {
			continue;
		}
		sprites[type as NativeCursorType] = {
			assetPath: asset.assetPath,
			// Theme hotspots are authored against the asset's own 32-logical reference;
			// the contract is a fraction of the image. See CursorSprite.
			hotspotX: asset.hotspotX / asset.width,
			hotspotY: asset.hotspotY / asset.height,
			...(model3d && asset.sculpted ? { sculpt: `${themeId}/${type}` } : {}),
			...(asset.glass ? { glass: `${themeId}/${type}` } : {}),
		};
	}
	// A kind drawn as the arrow takes the arrow's sprite, with the theme's art and its 3D model.
	// Done on the table the compositor reads, so it needs no mode of its own.
	for (const kind of asArrow) {
		for (const type of CURSOR_KINDS[kind]) {
			sprites[type] = sprites.arrow;
		}
	}
	return sprites;
}