@softov/scena 0.1.2

package/dist/core/dynamic-resolver.js

@@ -0,0 +1,134 @@
+import { isAction, isDataBinding, isFunctionCall, } from '../types/component-graph.js';
+import { readPath, writePath } from './path-resolver.js';
+// Resolves a DynamicValue to its concrete value.
+//   literal       → returned as-is
+//   DataBinding   → store.get(joinAbsolute(dataCtx, path))
+//   FunctionCall  → look up command, resolve args, invoke run() synchronously
+export function resolveDynamicValue(value, dataContext, scena) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (isDataBinding(value)) {
+        return readPath(scena.store, dataContext, value.path);
+    }
+    if (isFunctionCall(value)) {
+        return resolveFunctionCall(value, dataContext, scena);
+    }
+    return value;
+}
+function resolveArgs(args, dataContext, scena) {
+    if (!args)
+        return {};
+    const out = {};
+    for (const [k, v] of Object.entries(args)) {
+        out[k] = resolveDynamicValue(v, dataContext, scena);
+    }
+    return out;
+}
+function valueCallContext(scena) {
+    return {
+        scena,
+        store: scena.store,
+        surfaces: scena.surfaces,
+        commands: scena.commands,
+        events: scena.events,
+        source: 'graph',
+    };
+}
+// Synchronous FunctionCall resolution — bypasses the async command bus so
+// `{ call: 'required', args: {...} }` returns a value, not a Promise.
+//
+// The command bus (`scena.commands.executeFrom`) is for fire-and-forget
+// dispatch (palette, menu, keybinding). FunctionCall as a DynamicValue source
+// needs a real value back in the same render tick.
+export function resolveFunctionCall(fc, dataContext, scena) {
+    const cmd = scena.commands.get(fc.call);
+    if (!cmd) {
+        if (fc.callableFrom === 'clientOnly') {
+            throw new Error(`FunctionCall "${fc.call}" callableFrom=clientOnly has no registered handler`);
+        }
+        throw new Error(`FunctionCall "${fc.call}" not registered`);
+    }
+    if (!cmd.run) {
+        throw new Error(`FunctionCall "${fc.call}" has no client run — remote-only commands ` +
+            `cannot serve as DynamicValue sources`);
+    }
+    const args = resolveArgs(fc.args, dataContext, scena);
+    return cmd.run(valueCallContext(scena), args);
+}
+// Async dispatch — used by Action.functionCall (click handlers). Returns
+// a Promise so awaitable side-effects work as expected.
+function dispatchFunctionCall(fc, dataContext, scena) {
+    const args = resolveArgs(fc.args, dataContext, scena);
+    return scena.commands.executeFrom('graph', fc.call, args);
+}
+function narrow(value, predicate, expected) {
+    if (predicate(value))
+        return value;
+    throw new Error(`Dynamic value type mismatch: expected ${expected}, got ${typeof value}`);
+}
+export function resolveDynamicString(v, dataContext, scena) {
+    if (typeof v === 'string')
+        return v;
+    const resolved = resolveDynamicValue(v, dataContext, scena);
+    return narrow(resolved, (x) => typeof x === 'string', 'string');
+}
+export function resolveDynamicNumber(v, dataContext, scena) {
+    if (typeof v === 'number')
+        return v;
+    const resolved = resolveDynamicValue(v, dataContext, scena);
+    return narrow(resolved, (x) => typeof x === 'number', 'number');
+}
+export function resolveDynamicBoolean(v, dataContext, scena) {
+    if (typeof v === 'boolean')
+        return v;
+    const resolved = resolveDynamicValue(v, dataContext, scena);
+    return narrow(resolved, (x) => typeof x === 'boolean', 'boolean');
+}
+export function resolveDynamicStringList(v, dataContext, scena) {
+    if (Array.isArray(v) && v.every((x) => typeof x === 'string'))
+        return v;
+    const resolved = resolveDynamicValue(v, dataContext, scena);
+    return narrow(resolved, (x) => Array.isArray(x) && x.every((y) => typeof y === 'string'), 'string[]');
+}
+// Returns a 0-arg async callable that performs the Action when invoked.
+//   { event: { name, context, ... } }  → emits 'scena:action:event' on the bus
+//   { functionCall: { call, args } }   → dispatches through the command bus
+export function resolveAction(action, dataContext, scena, mountKey) {
+    if ('functionCall' in action) {
+        const fc = action.functionCall;
+        return () => dispatchFunctionCall(fc, dataContext, scena);
+    }
+    const ev = action.event;
+    return async () => {
+        const resolvedContext = ev.context
+            ? Object.fromEntries(Object.entries(ev.context).map(([k, v]) => [
+                k,
+                resolveDynamicValue(v, dataContext, scena),
+            ]))
+            : undefined;
+        scena.events.emit('scena:action:event', {
+            mountKey,
+            name: ev.name,
+            context: resolvedContext,
+            wantResponse: ev.wantResponse,
+            responsePath: ev.responsePath,
+        });
+    };
+}
+// Write-back for bidirectional widgets. Accepts only DataBinding form;
+// throws on FunctionCall, on `#/` indirection, and on wildcard paths.
+export function writeDynamic(value, dataContext, scena, next) {
+    if (!isDataBinding(value)) {
+        if (isFunctionCall(value)) {
+            throw new Error('writeDynamic: FunctionCall values are read-only');
+        }
+        if (isAction(value)) {
+            throw new Error('writeDynamic: Action values are not writable');
+        }
+        throw new Error('writeDynamic: only DataBinding values are writable');
+    }
+    writePath(scena.store, dataContext, value.path, next);
+}
+export function isWritableDynamic(v) {
+    return isDataBinding(v);
+}

