@driftengine/assets 4.6.1 → 4.7.1

package/dist/blendScene.js

@@ -0,0 +1,280 @@
+/**
+ * Which objects of a `.blend` are drawn, and where: the scene walk, in Blender's coordinates.
+ *
+ * **"Drawn" means what a render of the open scene shows**, the same rule `scripts/blender/
+ * export_gltf.py` applies before it hands the scene to Blender's exporter, so both routes into
+ * the engine agree on what an asset contains. An object is drawn when it is linked into the scene
+ * through at least one collection that is neither excluded from the view layer nor disabled for
+ * rendering, and is not itself hidden from renders. Parenting does not hide: a child of a hidden
+ * object is drawn where its parent would have put it, which is what Blender does.
+ *
+ * **A collection instance is expanded** into its objects, placed by the instancer and shifted by
+ * the collection's instance offset. Before 2.8 there were no collections, and the scene's bases and
+ * layer bits say the same thing.
+ *
+ * **What has to be evaluated is refused rather than guessed.** A constraint, a vertex parent or a
+ * particle instancer changes where things are by running Blender, so the walk names it in
+ * `refusals` and the caller declines the whole file. Animation does not refuse: Blender writes the
+ * evaluated value of every animated property back to the datablock, so a saved file holds the
+ * pose of the frame it was saved on.
+ */
+import { axisAngleMatrix, compose, eulerMatrix, multiply, multiply3, quaternionMatrix, translation, } from './blendMatrix.js';
+export const OB_EMPTY = 0;
+export const OB_MESH = 1;
+export const OB_LAMP = 10;
+export const OB_CAMERA = 11;
+export const OB_ARMATURE = 25;
+/** Object types that draw nothing and so need nothing evaluated: cameras, speakers, probes. */
+const INERT = new Set([OB_CAMERA, 12, 13, 22]);
+const NEEDS_EVALUATION = {
+    2: 'a curve',
+    3: 'a NURBS surface',
+    4: 'a text object',
+    5: 'a metaball',
+    26: 'a grease pencil object',
+    27: 'a hair curves object',
+    28: 'a point cloud',
+    29: 'a volume',
+    30: 'a grease pencil object',
+};
+const OB_HIDE_RENDER = 1 << 2;
+const COLLECTION_HIDE_RENDER = 1 << 3;
+const LAYER_COLLECTION_EXCLUDE = 1 << 4;
+const OB_DUPLICOLLECTION = 1 << 8;
+const OB_DUPLIVERTS = 1 << 4;
+const OB_DUPLIFACES = 1 << 9;
+const PARTYPE = 15;
+const PAROBJECT = 0;
+const PARSKEL = 4;
+const PARBONE = 7;
+/** The scene the file was saved looking at. */
+export function activeScene(blend) {
+    const glob = blend.idsOf('GLOB')[0];
+    const scene = glob?.has('curscene') === true ? glob.deref('curscene') : null;
+    return scene ?? blend.idsOf('SC')[0] ?? null;
+}
+/**
+ * The object's transform relative to its parent: location, rotation and scale, deltas folded in.
+ *
+ * `values`, where given, overrides what the file stores with what an animation says at a frame,
+ * keyed by Blender's data path and index — `location[0]`, `rotation_quaternion[3]` — which is what
+ * `Animation.values` fills (`blendAnimation.ts`).
+ */
+export function localMatrix(object, values) {
+    const read = (field, path, count, offset = 0) => {
+        const stored = object.has(field)
+            ? object.floats(field)
+            : new Array(count).fill(field.includes('size') || field.includes('scale') ? 1 : 0);
+        if (values === undefined)
+            return stored;
+        return stored.map((v, i) => values.get(`${path}[${i + offset}]`) ?? v);
+    };
+    const location = read('loc', 'location', 3);
+    const deltaLocation = read('dloc', 'delta_location', 3);
+    const scale = read('size', 'scale', 3);
+    const deltaScale = object.has('dscale')
+        ? read('dscale', 'delta_scale', 3)
+        : read('dsize', 'delta_scale', 3);
+    const mode = object.int('rotmode');
+    let rotation;
+    let delta;
+    if (mode === 0) {
+        rotation = quaternionMatrix(read('quat', 'rotation_quaternion', 4));
+        delta = quaternionMatrix(read('dquat', 'delta_rotation_quaternion', 4));
+    }
+    else if (mode === -1) {
+        /* Blender keys an axis-angle as four values, the angle first. */
+        const angle = values?.get('rotation_axis_angle[0]') ?? object.float('rotAngle');
+        rotation = axisAngleMatrix(read('rotAxis', 'rotation_axis_angle', 3, 1), angle);
+        delta = axisAngleMatrix(object.floats('drotAxis'), object.float('drotAngle'));
+    }
+    else {
+        rotation = eulerMatrix(read('rot', 'rotation_euler', 3), mode);
+        delta = eulerMatrix(read('drot', 'delta_rotation_euler', 3), mode);
+    }
+    return compose([0, 1, 2].map((i) => location[i] + deltaLocation[i]), multiply3(delta, rotation), [0, 1, 2].map((i) => scale[i] * deltaScale[i]));
+}
+/** Walk the scene into placed objects, naming in `refusals` anything that needs Blender to run. */
+export function placeObjects(blend, refusals, bonePose) {
+    const scene = activeScene(blend);
+    if (scene === null) {
+        refusals.push('the file has no scene');
+        return [];
+    }
+    const worlds = new Map();
+    const world = (object, depth = 0) => {
+        const cached = worlds.get(object.offset);
+        if (cached !== undefined)
+            return cached;
+        let matrix = localMatrix(object);
+        const parent = depth < 64 ? object.deref('parent') : null;
+        if (parent !== null) {
+            const type = object.int('partype') & PARTYPE;
+            let base = world(parent, depth + 1);
+            if (type === PARBONE) {
+                const pose = bonePose(parent, object.string('parsubstr'));
+                if (pose === null)
+                    refusals.push(`"${object.idName()}" is parented to a bone that is not there`);
+                else
+                    base = multiply(base, pose);
+            }
+            else if (type !== PAROBJECT && type !== PARSKEL) {
+                refusals.push(`"${object.idName()}" is parented to vertices, which Blender evaluates`);
+            }
+            matrix = multiply(base, multiply(object.floats('parentinv'), matrix));
+        }
+        if (object.list('constraints').length > 0) {
+            refusals.push(`"${object.idName()}" has constraints, which Blender evaluates`);
+        }
+        worlds.set(object.offset, matrix);
+        return matrix;
+    };
+    const placed = [];
+    const index = new Map();
+    const place = (object, outer, holder, depth) => {
+        const kind = object.int('type');
+        if (INERT.has(kind))
+            return;
+        const reason = NEEDS_EVALUATION[kind];
+        if (reason !== undefined)
+            refusals.push(`"${object.idName()}" is ${reason}, which Blender evaluates`);
+        if (object.list('particlesystem').length > 0) {
+            refusals.push(`"${object.idName()}" has a particle system, which Blender evaluates`);
+        }
+        const transflag = object.int('transflag');
+        if (transflag & (OB_DUPLIVERTS | OB_DUPLIFACES)) {
+            refusals.push(`"${object.idName()}" instances onto its vertices or faces, which Blender evaluates`);
+        }
+        const own = world(object);
+        const matrix = outer === null ? own : multiply(outer, own);
+        let parent = holder;
+        for (let up = object.deref('parent'), hops = 0; up !== null && hops < 64; hops++) {
+            const found = outer === null ? index.get(up.offset) : undefined;
+            if (found !== undefined) {
+                parent = found;
+                break;
+            }
+            up = up.deref('parent');
+        }
+        /*
+         * An instancer carries its collection's offset in its own matrix, so its members sit at their
+         * own world matrices beneath it. Blender's exporter writes the instancer the same way, which
+         * keeps the two node trees comparable; the empty draws nothing, so nothing moves on screen.
+         */
+        const collection = transflag & OB_DUPLICOLLECTION ? object.deref('dup_group') : null;
+        const offset = collection?.floats('dupli_ofs') ?? [0, 0, 0];
+        const held = collection === null
+            ? matrix
+            : multiply(matrix, translation(-offset[0], -offset[1], -offset[2]));
+        const at = placed.length;
+        placed.push({ object, name: object.idName(), kind, world: held, parent });
+        if (outer === null)
+            index.set(object.offset, at);
+        if (collection !== null && depth < 16) {
+            for (const member of collectionObjects(collection, true))
+                place(member, held, at, depth + 1);
+        }
+    };
+    const roots = sceneObjects(scene, blend);
+    /* Parents first, so a child finds its parent's index already assigned. */
+    const order = [...roots].sort((a, b) => depthOf(a) - depthOf(b));
+    for (const object of order)
+        place(object, null, -1, 0);
+    return placed;
+}
+function depthOf(object) {
+    let depth = 0;
+    for (let up = object.deref('parent'); up !== null && depth < 64; up = up.deref('parent'))
+        depth++;
+    return depth;
+}
+/** The objects a collection holds directly and through its children, those that render. */
+function collectionObjects(collection, nested) {
+    const out = [];
+    const seen = new Set();
+    const visit = (current, depth) => {
+        for (const link of current.list('gobject')) {
+            const object = link.deref('ob');
+            if (object === null || seen.has(object.offset))
+                continue;
+            seen.add(object.offset);
+            if ((object.int('restrictflag') & OB_HIDE_RENDER) === 0)
+                out.push(object);
+        }
+        if (!nested || depth > 32)
+            return;
+        for (const child of current.list('children')) {
+            const inner = child.deref('collection');
+            if (inner !== null && (inner.int('flag') & COLLECTION_HIDE_RENDER) === 0)
+                visit(inner, depth + 1);
+        }
+    };
+    visit(collection, 0);
+    return out;
+}
+/** Every object the scene renders, once each. */
+function sceneObjects(scene, blend) {
+    if (!scene.has('master_collection')) {
+        /* Before 2.8: bases on the scene, drawn when one of their layers is a visible scene layer. */
+        const layers = scene.int('lay');
+        return scene
+            .list('base')
+            .filter((base) => (base.int('lay') & layers) !== 0)
+            .map((base) => base.deref('object'))
+            .filter((object) => object !== null)
+            .filter((object) => (object.int('restrictflag') & OB_HIDE_RENDER) === 0);
+    }
+    const master = scene.deref('master_collection');
+    if (master === null)
+        return [];
+    const glob = blend.idsOf('GLOB')[0];
+    const layers = scene.list('view_layers');
+    const active = glob?.has('cur_view_layer') === true
+        ? layers.find((layer) => layer.offset === glob.deref('cur_view_layer')?.offset)
+        : undefined;
+    const layer = active ?? layers[0];
+    const top = layer?.list('layer_collections')[0];
+    const out = [];
+    const seen = new Set();
+    const take = (collection) => {
+        for (const link of collection.list('gobject')) {
+            const object = link.deref('ob');
+            if (object === null || seen.has(object.offset))
+                continue;
+            if ((object.int('restrictflag') & OB_HIDE_RENDER) !== 0)
+                continue;
+            seen.add(object.offset);
+            out.push(object);
+        }
+    };
+    /*
+     * Walk the layer collections where the view layer has them, since exclusion lives there; walk the
+     * collections themselves where it does not, which is a file written without a synchronised view
+     * layer and has nothing excluded.
+     */
+    const walkLayer = (lc, depth) => {
+        if (depth > 64 || (lc.int('flag') & LAYER_COLLECTION_EXCLUDE) !== 0)
+            return;
+        const collection = lc.deref('collection');
+        if (collection === null || (collection.int('flag') & COLLECTION_HIDE_RENDER) !== 0)
+            return;
+        take(collection);
+        for (const child of lc.list('layer_collections'))
+            walkLayer(child, depth + 1);
+    };
+    const walkCollection = (collection, depth) => {
+        if (depth > 64 || (collection.int('flag') & COLLECTION_HIDE_RENDER) !== 0)
+            return;
+        take(collection);
+        for (const child of collection.list('children')) {
+            const inner = child.deref('collection');
+            if (inner !== null)
+                walkCollection(inner, depth + 1);
+        }
+    };
+    if (top !== undefined)
+        walkLayer(top, 0);
+    else
+        walkCollection(master, 0);
+    return out;
+}

