@aphrody/shenron-dbxv2 0.0.0-stage → 1.4.7

package/src/declarations.ts

@@ -0,0 +1,135 @@
+/**
+ * Generation of `dbxv2.d.ts`: ambient modules typed per format for `dbxv2:*?<format>` imports and
+ * a union of the known entry paths, read from the private index. The file is written under `var/`
+ * (ignored by Git) and is itself refused by the public build guard.
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, resolve, sep } from "node:path";
+import type { Dbxv2Client } from "./client";
+import { Dbxv2ConfigError } from "./errors";
+import { DBXV2_DECLARATIONS_FILE, DBXV2_MARKER } from "./guard";
+import { formatRef, parseRef, type Dbxv2Ref } from "./refs";
+
+export interface DeclarationOptions {
+  /** Past this many paths the union degrades to template literal types (default 20 000). */
+  readonly maxLiteralPaths?: number;
+}
+
+const EXTENSIONS = {
+  png: ["emb"],
+  wav: ["acb", "awb"],
+  video: ["usm"],
+  model: ["emd"],
+} as const;
+
+const lit = (value: string): string => JSON.stringify(value);
+
+const unionOf = (items: readonly string[], fallback: string): string =>
+  items.length === 0 ? fallback : items.map(lit).join("\n  | ");
+
+/** Text of the declaration file for the given references (already validated). */
+export function renderDeclarations(
+  refs: readonly Dbxv2Ref[],
+  options: DeclarationOptions = {},
+): string {
+  const max = options.maxLiteralPaths ?? 20_000;
+  const all = [...new Set(refs.map(formatRef))].toSorted();
+  const literal = all.length <= max;
+  const byExt = (exts: readonly string[]): string[] =>
+    all.filter((p) => exts.includes(p.slice(p.lastIndexOf(".") + 1).toLowerCase()));
+  const pathType = (items: readonly string[]): string =>
+    literal ? unionOf(items, "never") : "`${string}/${string}`";
+
+  const lines = [
+    `// ${DBXV2_MARKER}: generated from the private DBXV2 index. Never commit, never ship.`,
+    "// Regenerate with: bun run --filter @aphrody/shenron-dbxv2 types",
+    "",
+    "/** Reference to an entry of a CPK: `<cpk>/<path>`. */",
+    `type Dbxv2KnownPath =\n  | ${pathType(all)};`,
+    `type Dbxv2KnownImage =\n  | ${pathType(byExt(EXTENSIONS.png))};`,
+    `type Dbxv2KnownAudio =\n  | ${pathType(byExt(EXTENSIONS.wav))};`,
+    `type Dbxv2KnownVideo =\n  | ${pathType(byExt(EXTENSIONS.video))};`,
+    `type Dbxv2KnownModel =\n  | ${pathType(byExt(EXTENSIONS.model))};`,
+    'type Dbxv2Specifier = `dbxv2:${Dbxv2KnownPath}?${"png" | "wav" | "video" | "model" | "glb" | "raw"}`;',
+    "",
+  ];
+  const resourceModule = (format: string, note: string): string[] => [
+    `/** ${note} */`,
+    `declare module "dbxv2:*?${format}" {`,
+    "  /** Entry reference. */",
+    "  export const ref: { readonly cpk: string; readonly path: string };",
+    "  /** Short-lived signed loopback URL (no token in it). */",
+    "  export const url: string;",
+    "  export function blob(signal?: AbortSignal): Promise<Blob>;",
+    "  export function arrayBuffer(signal?: AbortSignal): Promise<ArrayBuffer>;",
+    "  export default url;",
+    "}",
+    "",
+  ];
+  lines.push(
+    ...resourceModule("png", "EMB texture as PNG (`?png&index=N` selects another texture)."),
+    ...resourceModule("wav", "ACB sub-sound as WAV (`?wav&cue=N`)."),
+    ...resourceModule("video", "USM as MP4, WebM or MPEG-2."),
+    ...resourceModule("glb", "Assembled EMD as binary glTF."),
+    "/** Assembled EMD metadata (geometry and texture sizes), validated at load. */",
+    'declare module "dbxv2:*?model" {',
+    '  import type { Dbxv2ModelJson } from "@aphrody/shenron-dbxv2/schemas";',
+    "  export const ref: { readonly cpk: string; readonly path: string };",
+    "  export const jsonUrl: string;",
+    "  export const glbUrl: string;",
+    "  const model: Dbxv2ModelJson;",
+    "  export default model;",
+    "}",
+    "",
+    "/** Decompressed entry bytes. */",
+    'declare module "dbxv2:*?raw" {',
+    "  export const ref: { readonly cpk: string; readonly path: string };",
+    "  export const url: string;",
+    "  export function blob(signal?: AbortSignal): Promise<Blob>;",
+    "  const bytes: ArrayBuffer;",
+    "  export default bytes;",
+    "}",
+    "",
+  );
+  return lines.join("\n");
+}
+
+/** Every reference of the private server (all CPKs, or those listed), through `find`. */
+export async function collectKnownRefs(
+  client: Dbxv2Client,
+  options: { readonly cpks?: readonly string[]; readonly signal?: AbortSignal } = {},
+): Promise<Dbxv2Ref[]> {
+  const names = options.cpks ?? (await client.cpks({ signal: options.signal })).map((c) => c.name);
+  const refs: Dbxv2Ref[] = [];
+  for (const name of names) {
+    for await (const entry of client.findAll(name, { signal: options.signal, pageSize: 5000 })) {
+      try {
+        refs.push(parseRef({ cpk: name, path: entry.path }));
+      } catch {
+        // an entry name the reference grammar rejects cannot be imported anyway
+      }
+    }
+  }
+  return refs;
+}
+
+/** Default target: `<cwd>/var/dbxv2/dbxv2.d.ts` (ignored by Git). */
+export function defaultDeclarationsPath(cwd: string): string {
+  return resolve(cwd, "var", "dbxv2", DBXV2_DECLARATIONS_FILE);
+}
+
+/** Writes the declarations; refuses a path outside a `var/` directory unless `allowOutsideVar`. */
+export function writeDeclarations(
+  outFile: string,
+  content: string,
+  options: { readonly allowOutsideVar?: boolean } = {},
+): string {
+  const target = resolve(outFile);
+  if (!options.allowOutsideVar && !target.split(sep).includes("var"))
+    throw new Dbxv2ConfigError(
+      `refusing to write DBXV2 declarations outside a var/ directory: ${target}`,
+    );
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, content, "utf8");
+  return target;
+}