package/dist/core/index.d.ts

@@ -0,0 +1,44 @@
+export * from '../types/index.js';
+export { combineDisposables, disposableFrom } from './disposable.js';
+export { walk, clone, addIds, findById, stripMeta } from './component-graph.js';
+export { createPermissionEngine } from './permissions.js';
+export { createReactiveStore, localPath, rewriteLocal, clearMountLocal, } from './reactive-store.js';
+export { createBindingResolver } from './binding-resolver.js';
+export { resolveLabel } from './label.js';
+export { createStorageBackend, createLocalStorageStorage, } from './backends/storage-backend.js';
+export type { BackendStorage } from './backends/storage-backend.js';
+export { createModusBackend, DEFAULT_MODUS_BREAKPOINTS, } from './backends/modus-backend.js';
+export type { ModusClass, ModusBreakpoints, ModusBackendOptions, } from './backends/modus-backend.js';
+export { resolveSurfacePresentation, isOverlaid } from './surface-presentation.js';
+export type { PresentationPolicy } from './surface-presentation.js';
+export { registerMessages, registerLocale, unregisterMessages, setLocale, getLocale, getLocaleInfo, listLocaleInfo, setFallbackLocale, listLocales, lookup, resolveMessage, translate, allKeys, subscribeI18n, clearMessages, } from '../i18n/registry.js';
+export type { TranslateOptions, MessageTree, LocaleInfo, RegisterMessagesExtra, } from '../i18n/registry.js';
+export { createI18nBackend } from '../i18n/i18n-backend.js';
+export { createComponentRegistry } from './component-registry.js';
+export { createConverterRegistry } from './converter-registry.js';
+export { createMountSurfaceRegistry } from './mount-surface.js';
+export { createScena } from './scena.js';
+export { parsePath, joinAbsolute, joinSegments, hasWildcard, interpolatePath, readPath, writePath, scopeOf, } from './path-resolver.js';
+export { resolveDynamicValue, resolveDynamicString, resolveDynamicNumber, resolveDynamicBoolean, resolveDynamicStringList, resolveFunctionCall, resolveAction, writeDynamic, isWritableDynamic, } from './dynamic-resolver.js';
+export { createEventBus } from '../controls/events.js';
+export { createWhenEngine } from '../controls/when.js';
+export { createCommandRegistry } from '../controls/command.js';
+export { createKeybindingRegistry } from '../controls/keybinding.js';
+export { createLayoutAPI, createLayoutRegistry } from '../controls/layout.js';
+export { createSessionAPI } from '../controls/session.js';
+export { createShellRegistry } from '../controls/shell.js';
+export { createManifestAPI } from '../controls/manifest.js';
+export { createLocalStorageLayoutStorage, createNoopLayoutStorage, } from '../controls/storage/layout-local.js';
+export { createLocalStorageSessionStorage } from '../controls/storage/session-local.js';
+export { validateArgs, isPermissionPath } from '../runtime/args-schema.js';
+export type { ValidateArgsResult } from '../runtime/args-schema.js';
+export { createSurfaceBridge } from '../runtime/surface-bridge.js';
+export { registerClientHandler, getClientHandler, } from '../runtime/client-handlers.js';
+export { createInMemorySocket } from '../runtime/in-memory-socket.js';
+export type { InMemorySocket } from '../runtime/in-memory-socket.js';
+export { registerBuiltinFunctions } from '../runtime/builtins.js';
+export { registerLayoutCommands } from '../runtime/layout-commands.js';
+export { registerOpenerCommands } from '../runtime/opener-commands.js';
+export type { RegisterOpenerCommandsOptions } from '../runtime/opener-commands.js';
+export { a2uiV010Converter } from '../converters/a2ui-v0.10.js';
+export type { A2uiCreateSurface, A2uiComponentSpec, A2uiConverterInput, } from '../converters/a2ui-v0.10.js';

