@softov/scena 0.1.2

package/dist/react/SurfaceArea.js

@@ -0,0 +1,75 @@
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { Suspense, useEffect, useState, } from 'react';
+import { useScena } from './ScenaProvider.js';
+import { useLayout } from './hooks/useLayout.js';
+import { useMounts } from './hooks/useMounts.js';
+import { MountWrapper, ViewMount } from './ViewMount.js';
+import { useSurfaceResize } from './useSurfaceResize.js';
+function renderOneMount(mount) {
+    return (_jsx(MountWrapper, { mountKey: mount.key, dataContext: mount.dataContext, children: _jsx("div", { className: "oo-mount", "data-mount-key": mount.key, children: _jsx(ViewMount, { node: mount.component }) }) }));
+}
+function FallbackLayout({ mounts }) {
+    return (_jsx(_Fragment, { children: mounts.map((m) => (_jsx("div", { style: { display: 'contents' }, children: renderOneMount(m) }, m.key))) }));
+}
+export function SurfaceArea({ surface, layout, style, className, presentation = 'docked', resize, }) {
+    const scena = useScena();
+    const layoutState = useLayout();
+    const mounts = useMounts(surface);
+    const resizeBinding = useSurfaceResize(surface, presentation, resize);
+    const surfaceState = layoutState.surfaces[surface] ?? { visible: true };
+    const layoutId = surfaceState.layout ?? layout ?? 'default';
+    const [registryTick, setRegistryTick] = useState(0);
+    useEffect(() => {
+        const sub = scena.events.on('scena:registry:changed', (payload) => {
+            if (payload.registry === 'layouts') {
+                setRegistryTick((t) => t + 1);
+            }
+        });
+        return () => sub.dispose();
+    }, [scena]);
+    void registryTick;
+    const layoutDef = scena.layouts.get(layoutId);
+    const setSurfaceState = (patch) => {
+        scena.layout.setSurface(surface, patch);
+    };
+    const layoutProps = {
+        surface,
+        mounts,
+        state: surfaceState,
+        presentation,
+        setState: setSurfaceState,
+        renderMount: renderOneMount,
+        onActivate: (key) => scena.surfaces.focus(key),
+        onClose: (key, opts) => scena.surfaces.close(key, opts),
+        onReorder: (fromIndex, toIndex) => {
+            const persistedOrder = surfaceState.split?.order ?? [];
+            const orderSet = new Set(persistedOrder);
+            const orderedKnown = persistedOrder.filter((k) => mounts.some((m) => m.key === k));
+            const newKeys = mounts.filter((m) => !orderSet.has(m.key)).map((m) => m.key);
+            const next = [...orderedKnown, ...newKeys];
+            const [moved] = next.splice(fromIndex, 1);
+            if (moved !== undefined)
+                next.splice(toIndex, 0, moved);
+            // Spread the existing split so newer fields like `pinned` survive
+            // the write; the prior explicit pick dropped anything not listed.
+            scena.layout.setSurface(surface, {
+                split: {
+                    ...(surfaceState.split ?? {}),
+                    order: next,
+                },
+            });
+        },
+    };
+    return (_jsx("div", { "data-surface": surface, "data-presentation": presentation, className: [
+            'oo-surface',
+            `oo-surface--${surface.replace(':', '-')}`,
+            className,
+        ]
+            .filter(Boolean)
+            .join(' '), style: style, ...resizeBinding, children: layoutDef ? ((() => {
+            // Layout components are lazy (see ui/layout/register.ts) — render
+            // inside Suspense so the first use of a strategy can load its chunk.
+            const Layout = layoutDef.component;
+            return (_jsx(Suspense, { fallback: _jsx("div", { children: "Loading..." }), children: _jsx(Layout, { ...layoutProps }) }));
+        })()) : (_jsx(FallbackLayout, { mounts: mounts })) }));
+}

package/dist/react/Translate.d.ts

@@ -0,0 +1,8 @@
+import type { ReactNode } from 'react';
+export interface TranslateProps {
+    k: string;
+    ns?: string;
+    fallback?: string;
+    [param: string]: unknown;
+}
+export declare function Translate({ k, ns, ...params }: TranslateProps): ReactNode;

package/dist/react/Translate.js

