@softov/scena 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luiz Fernando Softov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,42 @@
+# @softov/scena
+
+Graph-mounted reactive UI runtime.
+
+Scena renders UI from data, not from hand-written component trees.
+A page is a graph of component nodes held in a layered reactive store; components resolve through a late-binding registry and mount lazily.
+
+> Status: pre-1.0. The public surface is still moving.
+
+## Install
+
+```bash
+pnpm add @softov/scena
+```
+
+React is an optional peer dependency - the core runtime and store work without it:
+
+```bash
+pnpm add react react-dom
+```
+
+## Entry points
+
+| Import | Contents |
+| --- | --- |
+| `@softov/scena` | Core runtime and reactive store |
+| `@softov/scena/types` | Contracts and type definitions |
+| `@softov/scena/react` | React bindings (full barrel) |
+| `@softov/scena/react/core` | Narrow boot entry - provider and hook only |
+| `@softov/scena/ui` | All UI components |
+| `@softov/scena/ui/builtins` | Registry catalog, no component code |
+| `@softov/scena/ui/<section>` | One section: `forms`, `layout`, `display`, `control`, `data`, `navigation`, `media`, `overlay`, `chart`, `menu`, `campus` |
+| `@softov/scena/styles` | Stylesheets and themes |
+| `@softov/scena/runtime` | Runtime helpers |
+| `@softov/scena/porta` | Auth gate - login UI and provider registry |
+
+Prefer the narrow entries (`/react/core`, `/ui/builtins`, `/ui/<section>`) over the
+barrels in application code - the barrels pull in every component.
+
+## License
+
+MIT

package/dist/controls/command.d.ts

@@ -0,0 +1,18 @@
+import type { EventBus } from '../types/events.js';
+import type { ReactiveStore, SocketBridge } from '../types/reactive-store.js';
+import type { MountSurfaceRegistry } from '../types/mount-surface.js';
+import type { CommandRegistry } from '../types/command.js';
+import type { WhenEngine } from '../types/when.js';
+import type { Scena } from '../types/scena.js';
+import type { KeybindingRegistry } from '../types/keybinding.js';
+interface Deps {
+    events: EventBus;
+    store: ReactiveStore;
+    surfaces: MountSurfaceRegistry;
+    when: WhenEngine;
+    socket?: SocketBridge;
+    keybindings: KeybindingRegistry;
+    getScena: () => Scena;
+}
+export declare function createCommandRegistry(deps: Deps): CommandRegistry;
+export {};

package/dist/controls/command.js

