@ifc-lite/viewer 1.8.0 → 1.10.0

package/src/lib/scripts/templates/reset-view.ts

@@ -0,0 +1,6 @@
+export {} // module boundary (stripped by transpiler)
+
+// Reset colors and visibility
+bim.viewer.resetColors()
+bim.viewer.resetVisibility()
+console.log('View reset — all colors and visibility restored')

package/src/lib/scripts/templates/space-validation.ts

@@ -0,0 +1,189 @@
+export {} // module boundary (stripped by transpiler)
+
+// ── Space & Room Validation ─────────────────────────────────────────────
+// Stakeholder: Facility Manager / Architect
+//
+// Validates IfcSpace entities for operations handover readiness. Checks
+// that every space has a Name, LongName, area and volume quantities,
+// and required properties. Generates a room schedule with measurements
+// and flags incomplete spaces. This would take hours of clicking through
+// individual spaces in the property panel.
+// ─────────────────────────────────────────────────────────────────────────
+
+bim.viewer.resetColors()
+bim.viewer.resetVisibility()
+
+const spaces = bim.query.byType('IfcSpace')
+
+if (spaces.length === 0) {
+  console.warn('No IfcSpace entities found in this model.')
+  console.log('')
+  console.log('This script validates room/space data. Models without')
+  console.log('IfcSpace entities are missing spatial programming data.')
+  console.log('')
+  // Show what spatial types exist
+  const spatialTypes = bim.query.byType('IfcBuildingStorey', 'IfcBuilding', 'IfcSite')
+  if (spatialTypes.length > 0) {
+    console.log('Spatial structure found:')
+    for (const e of spatialTypes) {
+      console.log('  ' + e.Type + ': ' + (e.Name || '<unnamed>'))
+    }
+  }
+  throw new Error('no spaces')
+}
+
+// ── 1. Extract space data ───────────────────────────────────────────────
+interface SpaceData {
+  entity: BimEntity
+  area: number | null
+  volume: number | null
+  perimeter: number | null
+  height: number | null
+  longName: string | null
+  category: string | null
+  occupancy: string | null
+  issues: string[]
+}
+
+const spaceData: SpaceData[] = []
+// Collect property/quantity paths for CSV export
+const spacePropPaths = new Set<string>()
+const spaceQtyPaths = new Set<string>()
+
+for (const space of spaces) {
+  const data: SpaceData = {
+    entity: space, area: null, volume: null, perimeter: null, height: null,
+    longName: null, category: null, occupancy: null, issues: []
+  }
+
+  // Extract quantities
+  const qsets = bim.query.quantities(space)
+  for (const qset of qsets) {
+    for (const q of qset.quantities) {
+      const lower = q.name.toLowerCase()
+      if (lower.includes('area') && !lower.includes('wall') && data.area === null) data.area = q.value
+      if (lower.includes('volume') && data.volume === null) data.volume = q.value
+      if (lower.includes('perimeter') && data.perimeter === null) data.perimeter = q.value
+      if (lower.includes('height') && data.height === null) data.height = q.value
+      if (q.value !== null && q.value !== 0) spaceQtyPaths.add(qset.name + '.' + q.name)
+    }
+  }
+
+  // Extract properties
+  const psets = bim.query.properties(space)
+  for (const pset of psets) {
+    for (const p of pset.properties) {
+      const lower = p.name.toLowerCase()
+      if (lower === 'longname' && p.value) data.longName = String(p.value)
+      if (lower === 'category' && p.value) data.category = String(p.value)
+      if (lower === 'occupancytype' && p.value) data.occupancy = String(p.value)
+      if (p.value !== null && p.value !== '') spacePropPaths.add(pset.name + '.' + p.name)
+    }
+  }
+
+  // Also check entity attributes
+  if (!data.longName && space.Description) data.longName = space.Description
+
+  // Check for issues
+  if (!space.Name || space.Name === '') data.issues.push('Missing Name')
+  if (!data.longName) data.issues.push('Missing LongName/Description')
+  if (data.area === null) data.issues.push('Missing Area')
+  if (data.volume === null) data.issues.push('Missing Volume')
+
+  spaceData.push(data)
+}
+
+// ── 2. Classify spaces ─────────────────────────────────────────────────
+const complete = spaceData.filter(s => s.issues.length === 0)
+const incomplete = spaceData.filter(s => s.issues.length > 0)
+
+// ── 3. Color-code ───────────────────────────────────────────────────────
+const batches: Array<{ entities: BimEntity[]; color: string }> = []
+if (complete.length > 0) batches.push({ entities: complete.map(s => s.entity), color: '#27ae60' })
+const minor = incomplete.filter(s => s.issues.length <= 2)
+const major = incomplete.filter(s => s.issues.length > 2)
+if (minor.length > 0) batches.push({ entities: minor.map(s => s.entity), color: '#f39c12' })
+if (major.length > 0) batches.push({ entities: major.map(s => s.entity), color: '#e74c3c' })
+if (batches.length > 0) bim.viewer.colorizeAll(batches)
+
+// ── 4. Report ───────────────────────────────────────────────────────────
+console.log('═══════════════════════════════════════')
+console.log('  SPACE & ROOM VALIDATION')
+console.log('═══════════════════════════════════════')
+console.log('')
+console.log('Spaces found: ' + spaces.length)
+console.log('  Complete:     ' + complete.length + '  ● green')
+console.log('  Minor issues: ' + minor.length + '  ● orange (1-2 issues)')
+console.log('  Major issues: ' + major.length + '  ● red (3+ issues)')
+
+// ── 5. Room schedule ────────────────────────────────────────────────────
+console.log('')
+console.log('── Room Schedule ──')
+console.log('Name                    | Area m²  | Volume m³ | Height m | Status')
+console.log('------------------------+----------+-----------+----------+-------')
+
+// Sort by name
+const sorted = [...spaceData].sort((a, b) => {
+  const nameA = a.entity.Name || 'zzz'
+  const nameB = b.entity.Name || 'zzz'
+  return nameA.localeCompare(nameB)
+})
+
+let totalArea = 0
+let totalVolume = 0
+
+for (const s of sorted) {
+  const name = ((s.entity.Name || '<unnamed>') + '                        ').slice(0, 24)
+  const area = s.area !== null ? (s.area.toFixed(1) + '    ').slice(0, 8) : '-       '
+  const vol = s.volume !== null ? (s.volume.toFixed(1) + '     ').slice(0, 9) : '-        '
+  const height = s.height !== null ? (s.height.toFixed(2) + '   ').slice(0, 8) : '-       '
+  const status = s.issues.length === 0 ? 'OK' : s.issues.length + ' issues'
+  console.log(name + '| ' + area + ' | ' + vol + ' | ' + height + ' | ' + status)
+  if (s.area !== null) totalArea += s.area
+  if (s.volume !== null) totalVolume += s.volume
+}
+
+console.log('------------------------+----------+-----------+----------+-------')
+console.log('TOTALS                  | ' + (totalArea.toFixed(1) + '    ').slice(0, 8) + ' | ' + (totalVolume.toFixed(1) + '     ').slice(0, 9) + ' |')
+
+// ── 6. Category breakdown ───────────────────────────────────────────────
+const categories: Record<string, { count: number; area: number }> = {}
+for (const s of spaceData) {
+  const cat = s.category || s.entity.ObjectType || 'Uncategorized'
+  if (!categories[cat]) categories[cat] = { count: 0, area: 0 }
+  categories[cat].count++
+  if (s.area !== null) categories[cat].area += s.area
+}
+
+if (Object.keys(categories).length > 1) {
+  console.log('')
+  console.log('── By Category ──')
+  for (const [cat, data] of Object.entries(categories).sort((a, b) => b[1].area - a[1].area)) {
+    console.log('  ' + cat + ': ' + data.count + ' spaces, ' + data.area.toFixed(1) + ' m²')
+  }
+}
+
+// ── 7. Issue details ────────────────────────────────────────────────────
+if (incomplete.length > 0) {
+  console.log('')
+  console.warn('── Incomplete Spaces ──')
+  const issueCount: Record<string, number> = {}
+  for (const s of incomplete) {
+    for (const issue of s.issues) {
+      issueCount[issue] = (issueCount[issue] || 0) + 1
+    }
+  }
+  for (const [issue, count] of Object.entries(issueCount).sort((a, b) => b[1] - a[1])) {
+    console.warn('  ' + issue + ': ' + count + ' spaces')
+  }
+}
+
+// ── 8. Export ────────────────────────────────────────────────────────────
+const spPropCols = Array.from(spacePropPaths).sort().slice(0, 15)
+const spQtyCols = Array.from(spaceQtyPaths).sort().slice(0, 15)
+bim.export.csv(spaces, {
+  columns: ['Name', 'Type', 'GlobalId', 'Description', 'ObjectType', ...spPropCols, ...spQtyCols],
+  filename: 'room-schedule.csv'
+})
+console.log('')
+console.log('Exported ' + spaces.length + ' spaces (' + (5 + spPropCols.length + spQtyCols.length) + ' columns) to room-schedule.csv')

