@zkmake/three-textures 0.1.0

package/dist/lab-CozZhJaq.js

@@ -0,0 +1,864 @@
+import { GLSL3, Mesh, NoColorSpace, OrthographicCamera, PlaneGeometry, RGBAFormat, RawShaderMaterial, SRGBColorSpace, Texture, UnsignedByteType, WebGLRenderTarget } from "three";
+//#region src/core/discover.ts
+const isTexture = (value) => value !== null && typeof value === "object" && value.isTexture === true;
+const add = (found, texture, ref, slot) => {
+	let entry = found.get(texture.source);
+	if (!entry) {
+		entry = {
+			source: texture.source,
+			textures: /* @__PURE__ */ new Set(),
+			refs: [],
+			slots: /* @__PURE__ */ new Set(),
+			materials: /* @__PURE__ */ new Set()
+		};
+		found.set(texture.source, entry);
+	}
+	entry.textures.add(texture);
+	entry.refs.push(ref);
+	entry.slots.add(slot);
+	if (ref.material) entry.materials.add(ref.material);
+};
+const scanMaterial = (found, material) => {
+	const record = material;
+	const label = material.name || material.type;
+	for (const key of Object.keys(record)) {
+		const value = record[key];
+		if (isTexture(value)) add(found, value, {
+			owner: record,
+			key,
+			material
+		}, `${label}.${key}`);
+	}
+	const uniforms = material.uniforms;
+	for (const [name, uniform] of Object.entries(uniforms ?? {})) if (uniform && isTexture(uniform.value)) add(found, uniform.value, {
+		owner: uniform,
+		key: "value",
+		material
+	}, `${label}.${name}`);
+};
+/** Every texture under `root`, grouped by source. Materials shared by many meshes are read once. */
+const findTextures = (root) => {
+	const found = /* @__PURE__ */ new Map();
+	const seen = /* @__PURE__ */ new Set();
+	const scene = root;
+	for (const key of ["background", "environment"]) {
+		const value = scene[key];
+		if (isTexture(value)) add(found, value, {
+			owner: scene,
+			key,
+			material: null
+		}, `scene.${key}`);
+	}
+	root.traverse((object) => {
+		const held = object.material;
+		for (const material of Array.isArray(held) ? held : held ? [held] : []) if (!seen.has(material)) {
+			seen.add(material);
+			scanMaterial(found, material);
+		}
+	});
+	return found;
+};
+//#endregion
+//#region src/core/kinds.ts
+/** An element three uploads with `texImage2D` as it is: what an image swap can replace. */
+const isImageLike = (data) => {
+	if (data === null || typeof data !== "object") return false;
+	const hasSize = "width" in data && "height" in data;
+	return typeof HTMLImageElement !== "undefined" && data instanceof HTMLImageElement || typeof HTMLCanvasElement !== "undefined" && data instanceof HTMLCanvasElement || typeof ImageBitmap !== "undefined" && data instanceof ImageBitmap || typeof OffscreenCanvas !== "undefined" && data instanceof OffscreenCanvas || hasSize && !("data" in data) && !("mipmaps" in data);
+};
+const kindOf = (texture) => {
+	const flags = texture;
+	if (flags.isCompressedArrayTexture || flags.isCompressedCubeTexture || flags.isData3DTexture || flags.isDataArrayTexture || flags.isCubeTexture || flags.isVideoTexture || flags.isDepthTexture || flags.isFramebufferTexture || flags.isRenderTargetTexture || flags.isArrayTexture) return "unsupported";
+	if (flags.isCompressedTexture) return "compressed";
+	if (flags.isDataTexture) return "data";
+	return isImageLike(texture.source.data) ? "image" : "unsupported";
+};
+/** Pixel size of the base level. */
+const sizeOf = (texture) => {
+	const image = texture.source.data;
+	const base = texture.mipmaps?.[0];
+	return {
+		width: base?.width ?? image?.width ?? 0,
+		height: base?.height ?? image?.height ?? 0
+	};
+};
+/** GPU compressed format families, by three's (GL-valued) format constants. */
+const FAMILIES = [
+	[
+		33776,
+		33779,
+		"BC1–3"
+	],
+	[
+		35840,
+		35843,
+		"PVRTC"
+	],
+	[
+		35916,
+		35919,
+		"BC1–3"
+	],
+	[
+		36196,
+		36196,
+		"ETC1"
+	],
+	[
+		36283,
+		36286,
+		"BC4–5"
+	],
+	[
+		36492,
+		36495,
+		"BC6–7"
+	],
+	[
+		37488,
+		37497,
+		"ETC2"
+	],
+	[
+		37808,
+		37853,
+		"ASTC"
+	]
+];
+/** A short format label: `ASTC`, `ETC2`, `RGBA` data, or the image's own. */
+const formatOf = (texture) => {
+	const kind = kindOf(texture);
+	if (kind === "compressed") {
+		const format = texture.format;
+		const family = FAMILIES.find(([low, high]) => format >= low && format <= high);
+		return family ? family[2] : "compressed";
+	}
+	if (kind === "data") return "data";
+	const data = texture.source.data;
+	const src = data?.currentSrc || data?.src || "";
+	return /\.([a-z0-9]+)(?:[?#]|$)/i.exec(src)?.[1]?.toLowerCase() ?? (data && "getContext" in data ? "canvas" : "image");
+};
+//#endregion
+//#region src/core/names.ts
+/** Vite's default asset name is `[name]-[hash][ext]` with an 8-character base64url hash. */
+const VITE_HASH = /-[A-Za-z0-9_-]{8}(\.[^.]+)$/;
+/** The file name at the end of a URL, query and hash dropped, bundler hash stripped. */
+const fileNameOf = (url) => {
+	if (url.startsWith("data:") || url.startsWith("blob:")) return null;
+	const last = decodeURIComponent(url.split(/[?#]/)[0].split("/").pop() ?? "");
+	return last ? last.replace(VITE_HASH, "$1") : null;
+};
+/** The URL an image texture was loaded from, when it has one. */
+const sourceUrlOf = (texture) => {
+	const data = texture.source.data;
+	const url = data?.currentSrc || data?.src;
+	return typeof url === "string" && url.length > 0 ? url : null;
+};
+/** A label without its extension, for a row: `bunny-baked.webp` reads as `bunny-baked`. */
+const stem = (file) => file.replace(/\.[^.]+$/, "");
+//#endregion
+//#region src/core/readback.ts
+/**
+* Read a texture back from the GPU as pixels: the one way to see (and save) a compressed, data or
+* generated texture, which has no file behind it. WebGL only.
+*
+* The texture is drawn onto a quad in a render target the size asked for, sampled raw (no uv
+* transform), and read back. Two corrections make the PNG a file an artist can edit and upload
+* back unchanged:
+* - Rows: three uploads an image with `flipY` bottom row first, so its readback is flipped back;
+*   a `flipY: false` texture (compressed, data, glTF) is written in the order it was uploaded.
+* - Colour: an sRGB texture samples as linear, so it's encoded back to sRGB bytes.
+*/
+const VERTEX = `
+in vec3 position;
+in vec2 uv;
+out vec2 vUv;
+
+void main() {
+  vUv = uv;
+  gl_Position = vec4(position.xy, 0.0, 1.0);
+}
+`;
+const FRAGMENT = `
+precision highp float;
+uniform sampler2D map;
+uniform bool encodeSRGB;
+in vec2 vUv;
+out vec4 color;
+
+vec3 toSRGB(vec3 linear) {
+  return mix(linear * 12.92, 1.055 * pow(linear, vec3(1.0 / 2.4)) - 0.055, step(0.0031308, linear));
+}
+
+void main() {
+  vec4 texel = texture(map, vUv);
+
+  color = encodeSRGB ? vec4(toSRGB(texel.rgb), texel.a) : texel;
+}
+`;
+/** WebGL ignores `flipY` for an `ImageBitmap`: it always uploads top row first. */
+const uploadsFlipped = (texture) => texture.flipY && !(typeof ImageBitmap !== "undefined" && texture.source.data instanceof ImageBitmap);
+let quad = null;
+const camera = new OrthographicCamera(-1, 1, 1, -1, 0, 1);
+const quadFor = (texture) => {
+	quad ??= new Mesh(new PlaneGeometry(2, 2), new RawShaderMaterial({
+		glslVersion: GLSL3,
+		vertexShader: VERTEX,
+		fragmentShader: FRAGMENT,
+		uniforms: {
+			map: { value: null },
+			encodeSRGB: { value: false }
+		},
+		depthTest: false,
+		depthWrite: false
+	}));
+	quad.frustumCulled = false;
+	quad.material.uniforms.map.value = texture;
+	quad.material.uniforms.encodeSRGB.value = texture.colorSpace === SRGBColorSpace;
+	return quad;
+};
+/** Pixels of `texture` at `width × height`, top row first, as they'd be saved to a file. */
+const readTexture = (renderer, texture, width, height) => {
+	const target = new WebGLRenderTarget(width, height, {
+		type: UnsignedByteType,
+		format: RGBAFormat,
+		colorSpace: NoColorSpace,
+		depthBuffer: false
+	});
+	const previous = renderer.getRenderTarget();
+	const xr = renderer.xr.enabled;
+	const autoClear = renderer.autoClear;
+	const pixels = new Uint8Array(width * height * 4);
+	try {
+		renderer.xr.enabled = false;
+		renderer.autoClear = true;
+		renderer.setRenderTarget(target);
+		renderer.render(quadFor(texture), camera);
+		renderer.readRenderTargetPixels(target, 0, 0, width, height, pixels);
+	} finally {
+		renderer.setRenderTarget(previous);
+		renderer.xr.enabled = xr;
+		renderer.autoClear = autoClear;
+		target.dispose();
+		quad.material.uniforms.map.value = null;
+	}
+	const out = new ImageData(width, height);
+	const row = width * 4;
+	const flipped = uploadsFlipped(texture);
+	for (let y = 0; y < height; y += 1) {
+		const from = flipped ? height - 1 - y : y;
+		out.data.set(pixels.subarray(from * row, from * row + row), y * row);
+	}
+	return out;
+};
+/** `readTexture` as a PNG. */
+const readTextureBlob = async (renderer, texture, width, height) => {
+	const canvas = document.createElement("canvas");
+	canvas.width = width;
+	canvas.height = height;
+	canvas.getContext("2d").putImageData(readTexture(renderer, texture, width, height), 0, 0);
+	return new Promise((resolve, reject) => canvas.toBlob((blob) => blob ? resolve(blob) : reject(/* @__PURE__ */ new Error("toBlob failed")), "image/png"));
+};
+/** Whether this renderer can read textures back (WebGL, not WebGPU). */
+const canReadBack = (renderer) => renderer !== null && typeof renderer === "object" && typeof renderer.readRenderTargetPixels === "function" && renderer.isWebGLRenderer === true;
+//#endregion
+//#region src/core/store.ts
+/** A store that lives as long as the page: tests, or `storageKey: null`. */
+const memoryStore = () => {
+	const swaps = /* @__PURE__ */ new Map();
+	return {
+		get: async (id) => swaps.get(id),
+		set: async (id, swap) => {
+			swaps.set(id, swap);
+		},
+		delete: async (id) => {
+			swaps.delete(id);
+		},
+		clear: async () => {
+			swaps.clear();
+		}
+	};
+};
+const DATABASE = "zkmake-three-textures";
+/** Sorts after every character a key can hold: the top of a key-prefix range. */
+const LAST_CHAR = String.fromCharCode(65535);
+const STORE = "swaps";
+const request = (req) => new Promise((resolve, reject) => {
+	req.onsuccess = () => resolve(req.result);
+	req.onerror = () => reject(req.error);
+});
+/** Swaps in IndexedDB, keyed `<storageKey>/<texture name>`. Falls back to memory without it. */
+const indexedDbStore = (storageKey) => {
+	if (typeof indexedDB === "undefined") return memoryStore();
+	let opened = null;
+	const database = () => {
+		opened ??= new Promise((resolve, reject) => {
+			const open = indexedDB.open(DATABASE, 1);
+			open.onupgradeneeded = () => open.result.createObjectStore(STORE);
+			open.onsuccess = () => resolve(open.result);
+			open.onerror = () => reject(open.error);
+		});
+		return opened;
+	};
+	const key = (id) => `${storageKey}/${id}`;
+	const store = async (mode) => (await database()).transaction(STORE, mode).objectStore(STORE);
+	return {
+		get: async (id) => await request((await store("readonly")).get(key(id))),
+		set: async (id, swap) => {
+			await request((await store("readwrite")).put(swap, key(id)));
+		},
+		delete: async (id) => {
+			await request((await store("readwrite")).delete(key(id)));
+		},
+		clear: async () => {
+			const range = IDBKeyRange.bound(`${storageKey}/`, `${storageKey}/${LAST_CHAR}`);
+			await request((await store("readwrite")).delete(range));
+		}
+	};
+};
+//#endregion
+//#region src/core/swap.ts
+/**
+* Put an image in place of a texture's pixels, and take it out again.
+*
+* - **In place**, for an image texture: the shared `Source` gets the new image and every texture
+*   on it re-uploads. Anything holding the texture — materials, the app's own references — sees
+*   the swap, and the texture keeps all its settings.
+* - **Rebind**, for compressed and data textures: their data is GPU-ready blocks or raw bytes, so
+*   an image can't go in their place. Each gets an image twin with its settings (wrap, filters,
+*   colour space, uv channel and transform) and the twin is bound wherever the original was: the
+*   material slots and uniforms `findTextures` saw. `flipY` is off, the way compressed and data
+*   textures lay their rows, so a readback of the original uploads back the same way up.
+*/
+const canSwap = (kind) => kind !== "unsupported";
+const bump = (textures) => {
+	for (const texture of textures) texture.needsUpdate = true;
+};
+const recompile = (materials) => {
+	for (const material of materials) if (material) material.needsUpdate = true;
+};
+const twinOf = (original, source) => {
+	const twin = new Texture();
+	twin.source = source;
+	twin.name = original.name;
+	twin.mapping = original.mapping;
+	twin.channel = original.channel;
+	twin.wrapS = original.wrapS;
+	twin.wrapT = original.wrapT;
+	twin.magFilter = original.magFilter;
+	twin.minFilter = original.minFilter;
+	twin.anisotropy = original.anisotropy;
+	twin.colorSpace = original.colorSpace;
+	twin.offset.copy(original.offset);
+	twin.repeat.copy(original.repeat);
+	twin.center.copy(original.center);
+	twin.rotation = original.rotation;
+	twin.matrixAutoUpdate = original.matrixAutoUpdate;
+	twin.matrix.copy(original.matrix);
+	twin.userData = { ...original.userData };
+	twin.flipY = false;
+	twin.premultiplyAlpha = false;
+	twin.generateMipmaps = true;
+	twin.needsUpdate = true;
+	return twin;
+};
+/** Bind twins into every ref that still holds an original. Returns the new bindings. */
+const bindRefs = (refs, twins) => {
+	const made = [];
+	for (const ref of refs) {
+		const original = ref.owner[ref.key];
+		const twin = twins.get(original);
+		if (twin) {
+			ref.owner[ref.key] = twin;
+			made.push({
+				...ref,
+				original,
+				twin
+			});
+		}
+	}
+	recompile(made.map((binding) => binding.material));
+	return made;
+};
+/** Show `image` on the texture: a first swap, or a new image over an earlier one. */
+const applyImage = (found, kind, image, existing) => {
+	if (kind === "image") {
+		const original = existing?.mode === "in-place" ? existing.original : found.source.data;
+		found.source.data = image;
+		bump(found.textures);
+		return {
+			mode: "in-place",
+			image,
+			showingOriginal: false,
+			original,
+			textures: new Set(found.textures)
+		};
+	}
+	if (existing?.mode === "rebind") {
+		existing.source.data = image;
+		bump(existing.twins.values());
+		const applied = {
+			...existing,
+			image,
+			showingOriginal: false
+		};
+		if (existing.showingOriginal) showOriginal(applied, false);
+		return applied;
+	}
+	const SourceClass = found.source.constructor;
+	const source = new SourceClass(image);
+	const twins = new Map([...found.textures].map((texture) => [texture, twinOf(texture, source)]));
+	return {
+		mode: "rebind",
+		image,
+		showingOriginal: false,
+		source,
+		twins,
+		bindings: bindRefs(found.refs, twins)
+	};
+};
+/**
+* A rebind swap reaches slots found after it: a mesh mounted later with the original texture.
+* Call after re-finding the scene's textures. In-place swaps need nothing: they changed the data.
+*/
+const bindNewRefs = (found, applied) => {
+	if (applied.mode !== "rebind" || applied.showingOriginal) return;
+	for (const texture of found.textures) if (!applied.twins.has(texture)) applied.twins.set(texture, twinOf(texture, applied.source));
+	applied.bindings.push(...bindRefs(found.refs, applied.twins));
+};
+/** Flip between the original and the swap (A/B), keeping both. */
+const showOriginal = (applied, original) => {
+	applied.showingOriginal = original;
+	if (applied.mode === "in-place") {
+		const first = [...applied.textures][0];
+		if (first) first.source.data = original ? applied.original : applied.image;
+		bump(applied.textures);
+		return;
+	}
+	for (const binding of applied.bindings) {
+		const from = original ? binding.twin : binding.original;
+		if (binding.owner[binding.key] === from) binding.owner[binding.key] = original ? binding.original : binding.twin;
+	}
+	recompile(applied.bindings.map((binding) => binding.material));
+};
+/** Undo the swap: the original data or bindings back, twins freed. */
+const revertImage = (applied) => {
+	showOriginal(applied, true);
+	if (applied.mode === "rebind") for (const twin of applied.twins.values()) twin.dispose();
+	if (typeof ImageBitmap !== "undefined" && applied.image instanceof ImageBitmap) applied.image.close();
+};
+/** The textures drawing now: twins while a rebind swap shows, the originals otherwise. */
+const boundTextures = (found, applied) => applied?.mode === "rebind" && !applied.showingOriginal ? [...applied.twins.values()] : [...found.textures];
+//#endregion
+//#region src/core/lab.ts
+const LINK_POLL_MS = 600;
+/** Decode to the same kind of object the texture held: WebGL ignores `flipY` for bitmaps. */
+const decode = async (blob, like) => {
+	if (typeof ImageBitmap !== "undefined" && like instanceof ImageBitmap) return {
+		image: await createImageBitmap(blob, {
+			premultiplyAlpha: "none",
+			colorSpaceConversion: "none"
+		}),
+		url: null
+	};
+	const url = URL.createObjectURL(blob);
+	const image = new Image();
+	image.src = url;
+	await image.decode();
+	return {
+		image,
+		url
+	};
+};
+const drawToDataUrl = (draw, width, height) => {
+	const canvas = document.createElement("canvas");
+	canvas.width = width;
+	canvas.height = height;
+	draw(canvas.getContext("2d"));
+	return canvas.toDataURL("image/png");
+};
+const fit = (width, height, max) => {
+	const scale = Math.min(1, max / Math.max(width, height, 1));
+	return {
+		width: Math.max(1, Math.round(width * scale)),
+		height: Math.max(1, Math.round(height * scale))
+	};
+};
+var TextureLab = class {
+	options;
+	store;
+	records = /* @__PURE__ */ new Map();
+	byId = /* @__PURE__ */ new Map();
+	/** Sources of rebind twins, so a refresh doesn't list them as textures of their own. */
+	twinSources = /* @__PURE__ */ new Set();
+	listeners = /* @__PURE__ */ new Set();
+	restoring = /* @__PURE__ */ new Set();
+	poll = null;
+	disposed = false;
+	constructor(options) {
+		this.options = options;
+		this.store = options.store ?? (options.storageKey === null ? memoryStore() : indexedDbStore(options.storageKey ?? "three-textures"));
+		this.refresh();
+	}
+	/** Whether this browser can live-link a file (the File System Access API: Chrome, Edge). */
+	static get canLink() {
+		return typeof window !== "undefined" && typeof window.showOpenFilePicker === "function";
+	}
+	/** Whether downloads and thumbnails can read textures back from the GPU. */
+	get canReadBack() {
+		return canReadBack(this.options.renderer);
+	}
+	subscribe(listener) {
+		this.listeners.add(listener);
+		return () => {
+			this.listeners.delete(listener);
+		};
+	}
+	/** Every texture, by name. */
+	entries() {
+		return [...this.byId.values()].map((record) => this.entryOf(record)).sort((a, b) => a.id.localeCompare(b.id));
+	}
+	entry(id) {
+		const record = this.byId.get(id);
+		return record ? this.entryOf(record) : null;
+	}
+	/**
+	* Look at the scene again: textures that appeared get entries (and their saved swap back), a
+	* rebind swap reaches slots mounted since. Entries whose textures left the scene stay while
+	* swapped or registered, so their state isn't lost.
+	*/
+	refresh() {
+		if (this.disposed) return;
+		const found = findTextures(this.options.scene);
+		let changed = false;
+		for (const info of this.options.textures ?? []) if (!found.has(info.texture.source)) found.set(info.texture.source, {
+			source: info.texture.source,
+			textures: /* @__PURE__ */ new Set([info.texture]),
+			refs: [],
+			slots: /* @__PURE__ */ new Set(),
+			materials: /* @__PURE__ */ new Set()
+		});
+		const seen = /* @__PURE__ */ new Set();
+		for (const [source, item] of found) {
+			if (this.twinSources.has(source)) continue;
+			seen.add(source);
+			const record = this.records.get(source);
+			if (record) {
+				const before = record.found.materials.size;
+				record.found = item;
+				if (record.applied) bindNewRefs(item, record.applied);
+				changed ||= before !== item.materials.size;
+				continue;
+			}
+			this.add(item);
+			changed = true;
+		}
+		for (const [source, record] of this.records) if (!seen.has(source) && !record.applied && !this.isRegistered(source)) {
+			this.records.delete(source);
+			this.byId.delete(record.id);
+			changed = true;
+		}
+		if (changed) this.notify();
+	}
+	/** Swap `blob` (an image file) in for the texture `id`. */
+	async swap(id, blob, { fileName = blob.name ?? null, persist = true } = {}) {
+		const record = this.require(id);
+		if (!canSwap(record.kind)) throw new Error(`three-textures: "${id}" can't be swapped (${record.kind})`);
+		const { image, url } = await decode(blob, record.found.source.data);
+		const previousUrl = record.url;
+		record.applied = applyImage(record.found, record.kind, image, record.applied);
+		if (record.applied.mode === "rebind") this.twinSources.add(record.applied.source);
+		record.blob = blob;
+		record.swapName = fileName || null;
+		record.url = url;
+		if (previousUrl && previousUrl !== url) URL.revokeObjectURL(previousUrl);
+		if (persist) await this.save(record);
+		this.changed(record);
+	}
+	/** A/B: show the original (`true`) or the swap (`false`). */
+	async showOriginal(id, original) {
+		const record = this.require(id);
+		if (!record.applied || record.applied.showingOriginal === original) return;
+		showOriginal(record.applied, original);
+		await this.save(record);
+		this.changed(record);
+	}
+	/** Back to the original, forgetting the swap. */
+	async revert(id) {
+		const record = this.require(id);
+		this.stopLink(record);
+		record.handle = null;
+		await this.store.delete(id);
+		if (!record.applied) {
+			this.notify();
+			return;
+		}
+		revertImage(record.applied);
+		if (record.applied.mode === "rebind") this.twinSources.delete(record.applied.source);
+		record.applied = null;
+		record.blob = null;
+		record.swapName = null;
+		if (record.url) {
+			URL.revokeObjectURL(record.url);
+			record.url = null;
+		}
+		this.changed(record);
+	}
+	/** Every entry back to its original, and every saved swap cleared. */
+	async revertAll() {
+		for (const record of this.byId.values()) if (record.applied || record.handle) await this.revert(record.id);
+		await this.store.clear();
+	}
+	/**
+	* The pixels showing now as a file: the swapped file, else the original file when its URL is
+	* known and fetchable, else a GPU readback as PNG.
+	*/
+	async toBlob(id) {
+		const record = this.require(id);
+		const fallbackName = `${id}.png`;
+		if (record.applied && !record.applied.showingOriginal && record.blob) return {
+			blob: record.blob,
+			fileName: record.swapName ?? fallbackName
+		};
+		if (record.src) try {
+			const response = await fetch(record.src);
+			if (response.ok) return {
+				blob: await response.blob(),
+				fileName: fileNameOf(record.src) ?? fallbackName
+			};
+		} catch {}
+		const renderer = this.options.renderer;
+		if (!canReadBack(renderer)) throw new Error(`three-textures: "${id}" has no file to download and the renderer can't read it back`);
+		const texture = [...record.found.textures][0];
+		const { width, height } = sizeOf(texture);
+		return {
+			blob: await readTextureBlob(renderer, texture, width, height),
+			fileName: fallbackName
+		};
+	}
+	/** Save the pixels showing now to the downloads folder. */
+	async download(id) {
+		const { blob, fileName } = await this.toBlob(id);
+		const url = URL.createObjectURL(blob);
+		const link = document.createElement("a");
+		link.href = url;
+		link.download = fileName;
+		document.body.append(link);
+		link.click();
+		link.remove();
+		setTimeout(() => URL.revokeObjectURL(url), 1e3);
+	}
+	/** A small picture of what's showing now, as a data URL; `null` when there's no way to draw it. */
+	thumbnail(id, max = 96) {
+		const record = this.require(id);
+		const bound = boundTextures(record.found, record.applied)[0];
+		if (!bound) return null;
+		const data = bound.source.data;
+		if (kindOf(bound) === "image" || record.applied && !record.applied.showingOriginal) {
+			const { width, height } = fit(data.width, data.height, max);
+			try {
+				return drawToDataUrl((context) => context.drawImage(data, 0, 0, width, height), width, height);
+			} catch {
+				return null;
+			}
+		}
+		const renderer = this.options.renderer;
+		if (!canReadBack(renderer)) return null;
+		const { width, height } = fit(sizeOf(bound).width, sizeOf(bound).height, max);
+		return drawToDataUrl((context) => context.putImageData(readTexture(renderer, bound, width, height), 0, 0), width, height);
+	}
+	/**
+	* Live-link a file: pick it once, and every save re-applies it. Call from a click (the browser
+	* shows a file picker, or asks to resume permission for a link restored after a reload).
+	*/
+	async link(id) {
+		const record = this.require(id);
+		let handle = record.handle;
+		if (handle) {
+			if ((await handle.requestPermission?.({ mode: "read" }) ?? "granted") !== "granted") return;
+		} else {
+			const picker = window.showOpenFilePicker;
+			if (!picker) throw new Error("three-textures: live links need the File System Access API (Chrome, Edge)");
+			[handle] = await picker({ types: [{
+				description: "Images",
+				accept: { "image/*": [
+					".png",
+					".jpg",
+					".jpeg",
+					".webp",
+					".avif"
+				] }
+			}] });
+		}
+		const file = await handle.getFile();
+		record.handle = handle;
+		record.link = "live";
+		record.lastModified = file.lastModified;
+		await this.swap(id, file, { fileName: handle.name });
+		this.startPolling();
+	}
+	/** Stop following the file; the last version stays swapped in. */
+	async unlink(id) {
+		const record = this.require(id);
+		this.stopLink(record);
+		record.handle = null;
+		await this.save(record);
+		this.notify();
+	}
+	dispose() {
+		this.disposed = true;
+		if (this.poll) clearInterval(this.poll);
+		this.listeners.clear();
+	}
+	add(item) {
+		const id = this.uniqueName(this.nameOf(item));
+		const texture = [...item.textures][0];
+		const registered = (this.options.textures ?? []).find((info) => info.texture.source === item.source);
+		const record = {
+			id,
+			found: item,
+			kind: kindOf(texture),
+			src: registered?.src ?? sourceUrlOf(texture),
+			applied: null,
+			blob: null,
+			swapName: null,
+			url: null,
+			handle: null,
+			link: "off",
+			lastModified: 0,
+			revision: 0
+		};
+		this.records.set(item.source, record);
+		this.byId.set(id, record);
+		this.restore(record);
+	}
+	nameOf(item) {
+		const registered = (this.options.textures ?? []).find((info) => info.texture.source === item.source);
+		if (registered) return registered.name;
+		for (const texture of item.textures) if (texture.name) return texture.name;
+		const url = sourceUrlOf([...item.textures][0]);
+		const file = url ? fileNameOf(url) : null;
+		return file ? stem(file) : [...item.slots][0] ?? "texture";
+	}
+	uniqueName(name) {
+		let unique = name;
+		for (let n = 2; this.byId.has(unique); n += 1) unique = `${name} ${n}`;
+		return unique;
+	}
+	isRegistered(source) {
+		return (this.options.textures ?? []).some((info) => info.texture.source === source);
+	}
+	async restore(record) {
+		if (this.restoring.has(record.id)) return;
+		this.restoring.add(record.id);
+		try {
+			const saved = await this.store.get(record.id);
+			if (!saved || this.disposed || record.applied || !canSwap(record.kind)) return;
+			await this.swap(record.id, saved.blob, {
+				fileName: saved.fileName,
+				persist: false
+			});
+			if (saved.showingOriginal) await this.showOriginal(record.id, true);
+			if (saved.handle) {
+				record.handle = saved.handle;
+				record.link = "paused";
+				this.notify();
+			}
+		} catch (error) {
+			console.warn(`three-textures: couldn't restore the swap for "${record.id}"`, error);
+		} finally {
+			this.restoring.delete(record.id);
+		}
+	}
+	async save(record) {
+		if (!record.blob || !record.applied) return;
+		const swap = {
+			blob: record.blob,
+			fileName: record.swapName,
+			showingOriginal: record.applied.showingOriginal,
+			handle: record.handle ?? void 0
+		};
+		try {
+			await this.store.set(record.id, swap);
+		} catch (error) {
+			try {
+				await this.store.set(record.id, {
+					...swap,
+					handle: void 0
+				});
+			} catch {
+				console.warn(`three-textures: couldn't save the swap for "${record.id}"`, error);
+			}
+		}
+	}
+	startPolling() {
+		this.poll ??= setInterval(() => void this.checkLinks(), LINK_POLL_MS);
+	}
+	async checkLinks() {
+		let live = 0;
+		for (const record of this.byId.values()) {
+			if (record.link !== "live" || !record.handle) continue;
+			live += 1;
+			try {
+				const file = await record.handle.getFile();
+				if (file.lastModified !== record.lastModified) {
+					record.lastModified = file.lastModified;
+					await this.swap(record.id, file, { fileName: record.handle.name });
+				}
+			} catch {
+				record.link = "paused";
+				this.notify();
+			}
+		}
+		if (live === 0 && this.poll) {
+			clearInterval(this.poll);
+			this.poll = null;
+		}
+	}
+	stopLink(record) {
+		record.link = "off";
+	}
+	require(id) {
+		const record = this.byId.get(id);
+		if (!record) throw new Error(`three-textures: no texture "${id}"`);
+		return record;
+	}
+	entryOf(record) {
+		const texture = [...record.found.textures][0];
+		const { width, height } = sizeOf(texture);
+		return {
+			id: record.id,
+			kind: record.kind,
+			format: formatOf(texture),
+			width,
+			height,
+			colorSpace: texture.colorSpace,
+			src: record.src,
+			materials: record.found.materials.size,
+			state: !record.applied ? "original" : record.applied.showingOriginal ? "showing-original" : "swapped",
+			link: record.link,
+			swapName: record.swapName,
+			unsupported: canSwap(record.kind) ? null : "cube, 3D, array, video and render-target textures can't be swapped",
+			revision: record.revision,
+			texture
+		};
+	}
+	changed(record) {
+		record.revision += 1;
+		this.options.onSwap?.({
+			id: record.id,
+			textures: [...record.found.textures],
+			bound: boundTextures(record.found, record.applied),
+			state: this.entryOf(record).state
+		});
+		this.options.invalidate?.();
+		this.notify();
+	}
+	notify() {
+		for (const listener of this.listeners) listener();
+	}
+};
+//#endregion
+export { readTexture as a, kindOf as c, canReadBack as i, sizeOf as l, indexedDbStore as n, readTextureBlob as o, memoryStore as r, formatOf as s, TextureLab as t, findTextures as u };
+
+//# sourceMappingURL=lab-CozZhJaq.js.map