@@ -0,0 +1,150 @@
+import { disposableFrom } from '../core/disposable.js';
+import { validateArgs } from '../runtime/args-schema.js';
+export function createCommandRegistry(deps) {
+    const { events, store, surfaces, when, socket, keybindings, getScena } = deps;
+    const commands = new Map();
+    function announce() {
+        events.emit('scena:registry:changed', { registry: 'commands' });
+    }
+    function dispatchModeOf(cmd) {
+        if (cmd.dispatch)
+            return cmd.dispatch;
+        return cmd.run ? 'client' : 'remote';
+    }
+    function contextFor(source, opts) {
+        const scena = getScena();
+        return {
+            scena,
+            store,
+            surfaces,
+            commands: scena.commands,
+            events,
+            source,
+            dataContext: opts?.dataContext,
+            host: opts?.host,
+        };
+    }
+    async function runRemote(id, args) {
+        if (!socket) {
+            throw new Error(`Cannot execute remote command "${id}": no socket bridge configured. ` +
+                `Pass a SocketBridge via createScena options or provide a local 'run' on the command.`);
+        }
+        socket.emit('command:execute', { commandId: id, args: [args] });
+        return undefined;
+    }
+    async function executeFrom(source, id, args, opts) {
+        const cmd = commands.get(id);
+        if (!cmd)
+            throw new Error(`Command "${id}" not registered`);
+        // NOTE: cmd.when is intentionally NOT gated here. `when` filters menu
+        // visibility (via commands.list({enabled:true})), not invocability. A
+        // command shown as enabled and then becoming disabled mid-dispatch is
+        // a logic error in the caller — the run() body is responsible for any
+        // last-mile guard it actually needs.
+        let normalizedArgs = args;
+        if (cmd.args) {
+            const result = validateArgs(cmd.args, args);
+            if (!result.ok) {
+                throw new Error(`Command "${id}" args invalid: ${result.errors.join('; ')}`);
+            }
+            normalizedArgs = result.value;
+        }
+        const mode = dispatchModeOf(cmd);
+        if (mode === 'remote')
+            return runRemote(id, normalizedArgs);
+        if (mode === 'either' && !cmd.run)
+            return runRemote(id, normalizedArgs);
+        if (!cmd.run)
+            throw new Error(`Command "${id}" has no local 'run'`);
+        return cmd.run(contextFor(source, { ...opts, source }), normalizedArgs);
+    }
+    // Title resolver for q matching — dynamic titles get a minimal stub ctx.
+    function resolveTitle(cmd) {
+        if (typeof cmd.title === 'string')
+            return cmd.title;
+        try {
+            return cmd.title(contextFor('programmatic'));
+        }
+        catch {
+            return cmd.id;
+        }
+    }
+    function matchesQuery(cmd, q) {
+        if (!q)
+            return true;
+        const needle = q.toLowerCase();
+        if (cmd.id.toLowerCase().includes(needle))
+            return true;
+        if (resolveTitle(cmd).toLowerCase().includes(needle))
+            return true;
+        if (cmd.keywords?.some((k) => k.toLowerCase().includes(needle)))
+            return true;
+        const shortcuts = Array.isArray(cmd.shortcut)
+            ? cmd.shortcut
+            : cmd.shortcut !== undefined
+                ? [cmd.shortcut]
+                : [];
+        if (shortcuts.some((s) => s.toLowerCase().includes(needle)))
+            return true;
+        return false;
+    }
+    function list(filter) {
+        let out = [...commands.values()];
+        if (filter?.category)
+            out = out.filter((c) => c.category === filter.category);
+        if (filter?.slot) {
+            const slots = Array.isArray(filter.slot) ? filter.slot : [filter.slot];
+            // commands.values() iteration order is insertion order, so the array
+            // is naturally deduplicated by id even when a command lists multiple
+            // matching slots (no need to track seen ids here).
+            out = out.filter((c) => c.slots?.some((s) => slots.includes(s)));
+        }
+        if (filter?.enabled !== undefined) {
+            out = out.filter((c) => {
+                const enabled = c.when === undefined || when.evaluate(c.when);
+                return enabled === filter.enabled;
+            });
+        }
+        if (filter?.q) {
+            const q = filter.q;
+            out = out.filter((c) => matchesQuery(c, q));
+        }
+        return out;
+    }
+    return {
+        register(cmd) {
+            commands.set(cmd.id, cmd);
+            const kbDisposables = [];
+            if (cmd.keys !== undefined) {
+                const keysList = Array.isArray(cmd.keys) ? cmd.keys : [cmd.keys];
+                for (const keys of keysList) {
+                    kbDisposables.push(keybindings.register({ keys, commandId: cmd.id, when: cmd.when }));
+                }
+            }
+            announce();
+            return disposableFrom(() => {
+                if (commands.get(cmd.id) === cmd) {
+                    commands.delete(cmd.id);
+                    for (const d of kbDisposables)
+                        d.dispose();
+                    announce();
+                }
+            });
+        },
+        unregister(id) {
+            if (commands.delete(id))
+                announce();
+        },
+        get(id) {
+            return commands.get(id);
+        },
+        list,
+        listEnabled(filter) {
+            return list({ ...filter, enabled: true });
+        },
+        execute(id, args, opts) {
+            return executeFrom(opts?.source ?? 'programmatic', id, args, opts);
+        },
+        executeFrom,
+    };
+}

package/dist/controls/events.d.ts

@@ -0,0 +1,3 @@
+import type { EventBus, ScenaEventMap } from '../types/events.js';
+export declare function createEventBus(): EventBus;
+export type { ScenaEventMap };

package/dist/controls/events.js

@@ -0,0 +1,43 @@
+import { disposableFrom } from '../core/disposable.js';
+export function createEventBus() {
+    const subs = new Map();
+    function emit(event, payload) {
+        const set = subs.get(event);
+        if (!set || set.size === 0)
+            return;
+        for (const fn of [...set]) {
+            try {
+                fn(payload);
+            }
+            catch (err) {
+                console.error(`[scena.events] listener for "${event}" threw:`, err);
+            }
+        }
+    }
+    function on(event, fn) {
+        let set = subs.get(event);
+        if (!set) {
+            set = new Set();
+            subs.set(event, set);
+        }
+        set.add(fn);
+        return disposableFrom(() => {
+            set.delete(fn);
+            if (set.size === 0)
+                subs.delete(event);
+        });
+    }
+    function off(event, fn) {
+        const set = subs.get(event);
+        if (!set)
+            return;
+        set.delete(fn);
+        if (set.size === 0)
+            subs.delete(event);
+    }
+    return {
+        emit: emit,
+        on: on,
+        off,
+    };
+}

package/dist/controls/index.d.ts