package/src/lib/scripts/templates/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022"],
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true
+  },
+  "include": ["bim-globals.d.ts", "*.ts"],
+  "exclude": ["tsconfig.json"]
+}

package/src/lib/scripts/templates.ts

@@ -0,0 +1,86 @@
+/* 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/. */
+
+/**
+ * Built-in script templates for the script editor.
+ *
+ * Templates are real .ts files in ./templates/ that are type-checked
+ * against the bim-globals.d.ts declaration. They are loaded as raw
+ * strings via Vite's ?raw import and served to the sandbox transpiler.
+ *
+ * Each template targets a specific stakeholder and combines multiple
+ * API calls into automated workflows that go beyond what the UI can
+ * do through manual clicking.
+ */
+
+// Raw source imports — Vite returns the file content as a string
+import dataQualityAudit from './templates/data-quality-audit.ts?raw';
+import fireSafetyCheck from './templates/fire-safety-check.ts?raw';
+import quantityTakeoff from './templates/quantity-takeoff.ts?raw';
+import envelopeCheck from './templates/envelope-check.ts?raw';
+import mepEquipmentSchedule from './templates/mep-equipment-schedule.ts?raw';
+import spaceValidation from './templates/space-validation.ts?raw';
+import federationCompare from './templates/federation-compare.ts?raw';
+import resetView from './templates/reset-view.ts?raw';
+
+export interface ScriptTemplate {
+  name: string;
+  description: string;
+  code: string;
+}
+
+/** Strip the `export {}` module boundary line that enables type checking */
+function stripModuleLine(raw: string): string {
+  return raw.replace(/^export \{\}[^\n]*\n\n?/, '');
+}
+
+export const SCRIPT_TEMPLATES: ScriptTemplate[] = [
+  {
+    name: 'Data quality audit',
+    description:
+      'BIM Manager — scan all entities for missing names, properties, and quantities; score model completeness; color-code by data quality',
+    code: stripModuleLine(dataQualityAudit),
+  },
+  {
+    name: 'Fire safety compliance',
+    description:
+      'Architect — check fire ratings across walls, doors, and slabs; flag load-bearing elements without ratings; export non-compliant list',
+    code: stripModuleLine(fireSafetyCheck),
+  },
+  {
+    name: 'Quantity takeoff',
+    description:
+      'Cost Estimator — aggregate area, volume, and length quantities across all element types; generate material takeoff table and CSV',
+    code: stripModuleLine(quantityTakeoff),
+  },
+  {
+    name: 'Envelope & thermal check',
+    description:
+      'Energy Consultant — identify external elements, check thermal transmittance values, isolate building envelope, flag missing data',
+    code: stripModuleLine(envelopeCheck),
+  },
+  {
+    name: 'MEP equipment schedule',
+    description:
+      'HVAC Engineer — discover all distribution elements, extract equipment properties, generate schedule, isolate and color by system',
+    code: stripModuleLine(mepEquipmentSchedule),
+  },
+  {
+    name: 'Space & room validation',
+    description:
+      'Facility Manager — validate IfcSpace entities for area, volume, naming; generate room schedule with totals; flag incomplete spaces',
+    code: stripModuleLine(spaceValidation),
+  },
+  {
+    name: 'Federation comparison',
+    description:
+      'Project Manager — compare multiple loaded models side by side: entity counts, type coverage, naming consistency, coordination issues',
+    code: stripModuleLine(federationCompare),
+  },
+  {
+    name: 'Reset view',
+    description: 'Utility — remove all color overrides and show all entities',
+    code: stripModuleLine(resetView),
+  },
+];

