@pascal-app/core 1.0.3 → 1.0.5

package/dist/services/roof-bearing.js

@@ -0,0 +1,234 @@
+import { pointInPolygon } from '../agent-operations/plan-geometry.js';
+import { nodesOnLevel } from '../agent-operations/scene-queries.js';
+import { getConicalRoofCoverage, getRoofSegmentDeckReach, getSegmentSlopeFrame, } from '../schema/index.js';
+import { resolveRoomRoofFootprintOnLevel } from '../systems/roof/roof-footprint.js';
+import { computeWallSlabSupport } from '../systems/slab/slab-support.js';
+import { sampleWallCenterline } from '../systems/wall/wall-curve.js';
+import { resolveWallTop } from '../systems/wall/wall-top.js';
+import { getWallPlaneTop } from './storey.js';
+const r3 = (value) => Math.round(value * 1000) / 1000;
+/** Pascal's plan rotation: positive turns local +z toward +x (the roof, stair and item convention). */
+function rot(x, z, angle) {
+    const c = Math.cos(angle);
+    const s = Math.sin(angle);
+    return [x * c + z * s, -x * s + z * c];
+}
+/** Where each wall of a level stands, in that level's metres: on the slab it is elected to, up to its own height or the storey's plane. */
+export function wallSpans(nodes, levelId) {
+    const content = nodesOnLevel(nodes, levelId);
+    const slabs = content.filter((node) => node.type === 'slab');
+    const walls = content.filter((node) => node.type === 'wall');
+    return new Map(walls.map((wall) => {
+        const support = computeWallSlabSupport(wall, slabs, walls, wall.supportSlabId, undefined, 0, nodes);
+        const top = resolveWallTop(wall, getWallPlaneTop(wall, levelId, nodes), support.elevation);
+        return [wall.id, { base: support.elevation, top }];
+    }));
+}
+/** A segment drawn over a rectangle of wall centre lines, [x0, z0, x1, z1], with its ridge along `ridgeAxis`. */
+export function shapeOfRect(rect, ridgeAxis, roofType, pitchDeg) {
+    const [ax, az, bx, bz] = rect;
+    const w = Math.abs(bx - ax);
+    const d = Math.abs(bz - az);
+    const width = ridgeAxis === 'x' ? w : d;
+    const depth = ridgeAxis === 'x' ? d : w;
+    return {
+        cx: (ax + bx) / 2,
+        cz: (az + bz) / 2,
+        yaw: ridgeAxis === 'x' ? 0 : -Math.PI / 2,
+        hw: width / 2,
+        hd: depth / 2,
+        reach: { x: 0, z: 0 },
+        roofType,
+        peak: getSegmentSlopeFrame({ roofType, pitch: pitchDeg, width, depth }).activeRh,
+    };
+}
+/** A segment where it stands, in its roof's level plan, through its roof container's placement. */
+export function segmentShape(nodes, segmentId) {
+    const segment = nodes[segmentId];
+    const roof = segment?.type === 'roof-segment' ? nodes[segment.parentId ?? ''] : undefined;
+    if (segment?.type !== 'roof-segment' || roof?.type !== 'roof')
+        return null;
+    const [ox, oz] = rot(segment.position[0], segment.position[2], roof.rotation);
+    const frame = getSegmentSlopeFrame(segment);
+    const coverage = segment.roofType === 'conical' ? getConicalRoofCoverage(segment) : null;
+    return {
+        cx: roof.position[0] + ox,
+        cz: roof.position[2] + oz,
+        yaw: roof.rotation + segment.rotation,
+        hw: segment.width / 2,
+        hd: segment.depth / 2,
+        reach: getRoofSegmentDeckReach(segment),
+        roofType: segment.roofType,
+        peak: frame.activeRh,
+        ...(coverage && !coverage.fullCircle
+            ? { sector: { start: coverage.startAngle, sweep: coverage.sweepAngle } }
+            : {}),
+    };
+}
+const toLocal = (shape, point) => rot(point[0] - shape.cx, point[1] - shape.cz, -shape.yaw);
+const toPlan = (shape, local) => {
+    const [x, z] = rot(local[0], local[1], shape.yaw);
+    return [shape.cx + x, shape.cz + z];
+};
+/** How far the roof stands above its eave over a point of its own frame (0 outside its walls). */
+export function riseAt(shape, lx, lz) {
+    const ex = shape.hw - Math.abs(lx);
+    const ez = shape.hd - Math.abs(lz);
+    if (ex < -1e-6 || ez < -1e-6 || shape.peak <= 0 || shape.hw <= 0 || shape.hd <= 0)
+        return 0;
+    switch (shape.roofType) {
+        case 'flat':
+            return 0;
+        // a shed rises from its low eave at +z to its high one at -z
+        case 'shed':
+            return (shape.peak * (shape.hd - lz)) / (2 * shape.hd);
+        case 'gable':
+        case 'gambrel':
+            return (shape.peak * Math.max(0, ez)) / shape.hd;
+        case 'conical':
+            return shape.peak * Math.max(0, 1 - Math.hypot(lx, lz) / shape.hw);
+        default:
+            return (shape.peak * Math.max(0, Math.min(ex, ez))) / Math.min(shape.hw, shape.hd);
+    }
+}
+/** A wall within this of a roof's edge line runs along that edge. */
+const ON_EDGE = 0.2;
+/** Less of a wall than this along an edge only crosses its end. */
+const MIN_OVERLAP = 0.3;
+/** How far past a wall's face the far side is read. */
+const BEYOND = 0.3;
+// Identity-keyed, as `getLevelElevations` is: `nodes` is an immutable scene snapshot, so one seat
+// or verify pass reads each level's walls, rooms and wall tops once, however many segments it tests
+// against them (a 500-node paste of 450 segments read the whole scene per wall per segment: 13 s).
+const planMemo = new WeakMap();
+/** A level's visible walls, its rooms and where its walls stand. */
+function planOf(nodes, levelId) {
+    let memo = planMemo.get(nodes);
+    if (!memo) {
+        memo = new Map();
+        planMemo.set(nodes, memo);
+    }
+    const hit = memo.get(levelId);
+    if (hit)
+        return hit;
+    const walls = [];
+    const rooms = [];
+    for (const node of Object.values(nodes)) {
+        if (node.parentId !== levelId)
+            continue;
+        if (node.type === 'wall' && node.visible !== false)
+            walls.push(node);
+        else if (node.type === 'zone' && node.polygon.length >= 3)
+            rooms.push(node);
+    }
+    const plan = { walls, rooms, spans: wallSpans(nodes, levelId) };
+    memo.set(levelId, plan);
+    return plan;
+}
+/** Whether the far side of a wall, at `probe`, is indoors: in a room, or labelled interior on a level with no rooms. */
+function indoors(rooms, wall, probe) {
+    if (rooms.length)
+        return rooms.some((room) => pointInPolygon(probe, room.polygon));
+    const dx = wall.end[0] - wall.start[0];
+    const dz = wall.end[1] - wall.start[1];
+    const length = Math.hypot(dx, dz) || 1;
+    // the door renderer's perpendicular: the direction turned 90° (x, z) → (-z, x)
+    const front = (probe[0] - wall.start[0]) * (-dz / length) + (probe[1] - wall.start[1]) * (dx / length) > 0;
+    return (front ? wall.frontSide : wall.backSide) === 'interior';
+}
+const bearing = (wall, top, rise) => ({
+    id: wall.id,
+    name: wall.name ?? wall.id,
+    top: r3(top),
+    rise,
+});
+/** Whether a local angle of a cone falls in its sector. */
+function inSector(shape, angle) {
+    if (!shape.sector)
+        return true;
+    const { start, sweep } = shape.sector;
+    const turn = Math.PI * 2;
+    const from = (((sweep >= 0 ? angle - start : start - angle) % turn) + turn) % turn;
+    return from <= Math.abs(sweep) + 1e-6;
+}
+/** The walls of a level a cone sits on: along its eave circle, within its sector, open air past them. */
+function coneWallsUnder({ walls, rooms, spans }, shape) {
+    const found = [];
+    for (const wall of walls) {
+        const top = spans.get(wall.id)?.top;
+        if (top === undefined)
+            continue;
+        const points = sampleWallCenterline(wall, 24).map(({ x, y }) => toLocal(shape, [x, y]));
+        const onEave = points.map(([lx, lz]) => Math.abs(Math.hypot(lx, lz) - shape.hw) <= ON_EDGE && inSector(shape, Math.atan2(lz, lx)));
+        let along = 0;
+        for (let i = 1; i < points.length; i++)
+            if (onEave[i - 1] && onEave[i])
+                along += Math.hypot(points[i][0] - points[i - 1][0], points[i][1] - points[i - 1][1]);
+        if (along < MIN_OVERLAP)
+            continue;
+        const stretch = points.filter((_, i) => onEave[i]);
+        const [lx, lz] = stretch[Math.floor(stretch.length / 2)];
+        const out = (shape.hw + (wall.thickness ?? 0.15) / 2 + BEYOND) / (Math.hypot(lx, lz) || 1);
+        if (!indoors(rooms, wall, toPlan(shape, [lx * out, lz * out])))
+            found.push(bearing(wall, top, 0));
+    }
+    return found;
+}
+/** The walls of a level a roof sits on, each with its top and the least the roof rises over it. */
+export function wallsUnder(nodes, levelId, shape) {
+    const plan = planOf(nodes, levelId);
+    if (shape.roofType === 'conical')
+        return coneWallsUnder(plan, shape);
+    const found = [];
+    for (const wall of plan.walls) {
+        const a = toLocal(shape, wall.start);
+        const b = toLocal(shape, wall.end);
+        for (const [across, at] of [
+            [1, -shape.hd],
+            [1, shape.hd],
+            [0, -shape.hw],
+            [0, shape.hw],
+        ]) {
+            if (Math.abs(a[across] - at) > ON_EDGE || Math.abs(b[across] - at) > ON_EDGE)
+                continue;
+            const [ua, ub] = across === 1 ? [a[0], b[0]] : [a[1], b[1]];
+            const half = across === 1 ? shape.hw : shape.hd;
+            const u0 = Math.max(-half, Math.min(ua, ub));
+            const u1 = Math.min(half, Math.max(ua, ub));
+            if (u1 - u0 < MIN_OVERLAP)
+                continue;
+            const point = (u, off = 0) => (across === 1 ? [u, at + off] : [at + off, u]);
+            const out = Math.sign(at) * ((wall.thickness ?? 0.15) / 2 + BEYOND);
+            const indoorsAt = (u, off) => indoors(plan.rooms, wall, toPlan(shape, point(u, off)));
+            // A wall running on past the roof's end with rooms on the roof's side there belongs to a
+            // house the roof dies into (a porch box buried in it, a full-width porch flush with its
+            // sides): the roof does not sit on it.
+            const intoHouse = (Math.min(ua, ub) < -half - ON_EDGE && indoorsAt(-half - BEYOND, -out)) ||
+                (Math.max(ua, ub) > half + ON_EDGE && indoorsAt(half + BEYOND, -out));
+            const top = plan.spans.get(wall.id)?.top;
+            if (top !== undefined && !intoHouse && !indoorsAt((u0 + u1) / 2, out))
+                found.push(bearing(wall, top, Math.min(riseAt(shape, ...point(u0)), riseAt(shape, ...point(u1)))));
+            break;
+        }
+    }
+    return found;
+}
+/** The eave a roof needs to clear the walls it sits on, in their level's metres; null when it sits on none. */
+export const seatOn = (walls) => walls.length ? r3(Math.max(...walls.map((wall) => wall.top - wall.rise))) : null;
+/** The walls of `levelId` a segment bears on, and the eave they need (null: it bears on none). */
+export function segmentBearing(nodes, segmentId, levelId) {
+    const shape = segmentShape(nodes, segmentId);
+    const walls = shape ? wallsUnder(nodes, levelId, shape) : [];
+    return { walls, need: seatOn(walls) };
+}
+/**
+ * Whether a roof footprint with no segment of its own yet (a rectangle drawn by hand, an imported
+ * roof plane) stands over a storey: an edge of it bears on the level's walls (`wallsUnder`), or it
+ * covers a room those walls enclose (a rectangle drawn loosely over a house). A porch or portico
+ * over posts beside the house does neither, and stays on the storey with its posts.
+ */
+export function standsOverStorey(nodes, levelId, shape) {
+    return (wallsUnder(nodes, levelId, shape).length > 0 ||
+        resolveRoomRoofFootprintOnLevel(levelId, nodes, [shape.cx, shape.cz]) !==
+            null);
+}

