Build and revise procedural 3D assets with your coding agent. Local MCP server, CLI and TypeScript engine with rendered review, editable source and GLB export.
JavaScript 3d3d-assets3d-modelingagent-skillsagent-toolsai-agentsasset-pipelinecligame-assetsglbgltfmcpmcp-servermodel-context-protocolprocedural-generationprocedural-modelingtext-to-3dthreejstypescript
Report cross-asset texture duplication with kiln textures (#287) (#296)
Matthew Kissinger52003d3277f0
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 85848d11..db2eedf0 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -7,6 +7,18 @@ does not publish a package.## Unreleased+- `kiln textures <files-or-folders> [--json]` reports the texture duplication a delivered+ set ships: embedded image occurrences against distinct images, the bytes sharing would+ save, and each distinct image's hash, size and the assets carrying it. The duplication+ is between assets, never inside one -- measured over 160 assets in four real worlds,+ within-asset duplicate images were 0 every time -- so a per-asset receipt count cannot+ see it and the report is scoped to a set. It reads bytes and writes nothing, so exported+ and canonical GLBs stay byte-identical; acting on it is the existing `--textures+ external` or `--textures manifest` from+ [#213](https://github.com/instruktlabs/kiln/issues/213). Library export:+ `textureSharingReport` from `@instruktlabs/kiln/asset-export`+ ([#287](https://github.com/instruktlabs/kiln/issues/287)).+## 1.5.0 (2026-10-25)- Generated Codex workspaces forward `KILN_EXPORT_ROOT` to the MCP server, sodiff --git a/dist/agent-run.mjs b/dist/agent-run.mjsindex 58af6b6f..f7426e0c 100644--- a/dist/agent-run.mjs+++ b/dist/agent-run.mjs@@ -39611,6 +39611,11 @@ var init_protocol = __esm(() => {};});+// src/texture-sharing.ts+var init_texture_sharing = __esm(() => {+ init_runtime_textures();+});+// src/asset-export.tsvar exports_asset_export = {};__export(exports_asset_export, {@@ -39846,6 +39851,7 @@ var encoder2, decoder, object3 = (value) => value !== null && typeof value === "var init_asset_export = __esm(() => {init_assets();init_runtime_textures();+ init_texture_sharing();encoder2 = new TextEncoder;decoder = new TextDecoder;});diff --git a/dist/build.json b/dist/build.jsonindex 21518649..2088083b 100644--- a/dist/build.json+++ b/dist/build.json@@ -2,10 +2,10 @@"schemaVersion": 1,"entries": {"worker": {- "identity": "sha256:1b726cc9d574815d80fee785535ffd81f319ba4682275a67a3b18fa668554818",+ "identity": "sha256:44d1307d1b8ddc24c8a3aca8e11a152ae201201a1826b9786cf4ad234d687d78","engineVersion": "1.5.0","toolchain": "[email protected]",- "sourceHash": "83b395d5aeb3dc6f3b6c81a9f655f5fe92e3165402f2a9d1e2e7f7b2c1fdbd76",+ "sourceHash": "5e0bc90a2e66a62db1120589e2f23862d6a615349e14af0bd27346a7774a0efc","rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a","dependencyHash": "af916d063d319fe3c11d1acc13211950eea82bb5ebb87ae4eb60008d72fa7f10","dependencies": {@@ -40,10 +40,10 @@"bundleHash": "sha256:e24d955bc16f47b1368e77f1833afaaaf4f11018c9c9e5e5b8f5eaeca34efd16"},"agent-run": {- "identity": "sha256:1b726cc9d574815d80fee785535ffd81f319ba4682275a67a3b18fa668554818",+ "identity": "sha256:44d1307d1b8ddc24c8a3aca8e11a152ae201201a1826b9786cf4ad234d687d78","engineVersion": "1.5.0","toolchain": "[email protected]",- "sourceHash": "83b395d5aeb3dc6f3b6c81a9f655f5fe92e3165402f2a9d1e2e7f7b2c1fdbd76",+ "sourceHash": "5e0bc90a2e66a62db1120589e2f23862d6a615349e14af0bd27346a7774a0efc","rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a","dependencyHash": "af916d063d319fe3c11d1acc13211950eea82bb5ebb87ae4eb60008d72fa7f10","dependencies": {@@ -75,13 +75,13 @@},"target": "node","file": "agent-run.mjs",- "bundleHash": "sha256:3303b1539a05deae38cdf1d3f1e05c8c1b046e3ee57bc55a8afa975316ff1aaa"+ "bundleHash": "sha256:b166dd44800e3f83301a427ca2b4072092a20017087e8307f8abb2c614107b4b"},"agent-providers": {- "identity": "sha256:1b726cc9d574815d80fee785535ffd81f319ba4682275a67a3b18fa668554818",+ "identity": "sha256:44d1307d1b8ddc24c8a3aca8e11a152ae201201a1826b9786cf4ad234d687d78","engineVersion": "1.5.0","toolchain": "[email protected]",- "sourceHash": "83b395d5aeb3dc6f3b6c81a9f655f5fe92e3165402f2a9d1e2e7f7b2c1fdbd76",+ "sourceHash": "5e0bc90a2e66a62db1120589e2f23862d6a615349e14af0bd27346a7774a0efc","rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a","dependencyHash": "af916d063d319fe3c11d1acc13211950eea82bb5ebb87ae4eb60008d72fa7f10","dependencies": {@@ -116,10 +116,10 @@"bundleHash": "sha256:9d6faf03d307321bc2e3bd5ce5bdee0bbbf61e0ebed8bfebfa1fb072287b83fa"},"mcp": {- "identity": "sha256:1b726cc9d574815d80fee785535ffd81f319ba4682275a67a3b18fa668554818",+ "identity": "sha256:44d1307d1b8ddc24c8a3aca8e11a152ae201201a1826b9786cf4ad234d687d78","engineVersion": "1.5.0","toolchain": "[email protected]",- "sourceHash": "83b395d5aeb3dc6f3b6c81a9f655f5fe92e3165402f2a9d1e2e7f7b2c1fdbd76",+ "sourceHash": "5e0bc90a2e66a62db1120589e2f23862d6a615349e14af0bd27346a7774a0efc","rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a","dependencyHash": "af916d063d319fe3c11d1acc13211950eea82bb5ebb87ae4eb60008d72fa7f10","dependencies": {@@ -154,10 +154,10 @@"bundleHash": "sha256:deeb947091b693e92337a2081678ed06cd0a2d23f813a375001c31dbf529a815"},"cli": {- "identity": "sha256:1b726cc9d574815d80fee785535ffd81f319ba4682275a67a3b18fa668554818",+ "identity": "sha256:44d1307d1b8ddc24c8a3aca8e11a152ae201201a1826b9786cf4ad234d687d78","engineVersion": "1.5.0","toolchain": "[email protected]",- "sourceHash": "83b395d5aeb3dc6f3b6c81a9f655f5fe92e3165402f2a9d1e2e7f7b2c1fdbd76",+ "sourceHash": "5e0bc90a2e66a62db1120589e2f23862d6a615349e14af0bd27346a7774a0efc","rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a","dependencyHash": "af916d063d319fe3c11d1acc13211950eea82bb5ebb87ae4eb60008d72fa7f10","dependencies": {@@ -189,13 +189,13 @@},"target": "node","file": "cli.mjs",- "bundleHash": "sha256:abe74e8e2609e90041ed74217a68c97ae6065b57818286f78b5344aeb0be9b9d"+ "bundleHash": "sha256:adee2762e10bc145052205a57a91448f97b9d56888df7c1ae688203891d8757f"},"engine": {- "identity": "sha256:1b726cc9d574815d80fee785535ffd81f319ba4682275a67a3b18fa668554818",+ "identity": "sha256:44d1307d1b8ddc24c8a3aca8e11a152ae201201a1826b9786cf4ad234d687d78","engineVersion": "1.5.0","toolchain": "[email protected]",- "sourceHash": "83b395d5aeb3dc6f3b6c81a9f655f5fe92e3165402f2a9d1e2e7f7b2c1fdbd76",+ "sourceHash": "5e0bc90a2e66a62db1120589e2f23862d6a615349e14af0bd27346a7774a0efc","rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a","dependencyHash": "af916d063d319fe3c11d1acc13211950eea82bb5ebb87ae4eb60008d72fa7f10","dependencies": {@@ -227,7 +227,7 @@},"target": "node","file": "mcp-engine.mjs",- "bundleHash": "sha256:68715c8a572f4a1d8041f88d228501534f85277bdd206394df6d932d00e1b673"+ "bundleHash": "sha256:4d3b7812dd8e6392f63dfb72ed7883b3171926035f06c202e55ccb77b4110006"}}}diff --git a/dist/cli.mjs b/dist/cli.mjsindex f1fe69af..d0386af0 100644--- a/dist/cli.mjs+++ b/dist/cli.mjs@@ -44350,6 +44350,132 @@ var init_assets_node = __esm(() => {windowsSharePath = /^[\\/]{2}[^\\/]+[\\/][^\\/]+/;});+// src/texture-sharing.ts+function readGlb(bytes) {+ if (bytes.byteLength < 20)+ throw new Error("Not a GLB: shorter than a GLB header");+ const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);+ if (view.getUint32(0, true) !== 1179937895)+ throw new Error("Not a GLB: bad magic");+ if (view.getUint32(4, true) !== 2)+ throw new Error("Not a GLB: unsupported version");+ if (view.getUint32(16, true) !== 1313821514)+ throw new Error("Not a GLB: first chunk is not JSON");+ const jsonEnd = 20 + view.getUint32(12, true);+ if (jsonEnd > bytes.byteLength)+ throw new Error("Invalid GLB chunk length");+ const json = JSON.parse(new TextDecoder().decode(bytes.subarray(20, jsonEnd)));+ if (!object3(json))+ throw new Error("Invalid glTF asset");+ if (jsonEnd + 8 > bytes.byteLength || view.getUint32(jsonEnd + 4, true) !== 5130562)+ return { json };+ const length = view.getUint32(jsonEnd, true);+ if (jsonEnd + 8 + length > bytes.byteLength)+ throw new Error("Invalid GLB chunk length");+ return { json, binary: bytes.subarray(jsonEnd + 8, jsonEnd + 8 + length) };+}+function pixelSize(bytes) {+ try {+ return imageDimensions(bytes);+ } catch {+ return {};+ }+}+function carriedImages(json, binary) {+ const views = Array.isArray(json.bufferViews) ? json.bufferViews : [];+ const carried = [];+ for (const image of Array.isArray(json.images) ? json.images : []) {+ if (!object3(image))+ throw new Error("Invalid glTF image");+ const view = index2(image.bufferView);+ if (view !== undefined) {+ const def = views[view];+ if (!object3(def))+ throw new Error("Invalid glTF image buffer view");+ if ((index2(def.buffer) ?? 0) !== 0)+ throw new Error("Image buffer view is not in this GLB binary chunk");+ const offset = index2(def.byteOffset) ?? 0;+ const length = index2(def.byteLength);+ if (length === undefined || !binary || offset + length > binary.byteLength)+ throw new Error("Invalid glTF image buffer view");+ if (typeof image.mimeType !== "string")+ throw new Error("Embedded image needs a mimeType");+ carried.push({ bytes: binary.subarray(offset, offset + length), mimeType: image.mimeType });+ continue;+ }+ const match = typeof image.uri === "string" ? DATA_URI.exec(image.uri) : null;+ if (match)+ carried.push({+ bytes: Uint8Array.from(atob(match[2]), (character) => character.charCodeAt(0)),+ mimeType: match[1]+ });+ }+ return carried;+}+async function textureSharingReport(assets) {+ const distinct = new Map;+ const skipped = [];+ let read = 0;+ let assetBytes = 0;+ let embeddedImages = 0;+ let embeddedImageBytes = 0;+ for (const asset of assets) {+ let carried;+ try {+ const { json, binary } = readGlb(asset.bytes);+ carried = carriedImages(json, binary);+ } catch (error) {+ skipped.push({ name: asset.name, reason: error.message });+ continue;+ }+ read += 1;+ assetBytes += asset.bytes.byteLength;+ for (const image of carried) {+ embeddedImages += 1;+ embeddedImageBytes += image.bytes.byteLength;+ const sha256 = `sha256:${await sha256Hex2(image.bytes)}`;+ const entry = distinct.get(sha256);+ if (entry) {+ entry.copies += 1;+ entry.assets.add(asset.name);+ } else+ distinct.set(sha256, {+ bytes: image.bytes.byteLength,+ mimeType: image.mimeType,+ ...pixelSize(image.bytes),+ copies: 1,+ assets: new Set([asset.name])+ });+ }+ }+ const distinctImageBytes = [...distinct.values()].reduce((total, image) => total + image.bytes, 0);+ const saving = (image) => image.bytes * (image.copies - 1);+ return {+ version: "kiln.texture-sharing.v1",+ assets: read,+ assetBytes,+ embeddedImages,+ distinctImages: distinct.size,+ embeddedImageBytes,+ distinctImageBytes,+ duplicateImageBytes: embeddedImageBytes - distinctImageBytes,+ images: [...distinct.entries()].sort(([sha, image], [otherSha, other]) => saving(other) - saving(image) || (sha < otherSha ? -1 : sha > otherSha ? 1 : 0)).map(([sha256, { bytes, mimeType, width, height, copies, assets: using }]) => ({+ sha256,+ bytes,+ mimeType,+ ...width !== undefined ? { width, height } : {},+ copies,+ assets: [...using].sort()+ })),+ skipped+ };+}+var object3 = (value) => typeof value === "object" && value !== null, index2 = (value) => typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : undefined, DATA_URI;+var init_texture_sharing = __esm(() => {+ init_runtime_textures();+ DATA_URI = /^data:([^;,]+);base64,(.*)$/s;+});+// src/ktx2-basis.tsimport { createHash as createHash17 } from "node:crypto";import { readFile as readFile8 } from "node:fs/promises";@@ -44514,7 +44640,7 @@ function readGlbJson(bytes) {}const jsonEnd = 20 + view.getUint32(12, true);const json = JSON.parse(decoder.decode(bytes.subarray(20, jsonEnd)));- if (!object3(json) || !object3(json.asset) || json.asset.version !== "2.0")+ if (!object4(json) || !object4(json.asset) || json.asset.version !== "2.0")throw new Error("Invalid glTF asset");return { json, jsonEnd };}@@ -44584,7 +44710,7 @@ async function exportAssetGlb(record, options = {}) {}const { json, jsonEnd } = readGlbJson(bytes);const asset = json.asset;- if (owns(asset, "extras") && !object3(asset.extras))+ if (owns(asset, "extras") && !object4(asset.extras))throw new Error("Cannot add provenance to non-object asset extras");const extras = asset.extras ?? {};if (owns(extras, "kilnProvenanceV1"))@@ -44593,10 +44719,10 @@ async function exportAssetGlb(record, options = {}) {if (json.scenes !== undefined && !Array.isArray(json.scenes))throw new Error("Invalid glTF scenes");for (const [index, scene] of (json.scenes ?? []).entries()) {- if (!object3(scene) || !object3(scene.extras) || !owns(scene.extras, "kilnReviewClipsV1"))+ if (!object4(scene) || !object4(scene.extras) || !owns(scene.extras, "kilnReviewClipsV1"))continue;const review = scene.extras.kilnReviewClipsV1;- if (!object3(review) || review.version !== 1 && review.version !== 2 || !Array.isArray(review.clips))+ if (!object4(review) || review.version !== 1 && review.version !== 2 || !Array.isArray(review.clips))throw new Error("Unsupported scenes[].extras.kilnReviewClipsV1");scenes.push({ index, kilnReviewClipsV1: review });delete scene.extras.kilnReviewClipsV1;@@ -44692,10 +44818,11 @@ async function externalLayout(gltf, manifest) {throw new Error(`Unexpected external glTF resource ${uri}`);return { json, buffers, textures: [...textures.values()] };}-var encoder2, decoder, object3 = (value) => value !== null && typeof value === "object" && !Array.isArray(value), owns = (value, key) => Object.hasOwn(value, key);+var encoder2, decoder, object4 = (value) => value !== null && typeof value === "object" && !Array.isArray(value), owns = (value, key) => Object.hasOwn(value, key);var init_asset_export = __esm(() => {init_assets();init_runtime_textures();+ init_texture_sharing();encoder2 = new TextEncoder;decoder = new TextDecoder;});@@ -56540,7 +56667,7 @@ async function assetMain(argv) {}if (arg === "--category" || arg.startsWith("--category="))throw new Error(CATEGORY_MIGRATION_MESSAGE);- if (arg === "--json" && command === "export") {+ if (arg === "--json" && (command === "export" || command === "textures")) {flags.json = "true";continue;}@@ -56842,6 +56969,50 @@ async function assetMain(argv) {}))}, null, 2));}+ } else if (command === "textures") {+ if (!positional.length)+ throw new Error("textures requires a file or directory");+ const { readdir } = await import("node:fs/promises");+ const paths = [];+ for (const path of positional) {+ if ((await stat6(path)).isDirectory())+ for (const entry of (await readdir(path)).sort()) {+ if (entry.toLowerCase().endsWith(".glb"))+ paths.push(resolve14(path, entry));+ }+ else+ paths.push(resolve14(path));+ }+ if (paths.length > TEXTURE_REPORT_LIMIT)+ throw new Error(`textures reads at most ${TEXTURE_REPORT_LIMIT} assets at once`);+ const assets = [];+ for (const path of paths)+ assets.push({ name: basename2(path), bytes: await fileBytes(path) });+ await Promise.resolve().then(() => init_texture_sharing());+ const report = await textureSharingReport(assets);+ if (flags.json)+ console.log(JSON.stringify({ ok: true, ...report }, null, 2));+ else {+ const count = (value) => value.toLocaleString("en-US");+ const share = report.assetBytes ? ` (${(100 * report.duplicateImageBytes / report.assetBytes).toFixed(1)}% of ${count(report.assetBytes)} delivered bytes)` : "";+ console.log(`${count(report.assets)} assets · ${count(report.embeddedImages)} embedded images · ${count(report.distinctImages)} distinct · ${count(report.duplicateImageBytes)} duplicated bytes${share}`);+ for (const { name, reason } of report.skipped)+ console.log(`Skipped ${name}: ${reason}`);+ if (!report.duplicateImageBytes)+ console.log("Every image is carried once: nothing to share across this set.");+ else {+ console.log("Share each image once with --textures external, or name their identities for a host with --textures manifest (docs/export-profiles.md#runtime-textures-manifest-and-shared-files):");+ const shared = report.images.filter((image) => image.copies > 1);+ for (const image of shared.slice(0, 10)) {+ const names = image.assets.slice(0, 3).join(", ");+ const rest = image.assets.length - 3;+ const size = image.width === undefined ? "" : `${image.width}x${image.height} `;+ console.log(` ${image.sha256.slice("sha256:".length, "sha256:".length + 12)} ${count(image.bytes)} B ${size}${image.mimeType} · ${image.copies} copies · saves ${count(image.bytes * (image.copies - 1))} B · ${names}${rest > 0 ? ` +${count(rest)} more` : ""}`);+ }+ if (shared.length > 10)+ console.log(` ... and ${count(shared.length - 10)} more shared images (--json for all)`);+ }+ }} else if (command === "import") {const file = positional[0];if (!file)@@ -56903,7 +57074,7 @@ async function assetMain(argv) {}return 0;}-var SAVE_LINES = ` kiln save <source.js|programRef> --name <name> [--collection project]+var TEXTURE_REPORT_LIMIT = 1024, SAVE_LINES = ` kiln save <source.js|programRef> --name <name> [--collection project][--asset <id> --parent <revision>] [--description <text>] [--tag <tag>][--model <model>] [--harness <harness>] [--author <author>] declared attribution[--backdrop neutral|dark|light] preview backdrop; the one the reviewed sheet used@@ -56966,6 +57137,11 @@ ${SAVE_LINES}[--json] receipt naming each file with its bytes and sha256export never replaces an existing file: an export hands off one exactsaved revision, while render --out replaces its own working output+ kiln textures <file-or-directory>... [--json]+ how many distinct images a delivered set carries against how many it ships,+ and the bytes sharing them would save. The duplication is between assets,+ never inside one, so point this at a whole delivery folder. Reads only:+ it writes and rewrites nothingkiln import <asset.zip|asset.glb> [--collection project] [--name <name>]prints the directory of each imported revisionkiln view [collection-directory|asset.glb|asset.zip] [--port 4318]@@ -57379,7 +57555,7 @@ function applyJsonOption(argv) {throw new Error(JSON_OPTION_MESSAGE);return PRINTS_JSON.has(command ?? "") ? rest : argv;}-var JSON_OPTION_MESSAGE = "--json prints a JSON receipt from render, source, export, discover, inspect, animation and service status|reprobe; edit, save, collections, assets, asset, import, project, material, review and migrate print JSON already and accept it. generate, view, collections add and service start|stop print no JSON.", PRINTS_JSON;+var JSON_OPTION_MESSAGE = "--json prints a JSON receipt from render, source, export, textures, discover, inspect, animation and service status|reprobe; edit, save, collections, assets, asset, import, project, material, review and migrate print JSON already and accept it. generate, view, collections add and service start|stop print no JSON.", PRINTS_JSON;var init_cli_json = __esm(() => {PRINTS_JSON = new Set(["save",@@ -59607,7 +59783,7 @@ async function runMain(argv) {return 1;}}- if (["save", "collections", "assets", "asset", "export", "import", "view"].includes(argv[0] ?? "")) {+ if (["save", "collections", "assets", "asset", "export", "textures", "import", "view"].includes(argv[0] ?? "")) {try {return await (await Promise.resolve().then(() => (init_asset_cli(), exports_asset_cli))).assetMain(argv);} catch (error) {diff --git a/dist/mcp-engine.mjs b/dist/mcp-engine.mjsindex 0ada2bdc..a432f370 100644--- a/dist/mcp-engine.mjs+++ b/dist/mcp-engine.mjs@@ -7033,6 +7033,11 @@ var init_runtime_textures = __esm(() => {]);});+// src/texture-sharing.ts+var init_texture_sharing = __esm(() => {+ init_runtime_textures();+});+// src/contracts/semantic.tsfunction semanticRole(base, ...segments) {const tail = segments.map((segment) => String(segment).trim()).filter((segment) => segment !== "");@@ -10822,6 +10827,7 @@ var encoder2, decoder, object2 = (value) => value !== null && typeof value === "var init_asset_export = __esm(() => {init_assets();init_runtime_textures();+ init_texture_sharing();encoder2 = new TextEncoder;decoder = new TextDecoder;});diff --git a/docs/export-profiles.md b/docs/export-profiles.mdindex 0a22a435..391ce0c2 100644--- a/docs/export-profiles.md+++ b/docs/export-profiles.md@@ -356,6 +356,7 @@ keep that notice file. KTX2 output is data produced by the encoder, not a copy oRuntime GLBs embed every texture, so forty assets that use one library material carryforty copies of its maps. Two opt-in choices let a host share them. Neither is thedefault: without `--textures`, the GLB, sidecar and `--json` receipt bytes are unchanged.+`kiln textures` measures what a given set would save before you choose.**Manifest.** `--textures manifest` (runtime profile, with or without `--target three`)adds `textures[]` to the sidecar. The GLB is unchanged apart from the provenance hash of@@ -430,6 +431,40 @@ Plain `--profile runtime` keeps `.glb` only, because that profile copies the binbyte for byte. Kiln's tests validate the `.gltf` with `gltf-validator` and load it through`GLTFLoader`. MCP `kiln_export` does not offer these options.+### Measuring a set: `kiln textures`++The duplication is **between assets, never inside one**: the exporter already shares an+image an asset uses twice, so a per-asset count of distinct against embedded images is+equal on every asset Kiln has ever written. Measured over 160 assets in four real worlds,+within-asset duplicate images were 0 every time. `kiln textures` therefore reads a whole+delivered set:++```sh+kiln textures assets/imports # a delivery folder+kiln textures palm.glb fern.glb --json # or named files, with a receipt+```++```text+49 assets · 119 embedded images · 24 distinct · 14,315,977 duplicated bytes (62.1% of 23,048,068 delivered bytes)+ e29644e20915 425,509 B 512x512 image/png · 12 copies · saves 4,680,599 B · palm-a.glb, palm-b.glb, shrub-a.glb +9 more+```++It reads bytes and writes nothing, so it is safe to point at a frozen delivery folder.+Directories contribute their `*.glb` files; a named file that is not a readable GLB is+listed under `skipped` with the reason rather than failing the set. At most 1024 assets+are read at once. `--json` adds `ok: true` to the `kiln.texture-sharing.v1` record:+`assets`, `assetBytes`, `embeddedImages`, `distinctImages`, `embeddedImageBytes`,+`distinctImageBytes`, `duplicateImageBytes`, and `images[]` — each distinct image's+`sha256`, `bytes`, `mimeType`, `copies` and the `assets` carrying it, largest saving+first, with `width` and `height` when the header is one Kiln reads. An image whose bytes+live in a buffer outside the GLB is not this GLB's to share, so that asset is skipped+with a reason rather than counted from the wrong bytes. The library export is `textureSharingReport` from+`@instruktlabs/kiln/asset-export`.++Worth measuring rather than assuming: across four real worlds the same mechanism saved+62.1%, 14.8%, 8.7% and 6.2% of delivered bytes. The saving is large only when the pack+genuinely shares a material family, so the number that matters is the one for your set.+## Pointer and hash contractThe runtime GLB contains this record in `asset.extras.kilnProvenanceV1`:diff --git a/skills/kiln-author-asset/references/export-profiles.md b/skills/kiln-author-asset/references/export-profiles.mdindex 770634d0..4317c451 100644--- a/skills/kiln-author-asset/references/export-profiles.md+++ b/skills/kiln-author-asset/references/export-profiles.md@@ -107,6 +107,13 @@ node kiln.mjs export ASSET_ID REVISION_ID --profile runtime --textures manifestnode kiln.mjs export ASSET_ID REVISION_ID --profile runtime --target three --textures external --out assets/mech.gltf --json```+Measure before choosing: `kiln textures <folder-or-files> [--json]` reports how many+distinct images a delivered set carries against how many it ships, largest saving first.+The duplication is between assets, never inside one -- the exporter already shares an+image an asset uses twice -- so point it at the whole delivery folder, not one asset. It+reads bytes and writes nothing. Across four real worlds the saving ranged from 6.2% to+62.1% of delivered bytes, so use your own set's number.+Both texture options are opt-in; without them the runtime files are unchanged. Themanifest lists each image's exact `sha256`, size, colour space and, when its bytes equala saved library map, that material pin. External textures are named by the hash of theirdiff --git a/src/asset-cli-texture-sharing.test.ts b/src/asset-cli-texture-sharing.test.tsnew file mode 100644index 00000000..3ee86dbf--- /dev/null+++ b/src/asset-cli-texture-sharing.test.ts@@ -0,0 +1,92 @@+/**+ * `kiln textures` (#287): the cross-asset duplication report over delivered assets.+ *+ * It reads bytes and writes nothing, so it can be pointed at a frozen delivery folder.+ */+import { expect, test } from 'bun:test';+import { spawnSync } from 'node:child_process';+import { createHash } from 'node:crypto';+import { mkdtemp, rm, writeFile } from 'node:fs/promises';+import { tmpdir } from 'node:os';+import { join, resolve } from 'node:path';+import { Document, WebIO } from '@gltf-transform/core';+import { encodePng } from './views/png';++const sha = (bytes: Uint8Array) => `sha256:${createHash('sha256').update(bytes).digest('hex')}`;+const png = (rgb: number[]) => new Uint8Array(encodePng(new Uint8Array(rgb), 2, 2));+const LEAF = png([30, 120, 40, 40, 140, 50, 30, 110, 35, 50, 150, 60]);+const BARK = png([90, 70, 50, 100, 80, 60, 85, 65, 45, 110, 90, 70]);++/** One textured triangle carrying the given images: base colour first, then normal. */+async function texturedGlb(images: readonly Uint8Array[]): Promise<Uint8Array> {+ const doc = new Document();+ const buffer = doc.createBuffer();+ const accessor = (type: 'VEC2' | 'VEC3', values: number[]) =>+ doc.createAccessor().setType(type).setArray(new Float32Array(values)).setBuffer(buffer);+ const material = doc.createMaterial('Plant');+ images.forEach((bytes, index) => {+ const texture = doc.createTexture(`image${index}`).setImage(bytes).setMimeType('image/png');+ if (index === 0) material.setBaseColorTexture(texture);+ else material.setNormalTexture(texture);+ });+ const primitive = doc+ .createPrimitive()+ .setAttribute('POSITION', accessor('VEC3', [0, 0, 0, 1, 0, 0, 0, 1, 0]))+ .setAttribute('TEXCOORD_0', accessor('VEC2', [0, 0, 1, 0, 0, 1]))+ .setMaterial(material);+ doc+ .createScene('Scene')+ .addChild(doc.createNode('Plant').setMesh(doc.createMesh('Plant').addPrimitive(primitive)));+ return new WebIO().writeBinary(doc);+}++test('kiln textures reports the duplication a pack ships and leaves every file alone', async () => {+ const root = await mkdtemp(join(tmpdir(), 'kiln-texture-sharing-'));+ const run = (args: string[]) =>+ spawnSync(process.execPath, [resolve('src/cli.ts'), ...args], {+ cwd: root,+ env: { ...process.env, KILN_RENDER: 'cpu' },+ encoding: 'utf8',+ });+ try {+ // Three plants on one shared leaf atlas: the pack's own material family.+ const [palm, fern, shrub] = await Promise.all([+ texturedGlb([LEAF, BARK]),+ texturedGlb([LEAF]),+ texturedGlb([LEAF]),+ ]);+ await Promise.all([+ writeFile(join(root, 'palm.glb'), palm),+ writeFile(join(root, 'fern.glb'), fern),+ writeFile(join(root, 'shrub.glb'), shrub),+ writeFile(join(root, 'notes.md'), 'not an asset'),+ ]);++ const receipt = run(['textures', '.', '--json']);+ expect(receipt.status).toBe(0);+ const report = JSON.parse(receipt.stdout);+ expect(report.ok).toBe(true);+ expect(report.version).toBe('kiln.texture-sharing.v1');+ expect(report.assets).toBe(3);+ expect(report.embeddedImages).toBe(4);+ expect(report.distinctImages).toBe(2);+ expect(report.duplicateImageBytes).toBe(LEAF.length * 2);+ expect(report.skipped).toEqual([]);+ // Largest saving first, and the atlas names every asset shipping a copy.+ expect(report.images[0].sha256).toBe(sha(LEAF));+ expect(report.images[0].copies).toBe(3);+ expect(report.images[0].assets).toEqual(['fern.glb', 'palm.glb', 'shrub.glb']);++ // Named files are read directly, and the report says what to do about a saving.+ const text = run(['textures', 'palm.glb', 'fern.glb']);+ expect(text.status).toBe(0);+ expect(text.stdout).toContain('2 distinct');+ expect(text.stdout).toContain('--textures external');++ // One asset alone has nothing to share, which is the normal per-asset case.+ const alone = run(['textures', 'palm.glb', '--json']);+ expect(JSON.parse(alone.stdout).duplicateImageBytes).toBe(0);+ } finally {+ await rm(root, { recursive: true, force: true });+ }+});diff --git a/src/asset-cli.ts b/src/asset-cli.tsindex 10a6fa1a..c8daf701 100644--- a/src/asset-cli.ts+++ b/src/asset-cli.ts@@ -25,6 +25,9 @@ import { CATEGORY_MIGRATION_MESSAGE, readHostRequirementsFile } from './requiremimport { observeLiveReview } from './tools/workspace';import { cliWorkspaceSelection, readMaterialDependencies } from './workspace-cli';+/** `kiln textures` reads every asset into memory, so the set is bounded. */+const TEXTURE_REPORT_LIMIT = 1024;+const SAVE_LINES = ` kiln save <source.js|programRef> --name <name> [--collection project][--asset <id> --parent <revision>] [--description <text>] [--tag <tag>][--model <model>] [--harness <harness>] [--author <author>] declared attribution@@ -67,6 +70,11 @@ ${SAVE_LINES}[--json] receipt naming each file with its bytes and sha256export never replaces an existing file: an export hands off one exactsaved revision, while render --out replaces its own working output+ kiln textures <file-or-directory>... [--json]+ how many distinct images a delivered set carries against how many it ships,+ and the bytes sharing them would save. The duplication is between assets,+ never inside one, so point this at a whole delivery folder. Reads only:+ it writes and rewrites nothingkiln import <asset.zip|asset.glb> [--collection project] [--name <name>]prints the directory of each imported revisionkiln view [collection-directory|asset.glb|asset.zip] [--port 4318]@@ -135,8 +143,8 @@ export async function assetMain(argv: readonly string[]): Promise<number> {}if (arg === '--category' || arg.startsWith('--category='))throw new Error(CATEGORY_MIGRATION_MESSAGE);- // The CLI's --json rule (cli-json.ts) leaves the switch only on export's receipt.- if (arg === '--json' && command === 'export') {+ // The CLI's --json rule (cli-json.ts) leaves the switch on the export and textures receipts.+ if (arg === '--json' && (command === 'export' || command === 'textures')) {flags.json = 'true';continue;}@@ -555,6 +563,54 @@ export async function assetMain(argv: readonly string[]): Promise<number> {),);}+ } else if (command === 'textures') {+ if (!positional.length) throw new Error('textures requires a file or directory');+ const { readdir } = await import('node:fs/promises');+ const paths: string[] = [];+ for (const path of positional) {+ if ((await stat(path)).isDirectory())+ for (const entry of (await readdir(path)).sort()) {+ if (entry.toLowerCase().endsWith('.glb')) paths.push(resolve(path, entry));+ }+ else paths.push(resolve(path));+ }+ // Bounded so pointing this at a whole tree fails fast instead of reading it all in.+ if (paths.length > TEXTURE_REPORT_LIMIT)+ throw new Error(`textures reads at most ${TEXTURE_REPORT_LIMIT} assets at once`);+ const assets: { name: string; bytes: Uint8Array }[] = [];+ for (const path of paths) assets.push({ name: basename(path), bytes: await fileBytes(path) });+ const { textureSharingReport } = await import('./texture-sharing');+ const report = await textureSharingReport(assets);+ if (flags.json) console.log(JSON.stringify({ ok: true, ...report }, null, 2));+ else {+ const count = (value: number) => value.toLocaleString('en-US');+ const share = report.assetBytes+ ? ` (${((100 * report.duplicateImageBytes) / report.assetBytes).toFixed(1)}% of ${count(report.assetBytes)} delivered bytes)`+ : '';+ console.log(+ `${count(report.assets)} assets · ${count(report.embeddedImages)} embedded images · ${count(report.distinctImages)} distinct · ${count(report.duplicateImageBytes)} duplicated bytes${share}`,+ );+ for (const { name, reason } of report.skipped) console.log(`Skipped ${name}: ${reason}`);+ if (!report.duplicateImageBytes)+ console.log('Every image is carried once: nothing to share across this set.');+ else {+ console.log(+ 'Share each image once with --textures external, or name their identities for a host with --textures manifest (docs/export-profiles.md#runtime-textures-manifest-and-shared-files):',+ );+ const shared = report.images.filter((image) => image.copies > 1);+ // Names are abbreviated here; --json carries every hash and every asset in full.+ for (const image of shared.slice(0, 10)) {+ const names = image.assets.slice(0, 3).join(', ');+ const rest = image.assets.length - 3;+ const size = image.width === undefined ? '' : `${image.width}x${image.height} `;+ console.log(+ ` ${image.sha256.slice('sha256:'.length, 'sha256:'.length + 12)} ${count(image.bytes)} B ${size}${image.mimeType} · ${image.copies} copies · saves ${count(image.bytes * (image.copies - 1))} B · ${names}${rest > 0 ? ` +${count(rest)} more` : ''}`,+ );+ }+ if (shared.length > 10)+ console.log(` ... and ${count(shared.length - 10)} more shared images (--json for all)`);+ }+ }} else if (command === 'import') {const file = positional[0];if (!file) throw new Error('import requires a ZIP or GLB file');diff --git a/src/asset-export.ts b/src/asset-export.tsindex 0dfcfbca..b57ee86f 100644--- a/src/asset-export.ts+++ b/src/asset-export.ts@@ -33,6 +33,8 @@ export type {RuntimeThreeOptionsV1,} from './runtime-three';export type { RuntimeTextureManifestEntryV1 } from './runtime-textures';+export { textureSharingReport } from './texture-sharing';+export type { TextureSharingImageV1, TextureSharingReportV1 } from './texture-sharing';export type AssetExportProfile = 'editable' | 'runtime';/*** Runtime only, opt-in. `manifest` adds sidecar `textures[]`; `external` (three target only)diff --git a/src/cli-json.ts b/src/cli-json.tsindex 721c3cdb..3fe1e25f 100644--- a/src/cli-json.ts+++ b/src/cli-json.ts@@ -4,7 +4,7 @@* no JSON output refuse it with this message. Receipt parsers own their own --json.*/export const JSON_OPTION_MESSAGE =- '--json prints a JSON receipt from render, source, export, discover, inspect, animation and service status|reprobe; edit, save, collections, assets, asset, import, project, material, review and migrate print JSON already and accept it. generate, view, collections add and service start|stop print no JSON.';+ '--json prints a JSON receipt from render, source, export, textures, discover, inspect, animation and service status|reprobe; edit, save, collections, assets, asset, import, project, material, review and migrate print JSON already and accept it. generate, view, collections add and service start|stop print no JSON.';const PRINTS_JSON = new Set(['save',diff --git a/src/cli.ts b/src/cli.tsindex 29980676..9dae4cbb 100644--- a/src/cli.ts+++ b/src/cli.ts@@ -803,7 +803,9 @@ async function runMain(argv: readonly string[]): Promise<number> {}}if (- ['save', 'collections', 'assets', 'asset', 'export', 'import', 'view'].includes(argv[0] ?? '')+ ['save', 'collections', 'assets', 'asset', 'export', 'textures', 'import', 'view'].includes(+ argv[0] ?? '',+ )) {try {return await (await import('./asset-cli')).assetMain(argv);diff --git a/src/texture-sharing.test.ts b/src/texture-sharing.test.tsnew file mode 100644index 00000000..540a8ac2--- /dev/null+++ b/src/texture-sharing.test.ts@@ -0,0 +1,237 @@+/**+ * Cross-asset texture sharing report (#287).+ *+ * The duplication #287 reports is entirely between assets, never inside one: measured over+ * 160 assets in four real Holodeck worlds, within-asset duplicate images were 0 every time,+ * because the exporter already dedupes images inside one document. So the report is scoped+ * to a set of delivered assets, and a single asset's own distinct images are never a saving.+ *+ * Fixtures are built with glTF-Transform from fixed PNGs, so their bytes depend only on+ * pinned packages, never on Kiln's renderer.+ */+import { expect, test } from 'bun:test';+import { createHash } from 'node:crypto';+import { Document, WebIO } from '@gltf-transform/core';+import { textureSharingReport } from './texture-sharing';++const sha = (bytes: Uint8Array) => `sha256:${createHash('sha256').update(bytes).digest('hex')}`;+const BASE_PNG = new Uint8Array(+ Buffer.from(+ 'iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAIAAAD91JpzAAAAFklEQVR4nGM4oaGhcUKDQUPjxJ07dwAhpgXd58qIBQAAAABJRU5ErkJggg==',+ 'base64',+ ),+);+const NORMAL_PNG = new Uint8Array(+ Buffer.from(+ 'iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAIAAAD91JpzAAAAEklEQVR4nGNoaPjf0PCfAUIBADX2B/1D9pjhAAAAAElFTkSuQmCC',+ 'base64',+ ),+);++/** One textured triangle carrying the given images, in order: base colour, then normal. */+async function texturedGlb(images: readonly Uint8Array[]): Promise<Uint8Array> {+ const doc = new Document();+ const buffer = doc.createBuffer();+ const position = doc+ .createAccessor()+ .setType('VEC3')+ .setArray(new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]))+ .setBuffer(buffer);+ const uv = doc+ .createAccessor()+ .setType('VEC2')+ .setArray(new Float32Array([0, 0, 1, 0, 0, 1]))+ .setBuffer(buffer);+ const material = doc.createMaterial('Brick');+ images.forEach((bytes, index) => {+ const texture = doc.createTexture(`image${index}`).setImage(bytes).setMimeType('image/png');+ if (index === 0) material.setBaseColorTexture(texture);+ else material.setNormalTexture(texture);+ });+ const primitive = doc+ .createPrimitive()+ .setAttribute('POSITION', position)+ .setAttribute('TEXCOORD_0', uv)+ .setMaterial(material);+ const node = doc.createNode('Tri').setMesh(doc.createMesh('Tri').addPrimitive(primitive));+ doc.createScene('Scene').addChild(node);+ return new WebIO().writeBinary(doc);+}++/** The same GLB with its JSON chunk replaced, so a test can express a layout by hand. */+function rebuilt(glb: Uint8Array, mutate: (json: Record<string, unknown>) => void): Uint8Array {+ const view = new DataView(glb.buffer, glb.byteOffset, glb.byteLength);+ const jsonEnd = 20 + view.getUint32(12, true);+ const json = JSON.parse(new TextDecoder().decode(glb.subarray(20, jsonEnd)));+ mutate(json);+ const text = new TextEncoder().encode(JSON.stringify(json));+ const padded = Math.ceil(text.length / 4) * 4;+ const out = new Uint8Array(20 + padded + (glb.byteLength - jsonEnd));+ out.set(glb.subarray(0, 20));+ out.fill(0x20, 20 + text.length, 20 + padded);+ out.set(text, 20);+ out.set(glb.subarray(jsonEnd), 20 + padded);+ const header = new DataView(out.buffer);+ header.setUint32(8, out.byteLength, true);+ header.setUint32(12, padded, true);+ return out;+}++test('reports one shared image as a saving and names every asset carrying it', async () => {+ const [wall, floor] = await Promise.all([+ texturedGlb([BASE_PNG, NORMAL_PNG]),+ texturedGlb([BASE_PNG]),+ ]);+ const report = await textureSharingReport([+ { name: 'wall.glb', bytes: wall },+ { name: 'floor.glb', bytes: floor },+ ]);++ expect(report.assets).toBe(2);+ expect(report.assetBytes).toBe(wall.byteLength + floor.byteLength);+ // Three embedded images, two distinct: the base colour map ships twice.+ expect(report.embeddedImages).toBe(3);+ expect(report.distinctImages).toBe(2);+ expect(report.embeddedImageBytes).toBe(BASE_PNG.length * 2 + NORMAL_PNG.length);+ expect(report.distinctImageBytes).toBe(BASE_PNG.length + NORMAL_PNG.length);+ expect(report.duplicateImageBytes).toBe(BASE_PNG.length);+ expect(report.skipped).toEqual([]);++ const shared = report.images.find((image) => image.sha256 === sha(BASE_PNG));+ expect(shared).toEqual({+ sha256: sha(BASE_PNG),+ bytes: BASE_PNG.length,+ mimeType: 'image/png',+ width: 2,+ height: 2,+ copies: 2,+ assets: ['floor.glb', 'wall.glb'],+ });+ // The map only one asset carries is reported too, with no saving behind it.+ expect(report.images.find((image) => image.sha256 === sha(NORMAL_PNG))?.copies).toBe(1);+});++test("one asset's own distinct images are never counted as a saving", async () => {+ const wall = await texturedGlb([BASE_PNG, NORMAL_PNG]);+ const report = await textureSharingReport([{ name: 'wall.glb', bytes: wall }]);++ expect(report.embeddedImages).toBe(2);+ expect(report.distinctImages).toBe(2);+ expect(report.duplicateImageBytes).toBe(0);+});++test('counts a repeated image inside one asset as a copy, not as a second distinct image', async () => {+ // Hand-built, because glTF-Transform dedupes identical images: a second image entry+ // pointing at the same buffer view. Real exports never do this -- 0 of 160 measured+ // assets did -- so the report has to stay right for the case it will not meet.+ const wall = rebuilt(await texturedGlb([BASE_PNG]), (json) => {+ (json.images as Record<string, unknown>[]).push({ ...(json.images as unknown[])[0]! });+ });++ const report = await textureSharingReport([{ name: 'wall.glb', bytes: wall }]);+ expect(report.skipped).toEqual([]);+ expect(report.embeddedImages).toBe(2);+ expect(report.distinctImages).toBe(1);+ expect(report.duplicateImageBytes).toBe(BASE_PNG.length);+ expect(report.images[0]!.copies).toBe(2);+ expect(report.images[0]!.assets).toEqual(['wall.glb']);+});++test('skips an unreadable input with its reason instead of failing the whole set', async () => {+ const wall = await texturedGlb([BASE_PNG]);+ const report = await textureSharingReport([+ { name: 'wall.glb', bytes: wall },+ {+ name: 'notes.txt',+ bytes: new TextEncoder().encode('a stray note sitting in the delivery folder'),+ },+ ]);++ expect(report.assets).toBe(1);+ expect(report.assetBytes).toBe(wall.byteLength);+ expect(report.distinctImages).toBe(1);+ expect(report.skipped).toEqual([{ name: 'notes.txt', reason: 'Not a GLB: bad magic' }]);+});++test('ignores an image already hosted outside the asset', async () => {+ const wall = rebuilt(await texturedGlb([BASE_PNG]), (json) => {+ json.images = [{ uri: 'textures/abc.png' }];+ });++ const report = await textureSharingReport([{ name: 'wall.glb', bytes: wall }]);+ expect(report.embeddedImages).toBe(0);+ expect(report.distinctImages).toBe(0);+ expect(report.duplicateImageBytes).toBe(0);+ expect(report.skipped).toEqual([]);+});++test('counts an image whose header it cannot read, without its pixel size', async () => {+ // Byte identity is what sharing turns on, so an unreadable header must not cost the+ // whole asset its report. Two assets carry the same opaque image.+ const opaque = new Uint8Array([7, 7, 7, 7, 7, 7, 7, 7]);+ const carry = (glb: Uint8Array) =>+ rebuilt(glb, (json) => {+ const views = json.bufferViews as Record<string, unknown>[];+ views.push({ buffer: 0, byteOffset: 0, byteLength: opaque.length });+ json.images = [{ bufferView: views.length - 1, mimeType: 'image/png' }];+ });+ const [wall, floor] = await Promise.all([texturedGlb([BASE_PNG]), texturedGlb([BASE_PNG])]);++ const report = await textureSharingReport([+ { name: 'wall.glb', bytes: carry(wall) },+ { name: 'floor.glb', bytes: carry(floor) },+ ]);+ expect(report.skipped).toEqual([]);+ expect(report.embeddedImages).toBe(2);+ expect(report.distinctImages).toBe(1);+ expect(report.images[0]!.copies).toBe(2);+ expect(report.images[0]!.bytes).toBe(opaque.length);+ expect(report.images[0]!.width).toBeUndefined();+ expect(report.images[0]!.height).toBeUndefined();+});++test('skips an asset whose image lives in a buffer this GLB does not carry', async () => {+ // Buffer 0 is the GLB's own binary chunk. An image on any other buffer is in a separate+ // file, so hashing the binary chunk at that offset would report bytes that are not it.+ const wall = rebuilt(await texturedGlb([BASE_PNG]), (json) => {+ (json.buffers as Record<string, unknown>[]).push({ uri: 'wall.bin', byteLength: 8 });+ (json.bufferViews as Record<string, unknown>[])[+ (json.images as Record<string, number>[])[0]!.bufferView!+ ]!.buffer = 1;+ });++ const report = await textureSharingReport([{ name: 'wall.glb', bytes: wall }]);+ expect(report.assets).toBe(0);+ expect(report.distinctImages).toBe(0);+ expect(report.skipped).toEqual([+ { name: 'wall.glb', reason: 'Image buffer view is not in this GLB binary chunk' },+ ]);+});++test('shares an image two assets carry as a base64 data URI', async () => {+ // Kiln's exporter uses buffer views, but a GLB may carry an image inline as a data URI,+ // and those bytes duplicate across assets exactly the same way.+ const inline = (glb: Uint8Array) =>+ rebuilt(glb, (json) => {+ json.images = [{ uri: `data:image/png;base64,${Buffer.from(BASE_PNG).toString('base64')}` }];+ });+ const [wall, floor] = await Promise.all([texturedGlb([BASE_PNG]), texturedGlb([BASE_PNG])]);++ const report = await textureSharingReport([+ { name: 'wall.glb', bytes: inline(wall) },+ { name: 'floor.glb', bytes: inline(floor) },+ ]);+ expect(report.skipped).toEqual([]);+ expect(report.embeddedImages).toBe(2);+ expect(report.distinctImages).toBe(1);+ expect(report.duplicateImageBytes).toBe(BASE_PNG.length);+ expect(report.images[0]).toEqual({+ sha256: sha(BASE_PNG),+ bytes: BASE_PNG.length,+ mimeType: 'image/png',+ width: 2,+ height: 2,+ copies: 2,+ assets: ['floor.glb', 'wall.glb'],+ });+});diff --git a/src/texture-sharing.ts b/src/texture-sharing.tsnew file mode 100644index 00000000..8d55fb2d--- /dev/null+++ b/src/texture-sharing.ts@@ -0,0 +1,216 @@+/**+ * Cross-asset texture sharing report (#287).+ *+ * Every delivered GLB embeds its own copy of the textures it uses, so a pack built on a+ * shared material family ships that family once per asset. The duplication is entirely+ * *between* assets: measured over 160 assets in four real worlds, within-asset duplicate+ * images were 0 every time, because the exporter already dedupes images inside one+ * document. A per-asset export receipt therefore cannot see any of it, and this report is+ * scoped to a set of delivered assets instead.+ *+ * It reads only the delivered bytes and rewrites nothing, so canonical and runtime exports+ * stay byte-identical. Acting on it is `--textures external`, which writes each image once+ * as `textures/<sha256>.<ext>`; `--textures manifest` carries the same identities in the+ * sidecar for a host that shares them itself.+ */+import { imageDimensions, sha256Hex } from './runtime-textures';++/** One distinct image, and every asset in the set that embeds those exact bytes. */+export interface TextureSharingImageV1 {+ /** `sha256:<64 lowercase hexadecimal characters>` of the exact embedded bytes. */+ sha256: string;+ bytes: number;+ mimeType: string;+ /** Pixel size from the image header, absent when the header is not one it reads. */+ width?: number;+ height?: number;+ /** Embedded copies across the set; `1` means no asset shares it. */+ copies: number;+ /** Names of the assets embedding it, sorted. */+ assets: string[];+}++export interface TextureSharingReportV1 {+ version: 'kiln.texture-sharing.v1';+ /** Assets read, excluding `skipped`. */+ assets: number;+ /** Total delivered bytes of those assets. */+ assetBytes: number;+ /** Embedded image occurrences across the set. */+ embeddedImages: number;+ distinctImages: number;+ embeddedImageBytes: number;+ distinctImageBytes: number;+ /** `embeddedImageBytes - distinctImageBytes`: what sharing each image once would save. */+ duplicateImageBytes: number;+ /** Distinct images, largest saving first, then by hash. */+ images: TextureSharingImageV1[];+ /** Inputs that are not readable GLBs, each with the reason, so one bad file is not fatal. */+ skipped: { name: string; reason: string }[];+}++const object = (value: unknown): value is Record<string, unknown> =>+ typeof value === 'object' && value !== null;+const index = (value: unknown): number | undefined =>+ typeof value === 'number' && Number.isInteger(value) && value >= 0 ? value : undefined;++/** The JSON and binary chunks of a GLB, or a reason it is not one. */+function readGlb(bytes: Uint8Array): { json: Record<string, unknown>; binary?: Uint8Array } {+ if (bytes.byteLength < 20) throw new Error('Not a GLB: shorter than a GLB header');+ const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);+ if (view.getUint32(0, true) !== 0x46546c67) throw new Error('Not a GLB: bad magic');+ if (view.getUint32(4, true) !== 2) throw new Error('Not a GLB: unsupported version');+ if (view.getUint32(16, true) !== 0x4e4f534a)+ throw new Error('Not a GLB: first chunk is not JSON');+ const jsonEnd = 20 + view.getUint32(12, true);+ if (jsonEnd > bytes.byteLength) throw new Error('Invalid GLB chunk length');+ const json: unknown = JSON.parse(new TextDecoder().decode(bytes.subarray(20, jsonEnd)));+ if (!object(json)) throw new Error('Invalid glTF asset');+ if (jsonEnd + 8 > bytes.byteLength || view.getUint32(jsonEnd + 4, true) !== 0x004e4942)+ return { json };+ const length = view.getUint32(jsonEnd, true);+ if (jsonEnd + 8 + length > bytes.byteLength) throw new Error('Invalid GLB chunk length');+ return { json, binary: bytes.subarray(jsonEnd + 8, jsonEnd + 8 + length) };+}++const DATA_URI = /^data:([^;,]+);base64,(.*)$/s;++/**+ * Pixel size when the header is one Kiln reads. Byte identity is what sharing turns on, so+ * an image in some other format still counts; it just reports no size.+ */+function pixelSize(bytes: Uint8Array): { width?: number; height?: number } {+ try {+ return imageDimensions(bytes);+ } catch {+ return {};+ }+}++/**+ * The exact bytes of each image this GLB carries itself. An image referenced by a plain+ * URI is already shared with whatever hosts it, so it carries no duplication and is not+ * counted.+ */+function carriedImages(+ json: Record<string, unknown>,+ binary: Uint8Array | undefined,+): { bytes: Uint8Array; mimeType: string }[] {+ const views = Array.isArray(json.bufferViews) ? json.bufferViews : [];+ const carried: { bytes: Uint8Array; mimeType: string }[] = [];+ for (const image of Array.isArray(json.images) ? json.images : []) {+ if (!object(image)) throw new Error('Invalid glTF image');+ const view = index(image.bufferView);+ if (view !== undefined) {+ const def = views[view];+ if (!object(def)) throw new Error('Invalid glTF image buffer view');+ // Buffer 0 is the GLB's own binary chunk; any other buffer is a separate file, so+ // reading the chunk at that offset would report bytes that are not the image.+ if ((index(def.buffer) ?? 0) !== 0)+ throw new Error('Image buffer view is not in this GLB binary chunk');+ const offset = index(def.byteOffset) ?? 0;+ const length = index(def.byteLength);+ if (length === undefined || !binary || offset + length > binary.byteLength)+ throw new Error('Invalid glTF image buffer view');+ if (typeof image.mimeType !== 'string') throw new Error('Embedded image needs a mimeType');+ carried.push({ bytes: binary.subarray(offset, offset + length), mimeType: image.mimeType });+ continue;+ }+ const match = typeof image.uri === 'string' ? DATA_URI.exec(image.uri) : null;+ if (match)+ carried.push({+ bytes: Uint8Array.from(atob(match[2]!), (character) => character.charCodeAt(0)),+ mimeType: match[1]!,+ });+ }+ return carried;+}++/**+ * Group the images a set of delivered assets carries by their exact bytes.+ *+ * @example+ * const report = await textureSharingReport([+ * { name: 'palm.glb', bytes: palm },+ * { name: 'fern.glb', bytes: fern },+ * ]);+ * report.duplicateImageBytes; // bytes a shared leaf atlas would save across the pack+ */+export async function textureSharingReport(+ assets: readonly { name: string; bytes: Uint8Array }[],+): Promise<TextureSharingReportV1> {+ const distinct = new Map<+ string,+ {+ bytes: number;+ mimeType: string;+ width?: number;+ height?: number;+ copies: number;+ assets: Set<string>;+ }+ >();+ const skipped: { name: string; reason: string }[] = [];+ let read = 0;+ let assetBytes = 0;+ let embeddedImages = 0;+ let embeddedImageBytes = 0;+ for (const asset of assets) {+ let carried: { bytes: Uint8Array; mimeType: string }[];+ try {+ const { json, binary } = readGlb(asset.bytes);+ carried = carriedImages(json, binary);+ } catch (error) {+ skipped.push({ name: asset.name, reason: (error as Error).message });+ continue;+ }+ read += 1;+ assetBytes += asset.bytes.byteLength;+ for (const image of carried) {+ embeddedImages += 1;+ embeddedImageBytes += image.bytes.byteLength;+ const sha256 = `sha256:${await sha256Hex(image.bytes)}`;+ const entry = distinct.get(sha256);+ if (entry) {+ entry.copies += 1;+ entry.assets.add(asset.name);+ } else+ distinct.set(sha256, {+ bytes: image.bytes.byteLength,+ mimeType: image.mimeType,+ ...pixelSize(image.bytes),+ copies: 1,+ assets: new Set([asset.name]),+ });+ }+ }+ const distinctImageBytes = [...distinct.values()].reduce(+ (total, image) => total + image.bytes,+ 0,+ );+ const saving = (image: { bytes: number; copies: number }) => image.bytes * (image.copies - 1);+ return {+ version: 'kiln.texture-sharing.v1',+ assets: read,+ assetBytes,+ embeddedImages,+ distinctImages: distinct.size,+ embeddedImageBytes,+ distinctImageBytes,+ duplicateImageBytes: embeddedImageBytes - distinctImageBytes,+ images: [...distinct.entries()]+ .sort(+ ([sha, image], [otherSha, other]) =>+ saving(other) - saving(image) || (sha < otherSha ? -1 : sha > otherSha ? 1 : 0),+ )+ .map(([sha256, { bytes, mimeType, width, height, copies, assets: using }]) => ({+ sha256,+ bytes,+ mimeType,+ ...(width !== undefined ? { width, height } : {}),+ copies,+ assets: [...using].sort(),+ })),+ skipped,+ };+}