package/dist/core/index.js

@@ -0,0 +1,48 @@
+// Public runtime entry — re-exports the type surface alongside the factory functions.
+export * from '../types/index.js';
+export { combineDisposables, disposableFrom } from './disposable.js';
+export { walk, clone, addIds, findById, stripMeta } from './component-graph.js';
+export { createPermissionEngine } from './permissions.js';
+export { createReactiveStore, localPath, rewriteLocal, clearMountLocal, } from './reactive-store.js';
+export { createBindingResolver } from './binding-resolver.js';
+// Pure Label resolver. `types/label.ts` documents this as the intended way to
+// resolve a Label outside React (useLabel is the reactive counterpart), so it
+// belongs on the public surface.
+export { resolveLabel } from './label.js';
+// Reference ScopeBackend implementations. The Yjs backend is a deep import
+// (`core/backends/yjs-backend.js`) so the barrel never references `yjs`.
+export { createStorageBackend, createLocalStorageStorage, } from './backends/storage-backend.js';
+// `$/modus` — display environment (size class, orientation, pointer accuracy)
+// published as a scope so `when` clauses can gate surfaces on it.
+export { createModusBackend, DEFAULT_MODUS_BREAKPOINTS, } from './backends/modus-backend.js';
+// Maps a `$/modus` size class to how each surface occupies space. The policy
+// is supplied by the app — scena ships the mechanism, not the opinion.
+// `isOverlaid` tells a shell whether to drop the splitter and draw a scrim.
+export { resolveSurfacePresentation, isOverlaid } from './surface-presentation.js';
+// i18n — registry (source of truth + active locale) + the `$/t` ScopeBackend.
+export { registerMessages, registerLocale, unregisterMessages, setLocale, getLocale, getLocaleInfo, listLocaleInfo, setFallbackLocale, listLocales, lookup, resolveMessage, translate, allKeys, subscribeI18n, clearMessages, } from '../i18n/registry.js';
+export { createI18nBackend } from '../i18n/i18n-backend.js';
+export { createComponentRegistry } from './component-registry.js';
+export { createConverterRegistry } from './converter-registry.js';
+export { createMountSurfaceRegistry } from './mount-surface.js';
+export { createScena } from './scena.js';
+export { parsePath, joinAbsolute, joinSegments, hasWildcard, interpolatePath, readPath, writePath, scopeOf, } from './path-resolver.js';
+export { resolveDynamicValue, resolveDynamicString, resolveDynamicNumber, resolveDynamicBoolean, resolveDynamicStringList, resolveFunctionCall, resolveAction, writeDynamic, isWritableDynamic, } from './dynamic-resolver.js';
+export { createEventBus } from '../controls/events.js';
+export { createWhenEngine } from '../controls/when.js';
+export { createCommandRegistry } from '../controls/command.js';
+export { createKeybindingRegistry } from '../controls/keybinding.js';
+export { createLayoutAPI, createLayoutRegistry } from '../controls/layout.js';
+export { createSessionAPI } from '../controls/session.js';
+export { createShellRegistry } from '../controls/shell.js';
+export { createManifestAPI } from '../controls/manifest.js';
+export { createLocalStorageLayoutStorage, createNoopLayoutStorage, } from '../controls/storage/layout-local.js';
+export { createLocalStorageSessionStorage } from '../controls/storage/session-local.js';
+export { validateArgs, isPermissionPath } from '../runtime/args-schema.js';
+export { createSurfaceBridge } from '../runtime/surface-bridge.js';
+export { registerClientHandler, getClientHandler, } from '../runtime/client-handlers.js';
+export { createInMemorySocket } from '../runtime/in-memory-socket.js';
+export { registerBuiltinFunctions } from '../runtime/builtins.js';
+export { registerLayoutCommands } from '../runtime/layout-commands.js';
+export { registerOpenerCommands } from '../runtime/opener-commands.js';
+export { a2uiV010Converter } from '../converters/a2ui-v0.10.js';

