@asteby/metacore-runtime-react 9.2.0 → 10.0.0

package/src/__tests__/hotswap-reload-policy.test.ts

@@ -0,0 +1,249 @@
+import { describe, expect, it, vi } from 'vitest'
+import {
+    applyHotSwapReload,
+    withVersionParam,
+    clearFederationContainer,
+    shortenHash,
+    type HotSwapReloadConfig,
+    type HotSwapReloadDeps,
+} from '../hotswap-reload-policy'
+import { type AddonManifestChangedMessage } from '../manifest-hotswap-subscriber'
+
+const msg = (
+    addonKey: string,
+    newHash: string | undefined = 'sha256:abcdef1234567890',
+): AddonManifestChangedMessage => ({
+    type: 'ADDON_MANIFEST_CHANGED',
+    payload: { addonKey, newHash },
+})
+
+interface FakeState {
+    map: Record<string, string>
+    deps: HotSwapReloadDeps
+    reload: ReturnType<typeof vi.fn>
+}
+
+function makeFakeState(): FakeState {
+    const reload = vi.fn()
+    const state: FakeState = {
+        map: {},
+        // populated below
+        deps: {} as HotSwapReloadDeps,
+        reload,
+    }
+    state.deps = {
+        setVersionMap: (updater) => {
+            state.map = updater(state.map)
+        },
+        reload,
+    }
+    return state
+}
+
+describe('shortenHash', () => {
+    it('strips the algorithm prefix and truncates to 8 hex chars', () => {
+        expect(shortenHash('sha256:ABCDEF1234567890')).toBe('abcdef12')
+        expect(shortenHash('abcdef1234567890')).toBe('abcdef12')
+    })
+
+    it('returns undefined for missing / empty input', () => {
+        expect(shortenHash(undefined)).toBeUndefined()
+        expect(shortenHash('')).toBeUndefined()
+        expect(shortenHash('sha256:')).toBeUndefined()
+    })
+})
+
+describe('withVersionParam', () => {
+    it('appends ?v=<hash8> to a URL with no query', () => {
+        expect(
+            withVersionParam('/api/addons/pos/frontend/remoteEntry.js', 'sha256:abcdef1234'),
+        ).toBe('/api/addons/pos/frontend/remoteEntry.js?v=abcdef12')
+    })
+
+    it('appends &v=<hash8> when other query params exist', () => {
+        expect(withVersionParam('/r.js?foo=1&bar=2', 'abcdef1234')).toBe(
+            '/r.js?foo=1&bar=2&v=abcdef12',
+        )
+    })
+
+    it('replaces a prior v= entry instead of accumulating', () => {
+        expect(withVersionParam('/r.js?v=oldhash&foo=1', 'newhash99')).toBe(
+            '/r.js?foo=1&v=newhash9',
+        )
+    })
+
+    it('preserves the URL fragment', () => {
+        expect(withVersionParam('/r.js#section', 'abcdef1234')).toBe(
+            '/r.js?v=abcdef12#section',
+        )
+    })
+
+    it('is idempotent for the same hash', () => {
+        const once = withVersionParam('/r.js', 'abcdef1234')
+        const twice = withVersionParam(once, 'abcdef1234')
+        expect(twice).toBe(once)
+    })
+
+    it('returns the URL unchanged for falsy hash', () => {
+        expect(withVersionParam('/r.js', undefined)).toBe('/r.js')
+        expect(withVersionParam('/r.js', '')).toBe('/r.js')
+    })
+})
+
+describe('clearFederationContainer', () => {
+    it('removes the container from window and returns true', () => {
+        // Node test environment — globalThis is functionally `window` here.
+        // We set a property and expect it to be removed.
+        ;(globalThis as Record<string, unknown>).metacore_test_addon = {
+            init: () => {},
+            get: () => {},
+        }
+        // The function checks `typeof window === 'undefined'`. In node env
+        // that's true → returns false. We only assert this code path doesn't
+        // throw and returns a boolean. The window-present case is exercised
+        // indirectly through manual integration in the hot-swap docs.
+        const result = clearFederationContainer('metacore_test_addon')
+        expect(typeof result).toBe('boolean')
+        delete (globalThis as Record<string, unknown>).metacore_test_addon
+    })
+
+    it('returns false when called for an unregistered scope in SSR (no window)', () => {
+        expect(clearFederationContainer('metacore_never_registered')).toBe(false)
+    })
+})
+
+describe('applyHotSwapReload', () => {
+    it('returns "noop" and does not touch the map when addonKey is missing', async () => {
+        const state = makeFakeState()
+        const action = await applyHotSwapReload(
+            {
+                type: 'ADDON_MANIFEST_CHANGED',
+                // @ts-expect-error — exercising the guard
+                payload: {},
+            },
+            {},
+            state.deps,
+        )
+        expect(action).toBe('noop')
+        expect(state.map).toEqual({})
+    })
+
+    it('default strategy rekeys the map with the short hash and fires onSwap("rekey")', async () => {
+        const state = makeFakeState()
+        const onSwap = vi.fn()
+        const action = await applyHotSwapReload(
+            msg('pos', 'sha256:abcdef1234'),
+            { onSwap },
+            state.deps,
+        )
+        expect(action).toBe('rekey')
+        expect(state.map).toEqual({ pos: 'abcdef12' })
+        expect(onSwap).toHaveBeenCalledWith(expect.anything(), 'rekey')
+    })
+
+    it('successive bumps for the same addon update the hash in place', async () => {
+        const state = makeFakeState()
+        await applyHotSwapReload(msg('pos', 'sha256:abcdef1234'), {}, state.deps)
+        await applyHotSwapReload(msg('pos', 'sha256:99999999'), {}, state.deps)
+        expect(state.map).toEqual({ pos: '99999999' })
+    })
+
+    it('bumps for different addons accumulate as independent entries', async () => {
+        const state = makeFakeState()
+        await applyHotSwapReload(msg('pos', 'sha256:aaaaaaaa'), {}, state.deps)
+        await applyHotSwapReload(msg('kitchen', 'sha256:bbbbbbbb'), {}, state.deps)
+        expect(state.map).toEqual({ pos: 'aaaaaaaa', kitchen: 'bbbbbbbb' })
+    })
+
+    it('cancels rekey when onBeforeReload returns false (sync)', async () => {
+        const state = makeFakeState()
+        const onBeforeReload = vi.fn().mockReturnValue(false)
+        const onSwap = vi.fn()
+        const action = await applyHotSwapReload(
+            msg('pos'),
+            { strategy: 'rekey', onBeforeReload, onSwap },
+            state.deps,
+        )
+        expect(action).toBe('cancelled')
+        expect(state.map).toEqual({})
+        expect(onSwap).toHaveBeenCalledWith(expect.anything(), 'cancelled')
+    })
+
+    it('proceeds with rekey when async onBeforeReload resolves true', async () => {
+        const state = makeFakeState()
+        const onBeforeReload = vi.fn().mockResolvedValue(true)
+        const action = await applyHotSwapReload(
+            msg('pos'),
+            { strategy: 'rekey', onBeforeReload },
+            state.deps,
+        )
+        expect(action).toBe('rekey')
+        expect(state.map).toEqual({ pos: 'abcdef12' })
+    })
+
+    it('strategy=manual updates the map and reports "manual" without reloading', async () => {
+        const state = makeFakeState()
+        const onSwap = vi.fn()
+        const action = await applyHotSwapReload(
+            msg('pos'),
+            { strategy: 'manual', onSwap },
+            state.deps,
+        )
+        expect(action).toBe('manual')
+        expect(state.map).toEqual({ pos: 'abcdef12' })
+        expect(state.reload).not.toHaveBeenCalled()
+        expect(onSwap).toHaveBeenCalledWith(expect.anything(), 'manual')
+    })
+
+    it('strategy=page-reload invokes the reload function via microtask', async () => {
+        const state = makeFakeState()
+        const onSwap = vi.fn()
+        const action = await applyHotSwapReload(
+            msg('pos'),
+            { strategy: 'page-reload', onSwap },
+            state.deps,
+        )
+        expect(action).toBe('page-reload')
+        expect(onSwap).toHaveBeenCalledWith(expect.anything(), 'page-reload')
+
+        // Yield to the microtask queue so the deferred reload fires.
+        await Promise.resolve()
+        expect(state.reload).toHaveBeenCalledTimes(1)
+    })
+
+    it('strategy=page-reload + onBeforeReload(false) skips the reload', async () => {
+        const state = makeFakeState()
+        const onBeforeReload = vi.fn().mockReturnValue(false)
+        const onSwap = vi.fn()
+        const action = await applyHotSwapReload(
+            msg('pos'),
+            { strategy: 'page-reload', onBeforeReload, onSwap },
+            state.deps,
+        )
+        expect(action).toBe('cancelled')
+        await Promise.resolve()
+        expect(state.reload).not.toHaveBeenCalled()
+        expect(onSwap).toHaveBeenCalledWith(expect.anything(), 'cancelled')
+    })
+
+    it('skips map update when newHash is missing but still rekeys (no-op effect)', async () => {
+        const state = makeFakeState()
+        const onSwap = vi.fn()
+        // Build a message with an explicitly missing newHash. Going through
+        // `msg(..., undefined)` would trigger the default-value substitution,
+        // so we hand-roll the payload here.
+        const action = await applyHotSwapReload(
+            {
+                type: 'ADDON_MANIFEST_CHANGED',
+                payload: { addonKey: 'pos' },
+            },
+            { onSwap },
+            state.deps,
+        )
+        expect(action).toBe('rekey')
+        // Without a hash, we have nothing to write; the map stays empty
+        // but onSwap still fires for telemetry.
+        expect(state.map).toEqual({})
+        expect(onSwap).toHaveBeenCalledWith(expect.anything(), 'rekey')
+    })
+})