@@ -0,0 +1,10 @@
+export { createEventBus } from './events.js';
+export { createWhenEngine } from './when.js';
+export { createCommandRegistry } from './command.js';
+export { createKeybindingRegistry } from './keybinding.js';
+export { createLayoutAPI, createLayoutRegistry } from './layout.js';
+export { createSessionAPI } from './session.js';
+export { createShellRegistry } from './shell.js';
+export { createManifestAPI } from './manifest.js';
+export { createLocalStorageLayoutStorage, createNoopLayoutStorage, } from './storage/layout-local.js';
+export { createLocalStorageSessionStorage } from './storage/session-local.js';

package/dist/controls/index.js

@@ -0,0 +1,10 @@
+export { createEventBus } from './events.js';
+export { createWhenEngine } from './when.js';
+export { createCommandRegistry } from './command.js';
+export { createKeybindingRegistry } from './keybinding.js';
+export { createLayoutAPI, createLayoutRegistry } from './layout.js';
+export { createSessionAPI } from './session.js';
+export { createShellRegistry } from './shell.js';
+export { createManifestAPI } from './manifest.js';
+export { createLocalStorageLayoutStorage, createNoopLayoutStorage, } from './storage/layout-local.js';
+export { createLocalStorageSessionStorage } from './storage/session-local.js';

package/dist/controls/keybinding.d.ts

@@ -0,0 +1,9 @@
+import type { EventBus } from '../types/events.js';
+import type { KeybindingRegistry } from '../types/keybinding.js';
+import type { WhenEngine } from '../types/when.js';
+interface Deps {
+    events: EventBus;
+    when: WhenEngine;
+}
+export declare function createKeybindingRegistry(deps: Deps): KeybindingRegistry;
+export {};

package/dist/controls/keybinding.js

@@ -0,0 +1,94 @@
+import { disposableFrom } from '../core/disposable.js';
+function normalizeKey(input) {
+    return input
+        .trim()
+        .toLowerCase()
+        .replace(/\s*\+\s*/g, '+');
+}
+function eventKeyOf(e) {
+    const parts = [];
+    if (e.ctrlKey)
+        parts.push('ctrl');
+    if (e.altKey)
+        parts.push('alt');
+    if (e.shiftKey)
+        parts.push('shift');
+    if (e.metaKey)
+        parts.push('meta');
+    parts.push(e.key.toLowerCase());
+    return parts.join('+');
+}
+export function createKeybindingRegistry(deps) {
+    const { events, when } = deps;
+    const bindings = [];
+    let chordBuffer = [];
+    let chordTimer = null;
+    function announce() {
+        events.emit('scena:registry:changed', { registry: 'keybindings' });
+    }
+    function clearChord() {
+        chordBuffer = [];
+        if (chordTimer) {
+            clearTimeout(chordTimer);
+            chordTimer = null;
+        }
+    }
+    function specificityOf(b) {
+        // Higher = wins. viewId > surfaceName > none.
+        if (b.scope?.viewId)
+            return 2;
+        if (b.scope?.surfaceName)
+            return 1;
+        return 0;
+    }
+    return {
+        register(binding) {
+            bindings.push(binding);
+            announce();
+            return disposableFrom(() => {
+                const idx = bindings.indexOf(binding);
+                if (idx >= 0) {
+                    bindings.splice(idx, 1);
+                    announce();
+                }
+            });
+        },
+        unregister(keys, commandId) {
+            const normalized = normalizeKey(keys);
+            for (let i = bindings.length - 1; i >= 0; i--) {
+                const b = bindings[i];
+                if (normalizeKey(b.keys) === normalized && b.commandId === commandId) {
+                    bindings.splice(i, 1);
+                }
+            }
+            announce();
+        },
+        list() {
+            return [...bindings];
+        },
+        resolve(event) {
+            chordBuffer.push(eventKeyOf(event));
+            const enabled = bindings.filter((b) => b.when === undefined || when.evaluate(b.when));
+            const currentChord = chordBuffer.join(' ');
+            // Exact match — fire.
+            const matches = enabled.filter((b) => normalizeKey(b.keys) === currentChord);
+            if (matches.length > 0) {
+                matches.sort((a, b) => specificityOf(b) - specificityOf(a));
+                const winner = matches[0];
+                clearChord();
+                return { kind: 'fire', commandId: winner.commandId, args: winner.args };
+            }
+            // Pending — some binding starts with the current chord prefix.
+            const prefix = `${currentChord} `;
+            const partial = enabled.some((b) => normalizeKey(b.keys).startsWith(prefix));
+            if (partial) {
+                if (chordTimer)
+                    clearTimeout(chordTimer);
+                chordTimer = setTimeout(clearChord, 1500);
+                return { kind: 'chord-pending', depth: chordBuffer.length };
+            }
+            clearChord();
+            return { kind: 'none' };
+        },
+    };
+}