package/dist/core/label.d.ts

@@ -0,0 +1,2 @@
+import type { Label, LabelResolveContext } from "../types/label.js";
+export declare function resolveLabel(label: Label | undefined, ctx: LabelResolveContext): string;

package/dist/core/label.js

@@ -0,0 +1,14 @@
+// the useLabel hook (reactive).
+export function resolveLabel(label, ctx) {
+    if (label == null)
+        return '';
+    if (typeof label === 'string')
+        return label;
+    if ('t' in label)
+        return ctx.translate(label.t);
+    if ('path' in label) {
+        const v = ctx.get(label.path);
+        return v == null ? '' : String(v);
+    }
+    return '';
+}

package/dist/core/mount-menu.d.ts

@@ -0,0 +1,2 @@
+import type { MountMenuRegistry } from '../types/mount-menu.js';
+export declare function createMountMenuRegistry(): MountMenuRegistry;

package/dist/core/mount-menu.js

@@ -0,0 +1,23 @@
+import { disposableFrom } from './disposable.js';
+export function createMountMenuRegistry() {
+    const bySlot = new Map();
+    function register(slot, contributor) {
+        let set = bySlot.get(slot);
+        if (!set) {
+            set = new Set();
+            bySlot.set(slot, set);
+        }
+        set.add(contributor);
+        return disposableFrom(() => set.delete(contributor));
+    }
+    function collect(slot, mount) {
+        const set = bySlot.get(slot);
+        if (!set)
+            return [];
+        const out = [];
+        for (const fn of set)
+            out.push(...fn(mount));
+        return out;
+    }
+    return { register, collect };
+}

package/dist/core/mount-surface.d.ts

@@ -0,0 +1,15 @@
+import type { EventBus } from '../types/events.js';
+import type { MountSurfaceRegistry } from '../types/mount-surface.js';
+import type { ComponentRegistry } from '../types/component-registry.js';
+import type { WhenEngine } from '../types/when.js';
+import type { BindingResolver } from '../types/binding-resolver.js';
+import type { ReactiveStore } from '../types/reactive-store.js';
+interface Deps {
+    events: EventBus;
+    when: WhenEngine;
+    bindings: BindingResolver;
+    store: ReactiveStore;
+    components: ComponentRegistry;
+}
+export declare function createMountSurfaceRegistry(deps: Deps): MountSurfaceRegistry;
+export {};

package/dist/core/mount-surface.js

