@pascal-app/editor 1.0.0 → 1.0.1

package/src/lib/send-to-app.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, test } from 'bun:test'
+import { LocalAppError, probeLocalApp, sendGlbToLocalApp, waitForLocalImport } from './send-to-app'
+
+type Handler = (url: string, init?: RequestInit) => Response | Promise<Response>
+
+function fakeFetch(handler: Handler): typeof fetch {
+  return ((input: RequestInfo | URL, init?: RequestInit) =>
+    Promise.resolve(handler(String(input), init))) as typeof fetch
+}
+
+const json = (body: unknown, status = 200) =>
+  new Response(JSON.stringify(body), { status, headers: { 'Content-Type': 'application/json' } })
+
+describe('probeLocalApp', () => {
+  test('reports unreachable when nothing answers on any port', async () => {
+    const tried: string[] = []
+    const probe = await probeLocalApp(
+      fakeFetch((url) => {
+        tried.push(url)
+        throw new TypeError('Failed to fetch')
+      }),
+      27412,
+      3,
+    )
+    expect(probe).toEqual({ status: 'unreachable' })
+    expect(tried).toEqual([
+      'http://127.0.0.1:27412/pascal/health',
+      'http://127.0.0.1:27413/pascal/health',
+      'http://127.0.0.1:27414/pascal/health',
+    ])
+  })
+
+  test('finds the app on a fallback port and tells whether it allows this origin', async () => {
+    const health = { app: 'blender', version: '5.2.1', addon: '0.1.0', port: 27413, allowed: false }
+    const probe = await probeLocalApp(
+      fakeFetch((url) => {
+        if (url.startsWith('http://127.0.0.1:27413/')) return json(health)
+        throw new TypeError('Failed to fetch')
+      }),
+    )
+    expect(probe).toEqual({ status: 'refused', base: 'http://127.0.0.1:27413', health })
+  })
+})
+
+describe('sendGlbToLocalApp', () => {
+  test('posts the GLB with percent-encoded project headers', async () => {
+    let seen: RequestInit | undefined
+    const status = await sendGlbToLocalApp(
+      'http://127.0.0.1:27412',
+      new Blob([new Uint8Array([1, 2, 3])]),
+      { name: 'Maison été', projectId: 'project_1' },
+      fakeFetch((_url, init) => {
+        seen = init
+        return json({ id: 'abc', state: 'queued' }, 202)
+      }),
+    )
+    expect(status).toEqual({ id: 'abc', state: 'queued' })
+    expect(seen?.method).toBe('POST')
+    expect(seen?.headers).toEqual({
+      'Content-Type': 'model/gltf-binary',
+      'X-Pascal-Project-Name': 'Maison%20%C3%A9t%C3%A9',
+      'X-Pascal-Project-Id': 'project_1',
+    })
+  })
+
+  test('maps a 403 to a refused error', async () => {
+    await expect(
+      sendGlbToLocalApp(
+        'http://127.0.0.1:27412',
+        new Blob([]),
+        {},
+        fakeFetch(() => json({ error: 'origin_not_allowed' }, 403)),
+      ),
+    ).rejects.toMatchObject({ name: 'LocalAppError', reason: 'refused' })
+  })
+})
+
+describe('waitForLocalImport', () => {
+  test('polls until the import is done', async () => {
+    let calls = 0
+    const status = await waitForLocalImport(
+      'http://127.0.0.1:27412',
+      'abc',
+      fakeFetch(() => {
+        calls += 1
+        return json(
+          calls < 3
+            ? { id: 'abc', state: 'queued' }
+            : { id: 'abc', state: 'done', summary: 'Imported' },
+        )
+      }),
+      { intervalMs: 1 },
+    )
+    expect(status.state).toBe('done')
+    expect(calls).toBe(3)
+  })
+
+  test('surfaces a failed import', async () => {
+    const error = await waitForLocalImport(
+      'http://127.0.0.1:27412',
+      'abc',
+      fakeFetch(() => json({ id: 'abc', state: 'failed', error: 'boom' })),
+      { intervalMs: 1 },
+    ).catch((e: unknown) => e)
+    expect(error).toBeInstanceOf(LocalAppError)
+    expect((error as LocalAppError).reason).toBe('failed')
+  })
+})

