@pascal-app/viewer 1.0.7 → 1.1.1

package/README.md

@@ -5,13 +5,13 @@
 ## Installation
 
 ```bash
-npm install @pascal-app/core @pascal-app/viewer @pascal-app/editor @pascal-app/nodes
+npm install @pascal-app/core @pascal-app/viewer @pascal-app/nodes
 ```
 
 ## Peer Dependencies
 
 ```bash
-npm install next react react-dom three @react-three/fiber @react-three/drei lucide-react zustand
+npm install react react-dom three @react-three/fiber @react-three/drei lucide-react zustand
 ```
 
 ## What's Included
@@ -25,33 +25,119 @@ npm install next react react-dom three @react-three/fiber @react-three/drei luci
 
 ## Usage
 
-```typescript
-import { loadPlugin } from '@pascal-app/core'
-import { builtinPlugin } from '@pascal-app/nodes'
-import { Viewer } from '@pascal-app/viewer'
-import { useEffect, useState } from 'react'
+The live render entry rebuilds geometry from a scene graph in ordinary React applications,
+including Vite. It requires neither Next.js, Tailwind, nor `@pascal-app/editor`.
 
-const registryReady = loadPlugin(builtinPlugin)
+```tsx
+import { acquireSceneReadOnlyLease, loadPlugin, useScene } from '@pascal-app/core'
+import { renderPlugin } from '@pascal-app/nodes/render'
+import { configureViewer, Viewer } from '@pascal-app/viewer'
+import { OrbitControls } from '@react-three/drei'
+import scene from './scene.json'
+
+configureViewer({
+  assetsBaseUrl: 'https://editor.pascal.app',
+  storageUrl: 'https://your-storage.example',
+  // Optional self-hosted decoder directories (include the trailing slash):
+  // decoders: { dracoPath: '/decoders/draco/', basisPath: '/decoders/basis/' },
+})
+await loadPlugin(renderPlugin)
+const releaseReadOnly = acquireSceneReadOnlyLease()
+useScene.getState().setScene(scene.nodes, scene.rootNodeIds, {
+  materials: scene.materials,
+  collections: scene.collections,
+  installedPlugins: scene.installedPlugins,
+})
 
 function App() {
-  const [ready, setReady] = useState(false)
+  return (
+    <div style={{ width: '100vw', height: '100vh' }}>
+      <Viewer>
+        <OrbitControls makeDefault target={[0, 1, 0]} />
+      </Viewer>
+    </div>
+  )
+}
 
-  useEffect(() => {
-    void registryReady.then(() => setReady(true))
-  }, [])
+// On teardown, unmount App before releasing the lease:
+// releaseReadOnly()
+```
 
-  if (!ready) return null
+Load exactly one built-in plugin per runtime: `renderPlugin` for a viewer, or the full
+`builtinPlugin` from `@pascal-app/nodes` for an editor. Without registration, nodes cannot render.
+The read-only lease suppresses document-writing systems while the live geometry systems rebuild
+from the supplied graph. Keep it until the viewer unmounts.
+
+**One active scene per page/package instance.** `useScene`, `useViewer`, the node registry,
+`sceneRegistry`, loader caches and viewer systems are shared singletons. Concurrent viewers cannot
+own independent graphs. Unmount the previous viewer and release its read-only lease and host
+subscriptions before switching projects; hydrate the new graph and reset the host's viewer
+selection/project presentation before remounting. Use a separate page/iframe for independent graphs.
+
+`configureViewer` resolves asset and storage origins at call time. Without configuration, assets
+use `https://editor.pascal.app`, with the existing `NEXT_PUBLIC_ASSETS_CDN_URL` and
+`NEXT_PUBLIC_SUPABASE_URL` environments used when available. Next hosts should pass those values
+explicitly at bootstrap. Draco defaults to version 1.5.5 and Basis to the Three.js 0.187.0
+transcoder. Configure before loading assets: changing paths does not unload cached models or
+already initialized decoder workers. KTX2 support is detected per renderer and misaligned textures
+retain the RGBA fallback. Denied browser storage disables preference persistence without blocking
+rendering.
+
+See [`fixtures/viewer-live`](../../fixtures/viewer-live) for a complete small graph and the
+isolated packed-package dev/production smoke test.
+
+## Walkthrough for live scenes
+
+`LiveWalkthroughController` is a 3D controller from the main `@pascal-app/viewer` entry.
+Mount it inside `Viewer` alongside your live graph rendered with `renderPlugin`. It is dormant
+until `useViewer.walkthroughMode` is true. `walkthroughMovement` chooses `walk` (gravity,
+BVH collision, crouch, jump and door/window/item/elevator interaction) or `drone` (free flight).
+No editor state, editing plugin or baked asset is required.
 