@@ -0,0 +1,214 @@
+import { isDataBinding } from '../types/component-graph.js';
+import { combineDisposables, disposableFrom } from './disposable.js';
+import { clearMountLocal } from './reactive-store.js';
+const MISSING_NODE = {
+    component: 'MissingComponent',
+    reason: 'unbound',
+};
+export function createMountSurfaceRegistry(deps) {
+    const { events, when, store, components } = deps;
+    const mountsByKey = new Map();
+    const visibleByKey = new Set();
+    function resolveTarget(t) {
+        if (isDataBinding(t)) {
+            const value = store.get(t.path);
+            if (!value || typeof value !== 'object' || !('component' in value)) {
+                return MISSING_NODE;
+            }
+            return value;
+        }
+        return t;
+    }
+    function attachTargetSub(internal, target) {
+        if (!isDataBinding(target))
+            return;
+        internal.targetSub?.dispose();
+        internal.targetSub = store.subscribe(target.path, () => {
+            internal.component = resolveTarget(target);
+            if (visibleByKey.has(internal.key)) {
+                events.emit('scena:mount:opened', {
+                    key: internal.key,
+                    surface: internal.surface,
+                    component: internal.component,
+                });
+            }
+        });
+    }
+    function setVisible(key, mount, next) {
+        const was = visibleByKey.has(key);
+        if (next === was)
+            return;
+        if (next) {
+            visibleByKey.add(key);
+            events.emit('scena:mount:opened', {
+                key,
+                surface: mount.surface,
+                component: mount.component,
+            });
+        }
+        else {
+            visibleByKey.delete(key);
+            events.emit('scena:mount:closed', { key });
+        }
+    }
+    function mount(decl) {
+        const internal = {
+            key: decl.key,
+            surface: decl.surface,
+            component: resolveTarget(decl.resource),
+            props: decl.props,
+            policy: decl.policy ?? {},
+            dataContext: decl.dataContext,
+            openedAt: Date.now(),
+            decl,
+        };
+        mountsByKey.set(decl.key, internal);
+        attachTargetSub(internal, decl.resource);
+        let whenSub;
+        if (decl.when !== undefined) {
+            whenSub = when.watch(decl.when, (visible) => setVisible(decl.key, internal, visible));
+        }
+        else {
+            setVisible(decl.key, internal, true);
+        }
+        return combineDisposables(whenSub, disposableFrom(() => {
+            if (mountsByKey.get(decl.key) === internal) {
+                internal.targetSub?.dispose();
+                if (visibleByKey.has(decl.key))
+                    setVisible(decl.key, internal, false);
+                mountsByKey.delete(decl.key);
+                clearMountLocal(store, decl.key);
+            }
+        }));
+    }
+    function open(opts) {
+        const existing = mountsByKey.get(opts.key);
+        if (existing) {
+            existing.surface = opts.surface;
+            existing.policy = opts.policy ?? existing.policy;
+            existing.dataContext = opts.dataContext ?? existing.dataContext;
+            // Re-opening an existing mount with a fresh display overrides;
+            // otherwise we keep what was there so silent re-opens (e.g. focus)
+            // don't drop the title.
+            if (opts.props)
+                existing.props = opts.props;
+            existing.targetSub?.dispose();
+            existing.component = resolveTarget(opts.resource);
+            attachTargetSub(existing, opts.resource);
+            if (!visibleByKey.has(opts.key))
+                setVisible(opts.key, existing, true);
+            focus(opts.key);
+        }
+        else {
+            const internal = {
+                key: opts.key,
+                surface: opts.surface,
+                component: resolveTarget(opts.resource),
+                props: opts.props,
+                policy: opts.policy ?? {},
+                dataContext: opts.dataContext,
+                openedAt: Date.now(),
+            };
+            mountsByKey.set(opts.key, internal);
+            attachTargetSub(internal, opts.resource);
+            setVisible(opts.key, internal, true);
+            focus(opts.key);
+        }
+        return {
+            key: opts.key,
+            surface: opts.surface,
+            close: (closeOpts) => close(opts.key, closeOpts),
+            focus: () => focus(opts.key),
+        };
+    }
+    function openResource(kind, args) {
+        if (!kind)
+            return null;
+        const id = args?.resourceId ?? store.get('$/resource/id');
+        const argsOpts = {
+            ...args?.options,
+        };
+        const extraProps = args?.extraProps ?? {};
+        if (!id)
+            return null;
+        const def = components.findOpeners(kind)[0];
+        if (!def)
+            return null;
+        store.patchMany({
+            '$/resource/kind': kind,
+            '$/resource/id': id,
+            '$/active/kind': kind,
+            '$/active/id': id,
+        });
+        const key = argsOpts?.mountKey ?? `${kind}:${id}`;
+        // Data context = the record root (`$/<namespace>/byId/<id>`), built from the
+        // declared namespace. With it set, `opens.title` and the mounted component's
+        // bindings can be RELATIVE (`{ path: '/name' }`) and resolve against this
+        // record — every open path (row-click, the generic resource.open command,
+        // cross-links) gets the record-name title from one declaration, no per-id
+        // string interpolation.
+        const ns = def.opens?.namespace;
+        const dataContext = ns ? `$/${ns}/byId/${String(id)}` : argsOpts?.dataContext;
+        return open({
+            surface: argsOpts?.surface ?? def.opens?.preferredSurface ?? 'main',
+            key,
+            dataContext,
+            resource: { component: def.component, resourceId: id, ...extraProps },
+            props: {
+                title: argsOpts?.title ?? def.opens?.title,
+                icon: def.opens?.icon,
+                color: def.opens?.color,
+            },
+        });
+    }
+    function close(key, opts) {
+        const mount = mountsByKey.get(key);
+        if (!mount)
+            return;
+        mount.targetSub?.dispose();
+        if (visibleByKey.has(key)) {
+            visibleByKey.delete(key);
+            events.emit('scena:mount:closed', { key, reason: opts?.reason });
+        }
+        mountsByKey.delete(key);
+        clearMountLocal(store, key);
+    }
+    function focus(key) {
+        const m = mountsByKey.get(key);
+        if (!m)
+            return;
+        events.emit('scena:mount:focused', { key, surface: m.surface });
+    }
+    function listAt(surface) {
+        const out = [];
+        for (const m of mountsByKey.values()) {
+            if (m.surface === surface && visibleByKey.has(m.key)) {
+                const { decl: _decl, targetSub: _targetSub, ...resolved } = m;
+                void _decl;
+                void _targetSub;
+                out.push(resolved);
+            }
+        }
+        return out.sort((a, b) => a.openedAt - b.openedAt);
+    }
+    function move(opts) {
+        const m = mountsByKey.get(opts.key);
+        if (!m)
+            return;
+        if (opts.fromSurface && m.surface !== opts.fromSurface)
+            return;
+        if (m.surface === opts.toSurface)
+            return;
+        const prev = m.surface;
+        m.surface = opts.toSurface;
+        if (visibleByKey.has(opts.key)) {
+            events.emit('scena:mount:closed', { key: opts.key, reason: `move:from:${prev}` });
+            events.emit('scena:mount:opened', {
+                key: opts.key,
+                surface: opts.toSurface,
+                component: m.component,
+            });
+        }
+    }
+    return { mount, open, openResource, close, focus, listAt, move };
+}

package/dist/core/path-resolver.d.ts

@@ -0,0 +1,14 @@
+import type { BindingPath } from '../types/component-graph.js';
+import type { ReactiveStore, ScopeName } from '../types/reactive-store.js';
+export interface ParsedPath {
+    absolute: boolean;
+    segments: string[];
+}
+export declare function parsePath(path: string): ParsedPath;
+export declare function scopeOf(path: BindingPath): ScopeName;
+export declare function joinAbsolute(dataContext: BindingPath | undefined, path: BindingPath): BindingPath;
+export declare function joinSegments(segments: string[]): BindingPath;
+export declare function hasWildcard(path: BindingPath): boolean;
+export declare function interpolatePath(store: ReactiveStore, dataContext: BindingPath | undefined, raw: string, depth?: number): string;
+export declare function readPath(store: ReactiveStore, dataContext: BindingPath | undefined, path: BindingPath, depth?: number): unknown;
+export declare function writePath(store: ReactiveStore, dataContext: BindingPath | undefined, path: BindingPath, value: unknown): void;