package/src/lib/send-to-app.ts

@@ -0,0 +1,121 @@
+/**
+ * Hand a scene to a desktop app listening on loopback (the Pascal Blender add-on
+ * today). The app answers `GET /pascal/health`, accepts a GLB on
+ * `POST /pascal/import`, and reports the import on `GET /pascal/import/<id>`.
+ * Protocol reference: https://github.com/pascalorg/blender-addon#send-to-blender-from-the-editor
+ */
+
+export const LOCAL_APP_PORT = 27412
+export const LOCAL_APP_PORT_RANGE = 5
+const PROBE_TIMEOUT_MS = 1000
+
+export type LocalAppHealth = {
+  app: string
+  version: string
+  addon: string
+  port: number
+  allowed: boolean
+}
+
+export type LocalAppProbe =
+  | { status: 'listening'; base: string; health: LocalAppHealth }
+  | { status: 'refused'; base: string; health: LocalAppHealth }
+  | { status: 'unreachable' }
+
+export type LocalImportStatus = {
+  id: string
+  state: 'queued' | 'done' | 'failed'
+  summary?: string
+  error?: string
+}
+
+export class LocalAppError extends Error {
+  constructor(
+    readonly reason: 'refused' | 'rejected' | 'failed' | 'timeout',
+    message: string,
+  ) {
+    super(message)
+    this.name = 'LocalAppError'
+  }
+}
+
+type FetchLike = typeof fetch
+
+function isHealth(value: unknown): value is LocalAppHealth {
+  const health = value as Partial<LocalAppHealth> | null
+  return Boolean(health && typeof health.app === 'string' && typeof health.allowed === 'boolean')
+}
+
+/** Try the app's port and a few after it, one second each. */
+export async function probeLocalApp(
+  fetchImpl: FetchLike = fetch,
+  port = LOCAL_APP_PORT,
+  range = LOCAL_APP_PORT_RANGE,
+): Promise<LocalAppProbe> {
+  for (let candidate = port; candidate < port + range; candidate++) {
+    const base = `http://127.0.0.1:${candidate}`
+    try {
+      const response = await fetchImpl(`${base}/pascal/health`, {
+        cache: 'no-store',
+        signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
+      })
+      if (!response.ok) continue
+      const health: unknown = await response.json()
+      if (!isHealth(health)) continue
+      return { status: health.allowed ? 'listening' : 'refused', base, health }
+    } catch {
+      // Nothing listening there; try the next port.
+    }
+  }
+  return { status: 'unreachable' }
+}
+
+export type SendSceneMeta = {
+  name?: string
+  projectId?: string
+  version?: string
+}
+
+/** POST the GLB; resolves with the queued import id. */
+export async function sendGlbToLocalApp(
+  base: string,
+  blob: Blob,
+  meta: SendSceneMeta = {},
+  fetchImpl: FetchLike = fetch,
+): Promise<LocalImportStatus> {
+  const headers: Record<string, string> = { 'Content-Type': 'model/gltf-binary' }
+  // Header values are Latin-1; the listener percent-decodes these.
+  if (meta.name) headers['X-Pascal-Project-Name'] = encodeURIComponent(meta.name)
+  if (meta.projectId) headers['X-Pascal-Project-Id'] = meta.projectId
+  if (meta.version) headers['X-Pascal-Version'] = meta.version
+  const response = await fetchImpl(`${base}/pascal/import`, { method: 'POST', headers, body: blob })
+  if (response.status === 403) {
+    throw new LocalAppError('refused', 'The app has not allowed this site to send scenes.')
+  }
+  if (!response.ok) {
+    throw new LocalAppError('rejected', `The app rejected the scene (HTTP ${response.status}).`)
+  }
+  return (await response.json()) as LocalImportStatus
+}
+
+/** Poll until the app has imported (or failed to import) the queued scene. */
+export async function waitForLocalImport(
+  base: string,
+  id: string,
+  fetchImpl: FetchLike = fetch,
+  { timeoutMs = 120_000, intervalMs = 500 } = {},
+): Promise<LocalImportStatus> {
+  const deadline = Date.now() + timeoutMs
+  while (Date.now() < deadline) {
+    const response = await fetchImpl(`${base}/pascal/import/${id}`, { cache: 'no-store' })
+    if (response.ok) {
+      const status = (await response.json()) as LocalImportStatus
+      if (status.state === 'done') return status
+      if (status.state === 'failed') {
+        throw new LocalAppError('failed', status.error ?? 'The app could not import the scene.')
+      }
+    }
+    await new Promise((resolve) => setTimeout(resolve, intervalMs))
+  }
+  throw new LocalAppError('timeout', 'The app did not finish importing in time.')
+}