package/src/__tests__/manifest-hotswap-subscriber.test.ts

@@ -0,0 +1,179 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+    ADDON_MANIFEST_CHANGED_TYPE,
+    wireHotSwapInvalidation,
+    type AddonManifestChangedMessage,
+    type ManifestHotSwapClient,
+} from '../manifest-hotswap-subscriber'
+import { useMetadataCache, defaultAddonKeyMatcher } from '../metadata-cache'
+import type { TableMetadata } from '../types'
+
+// Minimal stub TableMetadata; the cache stores values opaquely so the only
+// requirement is the type-shape compiles.
+const fakeMeta = (label: string): TableMetadata => ({ label }) as unknown as TableMetadata
+
+interface FakeClient extends ManifestHotSwapClient {
+    emit: (msg: AddonManifestChangedMessage) => void
+    subscriberCount: () => number
+}
+
+function makeFakeClient(): FakeClient {
+    const subs = new Map<string, Set<(m: AddonManifestChangedMessage) => void>>()
+    return {
+        subscribe(type, handler) {
+            let set = subs.get(type)
+            if (!set) {
+                set = new Set()
+                subs.set(type, set)
+            }
+            set.add(handler)
+            return () => {
+                subs.get(type)?.delete(handler)
+            }
+        },
+        emit(msg) {
+            const set = subs.get(msg.type)
+            if (!set) return
+            for (const h of set) h(msg)
+        },
+        subscriberCount() {
+            return Array.from(subs.values()).reduce((n, s) => n + s.size, 0)
+        },
+    }
+}
+
+describe('manifest-hotswap-subscriber', () => {
+    beforeEach(() => {
+        // Reset the zustand cache between tests so each starts from a
+        // known-empty state. The store persists by default; resetState
+        // here keeps the in-memory copy isolated.
+        useMetadataCache.setState({
+            cache: {},
+            modalCache: {},
+            metadataVersion: 'v-old',
+            prefetched: true,
+        })
+    })
+
+    afterEach(() => {
+        vi.restoreAllMocks()
+    })
+
+    it('emits the topic name the kernel/bridge publishes', () => {
+        expect(ADDON_MANIFEST_CHANGED_TYPE).toBe('ADDON_MANIFEST_CHANGED')
+    })
+
+    it('subscribes to ADDON_MANIFEST_CHANGED and invalidates the named addon on receipt', () => {
+        const cache = useMetadataCache.getState()
+        cache.setMetadata('kitchen_display.tickets', fakeMeta('tickets'))
+        cache.setMetadata('kitchen_display:settings', fakeMeta('settings'))
+        cache.setMetadata('kitchen_display/lines', fakeMeta('lines'))
+        cache.setMetadata('pos.cart', fakeMeta('cart'))
+        cache.setModalMetadata('kitchen_display.printer', fakeMeta('printer'))
+        cache.setModalMetadata('inventory.batch', fakeMeta('batch'))
+
+        const client = makeFakeClient()
+        const unsubscribe = wireHotSwapInvalidation(client)
+        expect(client.subscriberCount()).toBe(1)
+
+        client.emit({
+            type: 'ADDON_MANIFEST_CHANGED',
+            payload: {
+                addonKey: 'kitchen_display',
+                oldHash: 'sha256:aaa',
+                newHash: 'sha256:bbb',
+                version: '1.2.0',
+            },
+        })
+
+        const after = useMetadataCache.getState()
+        // Three table-cache entries scoped to kitchen_display should be gone.
+        expect(after.cache).toEqual({ 'pos.cart': fakeMeta('cart') })
+        // One modal entry gone; the inventory entry stays.
+        expect(after.modalCache).toEqual({ 'inventory.batch': fakeMeta('batch') })
+        // prefetched flipped to false so prefetchAll() can re-run.
+        expect(after.prefetched).toBe(false)
+
+        unsubscribe()
+        expect(client.subscriberCount()).toBe(0)
+    })
+
+    it('invokes the onSwap callback with the message and the removed count', () => {
+        const cache = useMetadataCache.getState()
+        cache.setMetadata('pos.cart', fakeMeta('cart'))
+        cache.setMetadata('pos:lines', fakeMeta('lines'))
+        cache.setMetadata('inventory.batch', fakeMeta('batch'))
+
+        const onSwap = vi.fn()
+        const client = makeFakeClient()
+        wireHotSwapInvalidation(client, { onSwap })
+
+        const message: AddonManifestChangedMessage = {
+            type: 'ADDON_MANIFEST_CHANGED',
+            payload: { addonKey: 'pos', newHash: 'sha256:new' },
+        }
+        client.emit(message)
+
+        expect(onSwap).toHaveBeenCalledTimes(1)
+        expect(onSwap).toHaveBeenCalledWith(message, 2)
+    })
+
+    it('honours a custom matcher when the host uses a different key convention', () => {
+        const cache = useMetadataCache.getState()
+        cache.setMetadata('addons/pos/cart', fakeMeta('cart'))
+        cache.setMetadata('addons/pos/lines', fakeMeta('lines'))
+        cache.setMetadata('addons/inv/batch', fakeMeta('batch'))
+
+        const matcher = (cacheKey: string, addonKey: string) =>
+            cacheKey.startsWith(`addons/${addonKey}/`)
+
+        const client = makeFakeClient()
+        wireHotSwapInvalidation(client, { matcher })
+
+        client.emit({
+            type: 'ADDON_MANIFEST_CHANGED',
+            payload: { addonKey: 'pos' },
+        })
+
+        const after = useMetadataCache.getState()
+        expect(Object.keys(after.cache)).toEqual(['addons/inv/batch'])
+    })
+
+    it('ignores malformed messages (missing addonKey) without throwing', () => {
+        const cache = useMetadataCache.getState()
+        cache.setMetadata('pos.cart', fakeMeta('cart'))
+
+        const client = makeFakeClient()
+        wireHotSwapInvalidation(client)
+
+        expect(() =>
+            client.emit({
+                type: 'ADDON_MANIFEST_CHANGED',
+                // @ts-expect-error — exercising the malformed-payload guard
+                payload: {},
+            }),
+        ).not.toThrow()
+
+        // Cache untouched.
+        expect(useMetadataCache.getState().cache).toEqual({
+            'pos.cart': fakeMeta('cart'),
+        })
+    })
+
+    it('returns a no-op unsubscribe when the client is undefined', () => {
+        const unsubscribe = wireHotSwapInvalidation(undefined)
+        expect(typeof unsubscribe).toBe('function')
+        expect(() => unsubscribe()).not.toThrow()
+    })
+
+    it('default matcher recognises addonKey, prefix., prefix:, prefix/', () => {
+        expect(defaultAddonKeyMatcher('pos', 'pos')).toBe(true)
+        expect(defaultAddonKeyMatcher('pos.cart', 'pos')).toBe(true)
+        expect(defaultAddonKeyMatcher('pos:lines', 'pos')).toBe(true)
+        expect(defaultAddonKeyMatcher('pos/checkout', 'pos')).toBe(true)
+        expect(defaultAddonKeyMatcher('possible.x', 'pos')).toBe(false)
+        expect(defaultAddonKeyMatcher('inventory.cart', 'pos')).toBe(false)
+        expect(defaultAddonKeyMatcher('', 'pos')).toBe(false)
+        expect(defaultAddonKeyMatcher('pos.cart', '')).toBe(false)
+    })
+})

