@pascal-app/core 1.0.1 → 1.0.4

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

@@ -0,0 +1,369 @@
+import { levelBuildingId } from '../building/level-duplication.js';
+import { getLevelDisplayName } from '../lib/level-name.js';
+import { detectOpenWallEnds } from '../lib/room-graph.js';
+import { AnyNode as AnyNodeSchema } from '../schema/index.js';
+import { getStoredLevelHeight } from '../services/storey.js';
+import { computeSegmentTransforms, rotateXZ } from '../systems/stair/stair-footprint.js';
+import { resolveStairTotalRise } from '../systems/stair/stair-rise-query.js';
+import { measureStair } from '../systems/stair/stair-sizing.js';
+import { checkOpeningWithinWall, formatOpeningBoundsIssue } from '../validation/opening-bounds.js';
+import { layoutIssuesFromScene } from './layout-clearance.js';
+import { wallResolvedHeight } from './level-reads.js';
+import { pointInPolygon, polygonContainsPolygon } from './plan-geometry.js';
+import { changesSince } from './scene-measure.js';
+import { contentCounts, levelIdOf, levelRole, levelsOf, nodesOnLevel, } from './scene-queries.js';
+export const CHECKPOINT_ORDER = 100;
+const checks = [];
+const reports = [];
+/** Adds a report's fields to every verify_scene from now on; registering again replaces it. */
+export function registerSceneReport(report) {
+    const at = reports.findIndex((known) => known.name === report.name);
+    if (at >= 0)
+        reports[at] = report;
+    else
+        reports.push(report);
+}
+/** Runs a check in every verify_scene from now on; registering a check again replaces it. */
+export function registerSceneCheck(check) {
+    const at = checks.findIndex((known) => known.name === check.name);
+    if (at >= 0)
+        checks[at] = check;
+    else
+        checks.push(check);
+    checks.sort((a, b) => a.order - b.order);
+}
+const occupiedContent = (counts) => counts.walls +
+    counts.zones +
+    counts.doors +
+    counts.windows +
+    counts.items +
+    counts.slabs +
+    counts.ceilings +
+    counts.stairs;
+function toWorldPlanPoint(stair, localX, localZ) {
+    const [worldX, worldZ] = rotateXZ(localX, localZ, stair.rotation ?? 0);
+    return [stair.position[0] + worldX, stair.position[2] + worldZ];
+}
+function stairFootprintPolygons(nodes, stair) {
+    if (stair.stairType === 'curved' || stair.stairType === 'spiral') {
+        const radius = Math.max(0.05, stair.innerRadius ?? 0.9) + Math.max(stair.width ?? 1, 0.4);
+        return [
+            Array.from({ length: 24 }).map((_, index) => {
+                const angle = (index / 24) * Math.PI * 2;
+                return toWorldPlanPoint(stair, Math.cos(angle) * radius, Math.sin(angle) * radius);
+            }),
+        ];
+    }
+    const segments = (stair.children ?? [])
+        .map((childId) => nodes[childId])
+        .filter((node) => node?.type === 'stair-segment');
+    const usableSegments = segments.length > 0
+        ? segments
+        : [
+            {
+                width: stair.width ?? 1,
+                length: 3,
+                height: resolveStairTotalRise(stair, nodes),
+                stepCount: stair.stepCount ?? 10,
+                attachmentSide: 'front',
+            },
+        ];
+    const transforms = computeSegmentTransforms(usableSegments);
+    return usableSegments.map((segment, index) => {
+        const transform = transforms[index] ?? {
+            position: [0, 0, 0],
+            rotation: 0,
+        };
+        const halfWidth = segment.width / 2;
+        const corners = [
+            [-halfWidth, 0],
+            [halfWidth, 0],
+            [halfWidth, segment.length],
+            [-halfWidth, segment.length],
+        ];
+        return corners.map(([localX, localZ]) => {
+            const [rx, rz] = rotateXZ(localX, localZ, transform.rotation);
+            return toWorldPlanPoint(stair, transform.position[0] + rx, transform.position[2] + rz);
+        });
+    });
+}
+function wallSamplePoints(wall) {
+    return [0.25, 0.5, 0.75].map((t) => [
+        wall.start[0] + (wall.end[0] - wall.start[0]) * t,
+        wall.start[1] + (wall.end[1] - wall.start[1]) * t,
+    ]);
+}
+function levelNumber(nodes, levelId) {
+    const node = levelId ? nodes[levelId] : undefined;
+    return node?.type === 'level' ? node.level : undefined;
+}
+function targetLevelIdsForStair(nodes, stair) {
+    const fromLevelId = stair.fromLevelId ?? levelIdOf(nodes, stair.id);
+    const toLevelId = stair.toLevelId ?? fromLevelId;
+    const fromLevel = levelNumber(nodes, fromLevelId);
+    const toLevel = levelNumber(nodes, toLevelId);
+    if (fromLevel === undefined || toLevel === undefined)
+        return toLevelId ? [toLevelId] : [];
+    const low = Math.min(fromLevel, toLevel);
+    const high = Math.max(fromLevel, toLevel);
+    const fromLevelNode = fromLevelId ? nodes[fromLevelId] : undefined;
+    const buildingId = fromLevelNode?.type === 'level'
+        ? levelBuildingId(nodes, fromLevelNode)
+        : null;
+    return levelsOf(nodes)
+        .filter((level) => level.level > low && level.level <= high)
+        .filter((level) => !buildingId || levelBuildingId(nodes, level) === buildingId)
+        .map((level) => level.id);
+}
+function holeBelongsToStair(surface, holeIndex, stairId) {
+    const metadata = surface.holeMetadata?.[holeIndex];
+    return metadata?.source === 'stair' && metadata.stairId === stairId;
+}
+function parentListsChild(parent, childId) {
+    if (!('children' in parent && Array.isArray(parent.children)))
+        return false;
+    return parent.children.some((child) => {
+        if (typeof child === 'string')
+            return child === childId;
+        return (child !== null &&
+            typeof child === 'object' &&
+            'id' in child &&
+            child.id === childId);
+    });
+}
+function schemaErrors(nodes) {
+    const errors = [];
+    for (const [id, node] of Object.entries(nodes)) {
+        const parsed = AnyNodeSchema.safeParse(node);
+        if (parsed.success)
+            continue;
+        for (const issue of parsed.error.issues)
+            errors.push({ nodeId: id, path: issue.path.join('.'), message: issue.message });
+    }
+    return errors;
+}
+/**
+ * `verify_scene`: a self-check after complex edits. Per-level content and roles, then every
+ * practical problem found, typed: rooms missing floors or ceilings, roof levels misused, storeys
+ * with no stair, openings off their wall, stairs off their slab, blocked doors, overlapping
+ * furniture, nodes their schema rejects.
+ */
+export const verifyScene = (nodes, input, context) => {
+    const onLevel = (levelId) => nodesOnLevel(nodes, levelId);
+    const ofType = (content, type) => content.filter((node) => node.type === type);
+    const levels = levelsOf(nodes).map((level) => {
+        const content = contentCounts(onLevel(level.id));
+        const { role, metadataRole, referenceLevelId } = levelRole(nodes, level);
+        return {
+            levelId: level.id,
+            levelName: getLevelDisplayName(level),
+            floorIndex: level.level,
+            role,
+            metadataRole,
+            isOccupiedStory: role === 'occupied',
+            isSupportLevel: role !== 'occupied',
+            referenceLevelId,
+            isActive: level.id === context.activeLevelId,
+            isEmpty: Object.values(content).every((count) => count === 0),
+            content,
+        };
+    });
+    const issues = [];
+    const report = (type, message, informational = false) => issues.push({ type, message, ...(informational ? { severity: 'info' } : {}) });
+    const empty = levels.filter((level) => level.isEmpty);
+    if (empty.length > 0)
+        report('empty_levels', `${empty.length} empty level(s): ${empty.map((level) => `${level.levelName} (${level.levelId})`).join(', ')}`);
+    for (const level of levels) {
+        const { content, levelName } = level;
+        // A free-standing wall (garden wall, half wall) is legitimate, not something to repair.
+        for (const end of detectOpenWallEnds(nodes, level.levelId)) {
+            if (end.reason === 'isolated')
+                continue;
+            issues.push({
+                type: 'wall_open_end',
+                message: `Wall ${end.wallId} ${end.end} is open on ${levelName}: ${end.reason}${end.candidate ? `; nearest wall ${end.candidate.wallId}` : ''}`,
+                wallId: end.wallId,
+                end: end.end,
+                reason: end.reason,
+                ...(end.gap !== undefined ? { gap: end.gap } : {}),
+                ...(end.candidate ? { nearestWallId: end.candidate.wallId } : {}),
+            });
+        }
+        if (level.role === 'roof') {
+            if (content.roofs === 0)
+                report('roof_level_no_roof', `${levelName} is a roof support level but has no roof geometry; add or move roof geometry there rather than deleting the support level to satisfy story count`);
+            if (occupiedContent(content) > 0)
+                report('roof_level_occupied', `${levelName} is a roof support level but contains occupied-story content; move rooms, walls, stairs, slabs, ceilings, and items to an occupied story and keep the roof level for roof geometry only`);
+            const reference = level.referenceLevelId ? nodes[level.referenceLevelId] : undefined;
+            if (reference?.type === 'level' && level.floorIndex <= reference.level)
+                report('roof_level_below_reference', `${levelName} roof support level should be above its reference occupied level ${reference.name ?? reference.id}`);
+            continue;
+        }
+        if (content.walls > 0 && content.zones === 0)
+            report('walls_no_zones', `${levelName} has walls but no zones/rooms`);
+        if (content.zones > 0 && content.slabs === 0)
+            report('zones_no_slabs', `${levelName} has zones but no slabs/floors`);
+        if (content.zones > 0 && content.ceilings === 0)
+            report('zones_no_ceilings', `${levelName} has zones but no ceilings`);
+        if (content.walls > 0 && content.doors === 0)
+            report('walls_no_doors', `${levelName} has walls but no doors`);
+        if (content.roofs > 0 && (content.walls > 0 || content.zones > 0 || content.stairs > 0))
+            report('roof_mixed_in_storey', `${levelName} mixes roof geometry with occupied-level content; place roofs on a dedicated roof level for solo/exploded level views`);
+    }
+    // Storeys are counted per building: separate buildings need no stair between them, and a wall
+    // can only span the storeys of its own building.
+    const storeysByBuilding = new Map();
+    for (const level of levels) {
+        if (!level.isOccupiedStory)
+            continue;
+        const node = nodes[level.levelId];
+        const buildingId = levelBuildingId(nodes, node) ?? '';
+        storeysByBuilding.set(buildingId, [...(storeysByBuilding.get(buildingId) ?? []), level]);
+    }
+    for (const [buildingId, storeys] of storeysByBuilding) {
+        if (storeys.length < 2)
+            continue;
+        const stairs = levels
+            .filter((level) => {
+            const node = nodes[level.levelId];
+            return (levelBuildingId(nodes, node) ?? '') === buildingId;
+        })
+            .reduce((sum, level) => sum + level.content.stairs, 0);
+        if (stairs === 0)
+            report('missing_stair', `${nodes[buildingId]?.name ?? 'The building'} has ${storeys.length} storeys and no stair: add one on the ground floor, in the hall or entry, to connect them.`);
+    }
+    for (const storeys of storeysByBuilding.values()) {
+        if (storeys.length < 2)
+            continue;
+        for (const level of storeys) {
+            const node = nodes[level.levelId];
+            const expectedHeight = getStoredLevelHeight(node);
+            for (const wall of ofType(onLevel(level.levelId), 'wall')) {
+                const wallHeight = wallResolvedHeight(nodes, wall);
+                if (wallHeight > expectedHeight + 0.25)
+                    report('wall_spans_storeys', `Wall ${wall.name ?? wall.id} on ${node.name ?? node.id} is ${wallHeight}m high; multi-story exterior walls should be split into level-owned story walls`);
+            }
+        }
+    }
+    for (const node of Object.values(nodes)) {
+        if (node.type !== 'door' && node.type !== 'window')
+            continue;
+        const parent = node.parentId ? nodes[node.parentId] : undefined;
+        if (parent?.type !== 'wall') {
+            report('opening_not_on_wall', `${node.type} ${node.id} is not parented to a wall`);
+            continue;
+        }
+        if (node.wallId !== parent.id)
+            report('opening_wall_mismatch', `${node.type} ${node.id} has wallId ${node.wallId ?? 'unset'} but is parented to wall ${parent.id}`);
+        if (!parentListsChild(parent, node.id))
+            report('opening_not_listed', `${node.type} ${node.id} is not listed in wall ${parent.id} children`);
+        for (const issue of checkOpeningWithinWall(node, parent, wallResolvedHeight(nodes, parent)))
+            report(issue.kind === 'along_wall' ? 'opening_outside_wall' : 'opening_outside_height', formatOpeningBoundsIssue(issue));
+    }
+    for (const stair of Object.values(nodes).filter((node) => node.type === 'stair')) {
+        const stairName = stair.name ?? stair.id;
+        for (const diagnostic of measureStair(stair, nodes).diagnostics)
+            report(`stair_${diagnostic.code.replaceAll('-', '_')}`, `Stair ${stairName}: ${diagnostic.message}`, diagnostic.code.endsWith('-target'));
+        const sourceLevelId = levelIdOf(nodes, stair.id);
+        if (sourceLevelId) {
+            const sourceName = nodes[sourceLevelId]?.name ?? sourceLevelId;
+            const footprints = stairFootprintPolygons(nodes, stair);
+            const sourceSlabs = ofType(onLevel(sourceLevelId), 'slab');
+            if (sourceSlabs.length > 0 &&
+                footprints.some((footprint) => !sourceSlabs.some((slab) => polygonContainsPolygon(slab.polygon, footprint))))
+                report('stair_outside_slab', `Stair ${stairName} footprint extends outside source floor slab on ${sourceName}`);
+            for (const wall of ofType(onLevel(sourceLevelId), 'wall'))
+                if (footprints.some((footprint) => wallSamplePoints(wall).some((point) => pointInPolygon(point, footprint, false))))
+                    report('stair_obstructed', `Wall ${wall.name ?? wall.id} obstructs stair ${stairName} on ${sourceName}`);
+        }
+        if ((stair.slabOpeningMode ?? 'none') !== 'destination')
+            continue;
+        const targetLevelIds = targetLevelIdsForStair(nodes, stair);
+        if (targetLevelIds.length === 0)
+            report('stair_opening_no_target', `Stair ${stairName} requests a slab opening but has no target level`);
+        for (const targetLevelId of targetLevelIds) {
+            const targetName = nodes[targetLevelId]?.name ?? targetLevelId;
+            const targetSlabs = ofType(onLevel(targetLevelId), 'slab');
+            if (targetSlabs.length === 0) {
+                report('stair_target_no_slab', `Stair ${stairName} targets ${targetName} but it has no slab`);
+                continue;
+            }
+            const holes = targetSlabs.flatMap((slab) => (slab.holes ?? [])
+                .map((hole, index) => ({ slab, hole, index }))
+                .filter((entry) => holeBelongsToStair(entry.slab, entry.index, stair.id)));
+            // Since owned floor openings, the stair owns a floor-opening on the floor above, and the
+            // slab hole it cuts names the opening, not the stair (else 14 false reports on one build).
+            const owned = onLevel(targetLevelId).filter((node) => node.type === 'floor-opening' &&
+                node.source === 'stair' &&
+                node.ownerId === stair.id &&
+                node.drawnOn === 'floor');
+            for (const opening of owned) {
+                const slab = targetSlabs.find((candidate) => candidate.id === opening.surfaceId) ?? targetSlabs[0];
+                holes.push({ slab, hole: opening.polygon, index: -1 });
+            }
+            if (holes.length === 0) {
+                report('stair_no_opening', `Stair ${stairName} has no destination slab opening on ${targetName}`);
+                continue;
+            }
+            for (const { slab, hole } of holes)
+                if (!polygonContainsPolygon(slab.polygon, hole))
+                    report('stair_opening_outside_slab', `Stair ${stairName} opening extends outside slab ${slab.name ?? slab.id}`);
+        }
+    }
+    const errors = schemaErrors(nodes);
+    for (const error of errors.slice(0, 5))
+        report('schema_invalid', `Schema: ${error.nodeId}.${error.path} ${error.message}`);
+    if (errors.length > 5)
+        report('schema_invalid', `Schema: ${errors.length - 5} additional validation errors`);
+    // Door keep-outs and item–item footprint overlaps (rotation-aware).
+    issues.push(...layoutIssuesFromScene(Object.values(nodes)));
+    for (const check of checks)
+        if (check.order < CHECKPOINT_ORDER)
+            issues.push(...check.run(nodes, input ?? {}));
+    // What the edits since the host's checkpoint lost, by place.
+    const since = context.checkpoint
+        ? changesSince(context.checkpoint, nodes)
+        : null;
+    if (since)
+        issues.push(...since.issues);
+    for (const check of checks)
+        if (check.order >= CHECKPOINT_ORDER)
+            issues.push(...check.run(nodes, input ?? {}));
+    const occupiedStoryCount = levels.filter((level) => level.isOccupiedStory).length;
+    return {
+        result: {
+            ok: true,
+            valid: errors.length === 0,
+            levelCount: levels.length,
+            occupiedStoryCount,
+            supportLevelCount: levels.length - occupiedStoryCount,
+            roofLevelIds: levels.filter((level) => level.role === 'roof').map((level) => level.levelId),
+            activeLevelId: context.activeLevelId,
+            levels,
+            emptyLevelIds: empty.map((level) => level.levelId),
+            issues,
+            hasIssues: issues.some((issue) => issue.severity !== 'info'),
+            ...authoredObjects(nodes),
+            ...Object.assign({}, ...reports.map((report) => report.run(nodes))),
+            ...(since && {
+                sinceCheckpoint: { name: context.checkpoint.name, changes: since.changes },
+            }),
+        },
+    };
+};
+/** Objects built by add_object, with what each stands in for: each is a gap in what Pascal builds. */
+function authoredObjects(nodes) {
+    const objects = Object.values(nodes)
+        .flatMap((node) => node.type === 'item' && node.source
+        ? [
+            {
+                id: node.id,
+                name: node.name ?? node.asset.name,
+                category: node.asset.category,
+                reason: typeof node.metadata?.reason === 'string' ? node.metadata.reason : null,
+            },
+        ]
+        : [])
+        .sort((a, b) => a.name.localeCompare(b.name) || a.id.localeCompare(b.id));
+    return objects.length ? { authoredObjects: objects } : {};
+}

