@zkmake/three-textures 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zubin Khavarian
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,132 @@
+# @zkmake/three-textures
+
+A dev panel for the textures in a three.js scene. See every texture the scene draws with, download
+one, paint over it, and put it back: the scene shows your version right away, in the real renderer,
+lighting and post-processing. Flip A/B against the original, keep swaps across reloads, and
+live-link a file so every save in your paint app shows up in the running scene.
+
+Compressed textures (KTX2, Basis) swap too: the panel reads them back from the GPU to a PNG you can
+edit, and swaps your image in by binding an image twin with the same settings wherever the
+original was used. Vanilla three and React Three Fiber.
+
+```sh
+bun add -d @zkmake/three-textures   # or npm i -D / pnpm add -D
+```
+
+Live demo: [three-textures.pages.dev](https://three-textures.pages.dev/), with a vanilla three and
+a React Three Fiber take on the same scene: an image texture and a clone of it, a data texture, and
+a KTX2 atlas cut into four cards. Download the atlas, paint on it, drop it back.
+
+## Vanilla three
+
+```ts
+import { mountTexturePanel } from "@zkmake/three-textures/ui";
+
+const panel = mountTexturePanel({ scene, renderer });
+// later: panel.dispose()
+```
+
+## React Three Fiber
+
+```tsx
+import { TexturePanel } from "@zkmake/three-textures/react";
+
+<Canvas>
+  {import.meta.env.DEV && <TexturePanel />}
+  {/* … */}
+</Canvas>;
+```
+
+It reads the scene and renderer from the canvas and asks for a frame after each swap, so
+`frameloop="demand"` works.
+
+## What each row does
+
+| Button                              | What it does                                                                          |
+| ----------------------------------- | ------------------------------------------------------------------------------------- |
+| thumbnail                           | A large preview, on the side away from the panel                                      |
+| download                            | The swapped file; else the original file; else a GPU readback as PNG                  |
+| replace (or drop a file on the row) | Swap an image in                                                                      |
+| live link (Chrome, Edge)            | Pick a file once; every save re-applies it. Survives a reload (the browser asks once) |
+| A/B                                 | Show the original, keep the swap                                                      |
+| revert                              | Put the original back and forget the swap                                             |
+
+Swaps are kept in IndexedDB under `storageKey` (default `three-textures`) and come back on reload by
+texture name. **Reset all** clears them.
+
+## How a swap works
+
+- **Image textures** swap in place: the texture's `Source` gets your image and every texture sharing
+  it (clones included) re-uploads. Anything holding the texture, your own code included, sees the
+  swap, and every setting stays.
+- **Compressed and data textures** can't take an image in place, so each gets an image twin with its
+  wrap, filters, colour space, uv channel and transform, bound into every material slot and uniform
+  that held the original, including meshes mounted later. `flipY` is off, the way compressed and data
+  textures lay their rows out, so a downloaded readback uploads back the same way up.
+
+Downloads come out as the source image would: an sRGB texture is encoded back to sRGB, and a `flipY`
+texture is turned back over. Readbacks and thumbnails of textures without a file need a
+`WebGLRenderer`; with WebGPU they're skipped.
+
+## The panel
+
+It's the same frame as the three-meter HUD (three-meter's `mountDevPanel`): drag it by the grip disc
+to any edge, the sliders disc shows or hides the list (compact is the brand label and the count), and
+the blend disc dims it while the pointer is away. Both panels together:
+
+```ts
+mountPerfHud(monitor, { defaultPlacement: { edge: "left" } });
+mountTexturePanel({ scene, renderer }); // right edge by default
+```
+
+## Options
+
+```ts
+mountTexturePanel({
+  scene,
+  renderer,
+  // Textures to name (and list before the scene shows them), with the file each came from.
+  textures: [{ name: "bunny", texture: bunnyTexture, src: bunnyUrl }],
+  // Redraw anything derived from a swapped texture, such as an atlas built on a canvas.
+  onSwap: ({ id, bound, state }) => rebuildAtlasFor(id, bound[0]),
+  storageKey: "my-game", // null keeps swaps for this page only
+  theme: "system", // or "dark", "light"
+  defaultPlacement: { edge: "right", align: "start" },
+  compact: false, // start with the list hidden (remembered after the first toggle)
+});
+```
+
+Textures are found in every material's texture properties (not only three's named maps) and uniforms
+(`ShaderMaterial`, custom shader materials), plus the scene's background and environment. A texture
+held only by your code (never bound to a material) needs `textures` to be listed.
+
+## In your own dev panel
+
+`createTexturePanel(lab)` is the bare element, for a host with its own tabs. `TextureLab` is the
+engine with no UI:
+
+```ts
+import { TextureLab } from "@zkmake/three-textures";
+import { createTexturePanel } from "@zkmake/three-textures/ui";
+
+const lab = new TextureLab({ scene, renderer });
+const panel = createTexturePanel(lab);
+
+tab.append(panel.element);
+panel.setEdge("right"); // the preview opens on the left
+panel.setActive(false); // pause the scene re-read while the tab is hidden
+
+await lab.swap("bunny", file);
+await lab.showOriginal("bunny", true);
+```
+
+## Examples
+
+[`apps/three-textures-site`](https://github.com/zkmake/three-kit/tree/main/apps/three-textures-site)
+is what runs at three-textures.pages.dev: [`src/demos/vanilla.ts`](https://github.com/zkmake/three-kit/blob/main/apps/three-textures-site/src/demos/vanilla.ts)
+with `mountTexturePanel`, [`src/demos/r3f.tsx`](https://github.com/zkmake/three-kit/blob/main/apps/three-textures-site/src/demos/r3f.tsx)
+with `<TexturePanel />`, each beside the three-meter HUD. `?r3f` opens on Fiber.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+import { a as TextureInfo, c as StoredSwap, d as memoryStore, f as TextureKind, h as sizeOf, i as TextureEntry, l as SwapStore, m as kindOf, n as LinkState, o as TextureLab, p as formatOf, r as SwapEvent, s as TextureLabOptions, t as EntryState, u as indexedDbStore } from "./lab-CN1v1x-y.js";
+import { Material, Object3D, Texture, WebGLRenderer } from "three";
+//#region src/core/discover.d.ts
+/** A texture's `Source`: the image data it uploads, shared by its clones. */
+type TextureSource = Texture["source"];
+/** Somewhere a texture is bound: `owner[key]`. A uniform's owner is the uniform, `{ value }`. */
+type TextureRef = {
+  owner: Record<string, unknown>;
+  key: string;
+  /** The material to recompile after rebinding, when the owner is one of its slots or uniforms. */
+  material: Material | null;
+};
+type Found = {
+  source: TextureSource;
+  textures: Set<Texture>;
+  refs: TextureRef[];
+  /** `material.slot` names, for a fallback label and the "used by" count. */
+  slots: Set<string>;
+  materials: Set<Material>;
+};
+/** Every texture under `root`, grouped by source. Materials shared by many meshes are read once. */
+export declare const findTextures: (root: Object3D) => Map<TextureSource, Found>;
+//#endregion
+//#region src/core/readback.d.ts
+/** Pixels of `texture` at `width × height`, top row first, as they'd be saved to a file. */
+export declare const readTexture: (renderer: WebGLRenderer, texture: Texture, width: number, height: number) => ImageData;
+/** `readTexture` as a PNG. */
+export declare const readTextureBlob: (renderer: WebGLRenderer, texture: Texture, width: number, height: number) => Promise<Blob>;
+/** Whether this renderer can read textures back (WebGL, not WebGPU). */
+export declare const canReadBack: (renderer: unknown) => renderer is WebGLRenderer;
+//#endregion
+export { type EntryState, type Found, type LinkState, type StoredSwap, type SwapEvent, type SwapStore, type TextureEntry, type TextureInfo, type TextureKind, TextureLab, type TextureLabOptions, type TextureRef, formatOf, indexedDbStore, kindOf, memoryStore, sizeOf };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,2 @@
+import { a as readTexture, c as kindOf, i as canReadBack, l as sizeOf, n as indexedDbStore, o as readTextureBlob, r as memoryStore, s as formatOf, t as TextureLab, u as findTextures } from "./lab-CozZhJaq.js";
+export { TextureLab, canReadBack, findTextures, formatOf, indexedDbStore, kindOf, memoryStore, readTexture, readTextureBlob, sizeOf };

package/dist/lab-CN1v1x-y.d.ts

@@ -0,0 +1,177 @@
+import { Object3D, Texture } from "three";
+//#region src/core/kinds.d.ts
+type TextureKind = "image" | "compressed" | "data" | "unsupported";
+declare const kindOf: (texture: Texture) => TextureKind;
+/** Pixel size of the base level. */
+declare const sizeOf: (texture: Texture) => {
+  width: number;
+  height: number;
+};
+/** A short format label: `ASTC`, `ETC2`, `RGBA` data, or the image's own. */
+declare const formatOf: (texture: Texture) => string;
+//#endregion
+//#region src/core/store.d.ts
+/**
+ * Where swaps survive a reload. IndexedDB by default: painted textures are megabytes each, past
+ * what `localStorage` holds, and a live-linked file's handle can be kept too (handles clone into
+ * IndexedDB; they can't be stringified).
+ */
+type StoredSwap = {
+  blob: Blob;
+  fileName: string | null;
+  showingOriginal: boolean;
+  /** A live-linked file, to resume after a reload (the browser asks for permission again). */
+  handle?: FileSystemFileHandleLike | undefined;
+};
+/** The slice of the File System Access API's file handle the live link uses. */
+type FileSystemFileHandleLike = {
+  name: string;
+  getFile(): Promise<File>;
+  queryPermission?(options: {
+    mode: "read";
+  }): Promise<PermissionState>;
+  requestPermission?(options: {
+    mode: "read";
+  }): Promise<PermissionState>;
+};
+type SwapStore = {
+  get(id: string): Promise<StoredSwap | undefined>;
+  set(id: string, swap: StoredSwap): Promise<void>;
+  delete(id: string): Promise<void>;
+  clear(): Promise<void>;
+};
+/** A store that lives as long as the page: tests, or `storageKey: null`. */
+declare const memoryStore: () => SwapStore;
+/** Swaps in IndexedDB, keyed `<storageKey>/<texture name>`. Falls back to memory without it. */
+declare const indexedDbStore: (storageKey: string) => SwapStore;
+//#endregion
+//#region src/core/lab.d.ts
+type TextureInfo = {
+  name: string;
+  texture: Texture;
+  /** The file it was loaded from, for downloads and thumbnails. */
+  src?: string;
+};
+type SwapEvent = {
+  id: string;
+  /** Every texture sharing the swapped pixels (the originals). */
+  textures: Texture[];
+  /** The textures drawing now: the originals after an in-place swap or a revert, else twins. */
+  bound: Texture[];
+  state: EntryState;
+};
+type TextureLabOptions = {
+  /** Where to look for textures. */
+  scene: Object3D;
+  /** A `WebGLRenderer`, for reading back textures with no file (compressed, data, generated). */
+  renderer?: unknown;
+  /** Textures to list whether or not the scene shows them yet, with names and source files. */
+  textures?: readonly TextureInfo[];
+  /** IndexedDB key prefix for saved swaps. `null` keeps swaps for this page only. Default `three-textures`. */
+  storageKey?: string | null;
+  /** Replaces the store (tests). */
+  store?: SwapStore;
+  /** After any swap, toggle or revert: redraw derived textures (atlases) from `bound`. */
+  onSwap?: (event: SwapEvent) => void;
+  /** Ask for a frame, for render-on-demand loops (R3F `frameloop="demand"`). */
+  invalidate?: () => void;
+};
+type EntryState = "original" | "swapped" | "showing-original";
+type LinkState = "off" | "live" | "paused";
+type TextureEntry = {
+  id: string;
+  kind: TextureKind;
+  /** `ASTC`, `ETC2`, `webp`, `canvas`, `data`… */
+  format: string;
+  width: number;
+  height: number;
+  colorSpace: string;
+  /** The file it came from, when known. */
+  src: string | null;
+  /** How many materials use it. */
+  materials: number;
+  state: EntryState;
+  link: LinkState;
+  /** Name of the file swapped in. */
+  swapName: string | null;
+  /** Why it can't be swapped, when it can't. */
+  unsupported: string | null;
+  /** Counts every change to what it shows: a cache key for thumbnails. */
+  revision: number;
+  /** One of the original textures. */
+  texture: Texture;
+};
+declare class TextureLab {
+  private readonly options;
+  private readonly store;
+  private readonly records;
+  private readonly byId;
+  /** Sources of rebind twins, so a refresh doesn't list them as textures of their own. */
+  private readonly twinSources;
+  private readonly listeners;
+  private readonly restoring;
+  private poll;
+  private disposed;
+  constructor(options: TextureLabOptions);
+  /** Whether this browser can live-link a file (the File System Access API: Chrome, Edge). */
+  static get canLink(): boolean;
+  /** Whether downloads and thumbnails can read textures back from the GPU. */
+  get canReadBack(): boolean;
+  subscribe(listener: () => void): () => void;
+  /** Every texture, by name. */
+  entries(): TextureEntry[];
+  entry(id: string): TextureEntry | 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(): void;
+  /** Swap `blob` (an image file) in for the texture `id`. */
+  swap(id: string, blob: Blob, { fileName, persist }?: {
+    fileName?: string | null;
+    persist?: boolean;
+  }): Promise<void>;
+  /** A/B: show the original (`true`) or the swap (`false`). */
+  showOriginal(id: string, original: boolean): Promise<void>;
+  /** Back to the original, forgetting the swap. */
+  revert(id: string): Promise<void>;
+  /** Every entry back to its original, and every saved swap cleared. */
+  revertAll(): Promise<void>;
+  /**
+   * 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.
+   */
+  toBlob(id: string): Promise<{
+    blob: Blob;
+    fileName: string;
+  }>;
+  /** Save the pixels showing now to the downloads folder. */
+  download(id: string): Promise<void>;
+  /** A small picture of what's showing now, as a data URL; `null` when there's no way to draw it. */
+  thumbnail(id: string, max?: number): string | null;
+  /**
+   * 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).
+   */
+  link(id: string): Promise<void>;
+  /** Stop following the file; the last version stays swapped in. */
+  unlink(id: string): Promise<void>;
+  dispose(): void;
+  private add;
+  private nameOf;
+  private uniqueName;
+  private isRegistered;
+  private restore;
+  private save;
+  private startPolling;
+  private checkLinks;
+  private stopLink;
+  private require;
+  private entryOf;
+  private changed;
+  private notify;
+}
+//#endregion
+export { TextureInfo as a, StoredSwap as c, memoryStore as d, TextureKind as f, sizeOf as h, TextureEntry as i, SwapStore as l, kindOf as m, LinkState as n, TextureLab as o, formatOf as p, SwapEvent as r, TextureLabOptions as s, EntryState as t, indexedDbStore as u };
+//# sourceMappingURL=lab-CN1v1x-y.d.ts.map