package/dist/gltf.js

@@ -455,8 +455,14 @@ function materialOf(material) {
         cutout: masked ? Math.min(1, Math.max(0, material?.alphaCutoff ?? 0.5)) : 0,
         /* Metalness is glTF's statement about reflection: a metal mirrors its surroundings and
            a dielectric mostly does not. It also feeds `specular`, which is not double counting,
-           because the two describe different halves of the same fact. */
-        reflectivity: Math.min(1, Math.max(0, modulated ? 0 : (pbr?.metallicFactor ?? 0))),
+           because the two describe different halves of the same fact.
+    
+           **An absent factor is 1 here as it is everywhere else in glTF**, with the decal guard
+           `highlight` applies above: an image-coloured surface naming no metallic stays a dielectric.
+           It read 0 for every surface until a Blender export showed it, because Blender writes no
+           `metallicFactor` for a metal — 1 is the default — so every untextured metal it exported
+           arrived taking a highlight and mirroring nothing. */
+        reflectivity: Math.min(1, Math.max(0, modulated ? 0 : pbr?.baseColorTexture === undefined ? metallic : (pbr?.metallicFactor ?? 0))),
         normalMap: material?.normalTexture?.index ?? -1,
         ormMap,
         emissiveMap: material?.emissiveTexture?.index ?? -1,

package/dist/index.d.ts

@@ -48,6 +48,27 @@ export type { Recognised } from './recognise.ts';
 export { fbxToMeshes } from './fbx.ts';
 export type { Inflate } from './fbx.ts';
 export { readModel, readerFor, extensionOf, MODEL_FORMATS } from './readModel.ts';
+export { BlendNeedsBlender, openBlend, readBlend } from './blend.ts';
+export { BlendData, BlendStruct } from './blendData.ts';
+export { blendToGltf, blackbody, imageMime, imagePath, materialSlots, packedImage, } from './blendGltf.ts';
+export type { BlendGltf } from './blendGltf.ts';
+export { placeObjects, localMatrix, activeScene, OB_ARMATURE, OB_EMPTY, OB_LAMP, OB_MESH, } from './blendScene.ts';
+export type { BlendPlaced } from './blendScene.ts';
+export { readBlendMesh } from './blendMesh.ts';
+export type { BlendMeshData, BlendColorLayer } from './blendMesh.ts';
+export { cornerNormals, faceNormals } from './blendNormals.ts';
+export { meshPrimitives, triangulateFace } from './blendGeometry.ts';
+export type { BlendPrimitive, SlotNeeds } from './blendGeometry.ts';
+export { readBlendSurface, customProperties } from './blendMaterial.ts';
+export type { BlendSurface, ChannelSource } from './blendMaterial.ts';
+export { judgeModifiers } from './blendModifiers.ts';
+export { Animation, actionCurves, readCurve } from './blendAnimation.ts';
+export type { Curve } from './blendAnimation.ts';
+export type { ModifierVerdict } from './blendModifiers.ts';
+export { blendCompression, isBlend } from './blendFile.ts';
+export type { BlendBlock, BlendHeader, DnaField, DnaStruct } from './blendFile.ts';
+export { unpackBlend, zstdFrames } from './blendPacked.ts';
+export type { BlendDecompress } from './blendPacked.ts';
 export type { ModelSource, ModelImport } from './readModel.ts';
 export { browserInflate, browserInflateRaw, prepareFbxInflate, prepareZipInflate, } from './fbxInflate.ts';
 export type { AsyncInflate } from './fbxInflate.ts';

package/dist/index.js

@@ -72,6 +72,23 @@ export { fbxToMeshes } from './fbx.js';
  * decompressors and the resolution of a name a file states are all the caller's to supply.
  */
 export { readModel, readerFor, extensionOf, MODEL_FORMATS } from './readModel.js';
+/*
+ * Blender's own format, read directly. `readModel` takes a `.blend` like any other model; the rest
+ * is for a bake that keeps a scene's structure — its instancing, its materials' channels — rather
+ * than flattening it into world-space meshes.
+ */
+export { BlendNeedsBlender, openBlend, readBlend } from './blend.js';
+export { BlendData, BlendStruct } from './blendData.js';
+export { blendToGltf, blackbody, imageMime, imagePath, materialSlots, packedImage, } from './blendGltf.js';
+export { placeObjects, localMatrix, activeScene, OB_ARMATURE, OB_EMPTY, OB_LAMP, OB_MESH, } from './blendScene.js';
+export { readBlendMesh } from './blendMesh.js';
+export { cornerNormals, faceNormals } from './blendNormals.js';
+export { meshPrimitives, triangulateFace } from './blendGeometry.js';
+export { readBlendSurface, customProperties } from './blendMaterial.js';
+export { judgeModifiers } from './blendModifiers.js';
+export { Animation, actionCurves, readCurve } from './blendAnimation.js';
+export { blendCompression, isBlend } from './blendFile.js';
+export { unpackBlend, zstdFrames } from './blendPacked.js';
 /*
  * The browser's decompressor, and the two-pass trick that makes an async one usable by a
  * synchronous parser. `DecompressionStream` is all a page has and it only works as a stream, so

package/dist/readModel.d.ts

@@ -25,6 +25,7 @@ import type { AnimationClip, DrftLight, DrftMaterial, DrftNode, DrftSkin } from
 import type { AssetReference } from './assetPath.ts';
 import type { Handedness, UpAxis } from './orient.ts';
 import type { Inflate } from './fbx.ts';
+import type { BlendDecompress } from './blendPacked.ts';
 /**
  * Every extension this project reads, in the order a bundle should be picked from.
  *
@@ -65,6 +66,8 @@ export interface ModelSource {
     readonly inflate?: Inflate;
     /** Raw deflate inflate, for the zip inside a `.3mf`. Not the same function as `inflate`. */
     readonly inflateRaw?: Inflate;
+    /** gzip and zstd, for a `.blend` saved compressed. See `blendPacked.ts`. */
+    readonly decompress?: BlendDecompress;
     /**
      * Derive a tangent frame where a material declares a normal map and the file supplies none.
      *
@@ -128,6 +131,14 @@ export interface ModelImport {
     lights?: readonly DrftLight[];
     /** Which way round the source's coordinate system was. `orient.ts` is what acts on it. */
     declaredHand?: Handedness;
+    /**
+     * Where the reader knows its result differs from what the authoring tool would export: a node
+     * graph glTF cannot hold, animation it does not read. Drawn anyway, and named.
+     *
+     * Absent for every format but `.blend`, whose authoring tool can be asked instead: the baker
+     * reads a non-empty list as the reason to hand the file to Blender when Blender is there.
+     */
+    approximations?: readonly string[];
 }
 /**
  * Read one model file into meshes.
@@ -138,6 +149,8 @@ export interface ModelImport {
  * whole call in a worker and keep the parse off the main thread.
  */
 export declare function readModel(source: ModelSource): Promise<ModelImport>;
