@ifc-lite/viewer 1.22.0 → 1.23.0

package/src/lib/metadata-clone.test.ts

@@ -0,0 +1,173 @@
+/* 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 { cloneElementMetadata } from './metadata-clone.js';
+
+import { StubStoreEditor, StubView, makeStubDataStore, type OverlayEntity } from './__test__/stubs.js';
+
+function makeStore(byType: Map<string, number[]>) {
+  return makeStubDataStore(byType) as unknown as Parameters<typeof cloneElementMetadata>[0];
+}
+
+describe('metadata-clone', () => {
+  it('appends targets to IfcRelDefinesByProperties RelatedObjects', () => {
+    const rel: OverlayEntity = {
+      expressId: 50,
+      type: 'IFCRELDEFINESBYPROPERTIES',
+      attributes: ['guid', null, null, null, [100], 200],
+    };
+    const editor = new StubStoreEditor([rel]);
+    const view = new StubView() as unknown as Parameters<typeof cloneElementMetadata>[1];
+    const store = makeStore(
+      new Map([['IFCRELDEFINESBYPROPERTIES', [50]]]),
+    );
+    const result = cloneElementMetadata(
+      store,
+      view,
+      editor as unknown as Parameters<typeof cloneElementMetadata>[2],
+      100,
+      [101, 102],
+    );
+    assert.strictEqual(result.relationshipsTouched, 1);
+    assert.deepStrictEqual(editor.getNewEntity(50)?.attributes[4], [100, 101, 102]);
+  });
+
+  it('preserves overlay #X string refs when appending', () => {
+    const rel: OverlayEntity = {
+      expressId: 51,
+      type: 'IFCRELASSOCIATESCLASSIFICATION',
+      // Mix of #X-string refs (overlay-style) — additions should
+      // pick up the same form so the exporter doesn't choke.
+      attributes: ['guid', null, null, null, ['#100', '#101'], '#999'],
+    };
+    const editor = new StubStoreEditor([rel]);
+    const view = new StubView() as unknown as Parameters<typeof cloneElementMetadata>[1];
+    const store = makeStore(
+      new Map([['IFCRELASSOCIATESCLASSIFICATION', [51]]]),
+    );
+    cloneElementMetadata(
+      store,
+      view,
+      editor as unknown as Parameters<typeof cloneElementMetadata>[2],
+      100,
+      [200, 201],
+    );
+    assert.deepStrictEqual(editor.getNewEntity(51)?.attributes[4], ['#100', '#101', '#200', '#201']);
+  });
+
+  it('skips relationships whose RelatedObjects do not include the source', () => {
+    const rel: OverlayEntity = {
+      expressId: 52,
+      type: 'IFCRELDEFINESBYPROPERTIES',
+      attributes: ['guid', null, null, null, [42, 43], 999],
+    };
+    const editor = new StubStoreEditor([rel]);
+    const view = new StubView() as unknown as Parameters<typeof cloneElementMetadata>[1];
+    const store = makeStore(
+      new Map([['IFCRELDEFINESBYPROPERTIES', [52]]]),
+    );
+    const result = cloneElementMetadata(
+      store,
+      view,
+      editor as unknown as Parameters<typeof cloneElementMetadata>[2],
+      100,
+      [200],
+    );
+    assert.strictEqual(result.relationshipsTouched, 0);
+    // Unchanged.
+    assert.deepStrictEqual(editor.getNewEntity(52)?.attributes[4], [42, 43]);
+  });
+
+  it('is idempotent for targets already present', () => {
+    const rel: OverlayEntity = {
+      expressId: 53,
+      type: 'IFCRELDEFINESBYPROPERTIES',
+      attributes: ['guid', null, null, null, [100, 101], 999],
+    };
+    const editor = new StubStoreEditor([rel]);
+    const view = new StubView() as unknown as Parameters<typeof cloneElementMetadata>[1];
+    const store = makeStore(
+      new Map([['IFCRELDEFINESBYPROPERTIES', [53]]]),
+    );
+    // Source = 100 (already in list). Add 101 (also already in list)
+    // and 102 (new). Only 102 should land.
+    cloneElementMetadata(
+      store,
+      view,
+      editor as unknown as Parameters<typeof cloneElementMetadata>[2],
+      100,
+      [101, 102],
+    );
+    assert.deepStrictEqual(editor.getNewEntity(53)?.attributes[4], [100, 101, 102]);
+  });
+
+  it('returns zero touches when the source has no relationships', () => {
+    const editor = new StubStoreEditor([]);
+    const view = new StubView() as unknown as Parameters<typeof cloneElementMetadata>[1];
+    const store = makeStore(new Map());
+    const result = cloneElementMetadata(
+      store,
+      view,
+      editor as unknown as Parameters<typeof cloneElementMetadata>[2],
+      100,
+      [200],
+    );
+    assert.strictEqual(result.relationshipsTouched, 0);
+  });
+
+  it('handles multiple relationship types in one call', () => {
+    const pset: OverlayEntity = {
+      expressId: 60,
+      type: 'IFCRELDEFINESBYPROPERTIES',
+      attributes: ['guid', null, null, null, [100], 999],
+    };
+    const type: OverlayEntity = {
+      expressId: 61,
+      type: 'IFCRELDEFINESBYTYPE',
+      attributes: ['guid', null, null, null, [100], 888],
+    };
+    const editor = new StubStoreEditor([pset, type]);
+    const view = new StubView() as unknown as Parameters<typeof cloneElementMetadata>[1];
+    const store = makeStore(
+      new Map([
+        ['IFCRELDEFINESBYPROPERTIES', [60]],
+        ['IFCRELDEFINESBYTYPE', [61]],
+      ]),
+    );
+    const result = cloneElementMetadata(
+      store,
+      view,
+      editor as unknown as Parameters<typeof cloneElementMetadata>[2],
+      100,
+      [200],
+    );
+    assert.strictEqual(result.relationshipsTouched, 2);
+    assert.deepStrictEqual(editor.getNewEntity(60)?.attributes[4], [100, 200]);
+    assert.deepStrictEqual(editor.getNewEntity(61)?.attributes[4], [100, 200]);
+  });
+
+  it('no-ops with empty target list', () => {
+    const rel: OverlayEntity = {
+      expressId: 70,
+      type: 'IFCRELDEFINESBYPROPERTIES',
+      attributes: ['guid', null, null, null, [100], 999],
+    };
+    const editor = new StubStoreEditor([rel]);
+    const view = new StubView() as unknown as Parameters<typeof cloneElementMetadata>[1];
+    const store = makeStore(
+      new Map([['IFCRELDEFINESBYPROPERTIES', [70]]]),
+    );
+    const result = cloneElementMetadata(
+      store,
+      view,
+      editor as unknown as Parameters<typeof cloneElementMetadata>[2],
+      100,
+      [],
+    );
+    assert.strictEqual(result.relationshipsTouched, 0);
+    assert.deepStrictEqual(editor.getNewEntity(70)?.attributes[4], [100]);
+  });
+});

package/src/lib/metadata-clone.ts

@@ -0,0 +1,124 @@
+/* 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/. */
+
+/**
+ * Carry an element's Pset / Qto / classification / material / type
+ * relationships from a source IfcProduct onto one or more target
+ * products. Used when an authoring operation produces siblings of
+ * a source entity (split, duplicate, etc.) — both halves of a split
+ * wall should keep the source's FireRating, etc.
+ *
+ * Strategy: append the target id(s) to each relationship's
+ * `RelatedObjects` list rather than cloning the relationship entity
+ * itself. Cheaper, less overlay growth, and the IFC schema allows
+ * many objects to share a single rel. Downstream tooling (IDS, Pset
+ * dumps, exports) reads each rel's RelatedObjects list, so the
+ * targets become first-class members.
+ *
+ * The relationships we touch:
+ *
+ *   IfcRelDefinesByProperties   — Psets / Qtos (the big one)
+ *   IfcRelDefinesByType         — occurrence → type binding
+ *   IfcRelAssociatesClassification
+ *   IfcRelAssociatesMaterial
+ *   IfcRelContainedInSpatialStructure — storey containment
+ *   IfcRelAggregates / IfcRelNests    — element assemblies
+ *
+ * Containment is handled separately by callers that already use
+ * `addWallToStore` / `addSlabToStore` etc. (those builders emit a
+ * fresh `IfcRelContainedInSpatialStructure` for the new entity), so
+ * this helper deliberately skips it.
+ *
+ * Returns the number of relationships touched so callers can log
+ * useful telemetry. Returns 0 silently when the source has no
+ * relationships — that's a valid case.
+ */
+
+import type { IfcDataStore } from '@ifc-lite/parser';
+import type { IfcAttributeValue, MutablePropertyView, StoreEditor } from '@ifc-lite/mutations';
+import { asExpressIdRef, readAttributes } from './placement-core.js';
+
+/** Relationship entity types we touch (case follows STEP storage form). */
+const RELATIONSHIPS_TO_CLONE = [
+  // [type, related-objects-attribute-index, related-object-is-list-of-refs?]
+  ['IFCRELDEFINESBYPROPERTIES', 4],
+  ['IFCRELDEFINESBYTYPE', 4],
+  ['IFCRELASSOCIATESCLASSIFICATION', 4],
+  ['IFCRELASSOCIATESMATERIAL', 4],
+  ['IFCRELAGGREGATES', 5],
+  ['IFCRELNESTS', 5],
+] as const;
+
+export interface CloneMetadataResult {
+  /** Number of relationships that gained at least one target. */
+  relationshipsTouched: number;
+}
+
+/**
+ * Coerce a raw RelatedObjects attribute into an array of express ids.
+ * Overlay-stored refs are `#X` strings; parsed source refs are bare
+ * numbers (see `asExpressIdRef`).
+ */
+function relatedObjectIds(raw: unknown): number[] {
+  if (!Array.isArray(raw)) return [];
+  const ids: number[] = [];
+  for (const v of raw) {
+    const id = asExpressIdRef(v);
+    if (id !== null) ids.push(id);
+  }
+  return ids;
+}
+
+/**
+ * Append target ids to the raw RelatedObjects list while preserving
+ * the source's ref form (`#X` strings if any source ref is a string,
+ * raw numbers otherwise). Avoids accidentally normalising overlay
+ * refs into bare numbers, which the exporter wouldn't recognise.
+ */
+function appendTargetsToList(
+  raw: unknown,
+  targets: number[],
+): unknown[] {
+  const list: unknown[] = Array.isArray(raw) ? raw.slice() : [];
+  const usesStrings = list.some((v) => typeof v === 'string');
+  for (const t of targets) {
+    list.push(usesStrings ? `#${t}` : t);
+  }
+  return list;
+}
+
+export function cloneElementMetadata(
+  dataStore: IfcDataStore,
+  view: MutablePropertyView,
+  editor: StoreEditor,
+  sourceExpressId: number,
+  targetExpressIds: number[],
+): CloneMetadataResult {
+  if (targetExpressIds.length === 0) return { relationshipsTouched: 0 };
+
+  // Dedupe caller-side input so a target listed twice doesn't
+  // produce two appends. The per-rel `currentRelated.includes`
+  // guard below would catch it on the second pass, but on the
+  // first pass both copies would land in the new list.
+  const uniqueTargets = Array.from(new Set(targetExpressIds));
+
+  let touched = 0;
+  for (const [type, index] of RELATIONSHIPS_TO_CLONE) {
+    const relIds = dataStore.entityIndex.byType.get(type) ?? [];
+    for (const relId of relIds) {
+      const attrs = readAttributes(dataStore, view, editor, relId);
+      if (!attrs) continue;
+      const currentRelated = relatedObjectIds(attrs[index]);
+      if (!currentRelated.includes(sourceExpressId)) continue;
+      // Skip targets that are already in the list — avoids duplicates
+      // when this is called twice for the same operation (idempotent).
+      const additions = uniqueTargets.filter((t) => !currentRelated.includes(t));
+      if (additions.length === 0) continue;
+      const newList = appendTargetsToList(attrs[index], additions);
+      editor.setPositionalAttribute(relId, index, newList as IfcAttributeValue);
+      touched++;
+    }
+  }
+  return { relationshipsTouched: touched };
+}