+```tsx
+import { LiveWalkthroughController, useFirstPersonHud, useViewer, Viewer } from '@pascal-app/viewer'
+import { WalkthroughHud } from '@pascal-app/viewer/ui'
+import { OrbitControls } from '@react-three/drei'
+
+function LiveViewer() {
+  const walking = useViewer(s => s.walkthroughMode)
+  const suspended = useViewer(s => s.walkthroughSuspended)
+  const floorLabel = useFirstPersonHud(s => s.floorLabel)
+  const zoneLabel = useFirstPersonHud(s => s.zoneLabel)
+  const interact = useFirstPersonHud(s => s.interact)
+  const exit = () => useViewer.getState().setWalkthroughMode(false)
   return (
-    <div style={{ width: '100vw', height: '100vh' }}>
-      <Viewer />
+    <div style={{ position: 'relative', width: '100vw', height: '100vh' }}>
+      <Viewer>
+        <OrbitControls enabled={!walking} makeDefault />
+        <LiveWalkthroughController />
+      </Viewer>
+      <button onClick={() => useViewer.getState().setWalkthroughMode(!walking)}>Walkthrough</button>
+      {walking && <WalkthroughHud floorLabel={floorLabel} zoneLabel={zoneLabel}
+        interact={interact} suspended={suspended} onExit={exit} />}
     </div>
   )
 }
 ```
 
-Load the built-in plugin once, before mounting any viewer. Without it, the registry has no node
-definitions and scene nodes cannot render. Host-provided plugins use the same `loadPlugin` API.
+Use the UI styling setup below for the HUD. Click the canvas to lock the pointer; WASD/arrows move,
+Space jumps, Shift runs, Ctrl crouches, E/R or a locked-pointer click operates the targeted object,
+and T closes it. P frees the cursor and click/P resumes. Escape or losing pointer lock exits.
+A placed spawn controls entry position and heading; otherwise the controller derives a grounded
+spawn from the camera and live collider world. Disable other camera controls while walking.
+
+The controller publishes floor, room and interaction prompts to `useFirstPersonHud`. Its main and
+`viewer/ui` exports reference the same store. Mount the HUD outside the canvas and pass those
+values explicitly. Door and drawer cues emit core `interaction:sound`; opt into playback with
+`initInteractionSounds` from `viewer/sfx`. Movement and interaction do not persist document edits.
+
+Optional `LiveWalkthroughControllerProps` let a host own framing: `paused` freezes movement/look,
+`externalFov` (a function, read when walkthrough starts and ends) leaves FOV application/restoration to the host while it returns true, `pointerInteraction={false}` reserves
+locked-pointer clicks for the host, and `suspendOnUnlock` keeps walkthrough active when pointer lock
+is lost (Escape with a free cursor exits). `onExit` runs after the controller clears
+`walkthroughMode`. Props remain current during a session without releasing pointer lock.
+For baked scenes, continue using `GlbWalkthroughController`; `DroneController` also works with
+either scene source when only free flight is needed.
 
 ## Custom Camera Controls
 
