@pascal-app/editor 1.0.4 → 1.0.5

package/src/store/use-audio.test.ts

@@ -0,0 +1,146 @@
+import { afterAll, beforeEach, describe, expect, test } from 'bun:test'
+import useAudio, { AUDIO_MUTED_STORAGE_KEY, AUDIO_SETTINGS_STORAGE_KEY } from './use-audio'
+
+function memoryStorage() {
+  const items = new Map<string, string>()
+  return {
+    items,
+    getItem: (key: string) => items.get(key) ?? null,
+    setItem: (key: string, value: string) => void items.set(key, value),
+    removeItem: (key: string) => void items.delete(key),
+  }
+}
+
+const originals = {
+  localStorage: Object.getOwnPropertyDescriptor(globalThis, 'localStorage'),
+  sessionStorage: Object.getOwnPropertyDescriptor(globalThis, 'sessionStorage'),
+}
+
+function use(name: 'localStorage' | 'sessionStorage', storage: ReturnType<typeof memoryStorage>) {
+  Object.defineProperty(globalThis, name, { configurable: true, value: storage })
+}
+
+/** One browser profile: its tabs share `localStorage`, each has its own `sessionStorage`. */
+let browser = memoryStorage()
+
+/** Another tab of the profile saves the settings: the browser stores them and tells this tab. */
+function savedInAnotherTab(state: Record<string, unknown>) {
+  const value = JSON.stringify({ state, version: 0 })
+  browser.setItem(AUDIO_SETTINGS_STORAGE_KEY, value)
+  globalThis.dispatchEvent(
+    Object.assign(new Event('storage'), { key: AUDIO_SETTINGS_STORAGE_KEY, newValue: value }),
+  )
+}
+
+/** The editor loading in a tab: a new one, or the same one reloaded (its session kept). */
+async function loadIn(tab: ReturnType<typeof memoryStorage>) {
+  use('sessionStorage', tab)
+  await useAudio.persist.rehydrate()
+  return useAudio.getState()
+}
+
+beforeEach(() => {
+  browser = memoryStorage()
+  use('localStorage', browser)
+})
+
+afterAll(() => {
+  for (const [name, descriptor] of Object.entries(originals)) {
+    if (descriptor) Object.defineProperty(globalThis, name, descriptor)
+    else Reflect.deleteProperty(globalThis, name)
+  }
+})
+
+describe('muting a tab', () => {
+  test('a tab keeps its own mute across reloads, and a new tab starts from the last choice', async () => {
+    const first = memoryStorage()
+    const second = memoryStorage()
+
+    expect((await loadIn(first)).muted).toBe(false)
+    useAudio.getState().toggleMute()
+
+    expect((await loadIn(second)).muted).toBe(true)
+    useAudio.getState().setMuted(false)
+
+    expect((await loadIn(first)).muted).toBe(true)
+    expect((await loadIn(memoryStorage())).muted).toBe(false)
+  })
+
+  test("another tab's choice does not change a tab that never chose", async () => {
+    const quiet = memoryStorage()
+    expect((await loadIn(quiet)).muted).toBe(false)
+
+    await loadIn(memoryStorage())
+    useAudio.getState().setMuted(true)
+
+    expect((await loadIn(quiet)).muted).toBe(false)
+  })
+
+  test("volumes are every tab's and never carry a mute", async () => {
+    const muting = memoryStorage()
+    await loadIn(muting)
+    useAudio.getState().setMuted(true)
+
+    await loadIn(memoryStorage())
+    useAudio.getState().setMuted(false)
+    await loadIn(muting)
+    useAudio.getState().setSfxVolume(20)
+
+    expect(JSON.parse(browser.getItem(AUDIO_SETTINGS_STORAGE_KEY)!).state).not.toHaveProperty(
+      'muted',
+    )
+    expect(browser.getItem(AUDIO_MUTED_STORAGE_KEY)).toBe('false')
+    const next = await loadIn(memoryStorage())
+    expect(next.sfxVolume).toBe(20)
+    expect(next.muted).toBe(false)
+  })
+
+  test("a volume another tab sets reaches this one at once, and this tab's saves carry it", async () => {
+    await loadIn(memoryStorage())
+    useAudio.getState().setSfxVolume(30)
+    useAudio.getState().setRadioPlaying(true)
+    const stored = JSON.parse(browser.getItem(AUDIO_SETTINGS_STORAGE_KEY)!)
+
+    savedInAnotherTab({ ...stored.state, isRadioPlaying: false, muted: true, sfxVolume: 80 })
+
+    expect(useAudio.getState()).toMatchObject({ isRadioPlaying: true, muted: false, sfxVolume: 80 })
+    const setElsewhere = browser.getItem(AUDIO_SETTINGS_STORAGE_KEY)
+    useAudio.getState().setMuted(true)
+    expect(browser.getItem(AUDIO_SETTINGS_STORAGE_KEY)).toBe(setElsewhere)
+    // The radio pausing as the tab is hidden saves every setting: the other tab's volume stays.
+    useAudio.getState().setRadioPlaying(false)
+    useAudio.getState().setMasterVolume(60)
+    expect(JSON.parse(browser.getItem(AUDIO_SETTINGS_STORAGE_KEY)!).state).toMatchObject({
+      masterVolume: 60,
+      sfxVolume: 80,
+    })
+  })
+
+  test("a mute saved when it was every tab's still holds, in settings the old build still reads", async () => {
+    browser.setItem(
+      AUDIO_SETTINGS_STORAGE_KEY,
+      JSON.stringify({ state: { masterVolume: 40, muted: true, sfxVolume: 50 }, version: 0 }),
+    )
+
+    const state = await loadIn(memoryStorage())
+
+    expect(state.muted).toBe(true)
+    expect(state.masterVolume).toBe(40)
+    expect((await loadIn(memoryStorage())).muted).toBe(true)
+    useAudio.getState().setSfxVolume(45)
+    const saved = JSON.parse(browser.getItem(AUDIO_SETTINGS_STORAGE_KEY)!)
+    expect(saved).toMatchObject({ state: { masterVolume: 40, sfxVolume: 45 }, version: 0 })
+    expect(saved.state).not.toHaveProperty('muted')
+  })
+
+  test('a tab still on the old settings does not undo a choice made since', async () => {
+    await loadIn(memoryStorage())
+    useAudio.getState().setMuted(false)
+    browser.setItem(
+      AUDIO_SETTINGS_STORAGE_KEY,
+      JSON.stringify({ state: { muted: true, sfxVolume: 50 }, version: 0 }),
+    )
+
+    expect((await loadIn(memoryStorage())).muted).toBe(false)
+  })
+})