+/** The separate levels of detail a bundle ships beside its model, finest first. */
+export declare function levelsBeside(model: string, names: readonly string[]): string[];
 /**
  * The collision hull a vehicle folder ships beside its model, or null.
  *
@@ -151,5 +164,4 @@ export declare function readModel(source: ModelSource): Promise<ModelImport>;
  * reader and no writer — a format decision about whether a hull is triangle soup or a set of
  * convex hulls, and not one an import should make in passing.
  */
-export declare function levelsBeside(model: string, names: readonly string[]): string[];
 export declare function colliderBeside(names: readonly string[]): string | null;

package/dist/readModel.js

@@ -31,6 +31,7 @@ import { parseUsda, usdzToMeshes } from './usd.js';
 import { threeMfToMeshes } from './threemf.js';
 import { kn5ToMeshes, toDrftNodes } from './kn5.js';
 import { describeRecognised, recognise } from './recognise.js';
+import { readBlend } from './blend.js';
 /**
  * Every extension this project reads, in the order a bundle should be picked from.
  *
@@ -49,6 +50,11 @@ export const MODEL_FORMATS = [
     { ext: '.3mf', tier: 1, note: '3MF, geometry and colour, with no UVs in the core format' },
     { ext: '.fbx', tier: 2, note: 'FBX, experimental reader, geometry, materials, skins and clips' },
     { ext: '.kn5', tier: 2, note: 'experimental reader, geometry, materials and hierarchy' },
+    {
+        ext: '.blend',
+        tier: 2,
+        note: 'Blender, read directly; modifiers, rigs and constraints are refused and baked through Blender',
+    },
 ];
 /** Whether this project has a reader for an extension. Lower case or not. */
 export function readerFor(ext) {
@@ -305,6 +311,29 @@ async function dispatch(source) {
             unitScale: result.unitScale,
         };
     }