package/src/lib/placement-core.ts

@@ -0,0 +1,340 @@
+/* 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/. */
+
+/**
+ * Core placement-chain reader + generic IfcProduct edits.
+ *
+ * Walks the standard product placement chain
+ *
+ *   IfcProduct → ObjectPlacement → IfcLocalPlacement
+ *              → RelativePlacement → IfcAxis2Placement3D
+ *              → Location → IfcCartesianPoint → Coordinates [x, y, z]
+ *
+ * Reads honour the `StoreEditor` overlay (overlay-only entities,
+ * positional-mutation overrides on top of source-buffer entities).
+ * Writes go through `setPositionalAttribute` so they stack with
+ * other overlay edits and participate in the standard undo path.
+ *
+ * Wall-specific edits live in `wall-edit.ts`; this module stays
+ * generic so file size + cognitive scope stay manageable.
+ */
+
+import type { IfcDataStore } from '@ifc-lite/parser';
+import type { MutablePropertyView, StoreEditor } from '@ifc-lite/mutations';
+
+/**
+ * Decode an entity's raw attributes from the source buffer.
+ *
+ * Injected from the call site rather than imported here directly —
+ * `@ifc-lite/parser` transitively pulls in `@ifc-lite/ifcx` /
+ * `@ifc-lite/pointcloud`, which aren't always buildable in the
+ * test environment. The viewer wires this once at module load
+ * (`placement-edit.boot.ts`); tests using only overlay entities
+ * never need to provide it.
+ */
+export type SourceAttrsReader = (
+  dataStore: IfcDataStore,
+  expressId: number,
+) => unknown[] | null;
+
+let configuredSourceReader: SourceAttrsReader | null = null;
+
+/**
+ * Register the parser-backed source reader. Called once during app
+ * boot. Pass `null` to clear (used by tests).
+ */
+export function setSourceAttrsReader(reader: SourceAttrsReader | null): void {
+  configuredSourceReader = reader;
+}
+
+type EntityAttrs = unknown[];
+
+/**
+ * Read the effective attribute list for an express id. Overlay-only
+ * entities come from the StoreEditor; source entities come from the
+ * original buffer. Positional-mutation overrides are layered on top so
+ * a previously-translated point reads back its mutated coords.
+ */
+export function readAttributes(
+  dataStore: IfcDataStore,
+  view: MutablePropertyView,
+  editor: StoreEditor,
+  expressId: number,
+): EntityAttrs | null {
+  const overlay = editor.getNewEntity(expressId);
+  let attrs: EntityAttrs | null = null;
+  if (overlay) {
+    attrs = overlay.attributes.slice();
+  } else if (configuredSourceReader) {
+    attrs = configuredSourceReader(dataStore, expressId);
+    if (!attrs) return null;
+    attrs = attrs.slice();
+  } else {
+    // No source reader configured and no overlay entry — typical in
+    // unit tests that don't wire `setSourceAttrsReader`. Treat as
+    // "unknown entity" so callers fall back gracefully.
+    return null;
+  }
+  // Apply positional mutations so a partially-edited entity reflects
+  // its current state (relevant when the user translates the same
+  // entity twice — the second read must see the first delta).
+  const mutated = view.getPositionalMutationsForEntity(expressId);
+  if (mutated) {
+    for (const [index, value] of mutated.entries()) {
+      attrs[index] = value;
+    }
+  }
+  return attrs;
+}
+
+/**
+ * References take two forms in our attribute graph:
+ *   - number (the parser normalises `#123` → 123 when reading source)
+ *   - string `#123` (overlay entities created via `editor.addEntity`
+ *     carry the raw `#X` form straight through)
+ * Treat both as valid so the chain walker works for source-buffer
+ * AND overlay-only entities — it's the same conceptual reference.
+ */
+export function asExpressIdRef(value: unknown): number | null {
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value === 'string' && value.startsWith('#')) {
+    const id = parseInt(value.slice(1), 10);
+    return Number.isFinite(id) ? id : null;
+  }
+  return null;
+}
+
+export function asCoordinateTriple(value: unknown): [number, number, number] | null {
+  if (!Array.isArray(value)) return null;
+  if (value.length < 2) return null;
+  const x = typeof value[0] === 'number' ? value[0] : NaN;
+  const y = typeof value[1] === 'number' ? value[1] : NaN;
+  // Coordinates may be 2D ([x, y]) — treat the missing Z as 0.
+  const z = value.length >= 3 && typeof value[2] === 'number' ? value[2] : 0;
+  if (Number.isNaN(x) || Number.isNaN(y)) return null;
+  return [x, y, z];
+}
+
+export function asDirectionRatios(value: unknown): [number, number, number] | null {
+  if (!Array.isArray(value)) return null;
+  if (value.length < 2) return null;
+  const x = typeof value[0] === 'number' ? value[0] : NaN;
+  const y = typeof value[1] === 'number' ? value[1] : NaN;
+  const z = value.length >= 3 && typeof value[2] === 'number' ? value[2] : 0;
+  if (Number.isNaN(x) || Number.isNaN(y)) return null;
+  return [x, y, z];
+}
+
+export interface PlacementChain {
+  /** IfcProduct.ObjectPlacement target (IfcLocalPlacement express id). */
+  localPlacementId: number;
+  /** IfcLocalPlacement.RelativePlacement target (IfcAxis2Placement3D express id). */
+  axisPlacementId: number;
+  /** IfcAxis2Placement3D.Location target (IfcCartesianPoint express id). */
+  cartesianPointId: number;
+  /** Current coordinates on the IfcCartesianPoint (storey-local, IFC Z-up). */
+  coordinates: [number, number, number];
+}
+
+/**
+ * Resolve the full placement chain for an IfcProduct. Returns `null`
+ * if any link is missing or has the wrong shape — callers should treat
+ * this as "this entity's placement isn't directly translatable" and
+ * surface a clear message rather than crashing.
+ *
+ * Indices follow the IfcProduct attribute order:
+ *   [0] GlobalId · [1] OwnerHistory · [2] Name · [3] Description
+ *   [4] ObjectType · [5] ObjectPlacement · [6] Representation · ...
+ *
+ * For non-product entities (e.g. profiles, points themselves) attrs[5]
+ * either doesn't exist or isn't a placement reference, so we bail.
+ */
+export function resolvePlacementChain(
+  dataStore: IfcDataStore,
+  view: MutablePropertyView,
+  editor: StoreEditor,
+  expressId: number,
+): PlacementChain | null {
+  const productAttrs = readAttributes(dataStore, view, editor, expressId);
+  if (!productAttrs) return null;
+
+  const localPlacementId = asExpressIdRef(productAttrs[5]);
+  if (localPlacementId === null) return null;
+
+  const localPlacementAttrs = readAttributes(dataStore, view, editor, localPlacementId);
+  if (!localPlacementAttrs) return null;
+
+  // IfcLocalPlacement.RelativePlacement is at index 1
+  // ([0] = PlacementRelTo (parent placement)).
+  const axisPlacementId = asExpressIdRef(localPlacementAttrs[1]);
+  if (axisPlacementId === null) return null;
+
+  const axisAttrs = readAttributes(dataStore, view, editor, axisPlacementId);
+  if (!axisAttrs) return null;
+
+  // IfcAxis2Placement3D.Location at index 0.
+  const cartesianPointId = asExpressIdRef(axisAttrs[0]);
+  if (cartesianPointId === null) return null;
+
+  const pointAttrs = readAttributes(dataStore, view, editor, cartesianPointId);
+  if (!pointAttrs) return null;
+
+  const coordinates = asCoordinateTriple(pointAttrs[0]);
+  if (!coordinates) return null;
+
+  return { localPlacementId, axisPlacementId, cartesianPointId, coordinates };
+}
+
+export type TranslateResult =
+  | { ok: true; oldCoordinates: [number, number, number]; newCoordinates: [number, number, number] }
+  | { ok: false; reason: string };
+
+/**
+ * Translate an IfcProduct by `delta` (storey-local IFC Z-up). Reads
+ * the current coordinates from the chain, adds the delta, writes back
+ * via `setPositionalAttribute`. Caller is responsible for batching
+ * undo (the upstream `setPositionalAttribute` action already pushes a
+ * single mutation onto the model's undo stack).
+ */
+export function translateProduct(
+  dataStore: IfcDataStore,
+  view: MutablePropertyView,
+  editor: StoreEditor,
+  expressId: number,
+  delta: [number, number, number],
+): TranslateResult {
+  const chain = resolvePlacementChain(dataStore, view, editor, expressId);
+  if (!chain) {
+    return {
+      ok: false,
+      reason:
+        'Entity placement is not a simple IfcLocalPlacement → IfcAxis2Placement3D → IfcCartesianPoint chain',
+    };
+  }
+  const [x, y, z] = chain.coordinates;
+  const next: [number, number, number] = [x + delta[0], y + delta[1], z + delta[2]];
+  editor.setPositionalAttribute(chain.cartesianPointId, 0, next);
+  return { ok: true, oldCoordinates: chain.coordinates, newCoordinates: next };
+}
+
+/**
+ * Set the entity's position to an absolute storey-local coordinate.
+ * Convenience over `translateProduct` when the caller has a target
+ * (e.g. a numeric form bound to current coordinates).
+ */
+export function setProductPosition(
+  dataStore: IfcDataStore,
+  view: MutablePropertyView,
+  editor: StoreEditor,
+  expressId: number,
+  position: [number, number, number],
+): TranslateResult {
+  const chain = resolvePlacementChain(dataStore, view, editor, expressId);
+  if (!chain) {
+    return {
+      ok: false,
+      reason:
+        'Entity placement is not a simple IfcLocalPlacement → IfcAxis2Placement3D → IfcCartesianPoint chain',
+    };
+  }
+  editor.setPositionalAttribute(chain.cartesianPointId, 0, position);
+  return { ok: true, oldCoordinates: chain.coordinates, newCoordinates: position };
+}
+
+/**
+ * Snapshot of the placement's IfcAxis2Placement3D rotation.
+ * `refDirectionId === null` means the slot is implicit (STEP `$`) —
+ * the default direction `[1, 0, 0]` is reported, but callers that
+ * want to rotate must refuse this case (no IfcDirection to write to
+ * without orphaning one on undo).
+ */
+export interface RotationState {
+  axisPlacementId: number;
+  refDirectionId: number | null;
+  refDirection: [number, number, number];
+  /** Current yaw about Z (rad). */
+  yawZ: number;
+}
+
+export function resolveRotationState(
+  dataStore: IfcDataStore,
+  view: MutablePropertyView,
+  editor: StoreEditor,
+  expressId: number,
+): RotationState | null {
+  const chain = resolvePlacementChain(dataStore, view, editor, expressId);
+  if (!chain) return null;
+  const axisAttrs = readAttributes(dataStore, view, editor, chain.axisPlacementId);
+  if (!axisAttrs) return null;
+  // IfcAxis2Placement3D index 2 = RefDirection (an optional IfcDirection ref).
+  const refDirectionId = asExpressIdRef(axisAttrs[2]);
+  if (refDirectionId === null) {
+    return {
+      axisPlacementId: chain.axisPlacementId,
+      refDirectionId: null,
+      refDirection: [1, 0, 0],
+      yawZ: 0,
+    };
+  }
+  const dirAttrs = readAttributes(dataStore, view, editor, refDirectionId);
+  if (!dirAttrs) return null;
+  // IfcDirection index 0 = DirectionRatios (list of doubles).
+  const ratios = asDirectionRatios(dirAttrs[0]);
+  if (!ratios) return null;
+  // Yaw about Z derived from the in-plane direction. Numerically
+  // stable for any unit-length input; for non-unit inputs we still
+  // recover the angle from atan2.
+  const yawZ = Math.atan2(ratios[1], ratios[0]);
+  return { axisPlacementId: chain.axisPlacementId, refDirectionId, refDirection: ratios, yawZ };
+}
+
+export type RotateResult =
+  | { ok: true; oldYawZ: number; newYawZ: number; newRefDirection: [number, number, number] }
+  | { ok: false; reason: string };
+
+/**
+ * Rotate an IfcProduct about the storey-up Z axis by `deltaYaw`
+ * radians. Updates RefDirection on the IfcAxis2Placement3D in place
+ * when one already exists.
+ *
+ * Refuses to operate when the placement has no explicit RefDirection
+ * (the implicit `[1, 0, 0]` STEP default). Materialising a fresh
+ * IfcDirection there would require a multi-mutation atomic undo
+ * entry to avoid orphans on undo, which the store doesn't have yet.
+ * Every entity emitted by `@ifc-lite/create`'s in-store builders
+ * carries an explicit RefDirection, so the implicit branch only
+ * trips on hand-rolled source-buffer entities — surfacing a clear
+ * refusal beats silently leaking entities.
+ */
+export function rotateProductYaw(
+  dataStore: IfcDataStore,
+  view: MutablePropertyView,
+  editor: StoreEditor,
+  expressId: number,
+  deltaYaw: number,
+): RotateResult {
+  const state = resolveRotationState(dataStore, view, editor, expressId);
+  if (!state) {
+    return {
+      ok: false,
+      reason:
+        'Entity placement is not a simple IfcLocalPlacement → IfcAxis2Placement3D chain',
+    };
+  }
+  if (state.refDirectionId === null) {
+    return {
+      ok: false,
+      reason:
+        'Entity has an implicit reference direction; rotation requires an explicit IfcDirection on its axis placement.',
+    };
+  }
+  const newYaw = state.yawZ + deltaYaw;
+  const newRatios: [number, number, number] = [
+    Math.cos(newYaw),
+    Math.sin(newYaw),
+    state.refDirection[2],
+  ];
+  editor.setPositionalAttribute(state.refDirectionId, 0, newRatios);
+  return { ok: true, oldYawZ: state.yawZ, newYawZ: newYaw, newRefDirection: newRatios };
+}

package/src/lib/placement-edit.boot.ts

@@ -0,0 +1,21 @@
+/* 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/. */
+
+/**
+ * Boot-time wiring for `placement-edit`. Imported once for its side
+ * effect from the app entrypoint (`main.tsx`). Keeps the
+ * `@ifc-lite/parser` import out of `placement-edit.ts` itself so the
+ * pure overlay-path logic stays unit-testable without a parser build.
+ */
+
+import { EntityExtractor, type IfcDataStore } from '@ifc-lite/parser';
+import { setSourceAttrsReader } from './placement-edit.js';
+
+setSourceAttrsReader((dataStore: IfcDataStore, expressId: number) => {
+  const ref = dataStore.entityIndex.byId.get(expressId);
+  if (!ref) return null;
+  const extractor = new EntityExtractor(dataStore.source);
+  const entity = extractor.extractEntity(ref);
+  return entity?.attributes ?? null;
+});