package/src/sdk/BimProvider.tsx

@@ -0,0 +1,50 @@
+/* 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/. */
+
+/**
+ * BimProvider — React context for the SDK's BimContext.
+ *
+ * Wraps useBimHost() and makes the `bim` object available to all children
+ * via useBim(). This enables gradual migration: components can progressively
+ * switch from direct Zustand store calls to SDK calls.
+ *
+ * Usage:
+ *   <BimProvider>
+ *     <App />
+ *   </BimProvider>
+ *
+ *   // In any component:
+ *   const bim = useBim();
+ *   const walls = bim.query().byType('IfcWall').toArray();
+ */
+
+import { createContext, useContext, type ReactNode } from 'react';
+import type { BimContext } from '@ifc-lite/sdk';
+import { useBimHost } from './useBimHost.js';
+
+const BimReactContext = createContext<BimContext | null>(null);
+
+/** Provider that initializes the SDK and makes it available via useBim() */
+export function BimProvider({ children }: { children: ReactNode }) {
+  const bim = useBimHost();
+  return (
+    <BimReactContext.Provider value={bim}>
+      {children}
+    </BimReactContext.Provider>
+  );
+}
+
+/**
+ * Access the BimContext from any component.
+ * Must be rendered inside a <BimProvider>.
+ *
+ * @throws if used outside a BimProvider
+ */
+export function useBim(): BimContext {
+  const ctx = useContext(BimReactContext);
+  if (!ctx) {
+    throw new Error('useBim() must be used within a <BimProvider>');
+  }
+  return ctx;
+}

