Embed a viewer or host the editor

There are two ways to put Pascal in your product. Pick one before you start:

	Hosted viewer in an iframe	Editor in your React app
Visitors can	Explore a public project: orbit, switch levels, walk through. Nothing they do edits it.	Edit scenes inside your app
Scenes are stored	In Pascal. The project must be public.	By your app, which loads and saves each scene
Access	Anyone with the link, no account needed	Your app’s own sign-in and permissions
Setup	One `<iframe>`	npm packages, build setup, and `onLoad` and `onSave` handlers
Start at	Basic embed	Host the editor in a React app

A public project is visible to anyone who has its link, so the hosted viewer is not a private way to show client work. See Share a project link.

Hosted viewer

Any public Pascal project can be embedded on another site with a plain <iframe> pointing at its viewer page. Visitors get the full interactive viewer — orbiting the camera, toggling levels and wall cutaways, and walking through the scene in first person — with no accounts, SDKs, or scripts required on your side. We rely on the same embed ourselves: the Pascal Capture iOS app shows scenes through this exact viewer.

The Pascal viewer embedded in the Pascal Capture iOS app — The embedded viewer inside the Pascal Capture iOS app — levels panel and controls bar included

Requirements

The project must be public. Flip the visibility control in the editor’s top bar from Private to Public. Private projects render an access screen instead of the scene.
Grab the URL with the Copy viewer link button next to the visibility control, or copy it from the address bar on the project’s viewer page. It has the form:

https://editor.pascal.app/viewer/<project-id>

Basic embed

<iframe
  src="https://editor.pascal.app/viewer/PROJECT_ID"
  width="800"
  height="500"
  style="border: 0; border-radius: 12px;"
  loading="lazy"
  title="Pascal 3D scene"
></iframe>

Replace PROJECT_ID with your project’s id (the last path segment of your viewer link). For a responsive embed, wrap the iframe in a container with a fixed aspect ratio:

<div style="aspect-ratio: 16 / 9;">
  <iframe
    src="https://editor.pascal.app/viewer/PROJECT_ID"
    style="border: 0; border-radius: 12px; width: 100%; height: 100%;"
    loading="lazy"
    title="Pascal 3D scene"
  ></iframe>
</div>

Embed mode for listings

Add embed=1 to show the scene the way the editor’s Preview does: the scene header (project name, breadcrumb and levels), the controls bar and the 2D/3D switcher. The community’s owner card, likes, Duplicate button, collections and the “Get Started” card are hidden.

<iframe
  src="https://editor.pascal.app/viewer/PROJECT_ID?embed=1&camera=saved"
  width="800"
  height="500"
  style="border: 0; border-radius: 12px;"
  loading="lazy"
  title="Pascal 3D scene"
></iframe>

Parameter	Effect
`embed`	Embed mode, as above. A value of `1`, `true`, or `yes` enables it.
`camera`	The opening view: `px,py,pz,tx,ty,tz` (camera position, then the point it looks at, in scene metres), with an optional seventh value for the field of view in degrees (10–120). `saved` opens on the view saved on the scene in the editor. An invalid value is ignored, so the viewer opens on its default view.
`returnTo`	In embed mode, shows a back arrow to this Pascal page (a path under `/community` or `/u`; any other value goes back to `/community`). Without it there is no back arrow.

When the scene is loaded and the opening view has landed, the frame posts one message to its parent, so your page can reveal the frame without showing the default view first:

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://editor.pascal.app') return
  if (event.data?.type === 'pascal:viewer-ready') {
    // event.data.projectId is the project shown
  }
})

URL parameters

The viewer accepts two flags to reduce its chrome inside embeds. A value of 1, true, or yes enables a flag.

Parameter	Effect
`hideHeader`	Hides the top-left card (back arrow, project name, owner, and its actions)
`hideBottomBar`	Hides the bottom-center controls bar (levels, walls, walkthrough, orbit, top view)

<iframe
  src="https://editor.pascal.app/viewer/PROJECT_ID?hideHeader=1&hideBottomBar=1"
  width="800"
  height="500"
  style="border: 0; border-radius: 12px;"
  loading="lazy"
  title="Pascal 3D scene"
