@pascal-app/core 1.0.6 → 1.0.7

package/dist/agent-operations/room-wet.js

@@ -0,0 +1,203 @@
+import { foldRoomName } from '../building/room-use.js';
+import { standsAgainst } from './dress-targets.js';
+import { itemPlanAabbInLevel } from './item-space.js';
+import { wallResolvedHeight } from './level-reads.js';
+import { roomWallFaces } from './room-faces.js';
+import { describeFinish, wallFaceFinish } from './room-finishes.js';
+import { finishTiled } from './room-tile.js';
+/**
+ * What a wet room is tiled to: a bathroom, shower room, WC or laundry counts tiled when the walls its
+ * fixtures stand against are tiled to `WET_TILED_TO_M`, and to the ceiling around its shower. The
+ * wall faces read are the stretches a shower, bath, basin or toilet stands against (within
+ * `STANDS_AGAINST_M` of the face), else, when none can be placed, every face of the room. A face is
+ * tiled to a height when tile covers at least `COVERED` of its stretch up to there; what covers it is
+ * read as the renderer layers it (the base finish, then the face's regions, a later one over an
+ * earlier). A face a script builds, or a finish the nodes cannot name, is `unknown`, and unknown
+ * never fails a room.
+ */
+/** A wet room's walls are tiled up to this, metres. */
+export const WET_TILED_TO_M = 1.2;
+/** The share of a face's stretch tile must cover to count as tiled there. */
+export const COVERED = 0.8;
+/** Tile may stop this short of a height and still count as reaching it, metres. */
+const SLACK_M = 0.02;
+/** Where "to the ceiling" begins, metres under the top of the wall. */
+const CEILING_SLACK_M = 0.05;
+/** How far a shower's stretch reaches past it each side, metres. */
+const SHOWER_MARGIN_M = 0.1;
+/** A shower hung on a wall has no footprint: this much of the wall each side of it is its stretch. */
+const HUNG_REACH_M = 0.45;
+const STEP_M = 0.05;
+const FIXTURE_WORDS = new Set([
+    'shower',
+    'showers',
+    'douche',
+    'douches',
+    'bath',
+    'baths',
+    'bathtub',
+    'bathtubs',
+    'tub',
+    'tubs',
+    'baignoire',
+    'baignoires',
+    'sink',
+    'sinks',
+    'basin',
+    'basins',
+    'washbasin',
+    'washbasins',
+    'lavabo',
+    'lavabos',
+    'vasque',
+    'vasques',
+    'vanity',
+    'vanities',
+    'toilet',
+    'toilets',
+    'wc',
+    'cuvette',
+    'bidet',
+    'bidets',
+    'washer',
+    'washing',
+    'lave',
+    'laundry',
+]);
+const SHOWER_WORDS = new Set(['shower', 'showers', 'douche', 'douches']);
+/** What a piece is, in words: its kind (a category, else its name without its room's words), never its name, so a "shower mirror" is a mirror. */
+const wordsOf = (piece) => foldRoomName(piece.kind)
+    .split(/[^a-z0-9]+/)
+    .filter(Boolean);
+const isFixture = (piece) => wordsOf(piece).some((word) => FIXTURE_WORDS.has(word));
+const isShower = (piece) => wordsOf(piece).some((word) => SHOWER_WORDS.has(word));
+/** The layers a face shows, bottom to top. */
+function layersOf(zone, wall, stretch, height, materials) {
+    const { face, length } = stretch;
+    const layers = [
+        {
+            u0: 0,
+            u1: length,
+            v0: 0,
+            v1: height,
+            state: finishTiled(wallFaceFinish(zone, wall, face, materials), materials),
+        },
+    ];
+    const script = wall.finishScripts?.[face];
+    if (script)
+        layers.push({
+            u0: 0,
+            u1: length,
+            v0: 0,
+            v1: Math.min(height, script.toHeight ?? height),
+            state: 'unknown',
+        });
+    for (const region of wall.faceRegions ?? []) {
+        if (region.face !== face)
+            continue;
+        layers.push({
+            u0: region.u0 ?? 0,
+            u1: region.u1 ?? length,
+            v0: region.v0 ?? 0,
+            v1: Math.min(height, region.v1 ?? height),
+            state: finishTiled(describeFinish(region.finish, materials), materials),
+        });
+    }
+    return layers;
+}
+/** How high tile runs unbroken from the floor at one point along a face, and whether what stops it is unreadable. */
+function tileRun(layers, u, height) {
+    const here = layers.filter((layer) => u >= layer.u0 && u <= layer.u1);
+    const stops = [...new Set([0, height, ...here.flatMap((layer) => [layer.v0, layer.v1])])]
+        .filter((v) => v >= 0 && v <= height)
+        .sort((a, b) => a - b);
+    for (let index = 0; index + 1 < stops.length; index++) {
+        const [low, high] = [stops[index], stops[index + 1]];
+        if (high - low < 1e-6)
+            continue;
+        const mid = (low + high) / 2;
+        const state = here.filter((layer) => mid >= layer.v0 && mid <= layer.v1).at(-1)?.state ?? 'no';
+        if (state !== 'yes')
+            return { top: low, open: state === 'unknown' };
+    }
+    return { top: height, open: false };
+}
+export function readStretch(nodes, zone, stretch, range, materials) {
+    const wall = nodes[stretch.wallId];
+    const height = wallResolvedHeight(nodes, wall);
+    const layers = layersOf(zone, wall, stretch, height, materials);
+    const count = Math.max(1, Math.ceil((range.u1 - range.u0) / STEP_M));
+    const runs = Array.from({ length: count }, (_, index) => tileRun(layers, range.u0 + ((index + 0.5) * (range.u1 - range.u0)) / count, height));
+    return { height, tops: runs.map((run) => run.top), open: runs.map((run) => run.open) };
+}
+/** Whether tile covers 80% of the samples up to `target`: yes, no, or unknown where unreadable parts could. */
+export function reaches(read, target) {
+    const n = read.tops.length;
+    const yes = read.tops.filter((top) => top >= target - SLACK_M).length;
+    const maybe = read.tops.filter((top, i) => top < target - SLACK_M && read.open[i]).length;
+    if (yes >= COVERED * n - 1e-9)
+        return 'yes';
+    return yes + maybe >= COVERED * n - 1e-9 ? 'unknown' : 'no';
+}
+/** The height 80% of the samples reach at least. */
+export const coveredTo = (read) => [...read.tops].sort((a, b) => a - b)[Math.floor((1 - COVERED) * read.tops.length - 1e-9)] ??
+    read.tops[0];
+const combine = (states) => states.includes('no') ? 'no' : states.includes('unknown') ? 'unknown' : 'yes';
+/** The stretch of a face a piece stands against, margin added, or undefined when it does not. */
+function against(nodes, byId, stretch, piece, margin) {
+    if (stretch.curved)
+        return undefined;
+    if (piece.hung) {
+        if (piece.hung.wallId !== stretch.wallId || piece.hung.face !== stretch.face)
+            return undefined;
+        const u0 = Math.max(stretch.u0, piece.hung.u - HUNG_REACH_M);
+        const u1 = Math.min(stretch.u1, piece.hung.u + HUNG_REACH_M);
+        return u1 > u0 ? { u0, u1 } : undefined;
+    }
+    const item = nodes[piece.id];
+    const box = item?.type === 'item' ? itemPlanAabbInLevel(item, byId) : null;
+    if (!box)
+        return undefined;
+    const { minX, maxX, minZ, maxZ } = box;
+    return standsAgainst(nodes[stretch.wallId], stretch, [
+        [minX, minZ],
+        [maxX, minZ],
+        [maxX, maxZ],
+        [minX, maxZ],
+    ], margin);
+}
+/** A wet room's walls against what it is tiled to; undefined for a room with no wall face. */
+export function readWet(nodes, byId, zone, pieces, materials) {
+    const stretches = roomWallFaces(nodes, zone);
+    if (!stretches.length)
+        return undefined;
+    const fixtures = pieces.filter(isFixture);
+    const wetKeys = new Set();
+    for (const stretch of stretches)
+        if (fixtures.some((piece) => against(nodes, byId, stretch, piece, 0)))
+            wetKeys.add(`${stretch.wallId}/${stretch.face}/${stretch.t0}`);
+    const byFixtures = wetKeys.size > 0;
+    const read = stretches.filter((stretch) => !byFixtures || wetKeys.has(`${stretch.wallId}/${stretch.face}/${stretch.t0}`));
+    const reads = read.map((stretch) => readStretch(nodes, zone, stretch, stretch, materials));
+    const tiled = combine(reads.map((r) => reaches(r, WET_TILED_TO_M)));
+    const readable = reads.every((r) => !r.open.some(Boolean));
+    const tiledTo = readable ? Math.min(...reads.map(coveredTo)) : null;
+    const showers = pieces.filter(isShower).flatMap((piece) => {
+        const fulls = stretches.flatMap((stretch) => {
+            const range = against(nodes, byId, stretch, piece, SHOWER_MARGIN_M);
+            if (!range)
+                return [];
+            const there = readStretch(nodes, zone, stretch, range, materials);
+            return [reaches(there, there.height - CEILING_SLACK_M)];
+        });
+        return fulls.length ? [{ id: piece.id, name: piece.name, full: combine(fulls) }] : [];
+    });
+    return {
+        byFixtures,
+        tiledTo,
+        anyTile: reads.some((r) => r.tops.some((top) => top > SLACK_M)),
+        tiled,
+        showers,
+        verdict: combine([tiled, ...showers.map((shower) => shower.full)]),
+    };
+}