package/src/sdk/adapters/export-adapter.ts

@@ -0,0 +1,283 @@
+/* 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 type { StoreApi } from './types.js';
+import type { EntityRef, EntityData, PropertySetData, QuantitySetData, ExportBackendMethods } from '@ifc-lite/sdk';
+import { EntityNode } from '@ifc-lite/query';
+import { getModelForRef } from './model-compat.js';
+
+/** Options for CSV export */
+interface CsvOptions {
+  columns: string[];
+  separator?: string;
+  filename?: string;
+}
+
+/**
+ * Validate that a value is a CsvOptions object.
+ */
+function isCsvOptions(v: unknown): v is CsvOptions {
+  if (v === null || typeof v !== 'object' || !('columns' in v)) return false;
+  const columns = (v as CsvOptions).columns;
+  if (!Array.isArray(columns)) return false;
+  // Validate all column entries are strings
+  return columns.every((c): c is string => typeof c === 'string');
+}
+
+/**
+ * Validate that a value is an array of EntityRef objects.
+ */
+function isEntityRefArray(v: unknown): v is EntityRef[] {
+  if (!Array.isArray(v)) return false;
+  if (v.length === 0) return true;
+  const first = v[0] as Record<string, unknown>;
+  // Accept both raw EntityRef and entity proxy objects with .ref
+  if ('modelId' in first && 'expressId' in first) {
+    return typeof first.modelId === 'string' && typeof first.expressId === 'number';
+  }
+  if ('ref' in first && first.ref !== null && typeof first.ref === 'object') {
+    const ref = first.ref as Record<string, unknown>;
+    return typeof ref.modelId === 'string' && typeof ref.expressId === 'number';
+  }
+  return false;
+}
+
+/**
+ * Normalize entity refs — entities from the sandbox may be EntityData
+ * objects with a .ref property, or raw EntityRef { modelId, expressId }.
+ */
+function normalizeRefs(raw: unknown[]): EntityRef[] {
+  return raw.map((item) => {
+    const r = item as Record<string, unknown>;
+    if (r.ref && typeof r.ref === 'object') {
+      return r.ref as EntityRef;
+    }
+    return { modelId: r.modelId as string, expressId: r.expressId as number };
+  });
+}
+
+/**
+ * Escape a CSV cell value — wrap in quotes if it contains the separator,
+ * double-quotes, or newlines.
+ */
+function escapeCsv(value: string, sep: string): string {
+  if (value.includes(sep) || value.includes('"') || value.includes('\n')) {
+    return `"${value.replace(/"/g, '""')}"`;
+  }
+  return value;
+}
+
+/**
+ * Export adapter — implements CSV and JSON export directly.
+ *
+ * This adapter resolves entity data by dispatching to the query adapter
+ * on the same LocalBackend, providing full export support for both
+ * direct dispatch calls and SDK namespace usage.
+ */
+export function createExportAdapter(store: StoreApi): ExportBackendMethods {
+  /** Resolve entity data via the query subsystem */
+  function getEntityData(ref: EntityRef): EntityData | null {
+    const state = store.getState();
+    const model = getModelForRef(state, ref.modelId);
+    if (!model?.ifcDataStore) return null;
+
+    const node = new EntityNode(model.ifcDataStore, ref.expressId);
+    return {
+      ref,
+      globalId: node.globalId,
+      name: node.name,
+      type: node.type,
+      description: node.description,
+      objectType: node.objectType,
+    };
+  }
+
+  /** Resolve property sets for an entity */
+  function getProperties(ref: EntityRef): PropertySetData[] {
+    const state = store.getState();
+    const model = getModelForRef(state, ref.modelId);
+    if (!model?.ifcDataStore) return [];
+
+    const node = new EntityNode(model.ifcDataStore, ref.expressId);
+    return node.properties().map((pset: { name: string; globalId?: string; properties: Array<{ name: string; type: number; value: string | number | boolean | null }> }) => ({
+      name: pset.name,
+      globalId: pset.globalId,
+      properties: pset.properties.map((p: { name: string; type: number; value: string | number | boolean | null }) => ({
+        name: p.name,
+        type: p.type,
+        value: p.value,
+      })),
+    }));
+  }
+
+  /** Resolve quantity sets for an entity */
+  function getQuantities(ref: EntityRef): QuantitySetData[] {
+    const state = store.getState();
+    const model = getModelForRef(state, ref.modelId);
+    if (!model?.ifcDataStore) return [];
+
+    const node = new EntityNode(model.ifcDataStore, ref.expressId);
+    return node.quantities().map((qset: { name: string; quantities: Array<{ name: string; type: number; value: number }> }) => ({
+      name: qset.name,
+      quantities: qset.quantities.map((q: { name: string; type: number; value: number }) => ({
+        name: q.name,
+        type: q.type,
+        value: q.value,
+      })),
+    }));
+  }
+
+  /** Resolve a single column value from entity data + properties + quantities.
+   * Accepts both IFC PascalCase (Name, GlobalId) and legacy camelCase (name, globalId).
+   * Dot-path columns (e.g. "Pset_WallCommon.FireRating" or "Qto_WallBaseQuantities.GrossVolume")
+   * resolve against property sets first, then quantity sets. */
+  function resolveColumnValue(
+    data: EntityData,
+    col: string,
+    getProps: () => PropertySetData[],
+    getQties: () => QuantitySetData[],
+  ): string {
+    // IFC schema attribute names (PascalCase) + legacy camelCase
+    switch (col) {
+      case 'Name': case 'name': return data.name;
+      case 'Type': case 'type': return data.type;
+      case 'GlobalId': case 'globalId': return data.globalId;
+      case 'Description': case 'description': return data.description;
+      case 'ObjectType': case 'objectType': return data.objectType;
+      case 'modelId': return data.ref.modelId;
+      case 'expressId': return String(data.ref.expressId);
+    }
+
+    // Property/Quantity path: "SetName.ValueName"
+    const dotIdx = col.indexOf('.');
+    if (dotIdx > 0) {
+      const setName = col.slice(0, dotIdx);
+      const valueName = col.slice(dotIdx + 1);
+
+      // Try property sets first
+      const psets = getProps();
+      const pset = psets.find(p => p.name === setName);
+      if (pset) {
+        const prop = pset.properties.find(p => p.name === valueName);
+        if (prop?.value != null) return String(prop.value);
+      }
+
+      // Fall back to quantity sets
+      const qsets = getQties();
+      const qset = qsets.find(q => q.name === setName);
+      if (qset) {
+        const qty = qset.quantities.find(q => q.name === valueName);
+        if (qty?.value != null) return String(qty.value);
+      }
+
+      return '';
+    }
+
+    return '';
+  }
+
+  return {
+    csv(rawRefs: unknown, rawOptions: unknown) {
+      if (!isEntityRefArray(rawRefs)) {
+        throw new Error('export.csv: first argument must be an array of entity references');
+      }
+      if (!isCsvOptions(rawOptions)) {
+        throw new Error('export.csv: second argument must be { columns: string[], separator?: string }');
+      }
+
+      const refs = normalizeRefs(rawRefs);
+      const options = rawOptions;
+      const sep = options.separator ?? ',';
+      const rows: string[][] = [];
+
+      // Header row
+      rows.push(options.columns);
+
+      // Data rows
+      for (const ref of refs) {
+        const data = getEntityData(ref);
+        if (!data) continue;
+
+        // Lazy-load properties/quantities only if a column needs them
+        let cachedProps: PropertySetData[] | null = null;
+        const getProps = (): PropertySetData[] => {
+          if (!cachedProps) cachedProps = getProperties(ref);
+          return cachedProps;
+        };
+        let cachedQties: QuantitySetData[] | null = null;
+        const getQties = (): QuantitySetData[] => {
+          if (!cachedQties) cachedQties = getQuantities(ref);
+          return cachedQties;
+        };
+
+        const row = options.columns.map(col => resolveColumnValue(data, col, getProps, getQties));
+        rows.push(row);
+      }
+
+      const csvString = rows.map(r => r.map(cell => escapeCsv(cell, sep)).join(sep)).join('\n');
+
+      // If filename specified, trigger browser download
+      if (options.filename) {
+        triggerDownload(csvString, options.filename, 'text/csv;charset=utf-8;');
+      }
+
+      return csvString;
+    },
+
+    json(rawRefs: unknown, columns: unknown) {
+      if (!isEntityRefArray(rawRefs)) {
+        throw new Error('export.json: first argument must be an array of entity references');
+      }
+      if (!Array.isArray(columns)) {
+        throw new Error('export.json: second argument must be a string[] of column names');
+      }
+
+      const refs = normalizeRefs(rawRefs);
+      const result: Record<string, unknown>[] = [];
+
+      for (const ref of refs) {
+        const data = getEntityData(ref);
+        if (!data) continue;
+
+        let cachedProps: PropertySetData[] | null = null;
+        const getProps = (): PropertySetData[] => {
+          if (!cachedProps) cachedProps = getProperties(ref);
+          return cachedProps;
+        };
+        let cachedQties: QuantitySetData[] | null = null;
+        const getQties = (): QuantitySetData[] => {
+          if (!cachedQties) cachedQties = getQuantities(ref);
+          return cachedQties;
+        };
+
+        const row: Record<string, unknown> = {};
+        for (const col of columns as string[]) {
+          const value = resolveColumnValue(data, col, getProps, getQties);
+          // Try to parse numeric values
+          const numVal = Number(value);
+          row[col] = value === '' ? null : !isNaN(numVal) && value.trim() !== '' ? numVal : value;
+        }
+        result.push(row);
+      }
+
+      return result;
+    },
+
+    download(content: string, filename: string, mimeType?: string) {
+      triggerDownload(content, filename, mimeType ?? 'text/plain');
+      return undefined;
+    },
+  };
+}
+
+/** Trigger a browser file download */
+function triggerDownload(content: string, filename: string, mimeType: string): void {
+  const blob = new Blob([content], { type: mimeType });
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = filename;
+  a.click();
+  URL.revokeObjectURL(url);
+}

package/src/sdk/adapters/lens-adapter.ts

@@ -0,0 +1,44 @@
+/* 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 type { LensBackendMethods } from '@ifc-lite/sdk';
+import type { StoreApi } from './types.js';
+import { BUILTIN_LENSES } from '@ifc-lite/lens';
+
+/** Type guard for lens config object */
+function isLensConfig(v: unknown): v is Record<string, unknown> {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+export function createLensAdapter(store: StoreApi): LensBackendMethods {
+  return {
+    presets() {
+      return BUILTIN_LENSES;
+    },
+    create(config: unknown) {
+      if (!isLensConfig(config)) {
+        throw new Error('lens.create: argument must be a lens configuration object');
+      }
+      const id = crypto.randomUUID();
+      return { ...config, id };
+    },
+    activate(lensId: unknown) {
+      if (typeof lensId !== 'string') {
+        throw new Error('lens.activate: argument must be a lens ID string');
+      }
+      const state = store.getState();
+      state.setActiveLens?.(lensId);
+      return undefined;
+    },
+    deactivate() {
+      const state = store.getState();
+      state.setActiveLens?.(null);
+      return undefined;
+    },
+    getActive() {
+      const state = store.getState();
+      return state.activeLensId ?? null;
+    },
+  };
+}