feat(viewer): save and reopen a portable federation setup (#3945)

Closes #3930. Save which models make up a federation (load order,
visibility, alignment anchor) to a small, portable JSON file that
references source files by name/size/content-fingerprint rather than
embedding bytes or paths. Reopening matches saved slots to freshly
picked local files, replays alignment through the existing
realignFederation pipeline against the restored anchor, and always
reports restored/missing/mismatched counts instead of silently
accepting a partial restore. Reachable via the command palette
("Save Federation Setup" / "Open Federation Setup").

Claude-Session: https://claude.ai/code/session_01QPHChk3Ve9N519A4kY7436

Author: BIMvoice

.changeset/federation-setup-portable-save-reopen.md

@@ -0,0 +1,5 @@
+---
+"@ifc-lite/viewer": minor
+---
+
+Add a portable federation setup file: save which models make up a federation (load order, visibility, and the alignment anchor) and reopen it later by matching saved slots back to local files by content fingerprint. The file references source files by name, size, and a content fingerprint — it never embeds file bytes, paths, or handles. Reopening replays the existing alignment pipeline against the restored anchor rather than storing baked transforms, and always reports how many models were restored versus missing or mismatched instead of silently accepting a partial restore. Reachable via the command palette ("Save Federation Setup" / "Open Federation Setup").

apps/viewer/src/components/viewer/CommandPalette.tsx

@@ -287,6 +287,9 @@ export function CommandPalette({ open, onOpenChange }: CommandPaletteProps) {
         action: () => {
           window.dispatchEvent(new CustomEvent('ifc-lite:open-files'));
         } },
