@ifc-lite/viewer 1.21.0 → 1.22.1

package/src/lib/level-offsets.ts

@@ -0,0 +1,140 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+
+/**
+ * Pure offset math for the Exploded level-display mode.
+ *
+ * Given a model's spatial hierarchy, computes the Y offset (in
+ * world / renderer frame) each storey should receive at a given
+ * `gap`. Index 0 stays at its native elevation; subsequent
+ * storeys (sorted by elevation ascending) lift by
+ * `(index - 0) × gap - elevationDelta` so they end up at
+ * `index × gap` relative to the lowest storey's Y.
+ *
+ * The output is `Map<storeyId, deltaY>` — pure data, no
+ * side-effects — so callers can:
+ *
+ *   1. Compute the target offsets
+ *   2. Subtract the previously-applied offsets
+ *   3. Push the delta into `pendingMeshTranslations`
+ *
+ * That subtraction is what makes mode toggles + gap changes
+ * reversible without re-loading geometry.
+ */
+
+import type { IfcDataStore } from '@ifc-lite/parser';
+
+export type StoreyOffsets = Map<number /* storey express id */, number /* renderer Y offset, m */>;
+
+/**
+ * Compute target offsets for `gap` based on the model's spatial
+ * hierarchy. Returns an empty map for models with no storeys, or
+ * with `gap = 0` (which is Stacked semantics).
+ *
+ * IFC convention: storey elevations are in the model's storey-
+ * local frame (Z-up). The renderer is Y-up, so an IFC elevation
+ * `e` translates to renderer Y `e` (the geometry pipeline already
+ * applies the swap when meshes are built).
+ */
+export function computeStoreyOffsets(
+  dataStore: IfcDataStore | undefined,
+  gap: number,
+): StoreyOffsets {
+  if (!dataStore || !Number.isFinite(gap) || gap <= 0) return new Map();
+  const elevations = dataStore.spatialHierarchy?.storeyElevations;
+  if (!elevations || elevations.size === 0) return new Map();
+
+  // Sort storeys by elevation ascending so the lowest storey
+  // keeps its native Y and everything above lifts.
+  const sorted = [...elevations.entries()].sort((a, b) => a[1] - b[1]);
+  const baseElevation = sorted[0][1];
+  const out: StoreyOffsets = new Map();
+  for (let i = 0; i < sorted.length; i++) {
+    const [storeyId, elevation] = sorted[i];
+    const targetY = baseElevation + i * gap;
+    const offset = targetY - elevation;
+    if (offset !== 0) out.set(storeyId, offset);
+  }
+  return out;
+}
+
+/**
+ * Diff a target offset map against the previously-applied map.
+ * Result: `Map<storeyId, deltaY>` such that
+ *
+ *   newAppliedY = oldAppliedY + delta = targetY
+ *
+ * Storeys present in `previous` but not `target` get a delta of
+ * `-previous[storeyId]` (they're reverting to Stacked). Storeys
+ * in `target` but not `previous` get `+target[storeyId]` (they're
+ * lifting fresh). Storeys in both get the difference.
+ *
+ * Zero deltas are omitted so the caller doesn't push no-ops.
+ */
+export function diffStoreyOffsets(
+  target: StoreyOffsets,
+  previous: StoreyOffsets,
+): StoreyOffsets {
+  const out: StoreyOffsets = new Map();
+  for (const [storeyId, prev] of previous) {
+    const next = target.get(storeyId) ?? 0;
+    const delta = next - prev;
+    if (delta !== 0) out.set(storeyId, delta);
+  }
+  for (const [storeyId, next] of target) {
+    if (previous.has(storeyId)) continue;
+    if (next !== 0) out.set(storeyId, next);
+  }
+  return out;
+}
+
+/**
+ * Resolve every entity in a storey to its globalId for the given
+ * model index. Walks `spatialHierarchy.elementToStorey` and
+ * filters to entries matching `storeyExpressId`. Returns an empty
+ * array when the hierarchy is missing.
+ *
+ * `toGlobalId` is injected so the helper stays free of
+ * FederationRegistry imports (keeps it test-friendly).
+ */
+export function entitiesInStorey(
+  dataStore: IfcDataStore | undefined,
+  storeyExpressId: number,
+  toGlobalId: (localExpressId: number) => number,
+): number[] {
+  if (!dataStore) return [];
+  const map = dataStore.spatialHierarchy?.elementToStorey;
+  if (!map) return [];
+  const out: number[] = [];
+  for (const [elementId, sid] of map) {
+    if (sid !== storeyExpressId) continue;
+    out.push(toGlobalId(elementId));
+  }
+  return out;
+}
+
+/**
+ * Build a per-entity-globalId translation map for a model from a
+ * storey-offset map. Used by the level-display effect to push
+ * into `pendingMeshTranslations`. The translation is along world
+ * +Y only (storey lift) so the X/Z components are zero.
+ *
+ * `toGlobalId` is injected for the same reason as above.
+ */
+export function buildEntityTranslations(
+  dataStore: IfcDataStore | undefined,
+  offsetsByStorey: StoreyOffsets,
+  toGlobalId: (localExpressId: number) => number,
+): Map<number, [number, number, number]> {
+  const out = new Map<number, [number, number, number]>();
+  if (!dataStore || offsetsByStorey.size === 0) return out;
+  const elementToStorey = dataStore.spatialHierarchy?.elementToStorey;
+  if (!elementToStorey) return out;
+  for (const [elementId, storeyId] of elementToStorey) {
+    const dy = offsetsByStorey.get(storeyId);
+    if (dy === undefined || dy === 0) continue;
+    out.set(toGlobalId(elementId), [0, dy, 0]);
+  }
+  return out;
+}