package/dist/agent-operations/scene-check-policy.d.ts

@@ -0,0 +1,5 @@
+/** Drops the whole-room pockets a room_unreachable finding of the same list says. */
+export declare function withoutDuplicatePockets<T extends {
+    type: string;
+}>(issues: T[]): T[];
+//# sourceMappingURL=scene-check-policy.d.ts.map

package/dist/agent-operations/scene-check-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scene-check-policy.d.ts","sourceRoot":"","sources":["../../src/agent-operations/scene-check-policy.ts"],"names":[],"mappings":"AAwBA,qFAAqF;AACrF,wBAAgB,uBAAuB,CAAC,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,MAAM,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,CAOpF"}

package/dist/agent-operations/scene-check-policy.js

@@ -0,0 +1,24 @@
+const fieldsOf = (issue) => issue;
+const isZoneId = (id) => id.startsWith('zone_');
+/**
+ * A whole-room pocket of a room, or of every room of a whole floor, that a room_unreachable
+ * finding already names.
+ */
+function repeatsUnreachable(pocket, named) {
+    if (pocket.type !== 'usage_pocket' || pocket.wholeRoom !== true)
+        return false;
+    const roomId = pocket.place?.roomId;
+    if (!roomId)
+        return false;
+    if (isZoneId(roomId))
+        return named.has(roomId);
+    const zoneIds = (pocket.nodeIds ?? []).filter(isZoneId);
+    return zoneIds.length > 0 && zoneIds.every((id) => named.has(id));
+}
+/** Drops the whole-room pockets a room_unreachable finding of the same list says. */
+export function withoutDuplicatePockets(issues) {
+    const named = new Set(issues
+        .filter((issue) => issue.type === 'room_unreachable')
+        .flatMap((issue) => fieldsOf(issue).nodeIds ?? []));
+    return issues.filter((issue) => !repeatsUnreachable(fieldsOf(issue), named));
+}