@@ -209,14 +295,118 @@ function ViewerControls() {
 }
 ```
 
+## Sound effects (`@pascal-app/viewer/sfx`)
+
+Opt in to building interactions and selection/hover cues from any viewer or custom UI.
+The default files come from `https://editor.pascal.app/audios/sfx`; hosts serving the files
+locally should configure their own base URL before preloading. Importing the entry creates no
+Howl instances or interaction subscriptions. Playback starts after the browser allows audio;
+selection/hover cues stay silent until user activation and during walkthrough.
+
+```tsx
+import { useEffect } from 'react'
+import { configureViewer } from '@pascal-app/viewer'
+import { initInteractionSounds, playSound, useAudioSettings, useViewerUiSounds } from '@pascal-app/viewer/sfx'
+configureViewer({ sfxBaseUrl: '/audios/sfx' })
+function SoundControls() {
+  useEffect(() => initInteractionSounds(), [])
+  useViewerUiSounds()
+  const toggleMute = useAudioSettings(s => s.toggleMute)
+  return <button onPointerEnter={() => playSound('menuHover')} onClick={() => { playSound('menuClick'); toggleMute() }}>Toggle sound</button>
+}
+```
+
+`SOUNDS` lists the built-in cue definitions. `playSound(name, options?)` supports gain
+(`volumeMultiplier`) and stereo positioning. `preloadSounds()` warms files without playing;
+`disposeSounds()` releases the shared cache when the host runtime shuts down. Host cues can use
+`SoundDefinition` objects with the same player, including `startSoundLoop` / `stopSoundLoop`.
+`useAudioSettings` shares master/effects volumes across tabs and keeps mute per tab, preserving
+existing Pascal storage keys. Denied storage falls back to memory. Existing radio preferences
+remain in the same settings record so editor consumers continue to share one store.
+
+## Viewer UI (`@pascal-app/viewer/ui`)
+
+Pascal's read-only viewer chrome as React components: the 3D / 2D / Split stage (`ViewerStage`)
+with its read-only floor plan (`FloorplanPreview`, kept in step with the 3D camera, with its compass
+and floor picker), the controls bar (levels, walls, display, daylight, sky, walkthrough), the scene
+header (project card, breadcrumb, floor list), the hover label, the room pills, room highlight and
+selected-room callout (`ViewerRooms`), the walkthrough and drone HUDs, the loader, the selection
+model behind them
+(`applyViewerClick`, `ViewerSelectionManager`) and the primitives they are built from (`Button`,
+`DropdownMenu*`, `Popover*`, `Tooltip*`, `Switch`). The entry never imports the editor or Next.
+
+The components are styled with Tailwind v4 classes. Point Tailwind at the built entry and import
+the theme (tokens, `shadow-elevation-*`, `corner-smooth`, the loader animations):
+
+```css
+@import "tailwindcss";
+@import "@pascal-app/viewer/ui/theme.css";
+@source "../node_modules/@pascal-app/viewer/dist/ui";
+```
+
+Override any token after the import (`:root { --radius: 0.5rem }`). The docks and menus scope
+themselves with a `dark` class. Control icons load from `configureViewer({ iconsBaseUrl })` (default
+`https://editor.pascal.app/icons`); button sounds play through `@pascal-app/viewer/sfx`.
+
+```tsx
+import { LiveWalkthroughController, useViewer, Viewer } from '@pascal-app/viewer'
+import {
+  ParametricViewerRooms,
+  SceneLoader,
+  ViewerControlsBar,
+  ViewerSceneHeader,
+  ViewerSelectionManager,
+  ViewerStage,
+  WalkthroughHud,
+} from '@pascal-app/viewer/ui'
+
+function ProjectViewer({ ready, name }: { ready: boolean; name: string }) {
+  const walking = useViewer((s) => s.walkthroughMode)
+  const toggleWalk = () => useViewer.getState().setWalkthroughMode(!walking)
+  return (
+    <div className="relative h-full w-full">
+      <ViewerStage>
+        <Viewer selectionManager="custom">
+          <LiveWalkthroughController />
+          <ViewerSelectionManager />
+          <ParametricViewerRooms />
+        </Viewer>
+      </ViewerStage>
+      <ViewerSceneHeader backHref={null} linkComponent={MyLink} projectName={name} />
+      <ViewerControlsBar onWalkthroughToggle={toggleWalk} walkthroughActive={walking} />
+      {walking && <WalkthroughHud onExit={toggleWalk} />}
+      {!ready && <SceneLoader />}
+    </div>
+  )
+}
+```
+
+`ViewerStage` shows its children (the 3D canvas) in 3D, the floor plan in 2D, and both side by side
+in Split; the switcher picks among `modes` (all three by default) and Split falls back to 2D on
+narrow screens. Panning, zooming or turning the plan moves the 3D camera and the reverse, through the
+navigation pose store (`navigationSyncPoseStore`); on the 3D side, drive your drei `CameraControls`
+through `useViewerCameraNavigationSync(controlsRef)`, as Pascal's camera does
+(`synchronizeNavigation={false}` turns the link off). The plan draws each kind's `def.floorplan`,
+which `renderPlugin` carries; without a `scene` prop it reads the live scene store, and a host with
+another node source passes `scene={{ nodes, installedPlugins }}`. Picking a floor in 2D selects that
+level in the viewer. Room names show as the plan's drawn tags. Control the mode with `mode` /
+`onModeChange` or let the stage hold it (`defaultMode`).
+
+`linkComponent` renders the header's links (a plain `<a>` by default); pass your router's link,
+e.g. Next's `Link`. `ParametricViewerRooms` is `ViewerRooms` over the live scene store; a host with
+another node source (a baked scene) passes `<ViewerRooms source={{ nodes, objectFor }} />`. While
+mounted, zones draw no tinted volume: a room shows through its pill and highlight instead. The walkthrough toggle flips `walkthroughMode`; the mounted
+`LiveWalkthroughController` moves the camera. Read `useFirstPersonHud` for the HUD's room and
+interaction props, as in the live walkthrough example above.
+
 ## Asset CDN Helpers
 
 ```typescript
-import { resolveCdnUrl, ASSETS_CDN_URL } from '@pascal-app/viewer'
+import { resolveCdnUrl } from '@pascal-app/viewer'
 
 // Resolves relative paths to CDN URLs
 const url = resolveCdnUrl('/items/chair/model.glb')
-// → 'https://pascal-cdn.wawasensei.dev/items/chair/model.glb'
+// → 'https://editor.pascal.app/items/chair/model.glb'
 
 // Handles external URLs and asset:// protocol
 const externalUrl = resolveCdnUrl('https://example.com/model.glb')

package/dist/components/viewer/drone-controller.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"drone-controller.d.ts","sourceRoot":"","sources":["../../../src/components/viewer/drone-controller.tsx"],"names":[],"mappings":"AAsCA,MAAM,MAAM,oBAAoB,GAAG;IACjC,oEAAoE;IACpE,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,kGAAkG;IAClG,MAAM,CAAC,EAAE,MAAM,IAAI,CAAA;CACpB,CAAA;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,EAAE,MAAc,EAAE,MAAM,EAAE,EAAE,oBAAoB,QAyK/E"}
+{"version":3,"file":"drone-controller.d.ts","sourceRoot":"","sources":["../../../src/components/viewer/drone-controller.tsx"],"names":[],"mappings":"AA+BA,MAAM,MAAM,oBAAoB,GAAG;IACjC,oEAAoE;IACpE,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,kGAAkG;IAClG,MAAM,CAAC,EAAE,MAAM,IAAI,CAAA;CACpB,CAAA;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,EAAE,MAAc,EAAE,MAAM,EAAE,EAAE,oBAAoB,QAyK/E"}

package/dist/components/viewer/drone-controller.js

@@ -3,14 +3,10 @@ import { useFrame, useThree } from '@react-three/fiber';
 import { useEffect, useRef } from 'react';
 import { Vector3 } from 'three';
 import { createDroneInput, DRONE_SLOW_MULTIPLIER, droneInputForKey, readDroneInput, seedDroneLook, stepDroneFlight, turnFirstPersonLook, } from '../../lib/drone-flight';
+import { isTypingTarget } from '../../lib/typing-target';
 import useViewer from '../../store/use-viewer';
 import { WALKTHROUGH_FOV } from './glb-walkthrough-controller';
 import { applyWalkthroughCameraClipping } from './viewer-camera';
-const TYPING_TARGET = 'input, textarea, select, [contenteditable]:not([contenteditable="false"]), [role="combobox"], [role="textbox"], [role="dialog"], [role="alertdialog"]';
-function isTypingTarget(target) {
-    const element = target;
-    return !!element && (element.isContentEditable === true || !!element.closest?.(TYPING_TARGET));
-}
 function requestLock(canvas) {
     // The request can reject asynchronously (the browser's re-lock cooldown);
     // clicking the canvas asks again.

package/dist/components/viewer/first-person/build-collider-world.d.ts

@@ -0,0 +1,14 @@
+import * as THREE from 'three';
+export declare const FIRST_PERSON_SPAWN_EYE_HEIGHT = 1.65;
+export type FirstPersonColliderWorld = {
+    mesh: THREE.Mesh;
+    bounds: THREE.Box3 | null;
+    dispose: () => void;
+};
+export type FirstPersonSpawn = {
+    position: [number, number, number];
+    yaw: number;
+};
+export declare function buildFirstPersonColliderWorldFromRegistry(): FirstPersonColliderWorld | null;
+export declare function deriveFirstPersonSpawn(camera: THREE.Camera, world: FirstPersonColliderWorld): FirstPersonSpawn;
+//# sourceMappingURL=build-collider-world.d.ts.map

package/dist/components/viewer/first-person/build-collider-world.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-collider-world.d.ts","sourceRoot":"","sources":["../../../../src/components/viewer/first-person/build-collider-world.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAqB9B,eAAO,MAAM,6BAA6B,OAAmB,CAAA;AAE7D,MAAM,MAAM,wBAAwB,GAAG;IACrC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAA;IAChB,MAAM,EAAE,KAAK,CAAC,IAAI,GAAG,IAAI,CAAA;IACzB,OAAO,EAAE,MAAM,IAAI,CAAA;CACpB,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IAClC,GAAG,EAAE,MAAM,CAAA;CACZ,CAAA;AAwWD,wBAAgB,yCAAyC,IAAI,wBAAwB,GAAG,IAAI,CA6F3F;AAED,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,KAAK,CAAC,MAAM,EACpB,KAAK,EAAE,wBAAwB,GAC9B,gBAAgB,CA0ClB"}