@ifc-lite/viewer 1.21.0 → 1.22.1

package/src/lib/llm/clipboard-detect.test.ts

@@ -0,0 +1,150 @@
+/* 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 test from 'node:test';
+import assert from 'node:assert/strict';
+import { looksLikeProviderKey, maskKey, readClipboardKey } from './clipboard-detect.js';
+
+// ── looksLikeProviderKey ───────────────────────────────────────────────────
+
+test('looksLikeProviderKey accepts a realistic Anthropic console key', () => {
+  // 14-char prefix + 50 random body chars
+  const key = 'sk-ant-api03-' + 'a'.repeat(60);
+  assert.equal(looksLikeProviderKey('anthropic', key), true);
+});
+
+test('looksLikeProviderKey rejects too-short Anthropic key', () => {
+  const key = 'sk-ant-api03-tooshort';
+  assert.equal(looksLikeProviderKey('anthropic', key), false);
+});
+
+test('looksLikeProviderKey rejects Anthropic key with wrong prefix', () => {
+  assert.equal(looksLikeProviderKey('anthropic', 'sk-' + 'a'.repeat(80)), false);
+  assert.equal(looksLikeProviderKey('anthropic', 'sk-ant-api01-' + 'a'.repeat(80)), false);
+});
+
+test('looksLikeProviderKey accepts a legacy OpenAI key', () => {
+  assert.equal(looksLikeProviderKey('openai', 'sk-' + 'a'.repeat(48)), true);
+});
+
+test('looksLikeProviderKey accepts an OpenAI project key', () => {
+  assert.equal(looksLikeProviderKey('openai', 'sk-proj-' + 'a'.repeat(48)), true);
+});
+
+test('looksLikeProviderKey accepts an OpenAI service-account key', () => {
+  assert.equal(looksLikeProviderKey('openai', 'sk-svcacct-' + 'a'.repeat(48)), true);
+});
+
+test('looksLikeProviderKey rejects random clipboard contents', () => {
+  assert.equal(looksLikeProviderKey('anthropic', 'hello world'), false);
+  assert.equal(looksLikeProviderKey('openai', 'https://example.com/?foo=bar'), false);
+  assert.equal(looksLikeProviderKey('openai', ''), false);
+});
+
+test('looksLikeProviderKey trims leading/trailing whitespace before matching', () => {
+  const key = 'sk-ant-api03-' + 'a'.repeat(60);
+  assert.equal(looksLikeProviderKey('anthropic', `  ${key}\n`), true);
+});
+
+// ── maskKey ────────────────────────────────────────────────────────────────
+
+test('maskKey preserves Anthropic prefix and last 4 chars', () => {
+  const key = 'sk-ant-api03-' + 'a'.repeat(56) + 'WXYZ';
+  const masked = maskKey(key);
+  assert.equal(masked.startsWith('sk-ant-api03-'), true);
+  assert.equal(masked.endsWith('WXYZ'), true);
+  assert.equal(masked.includes('••••'), true);
+});
+
+test('maskKey preserves OpenAI project prefix', () => {
+  const key = 'sk-proj-' + 'a'.repeat(40) + 'WXYZ';
+  const masked = maskKey(key);
+  assert.equal(masked.startsWith('sk-proj-'), true);
+  assert.equal(masked.endsWith('WXYZ'), true);
+});
+
+test('maskKey preserves bare sk- prefix for legacy keys', () => {
+  const key = 'sk-' + 'a'.repeat(45) + 'WXYZ';
+  const masked = maskKey(key);
+  assert.equal(masked.startsWith('sk-'), true);
+  assert.equal(masked.endsWith('WXYZ'), true);
+});
+
+test('maskKey falls back to bullets for absurdly short input', () => {
+  assert.equal(maskKey('short'), '••••');
+  assert.equal(maskKey(''), '••••');
+});
+
+// ── readClipboardKey ──────────────────────────────────────────────────────
+// We can't easily simulate a real browser Clipboard API in node:test, but we
+// can verify the helper degrades gracefully when navigator/clipboard is absent
+// and returns the matched key when a stub is provided.
+//
+// `globalThis.navigator` is defined as a getter in modern Node, so we use
+// Object.defineProperty with configurable:true to swap it for the duration
+// of each test, then restore the original descriptor.
+
+function withNavigator<T>(stub: unknown, fn: () => T): T {
+  const original = Object.getOwnPropertyDescriptor(globalThis, 'navigator');
+  Object.defineProperty(globalThis, 'navigator', {
+    value: stub,
+    configurable: true,
+    writable: true,
+  });
+  try {
+    return fn();
+  } finally {
+    if (original) {
+      Object.defineProperty(globalThis, 'navigator', original);
+    } else {
+      delete (globalThis as { navigator?: unknown }).navigator;
+    }
+  }
+}
+
+test('readClipboardKey returns null when navigator.clipboard is unavailable', async () => {
+  const result = await withNavigator({ clipboard: undefined }, () => readClipboardKey('anthropic'));
+  assert.equal(result, null);
+});
+
+test('readClipboardKey returns matched key when clipboard contents shape-match', async () => {
+  const goodKey = 'sk-ant-api03-' + 'b'.repeat(70);
+  const result = await withNavigator(
+    { clipboard: { readText: async () => goodKey } },
+    () => readClipboardKey('anthropic'),
+  );
+  assert.equal(result, goodKey);
+});
+
+test('readClipboardKey returns null when clipboard contents are unrelated', async () => {
+  const result = await withNavigator(
+    { clipboard: { readText: async () => 'just a normal copied string' } },
+    () => readClipboardKey('anthropic'),
+  );
+  assert.equal(result, null);
+});
+
+test('readClipboardKey swallows clipboard read errors and returns null', async () => {
+  const result = await withNavigator(
+    {
+      clipboard: {
+        readText: async () => {
+          throw new Error('NotAllowedError: permission denied');
+        },
+      },
+    },
+    () => readClipboardKey('openai'),
+  );
+  assert.equal(result, null);
+});
+
+test('readClipboardKey wrong-provider clipboard returns null', async () => {
+  // Anthropic key on clipboard, but we're checking for an OpenAI key
+  const anthropicKey = 'sk-ant-api03-' + 'c'.repeat(70);
+  const result = await withNavigator(
+    { clipboard: { readText: async () => anthropicKey } },
+    () => readClipboardKey('openai'),
+  );
+  assert.equal(result, null);
+});

package/src/lib/llm/clipboard-detect.ts

@@ -0,0 +1,90 @@
+/* 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/. */
+
+/**
+ * Clipboard sniffing for the BYOK key modal.
+ *
+ * After the user clicks our "Open Console" button, they create a key on the
+ * provider's site, copy it, and return to this tab. If transient activation
+ * (or clipboard-read permission) is still valid, we can detect the key and
+ * offer one-click insertion instead of forcing a manual paste.
+ *
+ * Reads are best-effort and silently no-op on:
+ *   - missing Clipboard API (older Safari, insecure context, sandboxed iframe)
+ *   - permission denied (Firefox without explicit user grant)
+ *   - read failure for any other reason
+ *
+ * We never throw on these — the modal just falls back to its manual paste UX.
+ */
+
+export type BYOKProvider = 'anthropic' | 'openai';
+
+/**
+ * Provider-specific shape checks. Tight enough to avoid false positives on
+ * random clipboard contents, permissive enough to cover the key formats each
+ * provider currently issues.
+ *
+ *   Anthropic console keys: `sk-ant-api03-` + ≥50 chars of [A-Za-z0-9_-]
+ *   OpenAI keys:            `sk-`, `sk-proj-`, `sk-svcacct-`, `sk-admin-` + ≥20 chars
+ *
+ * The OpenAI pattern uses a negative lookahead for `ant-` so an Anthropic key
+ * doesn't accidentally satisfy the OpenAI tab — they both start with `sk-`.
+ */
+const PROVIDER_PATTERNS: Record<BYOKProvider, RegExp> = {
+  anthropic: /^sk-ant-api03-[A-Za-z0-9_-]{50,}$/,
+  openai: /^sk-(?!ant-)(?:proj-|svcacct-|admin-)?[A-Za-z0-9_-]{20,}$/,
+};
+
+/**
+ * Try to read a candidate provider key from the system clipboard.
+ *
+ * Returns the trimmed key string if the clipboard contents match the provider
+ * pattern. Returns `null` for everything else (no match, permission denied,
+ * Clipboard API unavailable, etc.) — callers should treat `null` as "fall back
+ * to manual paste".
+ */
+export async function readClipboardKey(provider: BYOKProvider): Promise<string | null> {
+  if (typeof navigator === 'undefined' || !navigator.clipboard?.readText) {
+    return null;
+  }
+  try {
+    const text = await navigator.clipboard.readText();
+    const trimmed = text.trim();
+    if (PROVIDER_PATTERNS[provider].test(trimmed)) {
+      return trimmed;
+    }
+    return null;
+  } catch (err) {
+    // Permission denied / insecure context / no transient activation — these
+    // are expected on Firefox and Safari without an explicit user grant, and
+    // the manual-paste fallback still works. Log at debug level for diagnostic
+    // but never escalate to the UI.
+    console.debug('[byok] clipboard read failed', err);
+    return null;
+  }
+}
+
+/**
+ * Render-safe key mask. Preserves the provider prefix so the user can confirm
+ * the right key is detected, hides the secret middle, shows the last 4 chars
+ * for disambiguation.
+ *
+ *   sk-ant-api03-abcdef…XYZA
+ *   sk-proj-••••XYZA
+ *   sk-••••XYZA
+ */
+export function maskKey(key: string): string {
+  if (key.length < 12) return '••••';
+  const dashIdx = key.lastIndexOf('-');
+  const prefixEnd = dashIdx > 0 && dashIdx < 14 ? dashIdx + 1 : Math.min(14, key.length - 4);
+  return `${key.slice(0, prefixEnd)}••••${key.slice(-4)}`;
+}
+
+/**
+ * Light shape check shared with `readClipboardKey` so callers can validate
+ * manual paste contents the same way before saving.
+ */
+export function looksLikeProviderKey(provider: BYOKProvider, value: string): boolean {
+  return PROVIDER_PATTERNS[provider].test(value.trim());
+}

