@instruktlabs/kiln 1.2.2 → 1.2.3

package/dist/viewer/style.css

@@ -49,3 +49,13 @@ main{grid-template-columns:216px minmax(0,1fr);min-height:calc(100vh - 80px)}
 @media(max-width:800px){header{height:70px;padding:0 18px}main{display:block}.workspace-sidebar{height:auto;position:static;padding:12px 15px}#workspace-nav{display:flex;gap:5px}#workspace-nav button{white-space:nowrap;font-size:12px;flex:1;justify-content:center;padding:11px 7px}#workspace-nav button span{display:none}#collections{padding-top:6px}#collections:empty{padding:0}.workspace-panel{padding:25px 18px}.workspace-panel h1{font-size:31px}.project-layout{grid-template-columns:1fr;margin-top:23px}.project-list{display:flex;overflow:auto}.project-list button{min-width:180px}.review-layout{grid-template-columns:1fr}.timeline{display:flex;max-height:190px}.timeline-item{min-width:220px;max-width:260px}.timeline .empty{padding:18px}.panel-title{padding:12px 17px}.profile-grid{grid-template-columns:1fr}.review-viewports.comparing{grid-template-columns:1fr}.heading{gap:15px}.heading>button{font-size:12px;white-space:nowrap}.live-toolbar{align-items:flex-start}.live-toolbar .inline-field{flex-direction:column;align-items:flex-start}.local-dot{display:none}.live-stage{height:380px}}
 /* Manual LOD review: whole-asset shortcuts plus independent part choices. */
 .lod-controls{margin:12px 0;font-size:12px}.lod-total{margin:8px 0;color:var(--ink)}.lod-parts{padding:10px 12px;border:1px solid var(--line);border-radius:8px}.lod-parts summary{cursor:pointer;font-weight:600}.lod-parts .subtle{line-height:1.5}.lod-part-fields{display:grid;gap:10px;max-height:280px;overflow:auto;padding:4px 2px}.lod-part-fields .inline-field{justify-content:space-between;flex-wrap:wrap}.lod-part-fields select{max-width:100%}.comparison-lod{padding:12px 16px}.comparison-lod:has(.inline-field[hidden]){display:none}
+.material-card[data-selected-material="true"]{border-color:var(--accent)}
+.material-map{object-fit:contain;image-rendering:pixelated}
+.material-map-inspection{margin:14px 0}.material-inspection{min-width:0;overflow-wrap:anywhere}
+.material-inspection-controls{display:flex;gap:10px;flex-wrap:wrap;margin:14px 0}.material-inspection-controls .inline-field{flex-direction:column;align-items:flex-start}.material-inspection-controls select{max-width:100%;font-size:11px;padding:7px}
+.material-pixel-frame{max-height:360px;overflow:auto;border:1px solid var(--line);border-radius:5px;background:#202020}
+.material-pixel-frame[data-backdrop="checker"]{background-color:#d0d0d0;background-image:conic-gradient(#7a7a7a 25%,#d0d0d0 0 50%,#7a7a7a 0 75%,#d0d0d0 0);background-size:16px 16px}
+.material-pixel-frame[data-backdrop="light"]{background:#f2f2f2}.material-pixel-frame[data-backdrop="dark"]{background:#151515}
+.material-pixel-sheet{position:relative;flex:none;min-width:0}.material-pixel-image{display:block!important;width:100%!important;height:100%!important;max-height:none!important;object-fit:fill!important;image-rendering:pixelated;border-radius:0!important}
+.material-region-overlay{position:absolute;inset:0;pointer-events:none}.material-region-box{position:absolute;border:1px solid #ffce37;overflow:visible}.material-region-box>span{position:absolute;left:0;top:0;font-size:10px;line-height:1.2;background:#151515df;color:#ffefaf;white-space:nowrap;max-width:200px;overflow:hidden;text-overflow:ellipsis}.material-region-box.selected{border:2px solid #fff;box-shadow:0 0 0 2px #111}.material-region-list{display:grid;gap:6px;margin:12px 0}.material-region-list h4{font-size:11px;margin:5px 0}.material-region-list button{text-align:left;font-size:10px;padding:7px;overflow-wrap:anywhere}.material-region-list button[aria-pressed="true"]{border-color:var(--accent)}
+.material-inspection dl{font-size:11px}.material-inspection dt{color:var(--dim);margin-top:7px}.material-inspection dd{margin:0}.live-material-inspection{grid-column:1/-1}.live-material-inspection details{margin-top:12px}.asset-material-inputs{font-size:11px;margin:15px 0}.asset-material-inputs h3{font-size:12px}.asset-material-inputs a{color:var(--accent)}

package/docs/atlas-provenance.md

@@ -0,0 +1,23 @@
+# Atlas provenance in delivered GLBs
+
+`src/atlas-provenance.ts` is the internal owner of atlas metadata validation. It uses the existing atlas canonicalizer and manifest validator. It has no Node dependency and its live-scene readers are available to image-free structural QA. These internal helpers are not SDK authoring APIs.
+
+The default glTF scene owns `extras.kilnAtlasProvenance`:
+
+```json
+{"version":"kiln.atlas-provenance.v1","atlases":[{"id":"sha256:<manifest hash>","spec":{},"manifest":{}}]}
+```
+
+Each entry contains one complete canonical recipe and validated manifest. Entries deduplicate by exact manifest identity, with a content conflict check. Recipes are never repeated per mesh. Editable source and saved material records remain the authoring owners.
+
+Each material-slot `TextureInfo` owns `extras.kilnAtlasReference` with `version`, `id`, `effectiveSampler` (`minFilter`, `magFilter`, `wrapS`, `wrapT` as glTF values), `finalMime`, and `finalImageSha256`. Source collection creates only the version/id pair; final export fills actual sampler and encoded-image identities. The reference belongs to a texture use because one image can serve multiple samplers. glTF Transform preserves TextureInfo extras and does not preserve extras on glTF texture binding objects. Image extras would incorrectly conflate those uses.
+
+A primitive using a named remap owns `extras.kilnAtlasBinding`: `version`, `atlasId`, `region`, `inputOrigin`, and `mode`. Export checks the complete source geometry stamp against the primary atlas, including hashes, rectangles, scale and offset. Reimport derives that full geometry stamp from the validated manifest and compact binding. A geometry-wide binding requires its exact primary atlas among the primitive material slots. Companion color/data maps may have different manifest hashes with the same region layout. Manual full-sheet atlas use carries texture references without an inferred named binding. Ordinary textures carry no atlas metadata.
+
+Admission allows 128 unique identities, at most 256 KiB per JSON entry, a 4 MiB aggregate table including its envelope/separators, and 1,024 source binding observations. Exported documents independently bound slot references and primitive bindings to 1,024 each. Source graph admission precedes manifest cloning and scene export copies. Distinct atlas texture objects conservatively charge their full RGBA output toward a 64 MiB bake decoded-pixel budget. Encoded-image hashing admits at most 16 MiB per image and 64 MiB in aggregate before hashing. These are metadata/buffer-work bounds, not an operating-system or native codec RSS guarantee. Existing scene traversal remains proportional to the scene.
+
+Before first PNG encoding, baking verifies raw RGBA dimensions and SHA-256 against the compiled manifest. Already encoded source maps receive bounded PNG dimension/decode verification. Editing pixels while retaining an atlas stamp fails with a stale-provenance diagnostic. A validated GLB loader establishes a private WeakMap identity for exporter-derived delivery bytes; authored flags cannot establish this identity. Re-export checks those exact bytes against the validated delivery reference rather than comparing legitimate converted normal pixels to the original compiler pixels. The source recipe/pixel identity and final encoded-image identity remain separate. No GLB contains its own final artifact hash; that hash remains in external baked provenance.
+
+Both exporters write the same table, references and compact bindings. The optimizer validates input lineage and refreshes the final image identities after its transforms. Composition admits and merges the tables before copying source graphs and deleting their scenes. Import validates final bytes and samplers, never repairs a tampered reference. External transforms that rewrite images must update delivery references through the validated engine export path; retaining old image hashes makes the transformed artifact fail import validation.
+
+Structural metadata proves identities, named selectors and remap formulas. It does not prove an author's intended corner orientation after arbitrary within-domain UV edits, visual quality, or inferred physical density. Generic author `kiln*` userData remains excluded; only this owner's validated engine metadata is explicitly promoted.

package/docs/community-exporter.md

@@ -57,6 +57,28 @@ partitions are rejected by the shared preflight. Private `userData` is excluded;
 semantic extras and bounded review clips retain their existing policy. Export copies keep caller
 texture sources and skeleton references intact.
 
+Both converters preserve standard magnification/minification filters and S/T wrap
+modes on supported texture bindings, including different samplers sharing image
+bytes. Kiln's loader and procedural texture defaults remain repeat wrapping,
+linear magnification and trilinear minification. The default converter now writes
+these choices explicitly; regenerated GLBs can therefore have different bytes
+and material fingerprints from older exports. Existing saved revisions are
+unchanged. Mipmap generation itself is a consumer policy, not a glTF sampler flag.
+
+Already encoded PNG/JPEG images on direct, unflipped texture bindings retain their
+original bytes. This matters for cutout RGB padding under zero alpha and for exact
+partial-alpha color: canvas conversion can erase or round those channels. Derived
+channel maps and explicitly flipped images still require conversion. Raw byte maps
+used for metallic/roughness packing or normal-channel inversion are adapted on the
+export copy; caller images and texture references remain unchanged. For cutout atlas
+delivery, keep the canonical image orientation with `flipY: false`; pixel-exact
+transparent RGB through a requested vertical image flip is not qualified.
+
+If the optional native canvas binding cannot load, textured headless export reports
+the dependency and recovery steps. Reinstall with optional dependencies enabled and
+check the binding in the same Node runtime and platform as the Kiln host. It does not
+silently switch converters. Flat-material exports do not require that binding.
+
 This describes serialization capability. It does not automatically extend all authoring helpers,
 QA rules, preview materials or optimization algorithms. In particular, skin/morph deformation,
 complex texture transforms, material extensions in every review path, and runtime codec support
@@ -65,6 +87,11 @@ converter rather than bypassing the triangle pipeline's metadata and geometry po
 
 ## Qualify a consumer
 
+Both converters reject used `BackSide` materials because glTF has no back-only
+material flag. See the [portable sidedness contract](export-profiles.md#material-sidedness-at-export)
+for explicit inward geometry and deliberate two-sided sheets. This prevents silent
+front-face substitution; it does not change the default exporter or existing GLBs.
+
 Keep a canonical GLB and name the actual engine, importer, version and render pipeline in results.
 For example, Unity 6 Built-in RP with glTFast is a different target from Unity URP or an FBX workflow.
 Tests should check hierarchy, world-space positions, part names, material assignments, texture pixels,

package/docs/export-profiles.md

@@ -44,6 +44,26 @@ unsupported UV transforms and destination feature support still need qualificati
 Neither setting automatically enables mesh merging, geometry simplification, Draco,
 Meshopt or KTX2 compression. Those require separate choices and validation.
 
+## Material sidedness at export
+
+glTF represents front-only or double-sided surfaces. Both Kiln converters preserve
+`FrontSide` and `DoubleSide`. A used `BackSide` material now stops a source build
+with `EXPORT_MATERIAL_SIDE_UNSUPPORTED`. The direct scene API names the part and
+material; CLI/MCP carry closed repair advice without authored identifiers across
+the evaluator boundary. Use `kiln_source` with query `BackSide` to locate the
+authored material. This applies
+in both `warn` and `strict` geometry modes and before texture baking or conversion;
+unused material-array slots do not block export. Existing saved GLBs remain readable
+and exporting their exact bytes does not rebuild them.
+
+For a one-sided interior surface, author triangles facing inward and use
+`FrontSide`. For a leaf or other deliberate sheet visible from either side, use
+`DoubleSide`. Neither choice supplies thickness or missing caps. Do not flip only
+normals to repair winding. Automatic back-only conversion is not provided: winding,
+normal/tangent basis, groups, shared geometry and deformation data must remain
+consistent. A destination shader override is an explicit runtime choice, separate
+from the portable asset.
+
 ## CLI
 
 From an asset workspace, using the IDs returned by `save` or `assets`:

package/docs/material-library.md

@@ -35,8 +35,9 @@ node kiln.mjs material get RETURNED_MATERIAL_ID RETURNED_REVISION
 node kiln.mjs material export RETURNED_MATERIAL_ID RETURNED_REVISION --out wood-payload.json
 ```
 
-Copy the returned `portableSpec` into authored source and use
-`compilePortableMaterialSpecV2(portableSpec)` with the exact dependency pin.
+Copy the returned `portableSpec` into authored source with the exact dependency
+pin. Use `compilePortableMaterialSpecV2` for `portableSpec.schemaVersion === 2`
+and `compilePortableMaterialSpecV3` for version 3. Existing presets return V2.
 Custom draft creation uses CLI `material procedural --file draft.json`, corresponding
 to MCP `create-procedural`. These paths need no imports from internal `dist/` files
 or extra TypeScript loader. The public host APIs below are for a configured TypeScript
@@ -44,7 +45,10 @@ toolchain; ordinary Node cannot directly execute TypeScript inside `node_modules
 
 `list` returns compact summaries and accepts a `tag`. `get` requires `materialId` and `revisionId`
 and returns provenance plus a code-ready `portableSpec`. `create-procedural` accepts an editable
-draft using the same bounded layer recipes as the existing procedural compiler. An optional
+draft using the same bounded layer recipes as the existing procedural compiler. Opt-in
+drafts with `schemaVersion:2` also support RGBA recipes, named atlases and explicit
+per-map samplers; see the [standalone texture workflow](procedural-surfaces-v3.md#standalone-saved-materials-and-atlases).
+An optional
 `derive: {"kind":"normal-from-height","strength":2}` on a normal map converts the recipe's
 height pixels through the existing wrapped normal derivation. `import` accepts a complete
 normalized payload. None of these operations acquires source images from a provider.
@@ -66,8 +70,8 @@ Pin the returned material ID and revision hash before using its resource IDs. A
 optional: pass a pin array as MCP `materialDependencies` or CLI `--materials pins.json` for
 an individual operation, or put the array in a project's `materialDependencies` for shared use.
 The pin's `resourceId` is the material ID; its `revisionId` and `sha256` both equal the
-manifest's immutable `revisionId`. `compilePortableMaterialSpecV2(portableSpec)` then creates the
-material inside authored source. The host supplies complete map bytes through `materialResources`
+manifest's immutable `revisionId`. The compiler matching `portableSpec.schemaVersion`
+creates the material inside authored source. The host supplies complete map bytes through `materialResources`
 before build-cache lookup, including when evaluation uses the default subprocess.
 
 Editable standalone asset ZIPs carry the saved dependency closure in `materials.kiln.json`;

package/docs/procedural-surfaces-v3.md

@@ -0,0 +1,276 @@
+# Procedural RGBA surfaces V3
+
+`proceduralTexture({ schemaVersion: 3, ... })` creates rectangular RGBA pixels
+through the same authored-source helper as V1/V2. The standalone compiler is
+`compileProceduralTextureSpecV3` from the primitives SDK. Its contract helpers
+are `canonicalizeProceduralTextureSpecV3`, `canonicalProceduralTextureJsonV3`
+and `hashProceduralTextureSpecV3`.
+
+V1 (absent or `1` version) and V2 remain on their existing compiler, square
+power-of-two dimensions, opaque output, canonical JSON and hashes. An explicitly
+undefined version retains historical V1 behavior; V3 itself accepts strict JSON,
+so undefined fields are invalid. Unknown versions fail before dispatch. Existing
+portable material V2 references remain V2. New portable V3 material references
+and V2 saved material records are opt-in contracts described below.
+
+## Contract
+
+```ts
+{
+  schemaVersion: 3,
+  width: 4..1024, height: 4..1024, // integers, need not be powers of two
+  usage?: 'albedo' | 'emissive' | 'normal' | 'roughness' | 'metalness'
+    | 'metallicRoughness' | 'occlusion', // default albedo
+  name?: string,                 // 1..80 visible characters
+  background?: [r,g,b,a],         // bytes 0..255, default [0,0,0,0]
+  operations: OperationV3[],      // ordered, zero to 64 entries
+  palette?: { colors: RGB[], dither?: 'none' | 'bayer4' }
+}
+```
+
+RGBA channels are straight bytes. RGB is authored encoded color for albedo and
+emissive; other usages retain linear data. Transparent RGBA input canonicalizes
+to `[0,0,0,0]`, and every output pixel with zero alpha has zero RGB. Palette
+mapping and stamps support only albedo/emissive; they reject all data usages.
+Shapes and masks operate on declared bytes without interpreting data channels.
+
+Operations have these exact fields:
+
+| `op` | Fields |
+| --- | --- |
+| `paint` | `shape`, `rgba`, optional byte `opacity` (default 255) |
+| `mask` | `shape`, optional byte `alpha` (default 255), optional boolean `invert` (default false) |
+| `stamps` | `shape`, `rgba`, `count`, uint32 `seed`, `area`, optional byte `opacity`, optional boolean `periodic` (default false) |
+| `legacy-v2` | `spec` with explicit schemaVersion 2, optional byte `alpha` and byte `opacity` (both default 255) |
+
+V3 opacity is a byte, unlike V2's fractional opacity. The legacy layer delegates
+to the existing V2 compiler, including its six operators and first-layer rules.
+Its square size and usage must match the V3 surface; its output RGB is composited
+using the explicitly selected V3 alpha and opacity. It does not reinterpret V2
+blend modes or silently migrate a V2 recipe into V3 operations.
+
+## Coverage and compositing
+
+Coordinates describe integer pixel edges; a pixel `(x,y)` samples `(x+0.5,y+0.5)`.
+Shapes clip to the output extent. There is no antialiasing or fractional shape
+coverage in this compiler version.
+
+| Shape `kind` | Fields and coverage |
+| --- | --- |
+| `rectangle` | `x,y,width,height`; left/top inclusive, right/bottom exclusive |
+| `ellipse` | `x,y,width,height`; inscribed ellipse, boundary inclusive |
+| `polygon` | `points:[[x,y],...]`; even-odd fill, boundary inclusive, 3..64 vertices; self-intersections use that same fill rule |
+| `line` | `from:[x,y],to:[x,y],width`; capsule with inclusive round caps; coincident endpoints create a disk |
+
+Coordinates are integers -4096..4096. Shape widths/heights and line width are
+integers 1..2048. A one-pixel line on an integer edge can cover centers on both
+sides of the edge; width measures continuous distance, not a promised count of
+covered columns. Polygon degeneracies are deterministic rather than repaired.
+
+`paint` uses source-over. Define `round(n/d) = floor(n/d + 0.5)`. For source alpha
+`a`, operation opacity `o` and destination alpha `d`:
+
+```text
+s = round(a * o / 255)
+N = s * 255 + d * (255 - s)
+output alpha = round(N / 255)
+output channel = round((source channel * s * 255
+                        + destination channel * d * (255 - s)) / N)
+```
+
+When `s=0`, painting is inert. RGB division uses the unrounded alpha numerator,
+then alpha and RGB are stored as bytes after each operation. This blends authored
+byte values; it does not linearize encoded colors or introduce floating opacity.
+
+`mask` multiplies destination alpha by the mask byte and rounds half-up. Outside
+the covered shape it clears alpha. With `invert:true`, outside retains the mask
+alpha factor and inside clears alpha. It preserves destination RGB while alpha
+remains positive and clears RGB when alpha becomes zero. A mask affects only
+pixels already painted; subsequent paint can add pixels again.
+
+## Palettes and periodic stamps
+
+Palette mapping runs once after all operations. `colors` is an ordered array of
+1..32 RGB integers 0..0xffffff. The nearest color minimizes squared distance in
+encoded RGB bytes; a tie selects the first array entry. Alpha is preserved and
+transparent pixels stay black. `dither:'none'` is the default.
+
+`bayer4` repeats this fixed matrix from image origin `(0,0)`:
+
+```text
+ 0  8  2 10
+12  4 14  6
+ 3 11  1  9
+15  7 13  5
+```
+
+Before nearest-color selection, each RGB channel receives integer offset
+`(2 * matrixEntry - 15) * 2`, clipped to 0..255. Palette membership is therefore
+exact, and dither does not add alpha variation or random noise.
+
+Stamp `area` is `{x,y,width,height}`, with the same rectangle coordinate bounds.
+Each stamp translates its local shape by two integer offsets within that area.
+The PRNG starts from `(seed ^ 0xa3c59ac3) >>> 0`, substitutes fixed state
+`0x6d2b79f5` if that value is zero, performs Xorshift32 with shifts 13,17,5,
+and consumes X then Y in operation order. Offsets use unsigned state
+modulo area width/height. Counts are 1..256. Seeds use the full unsigned 32-bit
+range, including zero. No clock or random global is involved.
+
+`periodic:true` explicitly wraps the translated shape's bounding origin into one
+surface period, then clips copies translated by -period, 0 and +period on each
+axis. Its shape bounds must fit one period on each axis. Each periodic stamp
+counts as nine expanded copies, with at most 256 expanded copies across the
+recipe. Ordinary stamps clip at edges. Periodic placement does not establish
+that other operations tile; inspect repeat neighbors and the resulting patch.
+
+## Admission and identity
+
+Validation inspects every object and array data descriptor before field reads.
+Custom prototypes, accessors, symbols, holes, non-index array fields, forbidden
+prototype keys, functions, undefined, nonfinite numbers and unknown schema
+fields are rejected. Admission precedes the output pixel allocation.
+
+The limits are 1,048,576 output texels, 64 operations, 64 polygon vertices,
+256 expanded stamps and 32 palette colors. JSON preflight admits at most
+16,384 nodes and depth 10, at most 1024 fields per container, and at most
+262,144 characters of canonical JSON. The only arbitrary text is an 80-character
+name, so this also bounds UTF-8 recipe storage with a small fixed overhead.
+
+The conservative work ceiling is 64,000,000 units. It includes output
+initialization, clipped shape tests (each polygon edge counts), full mask scans,
+per-copy stamp bounds, palette comparisons and legacy pattern/noise work. V3
+transient pixel buffers stay below 64MiB. The compiler creates one RGBA output;
+legacy layers temporarily create matching RGBA outputs and palette metadata is
+bounded. These limits do not raise legacy or portable-material budgets.
+
+The compiler ID is `kiln.procedural-rgba.v3.1`. V3 recipe hashes are SHA-256 of
+`compilerId + '\n' + canonicalJson`; property order and omitted defaults produce
+the same canonical result. A changed pixel algorithm requires a new compiler ID.
+V3 metadata records that ID, canonical JSON and recipe hash. V2's hashes and
+material-record compiler ID `kiln.procedural-texture.v2` remain unchanged.
+
+Failures use closed evaluator diagnostic `PROCEDURAL_TEXTURE_V3_CONTRACT`;
+direct SDK calls also include the rejected field in the exception text.
+
+## Authored-source example
+
+```js
+function build() {
+  const root = createRoot('CutoutStudy');
+  const texture = proceduralTexture({
+    schemaVersion: 3, width: 16, height: 32, name: 'LeafStudy',
+    operations: [
+      { op: 'paint', shape: { kind: 'ellipse', x: 3, y: 2, width: 10, height: 28 },
+        rgba: [66, 100, 42, 255] },
+      { op: 'paint', shape: { kind: 'line', from: [8, 4], to: [8, 29], width: 1 },
+        rgba: [118, 132, 60, 255] }
+    ],
+    palette: { colors: [0x42642a, 0x76843c] }
+  });
+  const material = pbrMaterial({ albedo: texture, alphaMode: 'mask',
+    alphaCutoff: 0.5, doubleSided: true, roughness: 1 });
+  createPart('Card', planeGeo(0.5, 1), material, { parent: root });
+  return root;
+}
+```
+
+Textures keep existing repeat/linear/mipmap defaults. Sampling choices remain
+explicit Three.js texture settings; creating V3 does not select a pixel-art
+policy. The material's alpha mode and sidedness are separate from pixel alpha.
+
+## Standalone saved materials and atlases
+
+No mesh or project is required to create or save a procedural texture. The
+existing `kiln_material` action `create-procedural`, named operation
+`kiln_material_create`, and `kiln material procedural --file draft.json` share
+one JSON authoring boundary. An unversioned layered material draft retains its
+V1 record format and existing defaults. An opt-in material draft with
+`schemaVersion:2` accepts V2 layer recipes, V3 RGBA recipes, or named atlases and
+saves a V2 material record. This material-record version is distinct from a
+texture recipe's `schemaVersion`.
+
+Each new map supplies exactly one `procedural` or `atlas` recipe, its map slot,
+source provenance, transforms, and an explicit sampler:
+
+```json
+{
+  "minFilter": "nearest",
+  "magFilter": "nearest",
+  "wrapS": "clamp-to-edge",
+  "wrapT": "clamp-to-edge"
+}
+```
+
+This example is a choice for a pixel texture, not a global engine default.
+Minification also supports `linear`, `nearest-mipmap-nearest`,
+`nearest-mipmap-linear`, `linear-mipmap-nearest`, and `linear-mipmap-linear`.
+Wrapping supports `repeat`, `mirrored-repeat`, and `clamp-to-edge`.
+Evaluate minification in the consuming scene; nearest magnification alone does
+not establish acceptable motion, distant cutouts, or atlas gutter behavior.
+
+Read `shape:material-draft` and `shape:material-import` with Discovery for the
+complete runtime-validated fields. Sources keep explicit creator and license
+records. The JSON authoring surface accepts no file paths, URLs to fetch, or
+raw image bytes. Existing external image records enter through verified import.
+
+`textureAtlas(spec)` compiles named, fixed pixel rectangles. The atlas has
+`schemaVersion:1`, width, height, usage, an optional sampler, and regions.
+Coordinates are integer pixels from the top-left. Each region has a stable
+lowercase `name`, a `content` rectangle, a `source`, and optional crop, gutter,
+and edge mode. Default gutters are two pixels; padded allocations must fit
+without overlap. Sources must already match the requested crop size: this
+operation does not pack, resize, rotate, or resample images.
+
+A source is either `{kind:'procedural',spec:<V3 recipe>}` or
+`{kind:'resource',resourceId:<exact map id>,pin:{resourceId:<material id>,
+revisionId:<revision hash>,sha256:<same revision hash>}}`. Resource IDs identify
+the saved map, while the pin identifies its immutable material revision.
+Resolution uses only the explicitly injected material library or evaluator
+dependencies, never nearby projects or network requests. The shared dependency
+walker admits the entire metadata graph before loading source PNGs.
+
+`copy-edge` copies edge RGBA into the gutter. `mask-rgb-dilate` keeps gutter alpha
+zero and fills RGB from the nearest positive-alpha source texel, with a stable
+tie break. This reduces dark cutout fringes but does not guarantee safe mipmaps
+for every region size or viewing distance.
+
+Use `remapUVToAtlas(geometry, atlas, regionName, {inputOrigin,mode})` to map unit
+UVs into a named region on an owned geometry clone. `inputOrigin` is explicit
+`top-left` or `bottom-left`; `mode` is `content-boundary` or `texel-center`. Rich attributes,
+morphs and skin data are retained according to the UV helper's contract. A
+region binding describes that geometry's region; it does not infer independent
+region assignments for material groups.
+
+Saved atlas maps retain the canonical recipe, named-region/source manifest,
+compiler identity, encoded-image hash, decoded pixel hash and exact source
+revision pins. `kiln material export` includes the complete verified material
+closure; importing it into an offline workspace restores those revisions.
+Old-only payloads retain schemaVersion 1. Mixed or new records use schemaVersion
+2 without rewriting old identities. Projects remain optional and pin exact
+saved revisions when explicitly selected.
+
+## Atlas delivery and inspection
+
+Both GLB converters retain a bounded `kilnAtlasProvenance` table in scene extras,
+an exact `kilnAtlasReference` on each material texture use, and a compact
+`kilnAtlasBinding` on primitives created from a named remap. These optional extras
+describe Kiln lineage; ordinary glTF textures, UVs and samplers still render in
+consumers that ignore them. Manual full-sheet use needs no named binding.
+The [delivery metadata contract](atlas-provenance.md) specifies the fields,
+validation and bounds.
+
+The source manifest identifies compiled RGBA pixels and recipe inputs. The
+delivery reference separately identifies final encoded image bytes and the
+effective sampler for that use. Conversion may legitimately alter pixels, such
+as an explicit normal-channel conversion, so these identities are distinct.
+Import validates the recorded delivery identity; it never silently replaces a
+stale hash. Editing compiled atlas pixels requires recompilation or removal of
+the atlas metadata to make an ordinary manually authored texture.
+
+Structural QA checks declared regions, referenced UVs, slots and sampling without
+decoding images. Quantized UV storage has a bounded precision allowance. Work
+limits or unavailable dimensions produce partial coverage; a valid UV domain
+does not prove the intended orientation or visual quality. Inspect exact saved
+maps in Materials, or follow the material links from Library and Live Review.
+Use a material-faithful rendered view and the destination scene for cutout,
+lighting and motion decisions.

package/docs/projects-and-live-review.md

@@ -29,7 +29,7 @@ Authoring commands accept `--project` and `--project-revision`. MCP tools use `p
 node kiln.mjs render asset.kiln.js --no-project --materials pins.json --out asset.glb
 ```
 
-`pins.json` contains an array of exact `{resourceId, revisionId, sha256}` material dependencies. MCP accepts the same array as `materialDependencies`. These per-call pins work independently of project membership. With a project, additional pins can extend its lock, but conflicting revisions for the same resource are rejected. Copy returned identities rather than constructing them, and preserve the selected dependencies on subsequent calls that evaluate the source.
+`pins.json` contains an array of exact `{resourceId, revisionId, sha256}` material dependencies. MCP accepts the same array as `materialDependencies`. These per-call pins work independently of project membership. With a project, additional pins extend its lock and an explicit pin replaces the project pin for the same resource for that invocation. The saved project revision remains unchanged. Copy returned identities rather than constructing them, and preserve the selected dependencies on subsequent calls that evaluate the source.
 
 ## Materials and coherent art direction
 

package/docs/rendering.md

@@ -27,6 +27,47 @@ safety. See `kiln animation --help` for the complete options.
 
 CPU views show silhouette, orientation, proportion, and contact. They do not reproduce the asset's PBR materials. Translucent (opacity below 1) surfaces are composited after opaque geometry, farthest first, so parts behind glazing stay visible whatever order the scene lists them in. Use GPU views to review textures, roughness, metalness, and normal relief. GPU output can vary by device and driver.
 
+GLB review reconstructs skins with up to four joint influences per vertex,
+including normalized weights and inverse bind matrices. CPU triangles and pose
+bounds follow the sampled joint pose rather than the undeformed position buffer.
+Unsupported additional influence sets produce an explicit error. GLB review
+also reconstructs position/normal morph deltas, node-over-mesh default weights,
+and STEP, LINEAR or CUBICSPLINE weight animation before applying skin transforms.
+Missing target attributes contribute zero displacement. Other morph semantics
+retain `GLB_FLAT_MORPH_TARGETS_UNSUPPORTED`; they are not qualified by this path.
+Expanded morph attributes are bounded to 64 MiB per review scene, including
+zero-filled attributes. Weight tracks use the review limits of 4,096 keys and
+16,384 scalar values. Invalid counts and nonfinite weights/deltas are rejected.
+Morph primitive children receive unique binding-safe names beneath the original
+named node; use that parent for a stable authored-part selection. Copies have
+independent morph influences. Loop-closure evidence remains transform-only and
+reports weight tracks as unassessed rather than labeling them as scale tracks.
+Isolated, two-sided and composed-scene review
+copies own their skeletons and preserve required hidden joint ancestors as
+transforms without drawing their geometry. Include all referenced bones in the
+review root; copying an incomplete hierarchy reports the missing dependency.
+Geometry and textures remain shared read-only, while two-sided overrides own
+their materials. Qualify material-faithful derivatives separately from the
+whole-character CPU view.
+
+CPU views honor front-only, back-only and double-sided source materials in both
+camera paths. Facing follows triangle winding after deformation, with the mesh's
+world-transform reflection parity; changing vertex normals does not change culling.
+Visible back faces reverse their flat lighting normal. Disabling culling for a
+diagnostic view acts as a two-sided override. Singular transforms do not flip
+winding; collapsed triangles do not draw. CPU output remains geometry evidence,
+not PBR evidence. Back-only source materials are not directly portable to GLB;
+see [material sidedness at export](export-profiles.md#material-sidedness-at-export).
+
+Both CPU camera paths sample pixel centres with top-left shared-edge ownership.
+They evaluate all three edges directly from canonical endpoints, preventing
+rounding gaps and duplicate blending where adjacent triangles meet. Near/far
+clipping uses direction-independent intersections. Interpolation uses unbiased
+edge weights, including reciprocal depth for perspective cameras. This is a
+floating-point geometry preview, not hardware subpixel/MSAA emulation; perimeter
+pixels can differ from GPU views. Degenerate or nonfinite projected triangles
+are discarded, and raster loops stay within the output image.
+
 ## Review lighting
 
 New GPU tool captures use **`review-neutral-v1`**. The rig uses the room PMREM

package/docs/sdk.md

@@ -80,6 +80,59 @@ and source/revision receipts for reproducible replay. Compatibility of the SDK
 does not imply identical generated GLB bytes or renderer output across releases.
 Persisted data and rebuild restrictions follow the [migration contract](migration.md).
 
+## Procedural RGBA surfaces
+
+The `primitives` entrypoint and authored `proceduralTexture` helper accept an
+explicit V3 recipe for bounded rectangular RGBA images, shape coverage, alpha
+masks, palettes, dithering and seeded stamps. Pure V3 compilation returns pixels,
+canonical JSON and a compiler-qualified recipe hash without creating a mesh.
+Read the [V3 contract](procedural-surfaces-v3.md) for the exact limits and rounding
+rules. V1/V2 remain supported with their existing pixels, hashes and sampler
+defaults. The same entrypoint exposes `textureAtlas` and `remapUVToAtlas` for
+named regions. Portable V3 materials add explicit per-map sampling; opt-in V2
+material records persist recipes, compiled maps and exact dependency pins.
+See the [standalone material and atlas workflow](procedural-surfaces-v3.md#standalone-saved-materials-and-atlases).
+
+## Explicit character skinning
+
+The `character` and `primitives` entrypoints expose opt-in `createBoneChain` and
+`createSkinnedPart`; both are also sandbox helpers. `createJointChain` continues
+to return ordinary rigid `Object3D` pivots. Bone chains use the same versioned
+joint descriptors, infer an attached declared parent role and reject ambiguous
+roles/names before attaching nodes. They do not choose anatomy or a body plan.
+
+`createSkinnedPart(name, geometry, material, { parent, bones, indices, weights })`
+clones unchanged geometry and binds it to the assembled hierarchy's current rest
+pose. Supply exactly four indices and weights per vertex, in the explicit bone
+array order. Indices must be valid even in zero-weight lanes. By default weights
+must be in 0..1 and sum to one within 1e-5; `normalizeWeights: true` explicitly
+normalizes positive finite sums. Zero sums are rejected. Optional local position,
+Euler rotation (degrees), scale and semantic metadata match `createPart`'s units.
+
+The helper owns geometry, influence arrays and inverse bind matrices; bones and
+materials remain shared. Limits are 1024 bones, 262144 vertices and 128 MiB of
+cloned attributes plus new influence storage. These are helper limits, not new
+restrictions on direct Three.js authoring. Existing skin attributes and singular
+bind transforms are rejected. Set up rest transforms before binding; later rest
+edits/reparenting need deliberate rebinding. Animated bounds remain a consumer
+responsibility. The selected Three exporter is required to preserve skins;
+calling these helpers does not change the legacy default or select a converter.
+
+`inspectSkinIntegrity(root)` from `@instruktlabs/kiln/qa` reads source bindings
+without updating matrices, normalizing weights or repairing the scene. It returns
+bounded findings, checked counts and current posed world bounds (including position
+morphs). It is not an animation envelope, deformation-quality score or proof of
+collision clearance. Rigid meshes do not acquire skin or body-plan requirements.
+
+Export runs this check before bounds, texture baking or conversion. Invalid source
+bindings produce an `AssetQaBlockedError` at the scene stage with mesh/joint or
+vertex-range context and repair advice. This is mandatory input integrity, like
+invalid geometry buffers; QA warning mode and derivative serialization do not
+bypass it. The partial failure report does not claim the remaining QA rules ran.
+The independent final glTF validation remains in place. Source Three skeletons
+need their inverse-bind arrays populated; this does not change glTF's valid
+identity-matrix default when the file omits `inverseBindMatrices`.
+
 ## Execution and dependencies
 
 The root SDK is Node-oriented. `/node` adapters use filesystem or server services;

package/docs/tools-operations.md

@@ -1123,7 +1123,7 @@ Create and retain one immutable material from a preset or procedural definition.
           "type": "object",
           "properties": {
             "draft": {
-              "description": "create-procedural: materialId, name, tileable, sources, maps with layered procedural specs; optional tags, physicalSizeMeters, parameters. Shape: kiln_discover({ ids: ['shape:material-draft'] }).",
+              "description": "create-procedural: legacy layered draft, or schemaVersion 2 with explicit samplers and RGBA/atlas recipes. Exact atlas sources must exist in this library. Shape: kiln_discover({ ids: ['shape:material-draft'] }).",
               "type": "object",
               "propertyNames": {
                 "type": "string"
@@ -1166,7 +1166,7 @@ Import complete normalized material records and embedded PNGs. Does not fetch UR
   "type": "object",
   "properties": {
     "payload": {
-      "description": "import: schemaVersion 1 and complete normalized records with embedded PNG bytes. Shape: kiln_discover({ ids: ['shape:material-import'] }).",
+      "description": "import: schemaVersion 1 or 2, complete normalized records and their exact dependencies with embedded PNG bytes. Shape: kiln_discover({ ids: ['shape:material-import'] }).",
       "type": "object",
       "propertyNames": {
         "type": "string"

package/docs/tools.md

@@ -1328,7 +1328,7 @@ Manage optional shared workspace projects: list discovers IDs; get reads the cur
 
 ## kiln_material
 
-Manage optional immutable material resources in this workspace. presets discovers shipped architecture, wood, metal, fabric and ground recipes; create-preset bakes one with an explicit seed, creator and license; list returns compact material/revision summaries; get returns full provenance, hashes, map conventions, physical repeat scale and a code-ready portable material spec; create-procedural bakes bounded editable layer recipes including optional height-derived normals; import accepts complete normalized records with embedded PNG bytes. No action downloads URLs or executes source. Pin the returned materialId/revisionId through per-invocation materialDependencies or project dependencies before authored evaluation resolves the resources; no project is required.
+Manage optional immutable material resources in this workspace. presets lists shipped recipes; create-preset uses explicit seed, creator and license; list returns revision summaries; get returns provenance, hashes, sampling and a portable material spec. create-procedural accepts legacy layer drafts or schemaVersion 2 drafts with explicit samplers and bounded RGBA or named atlas recipes. Atlas resource sources require exact saved revisions; import requires complete normalized records and dependencies with embedded PNG bytes. Read shape:material-draft or shape:material-import through kiln_discover for full fields. No action downloads URLs or executes source. Pin the returned materialId/revisionId through per-invocation materialDependencies or project dependencies before evaluation; no project or mesh is required.
 
 <details>
 <summary>Input JSON Schema</summary>
@@ -1431,7 +1431,7 @@ Manage optional immutable material resources in this workspace. presets discover
       "pattern": "^sha256:[a-f0-9]{64}$"
     },
     "draft": {
-      "description": "create-procedural: materialId, name, tileable, sources, maps with layered procedural specs; optional tags, physicalSizeMeters, parameters. Shape: kiln_discover({ ids: ['shape:material-draft'] }).",
+      "description": "create-procedural: legacy layered draft, or schemaVersion 2 with explicit samplers and RGBA/atlas recipes. Exact atlas sources must exist in this library. Shape: kiln_discover({ ids: ['shape:material-draft'] }).",
       "type": "object",
       "propertyNames": {
         "type": "string"
@@ -1439,7 +1439,7 @@ Manage optional immutable material resources in this workspace. presets discover
       "additionalProperties": {}
     },
     "payload": {
-      "description": "import: schemaVersion 1 and complete normalized records with embedded PNG bytes. Shape: kiln_discover({ ids: ['shape:material-import'] }).",
+      "description": "import: schemaVersion 1 or 2, complete normalized records and their exact dependencies with embedded PNG bytes. Shape: kiln_discover({ ids: ['shape:material-import'] }).",
       "type": "object",
       "propertyNames": {
         "type": "string"

package/lib/asset-materials-node.d.ts

@@ -1,5 +1,5 @@
 /** Exact saved material closure, shared by standalone asset and project delivery. */
 import type { AssetRecord } from "./assets.js";
-import { type MaterialLibrary, type MaterialManifestV1, type MaterialRecordV1 } from "./material-library.js";
-export declare function dependencyManifests(asset: AssetRecord): MaterialManifestV1[];
-export declare function resolveSavedAssetMaterials(asset: AssetRecord, library?: MaterialLibrary): Promise<MaterialRecordV1[]>;
+import { type MaterialLibrary, type MaterialManifest, type MaterialRecord } from "./material-library.js";
+export declare function dependencyManifests(asset: AssetRecord): MaterialManifest[];
+export declare function resolveSavedAssetMaterials(asset: AssetRecord, library?: MaterialLibrary): Promise<MaterialRecord[]>;