package/src/lib/linear-element-edit.test.ts

@@ -0,0 +1,220 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import {
+  resolveLinearElementChain,
+  computeLinearElementSplitGeometry,
+  projectOntoLinearAxis,
+  MIN_LINEAR_SEGMENT_LENGTH,
+} from './linear-element-edit.js';
+
+import { StubStoreEditor, StubView, makeStubDataStore, type OverlayEntity } from './__test__/stubs.js';
+
+const dataStoreStub = makeStubDataStore() as unknown as Parameters<typeof resolveLinearElementChain>[0];
+
+/**
+ * Beam fixture mirroring `addBeamToStore` output:
+ *   #100 IfcBeam → #99 IfcLocalPlacement → #98 IfcAxis2Placement3D
+ *                       attrs[0] Location = #97 IfcCartesianPoint([1,0,0])
+ *                       attrs[1] Axis     = #96 IfcDirection([1,0,0])
+ *                       attrs[2] RefDir   = (omitted — not relevant for split)
+ *     → Representation #95 IfcProductDefinitionShape
+ *         → [#94 IfcShapeRepresentation]
+ *             → Items[0] = #93 IfcExtrudedAreaSolid
+ *                 attrs[0] SweptArea = #92 IfcRectangleProfileDef (W=0.3, H=0.5)
+ *                 attrs[3] Depth     = 4
+ */
+function makeBeamFixture() {
+  const startPoint: OverlayEntity = {
+    expressId: 97,
+    type: 'IFCCARTESIANPOINT',
+    attributes: [[1, 0, 0]],
+  };
+  const axisDir: OverlayEntity = {
+    expressId: 96,
+    type: 'IFCDIRECTION',
+    attributes: [[1, 0, 0]],
+  };
+  const axisPlacement: OverlayEntity = {
+    expressId: 98,
+    type: 'IFCAXIS2PLACEMENT3D',
+    attributes: [97, 96, null],
+  };
+  const localPlacement: OverlayEntity = {
+    expressId: 99,
+    type: 'IFCLOCALPLACEMENT',
+    attributes: [null, 98],
+  };
+  const profile: OverlayEntity = {
+    expressId: 92,
+    type: 'IFCRECTANGLEPROFILEDEF',
+    attributes: ['.AREA.', null, null, 0.3, 0.5],
+  };
+  const solid: OverlayEntity = {
+    expressId: 93,
+    type: 'IFCEXTRUDEDAREASOLID',
+    attributes: [92, null, null, 4],
+  };
+  const shapeRep: OverlayEntity = {
+    expressId: 94,
+    type: 'IFCSHAPEREPRESENTATION',
+    attributes: [null, 'Body', 'SweptSolid', [93]],
+  };
+  const productShape: OverlayEntity = {
+    expressId: 95,
+    type: 'IFCPRODUCTDEFINITIONSHAPE',
+    attributes: [null, null, [94]],
+  };
+  const beam: OverlayEntity = {
+    expressId: 100,
+    type: 'IFCBEAM',
+    attributes: ['guid', null, 'Beam-1', null, null, 99, 95, null],
+  };
+  return [startPoint, axisDir, axisPlacement, localPlacement, profile, solid, shapeRep, productShape, beam];
+}
+
+/**
+ * Column fixture — same shape but with the IfcAxis2Placement3D
+ * Axis slot set to null (= implicit world +Z), matching what
+ * `addColumnToStore` emits.
+ */
+function makeColumnFixture(depth = 3) {
+  const beam = makeBeamFixture();
+  const axisPlacement = beam.find((e) => e.expressId === 98)!;
+  axisPlacement.attributes = [97, null, null]; // implicit Z
+  const solid = beam.find((e) => e.expressId === 93)!;
+  solid.attributes = [92, null, null, depth];
+  const column = beam.find((e) => e.expressId === 100)!;
+  column.type = 'IFCCOLUMN';
+  return beam;
+}
+
+describe('linear-element-edit', () => {
+  it('resolves an explicit-axis beam chain', () => {
+    const entities = makeBeamFixture();
+    const editor = new StubStoreEditor(entities) as unknown as Parameters<typeof resolveLinearElementChain>[2];
+    const view = new StubView() as unknown as Parameters<typeof resolveLinearElementChain>[1];
+    const chain = resolveLinearElementChain(dataStoreStub, view, editor, 100);
+    assert.ok(chain);
+    assert.strictEqual(chain.elementType, 'IfcBeam');
+    assert.strictEqual(chain.depth, 4);
+    assert.strictEqual(chain.profileWidth, 0.3);
+    assert.strictEqual(chain.profileHeight, 0.5);
+    assert.deepStrictEqual(chain.axisDirection, [1, 0, 0]);
+    assert.deepStrictEqual(chain.startCoordinates, [1, 0, 0]);
+  });
+
+  it('defaults the axis to [0,0,1] for columns with implicit placement', () => {
+    const entities = makeColumnFixture();
+    const editor = new StubStoreEditor(entities) as unknown as Parameters<typeof resolveLinearElementChain>[2];
+    const view = new StubView() as unknown as Parameters<typeof resolveLinearElementChain>[1];
+    const chain = resolveLinearElementChain(dataStoreStub, view, editor, 100);
+    assert.ok(chain);
+    assert.strictEqual(chain.elementType, 'IfcColumn');
+    assert.deepStrictEqual(chain.axisDirection, [0, 0, 1]);
+  });
+
+  it('rejects non-linear element types', () => {
+    const entities = makeBeamFixture();
+    // Mutate the IfcBeam to an IfcWall — chain shouldn't resolve as a
+    // linear element even though the inner graph is shaped right.
+    entities.find((e) => e.expressId === 100)!.type = 'IFCWALL';
+    const editor = new StubStoreEditor(entities) as unknown as Parameters<typeof resolveLinearElementChain>[2];
+    const view = new StubView() as unknown as Parameters<typeof resolveLinearElementChain>[1];
+    assert.strictEqual(resolveLinearElementChain(dataStoreStub, view, editor, 100), null);
+  });
+
+  it('computeLinearElementSplitGeometry produces coherent halves', () => {
+    const entities = makeBeamFixture();
+    const editor = new StubStoreEditor(entities) as unknown as Parameters<typeof resolveLinearElementChain>[2];
+    const view = new StubView() as unknown as Parameters<typeof resolveLinearElementChain>[1];
+    const chain = resolveLinearElementChain(dataStoreStub, view, editor, 100);
+    assert.ok(chain);
+    const result = computeLinearElementSplitGeometry(chain, 1.5);
+    assert.ok(result.ok);
+    assert.strictEqual(result.geometry.leftDepth, 1.5);
+    assert.strictEqual(result.geometry.rightDepth, 2.5);
+    assert.deepStrictEqual(result.geometry.cutPoint, [2.5, 0, 0]); // start (1,0,0) + axis (1,0,0) * 1.5
+    assert.deepStrictEqual(result.geometry.endPoint, [5, 0, 0]); // start + axis * 4
+    assert.strictEqual(result.geometry.width, 0.3);
+    assert.strictEqual(result.geometry.height, 0.5);
+  });
+
+  it('rejects splits inside the min-segment guard', () => {
+    const entities = makeBeamFixture();
+    const editor = new StubStoreEditor(entities) as unknown as Parameters<typeof resolveLinearElementChain>[2];
+    const view = new StubView() as unknown as Parameters<typeof resolveLinearElementChain>[1];
+    const chain = resolveLinearElementChain(dataStoreStub, view, editor, 100);
+    assert.ok(chain);
+    assert.strictEqual(
+      computeLinearElementSplitGeometry(chain, MIN_LINEAR_SEGMENT_LENGTH / 2).ok,
+      false,
+    );
+    assert.strictEqual(
+      computeLinearElementSplitGeometry(chain, chain.depth - MIN_LINEAR_SEGMENT_LENGTH / 2).ok,
+      false,
+    );
+  });
+
+  it('projects cursor onto the axis with correct clamping', () => {
+    const entities = makeBeamFixture();
+    const editor = new StubStoreEditor(entities) as unknown as Parameters<typeof resolveLinearElementChain>[2];
+    const view = new StubView() as unknown as Parameters<typeof resolveLinearElementChain>[1];
+    const chain = resolveLinearElementChain(dataStoreStub, view, editor, 100);
+    assert.ok(chain);
+    // Beam runs from (1,0,0) along +X. Cursor at (3, 0.5, 0) projects
+    // to t = 2 along the axis (X-axis dot product).
+    assert.strictEqual(projectOntoLinearAxis(chain, [3, 0.5, 0]), 2);
+    // Past the end → clamps to depth.
+    assert.strictEqual(projectOntoLinearAxis(chain, [10, 0, 0]), chain.depth);
+    // Before the start → clamps to 0.
+    assert.strictEqual(projectOntoLinearAxis(chain, [-5, 0, 0]), 0);
+  });
+
+  it('column projection works along world +Z', () => {
+    const entities = makeColumnFixture(3);
+    const editor = new StubStoreEditor(entities) as unknown as Parameters<typeof resolveLinearElementChain>[2];
+    const view = new StubView() as unknown as Parameters<typeof resolveLinearElementChain>[1];
+    const chain = resolveLinearElementChain(dataStoreStub, view, editor, 100);
+    assert.ok(chain);
+    // Column at (1,0,0), 3 m tall along +Z. Cursor at (1.2, 0, 2)
+    // projects to t = 2 along Z.
+    assert.strictEqual(projectOntoLinearAxis(chain, [1.2, 0, 2]), 2);
+  });
+
+  it('rejects an explicit zero-length axis', () => {
+    const entities = makeBeamFixture();
+    // Override the axis IfcDirection to (0,0,0).
+    entities.find((e) => e.expressId === 96)!.attributes = [[0, 0, 0]];
+    const editor = new StubStoreEditor(entities) as unknown as Parameters<typeof resolveLinearElementChain>[2];
+    const view = new StubView() as unknown as Parameters<typeof resolveLinearElementChain>[1];
+    assert.strictEqual(resolveLinearElementChain(dataStoreStub, view, editor, 100), null);
+  });
+
+  it('rejects an axis with NaN components', () => {
+    const entities = makeBeamFixture();
+    entities.find((e) => e.expressId === 96)!.attributes = [[NaN, 0, 0]];
+    const editor = new StubStoreEditor(entities) as unknown as Parameters<typeof resolveLinearElementChain>[2];
+    const view = new StubView() as unknown as Parameters<typeof resolveLinearElementChain>[1];
+    assert.strictEqual(resolveLinearElementChain(dataStoreStub, view, editor, 100), null);
+  });
+
+  it('rejects non-finite extrusion depth', () => {
+    const entities = makeBeamFixture();
+    entities.find((e) => e.expressId === 93)!.attributes = [92, null, null, NaN];
+    const editor = new StubStoreEditor(entities) as unknown as Parameters<typeof resolveLinearElementChain>[2];
+    const view = new StubView() as unknown as Parameters<typeof resolveLinearElementChain>[1];
+    assert.strictEqual(resolveLinearElementChain(dataStoreStub, view, editor, 100), null);
+  });
+
+  it('rejects non-finite cross-section dimensions', () => {
+    const entities = makeBeamFixture();
+    entities.find((e) => e.expressId === 92)!.attributes = ['.AREA.', null, null, Infinity, 0.5];
+    const editor = new StubStoreEditor(entities) as unknown as Parameters<typeof resolveLinearElementChain>[2];
+    const view = new StubView() as unknown as Parameters<typeof resolveLinearElementChain>[1];
+    assert.strictEqual(resolveLinearElementChain(dataStoreStub, view, editor, 100), null);
+  });
+});