@@ -0,0 +1,10 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useI18n } from './hooks/useI18n.js';
+// Renders a translated message reactively — re-renders on locale switch. For
+// hand-written JSX where a label/value is a ReactNode AND you're outside a
+// component (config, column defs) so you can't call useI18n directly. For
+// declarative ComponentNodes, bind `{ path: '$/t/<key>' }` instead.
+export function Translate({ k, ns, ...params }) {
+    const { t } = useI18n(ns);
+    return _jsx(_Fragment, { children: t(k, params) });
+}

package/dist/react/ViewMount.d.ts

@@ -0,0 +1,12 @@
+import { type ReactNode } from 'react';
+import type { BindingPath, ComponentNode } from '../types/component-graph.js';
+interface ViewMountProps {
+    node: ComponentNode;
+}
+export declare function ViewMount({ node }: ViewMountProps): import("react").JSX.Element;
+export declare function MountWrapper({ mountKey, dataContext, children, }: {
+    mountKey: string;
+    dataContext?: BindingPath;
+    children: ReactNode;
+}): import("react").JSX.Element;
+export {};

package/dist/react/ViewMount.js

@@ -0,0 +1,268 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useReducer, useRef, useState, } from 'react';
+import { isAction, isComponentNode, isDataBinding, isDynamicChildList, isFunctionCall, } from '../types/component-graph.js';
+import { useScena } from './ScenaProvider.js';
+import { DataContextContext, MountContext, WriteContext, useCurrentMountKey, useDataContext, } from './mount-context.js';
+import { joinAbsolute, readPath } from '../core/path-resolver.js';
+import { resolveAction, resolveDynamicValue, writeDynamic, } from '../core/dynamic-resolver.js';
+import { rewriteLocal } from '../core/reactive-store.js';
+const RESERVED_KEYS = new Set(['id', 'component', '$meta']);
+const reactComponentCache = new WeakMap();
+const reactLoadingPromises = new WeakMap();
+async function loadReactComponent(def) {
+    if (def.renderer.kind !== 'react') {
+        throw new Error(`Cannot load non-react component "${def.component}" through React adapter`);
+    }
+    const cached = reactComponentCache.get(def);
+    if (cached)
+        return cached;
+    let pending = reactLoadingPromises.get(def);
+    if (pending)
+        return pending;
+    pending = def.renderer.load().then((mod) => {
+        const C = mod.default;
+        reactComponentCache.set(def, C);
+        return C;
+    });
+    reactLoadingPromises.set(def, pending);
+    return pending;
+}
+// Compute the absolute store path a DataBinding resolves to in this render,
+// applying mount-local rewriting and data-context joining. Returns undefined
+// when the path can't be normalized (e.g., relative path with no data context).
+function normalizePath(path, mountKey, dataContext) {
+    try {
+        if (path.startsWith('/') && !path.startsWith('$/')) {
+            return joinAbsolute(dataContext, path);
+        }
+        return rewriteLocal(path, mountKey);
+    }
+    catch {
+        return undefined;
+    }
+}
+// Walks every prop value of `node` and collects the absolute store paths the
+// renderer needs to subscribe to so re-renders fire when source data changes.
+function collectPaths(node, mountKey, dataContext, out) {
+    for (const [k, v] of Object.entries(node)) {
+        if (RESERVED_KEYS.has(k))
+            continue;
+        collectFromValue(v, mountKey, dataContext, out);
+    }
+}
+function collectFromValue(v, mountKey, dataContext, out) {
+    if (v === null || typeof v !== 'object')
+        return;
+    if (isComponentNode(v)) {
+        // Nested ViewMount handles its own subscriptions.
+        return;
+    }
+    // Order matters: more-specific shapes first, so DataBinding's "just path"
+    // structural guard doesn't accidentally catch a `{ template, path }`
+    // DynamicChildList or `{ event }`/`{ functionCall }` Action.
+    if (isAction(v)) {
+        if ('event' in v && v.event.context) {
+            for (const arg of Object.values(v.event.context)) {
+                collectFromValue(arg, mountKey, dataContext, out);
+            }
+        }
+        else if ('functionCall' in v && v.functionCall.args) {
+            for (const arg of Object.values(v.functionCall.args)) {
+                collectFromValue(arg, mountKey, dataContext, out);
+            }
+        }
+        return;
+    }
+    if (isDynamicChildList(v)) {
+        const abs = normalizePath(v.path, mountKey, dataContext);
+        if (abs)
+            out.add(abs);
+        return;
+    }
+    if (isFunctionCall(v)) {
+        if (v.args) {
+            for (const arg of Object.values(v.args)) {
+                collectFromValue(arg, mountKey, dataContext, out);
+            }
+        }
+        return;
+    }
+    if (isDataBinding(v)) {
+        const abs = normalizePath(v.path, mountKey, dataContext);
+        if (abs)
+            out.add(abs);
+        return;
+    }
+    if (Array.isArray(v)) {
+        for (const item of v)
+            collectFromValue(item, mountKey, dataContext, out);
+        return;
+    }
+    for (const inner of Object.values(v)) {
+        collectFromValue(inner, mountKey, dataContext, out);
+    }
+}
+// Resolves one prop value to its render-time form:
+//   ComponentNode      → <ViewMount node={...} />
+//   ComponentNode[]    → array of <ViewMount />
+//   { template, path } → array of <ViewMount /> per item; each gets a data context
+//   DataBinding        → resolved store value
+//   FunctionCall       → resolved (invoked) value
+//   Action             → 0-arg async handler
+//   literal / object   → pass through (recurse into nested arrays/objects)
+function resolveProp(v, scena, mountKey, dataContext) {
+    if (v === null || typeof v !== 'object')
+        return v;
+    if (isComponentNode(v)) {
+        return _jsx(ViewMount, { node: v });
+    }
+    if (Array.isArray(v) && v.every(isComponentNode)) {
+        return v.map((n, i) => (_jsx(ViewMount, { node: n }, n.id ?? i)));
+    }
+    if (isAction(v)) {
+        return resolveAction(v, dataContext, scena, mountKey);
+    }
+    if (isDynamicChildList(v)) {
+        const listValue = readPath(scena.store, dataContext, v.path);
+        if (!Array.isArray(listValue))
+            return [];
+        const baseAbs = normalizePath(v.path, mountKey, dataContext);
+        return listValue.map((_, i) => {
+            const itemContext = baseAbs
+                ? `${baseAbs}/${i}`
+                : undefined;
+            return (_jsx(DataContextContext.Provider, { value: itemContext, children: _jsx(ViewMount, { node: v.template }) }, i));
+        });
+    }
+    if (isFunctionCall(v)) {
+        return resolveDynamicValue(v, dataContext, scena);
+    }
+    if (isDataBinding(v)) {
+        return readPath(scena.store, dataContext, v.path);
+    }
+    if (Array.isArray(v)) {
+        return v.map((item) => resolveProp(item, scena, mountKey, dataContext));
+    }
+    // Plain object — recurse element-wise. Useful for nested arg structs.
+    const out = {};
+    for (const [k, inner] of Object.entries(v)) {
+        out[k] = resolveProp(inner, scena, mountKey, dataContext);
+    }
+    return out;
+}
+export function ViewMount({ node }) {
+    const scena = useScena();
+    const mountKey = useCurrentMountKey();
+    const dataContext = useDataContext();
+    const [, force] = useReducer((x) => x + 1, 0);
+    const [LoadedComponent, setLoadedComponent] = useState(null);
+    const def = scena.components.get(node.component);
+    useEffect(() => {
+        const sub = scena.events.on('scena:registry:changed', (payload) => {
+            if (payload.registry === 'components')
+                force();
+        });
+        return () => sub.dispose();
+    }, [scena]);
+    useEffect(() => {
+        if (!def || def.renderer.kind !== 'react') {
+            setLoadedComponent(null);
+            return;
+        }
+        const cached = reactComponentCache.get(def);
+        if (cached) {
+            setLoadedComponent(() => cached);
+            return;
+        }
+        let cancelled = false;
+        void loadReactComponent(def).then((C) => {
+            if (!cancelled)
+                setLoadedComponent(() => C);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [def]);
+    // Write-back setter scoped to THIS node. Bidirectional inputs use
+    // useWriteBack(propName)(next) to push user input through the resolver.
+    // Silently no-ops if the named prop isn't a DataBinding.
+    const writeBack = useCallback((propName, next) => {
+        const original = node[propName];
+        if (original === null ||
+            typeof original !== 'object' ||
+            !('path' in original)) {
+            return;
+        }
+        try {
+            writeDynamic(original, dataContext, scena, next);
+        }
+        catch (err) {
+            console.warn(`[scena.write] prop "${propName}" not writable:`, err);
+        }
+    }, [node, dataContext, scena]);
+    const subsRef = useRef([]);
+    useEffect(() => {
+        subsRef.current.forEach((d) => d.dispose());
+        const paths = new Set();
+        collectPaths(node, mountKey, dataContext, paths);
+        subsRef.current = [...paths].map((p) => scena.store.subscribe(p, () => force()));
+        return () => {
+            subsRef.current.forEach((d) => d.dispose());
+            subsRef.current = [];
+        };
+    }, [node, scena, mountKey, dataContext]);
+    // Component mount lifecycle — runs once per mounted instance; the returned
+    // function (if any) runs on unmount. Lets a component (esp. a template) set
+    // up timers / event subscriptions / store seeding. See ComponentMountHandler.
+    useEffect(() => {
+        if (!def?.onMount)
+            return;
+        const cleanup = def.onMount({ scena, store: scena.store, mountKey, dataContext });
+        return typeof cleanup === 'function' ? cleanup : undefined;
+    }, [def, scena, mountKey, dataContext]);
+    if (!def) {
+        return (_jsxs("span", { className: "oo-missing", title: `No component registered for "${node.component}"`, children: ["[", node.component, "]"] }));
+    }
+    if (def.renderer.kind === 'template') {
+        return _jsx(ViewMount, { node: def.renderer.template });
+    }
+    const props = resolveProps(node, scena, mountKey, dataContext);
+    if (def.renderer.kind === 'html') {
+        return _jsx(HtmlMount, { def: def, props: props });
+    }
+    if (!LoadedComponent) {
+        return (_jsxs("span", { className: "oo-loading-dots", "aria-busy": "true", children: [_jsx("span", {}), _jsx("span", {}), _jsx("span", {})] }));
+    }
+    // `children` prop becomes React children; everything else stays as a prop.
+    const { children: childrenProp, ...rest } = props;
+    return (_jsx(WriteContext.Provider, { value: writeBack, children: _jsx(LoadedComponent, { ...rest, children: childrenProp }) }));
+}
+function resolveProps(node, scena, mountKey, dataContext) {
+    const out = {};
+    for (const [k, v] of Object.entries(node)) {
+        if (RESERVED_KEYS.has(k))
+            continue;
+        out[k] = resolveProp(v, scena, mountKey, dataContext);
+    }
+    return out;
+}
+function HtmlMount({ def, props, }) {
+    const hostRef = useRef(null);
+    const disposableRef = useRef(null);
+    useEffect(() => {
+        if (!hostRef.current)
+            return;
+        if (def.renderer.kind !== 'html')
+            return;
+        disposableRef.current?.dispose();
+        disposableRef.current = def.renderer.mount(hostRef.current, props);
+        return () => {
+            disposableRef.current?.dispose();
+            disposableRef.current = null;
+        };
+    }, [def, props]);
+    return _jsx("div", { ref: hostRef });
+}
+export function MountWrapper({ mountKey, dataContext, children, }) {
+    return (_jsx(MountContext.Provider, { value: mountKey, children: _jsx(DataContextContext.Provider, { value: dataContext, children: children }) }));
+}

package/dist/react/core.d.ts

@@ -0,0 +1,6 @@
+export { Scena } from './Scena.js';
+export { ScenaProvider, useScena } from './ScenaProvider.js';
+export { useI18n } from './hooks/useI18n.js';
+export type { UseI18nResult } from './hooks/useI18n.js';
+export { Translate, Translate as T } from './Translate.js';
+export type { TranslateProps } from './Translate.js';

package/dist/react/core.js

@@ -0,0 +1,10 @@
+// Barrel-free boot entry for the React runtime. Just the provider + hook the
+// app shell needs to mount Scena — importing this does NOT pull the heavy
+// renderers (ViewMount, SurfaceArea, ShellSplitter, DefaultShell) that the full
+// '@softov/scena/react' barrel re-exports. Those load via the barrel only
+// once the shell actually renders (post-login / on first surface).
+export { Scena } from './Scena.js';
+export { ScenaProvider, useScena } from './ScenaProvider.js';
+// i18n hook + <Translate> (alias <T>) — narrow entry (registry-only).
+export { useI18n } from './hooks/useI18n.js';
+export { Translate, Translate as T } from './Translate.js';

package/dist/react/hooks/useCommand.d.ts

@@ -0,0 +1 @@
+export declare function useCommand(id: string): (args?: unknown) => Promise<unknown>;

package/dist/react/hooks/useCommand.js

@@ -0,0 +1,6 @@
+import { useCallback } from 'react';
+import { useScena } from '../ScenaProvider.js';
+export function useCommand(id) {
+    const scena = useScena();
+    return useCallback((args) => scena.commands.execute(id, args), [scena, id]);
+}

package/dist/react/hooks/useI18n.d.ts

@@ -0,0 +1,9 @@
+import { type LocaleInfo, type TranslateOptions } from '../../i18n/registry.js';
+export interface UseI18nResult {
+    t: (key: string, fallbackOrOptions?: string | TranslateOptions) => string;
+    locale: string;
+    info: LocaleInfo | undefined;
+    locales: LocaleInfo[];
+    setLocale: (locale: string) => void;
+}
+export declare function useI18n(namespace?: string): UseI18nResult;

package/dist/react/hooks/useI18n.js

@@ -0,0 +1,16 @@
+import { useCallback, useSyncExternalStore } from 'react';
+import { subscribeI18n, getLocale, getLocaleInfo, listLocaleInfo, translate, setLocale, } from '../../i18n/registry.js';
+// Reactive translation for hand-written React. Subscribes to the i18n registry,
+// so the component re-renders on locale switch / message registration. Optional
+// `namespace` is prefixed to every key. For declarative ComponentNodes, bind
+// `{ path: '$/t/<key>' }` instead (served by the i18n ScopeBackend).
+export function useI18n(namespace) {
+    const locale = useSyncExternalStore(subscribeI18n, getLocale, getLocale);
+    const t = useCallback((key, fallbackOrOptions) => translate(namespace ? `${namespace}/${key}` : key, fallbackOrOptions), 
+    // `locale` is deliberately a dependency even though `translate` reads it
+    // internally: consumers memoize on `t`, so its identity must change on a
+    // locale switch or they render stale translations.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [namespace, locale]);
+    return { t, locale, info: getLocaleInfo(locale), locales: listLocaleInfo(), setLocale };
+}

package/dist/react/hooks/useLabel.d.ts

@@ -0,0 +1,2 @@
+import type { Label } from '../../types/label.js';
+export declare function useLabel(label?: Label): string;

package/dist/react/hooks/useLabel.js

@@ -0,0 +1,19 @@
+import { useStore } from './useStore.js';
+import { useI18n } from './useI18n.js';
+import { translate } from '../../i18n/registry.js';
+// Resolve a Label (string | { path } | { t }) reactively: `{ path }` follows the
+// store, `{ t }` follows the locale, a string is returned as-is.
+export function useLabel(label) {
+    const path = label && typeof label === 'object' && 'path' in label ? label.path : undefined;
+    const bound = useStore(path);
+    useI18n(); // subscribe so `{ t }` re-resolves on locale switch
+    if (label == null)
+        return '';
+    if (typeof label === 'string')
+        return label;
+    if ('t' in label)
+        return translate(label.t);
+    if ('path' in label)
+        return bound == null ? '' : String(bound);
+    return '';
+}

package/dist/react/hooks/useLayout.d.ts

@@ -0,0 +1,2 @@
+import type { ScenaLayout } from '../../types/layout.js';
+export declare function useLayout(): ScenaLayout;

package/dist/react/hooks/useLayout.js

@@ -0,0 +1,10 @@
+import { useSyncExternalStore } from 'react';
+import { useScena } from '../ScenaProvider.js';
+const EMPTY = { surfaces: {} };
+export function useLayout() {
+    const scena = useScena();
+    return useSyncExternalStore((onChange) => {
+        const sub = scena.layout.subscribe(() => onChange());
+        return () => sub.dispose();
+    }, () => scena.layout.get(), () => EMPTY);
+}

package/dist/react/hooks/useMounts.d.ts

@@ -0,0 +1,2 @@
+import type { ResolvedMount, SurfaceName } from '../../types/mount-surface.js';
+export declare function useMounts(surface: SurfaceName): ResolvedMount[];

package/dist/react/hooks/useMounts.js

@@ -0,0 +1,17 @@
+import { useEffect, useState } from 'react';
+import { useScena } from '../ScenaProvider.js';
+export function useMounts(surface) {
+    const scena = useScena();
+    const [mounts, setMounts] = useState(() => scena.surfaces.listAt(surface));
+    useEffect(() => {
+        const refresh = () => setMounts(scena.surfaces.listAt(surface));
+        refresh();
+        const subs = [
+            scena.events.on('scena:mount:opened', refresh),
+            scena.events.on('scena:mount:closed', refresh),
+            scena.events.on('scena:mount:focused', refresh),
+        ];
+        return () => subs.forEach((s) => s.dispose());
+    }, [scena, surface]);
+    return mounts;
+}

package/dist/react/hooks/useStore.d.ts

@@ -0,0 +1,3 @@
+import type { BindingPath } from '../../types/component-graph.js';
+export declare function useStore<T = unknown>(path: BindingPath | undefined, dataContextOverride?: BindingPath): T | undefined;
+export declare function useStoreSetter(): (path: BindingPath, value: unknown) => void;

package/dist/react/hooks/useStore.js

@@ -0,0 +1,40 @@
+import { useMemo, useSyncExternalStore } from 'react';
+import { useScena } from '../ScenaProvider.js';
+import { useCurrentMountKey, useDataContext } from '../mount-context.js';
+import { rewriteLocal } from '../../core/reactive-store.js';
+import { joinAbsolute, readPath } from '../../core/path-resolver.js';
+function resolveForRead(path, mountKey, dataContext) {
+    if (path.startsWith('/') && !path.startsWith('$/')) {
+        return joinAbsolute(dataContext, path);
+    }
+    return rewriteLocal(path, mountKey);
+}
+export function useStore(path, 
+// Override the data context for resolving relative (`/…`) paths. Used by
+// layouts that render a mount's title outside its ViewMount provider (the tab
+// strip), passing the mount's own dataContext so `/name` resolves correctly.
+dataContextOverride) {
+    const scena = useScena();
+    const mountKey = useCurrentMountKey();
+    const providerContext = useDataContext();
+    const dataContext = dataContextOverride ?? providerContext;
+    // Resolve to `null` when the caller passes no path. Hooks below must still
+    // run (rules of hooks) — they just become no-ops via the null guard so
+    // consumers can do `useStore(cond ? path : undefined)` safely.
+    const resolved = useMemo(() => (path === undefined ? null : resolveForRead(path, mountKey, dataContext)), [path, mountKey, dataContext]);
+    return useSyncExternalStore((onChange) => {
+        if (resolved === null)
+            return () => undefined;
+        const sub = scena.store.subscribe(resolved, () => onChange());
+        return () => sub.dispose();
+    }, () => (resolved === null ? undefined : readPath(scena.store, undefined, resolved)), () => undefined);
+}
+export function useStoreSetter() {
+    const scena = useScena();
+    const mountKey = useCurrentMountKey();
+    const dataContext = useDataContext();
+    return (path, value) => {
+        const resolved = resolveForRead(path, mountKey, dataContext);
+        scena.store.set(resolved, value);
+    };
+}

package/dist/react/hooks/useStoreLabel.d.ts

@@ -0,0 +1,3 @@
+import { BindingPath } from '../../types/component-graph.js';
+import { Label } from '../../types/label.js';
+export declare function useStoreLabel(value: Label | undefined, fallback?: string, dataContext?: BindingPath): string;

package/dist/react/hooks/useStoreLabel.js

@@ -0,0 +1,25 @@
+import { translate } from '../../i18n/registry.js';
+import { useStore } from './useStore.js';
+const EMPTY_LABEL_PATH = '$/__label__/empty';
+export function useStoreLabel(value, fallback = '', dataContext) {
+    const path = value && typeof value === 'object' && 'path' in value
+        ? value.path
+        : EMPTY_LABEL_PATH;
+    // Always call the hook (rules of hooks). For non-path labels it reads a dummy
+    // path and the result is ignored below. dataContext resolves relative (`/…`)
+    // title paths against the mount's record root.
+    const stored = useStore(path, dataContext);
+    if (typeof value === 'string') {
+        return value;
+    }
+    if (!value) {
+        return fallback;
+    }
+    if ('path' in value) {
+        return stored ?? fallback;
+    }
+    if ('t' in value) {
+        return translate(value.t, fallback);
+    }
+    return fallback;
+}

package/dist/react/hooks/useSurfacePresentation.d.ts

@@ -0,0 +1,4 @@
+import type { SurfaceName } from '../../types/mount-surface.js';
+import type { SurfacePresentation } from '../../types/layout.js';
+import { type PresentationPolicy } from '../../core/surface-presentation.js';
+export declare function useSurfacePresentation(surface: SurfaceName, policy?: PresentationPolicy): SurfacePresentation;

package/dist/react/hooks/useSurfacePresentation.js

@@ -0,0 +1,16 @@
+import { resolveSurfacePresentation, } from '../../core/surface-presentation.js';
+import { useStore } from './useStore.js';
+// Reads `$/modus/class` and maps it to how this surface should occupy space.
+//
+// `policy` is the app's, not scena's — see surface-presentation.ts. Omitted, or
+// with the modus backend unregistered, every surface stays `docked`, which is
+// exactly the behavior before presentation existed.
+//
+// The backend is registered by the app:
+//   { scope: 'modus', create: () => createModusBackend() }
+export function useSurfacePresentation(surface, policy) {
+    const modus = useStore('$/modus/class');
+    if (!modus)
+        return 'docked';
+    return resolveSurfacePresentation(surface, modus, policy);
+}

package/dist/react/index.d.ts

@@ -0,0 +1,20 @@
+export { Scena } from './Scena.js';
+export { ScenaProvider, useScena } from './ScenaProvider.js';
+export { DefaultShell } from './DefaultShell.js';
+export { ViewMount, MountWrapper } from './ViewMount.js';
+export { ShellSplitter } from './ShellSplitter.js';
+export { SurfaceArea } from './SurfaceArea.js';
+export type { SurfaceAreaProps } from './SurfaceArea.js';
+export { useSurfaceResize } from './useSurfaceResize.js';
+export type { SurfaceResizeSpec, SurfaceResizeBinding } from './useSurfaceResize.js';
+export { MountContext, DataContextContext, WriteContext, useCurrentMountKey, useDataContext, useWriteBack, } from './mount-context.js';
+export { useStore, useStoreSetter } from './hooks/useStore.js';
+export { useI18n } from './hooks/useI18n.js';
+export type { UseI18nResult } from './hooks/useI18n.js';
+export { useLabel } from './hooks/useLabel.js';
+export { Translate, Translate as T } from './Translate.js';
+export type { TranslateProps } from './Translate.js';
+export { useCommand } from './hooks/useCommand.js';
+export { useLayout } from './hooks/useLayout.js';
+export { useMounts } from './hooks/useMounts.js';
+export { useSurfacePresentation } from './hooks/useSurfacePresentation.js';

package/dist/react/index.js

@@ -0,0 +1,20 @@
+export { Scena } from './Scena.js';
+export { ScenaProvider, useScena } from './ScenaProvider.js';
+export { DefaultShell } from './DefaultShell.js';
+export { ViewMount, MountWrapper } from './ViewMount.js';
+export { ShellSplitter } from './ShellSplitter.js';
+export { SurfaceArea } from './SurfaceArea.js';
+// The two resize models. `ShellSplitter` is an element the shell places between
+// surfaces; `useSurfaceResize` (reached through SurfaceArea's `resize` prop, or
+// directly for a custom surface component) puts the grip on the surface's own
+// edge. A shell picks one per surface.
+export { useSurfaceResize } from './useSurfaceResize.js';
+export { MountContext, DataContextContext, WriteContext, useCurrentMountKey, useDataContext, useWriteBack, } from './mount-context.js';
+export { useStore, useStoreSetter } from './hooks/useStore.js';
+export { useI18n } from './hooks/useI18n.js';
+export { useLabel } from './hooks/useLabel.js';
+export { Translate, Translate as T } from './Translate.js';
+export { useCommand } from './hooks/useCommand.js';
+export { useLayout } from './hooks/useLayout.js';
+export { useMounts } from './hooks/useMounts.js';
+export { useSurfacePresentation } from './hooks/useSurfacePresentation.js';

package/dist/react/mount-context.d.ts

@@ -0,0 +1,8 @@
+import type { BindingPath } from '../types/component-graph.js';
+export declare const MountContext: import("react").Context<string | null>;
+export declare function useCurrentMountKey(): string | null;
+export declare const DataContextContext: import("react").Context<BindingPath | undefined>;
+export declare function useDataContext(): BindingPath | undefined;
+export type WriteBack = (propName: string, next: unknown) => void;
+export declare const WriteContext: import("react").Context<WriteBack | null>;
+export declare function useWriteBack(propName: string): (next: unknown) => void;