package/src/env.ts

@@ -0,0 +1,111 @@
+/**
+ * Explicit public gateway configuration and private server gating.
+ * Local database paths remain unavailable in public builds. Pure: callers pass the environment.
+ */
+
+export type Dbxv2EnvInput = Readonly<Record<string, string | undefined>>;
+
+export const DBXV2_MIN_TOKEN_LENGTH = 16;
+
+export interface Dbxv2Config {
+  /** Origin (and optional path prefix) of the server, without trailing slash. */
+  readonly baseUrl: string;
+  readonly token?: string;
+  readonly mode?: "public";
+}
+
+export type Dbxv2DisabledReason =
+  | "public-render"
+  | "production"
+  | "missing-url"
+  | "invalid-url"
+  | "missing-token"
+  | "short-token";
+
+export type Dbxv2Status =
+  | { readonly enabled: true; readonly config: Dbxv2Config }
+  | { readonly enabled: false; readonly reason: Dbxv2DisabledReason };
+
+const WILDCARD_HOSTS = new Set(["0.0.0.0", "::", "[::]", ""]);
+
+const truthy = (value: string | undefined): boolean =>
+  value !== undefined && /^(?:1|true|yes|on)$/i.test(value.trim());
+
+/** A public render or build (or a production runtime): the private features never run there. */
+export function isPublicContext(env: Dbxv2EnvInput): Dbxv2DisabledReason | null {
+  if (
+    env.SHENRON_PROFILE === "public" ||
+    truthy(env.SHENRON_PUBLIC_RENDER) ||
+    truthy(env.SHENRON_PUBLIC_BUILD)
+  )
+    return "public-render";
+  if (env.NODE_ENV === "production") return "production";
+  return null;
+}
+
+/** Parses and validates a server URL; null when unusable (not http(s), wildcard host, credentials). */
+export function normalizeServerUrl(raw: string): string | null {
+  let url: URL;
+  try {
+    url = new URL(raw.trim());
+  } catch {
+    return null;
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+  if (WILDCARD_HOSTS.has(url.hostname)) return null;
+  if (url.username || url.password || url.search || url.hash) return null;
+  return url.href.replace(/\/+$/, "");
+}
+
+export function dbxv2Status(env: Dbxv2EnvInput): Dbxv2Status {
+  if (env.DBXV2_CLIENT_MODE === "public") {
+    const baseUrl = normalizeServerUrl(env.DBXV2_PUBLIC_URL ?? "");
+    if (!baseUrl || !baseUrl.startsWith("https://"))
+      return { enabled: false, reason: "invalid-url" };
+    return { enabled: true, config: { mode: "public", baseUrl } };
+  }
+  const context = isPublicContext(env);
+  if (context === "public-render") return { enabled: false, reason: context };
+  const rawUrl = env.DBXV2_SERVER_URL?.trim();
+  if (!rawUrl) return { enabled: false, reason: "missing-url" };
+  const baseUrl = normalizeServerUrl(rawUrl);
+  if (!baseUrl) return { enabled: false, reason: "invalid-url" };
+  const token = env.DBXV2_TOKEN ?? "";
+  if (!token) return { enabled: false, reason: "missing-token" };
+  if (token.length < DBXV2_MIN_TOKEN_LENGTH) return { enabled: false, reason: "short-token" };
+  return { enabled: true, config: { baseUrl, token } };
+}
+
+/** The server client features (`DBXV2_SERVER_URL` and `DBXV2_TOKEN`) are usable. */
+export function isDbxv2Enabled(env: Dbxv2EnvInput): boolean {
+  return dbxv2Status(env).enabled;
+}
+
+/** Path of the private database (`DBXV2_DB_PATH`), or null when unset or in a public context. */
+export function dbxv2DbPath(env: Dbxv2EnvInput): string | null {
+  if (isPublicContext(env)) return null;
+  const path = env.DBXV2_DB_PATH?.trim();
+  return path ? path : null;
+}
+
+export function isDbxv2DbEnabled(env: Dbxv2EnvInput): boolean {
+  return dbxv2DbPath(env) !== null;
+}
+
+const REASONS: Readonly<Record<Dbxv2DisabledReason, string>> = {
+  "public-render": "DBXV2 is never available in a public render or build",
+  production: "DBXV2 is disabled when NODE_ENV=production",
+  "missing-url": "DBXV2_SERVER_URL is not set",
+  "invalid-url": "DBXV2_SERVER_URL must be an http(s) URL without credentials or wildcard host",
+  "missing-token": "DBXV2_TOKEN is not set",
+  "short-token": `DBXV2_TOKEN must hold at least ${DBXV2_MIN_TOKEN_LENGTH} characters`,
+};
+
+export function describeDisabledReason(reason: Dbxv2DisabledReason): string {
+  return REASONS[reason];
+}
+
+/** The process environment unless one is given (the only place that reads `process.env` by default). */
+export function currentEnv(env: Dbxv2EnvInput = process.env): Dbxv2EnvInput {
+  return env;
+}

package/src/errors.ts

@@ -0,0 +1,141 @@
+/** Typed errors and a Result helper. Messages never carry the token or any query string. */
+
+export type Dbxv2ErrorKind =
+  | "disabled"
+  | "config"
+  | "auth"
+  | "forbidden"
+  | "not_found"
+  | "range"
+  | "busy"
+  | "timeout"
+  | "server"
+  | "network"
+  | "aborted"
+  | "schema"
+  | "changed"
+  | "build_refused";
+
+/** Bytes received before a download failed, to resume with `download({ resume })`. */
+export interface Dbxv2Partial {
+  readonly bytes: Uint8Array;
+  readonly etag: string;
+  readonly size: number;
+}
+
+export class Dbxv2Error extends Error {
+  readonly kind: Dbxv2ErrorKind;
+  readonly status: number | null;
+  partial?: Dbxv2Partial;
+
+  constructor(
+    kind: Dbxv2ErrorKind,
+    message: string,
+    options: { status?: number | null; cause?: unknown } = {},
+  ) {
+    super(message, options.cause === undefined ? undefined : { cause: options.cause });
+    this.name = new.target.name;
+    this.kind = kind;
+    this.status = options.status ?? null;
+  }
+}
+
+export class Dbxv2DisabledError extends Dbxv2Error {
+  constructor(message: string) {
+    super("disabled", message);
+  }
+}
+export class Dbxv2ConfigError extends Dbxv2Error {
+  constructor(message: string) {
+    super("config", message);
+  }
+}
+export class Dbxv2AuthError extends Dbxv2Error {
+  constructor(message = "unauthorized: check DBXV2_TOKEN") {
+    super("auth", message, { status: 401 });
+  }
+}
+export class Dbxv2ForbiddenError extends Dbxv2Error {
+  constructor(message: string) {
+    super("forbidden", message, { status: 403 });
+  }
+}
+export class Dbxv2NotFoundError extends Dbxv2Error {
+  constructor(message: string) {
+    super("not_found", message, { status: 404 });
+  }
+}
+export class Dbxv2RangeError extends Dbxv2Error {
+  constructor(message: string) {
+    super("range", message, { status: 416 });
+  }
+}
+export class Dbxv2BusyError extends Dbxv2Error {
+  constructor(message: string, status = 503) {
+    super("busy", message, { status });
+  }
+}
+export class Dbxv2TimeoutError extends Dbxv2Error {
+  constructor(message: string, status: number | null = null) {
+    super("timeout", message, { status });
+  }
+}
+export class Dbxv2ServerError extends Dbxv2Error {
+  constructor(message: string, status: number) {
+    super("server", message, { status });
+  }
+}
+export class Dbxv2NetworkError extends Dbxv2Error {
+  constructor(message: string, cause?: unknown) {
+    super("network", message, { cause });
+  }
+}
+export class Dbxv2AbortError extends Dbxv2Error {
+  constructor(message = "request aborted") {
+    super("aborted", message);
+  }
+}
+export class Dbxv2SchemaError extends Dbxv2Error {
+  readonly issues: readonly string[];
+  constructor(message: string, issues: readonly string[] = []) {
+    super("schema", message);
+    this.issues = issues;
+  }
+}
+/** The entry changed on the server while a ranged download was in progress. */
+export class Dbxv2ChangedError extends Dbxv2Error {
+  constructor(message: string) {
+    super("changed", message, { status: 200 });
+  }
+}
+export class Dbxv2BuildRefusedError extends Dbxv2Error {
+  constructor(message: string) {
+    super("build_refused", message);
+  }
+}
+
+export type Result<T, E extends Error = Dbxv2Error> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly error: E };
+
+/** Runs `fn` and turns a thrown {@link Dbxv2Error} into a failed Result; other errors propagate. */
+export async function attempt<T>(fn: () => Promise<T>): Promise<Result<T>> {
+  try {
+    return { ok: true, value: await fn() };
+  } catch (error) {
+    if (error instanceof Dbxv2Error) return { ok: false, error };
+    throw error;
+  }
+}
+
+/** Maps an HTTP error status of the private server to a typed error. */
+export function errorForStatus(status: number, detail: string): Dbxv2Error {
+  const message = `${detail} (HTTP ${status})`;
+  if (status === 401) return new Dbxv2AuthError(message);
+  if (status === 403) return new Dbxv2ForbiddenError(message);
+  if (status === 404) return new Dbxv2NotFoundError(message);
+  if (status === 416) return new Dbxv2RangeError(message);
+  if (status === 503) return new Dbxv2BusyError(message, status);
+  if (status === 504) return new Dbxv2TimeoutError(message, status);
+  return new Dbxv2ServerError(message, status);
+}