package/src/lib/linear-element-edit.ts

@@ -0,0 +1,327 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+
+/**
+ * Linear-element split helpers for IfcBeam, IfcColumn, and
+ * IfcMember — entities built by `@ifc-lite/create`'s in-store
+ * builders that share the shape:
+ *
+ *   IfcExtrudedAreaSolid
+ *     ├── SweptArea         : IfcRectangleProfileDef (Width × Height)
+ *     └── Depth             : extrusion length along the placement's
+ *                             local Z (= world axis direction for
+ *                             beams/members; world +Z for columns
+ *                             because their placement's Axis is `$`)
+ *
+ * The split logic is meaningfully different from walls: a wall's
+ * "length" is its profile XDim, so splitting requires rewriting
+ * four entities. A beam / column / member's "length" is the
+ * extrusion `Depth`, so we can shrink the source in place (one
+ * positional write) and add a fresh element at the cut point.
+ * Source identity (GlobalId, Pset rels) is preserved for the
+ * "left" half — cleaner downstream than the wall's two-new-walls
+ * approach, but the choice is dictated by the IFC representation,
+ * not preference.
+ */
+
+import type { IfcDataStore } from '@ifc-lite/parser';
+import type { MutablePropertyView, StoreEditor } from '@ifc-lite/mutations';
+import {
+  asExpressIdRef,
+  asCoordinateTriple,
+  asDirectionRatios,
+  readAttributes,
+  resolvePlacementChain,
+} from './placement-core.js';
+
+export const MIN_LINEAR_SEGMENT_LENGTH = 0.05; // metres
+
+/**
+ * Element types this module handles. Maps to the STEP storage form
+ * (`IFCBEAM`, …) — the slice's `splitLinearElementAtDistance` action
+ * picks the right `addBeam` / `addColumn` / `addMember` follow-up
+ * based on this value.
+ */
+export type LinearElementType = 'IfcBeam' | 'IfcColumn' | 'IfcMember';
+
+const LINEAR_ELEMENT_STEP_TYPES = new Set(['IFCBEAM', 'IFCCOLUMN', 'IFCMEMBER']);
+
+function stepTypeToLinearType(stepType: string): LinearElementType | null {
+  switch (stepType.toUpperCase()) {
+    case 'IFCBEAM':
+      return 'IfcBeam';
+    case 'IFCCOLUMN':
+      return 'IfcColumn';
+    case 'IFCMEMBER':
+      return 'IfcMember';
+    default:
+      return null;
+  }
+}
+
+export interface LinearElementEditChain {
+  /** STEP type name, for the slice's dispatch (`IfcBeam` / `IfcColumn` / `IfcMember`). */
+  elementType: LinearElementType;
+  /** Placement origin point id (storey-local). */
+  startPointId: number;
+  /** Current start coordinates in storey-local space. */
+  startCoordinates: [number, number, number];
+  /**
+   * World-axis direction of the extrusion in storey-local space.
+   * For beams / members this is the explicit
+   * `IfcAxis2Placement3D.Axis` IfcDirection. For columns it's the
+   * implicit default `[0, 0, 1]` (placement Axis = `$`).
+   */
+  axisDirection: [number, number, number];
+  /** IfcExtrudedAreaSolid id; holds the length on attribute 3 (`Depth`). */
+  extrudedSolidId: number;
+  /** Current extrusion length (metres). */
+  depth: number;
+  /** Profile cross-section width (X dimension, metres). */
+  profileWidth: number;
+  /** Profile cross-section height (Y dimension, metres). */
+  profileHeight: number;
+}
+
+function readEntityType(
+  dataStore: IfcDataStore,
+  view: MutablePropertyView,
+  editor: StoreEditor,
+  expressId: number,
+): string | null {
+  const overlay = editor.getNewEntity(expressId);
+  if (overlay) return overlay.type;
+  // Source-buffer entities: the parser's entityIndex.byId stores
+  // type per ref. Pull it through `byType` reverse-walk only if we
+  // can't avoid it. Simpler path: read the attributes via the
+  // source reader; if the reader path returns nothing the entity
+  // either doesn't exist or isn't reachable from where we stand.
+  const ref = dataStore.entityIndex.byId.get(expressId);
+  return ref?.type ?? null;
+}
+
+/**
+ * Resolve the chain for an IfcBeam / IfcColumn / IfcMember whose
+ * representation matches what `addBeamToStore` / `addColumnToStore`
+ * / `addMemberToStore` produce. Returns null when the chain doesn't
+ * match (mapped representation, non-rectangle profile, missing
+ * placement, etc.) so the caller can hide the split affordance.
+ */
+export function resolveLinearElementChain(
+  dataStore: IfcDataStore,
+  view: MutablePropertyView,
+  editor: StoreEditor,
+  expressId: number,
+): LinearElementEditChain | null {
+  const rawType = readEntityType(dataStore, view, editor, expressId);
+  if (!rawType || !LINEAR_ELEMENT_STEP_TYPES.has(rawType.toUpperCase())) return null;
+  const elementType = stepTypeToLinearType(rawType);
+  if (!elementType) return null;
+
+  // ObjectPlacement chain — gives us the start point AND the
+  // IfcAxis2Placement3D id for axis lookup.
+  const chain = resolvePlacementChain(dataStore, view, editor, expressId);
+  if (!chain) return null;
+
+  // Pull the axis direction. IfcAxis2Placement3D.Axis (index 1) may
+  // be null → implicit world +Z (matches the column builder).
+  const axisAttrs = readAttributes(dataStore, view, editor, chain.axisPlacementId);
+  if (!axisAttrs) return null;
+  const axisDirId = asExpressIdRef(axisAttrs[1]);
+  let axisDirection: [number, number, number] = [0, 0, 1];
+  if (axisDirId !== null) {
+    const dirAttrs = readAttributes(dataStore, view, editor, axisDirId);
+    if (!dirAttrs) return null;
+    const ratios = asDirectionRatios(dirAttrs[0]);
+    if (!ratios) return null;
+    // Reject NaN / Infinity components — those would propagate into
+    // every downstream split / projection call. The builder writes
+    // unit vectors but source-buffer entities can be malformed.
+    if (!Number.isFinite(ratios[0]) || !Number.isFinite(ratios[1]) || !Number.isFinite(ratios[2])) {
+      return null;
+    }
+    const len = Math.hypot(ratios[0], ratios[1], ratios[2]);
+    // Zero-length axis isn't translatable; refuse rather than fall
+    // back silently to world +Z (which would silently mis-orient
+    // every downstream operation).
+    if (len < 1e-9) return null;
+    axisDirection = [ratios[0] / len, ratios[1] / len, ratios[2] / len];
+  }
+
+  // Representation chain: same shape as walls but the length lives
+  // on the extrusion depth, not the profile XDim.
+  const elementAttrs = readAttributes(dataStore, view, editor, expressId);
+  if (!elementAttrs) return null;
+  const productShapeId = asExpressIdRef(elementAttrs[6]);
+  if (productShapeId === null) return null;
+  const productShapeAttrs = readAttributes(dataStore, view, editor, productShapeId);
+  if (!productShapeAttrs) return null;
+  const reps = productShapeAttrs[2];
+  if (!Array.isArray(reps) || reps.length === 0) return null;
+  const shapeRepId = asExpressIdRef(reps[0]);
+  if (shapeRepId === null) return null;
+  const shapeRepAttrs = readAttributes(dataStore, view, editor, shapeRepId);
+  if (!shapeRepAttrs) return null;
+  const items = shapeRepAttrs[3];
+  if (!Array.isArray(items) || items.length === 0) return null;
+  const solidId = asExpressIdRef(items[0]);
+  if (solidId === null) return null;
+
+  const solidAttrs = readAttributes(dataStore, view, editor, solidId);
+  if (!solidAttrs) return null;
+  const profileId = asExpressIdRef(solidAttrs[0]);
+  const depthRaw = solidAttrs[3];
+  if (
+    profileId === null ||
+    typeof depthRaw !== 'number' ||
+    !Number.isFinite(depthRaw) ||
+    depthRaw <= 0
+  ) {
+    return null;
+  }
+
+  // Cross-section dimensions from the IfcRectangleProfileDef
+  // (Width = XDim attr 3, Height = YDim attr 4). Not strictly
+  // needed for the split math, but exposed so callers building the
+  // new element can carry the same cross-section forward. Reject
+  // non-finite / non-positive — would silently produce zero-area
+  // or NaN-area profiles downstream.
+  const profileAttrs = readAttributes(dataStore, view, editor, profileId);
+  if (!profileAttrs) return null;
+  const profileWidth = profileAttrs[3];
+  const profileHeight = profileAttrs[4];
+  if (
+    typeof profileWidth !== 'number' ||
+    typeof profileHeight !== 'number' ||
+    !Number.isFinite(profileWidth) ||
+    !Number.isFinite(profileHeight) ||
+    profileWidth <= 0 ||
+    profileHeight <= 0
+  ) {
+    return null;
+  }
+
+  return {
+    elementType,
+    startPointId: chain.cartesianPointId,
+    startCoordinates: chain.coordinates,
+    axisDirection,
+    extrudedSolidId: solidId,
+    depth: depthRaw,
+    profileWidth,
+    profileHeight,
+  };
+}
+
+export interface LinearSplitGeometry {
+  /** Length the source's extrusion shrinks to (= split distance from start). */
+  leftDepth: number;
+  /** Cut point in storey-local space. */
+  cutPoint: [number, number, number];
+  /** End of the source (storey-local) — also the end of the new right half. */
+  endPoint: [number, number, number];
+  /** Length the new right-half element takes. */
+  rightDepth: number;
+  /** Cross-section dimensions to copy onto the new element. */
+  width: number;
+  height: number;
+}
+
+export type LinearSplitResult =
+  | { ok: true; geometry: LinearSplitGeometry }
+  | { ok: false; reason: string };
+
+/**
+ * Pure split-geometry math. Splits the linear element at
+ * `distance` metres from start. Returns the cut point + remaining
+ * lengths so the caller can shrink the source and add the right
+ * half via the matching `addBeam` / `addColumn` / `addMember`
+ * action.
+ *
+ * Same min-segment guard as walls (`MIN_LINEAR_SEGMENT_LENGTH`)
+ * so dragging the cursor to the very end of a column doesn't
+ * produce a sliver.
+ */
+export function computeLinearElementSplitGeometry(
+  chain: LinearElementEditChain,
+  distance: number,
+): LinearSplitResult {
+  if (!Number.isFinite(distance)) {
+    return { ok: false, reason: 'Split distance must be a finite number' };
+  }
+  if (
+    distance <= MIN_LINEAR_SEGMENT_LENGTH ||
+    distance >= chain.depth - MIN_LINEAR_SEGMENT_LENGTH
+  ) {
+    return {
+      ok: false,
+      reason: `Split must be at least ${MIN_LINEAR_SEGMENT_LENGTH} m from each end (element is ${chain.depth.toFixed(2)} m)`,
+    };
+  }
+  const [sx, sy, sz] = chain.startCoordinates;
+  const [dx, dy, dz] = chain.axisDirection;
+  const cut: [number, number, number] = [sx + dx * distance, sy + dy * distance, sz + dz * distance];
+  const end: [number, number, number] = [
+    sx + dx * chain.depth,
+    sy + dy * chain.depth,
+    sz + dz * chain.depth,
+  ];
+  return {
+    ok: true,
+    geometry: {
+      leftDepth: distance,
+      cutPoint: cut,
+      endPoint: end,
+      rightDepth: chain.depth - distance,
+      width: chain.profileWidth,
+      height: chain.profileHeight,
+    },
+  };
+}
+
+/**
+ * Project an arbitrary storey-local 3D cursor onto the element's
+ * axis and return how far along the element (in metres from start)
+ * it lands. Clamps to `[0, depth]`.
+ */
+export function projectOntoLinearAxis(
+  chain: LinearElementEditChain,
+  pointStoreyLocal: [number, number, number],
+): number {
+  const [px, py, pz] = pointStoreyLocal;
+  const [sx, sy, sz] = chain.startCoordinates;
+  const [dx, dy, dz] = chain.axisDirection;
+  const ux = px - sx;
+  const uy = py - sy;
+  const uz = pz - sz;
+  // Axis is unit-length by resolveLinearElementChain's contract; we
+  // still divide through for robustness.
+  const denom = dx * dx + dy * dy + dz * dz;
+  if (denom < 1e-9) return 0;
+  const t = (ux * dx + uy * dy + uz * dz) / denom;
+  return Math.max(0, Math.min(chain.depth, t));
+}
+
+/**
+ * Shrink the source linear element's extrusion to `newDepth`. Used
+ * by the split action's "left half" branch — the source's
+ * placement, axis, profile, and Pset relationships all stay; only
+ * the IfcExtrudedAreaSolid.Depth changes.
+ *
+ * Coerce-only: this is the equivalent of `setPositionalAttribute`
+ * for a known slot; we expose it via the helper module for
+ * symmetry with the other split helpers.
+ */
+export function shrinkLinearElementDepth(
+  editor: StoreEditor,
+  chain: LinearElementEditChain,
+  newDepth: number,
+): void {
+  editor.setPositionalAttribute(chain.extrudedSolidId, 3, newDepth);
+}
+
+// Re-export the asCoordinateTriple helper so callers that import
+// linear-element-edit don't have to reach into placement-core too.
+// Keeps the import surface tight for the slice action.
+export { asCoordinateTriple };