+      // #3930 portable federation setup — handlers live in `FederationSetupControls` (mounted from `useFileCommands`, ShareDialog's pattern).
+      { id: 'file:save-federation-setup', label: 'Save Federation Setup', keywords: 'federation setup save export portable models order alignment anchor', category: 'File', icon: Save, action: () => { window.dispatchEvent(new CustomEvent('ifc-lite:save-federation-setup')); } },
+      { id: 'file:open-federation-setup', label: 'Open Federation Setup', keywords: 'federation setup restore reopen import portable models order alignment anchor', category: 'File', icon: FolderOpen, immediate: true, action: () => { window.dispatchEvent(new CustomEvent('ifc-lite:open-federation-setup')); } },
     );
     for (const rf of recentFiles) {
       const fileName = rf.name;

apps/viewer/src/components/viewer/FederationSetupControls.tsx

@@ -0,0 +1,187 @@
+/* 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/. */
+
+/**
+ * Save/reopen a portable federation setup (#3930).
+ *
+ * Mounted once from `useFileCommands` (same pattern as `ShareDialog`), so it
+ * is reachable from the command palette regardless of which toolbar style is
+ * active. Two hidden `<input type="file">`s drive the two-step "open" flow
+ * (pick the saved `.federation.json`, then pick the local model files to
+ * match against it); the review step never applies anything silently — every
+ * slot is shown as matched, mismatched (same name, different content/size),
+ * or missing before the user confirms.
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { AlertTriangle, Anchor, Check, FileWarning } from 'lucide-react';
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from '@/components/ui/dialog';
+import { Button } from '@/components/ui/button';
+import { toast } from '@/components/ui/toast';
+import { useFederationSetup } from '@/hooks/useFederationSetup';
+import {
+  parseFederationSetupFile,
+  type FederationSetupFile,
+  type FederationSetupSlotMatch,
+} from '@/lib/federation/federationSetupFile';
+
+const EVENT_SAVE = 'ifc-lite:save-federation-setup';
+const EVENT_OPEN = 'ifc-lite:open-federation-setup';
+
+function confidenceBadge(match: FederationSetupSlotMatch): { label: string; icon: typeof Check; tone: string } {
+  switch (match.confidence) {
+    case 'content':
+      return { label: 'Matched', icon: Check, tone: 'text-emerald-600 dark:text-emerald-400' };
+    case 'name-size':
+      return { label: 'Matched (by name)', icon: Check, tone: 'text-emerald-600 dark:text-emerald-400' };
+    case 'name-only':
+      return { label: 'Same name, different file', icon: FileWarning, tone: 'text-amber-600 dark:text-amber-400' };
+    case 'none':
+      return { label: 'Missing', icon: AlertTriangle, tone: 'text-red-600 dark:text-red-400' };
+  }
+}
+
+export function FederationSetupControls() {
+  const { exportFederationSetup, matchFederationSetup, applyFederationSetup } = useFederationSetup();
+
+  const setupFileInputRef = useRef<HTMLInputElement>(null);
+  const modelFilesInputRef = useRef<HTMLInputElement>(null);
+  const [pendingSetup, setPendingSetup] = useState<FederationSetupFile | null>(null);
+  const [matches, setMatches] = useState<FederationSetupSlotMatch[] | null>(null);
+  const [applying, setApplying] = useState(false);
+
+  const handleSave = useCallback(() => {
+    void exportFederationSetup().then((result) => {
+      if (!result.ok) toast.error(result.error);
+      else toast.success('Federation setup saved.');
+    });
+  }, [exportFederationSetup]);
+
+  useEffect(() => {
+    const onSave = () => handleSave();
+    const onOpen = () => setupFileInputRef.current?.click();
+    window.addEventListener(EVENT_SAVE, onSave);
+    window.addEventListener(EVENT_OPEN, onOpen);
+    return () => {
+      window.removeEventListener(EVENT_SAVE, onSave);
+      window.removeEventListener(EVENT_OPEN, onOpen);
+    };
+  }, [handleSave]);
+
+  const handleSetupFileSelected = useCallback((e: React.ChangeEvent<HTMLInputElement>) => {
+    const file = e.target.files?.[0];
+    e.target.value = '';
+    if (!file) return;
+    void file.text().then((text) => {
+      const result = parseFederationSetupFile(text);
+      if (!result.ok) {
+        toast.error(`Not a valid federation setup file: ${result.error}`);
+        return;
+      }
+      setPendingSetup(result.setup);
+      toast.info(
+        `Loaded a setup with ${result.setup.slots.length} model slot${result.setup.slots.length === 1 ? '' : 's'} — now pick the model file(s) to match against it.`,
+      );
+      modelFilesInputRef.current?.click();
+    });
+  }, []);
+
+  const handleModelFilesSelected = useCallback((e: React.ChangeEvent<HTMLInputElement>) => {
+    const files = Array.from(e.target.files ?? []);
+    e.target.value = '';
+    if (!pendingSetup || files.length === 0) return;
+    void matchFederationSetup(pendingSetup, files).then(setMatches);
+  }, [pendingSetup, matchFederationSetup]);
+
+  const closeReview = useCallback(() => {
+    setMatches(null);
+    setPendingSetup(null);
+  }, []);
+
+  const handleApply = useCallback(() => {
+    if (!matches) return;
+    setApplying(true);
+    void applyFederationSetup(matches).then((result) => {
+      setApplying(false);
+      closeReview();
+      if (result.outcome === 'failed') {
+        toast.error('Could not restore the federation setup — none of the saved models were found.');
+        return;
+      }
+      const parts: string[] = [`Restored ${result.restoredCount}/${result.totalSlots} model(s)`];
+      if (result.missingSlots.length > 0) parts.push(`missing: ${result.missingSlots.join(', ')}`);
+      if (result.mismatchedSlots.length > 0) parts.push(`same name, different content: ${result.mismatchedSlots.join(', ')}`);
+      if (result.anchorMissing) parts.push('alignment anchor could not be restored');
+      const message = parts.join(' — ');
+      if (result.outcome === 'restored' && !result.anchorMissing) toast.success(message);
+      else toast.error(message);
+    });
+  }, [matches, applyFederationSetup, closeReview]);
+
+  return (
+    <>
+      <input
+        ref={setupFileInputRef}
+        type="file"
+        accept=".json,application/json"
+        className="hidden"
+        onChange={handleSetupFileSelected}
+      />
+      <input
+        ref={modelFilesInputRef}
+        type="file"
+        multiple
+        className="hidden"
+        onChange={handleModelFilesSelected}
+      />
+      <Dialog open={matches !== null} onOpenChange={(open) => { if (!open) closeReview(); }}>
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>Reopen federation setup</DialogTitle>
+            <DialogDescription>
+              Review how each saved model slot matched your local files before restoring.
+            </DialogDescription>
+          </DialogHeader>
+          <div className="max-h-80 overflow-y-auto space-y-1">
+            {matches?.map((match) => {
+              const badge = confidenceBadge(match);
+              const Icon = badge.icon;
+              return (
+                <div
+                  key={match.slotIndex}
+                  className="flex items-center gap-2 px-2 py-1.5 border border-zinc-200 dark:border-zinc-800 rounded text-sm"
+                >
+                  {match.slot.anchor && <Anchor className="h-3.5 w-3.5 text-amber-600 dark:text-amber-400 shrink-0" />}
+                  <span className="truncate flex-1">{match.slot.name}</span>
+                  <span className={`inline-flex items-center gap-1 text-xs ${badge.tone}`}>
+                    <Icon className="h-3.5 w-3.5" />
+                    {badge.label}
+                  </span>
+                </div>
+              );
+            })}
+          </div>
+          <DialogFooter>
+            <Button variant="outline" onClick={closeReview} disabled={applying}>Cancel</Button>
+            <Button
+              onClick={handleApply}
+              disabled={applying || !matches?.some((m) => m.file !== null)}
+            >
+              {applying ? 'Restoring…' : 'Restore federation'}
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+    </>
+  );
+}
+
+export default FederationSetupControls;

apps/viewer/src/components/viewer/toolbar/useFileCommands.tsx

@@ -24,6 +24,7 @@ import { toast } from '@/components/ui/toast';
 import { isCollabEnabled } from '@/lib/collab/config';
 import { ingestDxfFiles, splitDxfFiles } from '@/hooks/ingest/dxfIngest';
 import { ShareDialog } from '../ShareDialog';
+import { FederationSetupControls } from '../FederationSetupControls';
 
 import { FILE_ACCEPT, isSupportedModelFile } from '@/services/supported-model-files';
 
@@ -374,6 +375,7 @@ export function useFileCommands(): FileCommands {
         className="hidden"
       />
       {collabEnabled && <ShareDialog open={shareDialogOpen} onOpenChange={setShareDialogOpen} />}
+      <FederationSetupControls />
     </>
   );
 

apps/viewer/src/hooks/useFederationSetup.ts

@@ -0,0 +1,138 @@
+/* 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/. */
+
+/**
+ * Save and reopen a portable federation setup (issue #3930).
+ *
+ * Thin glue between the pure logic in `lib/federation/federationSetupFile.ts`
+ * and the live viewer store / canonical load path (`useIfcFederation.addModel`,
+ * `realignFederation`). See that module's header for what the saved file
+ * references versus embeds, and how alignment is replayed rather than baked in.
+ */
+
+import { useCallback } from 'react';
+import { useShallow } from 'zustand/react/shallow';
+import { useViewerStore, type FederatedModel } from '../store/index.js';
+import { useIfc } from './useIfc.js';
+import { findReferenceGeorefModel } from './ingest/federationAlign.js';
+import {
+  buildFederationSetupFile,
+  serializeFederationSetupFile,
+  matchFederationSetupSlots,
+  summarizeFederationSetupMatches,
+  type FederationSetupFile,
+  type FederationSetupSlotMatch,
+} from '../lib/federation/federationSetupFile.js';
+import { downloadFile, sanitizeFilename } from '../lib/export/download.js';
+
+/** Result of applying a federation setup — always distinguishes full vs. partial vs. failed restore. */
+export interface FederationSetupApplyResult {
+  outcome: 'restored' | 'partial' | 'failed';
+  /** Models actually (re-)loaded, in the order they were loaded. */
+  restoredCount: number;
+  totalSlots: number;
+  /** Slots for which no local file could be found. */
+  missingSlots: string[];
+  /** Slots matched only by filename, with different size/content than saved. */
+  mismatchedSlots: string[];
+  /** True when the saved anchor's model was restored and re-alignment ran. */
+  anchorRestored: boolean;
+  /** True when the setup had a saved anchor but that model could not be restored. */
+  anchorMissing: boolean;
+}
+
+export function useFederationSetup() {
+  const { addModel, realignFederation } = useIfc();
+  const { anchorModelIdOverride, setAnchorModelIdOverride } = useViewerStore(
+    useShallow((s) => ({
+      anchorModelIdOverride: s.anchorModelIdOverride,
+      setAnchorModelIdOverride: s.setAnchorModelIdOverride,
+    })),
+  );
+
+  /** Build and download the current federation as a portable setup file. Read-only — never mutates the store. */
+  const exportFederationSetup = useCallback(async (): Promise<{ ok: true } | { ok: false; error: string }> => {
+    const state = useViewerStore.getState();
+    const models = Array.from(state.models.values()) as FederatedModel[]; // Map insertion order = load order.
+    if (models.length === 0) {
+      return { ok: false, error: 'No models loaded — nothing to save.' };
+    }
+    const reference = findReferenceGeorefModel();
+    const anchorModelId = reference?.modelId ?? anchorModelIdOverride ?? null;
+
+    const setup = await buildFederationSetupFile(models, anchorModelId);
+    const json = serializeFederationSetupFile(setup);
+    const stem = models.length === 1
+      ? sanitizeFilename(models[0].name, { fallback: 'federation' })
+      : `federation-setup-${models.length}-models`;
+    downloadFile(json, `${sanitizeFilename(stem, { fallback: 'federation' })}.federation.json`, 'application/json;charset=utf-8;');
+    return { ok: true };
+  }, [anchorModelIdOverride]);
+
+  /** Match saved slots to freshly-picked local files, without applying anything yet (for the review step). */
+  const matchFederationSetup = useCallback(
+    (setup: FederationSetupFile, files: readonly File[]): Promise<FederationSetupSlotMatch[]> =>
+      matchFederationSetupSlots(setup, files),
+    [],
+  );
+
+  /**
+   * Load every resolvable (matched or name-only) slot through the ONE canonical
+   * load path (`addModel` -> `loadFile`), in saved order, then restore the
+   * anchor and re-run alignment. Never silently drops a slot: the return value
+   * always states exactly how many restored, which were missing, and whether
+   * the anchor could be restored.
+   */
+  const applyFederationSetup = useCallback(
+    async (matches: readonly FederationSetupSlotMatch[]): Promise<FederationSetupApplyResult> => {
+      const summary = summarizeFederationSetupMatches(matches);
+      const loadable = matches.filter((m) => m.file !== null);
+
+      let restoredCount = 0;
+      let restoredAnchorModelId: string | null = null;
+      const hadAnchorSlot = matches.some((m) => m.slot.anchor);
+
+      // Sequential, in saved order — mirrors loadFilesSequentially (the WASM
+      // parser isn't thread-safe) and preserves the saved federation's
+      // relative model order even when some slots are missing.
+      for (const match of loadable) {
+        if (!match.file) continue;
+        const modelId = await addModel(match.file, {
+          name: match.slot.name,
+          visible: match.slot.visible,
+          collapsed: match.slot.collapsed,
+        });
+        if (modelId) {
+          restoredCount += 1;
+          if (match.slot.anchor) restoredAnchorModelId = modelId;
+        }
+      }
+
+      let anchorRestored = false;
+      if (restoredAnchorModelId) {
+        setAnchorModelIdOverride(restoredAnchorModelId);
+        await realignFederation();
+        anchorRestored = true;
+      }
+
+      const outcome: FederationSetupApplyResult['outcome'] =
+        restoredCount === 0 ? 'failed' : restoredCount === matches.length ? 'restored' : 'partial';
+
+      return {
+        outcome,
+        restoredCount,
+        totalSlots: matches.length,
+        missingSlots: summary.missing.map((m) => m.slot.name),
+        mismatchedSlots: summary.mismatched.map((m) => m.slot.name),
+        anchorRestored,
+        anchorMissing: hadAnchorSlot && !anchorRestored,
+      };
+    },
+    [addModel, realignFederation, setAnchorModelIdOverride],
+  );
+
+  return { exportFederationSetup, matchFederationSetup, applyFederationSetup };
+}
+
+export default useFederationSetup;