package/dist/agent-operations/wall-opening.d.ts

@@ -0,0 +1,65 @@
+import { type WallOpeningInput } from '../building/wall-openings.js';
+import { type Achieved } from './achieved.js';
+import type { SceneChanges, SceneNodes } from './types.js';
+/**
+ * add_door and add_window for every surface: the editor's placement rules (`planWallOpening`),
+ * the node to create, and the one result the MCP and the chat both pass through as it is.
+ */
+export declare function addWallOpening(nodes: SceneNodes, input: WallOpeningInput): {
+    changes: SceneChanges;
+    result: {
+        message: string;
+        achieved: Achieved;
+        sillHeight?: number | undefined;
+        wallId: string;
+        localX: number;
+        t: number;
+        wallLength: number;
+        clamped: boolean;
+        coordinateSystem: "wall-local-meters";
+        doorId: `door_${string}` | `window_${string}`;
+        ok: true;
+    } | {
+        message: string;
+        achieved: Achieved;
+        sillHeight?: number | undefined;
+        wallId: string;
+        localX: number;
+        t: number;
+        wallLength: number;
+        clamped: boolean;
+        coordinateSystem: "wall-local-meters";
+        windowId: `door_${string}` | `window_${string}`;
+        ok: true;
+    };
+};
+/**
+ * add_door / add_window with a nodeId, rebuilt from its script: the same answer as a new opening,
+ * read from where it stands after the rebuild, with what the script reported.
+ */
+export declare function rebuiltOpeningResult(nodesAfter: SceneNodes, nodeId: string, summary: Record<string, unknown>, achieved: Achieved): {
+    achieved: Achieved;
+    message: string;
+    sillHeight?: number | undefined;
+    wallId: string;
+    localX: number;
+    t: number;
+    wallLength: number;
+    clamped: boolean;
+    coordinateSystem: "wall-local-meters";
+    doorId: string;
+    ok: true;
+} | {
+    achieved: Achieved;
+    message: string;
+    sillHeight?: number | undefined;
+    wallId: string;
+    localX: number;
+    t: number;
+    wallLength: number;
+    clamped: boolean;
+    coordinateSystem: "wall-local-meters";
+    windowId: string;
+    ok: true;
+};
+//# sourceMappingURL=wall-opening.d.ts.map