+    if (ext === '.blend') {
+        /*
+         * Read into a glTF document and through the glTF reader, so a `.blend` and Blender's export of
+         * it share every step after the document. A file needing evaluation throws
+         * `BlendNeedsBlender`, which the baker answers by asking Blender.
+         */
+        const result = await readBlend(bytes, source.decompress);
+        const parts = [result.binary];
+        const read = gltfToMeshes(result.doc, parts, options);
+        const said = [...result.approximations, ...result.warnings];
+        const shown = said.slice(0, 8);
+        return complete({
+            ...read,
+            ...readGltfSkins(result.doc, parts),
+            warnings: [
+                ...read.warnings,
+                ...shown,
+                ...(said.length > shown.length ? [`…and ${said.length - shown.length} more`] : []),
+                'blend: direct reader (tier 2), not covered by the compatibility promise.',
+            ],
+            approximations: result.approximations,
+        }, result.notes);
+    }
     if (ext === '.kn5') {
         /*
          * No capability of any kind: a `.kn5` embeds every texture it uses, so this is the one binary
@@ -354,19 +383,7 @@ function base64Bytes(base64) {
         out[i] = binary.charCodeAt(i);
     return out;
 }
-/**
- * The collision hull a vehicle folder ships beside its model, or null.
- *
- * **A convention, not a statement in any file**, which is why it is one named function instead of
- * a rule spread through the baker: a folder naming its hull differently gets no collider and the
- * baker says what it looked for, rather than leaving a consumer to wonder why physics has nothing
- * to work with.
- *
- * It is read by the ordinary reader and baked as its own asset. Carrying a hull *inside* the
- * model's own file would mean defining `COLL`, which is a declared FourCC with no payload, no
- * reader and no writer — a format decision about whether a hull is triangle soup or a set of
- * convex hulls, and not one an import should make in passing.
- */
+/** The separate levels of detail a bundle ships beside its model, finest first. */
 export function levelsBeside(model, names) {
     /*
      * `<name>_lod_<letter>.kn5` beside `<name>.kn5`, finest first, which is the order the letters
@@ -381,6 +398,19 @@ export function levelsBeside(model, names) {
         .sort((a, b) => a.match[1].toLowerCase().localeCompare(b.match[1].toLowerCase()))
         .map((entry) => entry.name);
 }
+/**
+ * The collision hull a vehicle folder ships beside its model, or null.
+ *
+ * **A convention, not a statement in any file**, which is why it is one named function instead of
+ * a rule spread through the baker: a folder naming its hull differently gets no collider and the
+ * baker says what it looked for, rather than leaving a consumer to wonder why physics has nothing
+ * to work with.
+ *
+ * It is read by the ordinary reader and baked as its own asset. Carrying a hull *inside* the
+ * model's own file would mean defining `COLL`, which is a declared FourCC with no payload, no
+ * reader and no writer — a format decision about whether a hull is triangle soup or a set of
+ * convex hulls, and not one an import should make in passing.
+ */
 export function colliderBeside(names) {
     return names.find((name) => name.toLowerCase() === 'collider.kn5') ?? null;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/assets",
-  "version": "4.6.1",
+  "version": "4.7.1",
   "description": "Model readers and the streaming loader for the .drft container",
   "license": "Apache-2.0",
   "type": "module",
@@ -27,11 +27,11 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@driftengine/drft": "4.6.1",
-    "@driftengine/texture": "4.6.1"
+    "@driftengine/drft": "4.7.1",
+    "@driftengine/texture": "4.7.1"
   },
   "peerDependencies": {
-    "@driftengine/core": "4.6.1"
+    "@driftengine/core": "4.7.1"
   },
   "author": "Drift Technologies",
   "repository": {

package/src/blend.ts

@@ -0,0 +1,57 @@
+/**
+ * Reading a `.blend` directly: Blender's own file, with no Blender installed.
+ *
+ * The route is container → catalogue → scene → glTF document → the glTF reader, each step in its
+ * own module, and this one only chains them and decides what a refusal looks like. See
+ * `blendGltf.ts` for why the document in the middle is glTF.
+ *
+ * **A refusal is an error with its reasons attached**, `BlendNeedsBlender`, because the caller
+ * that can act on it — the baker, with Blender on the machine — needs the list rather than a
+ * sentence to parse: it hands the file to Blender and says why. A browser has no Blender, and shows
+ * the message.
+ */
+
+import { DrftError } from '@driftengine/drft';
+import { BlendData } from './blendData.ts';
+import { blendToGltf } from './blendGltf.ts';
+import type { BlendGltf } from './blendGltf.ts';
+import { unpackBlend } from './blendPacked.ts';
+import type { BlendDecompress } from './blendPacked.ts';
+
+/** Thrown when a `.blend` holds something only Blender can evaluate, with each thing named. */
+export class BlendNeedsBlender extends DrftError {
+  readonly reasons: readonly string[];
+
+  constructor(reasons: readonly string[]) {
+    const shown = reasons
+      .slice(0, 6)
+      .map((reason) => `  ${reason}`)
+      .join('\n');
+    const more = reasons.length > 6 ? `\n  …and ${reasons.length - 6} more` : '';
+    super(
+      `blend: this file needs Blender to evaluate it, and the direct reader draws nothing rather than ` +
+        `the wrong shape:\n${shown}${more}\nBake it with \`npm run bake\` on a machine with Blender ` +
+        'installed, which hands it to Blender, or apply these in Blender and save again.',
+    );
+    this.name = 'BlendNeedsBlender';
+    this.reasons = reasons;
+  }
+}
+
+/** Open a `.blend`'s bytes, decompressing them first where the file was saved compressed. */
+export async function openBlend(
+  bytes: Uint8Array,
+  decompress?: BlendDecompress,
+): Promise<BlendData> {
+  return new BlendData(await unpackBlend(bytes, decompress));
+}
+
+/** A `.blend` as a glTF document, refusing it whole when any part of it needs evaluating. */
+export async function readBlend(
+  bytes: Uint8Array,
+  decompress?: BlendDecompress,
+): Promise<BlendGltf> {
+  const result = blendToGltf(await openBlend(bytes, decompress));
+  if (result.refusals.length > 0) throw new BlendNeedsBlender(result.refusals);
+  return result;
+}