package/src/lib/sfx/movement-tick.ts

@@ -1,3 +1,5 @@
+import { sfxEmitter } from '../sfx-bus'
+
 const DEFAULT_FREE_MOVEMENT_SFX_STEP_M = 0.1
 
 type MovementSfxStepKeyArgs = {
@@ -16,3 +18,38 @@ export function movementSfxStepKey({
   const step = gridSnapActive && gridStep > 0 ? gridStep : freeStep
   return coords.map((coord) => Math.round(coord / step)).join(',')
 }
+
+export function createMovementSfxTick() {
+  let previousKey: string | null = null
+  let pending: (() => void) | null = null
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const tick = (args: MovementSfxStepKeyArgs, emitInitialStep = false) => {
+    const nextKey = movementSfxStepKey(args)
+    if (nextKey !== previousKey && (previousKey !== null || emitInitialStep)) {
+      sfxEmitter.emit('sfx:grid-snap')
+    }
+    previousKey = nextKey
+  }
+  const cancel = () => {
+    clearTimeout(timer)
+    timer = undefined
+    pending = null
+  }
+  const flush = () => {
+    const apply = pending
+    cancel()
+    apply?.()
+  }
+  return {
+    tick,
+    schedule(args: MovementSfxStepKeyArgs, shouldPlay: () => boolean, emitInitialStep = false) {
+      pending = () => {
+        if (shouldPlay()) tick(args, emitInitialStep)
+      }
+      // Wait for R3F host dispatch after the native grid listener, without delaying the move.
+      if (timer === undefined) timer = setTimeout(flush, 0)
+    },
+    flush,
+    cancel,
+  }
+}

package/src/lib/surface-attachment.ts

@@ -0,0 +1,77 @@
+import { type AnyNode, type AnyNodeId, useScene } from '@pascal-app/core'
+import { evaluateRecipe, isProceduralItem } from '@pascal-app/core/procedural-items'
+import { Euler, Quaternion, Vector3 } from 'three'
+
+type Pose = { position: [number, number, number]; rotation: [number, number, number] }
+
+export function surfaceAttachmentId(node: Pick<AnyNode, 'id' | 'parentId'>): string | null {
+  const parent = node.parentId ? useScene.getState().nodes[node.parentId as AnyNodeId] : undefined
+  return isProceduralItem(parent) ? (parent.attachments[node.id] ?? null) : null
+}
+
+export function surfaceAttachmentUpdates(
+  id: AnyNodeId,
+  parentId: string | null | undefined,
+  surfaceId: string | null,
+) {
+  const nodes = useScene.getState().nodes
+  const updates: { id: AnyNodeId; data: Partial<AnyNode> }[] = []
+  for (const hostId of new Set([nodes[id]?.parentId, parentId])) {
+    const host = hostId ? nodes[hostId as AnyNodeId] : undefined
+    if (!isProceduralItem(host)) continue
+    const nextId = host.id === parentId ? surfaceId : null
+    if ((host.attachments[id] ?? null) === nextId) continue
+    const attachments = { ...host.attachments }
+    if (nextId === null) delete attachments[id]
+    else attachments[id] = nextId
+    updates.push({ id: host.id, data: { attachments } })
+  }
+  return updates
+}
+
+export function updateSurfaceNode(
+  id: AnyNodeId,
+  data: Partial<AnyNode>,
+  surfaceId?: string | null,
+) {
+  const node = useScene.getState().nodes[id]
+  const parentId = data.parentId === undefined ? node?.parentId : data.parentId
+  const selected =
+    surfaceId === undefined && node && node.parentId === parentId
+      ? surfaceAttachmentId(node)
+      : (surfaceId ?? null)
+  useScene
+    .getState()
+    .updateNodes([{ id, data }, ...surfaceAttachmentUpdates(id, parentId, selected)])
+}
+
+export function surfaceFramePose(
+  parentId: string | null | undefined,
+  surfaceId: string | null,
+  pose: Pose,
+  toStorage: boolean,
+): Pose {
+  const host = parentId ? useScene.getState().nodes[parentId as AnyNodeId] : undefined
+  if (!isProceduralItem(host) || surfaceId === null)
+    return { position: pose.position, rotation: pose.rotation }
+  const surface = evaluateRecipe(host.recipe, host.parameters).surfaces.find(
+    (s) => s.id === surfaceId,
+  )
+  if (!surface) throw new Error('Missing attachment surface')
+  const q = new Quaternion().setFromEuler(new Euler(...surface.rotation))
+  const position = new Vector3(...pose.position)
+  if (toStorage) position.sub(new Vector3(...surface.position)).applyQuaternion(q.clone().invert())
+  else position.applyQuaternion(q).add(new Vector3(...surface.position))
+  if (!surface.rotation[0] && !surface.rotation[2] && !pose.rotation[0] && !pose.rotation[2]) {
+    return {
+      position: position.toArray(),
+      rotation: [0, pose.rotation[1] + (toStorage ? -1 : 1) * surface.rotation[1], 0],
+    }
+  }
+  const rotation = new Euler().setFromQuaternion(
+    new Quaternion()
+      .setFromEuler(new Euler(...pose.rotation))
+      .premultiply(toStorage ? q.invert() : q),
+  )
+  return { position: position.toArray(), rotation: [rotation.x, rotation.y, rotation.z] }
+}

package/src/lib/units.ts

@@ -0,0 +1,254 @@
+import {
+  type AnyNode,
+  type AnyNodeId,
+  type BuildingNode,
+  type LevelNode,
+  pointInPolygon2D,
+  resolveAutoZonePolygon,
+  snapWorldXZToBuildingLocal,
+  UnitNode,
+  useScene,
+  type ZoneNode,
+} from '@pascal-app/core'
+import { useViewer } from '@pascal-app/viewer'
+import { useEffect } from 'react'
+import useEditor, { type StructureLayer } from '../store/use-editor'
+import { getActiveBuildingPose } from './world-grid-snap'
+
+type Nodes = Readonly<Record<AnyNodeId, AnyNode>>
+
+// Unit focus is a session gesture: the layer the user was on when focus began
+// comes back when focus ends, unless they switched layers by hand meanwhile.
+let restoreLayer: StructureLayer | null = null
+let entering = false
+let leaving = false
+
+export function focusedUnitNode(): UnitNode | null {
+  const id = useViewer.getState().focusedUnitId
+  const node = id ? useScene.getState().nodes[id] : undefined
+  return node?.type === 'unit' ? node : null
+}
+
+/** Levels carrying member zones, lowest ordinal first. */
+export function unitMemberLevels(unit: UnitNode, nodes: Nodes): LevelNode[] {
+  const levels = new Map<LevelNode['id'], LevelNode>()
+  for (const zoneId of unit.members) {
+    const zone = nodes[zoneId]
+    const level =
+      zone?.type === 'zone' && zone.parentId ? nodes[zone.parentId as AnyNodeId] : undefined
+    if (level?.type === 'level') levels.set(level.id, level)
+  }
+  return [...levels.values()].sort((a, b) => a.level - b.level)
+}
+
+export function enterUnitFocus(unitId: UnitNode['id']): void {
+  if (entering) return
+  entering = true
+  try {
+    const nodes = useScene.getState().nodes
+    const unit = nodes[unitId]
+    if (unit?.type !== 'unit') return
+    const editor = useEditor.getState()
+    if (restoreLayer === null) restoreLayer = editor.structureLayer
+    if (editor.phase !== 'structure') editor.setPhase('structure')
+    if (useEditor.getState().structureLayer !== 'zones') {
+      useEditor.getState().setStructureLayer('zones')
+    }
+    const viewer = useViewer.getState()
+    if (viewer.focusedUnitId !== unitId) viewer.setFocusedUnit(unitId)
+
+    const { selection, setSelection } = useViewer.getState()
+    const levels = unitMemberLevels(unit, nodes)
+    const levelId = levels.some((level) => level.id === selection.levelId)
+      ? selection.levelId
+      : (levels[0]?.id ?? selection.levelId)
+    const buildingId = (unit.parentId as BuildingNode['id'] | null) ?? selection.buildingId
+    const unitSelected = selection.selectedIds.length === 1 && selection.selectedIds[0] === unitId
+    if (selection.buildingId !== buildingId || selection.levelId !== levelId || !unitSelected) {
+      setSelection({ buildingId, levelId, selectedIds: [unitId] })
+    }
+  } finally {
+    entering = false
+  }
+}
+
+function finishLeave(unitId: UnitNode['id'], keepLayer: boolean) {
+  const layer = restoreLayer
+  restoreLayer = null
+  const editor = useEditor.getState()
+  if (
+    !keepLayer &&
+    layer &&
+    layer !== 'zones' &&
+    editor.phase === 'structure' &&
+    editor.structureLayer === 'zones'
+  ) {
+    editor.setStructureLayer(layer)
+  }
+  const { selection, setSelection } = useViewer.getState()
+  if (selection.selectedIds.length === 1 && selection.selectedIds[0] === unitId) {
+    setSelection({ selectedIds: [] })
+  }
+}
+
+/** Ends unit focus. Returns false when no unit was focused. */
+export function leaveUnitFocus(options?: { keepLayer?: boolean }): boolean {
+  const viewer = useViewer.getState()
+  const unitId = viewer.focusedUnitId
+  if (!unitId) return false
+  leaving = true
+  try {
+    viewer.setFocusedUnit(null)
+  } finally {
+    leaving = false
+  }
+  finishLeave(unitId, options?.keepLayer ?? false)
+  return true
+}
+
+/**
+ * Puts a zone in exactly one unit (or none): it leaves every other unit in the
+ * same store update, so the move is one undo step.
+ */
+export function assignZoneToUnit(zoneId: ZoneNode['id'], unitId: UnitNode['id'] | null): void {
+  const { nodes, updateNodes } = useScene.getState()
+  const updates: Array<{ id: AnyNodeId; data: Partial<AnyNode> }> = []
+  for (const node of Object.values(nodes)) {
+    if (node.type !== 'unit' || node.id === unitId || !node.members.includes(zoneId)) continue
+    updates.push({ id: node.id, data: { members: node.members.filter((id) => id !== zoneId) } })
+  }
+  const target = unitId ? nodes[unitId] : undefined
+  if (target?.type === 'unit' && !target.members.includes(zoneId)) {
+    updates.push({ id: target.id, data: { members: [...target.members, zoneId] } })
+  }
+  if (updates.length > 0) updateNodes(updates)
+}
+
+export function toggleZoneMembership(unitId: UnitNode['id'], zoneId: ZoneNode['id']): void {
+  const unit = useScene.getState().nodes[unitId]
+  if (unit?.type !== 'unit') return
+  assignZoneToUnit(zoneId, unit.members.includes(zoneId) ? null : unitId)
+}
+
+/**
+ * The zone under a point on the current level, in building-local XZ. A 3D
+ * click lands on whatever surface is closest (a floor slab sits above the
+ * zone fill), so painting resolves the zone from the hit point instead of the
+ * hit mesh. Nested zones resolve to the smallest one.
+ */
+export function zoneAtLevelPoint(x: number, z: number): ZoneNode | null {
+  const levelId = useViewer.getState().selection.levelId
+  if (!levelId) return null
+  const nodes = useScene.getState().nodes
+  const resolve = (id: AnyNodeId) => nodes[id]
+  let best: ZoneNode | null = null
+  let bestArea = Number.POSITIVE_INFINITY
+  for (const node of Object.values(nodes)) {
+    if (node.type !== 'zone' || node.parentId !== levelId) continue
+    const polygon = resolveAutoZonePolygon(node, resolve)
+    if (!pointInPolygon2D([x, z], polygon)) continue
+    let area = 0
+    for (let i = 0; i < polygon.length; i++) {
+      const a = polygon[i]!
+      const b = polygon[(i + 1) % polygon.length]!
+      area += a[0] * b[1] - b[0] * a[1]
+    }
+    area = Math.abs(area) / 2
+    if (area < bestArea) {
+      best = node
+      bestArea = area
+    }
+  }
+  return best
+}
+
+export function zoneAtWorldPoint(worldX: number, worldZ: number): ZoneNode | null {
+  const pose = getActiveBuildingPose()
+  const [x, z] = pose
+    ? snapWorldXZToBuildingLocal(worldX, worldZ, pose.position, pose.rotationY, 0).local
+    : [worldX, worldZ]
+  return zoneAtLevelPoint(x, z)
+}
+
+export const ZONE_PAINT_DELAY_MS = 250
+const pendingPaints = new Map<ZoneNode['id'], ReturnType<typeof setTimeout>>()
+
+/**
+ * The canvas paint gesture. The toggle waits out the double-click window so
+ * the second click of a double-click cancels it instead of toggling twice;
+ * the double-click itself then selects the zone.
+ */
+export function paintZoneMembership(unitId: UnitNode['id'], zoneId: ZoneNode['id']): void {
+  if (cancelPendingZonePaint(zoneId)) return
+  pendingPaints.set(
+    zoneId,
+    setTimeout(() => {
+      pendingPaints.delete(zoneId)
+      toggleZoneMembership(unitId, zoneId)
+    }, ZONE_PAINT_DELAY_MS),
+  )
+}
+
+export function cancelPendingZonePaint(zoneId: ZoneNode['id']): boolean {
+  const pending = pendingPaints.get(zoneId)
+  if (!pending) return false
+  clearTimeout(pending)
+  pendingPaints.delete(zoneId)
+  return true
+}
+
+export function createUnitInBuilding(buildingId: BuildingNode['id']): UnitNode['id'] | null {
+  const scene = useScene.getState()
+  const building = scene.nodes[buildingId]
+  if (building?.type !== 'building') return null
+  const unitCount = building.children.filter((id) => scene.nodes[id]?.type === 'unit').length
+  const unit = UnitNode.parse({ name: `Unit ${unitCount + 1}` })
+  scene.createNode(unit, buildingId)
+  enterUnitFocus(unit.id)
+  return unit.id
+}
+
+/**
+ * Keeps unit focus coherent with the rest of the editor: a focus set from
+ * anywhere (the unit inspector calls the viewer store directly) gets the full
+ * enter treatment, and focus ends when the user switches layer or phase by
+ * hand, selects anything other than the focused unit, or the unit is deleted.
+ */
+export function useUnitFocusRules(): void {
+  useEffect(() => {
+    const unsubscribeViewer = useViewer.subscribe((state, prev) => {
+      if (state.focusedUnitId !== prev.focusedUnitId) {
+        if (state.focusedUnitId) enterUnitFocus(state.focusedUnitId)
+        else if (prev.focusedUnitId && !leaving) finishLeave(prev.focusedUnitId, false)
+        return
+      }
+      const unitId = state.focusedUnitId
+      if (!unitId || state.selection === prev.selection) return
+      // Selecting a zone keeps focus: renaming or recolouring a zone row is
+      // part of arranging the unit, and zones live on the layer focus uses.
+      const { selectedIds } = state.selection
+      const selectsOther =
+        selectedIds.length > 0 && !(selectedIds.length === 1 && selectedIds[0] === unitId)
+      if (selectsOther) leaveUnitFocus()
+    })
+    const unsubscribeEditor = useEditor.subscribe((state, prev) => {
+      if (state.structureLayer === prev.structureLayer && state.phase === prev.phase) return
+      if (!useViewer.getState().focusedUnitId) return
+      if (state.phase !== 'structure' || state.structureLayer !== 'zones') {
+        leaveUnitFocus({ keepLayer: true })
+      }
+    })
+    const unsubscribeScene = useScene.subscribe((state, prev) => {
+      if (state.nodes === prev.nodes) return
+      const unitId = useViewer.getState().focusedUnitId
+      if (unitId && state.nodes[unitId]?.type !== 'unit') leaveUnitFocus()
+    })
+    return () => {
+      unsubscribeViewer()
+      unsubscribeEditor()
+      unsubscribeScene()
+      for (const pending of pendingPaints.values()) clearTimeout(pending)
+      pendingPaints.clear()
+    }
+  }, [])
+}

package/src/lib/usdz-export.ts

@@ -1,13 +1,19 @@
 import type { AnyNode } from '@pascal-app/core'
 import type { Object3D } from 'three'
 import { USDZExporter } from 'three/examples/jsm/exporters/USDZExporter.js'
-import * as WebGPUTextureUtils from 'three/examples/jsm/utils/WebGPUTextureUtils.js'
-import { type GlbExportOptions, preparePortableSceneFromViewer } from './glb-export'
+import { createExportTextureUtils } from './export-texture-utils'
+import {
+  DEFAULT_MODEL_EXPORT_TIMEOUT_MS,
+  type GlbExport,
+  type GlbExportOptions,
+  preparePortableSceneFromViewer,
+  withExportDeadline,
+} from './glb-export'
 import { createUsdzScene, disposeExportResources } from './portable-export'
 
 export type UsdzExportOptions = Pick<
   GlbExportOptions,
-  'excludedNodeTypes' | 'includedPresentationIds' | 'onlyVisible' | 'onWarning'
+  'excludedNodeTypes' | 'includedPresentationIds' | 'onlyVisible' | 'onWarning' | 'timeoutMs'
 >
 
 /** Export a native, self-contained USDZ with no glTF conversion fallback. */
@@ -16,23 +22,44 @@ export async function exportSceneToUsdz(
   nodes: Record<string, AnyNode>,
   options: UsdzExportOptions = {},
 ): Promise<Uint8Array<ArrayBuffer>> {
-  const prepared = await preparePortableSceneFromViewer(sceneGroup, nodes, {
+  const textureUtils = createExportTextureUtils()
+  const preparation = preparePortableSceneFromViewer(sceneGroup, nodes, {
     ...options,
     textures: 'embed',
+    animations: 'none',
+    textureUtils,
   })
-  for (const warning of prepared.warnings) options.onWarning?.(warning)
-
-  let scene: Object3D | null = null
+  // Assigned inside the raced closure, so plain `let`s narrow to `never` in
+  // the `finally`.
+  const run: { prepared: GlbExport | null; scene: Object3D | null; abandoned: boolean } = {
+    prepared: null,
+    scene: null,
+    abandoned: false,
+  }
   try {
-    scene = createUsdzScene(prepared.scene)
-    const exporter = new USDZExporter()
-    exporter.textureUtils = WebGPUTextureUtils
-    return await exporter.parseAsync(scene, {
-      onlyVisible: options.onlyVisible ?? true,
-      quickLookCompatible: true,
-    })
+    return await withExportDeadline(
+      (async () => {
+        run.prepared = await preparation
+        if (run.abandoned) throw new Error('USDZ export abandoned')
+        for (const warning of run.prepared.warnings) options.onWarning?.(warning)
+        run.scene = createUsdzScene(run.prepared.scene)
+        const exporter = new USDZExporter()
+        exporter.textureUtils = textureUtils as unknown as USDZExporter['textureUtils']
+        return exporter.parseAsync(run.scene, {
+          onlyVisible: options.onlyVisible ?? true,
+          quickLookCompatible: true,
+        })
+      })(),
+      options.timeoutMs ?? DEFAULT_MODEL_EXPORT_TIMEOUT_MS,
+      'USDZ',
+      () => {
+        run.abandoned = true
+      },
+    )
   } finally {
-    if (scene) disposeExportResources(scene, { textures: false })
-    prepared.dispose()
+    if (run.scene) disposeExportResources(run.scene, { textures: false })
+    if (run.prepared) run.prepared.dispose()
+    else preparation.then((late) => late.dispose()).catch(() => {})
+    await textureUtils.dispose()
   }
 }