package/dist/services/roof-level.d.ts

@@ -0,0 +1,121 @@
+import { type AnyNode, LevelNode, type RoofNode } from '../schema/index.js';
+/**
+ * Roofs and levels, one rule for every path that writes a roof (the editor's roof tool, the
+ * agents' create_roof, plugins): a roof lives on the level directly above the storey whose walls
+ * carry it. Over a building's top storey that is the building's roof level, kept above every
+ * storey, so exploded and solo level views lift the roof off the plan.
+ */
+type Nodes = Readonly<Record<string, AnyNode>>;
+/**
+ * Whether a node of this kind belongs on a storey, never on a roof level: a storey's structure and
+ * rooms, and every kind that stands on a floor (`capabilities.floorPlaced`: cabinets, shelves,
+ * columns, …).
+ */
+export declare const isStoreyContent: (type: string | undefined, metadata: Record<string, unknown> | undefined) => boolean;
+/** Retained roof geometry participates in level presentation without becoming parametric. */
+export declare const isRoofGeometry: (node: AnyNode | undefined) => boolean;
+/** Retained ceiling shells can lift with the roof while native room ceilings keep their hosts. */
+export declare const isCeilingGeometry: (node: AnyNode | undefined) => boolean;
+/** A level declared for its building's roofs (`metadata.role: 'roof'`). */
+export declare function isRoofLevel(node: AnyNode | undefined): boolean;
+/**
+ * A level that is its building's roof level: declared, whatever it holds (`verify_scene` reports a
+ * declared one someone walled); or, in a building that declares none, a level holding roofs and
+ * nothing a storey holds (a roof level written before levels declared it) with only such levels
+ * above it. Never the lowest level, a carport's roof on its posts being its ground floor. A level
+ * holding only roofs under a storey, or beside a declared roof level, is a storey still to be built
+ * with a lower wing's roof on it: it takes walls. The one rule every reader of a level's role goes
+ * by (`list_levels`, `verify_scene`, the agents' refusals, the editor's level stack and tools).
+ */
+export declare function servesAsRoofLevel(nodes: Nodes, level: LevelNode): boolean;
+export type RoofLevelPlan = 
+/** A storey stands above: it takes a roof over part of the storey below. */
+({
+    kind: 'storey';
+    levelId: string;
+}
+/** The building's roof level, `create`d first when it has none, `update`d when undeclared. */
+ | {
+    kind: 'roof';
+    levelId: string;
+    create: LevelNode | null;
+    update: {
+        id: string;
+        data: Partial<LevelNode>;
+    }[];
+}) & {
+    /**
+     * The storey's floor from the target level's, once the plan is written (m, negative): a roof
+     * measured from the storey's floor sits its container this high on the target level.
+     */
+    storeyOffset: number;
+};
+/**
+ * The level that takes the roofs over `storeyId`'s walls, as the scene stands. With a storey built
+ * above (anything on it), the storey directly above takes the roof over part of the one below: a
+ * porch, a lower wing. Else the building's roof level, above every level still to be built and
+ * every support level: the roof level there; the empty level directly above when it is the only
+ * one; else none yet (`level` null). Reads only, so a panel can ask on every store change.
+ */
+export declare function roofLevelAbove(nodes: Nodes, storeyId: string): {
+    kind: 'storey';
+    level: LevelNode;
+} | {
+    kind: 'roof';
+    level: LevelNode | null;
+};
+/**
+ * Where a roof carried by `storeyId`'s walls lives (`roofLevelAbove`): the storey directly above,
+ * or the building's roof level, declared if it was not, else a new "Roof" level `roofHeight` tall
+ * (the roof's rise over its eaves) on top. Pure: the caller writes the plan in the same step as the
+ * roof.
+ */
+export declare function planRoofLevel(nodes: Nodes, storeyId: string, roofHeight: number): RoofLevelPlan;
+/**
+ * The storey a level stands for: for a level serving as a roof level, the storey it covers
+ * (`storeyUnder`); else the level itself. Where storey content aimed at a roof level goes.
+ */
+export declare function storeyOf(nodes: Nodes, levelId: string): string;
+/**
+ * The storey a roof covers. On a roof level, the storey under it (`storeyUnder`). On a storey, the
+ * storey below when the roof stands near its floor (a porch's or a lower wing's roof, seated on the
+ * walls under it, as the rule places it); else the storey itself (a roof written on its own walls'
+ * level, before roof levels). Null off a level.
+ */
+export declare function coveredStoreyId(nodes: Nodes, roof: RoofNode): string | null;
+/** The roofs over a storey, wherever they stand (`coveredStoreyId`). */
+export declare function roofsOver(nodes: Nodes, storeyId: string): RoofNode[];
+/**
+ * Where a new top storey of `buildingId` goes: on top of its storeys, under the roof levels at the
+ * top of its stack, which each move up one (`shift`), so the roof stays above every storey.
+ */
+export declare function storeyInsertIndex(nodes: Nodes, buildingId: string): {
+    floorIndex: number;
+    shift: {
+        id: string;
+        data: Pick<LevelNode, 'level'>;
+    }[];
+};
+/**
+ * After a write that adds levels to `buildingId` (`before` to `after`), the floor indexes that keep
+ * its roof levels above every other level: the ones topping its stack before, and a roof level the
+ * write declares. An update per roof level that has to go up; none for a roof level in the middle
+ * of a stack, which a write that does not touch it leaves where it is.
+ */
+export declare function liftRoofLevels(before: Nodes, after: Nodes, buildingId: string): {
+    id: string;
+    data: Pick<LevelNode, 'level'>;
+}[];
+/**
+ * New floor indexes (`floors`: level id to its index) that put a building's roof level under one of
+ * its storeys it stood over: that pair, else null. Roles are read as the levels stand
+ * (`servesAsRoofLevel`), so an order a legacy stack already had passes, and so does one among
+ * storeys only. The one check every reorder goes by (the level selector, the chat's
+ * `reorder_level`, the capture app's REST reorder, `apply_patch`).
+ */
+export declare function roofLevelOrderBreach(nodes: Nodes, floors: ReadonlyMap<string, number>): {
+    roofId: string;
+    storeyId: string;
+} | null;
+export {};
+//# sourceMappingURL=roof-level.d.ts.map

