Skip to content

armgit / kiln

Public Imported from GitHub
0

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.

Report cross-asset texture duplication with kiln textures (#287) (#296)

Matthew Kissinger52003d3277f0
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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, so
diff --git a/dist/agent-run.mjs b/dist/agent-run.mjs
index 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.ts
var 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.json
index 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.mjs
index 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.ts
import { 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 sha256
export never replaces an existing file: an export hands off one exact
saved 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 nothing
kiln import <asset.zip|asset.glb> [--collection project] [--name <name>]
prints the directory of each imported revision
kiln 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.mjs
index 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.ts
function 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.md
index 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 o
Runtime GLBs embed every texture, so forty assets that use one library material carry
forty copies of its maps. Two opt-in choices let a host share them. Neither is the
default: 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 bin
byte 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 contract
The 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.md
index 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 manifest
node 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. The
manifest lists each image's exact `sha256`, size, colour space and, when its bytes equal
a saved library map, that material pin. External textures are named by the hash of their
diff --git a/src/asset-cli-texture-sharing.test.ts b/src/asset-cli-texture-sharing.test.ts
new file mode 100644
index 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.ts
index 10a6fa1a..c8daf701 100644
--- a/src/asset-cli.ts
+++ b/src/asset-cli.ts
@@ -25,6 +25,9 @@ import { CATEGORY_MIGRATION_MESSAGE, readHostRequirementsFile } from './requirem
import { 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 sha256
export never replaces an existing file: an export hands off one exact
saved 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 nothing
kiln import <asset.zip|asset.glb> [--collection project] [--name <name>]
prints the directory of each imported revision
kiln 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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,
+ };
+}