></iframe>

Even with both bars hidden, visitors can still orbit, pan, and zoom the camera with the mouse or touch.

On another site, the viewer always uses the embed presentation: the owner card, likes, Duplicate button, collections and the “Get Started” card are hidden even without embed=1, so visitors can’t be tricked into acting on their Pascal account.

What the embed serves

Embeds load the same thing your shared viewer link does: once a published project has finished baking, the viewer serves the optimized baked copy for fast loading, with doors and windows still interactive. Until a fresh bake is ready, it falls back to rendering the live scene. Republishing your project updates every embed automatically — the iframe URL never changes.

Current limits

An iframe is the only supported embed for hosted projects. There is no oEmbed endpoint or JavaScript API; the frame posts one message, pascal:viewer-ready, and accepts none.
Only the read-only viewer of a hosted project can be embedded, not the editor. To build the editor into your own React app, see Host the editor in a React app.
A self-hosted editor has its own public embeds at /embed/<id>. See Share a project publicly.

Host the editor in a React app

The open-source editor is also a React component, Editor from @pascal-app/editor. Your app supplies the scene and saves it; the component brings the tools, panels, the floor plan and the 3D view. Everything below is in version 1.0.5 of the packages.

npm install @pascal-app/core @pascal-app/viewer @pascal-app/editor @pascal-app/nodes

The editor expects React 18 or 19, Next.js 15 or newer, three.js 0.186, @react-three/fiber 9 and @react-three/drei 10 in your app. Load the built-in node definitions once, before you mount it:

registry.ts

import { loadPlugin } from "@pascal-app/core";
import { builtinPlugin } from "@pascal-app/nodes";

export const registryReady = loadPlugin(builtinPlugin);

Then mount the editor once registryReady has resolved. Without the node definitions, the scene can’t render:

"use client";

import { Editor } from "@pascal-app/editor";
import { useEffect, useState } from "react";
import { registryReady } from "./registry";

export function ProjectPage({ projectId }: { projectId: string }) {
  const [ready, setReady] = useState(false);
  useEffect(() => {
    void registryReady.then(() => setReady(true));
  }, []);
  if (!ready) return null;

  return (
    <div style={{ width: "100vw", height: "100vh" }}>
      <Editor
        layoutVersion="v2"
        projectId={projectId}
        onLoad={() => loadScene(projectId)}
        onSave={(scene) => saveScene(projectId, scene)}
        actionMenuPlacement="top"
        loadingSlot={<MyProjectSpinner />}
        onLoaderChange={(visible) => track("editor-loading", visible)}
        onViewerBreadcrumb={(breadcrumb) => reportBreadcrumb(breadcrumb)}
      />
    </div>
  );
}

onLoad resolves to the scene graph to open (or null), and onSave receives the scene graph to store. The editor’s own app, apps/editor/components/scene-loader.tsx, is a complete host with persistence. Your app owns authentication, access control and storage: before you ship, make an edit, let it save, reload the page and check that onLoad opens the saved scene.

Styles and build setup

@pascal-app/editor ships TypeScript source and styles itself with Tailwind CSS v4 utility classes. It ships no compiled stylesheet. In your app:

Add the editor to Next.js transpilePackages, with @pascal-app/core, @pascal-app/viewer and three.
Point Tailwind at the packages’ files, which it doesn’t scan in node_modules by default, and make dark: follow the .dark class:

@import "tailwindcss";
@source "../node_modules/@pascal-app/editor/src";
@source "../node_modules/@pascal-app/nodes/dist";

@custom-variant dark (&:is(.dark *));

Adjust the paths to where your stylesheet sits. The editor also reads the theme tokens (colours, radii, fonts) that the open-source app defines in apps/editor/app/globals.css; copy them, or map them to your own design tokens.

Host props

