@pascal-app/editor 1.0.0-beta.5 → 1.0.0

package/src/lib/local-project-presentation-persistence.test.ts

@@ -0,0 +1,302 @@
+import { describe, expect, test } from 'bun:test'
+import type {
+  ViewerPresentationConfiguration,
+  ViewerPresentationContribution,
+} from '@pascal-app/viewer'
+import {
+  createLocalProjectPresentationPersistence,
+  getLocalProjectPresentationStorageKey,
+} from './local-project-presentation-persistence'
+
+const CONTRIBUTION_ID = 'test:environment:presentation'
+
+type TestSnapshot = {
+  version: 1
+  value: string
+}
+
+class MemoryStorage {
+  readonly values = new Map<string, string>()
+
+  getItem(key: string): string | null {
+    return this.values.get(key) ?? null
+  }
+
+  setItem(key: string, value: string): void {
+    this.values.set(key, value)
+  }
+}
+
+class TestConfiguration implements ViewerPresentationConfiguration {
+  private readonly listeners = new Set<() => void>()
+  value = 'default'
+
+  getSnapshot = (): TestSnapshot => ({ version: 1, value: this.value })
+
+  restore = (snapshot: unknown): void => {
+    if (
+      typeof snapshot !== 'object' ||
+      snapshot === null ||
+      !('version' in snapshot) ||
+      snapshot.version !== 1 ||
+      !('value' in snapshot) ||
+      typeof snapshot.value !== 'string'
+    ) {
+      throw new Error('Invalid test presentation snapshot')
+    }
+    this.value = snapshot.value
+  }
+
+  reset = (): void => {
+    this.value = 'default'
+  }
+
+  subscribe = (onChange: () => void): (() => void) => {
+    this.listeners.add(onChange)
+    return () => this.listeners.delete(onChange)
+  }
+
+  setValue(value: string): void {
+    this.value = value
+    for (const listener of this.listeners) listener()
+  }
+}
+
+class TestRegistry {
+  private readonly listeners = new Set<() => void>()
+  private contributions: ViewerPresentationContribution[] = []
+
+  getSnapshot = (): readonly ViewerPresentationContribution[] => this.contributions
+
+  subscribe = (onChange: () => void): (() => void) => {
+    this.listeners.add(onChange)
+    return () => this.listeners.delete(onChange)
+  }
+
+  register(configuration: ViewerPresentationConfiguration): void {
+    this.contributions = [
+      {
+        id: CONTRIBUTION_ID,
+        component: async () => ({ default: () => null }),
+        configuration,
+      },
+    ]
+    for (const listener of this.listeners) listener()
+  }
+
+  uninstall(): void {
+    this.contributions = []
+    for (const listener of this.listeners) listener()
+  }
+}
+
+function readStoredValue(storage: MemoryStorage, projectId: string): string {
+  const raw = storage.getItem(getLocalProjectPresentationStorageKey(projectId))
+  if (!raw) throw new Error(`Missing presentation sidecar for ${projectId}`)
+  const sidecar = JSON.parse(raw) as {
+    contributions: Record<string, TestSnapshot>
+  }
+  const snapshot = sidecar.contributions[CONTRIBUTION_ID]
+  if (!snapshot) throw new Error(`Missing ${CONTRIBUTION_ID} snapshot`)
+  return snapshot.value
+}
+
+describe('local project presentation persistence', () => {
+  test('persists anonymous settings when assigning a new first project id', () => {
+    const storage = new MemoryStorage()
+    const registry = new TestRegistry()
+    const configuration = new TestConfiguration()
+    registry.register(configuration)
+    const persistence = createLocalProjectPresentationPersistence({
+      registry,
+      storage,
+      pageHideTarget: null,
+      flushDelayMs: 60_000,
+    })
+
+    persistence.switchProject(null)
+    configuration.setValue('anonymous atmosphere')
+    persistence.switchProject('first-project')
+
+    expect(configuration.value).toBe('anonymous atmosphere')
+    persistence.flush()
+    expect(readStoredValue(storage, 'first-project')).toBe('anonymous atmosphere')
+    persistence.dispose()
+
+    const reloadedRegistry = new TestRegistry()
+    const reloadedConfiguration = new TestConfiguration()
+    reloadedRegistry.register(reloadedConfiguration)
+    const reloadedPersistence = createLocalProjectPresentationPersistence({
+      registry: reloadedRegistry,
+      storage,
+      pageHideTarget: null,
+    })
+    reloadedPersistence.switchProject('first-project')
+
+    expect(reloadedConfiguration.value).toBe('anonymous atmosphere')
+    reloadedPersistence.dispose()
+  })
+
+  test('restores a stored project instead of overwriting it with anonymous settings', () => {
+    const storage = new MemoryStorage()
+    const storedRegistry = new TestRegistry()
+    const storedConfiguration = new TestConfiguration()
+    storedRegistry.register(storedConfiguration)
+    const storedPersistence = createLocalProjectPresentationPersistence({
+      registry: storedRegistry,
+      storage,
+      pageHideTarget: null,
+      flushDelayMs: 60_000,
+    })
+    storedPersistence.switchProject('existing-project')
+    storedConfiguration.setValue('stored atmosphere')
+    storedPersistence.flush()
+    storedPersistence.dispose()
+
+    const registry = new TestRegistry()
+    const configuration = new TestConfiguration()
+    registry.register(configuration)
+    const persistence = createLocalProjectPresentationPersistence({
+      registry,
+      storage,
+      pageHideTarget: null,
+      flushDelayMs: 60_000,
+    })
+    persistence.switchProject(null)
+    configuration.setValue('anonymous atmosphere')
+    persistence.switchProject('existing-project')
+
+    expect(configuration.value).toBe('stored atmosphere')
+    persistence.flush()
+    expect(readStoredValue(storage, 'existing-project')).toBe('stored atmosphere')
+    persistence.dispose()
+  })
+
+  test('flushes the old project before restoring defaults or the next project', () => {
+    const storage = new MemoryStorage()
+    const registry = new TestRegistry()
+    const configuration = new TestConfiguration()
+    registry.register(configuration)
+    const persistence = createLocalProjectPresentationPersistence({
+      registry,
+      storage,
+      pageHideTarget: null,
+      flushDelayMs: 60_000,
+    })
+
+    persistence.switchProject('project-a')
+    configuration.setValue('project A atmosphere')
+    persistence.switchProject('project-b')
+
+    expect(readStoredValue(storage, 'project-a')).toBe('project A atmosphere')
+    expect(configuration.value).toBe('default')
+
+    configuration.setValue('project B atmosphere')
+    persistence.switchProject('project-a')
+
+    expect(readStoredValue(storage, 'project-b')).toBe('project B atmosphere')
+    expect(configuration.value).toBe('project A atmosphere')
+    persistence.dispose()
+  })
+
+  test('restores a project after reload and flushes pending changes on dispose', () => {
+    const storage = new MemoryStorage()
+    const firstRegistry = new TestRegistry()
+    const firstConfiguration = new TestConfiguration()
+    firstRegistry.register(firstConfiguration)
+    const firstPersistence = createLocalProjectPresentationPersistence({
+      registry: firstRegistry,
+      storage,
+      pageHideTarget: null,
+      flushDelayMs: 60_000,
+    })
+
+    firstPersistence.switchProject('reloadable')
+    firstConfiguration.setValue('saved sky')
+    firstPersistence.dispose()
+
+    const reloadedRegistry = new TestRegistry()
+    const reloadedConfiguration = new TestConfiguration()
+    reloadedRegistry.register(reloadedConfiguration)
+    const reloadedPersistence = createLocalProjectPresentationPersistence({
+      registry: reloadedRegistry,
+      storage,
+      pageHideTarget: null,
+    })
+    reloadedPersistence.switchProject('reloadable')
+
+    expect(reloadedConfiguration.value).toBe('saved sky')
+    reloadedPersistence.dispose()
+  })
+
+  test('recovers corrupted presentation data without touching scene storage', () => {
+    const storage = new MemoryStorage()
+    const sceneStorageKey = 'pascal-editor-scene'
+    const sceneData = '{"nodes":{"site":{"type":"site"}}}'
+    storage.setItem(sceneStorageKey, sceneData)
+    storage.setItem(getLocalProjectPresentationStorageKey('corrupted'), '{not-json')
+
+    const registry = new TestRegistry()
+    const configuration = new TestConfiguration()
+    configuration.value = 'leaked from another project'
+    registry.register(configuration)
+    const persistence = createLocalProjectPresentationPersistence({
+      registry,
+      storage,
+      pageHideTarget: null,
+      flushDelayMs: 60_000,
+    })
+
+    persistence.switchProject('corrupted')
+    expect(configuration.value).toBe('default')
+    persistence.flush()
+
+    expect(readStoredValue(storage, 'corrupted')).toBe('default')
+    expect(storage.getItem(sceneStorageKey)).toBe(sceneData)
+    persistence.dispose()
+  })
+
+  test('retains configuration while a contribution is unregistered and registered again', () => {
+    const storage = new MemoryStorage()
+    const registry = new TestRegistry()
+    const firstConfiguration = new TestConfiguration()
+    registry.register(firstConfiguration)
+    const persistence = createLocalProjectPresentationPersistence({
+      registry,
+      storage,
+      pageHideTarget: null,
+      flushDelayMs: 60_000,
+    })
+
+    persistence.switchProject('plugin-cycle')
+    firstConfiguration.setValue('retained atmosphere')
+    registry.uninstall()
+
+    const reinstalledConfiguration = new TestConfiguration()
+    registry.register(reinstalledConfiguration)
+
+    expect(reinstalledConfiguration.value).toBe('retained atmosphere')
+    persistence.dispose()
+  })
+
+  test('flushes pending changes on pagehide', () => {
+    const storage = new MemoryStorage()
+    const registry = new TestRegistry()
+    const configuration = new TestConfiguration()
+    const pageHideTarget = new EventTarget()
+    registry.register(configuration)
+    const persistence = createLocalProjectPresentationPersistence({
+      registry,
+      storage,
+      pageHideTarget,
+      flushDelayMs: 60_000,
+    })
+
+    persistence.switchProject('pagehide')
+    configuration.setValue('last slider value')
+    pageHideTarget.dispatchEvent(new Event('pagehide'))
+
+    expect(readStoredValue(storage, 'pagehide')).toBe('last slider value')
+    persistence.dispose()
+  })
+})