package/dist/agent-operations/wall-opening.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wall-opening.d.ts","sourceRoot":"","sources":["../../src/agent-operations/wall-opening.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,gBAAgB,EAAE,MAAM,2BAA2B,CAAA;AAClF,OAAO,EAAE,KAAK,QAAQ,EAAmB,MAAM,YAAY,CAAA;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAEvD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqBxE;AAUD;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,QAAQ,EAAE,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;EAwBnB"}

package/dist/agent-operations/wall-opening.js

@@ -0,0 +1,55 @@
+import { planWallOpening } from '../building/wall-openings.js';
+import { achievedChanges } from './achieved.js';
+/**
+ * add_door and add_window for every surface: the editor's placement rules (`planWallOpening`),
+ * the node to create, and the one result the MCP and the chat both pass through as it is.
+ */
+export function addWallOpening(nodes, input) {
+    const plan = planWallOpening(nodes, input);
+    const changes = {
+        create: [{ node: plan.node, parentId: plan.wallId }],
+    };
+    return {
+        changes,
+        result: {
+            ok: true,
+            ...(input.kind === 'door' ? { doorId: plan.node.id } : { windowId: plan.node.id }),
+            wallId: plan.wallId,
+            localX: plan.localX,
+            t: plan.t,
+            wallLength: plan.wallLength,
+            clamped: plan.clamped,
+            coordinateSystem: 'wall-local-meters',
+            ...(plan.sillHeight === undefined ? {} : { sillHeight: plan.sillHeight }),
+            message: `Added ${input.kind} "${plan.node.name}" on wall ${plan.wallId}${plan.clamped ? ', slid to fit' : ''}`,
+            achieved: achievedChanges(nodes, changes),
+        },
+    };
+}
+/**
+ * add_door / add_window with a nodeId, rebuilt from its script: the same answer as a new opening,
+ * read from where it stands after the rebuild, with what the script reported.
+ */
+export function rebuiltOpeningResult(nodesAfter, nodeId, summary, achieved) {
+    const node = nodesAfter[nodeId];
+    const wall = node.wallId
+        ? nodesAfter[node.wallId]
+        : undefined;
+    const wallLength = wall?.type === 'wall'
+        ? Math.hypot(wall.end[0] - wall.start[0], wall.end[1] - wall.start[1])
+        : 0;
+    return {
+        ok: true,
+        ...(node.type === 'door' ? { doorId: nodeId } : { windowId: nodeId }),
+        wallId: node.wallId ?? '',
+        localX: node.position[0],
+        t: wallLength ? node.position[0] / wallLength : 0,
+        wallLength,
+        clamped: false,
+        coordinateSystem: 'wall-local-meters',
+        ...(node.type === 'window' ? { sillHeight: node.position[1] - node.height / 2 } : {}),
+        message: `Rebuilt ${node.type} "${node.name ?? nodeId}" from its script`,
+        ...summary,
+        achieved,
+    };
+}