package/dist/controls/layout.d.ts

@@ -0,0 +1,16 @@
+import type { EventBus } from '../types/events.js';
+import type { ReactiveStore } from '../types/reactive-store.js';
+import type { LayoutAPI, LayoutRegistry, LayoutStorage, ScenaLayout } from '../types/layout.js';
+interface LayoutDeps {
+    events: EventBus;
+    store: ReactiveStore;
+    initial?: ScenaLayout;
+    storage?: LayoutStorage;
+}
+export declare function createLayoutAPI(deps: LayoutDeps): LayoutAPI & {
+    setStorage(s: LayoutStorage | null): void;
+};
+export declare function createLayoutRegistry(deps: {
+    events: EventBus;
+}): LayoutRegistry;
+export {};

package/dist/controls/layout.js

@@ -0,0 +1,201 @@
+import { disposableFrom } from '../core/disposable.js';
+const DEFAULT_SURFACE_LAYOUTS = {
+    titlebar: { visible: true, layout: 'bar' },
+    activitybar: { visible: true, layout: 'rail' },
+    'sidebar:left': { visible: true, layout: 'single', size: 240 },
+    'sidebar:right': { visible: false, layout: 'stack', size: 280 },
+    main: { visible: true, layout: 'tab' },
+    'panel:bottom': { visible: false, layout: 'tab', size: 200 },
+    statusbar: { visible: true, layout: 'bar' },
+    overlay: { visible: true, layout: 'floating' },
+    detached: { visible: false, layout: 'single' },
+};
+function defaultLayout() {
+    return { surfaces: { ...DEFAULT_SURFACE_LAYOUTS } };
+}
+// Long enough to swallow a gesture, short enough that letting go of a splitter
+// and closing the tab keeps the size.
+const SAVE_DEBOUNCE_MS = 150;
+function applyDeep(base, patch) {
+    if (patch === null || typeof patch !== 'object')
+        return patch;
+    if (Array.isArray(patch))
+        return patch;
+    const out = { ...base };
+    for (const [k, v] of Object.entries(patch)) {
+        out[k] = applyDeep((out[k] ?? {}), v);
+    }
+    return out;
+}
+function surfaceBase(surface) {
+    // Surface names can contain `:` (sidebar:left). Per RFC 6901, `:` is a
+    // legal segment character, so we use it as-is.
+    return `$/layout/surfaces/${surface}`;
+}
+export function createLayoutAPI(deps) {
+    const { events, store } = deps;
+    let storage = deps.storage ?? null;
+    let state = deps.initial
+        ? applyDeep(defaultLayout(), deps.initial)
+        : defaultLayout();
+    const subscribers = new Set();
+    let saveTimer = null;
+    // Only the surfaces that could have changed. `set` and `patch` can touch any
+    // of them and pass nothing; `setSurface` names the one it wrote, which keeps a
+    // splitter drag from re-announcing all nine every frame.
+    function changedSurfaces(only) {
+        if (only !== undefined) {
+            const one = state.surfaces[only];
+            return one ? [[only, one]] : [];
+        }
+        return Object.entries(state.surfaces).filter((entry) => entry[1] !== undefined);
+    }
+    // `store.set` queues a change notification unconditionally, so mirroring a
+    // value back over itself still wakes every subscriber on that path. Most of
+    // what this writes is unchanged on any given call.
+    function setIfChanged(path, value) {
+        if (Object.is(store.get(path), value))
+            return;
+        store.set(path, value);
+    }
+    function mirrorToStore(only) {
+        for (const [surface, surfaceState] of changedSurfaces(only)) {
+            const base = surfaceBase(surface);
+            setIfChanged(`${base}/visible`, surfaceState.visible);
+            if (surfaceState.size !== undefined) {
+                setIfChanged(`${base}/size`, surfaceState.size);
+            }
+            if (surfaceState.layout !== undefined) {
+                setIfChanged(`${base}/layout`, surfaceState.layout);
+            }
+            if (surfaceState.activeContainerKey !== undefined) {
+                setIfChanged(`${base}/activeContainerKey`, surfaceState.activeContainerKey);
+            }
+            if (surfaceState.section !== undefined) {
+                setIfChanged(`${base}/section`, surfaceState.section);
+            }
+            if (surfaceState.split) {
+                setIfChanged(`${base}/split`, surfaceState.split);
+            }
+        }
+    }
+    function mirrorToCss(only) {
+        if (typeof document === 'undefined')
+            return;
+        const root = document.documentElement;
+        for (const [surface, surfaceState] of changedSurfaces(only)) {
+            const slug = surface.replace(':', '-');
+            if (surfaceState.size !== undefined) {
+                root.style.setProperty(`--oo-${slug}-size`, `${surfaceState.size}px`);
+            }
+            root.style.setProperty(`--oo-${slug}-visible`, surfaceState.visible ? '1' : '0');
+        }
+    }
+    // Writing the layout means serialising all of it, so a caller that changes
+    // something per animation frame would otherwise run a synchronous
+    // JSON.stringify + localStorage write on the main thread at 60Hz. Coalesced,
+    // the last value of a burst is the one that lands, which is the only one
+    // anybody wanted saved.
+    function scheduleSave() {
+        if (!storage)
+            return;
+        if (saveTimer !== null)
+            clearTimeout(saveTimer);
+        saveTimer = setTimeout(() => {
+            saveTimer = null;
+            if (storage)
+                void storage.save(state);
+        }, SAVE_DEBOUNCE_MS);
+    }
+    function notify(opts) {
+        events.emit('scena:layout:changed', state);
+        for (const fn of [...subscribers]) {
+            try {
+                fn(state);
+            }
+            catch (err) {
+                console.error('[scena.layout] subscriber threw:', err);
+            }
+        }
+        // The CSS variables move with the gesture: they are one write per changed
+        // property on one element, and a shell that sizes from them rather than
+        // from React state gets the frame for free.
+        mirrorToCss(opts?.surface);
+        // A frame of a drag is not a value anybody should be reading or storing.
+        // The next settled call mirrors and persists whatever it ended on.
+        if (opts?.transient === true)
+            return;
+        mirrorToStore(opts?.surface);
+        scheduleSave();
+    }
+    mirrorToStore();
+    mirrorToCss();
+    if (storage) {
+        void storage.load().then((loaded) => {
+            if (loaded) {
+                state = applyDeep(defaultLayout(), loaded);
+                notify();
+            }
+        });
+    }
+    return {
+        get() {
+            return state;
+        },
+        set(layout) {
+            state = layout;
+            notify();
+        },
+        patch(patch) {
+            state = applyDeep(state, patch);
+            notify();
+        },
+        setSurface(surface, surfaceState, opts) {
+            const current = state.surfaces[surface] ?? { visible: false };
+            state = {
+                ...state,
+                surfaces: {
+                    ...state.surfaces,
+                    [surface]: { ...current, ...surfaceState },
+                },
+            };
+            notify({ surface, ...(opts?.transient === true ? { transient: true } : {}) });
+        },
+        subscribe(fn) {
+            subscribers.add(fn);
+            return disposableFrom(() => subscribers.delete(fn));
+        },
+        setStorage(s) {
+            storage = s;
+        },
+    };
+}
+export function createLayoutRegistry(deps) {
+    const { events } = deps;
+    const layouts = new Map();
+    function announce() {
+        events.emit('scena:registry:changed', { registry: 'layouts' });
+    }
+    return {
+        register(layout) {
+            layouts.set(layout.id, layout);
+            announce();
+            return disposableFrom(() => {
+                if (layouts.get(layout.id) === layout) {
+                    layouts.delete(layout.id);
+                    announce();
+                }
+            });
+        },
+        unregister(id) {
+            if (layouts.delete(id))
+                announce();
+        },
+        get(id) {
+            return layouts.get(id);
+        },
+        list() {
+            return [...layouts.values()];
+        },
+    };
+}

package/dist/controls/manifest.d.ts

@@ -0,0 +1,21 @@
+import type { EventBus } from '../types/events.js';
+import type { ReactiveStore } from '../types/reactive-store.js';
+import type { ComponentRegistry } from '../types/component-registry.js';
+import type { CommandRegistry } from '../types/command.js';
+import type { KeybindingRegistry } from '../types/keybinding.js';
+import type { MountSurfaceRegistry } from '../types/mount-surface.js';
+import type { ConverterRegistry } from '../types/converter-registry.js';
+import type { PermissionEngine } from '../types/permissions.js';
+import type { ManifestAPI } from '../types/manifest.js';
+interface Deps {
+    events: EventBus;
+    store: ReactiveStore;
+    components: ComponentRegistry;
+    commands: CommandRegistry;
+    keybindings: KeybindingRegistry;
+    surfaces: MountSurfaceRegistry;
+    converters: ConverterRegistry;
+    permissions: PermissionEngine;
+}
+export declare function createManifestAPI(deps: Deps): ManifestAPI;
+export {};