package/src/lib/local-project-presentation-persistence.ts

@@ -0,0 +1,335 @@
+'use client'
+
+import { type ViewerPresentationContribution, viewerPresentationRegistry } from '@pascal-app/viewer'
+import { z } from 'zod'
+
+export const LOCAL_PROJECT_PRESENTATION_STORAGE_KEY_PREFIX = 'pascal:project-presentation:v1:'
+const LOCAL_PROJECT_PRESENTATION_VERSION = 1 as const
+const DEFAULT_FLUSH_DELAY_MS = 250
+
+type PresentationConfiguration = NonNullable<ViewerPresentationContribution['configuration']>
+
+type PresentationRegistry = {
+  getSnapshot: () => readonly ViewerPresentationContribution[]
+  subscribe: (onChange: () => void) => () => void
+}
+
+type PresentationStorage = {
+  getItem: (key: string) => string | null
+  setItem: (key: string, value: string) => void
+}
+
+type PageHideTarget = Pick<EventTarget, 'addEventListener' | 'removeEventListener'>
+
+const LocalProjectPresentationSidecarSchema = z
+  .object({
+    version: z.literal(LOCAL_PROJECT_PRESENTATION_VERSION),
+    projectId: z.string(),
+    contributions: z.record(z.string(), z.unknown()),
+  })
+  .strict()
+type LocalProjectPresentationSidecar = z.infer<typeof LocalProjectPresentationSidecarSchema>
+
+type StoredSidecar = {
+  contributions: Record<string, unknown>
+  malformed: boolean
+  source: 'missing' | 'stored' | 'unavailable'
+}
+
+export type LocalProjectPresentationPersistence = {
+  switchProject: (projectId: string | null) => void
+  flush: () => void
+  dispose: () => void
+}
+
+export type LocalProjectPresentationPersistenceOptions = {
+  registry?: PresentationRegistry
+  storage?: PresentationStorage | null
+  pageHideTarget?: PageHideTarget | null
+  flushDelayMs?: number
+}
+
+export function getLocalProjectPresentationStorageKey(projectId: string): string {
+  return `${LOCAL_PROJECT_PRESENTATION_STORAGE_KEY_PREFIX}${encodeURIComponent(projectId)}`
+}
+
+function emptyContributions(): Record<string, unknown> {
+  return Object.create(null) as Record<string, unknown>
+}
+
+function getBrowserStorage(): PresentationStorage | null {
+  if (typeof window === 'undefined') return null
+  try {
+    return window.localStorage
+  } catch {
+    return null
+  }
+}
+
+function readSidecar(storage: PresentationStorage | null, projectId: string): StoredSidecar {
+  if (!storage) {
+    return {
+      contributions: emptyContributions(),
+      malformed: false,
+      source: 'unavailable',
+    }
+  }
+
+  let raw: string | null
+  try {
+    raw = storage.getItem(getLocalProjectPresentationStorageKey(projectId))
+  } catch {
+    return {
+      contributions: emptyContributions(),
+      malformed: false,
+      source: 'unavailable',
+    }
+  }
+  if (raw === null) {
+    return {
+      contributions: emptyContributions(),
+      malformed: false,
+      source: 'missing',
+    }
+  }
+
+  try {
+    const parsed = LocalProjectPresentationSidecarSchema.safeParse(JSON.parse(raw))
+    if (!parsed.success || parsed.data.projectId !== projectId) {
+      return {
+        contributions: emptyContributions(),
+        malformed: true,
+        source: 'stored',
+      }
+    }
+    return {
+      contributions: Object.assign(emptyContributions(), parsed.data.contributions),
+      malformed: false,
+      source: 'stored',
+    }
+  } catch {
+    return {
+      contributions: emptyContributions(),
+      malformed: true,
+      source: 'stored',
+    }
+  }
+}
+
+class LocalProjectPresentationPersistenceImpl implements LocalProjectPresentationPersistence {
+  private projectId: string | null = null
+  private projectInitialized = false
+  private contributions = emptyContributions()
+  private readonly configurations = new Map<
+    string,
+    { configuration: PresentationConfiguration; unsubscribe: () => void }
+  >()
+  private readonly initializedConfigurationIds = new Set<string>()
+  private readonly registry: PresentationRegistry
+  private readonly storage: PresentationStorage | null
+  private readonly pageHideTarget: PageHideTarget | null
+  private readonly flushDelayMs: number
+  private readonly unsubscribeRegistry: () => void
+  private flushTimer: ReturnType<typeof setTimeout> | undefined
+  private dirty = false
+  private suppressWrites = false
+  private disposed = false
+
+  constructor(options: LocalProjectPresentationPersistenceOptions) {
+    this.registry = options.registry ?? viewerPresentationRegistry
+    this.storage = options.storage === undefined ? getBrowserStorage() : options.storage
+    this.pageHideTarget =
+      options.pageHideTarget === undefined
+        ? typeof window === 'undefined'
+          ? null
+          : window
+        : options.pageHideTarget
+    this.flushDelayMs = options.flushDelayMs ?? DEFAULT_FLUSH_DELAY_MS
+    this.unsubscribeRegistry = this.registry.subscribe(this.reconcileRegistry)
+    this.pageHideTarget?.addEventListener('pagehide', this.flushOnPageHide)
+    this.reconcileRegistry()
+  }
+
+  switchProject(projectId: string | null): void {
+    const nextProjectId = projectId && projectId.length > 0 ? projectId : null
+    if (this.projectInitialized && nextProjectId === this.projectId) return
+
+    const assigningAnonymousPresentation =
+      this.projectInitialized && this.projectId === null && nextProjectId !== null
+
+    this.flush()
+    this.projectId = nextProjectId
+    this.projectInitialized = true
+    this.initializedConfigurationIds.clear()
+
+    const stored = nextProjectId
+      ? readSidecar(this.storage, nextProjectId)
+      : {
+          contributions: emptyContributions(),
+          malformed: false,
+          source: 'missing' as const,
+        }
+    this.contributions = stored.contributions
+
+    if (assigningAnonymousPresentation && stored.source === 'missing') {
+      let capturedConfiguration = false
+      for (const [id, entry] of this.configurations) {
+        this.initializedConfigurationIds.add(id)
+        try {
+          this.contributions[id] = entry.configuration.getSnapshot()
+          capturedConfiguration = true
+        } catch {
+          // Leave the live configuration intact when an optional adapter cannot export.
+        }
+      }
+      if (capturedConfiguration) this.markDirty()
+      return
+    }
+
+    let recoveredInvalidConfiguration = stored.malformed
+    for (const [id, entry] of this.configurations) {
+      if (!this.restoreConfiguration(id, entry.configuration)) {
+        recoveredInvalidConfiguration = true
+      }
+    }
+
+    if (recoveredInvalidConfiguration) this.markDirty()
+  }
+
+  flush = (): void => {
+    if (this.flushTimer !== undefined) {
+      clearTimeout(this.flushTimer)
+      this.flushTimer = undefined
+    }
+    const projectId = this.projectId
+    if (!this.dirty || !projectId || !this.storage) return
+
+    const contributions = Object.assign(emptyContributions(), this.contributions)
+    for (const [id, entry] of this.configurations) {
+      if (!this.initializedConfigurationIds.has(id)) continue
+      try {
+        contributions[id] = entry.configuration.getSnapshot()
+      } catch {
+        // Retain the last valid snapshot when one contribution cannot export.
+      }
+    }
+
+    const sidecar: LocalProjectPresentationSidecar = {
+      version: LOCAL_PROJECT_PRESENTATION_VERSION,
+      projectId,
+      contributions,
+    }
+    try {
+      this.storage.setItem(
+        getLocalProjectPresentationStorageKey(projectId),
+        JSON.stringify(sidecar),
+      )
+      this.contributions = contributions
+      this.dirty = false
+    } catch {
+      // Storage denial, quota exhaustion, and non-serializable plugin data are non-fatal.
+    }
+  }
+
+  dispose(): void {
+    if (this.disposed) return
+    this.disposed = true
+    this.flush()
+    this.unsubscribeRegistry()
+    this.pageHideTarget?.removeEventListener('pagehide', this.flushOnPageHide)
+    for (const entry of this.configurations.values()) entry.unsubscribe()
+    this.configurations.clear()
+    this.initializedConfigurationIds.clear()
+  }
+
+  private readonly flushOnPageHide = (): void => {
+    this.flush()
+  }
+
+  private readonly reconcileRegistry = (): void => {
+    if (this.disposed) return
+
+    const current = new Map<string, PresentationConfiguration>()
+    for (const contribution of this.registry.getSnapshot()) {
+      if (contribution.configuration) {
+        current.set(contribution.id, contribution.configuration)
+      }
+    }
+
+    for (const [id, entry] of this.configurations) {
+      if (current.get(id) === entry.configuration) continue
+      if (this.initializedConfigurationIds.has(id)) {
+        this.captureConfiguration(id, entry.configuration)
+      }
+      entry.unsubscribe()
+      this.configurations.delete(id)
+      this.initializedConfigurationIds.delete(id)
+    }
+
+    for (const [id, configuration] of current) {
+      if (this.configurations.has(id)) continue
+
+      let unsubscribe: () => void = () => undefined
+      try {
+        unsubscribe = configuration.subscribe(() => {
+          if (!this.suppressWrites) this.markDirty()
+        })
+      } catch {
+        // A broken optional adapter must not affect the editor or other contributions.
+      }
+      this.configurations.set(id, { configuration, unsubscribe })
+
+      if (this.projectInitialized && !this.restoreConfiguration(id, configuration)) {
+        this.markDirty()
+      }
+    }
+  }
+
+  private restoreConfiguration(id: string, configuration: PresentationConfiguration): boolean {
+    let valid = true
+    this.suppressWrites = true
+    try {
+      if (Object.hasOwn(this.contributions, id)) {
+        try {
+          configuration.restore(this.contributions[id])
+        } catch {
+          valid = false
+          delete this.contributions[id]
+          try {
+            configuration.reset()
+          } catch {}
+        }
+      } else {
+        try {
+          configuration.reset()
+        } catch {}
+      }
+    } finally {
+      this.suppressWrites = false
+      this.initializedConfigurationIds.add(id)
+    }
+    return valid
+  }
+
+  private captureConfiguration(id: string, configuration: PresentationConfiguration): void {
+    try {
+      this.contributions[id] = configuration.getSnapshot()
+      this.markDirty()
+    } catch {
+      // Preserve the prior snapshot if the retiring adapter cannot export.
+    }
+  }
+
+  private markDirty(): void {
+    if (!this.projectId || this.suppressWrites || this.disposed) return
+    this.dirty = true
+    if (this.flushTimer !== undefined) clearTimeout(this.flushTimer)
+    this.flushTimer = setTimeout(this.flush, this.flushDelayMs)
+  }
+}
+
+export function createLocalProjectPresentationPersistence(
+  options: LocalProjectPresentationPersistenceOptions = {},
+): LocalProjectPresentationPersistence {
+  return new LocalProjectPresentationPersistenceImpl(options)
+}