package/src/lib/llm/models.ts

@@ -139,6 +139,20 @@ export const FREE_MODELS: LLMModel[] = rawFreeModels.map(applyCapabilities);
 // Requests go directly from the browser to the provider (no server proxy).
 
 const ANTHROPIC_BYOK_MODELS: LLMModel[] = [
+  {
+    id: 'claude-opus-4-7',
+    name: 'Claude Opus 4.7',
+    provider: 'Anthropic',
+    tier: 'byok',
+    source: 'anthropic',
+    contextWindow: 1_000_000,
+    supportsImages: true,
+    supportsFileAttachments: true,
+    cost: '$$$',
+    // Opus 4.7 returns 400 if temperature/top_p/top_k are present.
+    // See `whats-new-claude-4-7` docs § Sampling parameters removed.
+    acceptsSamplingParams: false,
+  },
   {
     id: 'claude-opus-4-6',
     name: 'Claude Opus 4.6',
@@ -175,6 +189,20 @@ const ANTHROPIC_BYOK_MODELS: LLMModel[] = [
 ];
 
 const OPENAI_BYOK_MODELS: LLMModel[] = [
+  {
+    id: 'gpt-5.5',
+    name: 'GPT-5.5',
+    provider: 'OpenAI',
+    tier: 'byok',
+    source: 'openai',
+    contextWindow: 1_000_000,
+    supportsImages: true,
+    supportsFileAttachments: true,
+    cost: '$$$',
+    // GPT-5 reasoning family only accepts the default temperature (1).
+    // Sending any other value returns 400 from /v1/chat/completions.
+    acceptsSamplingParams: false,
+  },
   {
     id: 'gpt-5.4',
     name: 'GPT-5.4',

package/src/lib/llm/stream-direct.ts

@@ -15,6 +15,7 @@
 
 import Anthropic from '@anthropic-ai/sdk';
 import { readSseStream, type StreamMessage, type StreamOptions } from './stream-client.js';
+import { getModelById } from './models.js';
 
 const STREAM_REQUEST_TIMEOUT_MS = 45_000;
 
@@ -71,12 +72,19 @@ export async function streamAnthropicChat(
     dangerouslyAllowBrowser: true,
   });
 
+  // Opus 4.7+ returns 400 if `temperature` (or `top_p`/`top_k`) is present.
+  // We gate on the per-model `acceptsSamplingParams` flag in models.ts so
+  // future Claude models that adopt the same policy only need a flag bump,
+  // and Opus 4.6 / Sonnet 4.6 / Haiku 4.5 keep their tuned temperature.
+  const modelDef = getModelById(model);
+  const sendSamplingParams = modelDef?.acceptsSamplingParams !== false;
+
   let fullText = '';
   try {
     const stream = client.messages.stream({
       model,
       max_tokens: 8192,
-      temperature: 0.3,
+      ...(sendSamplingParams ? { temperature: 0.3 } : {}),
       system: system || undefined,
       messages: toAnthropicMessages(messages),
     });
@@ -118,8 +126,6 @@ export async function streamAnthropicChat(
 
 // ── OpenAI ─────────────────────────────────────────────────────────────────
 
-import { getModelById } from './models.js';
-
 /**
  * Stream an OpenAI model. Automatically picks the right API:
  * - Chat Completions (`/v1/chat/completions`) for standard chat models
@@ -147,13 +153,19 @@ async function streamOpenAiChatCompletions(
     ? [{ role: 'system', content: system }, ...messages]
     : [...messages];
 
+  // GPT-5 reasoning models (gpt-5.5, gpt-5.5-pro) only accept the default
+  // temperature; sending any other value returns 400. Mirror the Anthropic
+  // path: when the model is flagged `acceptsSamplingParams: false`, omit.
+  const modelDef = getModelById(model);
+  const sendSamplingParams = modelDef?.acceptsSamplingParams !== false;
+
   const { response, cleanup } = await openAiFetch(
     'https://api.openai.com/v1/chat/completions',
     {
       model,
       messages: allMessages.map((m) => ({ role: m.role, content: m.content })),
       stream: true,
-      temperature: 0.3,
+      ...(sendSamplingParams ? { temperature: 0.3 } : {}),
       max_completion_tokens: 8192,
     },
     apiKey,

package/src/lib/llm/types.ts

@@ -163,6 +163,14 @@ export interface LLMModel {
   cost?: ModelCost;
   /** OpenAI API variant: 'chat' (default) or 'responses' (Codex-style models) */
   openaiApi?: 'chat' | 'responses';
+  /**
+   * Whether the model accepts the classic sampling parameters (`temperature`,
+   * `top_p`, `top_k`). Default: true. Set to `false` for models that reject
+   * them (Anthropic Claude Opus 4.7 and later — see
+   * https://platform.claude.com/docs/en/about-claude/models/whats-new-claude-4-7).
+   * When `false`, the stream client omits these params from the request body.
+   */
+  acceptsSamplingParams?: boolean;
 }
 
 export type ChatStatus = 'idle' | 'sending' | 'streaming' | 'error';

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 };
+}