--- name: reveal-3d description: "Integrates a local Cognite Reveal 3D CAD viewer bundle into Flows apps by copying app-local source code. Use when adding 3D viewer, 3D visualization, Reveal, CAD model, RevealProvider, RevealCanvas, Reveal3DResources, FDM 3D mapping, asset 3D model, model browser, or Cognite 3D content to a Flows application." metadata: argument-hint: "[FDM instance variable name or description, e.g. 'asset' or 'selectedEquipment']" --- # Reveal 3D Viewer Add a Cognite Reveal 3D viewer to a Flows app by copying the bundled source into the target app. Renders CAD models from CDF, with support for model browsing, direct model/revision IDs, or FDM-linked assets. FDM instance to visualize: **$ARGUMENTS** ## Use This When The user wants to embed an interactive Cognite Reveal viewer for CDF 3D/CAD content in a Flows app. Do **not** use this skill for static diagrams, graph visualizations, or unrelated custom Three.js scenes. ## Prerequisites - The app uses React + TypeScript and is wrapped in `@cognite/dune` auth (Flows auth). - The app has a `QueryClientProvider` from `@tanstack/react-query`. - The CDF project has 3D models, or the user has supplied direct model/revision IDs. - For FDM-linked 3D, the instance must be linked through Core DM (`CogniteVisualizable.object3D` -> `CogniteCADNode`). ## Integration Workflow Follow these steps in order. Adapt paths to the target app's conventions instead of inventing new ones. 1. **Inspect the target app.** Read `package.json`, `vite.config.ts`, `src/main.tsx`, and the app's folder/alias conventions. 2. **Install missing dependencies** with the app's package manager. See [Dependencies](#dependencies). Reuse existing pinned React, Flows, SDK, and React Query versions. 3. **Copy the bundle into the app.** Copy every file from `skills/reveal-3d/code/reveal/` into an app-local feature folder, typically: ```text src/features/reveal-3d/ ``` 4. **Import from the local folder**, never from the skill directory or the old external package. With a typical `@/*` alias: ```tsx import { CacheProvider, RevealKeepAlive, RevealProvider } from '@/features/reveal-3d'; ``` 5. **Configure Vite and `main.tsx`.** Read [vite-config.md](references/vite-config.md) and apply the process polyfill, manual `process`/`util`/`assert` aliases, `three` alias, dedupe settings, and `worker.format: 'es'`. 6. **Choose the implementation pattern.** Use Pattern B (model browser or direct model ID) unless you already have a `DMInstanceRef` and confirmed Core DM 3D linkage. For full examples, read [implementation.md](references/implementation.md). 7. **Keep provider placement stable.** `CacheProvider` and `RevealKeepAlive` are always mounted at page/app level. `RevealProvider` is conditional, only when a model is selected or linked. 8. **Run typecheck and build** (`tsc --noEmit`, `pnpm build`, etc.) and fix any copied-import or dependency issues. ## Minimal Example ```tsx import { useCallback, useMemo } from 'react'; import type { CogniteClient } from '@cognite/sdk'; import { CacheProvider, Reveal3DResources, RevealCanvas, RevealKeepAlive, RevealProvider, type AddCadResourceOptions, } from '@/features/reveal-3d'; type SelectedModel = { modelId: number; revisionId: number }; function ViewerContent({ modelId, revisionId }: SelectedModel) { const resources = useMemo( () => [{ modelId, revisionId }], [modelId, revisionId] ); const onLoaded = useCallback(() => {}, []); return ( ); } export function ViewerPage({ sdk, selected, }: { sdk: CogniteClient; selected: SelectedModel | null; }) { const memoizedSdk = useMemo(() => sdk, [sdk.project]); return (
{selected && ( )}
); } ``` ## Dependencies Suggested versions are starting points. If the target app already pins compatible versions, defer to the app. | Package | Suggested version | Purpose | |---------|-------------------|---------| | `react` / `react-dom` | app version | UI framework | | `@cognite/dune` | app version | Authenticated SDK via `useDune()` | | `@cognite/reveal` | `^4.30.0` | Reveal viewer runtime | | `@cognite/sdk` | `^10.0.0` | CDF API client | | `@tanstack/react-query` | `^5.90.21` | Reveal/FDM data fetching hooks | | `three` | `^0.180.0` | Three.js singleton used by Reveal | | `process`, `util`, `assert` | latest | Browser polyfills for Reveal dependencies | | `ajv` | `^8` | Avoids older transitive AJV resolution in monorepos | | `@types/three` | latest dev dep | TypeScript types | Example install (pnpm; adapt to the app's package manager): ```bash pnpm add @cognite/reveal @cognite/sdk @tanstack/react-query three process util assert ajv pnpm add -D @types/three ``` After install, check `@cognite/reveal`'s `three` peer requirement and align `three` if needed. Do **not** install `vite-plugin-node-polyfills`; use the explicit Vite aliases in [vite-config.md](references/vite-config.md). ## Critical Rules - `ViewerContent` contains only `RevealCanvas` and `Reveal3DResources`; no providers. - `resources` passed to `Reveal3DResources` must be memoized with `useMemo`. - `onModelsLoaded`, `onSelect`, and similar callbacks must be memoized with `useCallback`. - The SDK passed to `RevealProvider` must be memoized with `useMemo` keyed on `client.project`. - `RevealCanvas` fills its parent; the parent must have an explicit height. - Lazy-load canvas-heavy viewer content with `React.lazy` + `Suspense` when adding a route/page. ## Advanced Reference For the copied bundle API and exports, read `code/README.md`. For model browser and FDM-linked implementations, read `references/implementation.md`. For Vite, worker, polyfill, and troubleshooting details, read `references/vite-config.md`. ## Verification Checklist - [ ] All files from `skills/reveal-3d/code/reveal/` were copied into an app-local feature folder. - [ ] Imports point to the app-local folder (e.g. `@/features/reveal-3d`). - [ ] The app does not import Reveal helpers from the old external package. - [ ] Required dependencies are present in `package.json`. - [ ] `main.tsx` starts with the `process` polyfill before other imports. - [ ] `vite.config.ts` uses manual aliases, dedupe, `three` singleton alias, and `worker.format: 'es'`. - [ ] `CacheProvider` and `RevealKeepAlive` are always mounted; `RevealProvider` is conditional when model selection is conditional. - [ ] The viewer container has an explicit height. - [ ] Typecheck and build pass.