package/src/store/use-audio.tsx

@@ -1,13 +1,22 @@
 'use client'
 
 import { create } from 'zustand'
-import { persist } from 'zustand/middleware'
+import { createJSONStorage, persist } from 'zustand/middleware'
+
+export const AUDIO_SETTINGS_STORAGE_KEY = 'pascal-audio-settings'
+/**
+ * Mute is each tab's own, so someone working in two projects can silence one and hear the other.
+ * Under this key `sessionStorage` holds this tab's mute (kept across its reloads) and
+ * `localStorage` the last choice made in any tab, which a new tab starts from.
+ */
+export const AUDIO_MUTED_STORAGE_KEY = 'pascal-audio-muted'
 
 interface AudioState {
   masterVolume: number
   sfxVolume: number
   radioVolume: number
   isRadioPlaying: boolean
+  /** This tab's mute; the volumes are every tab's. */
   muted: boolean
   autoplay: boolean
   setMasterVolume: (v: number) => void
@@ -15,10 +24,73 @@ interface AudioState {
   setRadioVolume: (v: number) => void
   setRadioPlaying: (v: boolean) => void
   toggleRadioPlaying: () => void
+  setMuted: (muted: boolean) => void
   toggleMute: () => void
   setAutoplay: (v: boolean) => void
 }
 
+type StoredSettings = Pick<
+  AudioState,
+  'masterVolume' | 'sfxVolume' | 'radioVolume' | 'isRadioPlaying' | 'autoplay'
+>
+
+type BrowserStorage = 'localStorage' | 'sessionStorage'
+
+// Storage can be missing (a test, a server render) or refuse access (site data blocked): the page
+// then keeps its choices in memory only.
+function readStored(storage: BrowserStorage, key: string) {
+  try {
+    return globalThis[storage]?.getItem(key) ?? null
+  } catch {
+    return null
+  }
+}
+
+function writeStored(storage: BrowserStorage, key: string, value: string) {
+  try {
+    globalThis[storage]?.setItem(key, value)
+  } catch {}
+}
+
+/** This tab's mute. A tab without one takes the last choice made in any tab, and keeps it. */
+function tabMuted(): boolean {
+  const own = readStored('sessionStorage', AUDIO_MUTED_STORAGE_KEY)
+  if (own !== null) return own === 'true'
+  const muted = readStored('localStorage', AUDIO_MUTED_STORAGE_KEY) === 'true'
+  writeStored('sessionStorage', AUDIO_MUTED_STORAGE_KEY, String(muted))
+  return muted
+}
+
+/** A mute chosen in this tab: this tab's, and where the next new tab starts. Open tabs keep theirs. */
+function chooseMuted(muted: boolean) {
+  writeStored('sessionStorage', AUDIO_MUTED_STORAGE_KEY, String(muted))
+  writeStored('localStorage', AUDIO_MUTED_STORAGE_KEY, String(muted))
+  return { muted }
+}
+
+// The settings as this tab last read, wrote or took from another tab. A save carries every
+// setting, so a save that changes none (a mute, which is this tab's own) is skipped.
+let heldSettings: string | null = null
+// Set while this tab takes another tab's volumes: that is no choice of its own to save back.
+let adopting = false
+
+const settingsStorage = createJSONStorage<StoredSettings>(() => ({
+  getItem: (key) => {
+    heldSettings = readStored('localStorage', key)
+    return heldSettings
+  },
+  setItem: (key, value) => {
+    if (value === heldSettings) return
+    heldSettings = value
+    if (!adopting) writeStored('localStorage', key, value)
+  },
+  removeItem: (key) => {
+    try {
+      globalThis.localStorage?.removeItem(key)
+    } catch {}
+  },
+}))
+
 const useAudio = create<AudioState>()(
   persist(
     (set) => ({
@@ -33,13 +105,65 @@ const useAudio = create<AudioState>()(
       setRadioVolume: (v) => set({ radioVolume: v }),
       setRadioPlaying: (v) => set({ isRadioPlaying: v }),
       toggleRadioPlaying: () => set((state) => ({ isRadioPlaying: !state.isRadioPlaying })),
-      toggleMute: () => set((state) => ({ muted: !state.muted })),
+      setMuted: (muted) => set(chooseMuted(muted)),
+      toggleMute: () => set((state) => chooseMuted(!state.muted)),
       setAutoplay: (v) => set({ autoplay: v }),
     }),
     {
-      name: 'pascal-audio-settings',
+      name: AUDIO_SETTINGS_STORAGE_KEY,
+      storage: settingsStorage,
+      partialize: ({ masterVolume, sfxVolume, radioVolume, isRadioPlaying, autoplay }) => ({
+        masterVolume,
+        sfxVolume,
+        radioVolume,
+        isRadioPlaying,
+        autoplay,
+      }),
+      // The settings once held one mute for every tab: whoever had muted stays muted, unless a tab
+      // has chosen since (a tab still on that build can write it again). The format is unchanged,
+      // so that build reads these settings back with only the mute gone.
+      merge: (persisted, current) => {
+        const { muted, ...settings } = (persisted ?? {}) as Partial<StoredSettings> & {
+          muted?: unknown
+        }
+        if (
+          typeof muted === 'boolean' &&
+          readStored('localStorage', AUDIO_MUTED_STORAGE_KEY) === null
+        ) {
+          writeStored('localStorage', AUDIO_MUTED_STORAGE_KEY, String(muted))
+        }
+        return { ...current, ...settings, muted: tabMuted() }
+      },
     },
   ),
 )
 
+/**
+ * Another tab saved the settings: the volumes are every tab's, so this tab takes them at once, and
+ * a later save of its own carries them. Its mute and whether its radio plays stay its own.
+ */
+function adoptOtherTabSettings(event: StorageEvent) {
+  if (event.key !== AUDIO_SETTINGS_STORAGE_KEY || event.newValue === null) return
+  let stored: Partial<Record<keyof StoredSettings, unknown>> | undefined
+  try {
+    stored = JSON.parse(event.newValue)?.state
+  } catch {
+    return
+  }
+  const shared: Partial<StoredSettings> = {}
+  for (const key of ['masterVolume', 'sfxVolume', 'radioVolume'] as const) {
+    const value = stored?.[key]
+    if (typeof value === 'number') shared[key] = value
+  }
+  if (typeof stored?.autoplay === 'boolean') shared.autoplay = stored.autoplay
+  adopting = true
+  try {
+    useAudio.setState(shared)
+  } finally {
+    adopting = false
+  }
+}
+
+globalThis.addEventListener?.('storage', adoptOtherTabSettings)
+
 export default useAudio

package/src/store/use-construction-reveal.test.ts

@@ -0,0 +1,173 @@
+import { afterAll, afterEach, beforeAll, describe, expect, test } from 'bun:test'
+import type { AnyNodeDefinition } from '@pascal-app/core'
+import { BaseNode, loadPlugin, nodeRegistry, nodeType, objectId, useScene } from '@pascal-app/core'
+import { ANIMATION_SPEEDS } from '@pascal-app/viewer'
+import { createJSONStorage } from 'zustand/middleware'
+import useConstructionReveal, {
+  CONSTRUCTION_REVEAL_LEVELS,
+  CONSTRUCTION_REVEAL_STORAGE_KEY,
+  FRAMING_KIND,
+  getConstructionRevealLevel,
+  isFramingAvailable,
+  resolveConstructionLevel,
+} from './use-construction-reveal'
+
+function memoryStorage() {
+  const items = new Map<string, string>()
+  return {
+    items,
+    storage: createJSONStorage(() => ({
+      getItem: (key: string) => items.get(key) ?? null,
+      setItem: (key: string, value: string) => void items.set(key, value),
+      removeItem: (key: string) => void items.delete(key),
+    })),
+  }
+}
+
+afterEach(() => {
+  useConstructionReveal.setState({ level: 'full', chosen: false, speed: 1 })
+})
+
+describe('the construction animation preference', () => {
+  test('starts at full, with no choice of the person’s own, and offers four levels', () => {
+    expect(useConstructionReveal.getState().level).toBe('full')
+    expect(useConstructionReveal.getState().chosen).toBe(false)
+    expect(CONSTRUCTION_REVEAL_LEVELS).toEqual(['off', 'simple', 'full', 'framing'])
+  })
+
+  test('persists the chosen level and the speed under its own key', () => {
+    const { items, storage } = memoryStorage()
+    useConstructionReveal.persist.setOptions({ storage })
+    useConstructionReveal.getState().setLevel('simple')
+    expect(JSON.parse(items.get(CONSTRUCTION_REVEAL_STORAGE_KEY)!).state).toEqual({
+      level: 'simple',
+      chosen: true,
+      speed: 1,
+    })
+    expect(CONSTRUCTION_REVEAL_STORAGE_KEY).not.toBe('pascal-audio-settings')
+  })
+
+  test('restores a saved level, and an unknown one falls back to full', async () => {
+    const { items, storage } = memoryStorage()
+    useConstructionReveal.persist.setOptions({ storage })
+    items.set(CONSTRUCTION_REVEAL_STORAGE_KEY, JSON.stringify({ state: { level: 'off' } }))
+    await useConstructionReveal.persist.rehydrate()
+    expect(useConstructionReveal.getState().level).toBe('off')
+
+    items.set(CONSTRUCTION_REVEAL_STORAGE_KEY, JSON.stringify({ state: { level: 'cinematic' } }))
+    await useConstructionReveal.persist.rehydrate()
+    expect(useConstructionReveal.getState().level).toBe('full')
+  })
+})
+
+describe('the animation speed preference', () => {
+  test('starts at ×1', () => {
+    expect(useConstructionReveal.getState().speed).toBe(1)
+  })
+
+  test.each([...ANIMATION_SPEEDS])('×%d persists and reloads', async (speed) => {
+    const { items, storage } = memoryStorage()
+    useConstructionReveal.persist.setOptions({ storage })
+    useConstructionReveal.getState().setSpeed(speed)
+    const saved = items.get(CONSTRUCTION_REVEAL_STORAGE_KEY)!
+    expect(JSON.parse(saved).state.speed).toBe(speed)
+    // A new page: the store starts from its defaults and reads what was saved.
+    useConstructionReveal.setState({ speed: 1 })
+    items.set(CONSTRUCTION_REVEAL_STORAGE_KEY, saved)
+    await useConstructionReveal.persist.rehydrate()
+    expect(useConstructionReveal.getState().speed).toBe(speed)
+  })
+
+  test('a person saved before the setting is at ×1, and a stray value snaps to a step', async () => {
+    const { items, storage } = memoryStorage()
+    useConstructionReveal.persist.setOptions({ storage })
+    items.set(CONSTRUCTION_REVEAL_STORAGE_KEY, JSON.stringify({ state: { level: 'full' } }))
+    await useConstructionReveal.persist.rehydrate()
+    expect(useConstructionReveal.getState().speed).toBe(1)
+    items.set(CONSTRUCTION_REVEAL_STORAGE_KEY, JSON.stringify({ state: { speed: 1.6 } }))
+    await useConstructionReveal.persist.rehydrate()
+    expect(useConstructionReveal.getState().speed).toBe(1.5)
+    items.set(CONSTRUCTION_REVEAL_STORAGE_KEY, JSON.stringify({ state: { speed: 'fast' } }))
+    await useConstructionReveal.persist.rehydrate()
+    expect(useConstructionReveal.getState().speed).toBe(1)
+  })
+})
+
+describe('the level that plays follows the project', () => {
+  const none = { level: 'full', chosen: false } as const
+
+  test('with no choice of the person’s own: Framing with the framing plugin, Full without', () => {
+    expect(resolveConstructionLevel(none, true)).toBe('framing')
+    expect(resolveConstructionLevel(none, false)).toBe('full')
+  })
+
+  test('a choice is kept while the plugin stays installed', () => {
+    for (const level of CONSTRUCTION_REVEAL_LEVELS)
+      expect(resolveConstructionLevel({ level, chosen: true }, true)).toBe(level)
+  })
+
+  test('without the plugin Framing falls back to Full; every other choice stays', () => {
+    expect(resolveConstructionLevel({ level: 'framing', chosen: true }, false)).toBe('full')
+    expect(resolveConstructionLevel({ level: 'off', chosen: true }, false)).toBe('off')
+    expect(resolveConstructionLevel({ level: 'simple', chosen: true }, false)).toBe('simple')
+    // The saved choice is not erased: the plugin coming back brings Framing back.
+    expect(resolveConstructionLevel({ level: 'framing', chosen: true }, true)).toBe('framing')
+  })
+
+  test('a level saved before the default followed the project is a choice', async () => {
+    const { items, storage } = memoryStorage()
+    useConstructionReveal.persist.setOptions({ storage })
+    items.set(CONSTRUCTION_REVEAL_STORAGE_KEY, JSON.stringify({ state: { level: 'full' } }))
+    await useConstructionReveal.persist.rehydrate()
+    expect(useConstructionReveal.getState().chosen).toBe(true)
+    items.set(CONSTRUCTION_REVEAL_STORAGE_KEY, JSON.stringify({ state: {} }))
+    await useConstructionReveal.persist.rehydrate()
+    expect(useConstructionReveal.getState().chosen).toBe(false)
+  })
+})
+
+describe('the framing plugin of a project', () => {
+  const framing = {
+    kind: FRAMING_KIND,
+    schemaVersion: 1,
+    schema: BaseNode.extend({ id: objectId('framing'), type: nodeType(FRAMING_KIND) }),
+    category: 'structure',
+    defaults: () => ({}),
+    capabilities: {},
+    geometry: () => null,
+  } as unknown as AnyNodeDefinition
+  let restore: () => void = () => {}
+  const wasInstalled = useScene.getState().installedPlugins
+
+  beforeAll(async () => {
+    restore = nodeRegistry._snapshot()
+    nodeRegistry._reset()
+    await loadPlugin({ id: 'fixture:framing', apiVersion: 1, nodes: [framing] })
+  })
+  afterAll(() => {
+    restore()
+    useScene.setState({ installedPlugins: wasInstalled })
+  })
+
+  test('is available where the plugin that carries the kind is installed', () => {
+    expect(isFramingAvailable([])).toBe(false)
+    expect(isFramingAvailable(['fixture:other'])).toBe(false)
+    expect(isFramingAvailable(['fixture:framing'])).toBe(true)
+  })
+
+  test('is not available where no loaded plugin carries the kind at all', () => {
+    const snapshot = nodeRegistry._snapshot()
+    nodeRegistry._reset()
+    expect(isFramingAvailable(['fixture:framing'])).toBe(false)
+    snapshot()
+  })
+
+  test('the level that plays is read from the open project', () => {
+    useScene.setState({ installedPlugins: [] })
+    expect(getConstructionRevealLevel()).toBe('full')
+    useScene.setState({ installedPlugins: ['fixture:framing'] })
+    expect(getConstructionRevealLevel()).toBe('framing')
+    useConstructionReveal.getState().setLevel('full')
+    expect(getConstructionRevealLevel()).toBe('full')
+  })
+})

package/src/store/use-construction-reveal.ts

@@ -0,0 +1,145 @@
+'use client'
+
+import { isNodeKindEnabled, nodeRegistry, useRegistryVersion, useScene } from '@pascal-app/core'
+import {
+  type AnimationSpeed,
+  type ConstructionRevealLevel,
+  DEFAULT_ANIMATION_SPEED,
+  normalizeAnimationSpeed,
+} from '@pascal-app/viewer'
+import { create } from 'zustand'
+import { createJSONStorage, persist } from 'zustand/middleware'
+
+export const CONSTRUCTION_REVEAL_LEVELS: readonly ConstructionRevealLevel[] = [
+  'off',
+  'simple',
+  'full',
+  'framing',
+]
+
+export const CONSTRUCTION_REVEAL_STORAGE_KEY = 'pascal-construction-reveal'
+
+/**
+ * The kind the Framing level draws: it plays only in a project where this kind is registered and
+ * its plugin is installed. Read through the kind, not a plugin id, so it holds wherever the framing
+ * kinds live (the Bones plugin, or the procedural plugin that carries them).
+ */
+export const FRAMING_KIND = 'bones:framing'
+
+const DEFAULT_LEVEL: ConstructionRevealLevel = 'full'
+
+function normalizeLevel(value: unknown): ConstructionRevealLevel {
+  return CONSTRUCTION_REVEAL_LEVELS.includes(value as ConstructionRevealLevel)
+    ? (value as ConstructionRevealLevel)
+    : DEFAULT_LEVEL
+}
+
+/** Reads `localStorage` on each call, so a page without it (a test, a sandbox) still has the store's persist API. */
+const browserStorage = createJSONStorage(() => ({
+  getItem: (key: string) => globalThis.localStorage?.getItem(key) ?? null,
+  setItem: (key: string, value: string) => globalThis.localStorage?.setItem(key, value),
+  removeItem: (key: string) => globalThis.localStorage?.removeItem(key),
+}))
+
+type ConstructionRevealState = {
+  /**
+   * The level the person last chose (see `chosen`). Hosts read the level that plays through
+   * `useConstructionRevealLevel`, which also knows whether the framing plugin is installed.
+   */
+  level: ConstructionRevealLevel
+  /** Whether the person has chosen a level themselves; until then the default follows the project. */
+  chosen: boolean
+  setLevel: (level: ConstructionRevealLevel) => void
+  /**
+   * How fast builds play, a multiple of the shipped pace (×0.5 to ×2, higher is faster); the host
+   * passes it to `ConstructionReveal`. A change applies to the next build, never to one playing.
+   */
+  speed: AnimationSpeed
+  setSpeed: (speed: AnimationSpeed) => void
+}
+
+/** The person's construction-animation preferences (level and speed), kept across sessions. */
+const useConstructionReveal = create<ConstructionRevealState>()(
+  persist(
+    (set) => ({
+      level: DEFAULT_LEVEL,
+      chosen: false,
+      setLevel: (level) => set({ level, chosen: true }),
+      speed: DEFAULT_ANIMATION_SPEED,
+      setSpeed: (speed) => set({ speed: normalizeAnimationSpeed(speed) }),
+    }),
+    {
+      name: CONSTRUCTION_REVEAL_STORAGE_KEY,
+      storage: browserStorage,
+      partialize: (state) => ({ level: state.level, chosen: state.chosen, speed: state.speed }),
+      merge: (persisted, current) => {
+        const saved = persisted as
+          | { level?: unknown; chosen?: unknown; speed?: unknown }
+          | undefined
+        return {
+          ...current,
+          level: normalizeLevel(saved?.level),
+          // A level saved before the default followed the project was the person's own choice.
+          chosen: typeof saved?.chosen === 'boolean' ? saved.chosen : saved?.level !== undefined,
+          // A person saved before the setting existed is at ×1; a stray value snaps to a step.
+          speed: normalizeAnimationSpeed(saved?.speed),
+        }
+      },
+    },
+  ),
+)
+
+/**
+ * The level that plays. With no choice of the person's own it is Framing where the framing plugin
+ * is available in the project and Full where it is not; a choice is kept, except that Framing falls
+ * back to Full while the plugin is missing (the choice comes back with the plugin).
+ */
+export function resolveConstructionLevel(
+  saved: Pick<ConstructionRevealState, 'level' | 'chosen'>,
+  framingInstalled: boolean,
+): ConstructionRevealLevel {
+  if (!saved.chosen) return framingInstalled ? 'framing' : 'full'
+  return saved.level === 'framing' && !framingInstalled ? 'full' : saved.level
+}
+
+/**
+ * A click on a level in the control. The level that plays is not always the saved one (a saved Framing
+ * plays as Full while the plugin is gone), and a click on that pressed level is not a choice: it keeps
+ * the saved one, so it plays again with the plugin.
+ */
+export function chooseConstructionLevel(
+  level: ConstructionRevealLevel,
+  framingInstalled: boolean,
+): void {
+  const state = useConstructionReveal.getState()
+  if (state.chosen && resolveConstructionLevel(state, framingInstalled) === level) return
+  state.setLevel(level)
+}
+
+/** Whether the project has what draws the framing: the kind is registered and its plugin installed. */
+export function isFramingAvailable(installedPlugins: readonly string[]): boolean {
+  return nodeRegistry.has(FRAMING_KIND) && isNodeKindEnabled(FRAMING_KIND, installedPlugins)
+}
+
+/** The same, for a component: it re-reads when a plugin registers after the first render. */
+export function useFramingAvailable(): boolean {
+  useRegistryVersion()
+  return useScene((state) => isFramingAvailable(state.installedPlugins))
+}
+
+/** The level that plays now, for a component: the person's choice or the project's default. */
+export function useConstructionRevealLevel(): ConstructionRevealLevel {
+  const level = useConstructionReveal((state) => state.level)
+  const chosen = useConstructionReveal((state) => state.chosen)
+  return resolveConstructionLevel({ level, chosen }, useFramingAvailable())
+}
+
+/** The level that plays now, read once (a tool's executor, not a component). */
+export function getConstructionRevealLevel(): ConstructionRevealLevel {
+  return resolveConstructionLevel(
+    useConstructionReveal.getState(),
+    isFramingAvailable(useScene.getState().installedPlugins),
+  )
+}
+
+export default useConstructionReveal

package/src/store/use-corner-snap-hint.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, test } from 'bun:test'
+import { CORNER_BLOCK_NOTES, cornerHintRows } from './use-corner-snap-hint'
+
+// The HUD near a wall end: what a click does where a window can join, and why not where it cannot,
+// in one wording for the placement HUD and the move HUD.
+describe('cornerHintRows', () => {
+  test('says nothing away from a wall end', () => {
+    expect(cornerHintRows(null)).toEqual([])
+  })
+
+  test('says what a click does where the window can join, and how to skip it with Alt', () => {
+    for (const hint of ['join', 'new'] as const)
+      expect(cornerHintRows(hint).map((row) => row.keys)).toEqual([['Left click'], ['Alt']])
+    expect(cornerHintRows('join')[0]?.label).not.toBe(cornerHintRows('new')[0]?.label)
+  })
+
+  test('gives each reason its own sentence where the end is no corner, and offers no click', () => {
+    const reasons = Object.keys(CORNER_BLOCK_NOTES) as (keyof typeof CORNER_BLOCK_NOTES)[]
+    const rows = reasons.map((reason) => cornerHintRows(reason))
+
+    expect(new Set(rows.map((row) => row[0]?.label)).size).toBe(reasons.length)
+    expect(rows.flat().every((row) => !row.keys.includes('Left click'))).toBe(true)
+  })
+})