package/src/lib/material-paint.ts

@@ -47,6 +47,8 @@ export type PaintableMaterialTarget =
       | 'turbine-vent'
       | 'cupola'
       | 'eyebrow-vent'
+      | 'gutter'
+      | 'downspout'
     >
   | 'item'
 

package/src/lib/model-export.ts

@@ -0,0 +1,29 @@
+import type { GlbExportOptions } from './glb-export'
+
+export type ModelExportFormat = 'glb' | 'usdz' | 'stl' | 'obj' | 'print-stl' | 'print-3mf'
+
+export type ModelExportOptions = Pick<
+  GlbExportOptions,
+  'onlyVisible' | 'excludedNodeTypes' | 'includedPresentationIds'
+> & {
+  download?: boolean
+  printScale?: number
+  printScope?: 'whole' | 'levels'
+  printContent?: 'structure' | 'everything'
+  printBase?: 'none' | 'plinth'
+  printMinimumFeatureMm?: number
+  printPlinthMarginMm?: number
+  printPlinthThicknessMm?: number
+}
+
+export type ModelExportArtifact = {
+  blob: Blob
+  filename: string
+  metadata?: unknown
+  warnings?: readonly string[]
+}
+
+export type ModelExport = (
+  format?: ModelExportFormat,
+  options?: ModelExportOptions,
+) => Promise<ModelExportArtifact | null>