@ifc-lite/viewer 1.21.0 → 1.22.0

package/src/lib/geo/terrain-elevation.ts

@@ -13,13 +13,34 @@
 
 import { queryTerrainElevation } from './reproject';
 
+export type TerrainElevationSource =
+  | 'globe.getHeight'
+  | 'scene.sampleHeight'
+  | 'scene.sampleHeightMostDetailed'
+  | 'open-meteo';
+
+export type TerrainHeightReference = 'ellipsoidal' | 'visual-surface' | 'orthometric';
+
+export interface TerrainElevationSample {
+  height: number;
+  source: TerrainElevationSource;
+  reference: TerrainHeightReference;
+  cacheNamespace: string;
+  fromCache: boolean;
+}
+
+export interface ResolveTerrainElevationOptions {
+  cacheNamespace?: string;
+  preferOrthometric?: boolean;
+}
+
 // Module-level cache so bridge rebuilds (georef edits, clamp toggles)
 // re-use values within the session instead of re-hitting the network.
-const terrainElevationCache = new Map<string, number>();
+const terrainElevationCache = new Map<string, TerrainElevationSample>();
 
-function terrainCacheKey(lat: number, lon: number): string {
+function terrainCacheKey(lat: number, lon: number, cacheNamespace: string): string {
   // 5 decimal places ≈ 1.1m precision — plenty for site-level elevation.
-  return `${lat.toFixed(5)},${lon.toFixed(5)}`;
+  return `${cacheNamespace}:${lat.toFixed(5)},${lon.toFixed(5)}`;
 }
 
 // Earth's plausible terrestrial elevation range. Mariana Trench ≈ −11 km
@@ -45,122 +66,210 @@ export function clearTerrainElevationCache(): void {
  *
  * Order:
  *   1. Cache (instant — re-bridge after georef edit).
- *   2. globe.getHeight (sync, terrain provider — exact-zero treated as
- *      "no data" since the default ellipsoid provider returns 0 for every
- *      lat/lon).
- *   3. scene.sampleHeight (sync, queries 3D Tiles + terrain — only works
+ *   2. scene.sampleHeight (sync, queries 3D Tiles + terrain — only works
  *      if tiles for the location are already rendered).
- *   4. scene.sampleHeightMostDetailed with a bounded timeout — forces tile
+ *   3. scene.sampleHeightMostDetailed with a bounded timeout — forces tile
  *      load and returns the height of the actually-rendered surface (what
  *      the user SEES in Google Photorealistic 3D Tiles). Tried before
  *      Open-Meteo because the visible-tile elevation is what models need
  *      to sit on; Open-Meteo's DEM ignores buildings/road surfaces.
+ *   4. globe.getHeight (terrain provider fallback — exact-zero treated as
+ *      "no data" since the default ellipsoid provider returns 0 for every
+ *      lat/lon).
  *   5. Open-Meteo elevation API — bare-earth fallback when tiles can't be
  *      sampled (offline, no 3D tileset, timeout, etc.).
  */
 const SAMPLE_DETAILED_TIMEOUT_MS = 3500;
 
-export async function resolveTerrainElevation(
+function getTerrainSourceReference(source: TerrainElevationSource): TerrainHeightReference {
+  switch (source) {
+    case 'globe.getHeight':
+      return 'ellipsoidal';
+    case 'scene.sampleHeight':
+    case 'scene.sampleHeightMostDetailed':
+      return 'visual-surface';
+    case 'open-meteo':
+      return 'orthometric';
+  }
+}
+
+function acceptTerrainElevation(
+  cacheKey: string,
+  height: number,
+  source: TerrainElevationSource,
+  cacheNamespace: string,
+  ms?: number,
+): TerrainElevationSample {
+  const sample: TerrainElevationSample = {
+    height,
+    source,
+    reference: getTerrainSourceReference(source),
+    cacheNamespace,
+    fromCache: false,
+  };
+  terrainElevationCache.set(cacheKey, sample);
+  const timing = ms !== undefined ? ` (${ms.toFixed(0)}ms)` : '';
+  console.debug(
+    `[TerrainElevation] via ${source}: ${height.toFixed(2)}m`
+    + ` (${sample.reference}) at ${cacheKey}${timing}`,
+  );
+  return sample;
+}
+
+function getTerrainSourceCandidates(
+  preferOrthometric: boolean,
+): Array<{
+  source: TerrainElevationSource;
+  resolve: (
+    Cesium: typeof import('cesium'),
+    viewer: InstanceType<typeof import('cesium').Viewer>,
+    position: InstanceType<typeof import('cesium').Cartographic>,
+    lat: number,
+    lon: number,
+  ) => Promise<{ height: number | undefined | null; elapsedMs?: number; skipped?: boolean }>;
+}> {
+  const candidates = [
+    {
+      source: 'scene.sampleHeight' as const,
+      resolve: async (
+        _Cesium: typeof import('cesium'),
+        viewer: InstanceType<typeof import('cesium').Viewer>,
+        position: InstanceType<typeof import('cesium').Cartographic>,
+      ) => {
+        if (!viewer.scene.sampleHeightSupported) return { height: null, skipped: true };
+        return { height: viewer.scene.sampleHeight(position) };
+      },
+    },
+    {
+      source: 'scene.sampleHeightMostDetailed' as const,
+      resolve: async (
+        _Cesium: typeof import('cesium'),
+        viewer: InstanceType<typeof import('cesium').Viewer>,
+        position: InstanceType<typeof import('cesium').Cartographic>,
+      ) => {
+        if (!viewer.scene.sampleHeightSupported) return { height: null, skipped: true };
+
+        let timeoutId: ReturnType<typeof setTimeout> | undefined;
+        try {
+          const t0 = performance.now();
+          const detailed = viewer.scene.sampleHeightMostDetailed([position]);
+          const timeout = new Promise<null>((resolve) => {
+            timeoutId = setTimeout(() => resolve(null), SAMPLE_DETAILED_TIMEOUT_MS);
+          });
+          const winner = await Promise.race([detailed, timeout]);
+          const elapsedMs = performance.now() - t0;
+          if (winner === null) {
+            console.debug(
+              `[TerrainElevation] sampleHeightMostDetailed timed out after ${elapsedMs.toFixed(0)}ms`,
+            );
+            return { height: null, elapsedMs, skipped: true };
+          }
+
+          const r0 = winner[0] as { height?: number } | undefined;
+          return { height: r0?.height, elapsedMs };
+        } finally {
+          if (timeoutId !== undefined) clearTimeout(timeoutId);
+        }
+      },
+    },
+    {
+      source: 'globe.getHeight' as const,
+      resolve: async (
+        _Cesium: typeof import('cesium'),
+        viewer: InstanceType<typeof import('cesium').Viewer>,
+        position: InstanceType<typeof import('cesium').Cartographic>,
+      ) => {
+        const h = viewer.scene.globe.getHeight(position);
+        if (h !== undefined && Math.abs(h) <= 1e-3) {
+          return { height: null, skipped: true };
+        }
+        return { height: h };
+      },
+    },
+    {
+      source: 'open-meteo' as const,
+      resolve: async (
+        _Cesium: typeof import('cesium'),
+        _viewer: InstanceType<typeof import('cesium').Viewer>,
+        _position: InstanceType<typeof import('cesium').Cartographic>,
+        lat: number,
+        lon: number,
+      ) => {
+        const t0 = performance.now();
+        const elev = await queryTerrainElevation({ lat, lon });
+        return { height: elev, elapsedMs: performance.now() - t0 };
+      },
+    },
+  ];
+
+  if (!preferOrthometric) return candidates;
+  return [
+    candidates[3],
+    candidates[2],
+    candidates[0],
+    candidates[1],
+  ];
+}
+
+export async function resolveTerrainElevationDetailed(
   Cesium: typeof import('cesium'),
   viewer: InstanceType<typeof import('cesium').Viewer>,
   lat: number,
   lon: number,
-): Promise<number | null> {
-  const cacheKey = terrainCacheKey(lat, lon);
+  options: ResolveTerrainElevationOptions = {},
+): Promise<TerrainElevationSample | null> {
+  const cacheNamespace = options.cacheNamespace ?? 'default';
+  const preferOrthometric = options.preferOrthometric ?? false;
+  const cacheKey = terrainCacheKey(lat, lon, cacheNamespace);
   const cached = terrainElevationCache.get(cacheKey);
   if (cached !== undefined) {
-    console.debug(`[TerrainElevation] cached at ${cacheKey}: ${cached.toFixed(2)}m`);
-    return cached;
+    console.debug(
+      `[TerrainElevation] cached at ${cacheKey}: ${cached.height.toFixed(2)}m`
+      + ` via ${cached.source} (${cached.reference})`,
+    );
+    return { ...cached, fromCache: true };
   }
 
   const position = Cesium.Cartographic.fromDegrees(lon, lat);
-  const accept = (h: number, source: string, ms?: number): number => {
-    terrainElevationCache.set(cacheKey, h);
-    const t = ms !== undefined ? ` (${ms.toFixed(0)}ms)` : '';
-    console.debug(`[TerrainElevation] via ${source}: ${h.toFixed(2)}m at ${cacheKey}${t}`);
-    return h;
-  };
   const skip = (h: unknown, source: string) => {
     console.debug(`[TerrainElevation] ${source} returned implausible value ${h}; skipping`);
   };
 
-  // 1. Sync globe.getHeight. The default ellipsoid provider returns 0 for
-  //    every lat/lon, so when no real terrain provider is wired we'd lock
-  //    in 0 and never reach the network fallbacks. Treat exact-zero from
-  //    this source specifically as "no data" — Open-Meteo can still return
-  //    a true 0 elsewhere in the chain for legitimate sea-level sites.
-  try {
-    const h = viewer.scene.globe.getHeight(position);
-    if (h !== undefined && isPlausibleElevation(h) && Math.abs(h) > 1e-3) {
-      return accept(h, 'globe.getHeight');
-    }
-    if (h !== undefined && !isPlausibleElevation(h)) skip(h, 'globe.getHeight');
-  } catch (err) {
-    console.warn('[TerrainElevation] globe.getHeight threw:', err);
-  }
-
-  // 2. Sync scene.sampleHeight — works with 3D Tiles when tiles for this
-  //    location are already rendered.
-  if (viewer.scene.sampleHeightSupported) {
+  for (const candidate of getTerrainSourceCandidates(preferOrthometric)) {
     try {
-      const h = viewer.scene.sampleHeight(position);
-      if (h !== undefined && isPlausibleElevation(h)) {
-        return accept(h, 'scene.sampleHeight');
+      const { height, elapsedMs, skipped } = await candidate.resolve(
+        Cesium, viewer, position, lat, lon,
+      );
+      if (height !== undefined && height !== null && isPlausibleElevation(height)) {
+        return acceptTerrainElevation(
+          cacheKey,
+          height,
+          candidate.source,
+          cacheNamespace,
+          elapsedMs,
+        );
       }
-      if (h !== undefined) skip(h, 'scene.sampleHeight');
-    } catch (err) {
-      console.warn('[TerrainElevation] scene.sampleHeight threw:', err);
-    }
-  }
-
-  // 3. Force-load the 3D-Tile tile at this location and sample the
-  //    rendered surface. This is what Google Photorealistic 3D Tiles
-  //    show on screen, so the model lands on the SAME surface the user
-  //    sees — no "below the visible ground" mismatch with Open-Meteo's
-  //    DEM. Bounded by a timeout so a slow tile fetch doesn't keep the
-  //    bridge waiting forever; Open-Meteo runs after as a backstop.
-  if (viewer.scene.sampleHeightSupported) {
-    let timeoutId: ReturnType<typeof setTimeout> | undefined;
-    try {
-      const t0 = performance.now();
-      const detailed = viewer.scene.sampleHeightMostDetailed([position]);
-      const timeout = new Promise<null>((resolve) => {
-        timeoutId = setTimeout(() => resolve(null), SAMPLE_DETAILED_TIMEOUT_MS);
-      });
-      const winner = await Promise.race([detailed, timeout]);
-      const ms = performance.now() - t0;
-      if (winner !== null) {
-        const r0 = winner[0] as { height?: number } | undefined;
-        if (r0?.height !== undefined && isPlausibleElevation(r0.height)) {
-          return accept(r0.height, 'scene.sampleHeightMostDetailed', ms);
-        }
-        if (r0?.height !== undefined) skip(r0.height, 'scene.sampleHeightMostDetailed');
-      } else {
-        console.debug(`[TerrainElevation] sampleHeightMostDetailed timed out after ${ms.toFixed(0)}ms`);
+      if (height !== undefined && height !== null) {
+        skip(height, candidate.source);
+      } else if (!skipped) {
+        console.debug(`[TerrainElevation] ${candidate.source} returned no value`);
       }
     } catch (err) {
-      console.warn('[TerrainElevation] sampleHeightMostDetailed threw:', err);
-    } finally {
-      // Cancel the timeout if the detailed sample resolved first, so the
-      // timer doesn't dangle and resolve to null after we've moved on.
-      if (timeoutId !== undefined) clearTimeout(timeoutId);
+      console.warn(`[TerrainElevation] ${candidate.source} threw:`, err);
     }
   }
 
-  // 4. Open-Meteo bare-earth elevation. Used as a network fallback when
-  //    the visible-tile sample didn't resolve in time.
-  try {
-    const t0 = performance.now();
-    const elev = await queryTerrainElevation({ lat, lon });
-    const ms = performance.now() - t0;
-    if (elev !== null && isPlausibleElevation(elev)) {
-      return accept(elev, 'Open-Meteo', ms);
-    }
-    if (elev !== null) skip(elev, 'Open-Meteo');
-  } catch (err) {
-    console.warn('[TerrainElevation] Open-Meteo threw:', err);
-  }
-
   console.warn(`[TerrainElevation] no source returned a plausible value at ${cacheKey}`);
   return null;
 }
+
+export async function resolveTerrainElevation(
+  Cesium: typeof import('cesium'),
+  viewer: InstanceType<typeof import('cesium').Viewer>,
+  lat: number,
+  lon: number,
+  options: ResolveTerrainElevationOptions = {},
+): Promise<number | null> {
+  const result = await resolveTerrainElevationDetailed(Cesium, viewer, lat, lon, options);
+  return result?.height ?? null;
+}

package/src/lib/lens/adapter.ts

@@ -14,6 +14,8 @@ import type { LensDataProvider, PropertySetInfo, ClassificationInfo } from '@ifc
 import type { IfcDataStore } from '@ifc-lite/parser';
 import {
   extractEntityAttributesOnDemand,
+  extractPropertiesOnDemand,
+  extractTypePropertiesOnDemand,
   extractQuantitiesOnDemand,
   extractClassificationsOnDemand,
   extractMaterialsOnDemand,
@@ -105,17 +107,61 @@ export function createLensDataProvider(
     ): unknown {
       const resolved = resolveGlobalId(globalId, entries);
       if (!resolved) return undefined;
-      return resolved.entry.ifcDataStore.properties?.getPropertyValue?.(
-        resolved.expressId,
-        propertySetName,
-        propertyName,
-      );
+      const store = resolved.entry.ifcDataStore;
+      const id = resolved.expressId;
+
+      // On-demand extraction path: pre-built table is empty for client-parsed
+      // stores, so iterate the same psets we expose via getPropertySets.
+      if (store.onDemandPropertyMap && store.source?.length > 0) {
+        const instancePsets = extractPropertiesOnDemand(store, id);
+        for (const pset of instancePsets) {
+          if (pset.name !== propertySetName) continue;
+          for (const prop of pset.properties) {
+            if (prop.name === propertyName) return prop.value;
+          }
+        }
+        // Fall through to type-inherited psets (Pset_*Common is typically
+        // attached to IfcSpaceType / IfcWallType, not the instance).
+        const typeProps = extractTypePropertiesOnDemand(store, id);
+        if (typeProps) {
+          for (const pset of typeProps.properties) {
+            if (pset.name !== propertySetName) continue;
+            for (const prop of pset.properties) {
+              if (prop.name === propertyName) return prop.value;
+            }
+          }
+        }
+        return undefined;
+      }
+
+      return store.properties?.getPropertyValue?.(id, propertySetName, propertyName);
     },
 
     getPropertySets(globalId: number): PropertySetInfo[] {
       const resolved = resolveGlobalId(globalId, entries);
       if (!resolved) return [];
-      const psets = resolved.entry.ifcDataStore.properties?.getForEntity?.(resolved.expressId);
+      const store = resolved.entry.ifcDataStore;
+      const id = resolved.expressId;
+
+      // Properties are extracted lazily — the pre-built table is empty unless
+      // server-parsed. Mirror the quantity path and use the on-demand extractor,
+      // which itself falls back to the eager table when no on-demand map exists.
+      if (store.onDemandPropertyMap && store.source?.length > 0) {
+        const instancePsets = extractPropertiesOnDemand(store, id) as PropertySetInfo[];
+        // Merge type-inherited psets (Pset_*Common lives on the type entity
+        // for occurrences). Instance psets take precedence on name conflict.
+        const typeProps = extractTypePropertiesOnDemand(store, id);
+        if (!typeProps || typeProps.properties.length === 0) return instancePsets;
+
+        const seen = new Set(instancePsets.map((p) => p.name));
+        const merged = instancePsets.slice();
+        for (const pset of typeProps.properties) {
+          if (!seen.has(pset.name)) merged.push(pset as PropertySetInfo);
+        }
+        return merged;
+      }
+
+      const psets = store.properties?.getForEntity?.(id);
       if (!psets) return [];
       return psets as PropertySetInfo[];
     },

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