package/dist/agent-operations/scene-checkpoint.d.ts

@@ -38,6 +38,12 @@ export type SessionRecord = {
     designBrief?: DesignBrief;
     /** The catalog ids view_assets showed: a brief keeps a catalog piece as it is only after one. */
     viewed?: string[];
+    /**
+     * What a module read about the scene or the turn when its tool last ran, by the module's own key:
+     * plain JSON, small, opaque here. The module that wrote a key reads it back from
+     * `context.session.readings`.
+     */
+    readings?: Record<string, unknown>;
 };
 /**
  * What an operation or a write asks its host to keep; a `designBrief` of null takes the brief away,
@@ -48,6 +54,8 @@ export type SessionKeep = {
     made?: readonly MadeEntry[];
     designBrief?: DesignBrief | null;
     viewed?: readonly string[] | null;
+    /** Keys to set, each replacing the module's last reading; a null takes the key away. */
+    readings?: Readonly<Record<string, unknown>>;
 };
 export declare const EMPTY_SESSION: SessionRecord;
 /** A session names at most this many moments, `start` included. */
@@ -58,6 +66,8 @@ export declare const MAX_CHECKPOINT_NODES = 5000;
 export declare const MAX_MADE = 20000;
 /** The viewed list keeps the most recent ids up to here. */
 export declare const MAX_VIEWED = 500;