package/src/__tests__/wasm-client-sri.test.ts

@@ -0,0 +1,82 @@
+// Wasm-client SRI smoke tests — lives in runtime-react because the SDK
+// package does not (yet) carry a vitest setup of its own. We import the
+// helper through the workspace specifier so the test exercises the same
+// public boundary downstream apps see.
+//
+// The SRI logic is decoupled from WebAssembly instantiation by design, so
+// these tests run in plain Node without needing a real `.wasm` module.
+
+import { describe, it, expect } from 'vitest'
+import {
+    verifyIntegrity,
+    WasmIntegrityError,
+} from '@asteby/metacore-sdk'
+
+function bytes(input: string): Uint8Array {
+    return new TextEncoder().encode(input)
+}
+
+async function digestB64(algo: 'SHA-256' | 'SHA-384' | 'SHA-512', input: string) {
+    const buf = await crypto.subtle.digest(algo, bytes(input))
+    const view = new Uint8Array(buf)
+    let bin = ''
+    for (let i = 0; i < view.byteLength; i++) bin += String.fromCharCode(view[i]!)
+    return btoa(bin)
+}
+
+describe('verifyIntegrity', () => {
+    it('accepts a matching sha384 digest', async () => {
+        const payload = 'hello, metacore wasm world'
+        const hash = await digestB64('SHA-384', payload)
+        await expect(
+            verifyIntegrity(bytes(payload), `sha384-${hash}`),
+        ).resolves.toBeUndefined()
+    })
+
+    it('accepts a matching sha256 digest', async () => {
+        const payload = '{"hello":"world"}'
+        const hash = await digestB64('SHA-256', payload)
+        await expect(
+            verifyIntegrity(bytes(payload), `sha256-${hash}`),
+        ).resolves.toBeUndefined()
+    })
+
+    it('throws WasmIntegrityError on digest mismatch', async () => {
+        const payload = 'hello'
+        const wrong = await digestB64('SHA-384', 'tampered')
+        await expect(
+            verifyIntegrity(bytes(payload), `sha384-${wrong}`),
+        ).rejects.toBeInstanceOf(WasmIntegrityError)
+    })
+
+    it('passes when ANY space-separated token matches', async () => {
+        const payload = 'multi-hash'
+        const bad = await digestB64('SHA-384', 'other')
+        const good = await digestB64('SHA-256', payload)
+        await expect(
+            verifyIntegrity(bytes(payload), `sha384-${bad} sha256-${good}`),
+        ).resolves.toBeUndefined()
+    })
+
+    it('is a no-op when integrity is the empty string', async () => {
+        await expect(verifyIntegrity(bytes('anything'), '')).resolves.toBeUndefined()
+    })
+
+    it('rejects malformed integrity tokens', async () => {
+        await expect(
+            verifyIntegrity(bytes('x'), 'this-has-no-algo'),
+        ).rejects.toBeInstanceOf(WasmIntegrityError)
+    })
+
+    it('rejects unsupported algorithms', async () => {
+        await expect(
+            verifyIntegrity(bytes('x'), 'md5-deadbeef'),
+        ).rejects.toBeInstanceOf(WasmIntegrityError)
+    })
+
+    it('handles length-mismatched digests as a clean mismatch', async () => {
+        await expect(
+            verifyIntegrity(bytes('x'), 'sha256-short'),
+        ).rejects.toBeInstanceOf(WasmIntegrityError)
+    })
+})