package/dist/agent-tools/achieved.d.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod';
+/** What the scene holds after a call that changes it (agent-operations `achievedChanges`). */
+export declare const achievedOutput: z.ZodObject<{
+    created: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    updated: z.ZodNumber;
+    deleted: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    unchanged: z.ZodOptional<z.ZodLiteral<true>>;
+}, z.core.$strip>;
+//# sourceMappingURL=achieved.d.ts.map

package/dist/agent-tools/achieved.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"achieved.d.ts","sourceRoot":"","sources":["../../src/agent-tools/achieved.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,8FAA8F;AAC9F,eAAO,MAAM,cAAc;;;;;iBAKzB,CAAA"}

package/dist/agent-tools/achieved.js

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+/** What the scene holds after a call that changes it (agent-operations `achievedChanges`). */
+export const achievedOutput = z.object({
+    created: z.record(z.string(), z.number()),
+    updated: z.number(),
+    deleted: z.record(z.string(), z.number()),
+    unchanged: z.literal(true).optional(),
+});

package/dist/agent-tools/add-object.d.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+/** The `params` field every scripted tool shares (add_object, add_window, add_door, add_column). */
+export declare const scriptParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodNumber, z.ZodBoolean, z.ZodString]>>>;
+/** The `language` field every scripted tool shares. */
+export declare const scriptLanguage: z.ZodOptional<z.ZodEnum<{
+    three: "three";
+    bpy: "bpy";
+}>>;
+export declare const addObjectTool: {
+    name: string;
+    title: string;
+    description: string;
+    input: {
+        name: z.ZodOptional<z.ZodString>;
+        category: z.ZodOptional<z.ZodString>;
+        reason: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        code: z.ZodOptional<z.ZodString>;
+        language: z.ZodOptional<z.ZodEnum<{
+            three: "three";
+            bpy: "bpy";
+        }>>;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodNumber, z.ZodBoolean, z.ZodString]>>>;
+        nodeId: z.ZodOptional<z.ZodString>;
+        parentId: z.ZodOptional<z.ZodString>;
+        position: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+        rotation: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>, z.ZodTransform<number, string | number>>>;
+        side: z.ZodOptional<z.ZodEnum<{
+            front: "front";
+            back: "back";
+        }>>;
+    };
+};
+export declare const getSourceTool: {
+    name: string;
+    title: string;
+    description: string;
+    input: {
+        nodeId: z.ZodString;
+    };
+};
+//# sourceMappingURL=add-object.d.ts.map