+/** A session keeps the readings of this many modules; the oldest key goes first. */
+export declare const MAX_READINGS = 16;
 /**
  * The record after a keep: a checkpoint of the same name is replaced, made entries accumulate. A node
  * is made once, however many writers report it, and the list only ever grows at its end (a

package/dist/agent-operations/scene-checkpoint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scene-checkpoint.d.ts","sourceRoot":"","sources":["../../src/agent-operations/scene-checkpoint.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"scene-checkpoint.d.ts","sourceRoot":"","sources":["../../src/agent-operations/scene-checkpoint.ts"],"names":[],"mappings":"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"}

package/dist/agent-operations/scene-checkpoint.js

@@ -13,6 +13,8 @@ export const MAX_CHECKPOINT_NODES = 5000;
 export const MAX_MADE = 20_000;
 /** The viewed list keeps the most recent ids up to here. */
 export const MAX_VIEWED = 500;
+/** A session keeps the readings of this many modules; the oldest key goes first. */
+export const MAX_READINGS = 16;
 /**
  * The record after a keep: a checkpoint of the same name is replaced, made entries accumulate. A node
  * is made once, however many writers report it, and the list only ever grows at its end (a
@@ -36,6 +38,7 @@ export function keepInSession(session, keep) {
             ...(session.viewed ?? []).filter((id) => !incomingViewed.has(id)),
             ...incomingViewed,
         ].slice(-MAX_VIEWED);
+    const readings = keptReadings(session.readings, keep.readings);
     return {
         checkpoints: keep.checkpoint
             ? { ...session.checkpoints, [keep.checkpoint.name]: keep.checkpoint }
@@ -43,8 +46,26 @@ export function keepInSession(session, keep) {
         made: fresh.length ? [...session.made, ...fresh].slice(0, MAX_MADE) : session.made,
         ...(designBrief ? { designBrief } : {}),
         ...(viewed.length ? { viewed } : {}),
+        ...(readings ? { readings } : {}),
     };
 }
+/** A module's key: lower case first, then letters, digits, dots, dashes and underscores (`brief.refusedPieces`). */
+const READING_KEY = /^[a-z][\w.-]{0,63}$/;
+/** The readings after a keep: a key set again moves to the end, a null drops it, a key that is not a module's is ignored, and the oldest past the cap go. */
+function keptReadings(held, keep) {
+    if (!keep)
+        return held;
+    const next = new Map(Object.entries(held ?? {}));
+    for (const [key, value] of Object.entries(keep)) {
+        if (!READING_KEY.test(key))
+            continue;
+        next.delete(key);
+        if (value !== null && value !== undefined)
+            next.set(key, value);
+    }
+    const kept = [...next].slice(-MAX_READINGS);
+    return kept.length ? Object.fromEntries(kept) : undefined;
+}
 const FNV_PRIME = 0x01000193;
 /** Plain JSON in a fixed key order, numbers to a tenth of a millimetre, undefined dropped. */
 function stable(value) {
@@ -81,6 +102,7 @@ const nameOf = (node) => typeof node.name === 'string' && node.name ? { name: no
 /** The scene as a checkpoint remembers it: every node's fingerprint and the registered families' places. */
 export function takeCheckpoint(nodes, name, madeAt) {
     const remembered = {};
+    // biome-ignore lint/plugin: a checkpoint remembers every node
     for (const node of Object.values(nodes))
         remembered[node.id] = {
             type: node.type,
@@ -129,6 +151,7 @@ export function createdBetween(before, after) {
  * the session has one, or the scene is too large to remember.
  */
 export function startOfSession(session, nodes) {
+    // biome-ignore lint/plugin: a checkpoint remembers every node, so its size is the scene's
     if (session.checkpoints.start || Object.keys(nodes).length > MAX_CHECKPOINT_NODES)
         return undefined;
     return { checkpoint: takeCheckpoint(nodes, 'start', session.made.length) };
@@ -148,6 +171,7 @@ const Checkpoint = z.object({
     measure: Measure,
     nodes: z
         .record(z.string(), Remembered)
+        // biome-ignore lint/plugin: a stored checkpoint's own record, not the scene
         .refine((nodes) => Object.keys(nodes).length <= MAX_CHECKPOINT_NODES),
     issues: z.array(z.string()),
     madeAt: z.number().int().min(0),
@@ -165,6 +189,13 @@ const Record_ = z.object({
     made: z.array(Made).max(MAX_MADE),
     designBrief: DesignBriefRecord.optional(),
     viewed: z.array(z.string()).max(MAX_VIEWED).optional(),
+    // a bag that does not read back costs the session its readings, never its brief or its moments
+    readings: z
+        .record(z.string(), z.unknown())
+        .refine((readings) => Object.keys(readings).length <= MAX_READINGS &&
+        Object.keys(readings).every((key) => READING_KEY.test(key)))
+        .optional()
+        .catch(undefined),
 });
 /**
  * A session record read back from where a host stored it. Anything that is not one is no record:

package/dist/agent-operations/scene-issue-groups.d.ts

@@ -0,0 +1,17 @@
+import type { SceneNodes } from './types.js';
+import type { SceneIssue } from './verify-scene.js';
+export type SceneIssueGroup = {
+    type: string;
+    message: string;
+    severity?: 'info' | 'warning';
+    count: number;
+    nodeIds: string[];
+    nodes: {
+        id: string;
+        name: string;
+        count: number;
+    }[];
+    issueIndexes: number[];
+};
+export declare function sceneIssueGroups(issues: SceneIssue[], nodes: SceneNodes): SceneIssueGroup[];
+//# sourceMappingURL=scene-issue-groups.d.ts.map

package/dist/agent-operations/scene-issue-groups.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scene-issue-groups.d.ts","sourceRoot":"","sources":["../../src/agent-operations/scene-issue-groups.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AACzC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAEhD,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7B,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,KAAK,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;IACpD,YAAY,EAAE,MAAM,EAAE,CAAA;CACvB,CAAA;AAuCD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,EAAE,EAAE,KAAK,EAAE,UAAU,GAAG,eAAe,EAAE,CAqC3F"}

package/dist/agent-operations/scene-issue-groups.js

@@ -0,0 +1,71 @@
+import { DOOR_STOPPED_BLOCKING_DEG } from '../spatial/usage-field/swings.js';
+const BLOCKERS = new Set(['room_unreachable', 'door_blocked']);
+const REPEATS = new Set(['item_overlap', 'item_too_close']);
+/** A door whose leaf stops short of `DOOR_STOPPED_BLOCKING_DEG` is no way through, whatever it meets. */
+const isStoppedDoor = (issue) => issue.type === 'usage_door_swing' &&
+    'valueDeg' in issue &&
+    typeof issue.valueDeg === 'number' &&
+    issue.valueDeg < DOOR_STOPPED_BLOCKING_DEG;
+const severityOf = (issue) => issue && 'severity' in issue ? issue.severity : undefined;
+function priority(issue) {
+    if (BLOCKERS.has(issue.type) || isStoppedDoor(issue))
+        return 0;
+    if (severityOf(issue) === 'info')
+        return 3;
+    return REPEATS.has(issue.type) ? 2 : 1;
+}
+function namedIds(issue, nodes) {
+    return [
+        ...new Set(Object.entries(issue).flatMap(([key, value]) => {
+            if (key.endsWith('Ids') && Array.isArray(value))
+                return value.filter((id) => typeof id === 'string' && !!nodes[id]);
+            if (key.endsWith('Id') && typeof value === 'string' && nodes[value])
+                return [value];
+            return [];
+        })),
+    ];
+}
+function groupMessage(type, count, nodeCount) {
+    const kind = type.replaceAll('_', ' ');
+    return `${count} ${kind} findings${nodeCount ? ` involving ${nodeCount} elements` : ''}.`;
+}
+export function sceneIssueGroups(issues, nodes) {
+    issues.sort((first, second) => priority(first) - priority(second));
+    const groups = new Map();
+    for (const [index, issue] of issues.entries()) {
+        let group = groups.get(issue.type);
+        if (!group) {
+            group = {
+                type: issue.type,
+                message: issue.message,
+                count: 0,
+                nodeIds: [],
+                nodes: [],
+                issueIndexes: [],
+            };
+            groups.set(issue.type, group);
+        }
+        group.count++;
+        group.issueIndexes.push(index);
+        for (const id of namedIds(issue, nodes)) {
+            const involved = group.nodes.find((node) => node.id === id);
+            if (involved)
+                involved.count++;
+            else
+                group.nodes.push({ id, name: nodes[id]?.name ?? id, count: 1 });
+        }
+    }
+    for (const group of groups.values()) {
+        group.nodes.sort((first, second) => first.id.localeCompare(second.id));
+        group.nodeIds = group.nodes.map(({ id }) => id);
+        if (group.count > 1) {
+            const summary = groupMessage(group.type, group.count, group.nodeIds.length);
+            group.message = group.nodeIds.length ? summary : `${summary} First: ${group.message}`;
+        }
+        if (group.issueIndexes.every((index) => severityOf(issues[index]) === 'info'))
+            group.severity = 'info';
+        else if (group.issueIndexes.some((index) => severityOf(issues[index]) === 'warning'))
+            group.severity = 'warning';
+    }
+    return [...groups.values()];
+}

package/dist/agent-operations/scene-materials.d.ts

@@ -1,3 +1,4 @@
+import type { CompiledGeometryScript } from '../schema/index.js';
 import { MaterialSchema } from '../schema/material.js';
 import { type SceneMaterial, type SceneMaterialId } from '../schema/scene-material.js';
 /**
@@ -10,6 +11,28 @@ export declare function resolveInlinePaintMaterial(materials: Readonly<Record<Sc
     sceneMaterial: SceneMaterial;
     created: boolean;
 };
+/** How a colour's surface reflects: a module's own values, or a matte paint. */
+export type ColorSurface = {
+    roughness: number;
+    metalness: number;
+};
+export declare const MATTE: ColorSurface;
+/**
+ * A colour kept exactly rather than snapped to the library: a native material named by its hex
+ * (and its surface, when not matte), so the same colour and surface reuse one scene material.
+ */
+export declare function exactColorMaterial(materials: Readonly<Record<SceneMaterialId, SceneMaterial>> | undefined, hex: string, surface?: ColorSurface): {
+    ref: string;
+    sceneMaterial: SceneMaterial;
+    created: boolean;
+};
+/**
+ * A compiled module's slots with each of its own colours written exactly, over the library
+ * matches: glass keeps the library glass (drawn see-through, letting light pass) and an emissive
+ * slot its module's material (a scene material carries no emission, so a bulb stays lit).
+ * `exact` answers a colour's ref, or undefined to keep the match.
+ */
+export declare function exactScriptSlots(manifest: CompiledGeometryScript['manifest'], matched: Record<string, string>, exact: (hex: string, surface: ColorSurface) => string | undefined): Record<string, string>;
 /** The scene materials a node points at, in its slots and its role fields alike. */
 export declare function referencedSceneMaterialIds(value: unknown): Set<string>;
 //# sourceMappingURL=scene-materials.d.ts.map

package/dist/agent-operations/scene-materials.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scene-materials.d.ts","sourceRoot":"","sources":["../../src/agent-operations/scene-materials.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACnD,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,eAAe,EACrB,MAAM,0BAA0B,CAAA;AAqBjC;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,eAAe,EAAE,aAAa,CAAC,CAAC,GAAG,SAAS,EACvE,KAAK,EAAE,cAAc,EACrB,IAAI,CAAC,EAAE,MAAM,GACZ;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAqBjE;AAED,oFAAoF;AACpF,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,CAWtE"}
+{"version":3,"file":"scene-materials.d.ts","sourceRoot":"","sources":["../../src/agent-operations/scene-materials.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAA;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACnD,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,eAAe,EACrB,MAAM,0BAA0B,CAAA;AAqBjC;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,eAAe,EAAE,aAAa,CAAC,CAAC,GAAG,SAAS,EACvE,KAAK,EAAE,cAAc,EACrB,IAAI,CAAC,EAAE,MAAM,GACZ;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAqBjE;AAID,gFAAgF;AAChF,MAAM,MAAM,YAAY,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAA;AACnE,eAAO,MAAM,KAAK,EAAE,YAA+C,CAAA;AAEnE;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,eAAe,EAAE,aAAa,CAAC,CAAC,GAAG,SAAS,EACvE,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,YAAoB;SApCrB,MAAM;mBAAiB,aAAa;aAAW,OAAO;EAuD/D;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,sBAAsB,CAAC,UAAU,CAAC,EAC5C,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,KAAK,MAAM,GAAG,SAAS,GAChE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAWxB;AAED,oFAAoF;AACpF,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,CAWtE"}

package/dist/agent-operations/scene-materials.js

@@ -44,6 +44,47 @@ export function resolveInlinePaintMaterial(materials, input, name) {
     };
     return { ref: toSceneMaterialRef(id), sceneMaterial, created: true };
 }
+const GLASS_REF = 'library:preset-glass';
+export const MATTE = { roughness: 0.9, metalness: 0 };
+/**
+ * A colour kept exactly rather than snapped to the library: a native material named by its hex
+ * (and its surface, when not matte), so the same colour and surface reuse one scene material.
+ */
+export function exactColorMaterial(materials, hex, surface = MATTE) {
+    const color = hex.toLowerCase();
+    return resolveInlinePaintMaterial(materials, {
+        properties: {
+            color,
+            roughness: surface.roughness,
+            metalness: surface.metalness,
+            opacity: 1,
+            transparent: false,
+            side: 'front',
+        },
+    }, surface.roughness === MATTE.roughness && surface.metalness === MATTE.metalness
+        ? color
+        : `${color}, roughness ${+surface.roughness.toFixed(2)}, metalness ${+surface.metalness.toFixed(2)}`);
+}
+/**
+ * A compiled module's slots with each of its own colours written exactly, over the library
+ * matches: glass keeps the library glass (drawn see-through, letting light pass) and an emissive
+ * slot its module's material (a scene material carries no emission, so a bulb stays lit).
+ * `exact` answers a colour's ref, or undefined to keep the match.
+ */
+export function exactScriptSlots(manifest, matched, exact) {
+    const slots = { ...matched };
+    for (const slot of manifest.slots) {
+        if (!slot.color || slot.emissive || slots[slot.id] === GLASS_REF)
+            continue;
+        const ref = exact(slot.color, {
+            roughness: slot.roughness ?? MATTE.roughness,
+            metalness: slot.metalness ?? MATTE.metalness,
+        });
+        if (ref)
+            slots[slot.id] = ref;
+    }
+    return slots;
+}
 /** The scene materials a node points at, in its slots and its role fields alike. */
 export function referencedSceneMaterialIds(value) {
     const ids = new Set();