Build and revise procedural 3D assets with your coding agent. Local MCP server, CLI and TypeScript engine with rendered review, editable source and GLB export.
JavaScript 3d3d-assets3d-modelingagent-skillsagent-toolsai-agentsasset-pipelinecligame-assetsglbgltfmcpmcp-servermodel-context-protocolprocedural-generationprocedural-modelingtext-to-3dthreejstypescript
feat(qa): declare parts that rest on an external support (#220) (#234)
Matthew Kissingerdce96f0ad2b7
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex c8d9ddae..13addfac 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -93,6 +93,13 @@ does not publish a package.Meshopt decoder reads the GLB, while `KHR_mesh_quantization`, instancing and everypreserved feature stay. The sidecar `delivery.compression` records `{ extension: 'none' }`.The default output is unchanged.+- Declare parts that rest on an external support ([#220](https://github.com/instruktlabs/kiln/issues/220)).+ A requirements binding can list `externalSupport.supports`: named parts and the plane they+ rest on outside the asset. A named part whose bottom meets that plane moves from the+ floating-parts warning to an informational line, and its connectivity observation becomes+ `GEO_PART_EXTERNAL_SUPPORT` naming the declaration. Undeclared parts, parts at another+ height and every other disposition are unchanged. The declaration is covered by the policy+ hash.## 1.3.1 (2026-10-17)diff --git a/dist/agent-run.mjs b/dist/agent-run.mjsindex 9c44c97a..95d69bfa 100644--- a/dist/agent-run.mjs+++ b/dist/agent-run.mjs@@ -561,7 +561,7 @@ function createAssetRequirementsV1(input = {}) {...input});}-var text, positive, nonnegative, count, names, marker, roof, structure, effects, requirements, AssetRequirementsV1Schema;+var text, positive, nonnegative, count, names, marker, supportParts, roof, structure, effects, requirements, AssetRequirementsV1Schema;var init_requirements = __esm(() => {init_asset();init_breadth();@@ -573,6 +573,9 @@ var init_requirements = __esm(() => {message: "Values must be unique."});marker = z.strictObject({});+ supportParts = z.array(text).min(1).max(256).refine((values) => new Set(values).size === values.length, {+ message: "Values must be unique."+ });roof = z.strictObject({type: text.optional(),ridgeAxis: z.enum(["x", "z"]).optional(),@@ -692,6 +695,13 @@ var init_requirements = __esm(() => {precomputedTangents: z.boolean().optional(),skinned: z.boolean().optional()})).optional(),+ externalSupport: statement(z.strictObject({+ supports: z.array(z.strictObject({+ parts: supportParts,+ planeY: z.number().finite(),+ tolerance: nonnegative.max(0.5).optional()+ })).min(1).max(32)+ })).optional(),access: statement(z.strictObject({ enterable: z.boolean().optional(), driveable: z.boolean().optional() })).optional()});AssetRequirementsV1Schema = z.strictObject({@@ -9929,7 +9939,8 @@ function resolveRequirementsApplicability(requirements) {grounding: ["planeY"],bounds: ["units", "x", "y", "z"],animation: ["clips"],- representation: ["precomputedTangents"]+ representation: ["precomputedTangents"],+ externalSupport: ["supports"]};for (const [key, statement] of Object.entries(requirements.requirements)) {if (statement?.state !== "requested")@@ -12590,6 +12601,25 @@ var init_solid_diagnostic = __esm(() => {};});+// src/external-support.ts+function restingSupport(mesh, bottomY, supports) {+ return declaredSupports(mesh, supports).find((support) => Math.abs(bottomY - support.planeY) <= (support.tolerance ?? EXTERNAL_SUPPORT_TOLERANCE));+}+function declaredSupports(mesh, supports) {+ if (!supports?.length)+ return [];+ const names = new Set;+ for (let node = mesh;node; node = node.parent) {+ if (!node.name)+ continue;+ names.add(node.name);+ if (node.name.startsWith("Mesh_"))+ names.add(node.name.slice(5));+ }+ return supports.filter((support) => support.parts.some((part) => names.has(part)));+}+var EXTERNAL_SUPPORT_TOLERANCE = 0.02;+// src/qa/breadth-evidence.tsimport * as THREE6 from "three";function record7(value) {@@ -16629,7 +16659,7 @@ var init_lod2 = __esm(() => {// src/qa/part-connectivity.tsimport * as THREE14 from "three";-function collectParts2(root, exempt) {+function collectParts2(root, exempt, supports) {const parts = [];let lodExcluded = 0;root.updateWorldMatrix(true, true);@@ -16649,7 +16679,8 @@ function collectParts2(root, exempt) {const box = new THREE14.Box3().setFromObject(mesh);if (box.isEmpty())return;- parts.push({ name, box });+ const support = restingSupport(mesh, box.min.y, supports);+ parts.push({ name, box, ...support ? { support } : {} });});return { parts, lodExcluded };}@@ -16659,9 +16690,9 @@ function boxGap(a, b) {const dz = Math.max(0, Math.max(a.min.z - b.max.z, b.min.z - a.max.z));return Math.hypot(dx, dy, dz);}-function analyzePartConnectivity(root) {+function analyzePartConnectivity(root, supports) {const exempt = [];- const { parts, lodExcluded } = collectParts2(root, exempt);+ const { parts, lodExcluded } = collectParts2(root, exempt, supports);const report = {partsAnalyzed: parts.length,mainComponentSize: parts.length,@@ -16722,22 +16753,48 @@ function analyzePartConnectivity(root) {gap = Math.min(gap, boxGap(parts[m].box, parts[b].box));}}+ const lowest = members.reduce((a, b) => parts[b].box.min.y < parts[a].box.min.y ? b : a);+ const support = parts[lowest].support;report.groups.push({parts: members.map((m) => parts[m].name),- gap: Math.round(gap * 1e6) / 1e6+ gap: Math.round(gap * 1e6) / 1e6,+ ...support && members.every((m) => parts[m].support) ? {+ externalSupport: {+ planeY: support.planeY,+ bottomY: Math.round(parts[lowest].box.min.y * 1e6) / 1e6,+ tolerance: support.tolerance ?? CONNECTIVITY_TOLERANCE+ }+ } : {}});}report.groups.sort((a, b) => b.parts.length - a.parts.length || a.gap - b.gap);return report;}-function inspectPartConnectivity(scene) {+function inspectPartConnectivity(scene, supports) {if (!(scene instanceof THREE14.Object3D))return [];- const report = analyzePartConnectivity(scene);+ const report = analyzePartConnectivity(scene, supports);const lodNote = report.lodExcluded === 1 ? " 1 part on an LOD level above 0 was not analyzed." : report.lodExcluded > 1 ? ` ${report.lodExcluded} parts on LOD levels above 0 were not analyzed.` : "";return report.groups.map((group) => {const listed = group.parts.map((p) => JSON.stringify(p)).join(", ");const subject = group.parts.length === 1 ? `Part ${listed} is` : `A group of ${group.parts.length} parts (${listed}) is`;+ const declared = group.externalSupport;+ if (declared)+ return {+ code: "GEO_PART_EXTERNAL_SUPPORT",+ disposition: "observe",+ dimension: "visualQuality",+ profile: "geometry.partConnectivity",+ message: `${subject} separate from the largest component and rests on the support declared in requirements.externalSupport at Y=${declared.planeY.toFixed(3)} m (bottom at Y=${declared.bottomY.toFixed(3)} m). Information only: the support is composed outside this asset.${lodNote}`,+ affected: { node: group.parts[0] },+ measurement: {+ name: "bottomToSupportPlane",+ actual: declared.bottomY,+ expected: declared.planeY,+ threshold: declared.tolerance+ },+ repairText: "No change is needed for a declared support. Remove the part from requirements.externalSupport if it should attach within this asset."+ };return {code: "GEO_PART_CONNECTIVITY",disposition: "observe",@@ -22901,7 +22958,7 @@ function runRequirementsSceneQa(context, scene, clips, policy = {}, evidence = {findings.push(decision.mode === "observe" || decision.mode === "warn" ? { ...finding, disposition: decision.mode } : finding);continue;}- const measured = decision.ruleId === SWEEP_QA_RULE.id ? inspectSweepGeometry(scene) : decision.ruleId === PART_CONNECTIVITY_QA_RULE.id ? inspectPartConnectivity(scene) : decision.ruleId === ASSET_SCOPE_QA_RULE.id && scope?.state === "requested" ? inspectAssetScope({+ const measured = decision.ruleId === SWEEP_QA_RULE.id ? inspectSweepGeometry(scene) : decision.ruleId === PART_CONNECTIVITY_QA_RULE.id ? inspectPartConnectivity(scene, needs.externalSupport?.state === "requested" ? needs.externalSupport.value.supports : undefined) : decision.ruleId === ASSET_SCOPE_QA_RULE.id && scope?.state === "requested" ? inspectAssetScope({profile: "asset.requirements.v1",scope: { schemaVersion: 1, scope: scope.value, explicit: true },derivedEvidence: { source: "engine-scene-analysis", assetScope: scopeObservation }@@ -37165,7 +37222,10 @@ async function renderSceneToGLB(root, opts = {}) {const materialResourceProvenance = collectMaterialResourceProvenance(root);for (const w of inspectGeneratedAnimation(root, clips))warnings.push(w);- for (const w of inspectSceneStructure(root))+ const externalSupport = requirements.requirements.requirements.externalSupport;+ for (const w of inspectSceneStructure(root, {+ ...externalSupport?.state === "requested" ? { externalSupport: externalSupport.value.supports } : {}+ }))warnings.push(w);const atlas = collectAtlasProvenance(root);const bakedTextures = await bakeSceneTextures(root, warnings);@@ -37491,6 +37551,7 @@ function collectMeshStats(root) {box.getCenter(center);box.getSize(size);out.push({+ object: obj,name: obj.name || "(unnamed)",triCount: Math.floor(tri),isPlaneGeo: geo.type === "PlaneGeometry",@@ -37549,6 +37610,7 @@ function inspectSceneStructure(root, opts = {}) {}if (meshes.length > 1) {const floaters = [];+ const supported = [];for (let i = 0;i < meshes.length; i++) {const a = meshes[i];const ax = a.box.clone().expandByScalar(FLOATING_EXPAND);@@ -37564,6 +37626,12 @@ function inspectSceneStructure(root, opts = {}) {}if (overlapsAny)continue;+ const support = restingSupport(a.object, a.box.min.y, opts.externalSupport);+ if (support) {+ supported.push(`${a.name} at Y=${support.planeY.toFixed(3)}`);+ continue;+ }+ const declared = declaredSupports(a.object, opts.externalSupport)[0];let nearest;let nearestGap;for (let j = 0;j < meshes.length; j++) {@@ -37576,7 +37644,8 @@ function inspectSceneStructure(root, opts = {}) {}}const fix = nearest && nearestGap ? ` Fix: shift "${a.name}" by [${nearestGap.x.toFixed(3)}, ${nearestGap.y.toFixed(3)}, ${nearestGap.z.toFixed(3)}] toward "${nearest.name}", or call snapTo(part, hostPart) to do it automatically.` : "";- floaters.push({ name: a.name, fix });+ const mismatch = declared ? ` It is named in a declared external support at Y=${declared.planeY.toFixed(3)}, but its bottom is at Y=${a.box.min.y.toFixed(3)}.` : "";+ floaters.push({ name: a.name, fix: fix + mismatch });}if (floaters.length > 0) {const entries = floaters.slice(0, FLOATER_FIXES_SHOWN).map(({ name, fix }) => `${name}${fix ? ` —${fix}` : ""}`);@@ -37589,6 +37658,12 @@ function inspectSceneStructure(root, opts = {}) {}warnings.push(`Floating parts (no mesh overlap with any sibling, 2cm tol): ${entries.join(" | ")}`);}+ if (supported.length > 0) {+ const shown = supported.slice(0, FLOATER_NAMES_SHOWN);+ if (supported.length > shown.length)+ shown.push(`+${supported.length - shown.length} more`);+ warnings.push(`Declared external support (requirements.externalSupport): ${shown.join(", ")} rest on a support composed outside this asset; information only, no action needed.`);+ }}return warnings;}diff --git a/dist/build.json b/dist/build.jsonindex 7f512c67..0e1a4b91 100644--- a/dist/build.json+++ b/dist/build.json@@ -2,10 +2,10 @@"schemaVersion": 1,"entries": {"worker": {- "identity": "sha256:fb9b1409ce7a7d5ce24f06828658b013762cecc801aaf70c31fdd41d44d4c8c2",+ "identity": "sha256:a9d192f91e1e95b12632695341dda15867120f57f7b7b3aa68cee64fd11d4006","engineVersion": "1.3.1","toolchain": "[email protected]",- "sourceHash": "5ee9b6bf3672d303291bb8fe18ddb673dacadb219640d1f1cea82b3f9ac7519b",+ "sourceHash": "4f6b8ae26e6f2abdbe2ecb58b51f3c401175d70fd8ba63fe4880dae50511565c","rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a","dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3","dependencies": {@@ -37,13 +37,13 @@},"target": "node","file": "evaluator-worker.mjs",- "bundleHash": "sha256:eb4c421782d3d96e7f4ba04072ecdca10af471d17299bc42a1e0e2fc4c54c421"+ "bundleHash": "sha256:326aaf15bc9181bc8ef5b2cf02861c33cc7848347e50830f288330121c0d1f0e"},"agent-run": {- "identity": "sha256:fb9b1409ce7a7d5ce24f06828658b013762cecc801aaf70c31fdd41d44d4c8c2",+ "identity": "sha256:a9d192f91e1e95b12632695341dda15867120f57f7b7b3aa68cee64fd11d4006","engineVersion": "1.3.1","toolchain": "[email protected]",- "sourceHash": "5ee9b6bf3672d303291bb8fe18ddb673dacadb219640d1f1cea82b3f9ac7519b",+ "sourceHash": "4f6b8ae26e6f2abdbe2ecb58b51f3c401175d70fd8ba63fe4880dae50511565c","rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a","dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3","dependencies": {@@ -75,13 +75,13 @@},"target": "node","file": "agent-run.mjs",- "bundleHash": "sha256:74d69033c8ffa36f7b060a54845f71a0d7d4cd5e9ec60237d080ec7f5e374d8f"+ "bundleHash": "sha256:40e510f17106f36cc81195e1ea3309deb743ba601f0081d6744685d4f297a32e"},"agent-providers": {- "identity": "sha256:fb9b1409ce7a7d5ce24f06828658b013762cecc801aaf70c31fdd41d44d4c8c2",+ "identity": "sha256:a9d192f91e1e95b12632695341dda15867120f57f7b7b3aa68cee64fd11d4006","engineVersion": "1.3.1","toolchain": "[email protected]",- "sourceHash": "5ee9b6bf3672d303291bb8fe18ddb673dacadb219640d1f1cea82b3f9ac7519b",+ "sourceHash": "4f6b8ae26e6f2abdbe2ecb58b51f3c401175d70fd8ba63fe4880dae50511565c","rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a","dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3","dependencies": {@@ -116,10 +116,10 @@"bundleHash": "sha256:9d6faf03d307321bc2e3bd5ce5bdee0bbbf61e0ebed8bfebfa1fb072287b83fa"},"mcp": {- "identity": "sha256:fb9b1409ce7a7d5ce24f06828658b013762cecc801aaf70c31fdd41d44d4c8c2",+ "identity": "sha256:a9d192f91e1e95b12632695341dda15867120f57f7b7b3aa68cee64fd11d4006","engineVersion": "1.3.1","toolchain": "[email protected]",- "sourceHash": "5ee9b6bf3672d303291bb8fe18ddb673dacadb219640d1f1cea82b3f9ac7519b",+ "sourceHash": "4f6b8ae26e6f2abdbe2ecb58b51f3c401175d70fd8ba63fe4880dae50511565c","rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a","dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3","dependencies": {@@ -154,10 +154,10 @@"bundleHash": "sha256:a246b2c79d629a332cef4430dbe742b0c4a0d2f04f0281e673c3c60ff22706da"},"cli": {- "identity": "sha256:fb9b1409ce7a7d5ce24f06828658b013762cecc801aaf70c31fdd41d44d4c8c2",+ "identity": "sha256:a9d192f91e1e95b12632695341dda15867120f57f7b7b3aa68cee64fd11d4006","engineVersion": "1.3.1","toolchain": "[email protected]",- "sourceHash": "5ee9b6bf3672d303291bb8fe18ddb673dacadb219640d1f1cea82b3f9ac7519b",+ "sourceHash": "4f6b8ae26e6f2abdbe2ecb58b51f3c401175d70fd8ba63fe4880dae50511565c","rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a","dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3","dependencies": {@@ -189,13 +189,13 @@},"target": "node","file": "cli.mjs",- "bundleHash": "sha256:689fbdd3acf0742745c2e579ac399dccd49363113afd474208136ab26bdda194"+ "bundleHash": "sha256:d81bc1f41df8bae96caa68af5ba692f2414038bb25827ebc3d5d6875fbcd2819"},"engine": {- "identity": "sha256:fb9b1409ce7a7d5ce24f06828658b013762cecc801aaf70c31fdd41d44d4c8c2",+ "identity": "sha256:a9d192f91e1e95b12632695341dda15867120f57f7b7b3aa68cee64fd11d4006","engineVersion": "1.3.1","toolchain": "[email protected]",- "sourceHash": "5ee9b6bf3672d303291bb8fe18ddb673dacadb219640d1f1cea82b3f9ac7519b",+ "sourceHash": "4f6b8ae26e6f2abdbe2ecb58b51f3c401175d70fd8ba63fe4880dae50511565c","rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a","dependencyHash": "20b5b45a138ab83d340e78729d1a427bdc9b8aeadc47c5f7acf907eab43377f3","dependencies": {@@ -227,7 +227,7 @@},"target": "node","file": "mcp-engine.mjs",- "bundleHash": "sha256:4aa709eeff1d69fd57dfecf6a3f49c9a0a669484ad8ac40caab4ec1fa850f06e"+ "bundleHash": "sha256:4c28e9a7f4eb98ff72e5f5592e8b906fcf951034152458b85cbc12aacd2067f8"}}}diff --git a/dist/cli.mjs b/dist/cli.mjsindex ae0e8f01..7c33e499 100644--- a/dist/cli.mjs+++ b/dist/cli.mjs@@ -11004,6 +11004,25 @@ var init_prop = __esm(() => {];});+// src/external-support.ts+function restingSupport(mesh, bottomY, supports) {+ return declaredSupports(mesh, supports).find((support) => Math.abs(bottomY - support.planeY) <= (support.tolerance ?? EXTERNAL_SUPPORT_TOLERANCE));+}+function declaredSupports(mesh, supports) {+ if (!supports?.length)+ return [];+ const names = new Set;+ for (let node = mesh;node; node = node.parent) {+ if (!node.name)+ continue;+ names.add(node.name);+ if (node.name.startsWith("Mesh_"))+ names.add(node.name.slice(5));+ }+ return supports.filter((support) => support.parts.some((part) => names.has(part)));+}+var EXTERNAL_SUPPORT_TOLERANCE = 0.02;+// src/delivery.tsimport * as THREE15 from "three";import { ConvexGeometry } from "three/addons/geometries/ConvexGeometry.js";@@ -11375,7 +11394,7 @@ var init_lod2 = __esm(() => {// src/qa/part-connectivity.tsimport * as THREE16 from "three";-function collectParts2(root, exempt) {+function collectParts2(root, exempt, supports) {const parts = [];let lodExcluded = 0;root.updateWorldMatrix(true, true);@@ -11395,7 +11414,8 @@ function collectParts2(root, exempt) {const box = new THREE16.Box3().setFromObject(mesh);if (box.isEmpty())return;- parts.push({ name, box });+ const support = restingSupport(mesh, box.min.y, supports);+ parts.push({ name, box, ...support ? { support } : {} });});return { parts, lodExcluded };}@@ -11405,9 +11425,9 @@ function boxGap(a, b) {const dz = Math.max(0, Math.max(a.min.z - b.max.z, b.min.z - a.max.z));return Math.hypot(dx, dy, dz);}-function analyzePartConnectivity(root) {+function analyzePartConnectivity(root, supports) {const exempt = [];- const { parts, lodExcluded } = collectParts2(root, exempt);+ const { parts, lodExcluded } = collectParts2(root, exempt, supports);const report = {partsAnalyzed: parts.length,mainComponentSize: parts.length,@@ -11468,22 +11488,48 @@ function analyzePartConnectivity(root) {gap = Math.min(gap, boxGap(parts[m].box, parts[b].box));}}+ const lowest = members.reduce((a, b) => parts[b].box.min.y < parts[a].box.min.y ? b : a);+ const support = parts[lowest].support;report.groups.push({parts: members.map((m) => parts[m].name),- gap: Math.round(gap * 1e6) / 1e6+ gap: Math.round(gap * 1e6) / 1e6,+ ...support && members.every((m) => parts[m].support) ? {+ externalSupport: {+ planeY: support.planeY,+ bottomY: Math.round(parts[lowest].box.min.y * 1e6) / 1e6,+ tolerance: support.tolerance ?? CONNECTIVITY_TOLERANCE+ }+ } : {}});}report.groups.sort((a, b) => b.parts.length - a.parts.length || a.gap - b.gap);return report;}-function inspectPartConnectivity(scene) {+function inspectPartConnectivity(scene, supports) {if (!(scene instanceof THREE16.Object3D))return [];- const report = analyzePartConnectivity(scene);+ const report = analyzePartConnectivity(scene, supports);const lodNote = report.lodExcluded === 1 ? " 1 part on an LOD level above 0 was not analyzed." : report.lodExcluded > 1 ? ` ${report.lodExcluded} parts on LOD levels above 0 were not analyzed.` : "";return report.groups.map((group) => {const listed = group.parts.map((p) => JSON.stringify(p)).join(", ");const subject = group.parts.length === 1 ? `Part ${listed} is` : `A group of ${group.parts.length} parts (${listed}) is`;+ const declared = group.externalSupport;+ if (declared)+ return {+ code: "GEO_PART_EXTERNAL_SUPPORT",+ disposition: "observe",+ dimension: "visualQuality",+ profile: "geometry.partConnectivity",+ message: `${subject} separate from the largest component and rests on the support declared in requirements.externalSupport at Y=${declared.planeY.toFixed(3)} m (bottom at Y=${declared.bottomY.toFixed(3)} m). Information only: the support is composed outside this asset.${lodNote}`,+ affected: { node: group.parts[0] },+ measurement: {+ name: "bottomToSupportPlane",+ actual: declared.bottomY,+ expected: declared.planeY,+ threshold: declared.tolerance+ },+ repairText: "No change is needed for a declared support. Remove the part from requirements.externalSupport if it should attach within this asset."+ };return {code: "GEO_PART_CONNECTIVITY",disposition: "observe",@@ -14250,7 +14296,7 @@ function createAssetRequirementsV1(input = {}) {...input});}-var text, positive2, nonnegative, count2, names, marker, roof, structure, effects, requirements, AssetRequirementsV1Schema;+var text, positive2, nonnegative, count2, names, marker, supportParts, roof, structure, effects, requirements, AssetRequirementsV1Schema;var init_requirements = __esm(() => {init_asset();init_breadth();@@ -14262,6 +14308,9 @@ var init_requirements = __esm(() => {message: "Values must be unique."});marker = z.strictObject({});+ supportParts = z.array(text).min(1).max(256).refine((values) => new Set(values).size === values.length, {+ message: "Values must be unique."+ });roof = z.strictObject({type: text.optional(),ridgeAxis: z.enum(["x", "z"]).optional(),@@ -14381,6 +14430,13 @@ var init_requirements = __esm(() => {precomputedTangents: z.boolean().optional(),skinned: z.boolean().optional()})).optional(),+ externalSupport: statement(z.strictObject({+ supports: z.array(z.strictObject({+ parts: supportParts,+ planeY: z.number().finite(),+ tolerance: nonnegative.max(0.5).optional()+ })).min(1).max(32)+ })).optional(),access: statement(z.strictObject({ enterable: z.boolean().optional(), driveable: z.boolean().optional() })).optional()});AssetRequirementsV1Schema = z.strictObject({@@ -19776,7 +19832,8 @@ function resolveRequirementsApplicability(requirements) {grounding: ["planeY"],bounds: ["units", "x", "y", "z"],animation: ["clips"],- representation: ["precomputedTangents"]+ representation: ["precomputedTangents"],+ externalSupport: ["supports"]};for (const [key, statement] of Object.entries(requirements.requirements)) {if (statement?.state !== "requested")@@ -20571,7 +20628,7 @@ function runRequirementsSceneQa(context, scene, clips, policy = {}, evidence = {findings.push(decision.mode === "observe" || decision.mode === "warn" ? { ...finding, disposition: decision.mode } : finding);continue;}- const measured = decision.ruleId === SWEEP_QA_RULE.id ? inspectSweepGeometry(scene) : decision.ruleId === PART_CONNECTIVITY_QA_RULE.id ? inspectPartConnectivity(scene) : decision.ruleId === ASSET_SCOPE_QA_RULE.id && scope?.state === "requested" ? inspectAssetScope({+ const measured = decision.ruleId === SWEEP_QA_RULE.id ? inspectSweepGeometry(scene) : decision.ruleId === PART_CONNECTIVITY_QA_RULE.id ? inspectPartConnectivity(scene, needs.externalSupport?.state === "requested" ? needs.externalSupport.value.supports : undefined) : decision.ruleId === ASSET_SCOPE_QA_RULE.id && scope?.state === "requested" ? inspectAssetScope({profile: "asset.requirements.v1",scope: { schemaVersion: 1, scope: scope.value, explicit: true },derivedEvidence: { source: "engine-scene-analysis", assetScope: scopeObservation }@@ -38270,7 +38327,10 @@ async function renderSceneToGLB(root, opts = {}) {const materialResourceProvenance = collectMaterialResourceProvenance(root);for (const w of inspectGeneratedAnimation(root, clips))warnings.push(w);- for (const w of inspectSceneStructure(root))+ const externalSupport = requirements.requirements.requirements.externalSupport;+ for (const w of inspectSceneStructure(root, {+ ...externalSupport?.state === "requested" ? { externalSupport: externalSupport.value.supports } : {}+ }))warnings.push(w);const atlas = collectAtlasProvenance(root);const bakedTextures = await bakeSceneTextures(root, warnings);@@ -38606,6 +38666,7 @@ function collectMeshStats(root) {box.getCenter(center);box.getSize(size);out.push({+ object: obj,name: obj.name || "(unnamed)",triCount: Math.floor(tri),isPlaneGeo: geo.type === "PlaneGeometry",@@ -38664,6 +38725,7 @@ function inspectSceneStructure(root, opts = {}) {}if (meshes.length > 1) {const floaters = [];+ const supported = [];for (let i = 0;i < meshes.length; i++) {const a = meshes[i];const ax = a.box.clone().expandByScalar(FLOATING_EXPAND);@@ -38679,6 +38741,12 @@ function inspectSceneStructure(root, opts = {}) {}if (overlapsAny)continue;+ const support = restingSupport(a.object, a.box.min.y, opts.externalSupport);+ if (support) {+ supported.push(`${a.name} at Y=${support.planeY.toFixed(3)}`);+ continue;+ }+ const declared = declaredSupports(a.object, opts.externalSupport)[0];let nearest;let nearestGap;for (let j = 0;j < meshes.length; j++) {@@ -38691,7 +38759,8 @@ function inspectSceneStructure(root, opts = {}) {}}const fix = nearest && nearestGap ? ` Fix: shift "${a.name}" by [${nearestGap.x.toFixed(3)}, ${nearestGap.y.toFixed(3)}, ${nearestGap.z.toFixed(3)}] toward "${nearest.name}", or call snapTo(part, hostPart) to do it automatically.` : "";- floaters.push({ name: a.name, fix });+ const mismatch = declared ? ` It is named in a declared external support at Y=${declared.planeY.toFixed(3)}, but its bottom is at Y=${a.box.min.y.toFixed(3)}.` : "";+ floaters.push({ name: a.name, fix: fix + mismatch });}if (floaters.length > 0) {const entries = floaters.slice(0, FLOATER_FIXES_SHOWN).map(({ name, fix }) => `${name}${fix ? ` —${fix}` : ""}`);@@ -38704,6 +38773,12 @@ function inspectSceneStructure(root, opts = {}) {}warnings.push(`Floating parts (no mesh overlap with any sibling, 2cm tol): ${entries.join(" | ")}`);}+ if (supported.length > 0) {+ const shown = supported.slice(0, FLOATER_NAMES_SHOWN);+ if (supported.length > shown.length)+ shown.push(`+${supported.length - shown.length} more`);+ warnings.push(`Declared external support (requirements.externalSupport): ${shown.join(", ")} rest on a support composed outside this asset; information only, no action needed.`);+ }}return warnings;}diff --git a/dist/evaluator-worker.mjs b/dist/evaluator-worker.mjsindex 57dbceb8..f9addfc4 100644--- a/dist/evaluator-worker.mjs+++ b/dist/evaluator-worker.mjs@@ -170,6 +170,25 @@ var init_solid_diagnostic = __esm(() => {};});+// src/external-support.ts+function restingSupport(mesh, bottomY, supports) {+ return declaredSupports(mesh, supports).find((support) => Math.abs(bottomY - support.planeY) <= (support.tolerance ?? EXTERNAL_SUPPORT_TOLERANCE));+}+function declaredSupports(mesh, supports) {+ if (!supports?.length)+ return [];+ const names = new Set;+ for (let node = mesh;node; node = node.parent) {+ if (!node.name)+ continue;+ names.add(node.name);+ if (node.name.startsWith("Mesh_"))+ names.add(node.name.slice(5));+ }+ return supports.filter((support) => support.parts.some((part) => names.has(part)));+}+var EXTERNAL_SUPPORT_TOLERANCE = 0.02;+// src/contracts/breadth.tsfunction cloneVfxIntentV1(value) {return {@@ -707,7 +726,7 @@ function createAssetRequirementsV1(input = {}) {...input});}-var text, positive, nonnegative, count2, names, marker, roof, structure, effects, requirements, AssetRequirementsV1Schema;+var text, positive, nonnegative, count2, names, marker, supportParts, roof, structure, effects, requirements, AssetRequirementsV1Schema;var init_requirements = __esm(() => {init_asset();init_breadth();@@ -719,6 +738,9 @@ var init_requirements = __esm(() => {message: "Values must be unique."});marker = z.strictObject({});+ supportParts = z.array(text).min(1).max(256).refine((values) => new Set(values).size === values.length, {+ message: "Values must be unique."+ });roof = z.strictObject({type: text.optional(),ridgeAxis: z.enum(["x", "z"]).optional(),@@ -838,6 +860,13 @@ var init_requirements = __esm(() => {precomputedTangents: z.boolean().optional(),skinned: z.boolean().optional()})).optional(),+ externalSupport: statement(z.strictObject({+ supports: z.array(z.strictObject({+ parts: supportParts,+ planeY: z.number().finite(),+ tolerance: nonnegative.max(0.5).optional()+ })).min(1).max(32)+ })).optional(),access: statement(z.strictObject({ enterable: z.boolean().optional(), driveable: z.boolean().optional() })).optional()});AssetRequirementsV1Schema = z.strictObject({@@ -6937,7 +6966,7 @@ var init_lod2 = __esm(() => {// src/qa/part-connectivity.tsimport * as THREE9 from "three";-function collectParts2(root, exempt) {+function collectParts2(root, exempt, supports) {const parts = [];let lodExcluded = 0;root.updateWorldMatrix(true, true);@@ -6957,7 +6986,8 @@ function collectParts2(root, exempt) {const box = new THREE9.Box3().setFromObject(mesh);if (box.isEmpty())return;- parts.push({ name, box });+ const support = restingSupport(mesh, box.min.y, supports);+ parts.push({ name, box, ...support ? { support } : {} });});return { parts, lodExcluded };}@@ -6967,9 +6997,9 @@ function boxGap(a, b) {const dz = Math.max(0, Math.max(a.min.z - b.max.z, b.min.z - a.max.z));return Math.hypot(dx, dy, dz);}-function analyzePartConnectivity(root) {+function analyzePartConnectivity(root, supports) {const exempt = [];- const { parts, lodExcluded } = collectParts2(root, exempt);+ const { parts, lodExcluded } = collectParts2(root, exempt, supports);const report = {partsAnalyzed: parts.length,mainComponentSize: parts.length,@@ -7030,22 +7060,48 @@ function analyzePartConnectivity(root) {gap = Math.min(gap, boxGap(parts[m].box, parts[b].box));}}+ const lowest = members.reduce((a, b) => parts[b].box.min.y < parts[a].box.min.y ? b : a);+ const support = parts[lowest].support;report.groups.push({parts: members.map((m) => parts[m].name),- gap: Math.round(gap * 1e6) / 1e6+ gap: Math.round(gap * 1e6) / 1e6,+ ...support && members.every((m) => parts[m].support) ? {+ externalSupport: {+ planeY: support.planeY,+ bottomY: Math.round(parts[lowest].box.min.y * 1e6) / 1e6,+ tolerance: support.tolerance ?? CONNECTIVITY_TOLERANCE+ }+ } : {}});}report.groups.sort((a, b) => b.parts.length - a.parts.length || a.gap - b.gap);return report;}-function inspectPartConnectivity(scene) {+function inspectPartConnectivity(scene, supports) {if (!(scene instanceof THREE9.Object3D))return [];- const report = analyzePartConnectivity(scene);+ const report = analyzePartConnectivity(scene, supports);const lodNote = report.lodExcluded === 1 ? " 1 part on an LOD level above 0 was not analyzed." : report.lodExcluded > 1 ? ` ${report.lodExcluded} parts on LOD levels above 0 were not analyzed.` : "";return report.groups.map((group) => {const listed = group.parts.map((p) => JSON.stringify(p)).join(", ");const subject = group.parts.length === 1 ? `Part ${listed} is` : `A group of ${group.parts.length} parts (${listed}) is`;+ const declared = group.externalSupport;+ if (declared)+ return {+ code: "GEO_PART_EXTERNAL_SUPPORT",+ disposition: "observe",+ dimension: "visualQuality",+ profile: "geometry.partConnectivity",+ message: `${subject} separate from the largest component and rests on the support declared in requirements.externalSupport at Y=${declared.planeY.toFixed(3)} m (bottom at Y=${declared.bottomY.toFixed(3)} m). Information only: the support is composed outside this asset.${lodNote}`,+ affected: { node: group.parts[0] },+ measurement: {+ name: "bottomToSupportPlane",+ actual: declared.bottomY,+ expected: declared.planeY,+ threshold: declared.tolerance+ },+ repairText: "No change is needed for a declared support. Remove the part from requirements.externalSupport if it should attach within this asset."+ };return {code: "GEO_PART_CONNECTIVITY",disposition: "observe",@@ -13733,7 +13789,8 @@ function resolveRequirementsApplicability(requirements) {grounding: ["planeY"],bounds: ["units", "x", "y", "z"],animation: ["clips"],- representation: ["precomputedTangents"]+ representation: ["precomputedTangents"],+ externalSupport: ["supports"]};for (const [key, statement] of Object.entries(requirements.requirements)) {if (statement?.state !== "requested")@@ -14186,7 +14243,7 @@ function runRequirementsSceneQa(context, scene, clips, policy = {}, evidence = {findings.push(decision.mode === "observe" || decision.mode === "warn" ? { ...finding, disposition: decision.mode } : finding);continue;}- const measured = decision.ruleId === SWEEP_QA_RULE.id ? inspectSweepGeometry(scene) : decision.ruleId === PART_CONNECTIVITY_QA_RULE.id ? inspectPartConnectivity(scene) : decision.ruleId === ASSET_SCOPE_QA_RULE.id && scope?.state === "requested" ? inspectAssetScope({+ const measured = decision.ruleId === SWEEP_QA_RULE.id ? inspectSweepGeometry(scene) : decision.ruleId === PART_CONNECTIVITY_QA_RULE.id ? inspectPartConnectivity(scene, needs.externalSupport?.state === "requested" ? needs.externalSupport.value.supports : undefined) : decision.ruleId === ASSET_SCOPE_QA_RULE.id && scope?.state === "requested" ? inspectAssetScope({profile: "asset.requirements.v1",scope: { schemaVersion: 1, scope: scope.value, explicit: true },derivedEvidence: { source: "engine-scene-analysis", assetScope: scopeObservation }@@ -33617,7 +33674,10 @@ async function renderSceneToGLB(root, opts = {}) {const materialResourceProvenance = collectMaterialResourceProvenance(root);for (const w of inspectGeneratedAnimation(root, clips))warnings.push(w);- for (const w of inspectSceneStructure(root))+ const externalSupport = requirements.requirements.requirements.externalSupport;+ for (const w of inspectSceneStructure(root, {+ ...externalSupport?.state === "requested" ? { externalSupport: externalSupport.value.supports } : {}+ }))warnings.push(w);const atlas = collectAtlasProvenance(root);const bakedTextures = await bakeSceneTextures(root, warnings);@@ -33943,6 +34003,7 @@ function collectMeshStats(root) {box.getCenter(center);box.getSize(size);out.push({+ object: obj,name: obj.name || "(unnamed)",triCount: Math.floor(tri),isPlaneGeo: geo.type === "PlaneGeometry",@@ -34001,6 +34062,7 @@ function inspectSceneStructure(root, opts = {}) {}if (meshes.length > 1) {const floaters = [];+ const supported = [];for (let i = 0;i < meshes.length; i++) {const a = meshes[i];const ax = a.box.clone().expandByScalar(FLOATING_EXPAND);@@ -34016,6 +34078,12 @@ function inspectSceneStructure(root, opts = {}) {}if (overlapsAny)continue;+ const support = restingSupport(a.object, a.box.min.y, opts.externalSupport);+ if (support) {+ supported.push(`${a.name} at Y=${support.planeY.toFixed(3)}`);+ continue;+ }+ const declared = declaredSupports(a.object, opts.externalSupport)[0];let nearest;let nearestGap;for (let j = 0;j < meshes.length; j++) {@@ -34028,7 +34096,8 @@ function inspectSceneStructure(root, opts = {}) {}}const fix = nearest && nearestGap ? ` Fix: shift "${a.name}" by [${nearestGap.x.toFixed(3)}, ${nearestGap.y.toFixed(3)}, ${nearestGap.z.toFixed(3)}] toward "${nearest.name}", or call snapTo(part, hostPart) to do it automatically.` : "";- floaters.push({ name: a.name, fix });+ const mismatch = declared ? ` It is named in a declared external support at Y=${declared.planeY.toFixed(3)}, but its bottom is at Y=${a.box.min.y.toFixed(3)}.` : "";+ floaters.push({ name: a.name, fix: fix + mismatch });}if (floaters.length > 0) {const entries = floaters.slice(0, FLOATER_FIXES_SHOWN).map(({ name, fix }) => `${name}${fix ? ` —${fix}` : ""}`);@@ -34041,6 +34110,12 @@ function inspectSceneStructure(root, opts = {}) {}warnings.push(`Floating parts (no mesh overlap with any sibling, 2cm tol): ${entries.join(" | ")}`);}+ if (supported.length > 0) {+ const shown = supported.slice(0, FLOATER_NAMES_SHOWN);+ if (supported.length > shown.length)+ shown.push(`+${supported.length - shown.length} more`);+ warnings.push(`Declared external support (requirements.externalSupport): ${shown.join(", ")} rest on a support composed outside this asset; information only, no action needed.`);+ }}return warnings;}diff --git a/dist/mcp-engine.mjs b/dist/mcp-engine.mjsindex 4125a899..a735b688 100644--- a/dist/mcp-engine.mjs+++ b/dist/mcp-engine.mjs@@ -16836,6 +16836,25 @@ var init_prop = __esm(() => {];});+// src/external-support.ts+function restingSupport(mesh, bottomY, supports) {+ return declaredSupports(mesh, supports).find((support) => Math.abs(bottomY - support.planeY) <= (support.tolerance ?? EXTERNAL_SUPPORT_TOLERANCE));+}+function declaredSupports(mesh, supports) {+ if (!supports?.length)+ return [];+ const names = new Set;+ for (let node = mesh;node; node = node.parent) {+ if (!node.name)+ continue;+ names.add(node.name);+ if (node.name.startsWith("Mesh_"))+ names.add(node.name.slice(5));+ }+ return supports.filter((support) => support.parts.some((part) => names.has(part)));+}+var EXTERNAL_SUPPORT_TOLERANCE = 0.02;+// src/lod.tsfunction lodName(name) {const match = LOD_TOKEN.exec(name);@@ -16989,7 +17008,7 @@ var init_lod2 = __esm(() => {// src/qa/part-connectivity.tsimport * as THREE22 from "three";-function collectParts2(root, exempt) {+function collectParts2(root, exempt, supports) {const parts = [];let lodExcluded = 0;root.updateWorldMatrix(true, true);@@ -17009,7 +17028,8 @@ function collectParts2(root, exempt) {const box = new THREE22.Box3().setFromObject(mesh);if (box.isEmpty())return;- parts.push({ name, box });+ const support = restingSupport(mesh, box.min.y, supports);+ parts.push({ name, box, ...support ? { support } : {} });});return { parts, lodExcluded };}@@ -17019,9 +17039,9 @@ function boxGap(a, b) {const dz = Math.max(0, Math.max(a.min.z - b.max.z, b.min.z - a.max.z));return Math.hypot(dx, dy, dz);}-function analyzePartConnectivity(root) {+function analyzePartConnectivity(root, supports) {const exempt = [];- const { parts, lodExcluded } = collectParts2(root, exempt);+ const { parts, lodExcluded } = collectParts2(root, exempt, supports);const report = {partsAnalyzed: parts.length,mainComponentSize: parts.length,@@ -17082,22 +17102,48 @@ function analyzePartConnectivity(root) {gap = Math.min(gap, boxGap(parts[m].box, parts[b].box));}}+ const lowest = members.reduce((a, b) => parts[b].box.min.y < parts[a].box.min.y ? b : a);+ const support = parts[lowest].support;report.groups.push({parts: members.map((m) => parts[m].name),- gap: Math.round(gap * 1e6) / 1e6+ gap: Math.round(gap * 1e6) / 1e6,+ ...support && members.every((m) => parts[m].support) ? {+ externalSupport: {+ planeY: support.planeY,+ bottomY: Math.round(parts[lowest].box.min.y * 1e6) / 1e6,+ tolerance: support.tolerance ?? CONNECTIVITY_TOLERANCE+ }+ } : {}});}report.groups.sort((a, b) => b.parts.length - a.parts.length || a.gap - b.gap);return report;}-function inspectPartConnectivity(scene) {+function inspectPartConnectivity(scene, supports) {if (!(scene instanceof THREE22.Object3D))return [];- const report = analyzePartConnectivity(scene);+ const report = analyzePartConnectivity(scene, supports);const lodNote = report.lodExcluded === 1 ? " 1 part on an LOD level above 0 was not analyzed." : report.lodExcluded > 1 ? ` ${report.lodExcluded} parts on LOD levels above 0 were not analyzed.` : "";return report.groups.map((group) => {const listed = group.parts.map((p) => JSON.stringify(p)).join(", ");const subject = group.parts.length === 1 ? `Part ${listed} is` : `A group of ${group.parts.length} parts (${listed}) is`;+ const declared = group.externalSupport;+ if (declared)+ return {+ code: "GEO_PART_EXTERNAL_SUPPORT",+ disposition: "observe",+ dimension: "visualQuality",+ profile: "geometry.partConnectivity",+ message: `${subject} separate from the largest component and rests on the support declared in requirements.externalSupport at Y=${declared.planeY.toFixed(3)} m (bottom at Y=${declared.bottomY.toFixed(3)} m). Information only: the support is composed outside this asset.${lodNote}`,+ affected: { node: group.parts[0] },+ measurement: {+ name: "bottomToSupportPlane",+ actual: declared.bottomY,+ expected: declared.planeY,+ threshold: declared.tolerance+ },+ repairText: "No change is needed for a declared support. Remove the part from requirements.externalSupport if it should attach within this asset."+ };return {code: "GEO_PART_CONNECTIVITY",disposition: "observe",@@ -19861,7 +19907,7 @@ function createAssetRequirementsV1(input = {}) {...input});}-var text2, positive2, nonnegative, count3, names, marker, roof, structure, effects, requirements, AssetRequirementsV1Schema;+var text2, positive2, nonnegative, count3, names, marker, supportParts, roof, structure, effects, requirements, AssetRequirementsV1Schema;var init_requirements = __esm(() => {init_asset();init_breadth();@@ -19873,6 +19919,9 @@ var init_requirements = __esm(() => {message: "Values must be unique."});marker = z5.strictObject({});+ supportParts = z5.array(text2).min(1).max(256).refine((values) => new Set(values).size === values.length, {+ message: "Values must be unique."+ });roof = z5.strictObject({type: text2.optional(),ridgeAxis: z5.enum(["x", "z"]).optional(),@@ -19992,6 +20041,13 @@ var init_requirements = __esm(() => {precomputedTangents: z5.boolean().optional(),skinned: z5.boolean().optional()})).optional(),+ externalSupport: statement(z5.strictObject({+ supports: z5.array(z5.strictObject({+ parts: supportParts,+ planeY: z5.number().finite(),+ tolerance: nonnegative.max(0.5).optional()+ })).min(1).max(32)+ })).optional(),access: statement(z5.strictObject({ enterable: z5.boolean().optional(), driveable: z5.boolean().optional() })).optional()});AssetRequirementsV1Schema = z5.strictObject({@@ -20288,7 +20344,8 @@ function resolveRequirementsApplicability(requirements) {grounding: ["planeY"],bounds: ["units", "x", "y", "z"],animation: ["clips"],- representation: ["precomputedTangents"]+ representation: ["precomputedTangents"],+ externalSupport: ["supports"]};for (const [key, statement] of Object.entries(requirements.requirements)) {if (statement?.state !== "requested")@@ -21001,7 +21058,7 @@ function runRequirementsSceneQa(context, scene, clips, policy = {}, evidence = {findings.push(decision.mode === "observe" || decision.mode === "warn" ? { ...finding, disposition: decision.mode } : finding);continue;}- const measured = decision.ruleId === SWEEP_QA_RULE.id ? inspectSweepGeometry(scene) : decision.ruleId === PART_CONNECTIVITY_QA_RULE.id ? inspectPartConnectivity(scene) : decision.ruleId === ASSET_SCOPE_QA_RULE.id && scope?.state === "requested" ? inspectAssetScope({+ const measured = decision.ruleId === SWEEP_QA_RULE.id ? inspectSweepGeometry(scene) : decision.ruleId === PART_CONNECTIVITY_QA_RULE.id ? inspectPartConnectivity(scene, needs.externalSupport?.state === "requested" ? needs.externalSupport.value.supports : undefined) : decision.ruleId === ASSET_SCOPE_QA_RULE.id && scope?.state === "requested" ? inspectAssetScope({profile: "asset.requirements.v1",scope: { schemaVersion: 1, scope: scope.value, explicit: true },derivedEvidence: { source: "engine-scene-analysis", assetScope: scopeObservation }@@ -37814,7 +37871,10 @@ async function renderSceneToGLB(root, opts = {}) {const materialResourceProvenance = collectMaterialResourceProvenance(root);for (const w of inspectGeneratedAnimation(root, clips))warnings.push(w);- for (const w of inspectSceneStructure(root))+ const externalSupport = requirements.requirements.requirements.externalSupport;+ for (const w of inspectSceneStructure(root, {+ ...externalSupport?.state === "requested" ? { externalSupport: externalSupport.value.supports } : {}+ }))warnings.push(w);const atlas = collectAtlasProvenance(root);const bakedTextures = await bakeSceneTextures(root, warnings);@@ -38150,6 +38210,7 @@ function collectMeshStats(root) {box.getCenter(center);box.getSize(size);out.push({+ object: obj,name: obj.name || "(unnamed)",triCount: Math.floor(tri),isPlaneGeo: geo.type === "PlaneGeometry",@@ -38208,6 +38269,7 @@ function inspectSceneStructure(root, opts = {}) {}if (meshes.length > 1) {const floaters = [];+ const supported = [];for (let i = 0;i < meshes.length; i++) {const a = meshes[i];const ax = a.box.clone().expandByScalar(FLOATING_EXPAND);@@ -38223,6 +38285,12 @@ function inspectSceneStructure(root, opts = {}) {}if (overlapsAny)continue;+ const support = restingSupport(a.object, a.box.min.y, opts.externalSupport);+ if (support) {+ supported.push(`${a.name} at Y=${support.planeY.toFixed(3)}`);+ continue;+ }+ const declared = declaredSupports(a.object, opts.externalSupport)[0];let nearest;let nearestGap;for (let j = 0;j < meshes.length; j++) {@@ -38235,7 +38303,8 @@ function inspectSceneStructure(root, opts = {}) {}}const fix = nearest && nearestGap ? ` Fix: shift "${a.name}" by [${nearestGap.x.toFixed(3)}, ${nearestGap.y.toFixed(3)}, ${nearestGap.z.toFixed(3)}] toward "${nearest.name}", or call snapTo(part, hostPart) to do it automatically.` : "";- floaters.push({ name: a.name, fix });+ const mismatch = declared ? ` It is named in a declared external support at Y=${declared.planeY.toFixed(3)}, but its bottom is at Y=${a.box.min.y.toFixed(3)}.` : "";+ floaters.push({ name: a.name, fix: fix + mismatch });}if (floaters.length > 0) {const entries = floaters.slice(0, FLOATER_FIXES_SHOWN).map(({ name, fix }) => `${name}${fix ? ` —${fix}` : ""}`);@@ -38248,6 +38317,12 @@ function inspectSceneStructure(root, opts = {}) {}warnings.push(`Floating parts (no mesh overlap with any sibling, 2cm tol): ${entries.join(" | ")}`);}+ if (supported.length > 0) {+ const shown = supported.slice(0, FLOATER_NAMES_SHOWN);+ if (supported.length > shown.length)+ shown.push(`+${supported.length - shown.length} more`);+ warnings.push(`Declared external support (requirements.externalSupport): ${shown.join(", ")} rest on a support composed outside this asset; information only, no action needed.`);+ }}return warnings;}diff --git a/docs/migration.md b/docs/migration.mdindex 6a4a1a06..58208f3d 100644--- a/docs/migration.md+++ b/docs/migration.md@@ -440,6 +440,24 @@ session's policy; start a new session to select a reviewed binding. Each boundserver serves one task/asset lineage. Omit the flag for ordinary neutral authoring.Tool arguments and source metadata cannot select or replace the host binding.+A binding can state that named parts rest on a support composed outside the asset,+such as cushions authored for the seat of a separate structure module:++```json+"externalSupport": {+ "state": "requested",+ "value": { "supports": [{ "parts": ["Cushion_L", "BackCushions"], "planeY": 0.45 }] },+ "reason": "The seat is a separate module"+}+```++A part matches by its name, its name without the `Mesh_` prefix that `createPart`+adds, or an ancestor's name. When its world bottom lies within `tolerance` (default+0.02 m) of `planeY`, the floating-parts warning lists it on a separate informational+line and the connectivity observation becomes `GEO_PART_EXTERNAL_SUPPORT`, naming the+declaration. A named part at another height stays a floating part with the mismatch+stated. Other parts and dispositions are unchanged. The declaration is part of the+policy hash; its `reason` is not.## Review explicit legacy data conversionLibrary callers of `@instruktlabs/kiln/qa` now use `collectRequirementsSceneEvidence`diff --git a/src/contracts/requirements.ts b/src/contracts/requirements.tsindex 7420c930..32a18cfb 100644--- a/src/contracts/requirements.ts+++ b/src/contracts/requirements.ts@@ -37,6 +37,13 @@ const names = z.array(text).refine((values) => new Set(values).size === values.lmessage: 'Values must be unique.',});const marker = z.strictObject({});+const supportParts = z+ .array(text)+ .min(1)+ .max(256)+ .refine((values) => new Set(values).size === values.length, {+ message: 'Values must be unique.',+ });/** An absent statement is unspecified. Inference is advice, never an enforced demand. */export type RequirementStatement<T> =@@ -221,6 +228,24 @@ const requirements = z.strictObject({skinned: z.boolean().optional(),}),).optional(),+ /**+ * Named parts rest on a support composed outside this asset, such as cushions on a separate+ * seat module. A detached part whose bottom meets its plane is reported as information.+ */+ externalSupport: statement(+ z.strictObject({+ supports: z+ .array(+ z.strictObject({+ parts: supportParts,+ planeY: z.number().finite(),+ tolerance: nonnegative.max(0.5).optional(),+ }),+ )+ .min(1)+ .max(32),+ }),+ ).optional(),/** Preserve explicit functional capabilities without a semantic category. */access: statement(z.strictObject({ enterable: z.boolean().optional(), driveable: z.boolean().optional() }),diff --git a/src/external-support.ts b/src/external-support.tsnew file mode 100644index 00000000..971ea81b--- /dev/null+++ b/src/external-support.ts@@ -0,0 +1,46 @@+/**+ * Requirements-declared external support (`requirements.externalSupport`): named parts rest+ * on something composed outside this asset, such as cushions on a separate seat module.+ * The declaration is the host's statement; the part's measured bottom must still meet the+ * stated plane before a floating observation is reported as information.+ */+import type * as THREE from 'three';++export interface ExternalSupportV1 {+ /** Part or group names; a mesh matches by its name, its `Mesh_`-less name or an ancestor. */+ parts: string[];+ /** Asset-frame height of the external contact plane, in metres. */+ planeY: number;+ /** Allowed distance between a part's bottom and planeY. Default 0.02 m. */+ tolerance?: number;+}++/** Matches the floating-parts and connectivity adjacency tolerance. */+export const EXTERNAL_SUPPORT_TOLERANCE = 0.02;++/** The support whose parts name this mesh and whose plane its world bottom meets. */+export function restingSupport(+ mesh: THREE.Object3D,+ bottomY: number,+ supports: readonly ExternalSupportV1[] | undefined,+): ExternalSupportV1 | undefined {+ return declaredSupports(mesh, supports).find(+ (support) =>+ Math.abs(bottomY - support.planeY) <= (support.tolerance ?? EXTERNAL_SUPPORT_TOLERANCE),+ );+}++/** Every support that names this mesh or one of its ancestors. */+export function declaredSupports(+ mesh: THREE.Object3D,+ supports: readonly ExternalSupportV1[] | undefined,+): ExternalSupportV1[] {+ if (!supports?.length) return [];+ const names = new Set<string>();+ for (let node: THREE.Object3D | null = mesh; node; node = node.parent) {+ if (!node.name) continue;+ names.add(node.name);+ if (node.name.startsWith('Mesh_')) names.add(node.name.slice(5));+ }+ return supports.filter((support) => support.parts.some((part) => names.has(part)));+}diff --git a/src/qa/external-support.test.ts b/src/qa/external-support.test.tsnew file mode 100644index 00000000..7e42d7f9--- /dev/null+++ b/src/qa/external-support.test.ts@@ -0,0 +1,148 @@+import { expect, test } from 'bun:test';+import * as THREE from 'three';+import { createAssetRequirementsV1, type AssetRequirementsV1 } from '../contracts/requirements';+import { renderSceneToGLB, inspectSceneStructure } from '../render';+import { createAssetRequirementsStore } from '../requirements-store';+import { resolveRequirementsContext } from '../requirements-context';+import { runRequirementsSceneQa } from './requirements-run';++/** Cushions authored to rest on the seat of a separate structure module, as in the Cove pass. */+function cushions() {+ const root = new THREE.Group();+ root.name = 'SofaSoft';+ const box = (name: string, x: number, bottom: number, parent: THREE.Object3D = root) => {+ const mesh = new THREE.Mesh(+ new THREE.BoxGeometry(0.5, 0.15, 0.5),+ new THREE.MeshStandardMaterial(),+ );+ mesh.name = name;+ mesh.position.set(x, bottom + 0.075, 0);+ parent.add(mesh);+ return mesh;+ };+ box('Throw', 0, 0); // on the floor: the main body of this module+ box('Mesh_Cushion_L', -1, 0.45); // createPart('Cushion_L') names its mesh Mesh_Cushion_L+ const back = new THREE.Group();+ back.name = 'BackCushions';+ root.add(back);+ box('Back_A', 1, 0.45, back);+ box('Pillow', 2, 0.6); // declared, but not at the declared seat height+ box('Lamp', -2, 1.6); // not declared+ return root;+}+const SUPPORT: AssetRequirementsV1['requirements'] = {+ externalSupport: {+ state: 'requested',+ value: { supports: [{ parts: ['Cushion_L', 'BackCushions', 'Pillow'], planeY: 0.45 }] },+ reason: 'Seat structure is a separate module',+ },+};+function bind(requirements: AssetRequirementsV1['requirements']) {+ return createAssetRequirementsStore().host.bind(+ { taskId: 'cove', lineageId: 'sofa' },+ createAssetRequirementsV1({ labels: ['prop'], requirements }),+ { actor: 'owner', source: 'brief', reason: 'Fixture requirement' },+ );+}+/** The parts a floating-parts warning reports, not the siblings its fixes point toward. */+const floaterNames = (warning: string | undefined) =>+ (warning ?? '')+ .slice(warning!.indexOf(': ') + 2)+ .split(' | ')+ .map((entry) => entry.split(' —')[0])+ .sort();+const findings = (requirements: AssetRequirementsV1['requirements']) => {+ const report = runRequirementsSceneQa(+ resolveRequirementsContext(bind(requirements)),+ cushions(),+ [],+ {},+ );+ return { report, all: Object.values(report.dimensions).flatMap((d) => d.findings) };+};++test('a declared external support makes those parts informational and leaves the rest alone', () => {+ const { report, all } = findings(SUPPORT);+ expect(report.unevaluatedRequirements).toEqual([]);+ const supported = all.filter((f) => f.code === 'GEO_PART_EXTERNAL_SUPPORT');+ expect(supported.map((f) => f.affected?.node).sort()).toEqual(['Back_A', 'Mesh_Cushion_L']);+ for (const finding of supported) {+ expect(finding.disposition).toBe('observe');+ expect(finding.message).toContain('requirements.externalSupport');+ expect(finding.measurement).toMatchObject({ name: 'bottomToSupportPlane', expected: 0.45 });+ }+ const floating = all.filter((f) => f.code === 'GEO_PART_CONNECTIVITY');+ expect(floating.map((f) => f.affected?.node).sort()).toEqual(['Lamp', 'Pillow']);+ // Without the declaration every detached part keeps the existing observation.+ const plain = findings({}).all.filter((f) => f.code === 'GEO_PART_CONNECTIVITY');+ expect(plain.map((f) => f.affected?.node).sort()).toEqual([+ 'Back_A',+ 'Lamp',+ 'Mesh_Cushion_L',+ 'Pillow',+ ]);+});++test('the floating-parts warning names declared support as information, not as a defect', () => {+ const supports = [{ parts: ['Cushion_L', 'BackCushions', 'Pillow'], planeY: 0.45 }];+ const warnings = inspectSceneStructure(cushions(), { externalSupport: supports });+ const floating = warnings.find((w) => w.startsWith('Floating parts'))!;+ expect(floating).toContain('Lamp');+ expect(floating).toContain('Pillow');+ expect(floating).toContain('declared external support at Y=0.450');+ expect(floaterNames(floating)).toEqual(['Lamp', 'Pillow', 'Throw']);+ const declared = warnings.find((w) => w.startsWith('Declared external support'))!;+ expect(declared).toContain('requirements.externalSupport');+ expect(declared).toContain('Mesh_Cushion_L');+ expect(declared).toContain('Back_A');+ expect(declared).toContain('no action needed');+ const plain = inspectSceneStructure(cushions());+ expect(plain.some((w) => w.startsWith('Declared external support'))).toBe(false);+ expect(floaterNames(plain.find((w) => w.startsWith('Floating parts')))).toEqual([+ 'Back_A',+ 'Lamp',+ 'Mesh_Cushion_L',+ 'Pillow',+ 'Throw',+ ]);+});++test('render reads the declaration from the bound requirements', async () => {+ const result = await renderSceneToGLB(cushions(), { requirements: bind(SUPPORT) });+ expect(result.warnings.find((w) => w.startsWith('Declared external support'))).toContain(+ 'Mesh_Cushion_L',+ );+ expect(floaterNames(result.warnings.find((w) => w.startsWith('Floating parts')))).toEqual([+ 'Lamp',+ 'Pillow',+ 'Throw',+ ]);+});++test('the declaration is part of the requirements policy and validated strictly', () => {+ const hash = (planeY: number, reason: string) =>+ bind({+ externalSupport: {+ state: 'requested',+ value: { supports: [{ parts: ['Cushion_L'], planeY }] },+ reason,+ },+ }).policyHash;+ expect(hash(0.45, 'one')).toBe(hash(0.45, 'another wording'));+ expect(hash(0.45, 'one')).not.toBe(hash(0.5, 'one'));+ expect(hash(0.45, 'one')).not.toBe(bind({}).policyHash);+ for (const value of [+ { supports: [] },+ { supports: [{ parts: [], planeY: 0 }] },+ { supports: [{ parts: ['A', 'A'], planeY: 0 }] },+ { supports: [{ parts: ['A'], planeY: Number.NaN }] },+ { supports: [{ parts: ['A'], planeY: 0, tolerance: -1 }] },+ { supports: [{ parts: ['A'], planeY: 0, height: 1 }] },+ ])+ expect(() =>+ createAssetRequirementsV1({+ labels: ['prop'],+ requirements: { externalSupport: { state: 'requested', value: value as never } },+ }),+ ).toThrow();+});diff --git a/src/qa/part-connectivity.ts b/src/qa/part-connectivity.tsindex 2000da99..666a1c86 100644--- a/src/qa/part-connectivity.ts+++ b/src/qa/part-connectivity.ts@@ -34,6 +34,7 @@*/import * as THREE from 'three';+import { type ExternalSupportV1, restingSupport } from '../external-support';import { lodLevel } from './lod';import { KILN_ENGINE_QA_OWNER, type QaRule } from './registry';import type { QaContext, QaFinding } from './types';@@ -56,6 +57,8 @@ const EXEMPT_NAME = /(?:^|_)(?:leaf|leaves|foliage|frond|card|decal|billboard|peinterface ConnectivityPart {name: string;box: THREE.Box3;+ /** The requirements-declared external support this part's bottom meets, if any. */+ support?: ExternalSupportV1;}export interface DisconnectedGroupV1 {@@ -63,6 +66,8 @@ export interface DisconnectedGroupV1 {parts: string[];/** Shortest distance from this component to the main one, in meters. */gap: number;+ /** Present when every part rests on a requirements-declared external support. */+ externalSupport?: { planeY: number; bottomY: number; tolerance: number };}export interface PartConnectivityReportV1 {@@ -83,6 +88,7 @@ export interface PartConnectivityReportV1 {function collectParts(root: THREE.Object3D,exempt: string[],+ supports?: readonly ExternalSupportV1[],): { parts: ConnectivityPart[]; lodExcluded: number } {const parts: ConnectivityPart[] = [];let lodExcluded = 0;@@ -101,7 +107,8 @@ function collectParts(}const box = new THREE.Box3().setFromObject(mesh);if (box.isEmpty()) return;- parts.push({ name, box });+ const support = restingSupport(mesh, box.min.y, supports);+ parts.push({ name, box, ...(support ? { support } : {}) });});return { parts, lodExcluded };}@@ -120,9 +127,12 @@ function boxGap(a: THREE.Box3, b: THREE.Box3): number {* Exported for testing and for anything that wants the structure rather than* the finding.*/-export function analyzePartConnectivity(root: THREE.Object3D): PartConnectivityReportV1 {+export function analyzePartConnectivity(+ root: THREE.Object3D,+ supports?: readonly ExternalSupportV1[],+): PartConnectivityReportV1 {const exempt: string[] = [];- const { parts, lodExcluded } = collectParts(root, exempt);+ const { parts, lodExcluded } = collectParts(root, exempt, supports);const report: PartConnectivityReportV1 = {partsAnalyzed: parts.length,mainComponentSize: parts.length,@@ -187,9 +197,21 @@ export function analyzePartConnectivity(root: THREE.Object3D): PartConnectivityRgap = Math.min(gap, boxGap(parts[m]!.box, parts[b]!.box));}}+ // The lowest part names the plane the group rests on when all of it is declared.+ const lowest = members.reduce((a, b) => (parts[b]!.box.min.y < parts[a]!.box.min.y ? b : a));+ const support = parts[lowest]!.support;report.groups.push({parts: members.map((m) => parts[m]!.name),gap: Math.round(gap * 1e6) / 1e6,+ ...(support && members.every((m) => parts[m]!.support)+ ? {+ externalSupport: {+ planeY: support.planeY,+ bottomY: Math.round(parts[lowest]!.box.min.y * 1e6) / 1e6,+ tolerance: support.tolerance ?? CONNECTIVITY_TOLERANCE,+ },+ }+ : {}),});}@@ -205,9 +227,12 @@ export function analyzePartConnectivity(root: THREE.Object3D): PartConnectivityR* `exact` is reserved for rules already enforcing on frozen conformance* evidence, so a new gate is `heuristic` however precise its arithmetic.*/-export function inspectPartConnectivity(scene: unknown): readonly QaFinding[] {+export function inspectPartConnectivity(+ scene: unknown,+ supports?: readonly ExternalSupportV1[],+): readonly QaFinding[] {if (!(scene instanceof THREE.Object3D)) return [];- const report = analyzePartConnectivity(scene);+ const report = analyzePartConnectivity(scene, supports);const lodNote =report.lodExcluded === 1? ' 1 part on an LOD level above 0 was not analyzed.'@@ -220,6 +245,24 @@ export function inspectPartConnectivity(scene: unknown): readonly QaFinding[] {group.parts.length === 1? `Part ${listed} is`: `A group of ${group.parts.length} parts (${listed}) is`;+ const declared = group.externalSupport;+ if (declared)+ return {+ code: 'GEO_PART_EXTERNAL_SUPPORT',+ disposition: 'observe' as const,+ dimension: 'visualQuality' as const,+ profile: 'geometry.partConnectivity',+ message: `${subject} separate from the largest component and rests on the support declared in requirements.externalSupport at Y=${declared.planeY.toFixed(3)} m (bottom at Y=${declared.bottomY.toFixed(3)} m). Information only: the support is composed outside this asset.${lodNote}`,+ affected: { node: group.parts[0]! },+ measurement: {+ name: 'bottomToSupportPlane',+ actual: declared.bottomY,+ expected: declared.planeY,+ threshold: declared.tolerance,+ },+ repairText:+ 'No change is needed for a declared support. Remove the part from requirements.externalSupport if it should attach within this asset.',+ };return {code: 'GEO_PART_CONNECTIVITY',disposition: 'observe' as const,diff --git a/src/qa/requirements-applicability.ts b/src/qa/requirements-applicability.tsindex 3fb9cb5a..2de004af 100644--- a/src/qa/requirements-applicability.ts+++ b/src/qa/requirements-applicability.ts@@ -187,6 +187,7 @@ export function resolveRequirementsApplicability(bounds: ['units', 'x', 'y', 'z'],animation: ['clips'],representation: ['precomputedTangents'],+ externalSupport: ['supports'],};for (const [key, statement] of Object.entries(requirements.requirements)) {if (statement?.state !== 'requested') continue;diff --git a/src/qa/requirements-run.ts b/src/qa/requirements-run.tsindex 8b285dff..4588a3a4 100644--- a/src/qa/requirements-run.ts+++ b/src/qa/requirements-run.ts@@ -274,7 +274,12 @@ export function runRequirementsSceneQa(decision.ruleId === SWEEP_QA_RULE.id? inspectSweepGeometry(scene): decision.ruleId === PART_CONNECTIVITY_QA_RULE.id- ? inspectPartConnectivity(scene)+ ? inspectPartConnectivity(+ scene,+ needs.externalSupport?.state === 'requested'+ ? needs.externalSupport.value.supports+ : undefined,+ ): decision.ruleId === ASSET_SCOPE_QA_RULE.id && scope?.state === 'requested'? inspectAssetScope({profile: 'asset.requirements.v1',diff --git a/src/render.ts b/src/render.tsindex b589bb81..ccc2605e 100644--- a/src/render.ts+++ b/src/render.ts@@ -1,4 +1,5 @@import type { DuckClip } from './views/pose';+import { declaredSupports, type ExternalSupportV1, restingSupport } from './external-support';import {assertNoLegacyRuntimePolicy,resolveRequirementsContext,@@ -1791,7 +1792,13 @@ export async function renderSceneToGLB(// pivot" hint is first; the bridge also emits a briefer "target not// found - skipped" for each unresolved track (kept for compatibility).for (const w of inspectGeneratedAnimation(root, clips)) warnings.push(w);- for (const w of inspectSceneStructure(root)) warnings.push(w);+ const externalSupport = requirements.requirements.requirements.externalSupport;+ for (const w of inspectSceneStructure(root, {+ ...(externalSupport?.state === 'requested'+ ? { externalSupport: externalSupport.value.supports }+ : {}),+ }))+ warnings.push(w);// T2.2 — encode in-memory textures to PNG BEFORE QA, so QA judges the file// that will actually be written. A procedural DataTexture used to reach the@@ -2752,6 +2759,7 @@ export function inspectGeneratedAnimation(// =============================================================================interface MeshStats {+ object: THREE.Object3D;name: string;triCount: number;isPlaneGeo: boolean;@@ -2798,6 +2806,7 @@ function collectMeshStats(root: THREE.Object3D): MeshStats[] {box.getSize(size);out.push({+ object: obj,name: obj.name || '(unnamed)',triCount: Math.floor(tri),isPlaneGeo: geo.type === 'PlaneGeometry',@@ -2837,6 +2846,8 @@ function collectMeshStats(root: THREE.Object3D): MeshStats[] {export interface InspectStructureOptions {/** Asset kind for the orientation advisory. Omit to skip it. */category?: 'vehicle' | 'weapon' | 'boat' | 'aircraft' | (string & {});+ /** requirements.externalSupport: named parts that rest on a support outside this asset. */+ externalSupport?: readonly ExternalSupportV1[];}/** Floating parts named with their own fix; the rest share one line of names. */@@ -2900,6 +2911,7 @@ export function inspectSceneStructure(if (meshes.length > 1) {const floaters: { name: string; fix: string }[] = [];+ const supported: string[] = [];for (let i = 0; i < meshes.length; i++) {const a = meshes[i]!;const ax = a.box.clone().expandByScalar(FLOATING_EXPAND);@@ -2913,6 +2925,13 @@ export function inspectSceneStructure(}}if (overlapsAny) continue;+ // A declared external support whose plane this part's bottom meets is information.+ const support = restingSupport(a.object, a.box.min.y, opts.externalSupport);+ if (support) {+ supported.push(`${a.name} at Y=${support.planeY.toFixed(3)}`);+ continue;+ }+ const declared = declaredSupports(a.object, opts.externalSupport)[0];// Actionable fix: the minimal shift to the NEAREST sibling, plus the// snapTo call that applies it.@@ -2930,7 +2949,10 @@ export function inspectSceneStructure(nearest && nearestGap? ` Fix: shift "${a.name}" by [${nearestGap.x.toFixed(3)}, ${nearestGap.y.toFixed(3)}, ${nearestGap.z.toFixed(3)}] toward "${nearest.name}", or call snapTo(part, hostPart) to do it automatically.`: '';- floaters.push({ name: a.name, fix });+ const mismatch = declared+ ? ` It is named in a declared external support at Y=${declared.planeY.toFixed(3)}, but its bottom is at Y=${a.box.min.y.toFixed(3)}.`+ : '';+ floaters.push({ name: a.name, fix: fix + mismatch });}if (floaters.length > 0) {// The per-part fix text is 170 characters; a scattered asset repeated it@@ -2951,6 +2973,13 @@ export function inspectSceneStructure(`Floating parts (no mesh overlap with any sibling, 2cm tol): ${entries.join(' | ')}`,);}+ if (supported.length > 0) {+ const shown = supported.slice(0, FLOATER_NAMES_SHOWN);+ if (supported.length > shown.length) shown.push(`+${supported.length - shown.length} more`);+ warnings.push(+ `Declared external support (requirements.externalSupport): ${shown.join(', ')} rest on a support composed outside this asset; information only, no action needed.`,+ );+ }}return warnings;