package/dist/agent-tools/add-object.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"add-object.d.ts","sourceRoot":"","sources":["../../src/agent-tools/add-object.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAmCvB,oGAAoG;AACpG,eAAO,MAAM,YAAY,wGAKtB,CAAA;AAEH,uDAAuD;AACvD,eAAO,MAAM,cAAc;;;GAE1B,CAAA;AAED,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;CAiDzB,CAAA;AAED,eAAO,MAAM,aAAa;;;;;;;CAQzB,CAAA"}

package/dist/agent-tools/add-object.js

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+import { geometryMetaFields } from '../schema/geometry-metadata.js';
+import { GeometryScriptLanguage } from '../schema/geometry-source.js';
+import { measurement } from './measurement.js';
+import { NodeId } from './node-id.js';
+const DESCRIPTION = `Build an object by writing a plain three.js module, the way you would in any three.js project. Use it for what the catalog and the structure tools cannot reproduce faithfully: custom columns and capitals, mouldings and trim, panels, lanterns and fixtures, exposed beams, vaulted or tray ceiling bodies, canopies, a porch, railings, built-ins. Pascal runs the module in a sandbox, stores the result and places it as one object the user can move, paint, and ask you to edit again.
+
+Module shape (import THREE from the three package as usual; the addons below too):
+  // also available: three/addons/utils/BufferGeometryUtils.js, three/addons/geometries/{RoundedBoxGeometry,ConvexGeometry,LoftGeometry,ParametricGeometry}.js, three-bvh-csg (Brush, Evaluator, SUBTRACTION, ADDITION, INTERSECTION)
+  export const params = { width: { default: 4.8, min: 3, max: 8, step: 0.1, unit: 'm', label: 'Width' } }
+  export const mount = 'floor'   // 'floor' | 'wall-side' (on a wall face) | 'wall' (through a wall, like a window) | 'ceiling'
+  export default function build({ params, THREE }) { const group = new THREE.Group(); /* … */ return group }
+
+One object is one feature that changes together: a porch, a railing run, a fireplace surround, a ceiling with its beams. Never a whole house, and never walls, rooms, floors, roofs, stairs, doors or windows: those have their own tools. A new object says what it stands in for (reason): the scene check lists every authored object with its reason, so each names something Pascal has no type for. On a floor, a plain box with a wall's size or a floor plate is refused with the tool to use (use_walls, use_slab); a detailed object with a wall's size (a bookcase, a screen), or one named after something Pascal builds, is built with a hint naming the tool.
+
+Conventions (they make the object work in Pascal; follow them):
+- Metres, Y up, modelled as it stands. Pascal puts the bottom-centre of the bounds at the placement point; for wall-side the back face sits on the wall and the object faces +Z.
+- Paint: name every material slot_<finish> (slot_trim, slot_frame, slot_metal) and reuse one material per finish; a material named "glass" renders as glass.
+- Parts: name the few groups a person would point at part:<id> (part:column_left, part:canopy, part:landing), usually 2–24, a group per part, not every mesh. Set userData.type on parts someone would look for: column, beam, slab, roof, railing, panel, trim, step, light.
+- Lights: add a THREE.PointLight or SpotLight named light:<id> where the bulb is; it becomes a switchable light.
+- Motion: put THREE.AnimationClips on the returned group's .animations, as in any three.js project; tracks target <objectName>.<property> or <object.uuid>.<property> and may use any transform property (position, rotation, rotation[y], quaternion, scale); material and visibility tracks do not animate. A clip named open becomes the object's open/close control (close plays a clip named close, or open reversed); a clip named loop runs continuously; every other clip gets its own play toggle labelled with its name (name it for the person: "Twirl", "Music"). Write as many clips as the object needs.
+- Cuts: a mesh named cutout cuts only the mounted host; cut:wall, cut:ceiling and cut:slab require that host kind (floor items cut their support slab). The hidden cutter must reach the host; walls use its real shape, ceilings and slabs its through-hole footprint.
+- Sockets: an empty Object3D named anchor:<id> marks where other things attach.
+- No textures, network or DOM. At most 300k triangles, 32 materials, 60 m per side.
+
+Blender instead (language 'bpy'): when the shape is easier with Blender's modelling (bevelled or rounded edges, subdivision-smooth and organic forms, booleans, curves and text, solidify, array, screw and other modifiers), write a bpy module:
+  import bpy, bmesh
+  PARAMS = {"width": {"default": 1.8, "min": 1.2, "max": 2.6, "step": 0.05, "unit": "m", "label": "Width"}}
+  MOUNT = "floor"
+  def build(params): ...   # add objects to the empty scene; everything in it is exported, modifiers applied
+The same conventions in Blender terms: metres, Z up, the front faces -Y (Blender's Front view); part:<id>, light:<id> (a light object; its custom property intensity sets the brightness, default 2), anchor:<id> (an empty), cutout, cut:wall|ceiling|slab and collider are object names; userData is the object's custom properties (obj["type"] = "panel"); slot_<finish> are material names. A clip is one action named open, close, loop or anything else, assigned to every object that moves in it. Use the data API and bmesh, not operators that need a 3D viewport. A Blender build takes a few seconds.
+
+Edit: pass nodeId with new code and/or params (params alone rebuild the stored script; read it first with get_source to change the code); identity, placement, paint and the params you leave out are kept. The result lists the size, parts, slots, lights, animations and params.`;
+/** The `params` field every scripted tool shares (add_object, add_window, add_door, add_column). */
+export const scriptParams = z
+    .record(z.string(), z.union([z.number(), z.boolean(), z.string()]))
+    .optional()
+    .describe("Values for the params the module declares; on an edit, each one you leave out keeps its current value (clamped to the param's range) and a param new to the code starts at its default.");
+/** The `language` field every scripted tool shares. */
+export const scriptLanguage = GeometryScriptLanguage.optional().describe("The code's language: 'three' (default) for a three.js module, 'bpy' for a Blender module (see add_object). On an edit it defaults to the language the object was built in.");
+export const addObjectTool = {
+    name: 'add_object',
+    title: 'Build object',
+    description: DESCRIPTION,
+    input: {
+        code: z
+            .string()
+            .min(1)
+            .max(48_000)
+            .optional()
+            .describe('The module (see the tool description). Required to create; omit to rebuild an object with new params.'),
+        language: scriptLanguage,
+        params: scriptParams,
+        nodeId: NodeId.optional().describe('Edit this existing authored object instead of creating one.'),
+        parentId: NodeId.optional().describe('Host for a new object: a level (default: the floor in view), a wall (wall / wall-side mounts), a ceiling, or an item it rests on.'),
+        position: z
+            .array(z.number())
+            .length(3)
+            .optional()
+            .describe('Placement in the host frame, metres. Level: [x, y, z] (y = 0 on the floor). Wall: [distance along the wall from its start, height of the bottom, 0].'),
+        rotation: measurement('angle', 'deg', {
+            description: 'Y-axis rotation (default: 0).',
+        }).optional(),
+        side: z
+            .enum(['front', 'back'])
+            .optional()
+            .describe('Which wall face a wall-side object sits on.'),
+        ...geometryMetaFields,
+        name: geometryMetaFields.name.describe('What the user would call it ("Front porch").'),
+        category: geometryMetaFields.category.describe('What it is, one word or two ("porch", "lantern", "ceiling", "trim").'),
+        reason: z
+            .string()
+            .min(1)
+            .max(200)
+            .optional()
+            .describe('What it stands in for: why no Pascal tool or catalog item builds it ("no cornice type"). Required to create; an edit keeps it unless given.'),
+    },
+};
+export const getSourceTool = {
+    name: 'get_source',
+    title: 'Read object script',
+    description: 'The module (three.js or Blender bpy, named by language) an object (or a window, door or column built from code) runs, with its params and their current values. Read it before changing its code, then pass the edited module back with the same nodeId: to add_object for an object, to add_window / add_door / add_column for their respective kinds.',
+    input: {
+        nodeId: NodeId.describe('An object, window, door or column built from code.'),
+    },
+};