package/src/addon-layout-context.tsx

@@ -0,0 +1,137 @@
+// AddonLayoutContext — broadcast the active addon entry's layout selection
+// (`shell` vs `immersive`) up to the host so it can hide/show its chrome
+// (Sidebar, Topbar, breadcrumbs) when an immersive addon is mounted.
+//
+// Why a context rather than a prop on the host shell:
+//
+//   1. The host shell is rendered ABOVE the addon route in the tree, but the
+//      decision about what layout the addon wants comes from the addon itself
+//      (manifest.frontend.layout) which the AddonLoader knows about at mount
+//      time. A bottom-up signal via context inverts the dependency cleanly.
+//
+//   2. Addon entries can swap layouts at runtime (think a kiosk-mode toggle
+//      inside a POS). A context value reactively updates the host without
+//      asking each route to wire props.
+//
+//   3. When the user navigates AWAY from an immersive addon, the AddonLoader
+//      unmounts, its layout context updater fires `setLayout("shell")` from
+//      a cleanup effect, and the chrome restores automatically.
+//
+// Host integration (starter-core, ops, …):
+//
+//   function AppShell({ children }) {
+//     const layout = useAddonLayout()
+//     const chrome = layout !== "immersive"
+//     return (
+//       <div className={chrome ? "grid grid-cols-[280px_1fr]" : "h-dvh w-dvw"}>
+//         {chrome && <Sidebar />}
+//         <main>{chrome && <Topbar />}{children}</main>
+//       </div>
+//     )
+//   }
+//
+// The context defaults to `"shell"`, so apps that never mount an
+// `<AddonLayoutProvider>` keep the legacy behaviour.
+
+import {
+    createContext,
+    useCallback,
+    useContext,
+    useEffect,
+    useMemo,
+    useState,
+} from 'react'
+import type { AddonLayout } from '@asteby/metacore-sdk'
+
+export type { AddonLayout }
+
+interface AddonLayoutState {
+    /** Active layout. `"shell"` (default) or `"immersive"`. */
+    layout: AddonLayout
+    /**
+     * Imperative setter for the host or an addon-loader to mutate the active
+     * layout. Exposed for advanced use; most callers should use
+     * `useDeclareAddonLayout(layout)` from a route component, which scopes the
+     * change to the route's mount lifetime.
+     */
+    setLayout: (layout: AddonLayout) => void
+}
+
+const defaultState: AddonLayoutState = {
+    layout: 'shell',
+    setLayout: () => {
+        /* noop — provider missing; consumers degrade to legacy "shell" */
+    },
+}
+
+const AddonLayoutContext = createContext<AddonLayoutState>(defaultState)
+
+export interface AddonLayoutProviderProps {
+    /** Initial layout — usually `"shell"`. */
+    initial?: AddonLayout
+    children: React.ReactNode
+}
+
+/**
+ * Wrap the host app once, above the router outlet. The provider keeps the
+ * currently-active layout in state; addon-loader and `useDeclareAddonLayout`
+ * mutate it from below.
+ */
+export function AddonLayoutProvider({
+    initial = 'shell',
+    children,
+}: AddonLayoutProviderProps) {
+    const [layout, setLayout] = useState<AddonLayout>(initial)
+    const value = useMemo<AddonLayoutState>(
+        () => ({ layout, setLayout }),
+        [layout],
+    )
+    return (
+        <AddonLayoutContext.Provider value={value}>
+            {children}
+        </AddonLayoutContext.Provider>
+    )
+}
+
+/**
+ * Read the currently-active layout. The host shell calls this and decides
+ * whether to render its chrome. Returns `"shell"` when no provider is
+ * mounted, so apps that have not adopted immersive addons keep working.
+ */
+export function useAddonLayout(): AddonLayout {
+    return useContext(AddonLayoutContext).layout
+}
+
+/**
+ * Imperative API — the value returned mirrors `useAddonLayout()` but also
+ * exposes the setter for hosts that need to flip the layout outside of a
+ * route lifecycle (e.g. a hotkey forcing kiosk mode). Most addon entries do
+ * NOT need this; prefer `useDeclareAddonLayout`.
+ */
+export function useAddonLayoutControl(): AddonLayoutState {
+    return useContext(AddonLayoutContext)
+}
+
+/**
+ * Declare the layout from the addon side. Mounts the value, restores
+ * `"shell"` on unmount. Skip when `layout` is undefined so route components
+ * can pass `manifest.frontend?.layout` directly without branching.
+ *
+ *   function PosEntry({ manifest }: { manifest: Manifest }) {
+ *     useDeclareAddonLayout(manifest.frontend?.layout)
+ *     return <PosScreen />
+ *   }
+ */
+export function useDeclareAddonLayout(layout: AddonLayout | undefined): void {
+    const { setLayout } = useAddonLayoutControl()
+    // useCallback so the effect only re-runs on a real layout change, not on
+    // every render of the consumer that happens to forward an inline literal.
+    const apply = useCallback(setLayout, [setLayout])
+    useEffect(() => {
+        if (!layout || layout === 'shell') return
+        apply(layout)
+        return () => {
+            apply('shell')
+        }
+    }, [layout, apply])
+}