package/dist/services/roof-level.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roof-level.d.ts","sourceRoot":"","sources":["../../src/services/roof-level.ts"],"names":[],"mappings":"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"}

package/dist/services/roof-level.js

@@ -0,0 +1,280 @@
+import { getDefaultLevelName, getLevelDisplayName } from '../lib/level-name.js';
+import { nodeRegistry } from '../registry/index.js';
+import { LevelNode } from '../schema/index.js';
+import { getLevelElevations } from './storey.js';
+/** What a storey holds and a roof level must not: its structure and rooms. */
+const STOREY_CONTENT = new Set([
+    'wall',
+    'zone',
+    'slab',
+    'ceiling',
+    'item',
+    'stair',
+]);
+/**
+ * Whether a node of this kind belongs on a storey, never on a roof level: a storey's structure and
+ * rooms, and every kind that stands on a floor (`capabilities.floorPlaced`: cabinets, shelves,
+ * columns, …).
+ */
+export const isStoreyContent = (type, metadata) => type !== undefined &&
+    !(type === 'item' && (metadata?.role === 'roof' || metadata?.role === 'ceiling')) &&
+    (STOREY_CONTENT.has(type) || nodeRegistry.get(type)?.capabilities?.floorPlaced !== undefined);
+/** Retained roof geometry participates in level presentation without becoming parametric. */
+export const isRoofGeometry = (node) => node?.type === 'roof' || (node?.type === 'item' && node.metadata?.role === 'roof');
+/** Retained ceiling shells can lift with the roof while native room ceilings keep their hosts. */
+export const isCeilingGeometry = (node) => node?.type === 'ceiling' || (node?.type === 'item' && node.metadata?.role === 'ceiling');
+/** A level declared for its building's roofs (`metadata.role: 'roof'`). */
+export function isRoofLevel(node) {
+    return node?.type === 'level' && node.metadata?.role === 'roof';
+}
+/** A level declared to carry structure, not rooms (`metadata.role: 'support'`). */
+const isSupportLevel = (level) => level.metadata?.role === 'support';
+const childrenOf = (nodes, level) => level.children.map((id) => nodes[id]).filter((child) => child !== undefined);
+/** A level holding roofs and nothing a storey holds, unless declared a support. */
+const holdsOnlyRoofs = (nodes, level) => {
+    if (isSupportLevel(level))
+        return false;
+    const children = childrenOf(nodes, level);
+    return (children.some(isRoofGeometry) &&
+        !children.some((child) => isStoreyContent(child.type, child.metadata)));
+};
+/** A building's levels: those it lists, and those naming it as their parent. */
+function levelsOf(nodes, buildingId) {
+    const building = buildingId ? nodes[buildingId] : undefined;
+    const listed = new Set(building?.type === 'building' ? building.children : []);
+    return Object.values(nodes).filter((node) => node.type === 'level' && (node.parentId === (buildingId ?? null) || listed.has(node.id)));
+}
+/**
+ * A level that is its building's roof level: declared, whatever it holds (`verify_scene` reports a
+ * declared one someone walled); or, in a building that declares none, a level holding roofs and
+ * nothing a storey holds (a roof level written before levels declared it) with only such levels
+ * above it. Never the lowest level, a carport's roof on its posts being its ground floor. A level
+ * holding only roofs under a storey, or beside a declared roof level, is a storey still to be built
+ * with a lower wing's roof on it: it takes walls. The one rule every reader of a level's role goes
+ * by (`list_levels`, `verify_scene`, the agents' refusals, the editor's level stack and tools).
+ */
+export function servesAsRoofLevel(nodes, level) {
+    if (isRoofLevel(level))
+        return true;
+    if (!holdsOnlyRoofs(nodes, level))
+        return false;
+    const stack = levelsOf(nodes, level.parentId);
+    return (!stack.some(isRoofLevel) &&
+        stack.some((other) => other.level < level.level) &&
+        stack.every((other) => other.level <= level.level || holdsOnlyRoofs(nodes, other)));
+}
+const elevationsOf = (nodes) => getLevelElevations(nodes);
+/** The other levels of a level's building, in stack order, below it or above it. */
+function stackOf(nodes, levelId, side) {
+    const elevations = elevationsOf(nodes);
+    const own = elevations.get(levelId);
+    if (!own)
+        return [];
+    return [...elevations]
+        .filter(([, entry]) => entry.buildingId === own.buildingId &&
+        (side === 'above' ? entry.ordinal > own.ordinal : entry.ordinal < own.ordinal))
+        .sort(([, a], [, b]) => (side === 'above' ? a.ordinal - b.ordinal : b.ordinal - a.ordinal))
+        .map(([id]) => nodes[id])
+        .filter((node) => node?.type === 'level');
+}
+/** How far `storeyId`'s floor sits from `levelId`'s (m): negative, the storey being below. */
+function storeyOffsetTo(nodes, storeyId, levelId) {
+    const elevations = elevationsOf(nodes);
+    return (elevations.get(storeyId)?.baseY ?? 0) - (elevations.get(levelId)?.baseY ?? 0);
+}
+/** A level reused as the roof level, declared when it was not. */
+function roofLevelPlan(nodes, storeyId, level) {
+    return {
+        kind: 'roof',
+        levelId: level.id,
+        storeyOffset: storeyOffsetTo(nodes, storeyId, level.id),
+        create: null,
+        update: isRoofLevel(level)
+            ? []
+            : [
+                {
+                    id: level.id,
+                    data: {
+                        metadata: { ...level.metadata, role: 'roof' },
+                        // A name a person gave stays; an unnamed level would read as a floor.
+                        name: getLevelDisplayName(level) === getDefaultLevelName(level.level)
+                            ? 'Roof'
+                            : level.name,
+                    },
+                },
+            ],
+    };
+}
+/**
+ * The level that takes the roofs over `storeyId`'s walls, as the scene stands. With a storey built
+ * above (anything on it), the storey directly above takes the roof over part of the one below: a
+ * porch, a lower wing. Else the building's roof level, above every level still to be built and
+ * every support level: the roof level there; the empty level directly above when it is the only
+ * one; else none yet (`level` null). Reads only, so a panel can ask on every store change.
+ */
+export function roofLevelAbove(nodes, storeyId) {
+    const above = stackOf(nodes, storeyId, 'above');
+    const isPlain = (level) => !servesAsRoofLevel(nodes, level) && !isSupportLevel(level);
+    // The roof stands on the storey directly above, an empty one still to be built included.
+    if (above.some((level) => isPlain(level) && level.children.length > 0))
+        return { kind: 'storey', level: above.find(isPlain) };
+    const top = above.filter((level) => !servesAsRoofLevel(nodes, level)).at(-1);
+    const roofLevel = above.find((level) => servesAsRoofLevel(nodes, level) && (!top || level.level > top.level));
+    if (roofLevel)
+        return { kind: 'roof', level: roofLevel };
+    if (above.length === 1 && isPlain(above[0]))
+        return { kind: 'roof', level: above[0] };
+    return { kind: 'roof', level: null };
+}
+/**
+ * Where a roof carried by `storeyId`'s walls lives (`roofLevelAbove`): the storey directly above,
+ * or the building's roof level, declared if it was not, else a new "Roof" level `roofHeight` tall
+ * (the roof's rise over its eaves) on top. Pure: the caller writes the plan in the same step as the
+ * roof.
+ */
+export function planRoofLevel(nodes, storeyId, roofHeight) {
+    const storey = nodes[storeyId];
+    if (storey?.type !== 'level')
+        throw Error(`${storeyId} is not a level`);
+    const target = roofLevelAbove(nodes, storeyId);
+    if (target.kind === 'storey')
+        return {
+            kind: 'storey',
+            levelId: target.level.id,
+            storeyOffset: storeyOffsetTo(nodes, storeyId, target.level.id),
+        };
+    if (target.level)
+        return roofLevelPlan(nodes, storeyId, target.level);
+    const top = stackOf(nodes, storeyId, 'above')
+        .filter((level) => !servesAsRoofLevel(nodes, level))
+        .at(-1);
+    const level = LevelNode.parse({
+        name: 'Roof',
+        parentId: storey.parentId,
+        level: (top ?? storey).level + 1,
+        height: Math.max(roofHeight, 0.2),
+        children: [],
+        metadata: { role: 'roof' },
+    });
+    return {
+        kind: 'roof',
+        levelId: level.id,
+        storeyOffset: storeyOffsetTo({ ...nodes, [level.id]: level }, storeyId, level.id),
+        create: level,
+        update: [],
+    };
+}
+/**
+ * The storey under a roof level: the highest below it that holds something (levels still to be
+ * built and support levels between are passed over), else the level directly below; the level
+ * itself with none below.
+ */
+function storeyUnder(nodes, level) {
+    const below = stackOf(nodes, level.id, 'below');
+    return (below.find((other) => !servesAsRoofLevel(nodes, other) && !isSupportLevel(other) && other.children.length > 0) ??
+        below[0] ??
+        level).id;
+}
+/**
+ * The storey a level stands for: for a level serving as a roof level, the storey it covers
+ * (`storeyUnder`); else the level itself. Where storey content aimed at a roof level goes.
+ */
+export function storeyOf(nodes, levelId) {
+    const level = nodes[levelId];
+    return level?.type === 'level' && servesAsRoofLevel(nodes, level)
+        ? storeyUnder(nodes, level)
+        : levelId;
+}
+/**
+ * The storey a roof covers. On a roof level, the storey under it (`storeyUnder`). On a storey, the
+ * storey below when the roof stands near its floor (a porch's or a lower wing's roof, seated on the
+ * walls under it, as the rule places it); else the storey itself (a roof written on its own walls'
+ * level, before roof levels). Null off a level.
+ */
+export function coveredStoreyId(nodes, roof) {
+    const level = roof.parentId ? nodes[roof.parentId] : undefined;
+    if (level?.type !== 'level')
+        return null;
+    if (servesAsRoofLevel(nodes, level))
+        return storeyUnder(nodes, level);
+    const below = stackOf(nodes, level.id, 'below');
+    if (!below.length)
+        return level.id;
+    const height = elevationsOf(nodes).get(level.id)?.height ?? 0;
+    return roof.position[1] < height / 2 ? below[0].id : level.id;
+}
+/** The roofs over a storey, wherever they stand (`coveredStoreyId`). */
+export function roofsOver(nodes, storeyId) {
+    return Object.values(nodes).filter((node) => node.type === 'roof' && coveredStoreyId(nodes, node) === storeyId);
+}
+/**
+ * The roof levels topping a building's stack (`servesAsRoofLevel`, which keeps an undeclared lowest
+ * level a storey), bottom up: a building whose only level is declared the roof level has that one.
+ */
+function topRoofLevels(nodes, buildingId) {
+    const levels = levelsOf(nodes, buildingId).sort((a, b) => a.level - b.level);
+    let top = levels.length;
+    while (top > 0 && servesAsRoofLevel(nodes, levels[top - 1]))
+        top--;
+    return levels.slice(top);
+}
+/**
+ * Where a new top storey of `buildingId` goes: on top of its storeys, under the roof levels at the
+ * top of its stack, which each move up one (`shift`), so the roof stays above every storey.
+ */
+export function storeyInsertIndex(nodes, buildingId) {
+    const roofLevels = topRoofLevels(nodes, buildingId);
+    if (!roofLevels.length) {
+        const levels = levelsOf(nodes, buildingId);
+        return {
+            floorIndex: levels.length ? Math.max(...levels.map((level) => level.level)) + 1 : 0,
+            shift: [],
+        };
+    }
+    return {
+        floorIndex: roofLevels[0].level,
+        shift: roofLevels.map((level) => ({ id: level.id, data: { level: level.level + 1 } })),
+    };
+}
+/**
+ * After a write that adds levels to `buildingId` (`before` to `after`), the floor indexes that keep
+ * its roof levels above every other level: the ones topping its stack before, and a roof level the
+ * write declares. An update per roof level that has to go up; none for a roof level in the middle
+ * of a stack, which a write that does not touch it leaves where it is.
+ */
+export function liftRoofLevels(before, after, buildingId) {
+    const ids = new Set(topRoofLevels(before, buildingId).map((level) => level.id));
+    const levels = levelsOf(after, buildingId);
+    for (const level of levels)
+        if (!before[level.id] && isRoofLevel(level))
+            ids.add(level.id);
+    const roofs = levels.filter((level) => ids.has(level.id)).sort((a, b) => a.level - b.level);
+    const others = levels.filter((level) => !ids.has(level.id));
+    if (!(roofs.length && others.length))
+        return [];
+    const top = Math.max(...others.map((level) => level.level));
+    return roofs.flatMap((level, i) => {
+        const floor = Math.max(level.level, top + 1 + i);
+        return floor === level.level ? [] : [{ id: level.id, data: { level: floor } }];
+    });
+}
+/**
+ * New floor indexes (`floors`: level id to its index) that put a building's roof level under one of
+ * its storeys it stood over: that pair, else null. Roles are read as the levels stand
+ * (`servesAsRoofLevel`), so an order a legacy stack already had passes, and so does one among
+ * storeys only. The one check every reorder goes by (the level selector, the chat's
+ * `reorder_level`, the capture app's REST reorder, `apply_patch`).
+ */
+export function roofLevelOrderBreach(nodes, floors) {
+    const floorOf = (level) => floors.get(level.id) ?? level.level;
+    const buildings = new Set([...floors.keys()].map((id) => nodes[id]).flatMap((node) => (node ? [node.parentId] : [])));
+    for (const buildingId of buildings) {
+        const levels = levelsOf(nodes, buildingId);
+        const roofs = levels.filter((level) => servesAsRoofLevel(nodes, level));
+        for (const roof of roofs)
+            for (const storey of levels.filter((level) => !roofs.includes(level)))
+                if (roof.level > storey.level && floorOf(roof) < floorOf(storey))
+                    return { roofId: roof.id, storeyId: storey.id };
+    }
+    return null;
+}