Prop	What it does
`loadingSlot`	Your loading surface. It covers the canvas panes in both layouts, in 2D and 3D, while the scene loads. The editor still decides when loading is over, and a failed load always shows the editor’s error and Try again screen. Omit it or pass `null` for the default loader.
`onLoaderChange`	Called with `true` when the loader shows and `false` when the scene is ready, so you can measure open-to-interactive time.
`actionMenuPlacement`	`'bottom'` (default) or `'top'`. With `'top'`, the v2 layout gives the tool menu its own row under the toolbar, centred on the scene panes, so the bottom strip stays free; the v1 layout floats it at the top edge. On mobile it stays at the bottom. The type is exported as `ActionMenuPlacement`.
`onViewerBreadcrumb`	Receives viewer diagnostics for your error reporter, such as `raycast_invalid_material` when a pointer raycast skips a mesh whose geometry groups point past its materials. Each breadcrumb is `{ category, message, level, data? }`, with `level` `'info'` or `'warning'`. The packages carry no error-reporting SDK, so forward it yourself, for example to Sentry’s `addBreadcrumb`.

onViewerBreadcrumb forwards the onBreadcrumb prop of Viewer from @pascal-app/viewer. If you mount the read-only Viewer on its own, pass onBreadcrumb there. Both use the ViewerBreadcrumb and ViewerBreadcrumbHandler types that @pascal-app/viewer exports.

Light and dark chrome

The editor sets no theme of its own: its chrome follows the nearest .dark class. Leave the class off for a light editor. Menus and tooltips render into <body>, so for a dark editor put dark on <body> or <html>. The Preview stage, the walkthrough HUD and the controls bar stay dark in either theme, and the 3D scene keeps its own Scene theme. To let people pick, pass InterfaceThemeRow through SettingsPanel’s preferences slot. It’s the System, Light and Dark row; applying the choice is up to your app:

import { InterfaceThemeRow, SettingsPanel, type InterfaceTheme } from "@pascal-app/editor";

<SettingsPanel
  preferences={
    <InterfaceThemeRow value={theme} onChange={(next: InterfaceTheme) => setTheme(next)} />
  }
/>;

InterfaceTheme is 'system' | 'light' | 'dark'. Without the row, Preferences shows no theme setting.

Select and show a node

These are the helpers the editor’s own lists use, so a node selected from your UI behaves the same way:

import { enterUnitFocus, frameViewerNode, selectZoneOrRoom } from "@pascal-app/editor";

selectZoneOrRoom(zoneId); // returns "room" for an enclosed room, else "zone"
frameViewerNode(nodeId, source); // the node's saved view, else its bounding box
enterUnitFocus(unitId); // focus a unit, as the site panel does

selectZoneOrRoom selects an enclosed room as a room (its panel and pill), and anything else as a zone.
frameViewerNode moves the camera to the node: its saved view if it has one, else its bounding box. When only the 2D plan is on screen, the plan glides to fit the node instead. Under reduced motion, it jumps. source is a ViewerSource: { nodes, objectFor }, the scene’s nodes and a lookup from a node id to its rendered three.js object.
enterUnitFocus focuses a unit, which isn’t selectable on its own.

Nodes your app lists in useViewer’s pointedIds (for example, the ones a chat message mentions) are highlighted in the plan, as a room outline, and in 3D. PLUGINS_VIEW_ID names the plugin directory view. Open it with openEditorView(PLUGINS_VIEW_ID).

Plugin start screens in your chat

A plugin’s PluginChatExtension can add a start screen that your chat shows while a thread is empty. start lazily loads a component that receives ChatStartProps:

Member	What it does
`send(text, images?)`	Sends a message now, at the level that runs the plugin’s tools. Images go by reference (`{ url, name }`).
`attach(files)`	Puts files on the next message, in the composer.
`requirePro()`	Asks whether the person’s plan includes the level that runs the plugin’s tools. When it doesn’t, your app offers the upgrade and it returns `false`. It changes nothing in the chat.

IconRefGlyph ({ icon, size? }) and IconRefImage ({ src, size?, className? }) render registry icons the way the editor does. See Create a plugin for the rest of the plugin contract.

Integrate

Extend Pascal

Embed a viewer or host the editor

Hosted viewer

Requirements

Basic embed

Embed mode for listings

URL parameters

What the embed serves

Current limits

Host the editor in a React app

Styles and build setup

Host props

Light and dark chrome

Select and show a node

Plugin start screens in your chat