package/src/guard.ts

@@ -0,0 +1,115 @@
+/**
+ * Public-build guard: no DBXV2 module, type declaration or marker may reach a public bundle or
+ * release tree. Every module generated by the `dbxv2:` plugin carries {@link DBXV2_MARKER}, and
+ * the public server build (`scripts/build/server.ts`) fails when it finds one.
+ */
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { Dbxv2BuildRefusedError } from "./errors";
+import { isPublicContext, type Dbxv2EnvInput } from "./env";
+
+/** Literal present in every generated module and declaration file. */
+export const DBXV2_MARKER = "@dbxv2-private";
+
+/** Basename of the generated declarations. */
+export const DBXV2_DECLARATIONS_FILE = "dbxv2.d.ts";
+
+/** The subset of `Bun.build` options the guard looks at. */
+export interface BuildConfigLike {
+  readonly minify?: unknown;
+  readonly define?: Readonly<Record<string, string>>;
+  readonly sourcemap?: unknown;
+  readonly splitting?: unknown;
+}
+
+/** Why a build is considered public/production, or null when it is a development build. */
+export function publicBuildReason(
+  config: BuildConfigLike | undefined,
+  env: Dbxv2EnvInput,
+): string | null {
+  const context = isPublicContext(env);
+  if (context === "public-render") return "SHENRON_PROFILE/SHENRON_PUBLIC_* marks a public build";
+  if (context === "production") return "NODE_ENV=production";
+  if (config?.minify) return "minify is enabled (production build)";
+  const nodeEnv = config?.define?.["process.env.NODE_ENV"];
+  if (nodeEnv !== undefined && /production/.test(nodeEnv)) return "define NODE_ENV=production";
+  return null;
+}
+
+/** Throws {@link Dbxv2BuildRefusedError} when a public or production build asks for DBXV2 modules. */
+export function assertDbxv2BuildAllowed(
+  config: BuildConfigLike | undefined,
+  env: Dbxv2EnvInput,
+): void {
+  const reason = publicBuildReason(config, env);
+  if (reason) {
+    throw new Dbxv2BuildRefusedError(
+      `Bun.build refused for dbxv2: modules (${reason}). DBXV2 is private (Bandai Namco / Dimps) ` +
+        "and must never be bundled into a public or production artifact.",
+    );
+  }
+}
+
+/**
+ * Binary public assets (WebAssembly, images, audio, video, models) are scanned too: the marker,
+ * the private relay/serve names and the private-store references must not appear in them.
+ */
+const BINARY_SCANNED =
+  /\.(?:wasm|png|webp|avif|jpe?g|gif|ico|mp3|ogg|wav|mp4|m2v|webm|glb|gltf|bin)$/i;
+const MAX_BINARY = 256 * 1024 * 1024;
+
+/** Byte strings that identify the private DBXV2 store or its relays inside a binary asset. */
+export const DBXV2_BINARY_REFERENCES: readonly string[] = [
+  DBXV2_MARKER,
+  "admin/dbxv2/media",
+  "dbxv2-serve",
+  "DBXV2_SERVER_URL",
+  "DBXV2_DB_PATH",
+];
+
+const SCANNED = /\.(?:m?js|cjs|ts|mts|cts|d\.ts|map|json|html)$/i;
+const MAX_FILE = 16 * 1024 * 1024;
+
+/**
+ * Files under `dir` that carry the DBXV2 marker (text or binary: wasm, images, media) or are the generated declarations (paths relative
+ * to `dir`). `node_modules` are not skipped: a leak there ships as well.
+ */
+export function findDbxv2Leaks(dir: string): string[] {
+  const leaks: string[] = [];
+  const walk = (current: string, prefix: string): void => {
+    for (const entry of readdirSync(current, { withFileTypes: true })) {
+      const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+      const full = join(current, entry.name);
+      if (entry.isDirectory()) {
+        walk(full, rel);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      if (entry.name === DBXV2_DECLARATIONS_FILE) {
+        leaks.push(rel);
+        continue;
+      }
+      if (BINARY_SCANNED.test(entry.name)) {
+        try {
+          if (statSync(full).size > MAX_BINARY) continue;
+          const bytes = readFileSync(full);
+          if (DBXV2_BINARY_REFERENCES.some((needle) => bytes.includes(needle))) leaks.push(rel);
+        } catch {
+          // unreadable file: nothing to scan
+        }
+        continue;
+      }
+      if (!SCANNED.test(entry.name)) continue;
+      let size: number;
+      try {
+        size = statSync(full).size;
+      } catch {
+        continue;
+      }
+      if (size > MAX_FILE) continue;
+      if (readFileSync(full, "latin1").includes(DBXV2_MARKER)) leaks.push(rel);
+    }
+  };
+  walk(dir, "");
+  return leaks;
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+/** Public API of `@aphrody/shenron-dbxv2` (private package: DBXV2 data is never public). */
+export * from "./cache";
+export * from "./client";
+export * from "./db";
+export * from "./declarations";
+export * from "./env";
+export * from "./errors";
+export * from "./guard";
+export * from "./pixel-perfect";
+export * from "./plugin";
+export * from "./proxy";
+export * from "./refs";
+export * from "./runtime";
+export * from "./schemas";
+export * from "./texture";

package/src/pixel-perfect.ts

@@ -0,0 +1,139 @@
+/**
+ * Pixel-perfect presentation helpers for DBXV2 textures (DOM / canvas), and the sampler contract
+ * for wgpu / Bevy.
+ *
+ * Rules: integer scale only (in device pixels), nearest-neighbour sampling, no sub-pixel offset,
+ * `devicePixelRatio` taken into account, position snapped to the device pixel grid.
+ *
+ * wgpu / Bevy (crates/shenron-engine) must apply the equivalent: `FilterMode::Nearest` for mag,
+ * min and mipmap, `mip_level_count = 1`, `AddressMode::ClampToEdge`, exact UVs (texel centres, no
+ * bias), a viewport / quad whose size is a whole multiple of the texture size in physical pixels
+ * and whose origin is a whole physical pixel, and an `Rgba8UnormSrgb` (colour) or `Rgba8Unorm`
+ * (data) format matching the declared colour space. {@link NEAREST_SAMPLER} is the wgpu descriptor.
+ */
+
+export interface PixelBox {
+  /** Available width / height in CSS pixels. */
+  readonly width: number;
+  readonly height: number;
+}
+
+export interface PixelPerfectOptions {
+  /** Device pixel ratio (default 1). */
+  readonly dpr?: number;
+  /** Upper bound of the integer scale (default unbounded). */
+  readonly maxScale?: number;
+  /** Fail instead of showing the image smaller than 1:1 when it does not fit (default: clamp to 1). */
+  readonly strict?: boolean;
+}
+
+export interface PixelPlacement {
+  /** Integer scale in device pixels per texel. */
+  readonly scale: number;
+  /** Size in device pixels (whole numbers). */
+  readonly deviceWidth: number;
+  readonly deviceHeight: number;
+  /** Origin in device pixels, centred in the box and floored to the grid. */
+  readonly deviceX: number;
+  readonly deviceY: number;
+  /** Same values in CSS pixels (device / dpr); exact when dpr is an integer. */
+  readonly cssWidth: number;
+  readonly cssHeight: number;
+  readonly cssX: number;
+  readonly cssY: number;
+  /** The image does not fit even at scale 1 (only reported when not strict). */
+  readonly overflow: boolean;
+}
+
+/** Largest integer scale whose result fits the box, positioned on the device pixel grid. */
+export function pixelPerfect(
+  imageWidth: number,
+  imageHeight: number,
+  box: PixelBox,
+  options: PixelPerfectOptions = {},
+): PixelPlacement {
+  const dpr = options.dpr && options.dpr > 0 ? options.dpr : 1;
+  if (
+    !(imageWidth > 0) ||
+    !(imageHeight > 0) ||
+    !Number.isInteger(imageWidth) ||
+    !Number.isInteger(imageHeight)
+  )
+    throw new RangeError("image dimensions must be positive integers");
+  const boxW = Math.floor(box.width * dpr);
+  const boxH = Math.floor(box.height * dpr);
+  const fit = Math.floor(Math.min(boxW / imageWidth, boxH / imageHeight));
+  if (fit < 1 && options.strict) throw new RangeError("image does not fit at an integer scale");
+  const scale = Math.max(1, Math.min(fit, options.maxScale ?? Number.POSITIVE_INFINITY));
+  const deviceWidth = imageWidth * scale;
+  const deviceHeight = imageHeight * scale;
+  const deviceX = Math.floor((boxW - deviceWidth) / 2);
+  const deviceY = Math.floor((boxH - deviceHeight) / 2);
+  return {
+    scale,
+    deviceWidth,
+    deviceHeight,
+    deviceX,
+    deviceY,
+    cssWidth: deviceWidth / dpr,
+    cssHeight: deviceHeight / dpr,
+    cssX: deviceX / dpr,
+    cssY: deviceY / dpr,
+    overflow: fit < 1,
+  };
+}
+
+/** Inline style for an `<img>` or `<canvas>` positioned in a relatively-positioned box. */
+export function pixelPerfectStyle(placement: PixelPlacement): Record<string, string> {
+  return {
+    position: "absolute",
+    left: `${placement.cssX}px`,
+    top: `${placement.cssY}px`,
+    width: `${placement.cssWidth}px`,
+    height: `${placement.cssHeight}px`,
+    imageRendering: "pixelated",
+  };
+}
+
+/** Minimal canvas 2D surface (structural, no DOM class needed). */
+export interface PixelCanvasContext {
+  imageSmoothingEnabled: boolean;
+  drawImage(image: unknown, dx: number, dy: number, dw: number, dh: number): void;
+}
+
+/**
+ * Draws on a canvas whose backing store is already in device pixels (width = css * dpr).
+ * Smoothing is disabled and the destination is whole device pixels.
+ */
+export function drawPixelPerfect(
+  ctx: PixelCanvasContext,
+  image: unknown,
+  placement: PixelPlacement,
+): void {
+  ctx.imageSmoothingEnabled = false;
+  ctx.drawImage(
+    image,
+    placement.deviceX,
+    placement.deviceY,
+    placement.deviceWidth,
+    placement.deviceHeight,
+  );
+}
+
+/** wgpu sampler descriptor: nearest everywhere, no mip, clamped, no LOD bias. */
+export const NEAREST_SAMPLER = {
+  magFilter: "nearest",
+  minFilter: "nearest",
+  mipmapFilter: "nearest",
+  addressModeU: "clamp-to-edge",
+  addressModeV: "clamp-to-edge",
+  addressModeW: "clamp-to-edge",
+  lodMinClamp: 0,
+  lodMaxClamp: 0,
+  maxAnisotropy: 1,
+} as const;
+
+/** Texture descriptor fragments matching a declared colour space (single mip level). */
+export function wgpuTextureFormat(colorSpace: "srgb" | "linear"): "rgba8unorm-srgb" | "rgba8unorm" {
+  return colorSpace === "srgb" ? "rgba8unorm-srgb" : "rgba8unorm";
+}