@softov/scena 0.1.2

package/dist/core/reactive-store.js

@@ -0,0 +1,496 @@
+import { disposableFrom } from './disposable.js';
+import { parsePath, joinSegments, hasWildcard } from './path-resolver.js';
+import { compileSelect } from './computed-dsl.js';
+function makeNode() {
+    return { hasValue: false, value: undefined };
+}
+function isWildcardPath(path) {
+    return path.includes('*');
+}
+function segmentsOf(path) {
+    // Store paths are always absolute ($/scope/...) — relative resolution happens
+    // in the React hooks / resolver before reaching the store. parsePath handles
+    // RFC6901 unescape + `..` rejection.
+    return parsePath(path).segments;
+}
+function nodeEmpty(node) {
+    return (!node.hasValue &&
+        !(node.subscribers && node.subscribers.size) &&
+        !(node.wildSubs && node.wildSubs.length) &&
+        !(node.children && node.children.size));
+}
+function matchPattern(pattern, segs) {
+    if (pattern.length !== segs.length)
+        return false;
+    for (let i = 0; i < pattern.length; i++) {
+        if (pattern[i] !== '*' && pattern[i] !== segs[i])
+            return false;
+    }
+    return true;
+}
+export function createReactiveStore(deps) {
+    const { events } = deps;
+    const root = makeNode();
+    const dataProviders = new Map();
+    const loadedNamespaces = new Set();
+    // scope -> value backend (in-memory tree is the default; absent = use tree)
+    const backends = new Map();
+    const backendFactories = new Map();
+    for (const f of deps.backendFactories ?? [])
+        backendFactories.set(f.scope, f);
+    const backendDisposers = [];
+    // computed target (canonical path) -> its `from` paths, for cycle detection.
+    const computedDeps = new Map();
+    const pending = new Map();
+    // Paths whose change came from a backend push (Yjs/socket): the backend
+    // already holds the new value before emit() fires, so `previous` can't be
+    // captured and the Object.is dedupe would wrongly swallow it. Force-notify.
+    const forced = new Set();
+    let flushScheduled = false;
+    // ── tree walking ────────────────────────────────────────────────────────
+    function walk(segs, create) {
+        let node = root;
+        for (const seg of segs) {
+            let next = node.children?.get(seg);
+            if (!next) {
+                if (!create)
+                    return undefined;
+                if (!node.children)
+                    node.children = new Map();
+                next = makeNode();
+                node.children.set(seg, next);
+            }
+            node = next;
+        }
+        return node;
+    }
+    // Collect [root, n1, …] for an existing path (stops at first missing node).
+    function walkStack(segs) {
+        const stack = [root];
+        let node = root;
+        for (const seg of segs) {
+            const next = node.children?.get(seg);
+            if (!next)
+                break;
+            stack.push(next);
+            node = next;
+        }
+        return stack;
+    }
+    function prune(segs) {
+        const stack = walkStack(segs);
+        // stack[i] is the node after consuming segs[0..i-1]; stack[0] = root.
+        for (let i = stack.length - 1; i >= 1; i--) {
+            const node = stack[i];
+            if (!nodeEmpty(node))
+                break;
+            const parent = stack[i - 1];
+            parent.children?.delete(segs[i - 1]);
+            if (parent.children && parent.children.size === 0)
+                parent.children = undefined;
+        }
+    }
+    // ── value storage (backend-routed; default = in-memory tree node) ─────────
+    function ensureBackend(scope) {
+        let backend = backends.get(scope);
+        if (backend)
+            return backend;
+        const factory = backendFactories.get(scope);
+        if (!factory)
+            return undefined;
+        backend = factory.create();
+        backends.set(scope, backend);
+        if (backend.attach) {
+            backendDisposers.push(backend.attach((path, value) => emitExternal(path, value)));
+        }
+        return backend;
+    }
+    function readValue(segs) {
+        const backend = segs.length ? ensureBackend(segs[0]) : undefined;
+        if (backend)
+            return backend.get(segs.slice(1));
+        const node = walk(segs, false);
+        return node && node.hasValue
+            ? { hasValue: true, value: node.value }
+            : { hasValue: false, value: undefined };
+    }
+    function writeValue(segs, value) {
+        const backend = segs.length ? ensureBackend(segs[0]) : undefined;
+        if (backend) {
+            backend.set(segs.slice(1), value);
+            return;
+        }
+        const node = walk(segs, true);
+        node.hasValue = true;
+        node.value = value;
+    }
+    function removeValue(segs) {
+        const backend = segs.length ? ensureBackend(segs[0]) : undefined;
+        if (backend) {
+            const had = backend.get(segs.slice(1)).hasValue;
+            backend.delete(segs.slice(1));
+            return had;
+        }
+        const node = walk(segs, false);
+        if (!node || !node.hasValue)
+            return false;
+        node.hasValue = false;
+        node.value = undefined;
+        return true;
+    }
+    // ── batching / notification ───────────────────────────────────────────────
+    function queueChange(canonical) {
+        if (!pending.has(canonical)) {
+            pending.set(canonical, { previous: readValue(segmentsOf(canonical)).value });
+        }
+        if (!flushScheduled) {
+            flushScheduled = true;
+            queueMicrotask(flush);
+        }
+    }
+    function safeExact(fn, value, path) {
+        try {
+            fn(value);
+        }
+        catch (err) {
+            console.error(`[scena.store] subscriber for "${path}" threw:`, err);
+        }
+    }
+    function safeWild(fn, value, path) {
+        try {
+            fn(value, path);
+        }
+        catch (err) {
+            console.error(`[scena.store] wildcard subscriber threw:`, err);
+        }
+    }
+    function notify(canonical, value) {
+        const segs = segmentsOf(canonical);
+        // Walk root → exact node. At each visited node check wildcard subs whose
+        // anchor is that node; at the terminal node fire exact subscribers.
+        let node = root;
+        fireWild(node, segs, 0, value, canonical);
+        for (let d = 0; d < segs.length; d++) {
+            node = node.children?.get(segs[d]);
+            if (!node)
+                break;
+            fireWild(node, segs, d + 1, value, canonical);
+            if (d === segs.length - 1 && node.subscribers) {
+                for (const fn of [...node.subscribers])
+                    safeExact(fn, value, canonical);
+            }
+        }
+    }
+    function fireWild(node, segs, depth, value, path) {
+        if (!node.wildSubs)
+            return;
+        const rem = segs.slice(depth);
+        for (const ws of [...node.wildSubs]) {
+            if (matchPattern(ws.pattern, rem))
+                safeWild(ws.fn, value, path);
+        }
+    }
+    function flush() {
+        flushScheduled = false;
+        if (pending.size === 0)
+            return;
+        const batch = [...pending.entries()];
+        pending.clear();
+        for (const [canonical, { previous }] of batch) {
+            const { hasValue, value } = readValue(segmentsOf(canonical));
+            const force = forced.delete(canonical);
+            if (!force && Object.is(value, previous) && hasValue)
+                continue;
+            events.emit('scena:store:changed', { path: canonical, value, previous });
+            notify(canonical, value);
+        }
+    }
+    // External (backend-pushed) change: write already happened in the backend.
+    function emitExternal(path, _value) {
+        const canonical = joinSegments(segmentsOf(path));
+        forced.add(canonical);
+        queueChange(canonical);
+    }
+    function ensureNamespaceLoaded(scope) {
+        if (loadedNamespaces.has(scope))
+            return;
+        const def = dataProviders.get(scope);
+        if (!def)
+            return;
+        if (def.load === 'lazy' || def.load === undefined) {
+            loadedNamespaces.add(scope);
+            void def.provider.load(store, deps.socket);
+        }
+    }
+    // ── subtree helpers ───────────────────────────────────────────────────────
+    function walkSubtree(node, segs, visit) {
+        visit(node, segs);
+        if (node.children) {
+            for (const [seg, child] of node.children)
+                walkSubtree(child, [...segs, seg], visit);
+        }
+    }
+    // Writing a CONTAINER value invalidates sub-path subscribers — a binding to
+    // `$/a/b/name` reads via readPath, descending into the object stored at
+    // `$/a/b`, so replacing that object changes its resolved value even though no
+    // `name` node was written. notify() only walks root→exact, never down, so
+    // queue every SUBSCRIBED descendant of the written node here. Gated on the old
+    // OR new value being a container — a primitive write (e.g. `$/a = 1`) can't
+    // change any descendant's descended value, so it stays exact-path-only.
+    // Bounded: only materialized nodes (subscribed/written) exist, and only when
+    // the node has children — leaf/primitive writes stay O(1). Descendants flush
+    // with a node-only value (often undefined); subscribers re-read via readPath
+    // (which useStore does), so the fired value arg is just a wake-up signal.
+    function isContainer(v) {
+        return typeof v === 'object' && v !== null;
+    }
+    function queueDescendants(segs, prev, next) {
+        if (!isContainer(prev) && !isContainer(next))
+            return;
+        const node = walk(segs, false);
+        if (!node?.children)
+            return;
+        walkSubtree(node, segs, (n, s) => {
+            if (n === node)
+                return; // the exact path is queued by the caller
+            if ((n.subscribers && n.subscribers.size) || (n.wildSubs && n.wildSubs.length)) {
+                queueChange(joinSegments(s));
+            }
+        });
+    }
+    // ── public API ──────────────────────────────────────────────────────────
+    const store = {
+        _internalKeys() {
+            const keys = [];
+            walkSubtree(root, [], (node, segs) => {
+                if (node.hasValue && segs.length)
+                    keys.push(joinSegments(segs));
+            });
+            return keys;
+        },
+        get(path) {
+            const segs = segmentsOf(path);
+            if (segs.length)
+                ensureNamespaceLoaded(segs[0]);
+            return readValue(segs).value;
+        },
+        set(path, value) {
+            const segs = segmentsOf(path);
+            const canonical = joinSegments(segs);
+            queueChange(canonical);
+            const prev = readValue(segs).value;
+            writeValue(segs, value);
+            queueDescendants(segs, prev, value);
+        },
+        patch(path, partial) {
+            const segs = segmentsOf(path);
+            const canonical = joinSegments(segs);
+            queueChange(canonical);
+            const current = readValue(segs).value;
+            const next = { ...current, ...partial };
+            writeValue(segs, next);
+            queueDescendants(segs, current, next);
+        },
+        patchMany(entries) {
+            for (const [path, value] of Object.entries(entries)) {
+                const segs = segmentsOf(path);
+                queueChange(joinSegments(segs));
+                const prev = readValue(segs).value;
+                writeValue(segs, value);
+                queueDescendants(segs, prev, value);
+            }
+        },
+        delete(path) {
+            const segs = segmentsOf(path);
+            const canonical = joinSegments(segs);
+            // capture previous before mutating
+            queueChange(canonical);
+            const removed = removeValue(segs);
+            if (removed)
+                prune(segs);
+        },
+        clearNamespace(scope) {
+            loadedNamespaces.delete(scope);
+            const node = root.children?.get(scope);
+            const backend = backends.get(scope);
+            if (!node && !backend)
+                return;
+            // Queue changes (capturing previous) for every value-bearing or
+            // subscribed descendant BEFORE clearing, so subscribers fire with the
+            // post-clear value (undefined). O(subtree), not O(total store).
+            if (node) {
+                walkSubtree(node, [scope], (n, segs) => {
+                    const present = backend ? backend.get(segs.slice(1)).hasValue : n.hasValue;
+                    if (present || (n.subscribers && n.subscribers.size)) {
+                        queueChange(joinSegments(segs));
+                    }
+                });
+            }
+            if (backend) {
+                backend.clear();
+            }
+            else if (node) {
+                walkSubtree(node, [scope], (n) => {
+                    n.hasValue = false;
+                    n.value = undefined;
+                });
+            }
+        },
+        subscribe(path, fn) {
+            const segs = segmentsOf(path);
+            if (segs.length) {
+                ensureNamespaceLoaded(segs[0]);
+                // Activate the scope's backend so external-push backends (Yjs/socket)
+                // attach their observer before the first change arrives.
+                ensureBackend(segs[0]);
+            }
+            if (isWildcardPath(path)) {
+                const star = segs.indexOf('*');
+                const prefix = segs.slice(0, star);
+                const pattern = segs.slice(star); // includes the '*' and the rest
+                const anchor = walk(prefix, true);
+                if (!anchor.wildSubs)
+                    anchor.wildSubs = [];
+                const entry = { pattern, fn: fn };
+                anchor.wildSubs.push(entry);
+                return disposableFrom(() => {
+                    const arr = anchor.wildSubs;
+                    if (!arr)
+                        return;
+                    const i = arr.indexOf(entry);
+                    if (i >= 0)
+                        arr.splice(i, 1);
+                    if (arr.length === 0)
+                        anchor.wildSubs = undefined;
+                    prune(prefix);
+                });
+            }
+            const node = walk(segs, true);
+            if (!node.subscribers)
+                node.subscribers = new Set();
+            node.subscribers.add(fn);
+            return disposableFrom(() => {
+                node.subscribers?.delete(fn);
+                if (node.subscribers && node.subscribers.size === 0)
+                    node.subscribers = undefined;
+                prune(segs);
+            });
+        },
+        subscriberCount(scope) {
+            const node = root.children?.get(scope);
+            if (!node)
+                return 0;
+            let count = 0;
+            walkSubtree(node, [scope], (n) => {
+                if (n.subscribers)
+                    count += n.subscribers.size;
+                if (n.wildSubs)
+                    count += n.wildSubs.length;
+            });
+            return count;
+        },
+        computed(path, def) {
+            const target = joinSegments(segmentsOf(path));
+            const froms = def.from.slice();
+            detectCycle(target, froms);
+            computedDeps.set(target, froms);
+            const selectFn = typeof def.select === 'function' ? def.select : compileSelect(def.select);
+            const recompute = () => {
+                const inputs = {};
+                for (const f of froms)
+                    inputs[f] = gatherInput(f);
+                store.set(path, selectFn(inputs));
+            };
+            const disposables = froms.map((p) => store.subscribe(p, recompute));
+            recompute();
+            return disposableFrom(() => {
+                disposables.forEach((d) => d.dispose());
+                computedDeps.delete(target);
+            });
+        },
+        registerDataProvider(def) {
+            dataProviders.set(def.namespace, def);
+            if (def.load === 'eager') {
+                loadedNamespaces.add(def.namespace);
+                void def.provider.load(store, deps.socket);
+            }
+            return disposableFrom(() => {
+                if (loadedNamespaces.has(def.namespace)) {
+                    void def.provider.unload?.(store, deps.socket);
+                    loadedNamespaces.delete(def.namespace);
+                }
+                dataProviders.delete(def.namespace);
+            });
+        },
+        listDataProviders() {
+            return [...dataProviders.values()];
+        },
+    };
+    // ── computed helpers ──────────────────────────────────────────────────────
+    function gatherInput(from) {
+        if (hasWildcard(from)) {
+            // Expand a wildcard `from` to the array of matched stored values
+            // (in-memory scopes only). Used by collection selects (countWhere, …).
+            const segs = segmentsOf(from);
+            const star = segs.indexOf('*');
+            const prefix = segs.slice(0, star);
+            const pattern = segs.slice(star);
+            const anchor = walk(prefix, false);
+            if (!anchor)
+                return [];
+            const out = [];
+            walkSubtree(anchor, prefix, (n, s) => {
+                if (!n.hasValue)
+                    return;
+                if (matchPattern(pattern, s.slice(prefix.length)))
+                    out.push(n.value);
+            });
+            return out;
+        }
+        return store.get(from);
+    }
+    function detectCycle(target, froms) {
+        const seen = new Set();
+        const stack = froms.map((f) => joinSegments(segmentsOf(f)));
+        while (stack.length) {
+            const cur = stack.pop();
+            if (cur === target) {
+                throw new Error(`computed: registering "${target}" would create a dependency cycle.`);
+            }
+            if (seen.has(cur))
+                continue;
+            seen.add(cur);
+            const deps2 = computedDeps.get(cur);
+            if (deps2)
+                stack.push(...deps2.map((f) => joinSegments(segmentsOf(f))));
+        }
+    }
+    return store;
+}
+// ── mount-local helpers (canonical layout: `$/local/<mountKey>/<rest>`) ──────
+export function localPath(mountKey, suffix) {
+    const tail = suffix.startsWith('/') ? suffix.slice(1) : suffix;
+    return `$/local/${mountKey}/${tail}`;
+}
+const LOCAL_PREFIX = '$/local/';
+export function rewriteLocal(path, mountKey) {
+    if (!mountKey)
+        return path;
+    if (!path.startsWith(LOCAL_PREFIX))
+        return path;
+    const tail = path.slice(LOCAL_PREFIX.length);
+    if (tail.startsWith(`${mountKey}/`) || tail === mountKey)
+        return path;
+    return `$/local/${mountKey}/${tail}`;
+}
+export function clearMountLocal(store, mountKey) {
+    const internal = store;
+    const keys = internal._internalKeys?.() ?? [];
+    const prefix = `$/local/${mountKey}/`;
+    const exact = `$/local/${mountKey}`;
+    for (const key of keys) {
+        if (key === exact || key.startsWith(prefix)) {
+            store.delete(key);
+        }
+    }
+}

package/dist/core/scena.d.ts

@@ -0,0 +1,2 @@
+import type { CreateScena } from '../types/scena.js';
+export declare const createScena: CreateScena;

package/dist/core/scena.js

@@ -0,0 +1,115 @@
+import { createEventBus } from '../controls/events.js';
+import { createWhenEngine } from '../controls/when.js';
+import { createCommandRegistry } from '../controls/command.js';
+import { createKeybindingRegistry } from '../controls/keybinding.js';
+import { createLayoutAPI, createLayoutRegistry } from '../controls/layout.js';
+import { createSessionAPI } from '../controls/session.js';
+import { createShellRegistry } from '../controls/shell.js';
+import { createManifestAPI } from '../controls/manifest.js';
+import { createPermissionEngine } from './permissions.js';
+import { createReactiveStore } from './reactive-store.js';
+import { createBindingResolver } from './binding-resolver.js';
+import { createComponentRegistry } from './component-registry.js';
+import { createConverterRegistry } from './converter-registry.js';
+import { createMountSurfaceRegistry } from './mount-surface.js';
+import { createMountMenuRegistry } from './mount-menu.js';
+import { registerBuiltinFunctions } from '../runtime/builtins.js';
+export const createScena = (opts = {}) => {
+    const events = opts.events ?? createEventBus();
+    const permissions = createPermissionEngine();
+    const store = createReactiveStore({
+        events,
+        socket: opts.socket,
+        backendFactories: opts.backendFactories,
+    });
+    const bindings = createBindingResolver({ store });
+    const when = createWhenEngine({ store });
+    const components = createComponentRegistry({ events });
+    const converters = createConverterRegistry();
+    const surfaces = createMountSurfaceRegistry({ events, when, bindings, store, components });
+    const mountMenus = createMountMenuRegistry();
+    const layouts = createLayoutRegistry({ events });
+    const shells = createShellRegistry({ events, initialId: opts.initialShellId });
+    const layout = createLayoutAPI({
+        events,
+        store,
+        initial: opts.initialLayout,
+        storage: opts.layoutStorage,
+    });
+    const scenaRef = { current: null };
+    const keybindings = createKeybindingRegistry({ events, when });
+    const commands = createCommandRegistry({
+        events,
+        store,
+        surfaces,
+        when,
+        socket: opts.socket,
+        keybindings,
+        getScena: () => {
+            if (!scenaRef.current) {
+                throw new Error('Scena instance accessed before createScena() returned');
+            }
+            return scenaRef.current;
+        },
+    });
+    const session = createSessionAPI({
+        events,
+        store,
+        surfaces,
+        components,
+        storage: opts.sessionStorage,
+    });
+    const manifest = createManifestAPI({
+        events,
+        store,
+        components,
+        commands,
+        keybindings,
+        surfaces,
+        converters,
+        permissions,
+    });
+    if (opts.initialActive) {
+        for (const [path, value] of Object.entries(opts.initialActive)) {
+            store.set(path, value);
+        }
+    }
+    events.on('scena:mount:focused', (payload) => {
+        const ev = payload;
+        layout.setSurface(ev.surface, { activeContainerKey: ev.key });
+    });
+    const scena = {
+        components,
+        store,
+        bindings,
+        surfaces,
+        mountMenus,
+        layouts,
+        converters,
+        permissions,
+        commands,
+        keybindings,
+        shells,
+        layout,
+        session,
+        manifest,
+        events,
+        when,
+        open: surfaces.open.bind(surfaces),
+        openResource: surfaces.openResource.bind(surfaces),
+        execute: commands.execute.bind(commands),
+        setSessionStorage(s) {
+            session.setStorage(s);
+        },
+        setLayoutStorage(s) {
+            layout.setStorage(s);
+        },
+        dispose() {
+            // Per-source disposable tracking lives at the registration site.
+        },
+    };
+    scenaRef.current = scena;
+    // The a2ui v0.10 basic-catalog functions are always available.
+    registerBuiltinFunctions(scena);
+    return scena;
+};

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

@@ -0,0 +1,6 @@
+import type { SurfaceName } from '../types/mount-surface.js';
+import type { SurfacePresentation } from '../types/layout.js';
+import type { ModusClass } from './backends/modus-backend.js';
+export type PresentationPolicy = Partial<Record<SurfaceName, Partial<Record<ModusClass, SurfacePresentation>>>>;
+export declare function resolveSurfacePresentation(surface: SurfaceName, modus: ModusClass, policy?: PresentationPolicy): SurfacePresentation;
+export declare function isOverlaid(presentation: SurfacePresentation): boolean;

package/dist/core/surface-presentation.js

@@ -0,0 +1,12 @@
+export function resolveSurfacePresentation(surface, modus, policy = {}) {
+    return policy[surface]?.[modus] ?? 'docked';
+}
+// True when a presentation takes the surface out of the flex flow. Shells use
+// this to decide whether to render a splitter at all — a floating surface has
+// nothing left to resize against — and whether a scrim is needed.
+//
+// `bar` is excluded on purpose: it is pinned to an edge but still occupies it,
+// so a shell keeps reserving space for it and draws no scrim.
+export function isOverlaid(presentation) {
+    return presentation === 'floating' || presentation === 'sheet';
+}

package/dist/i18n/i18n-backend.d.ts

@@ -0,0 +1,2 @@
+import type { ScopeBackend } from '../types/scope-backend.js';
+export declare function createI18nBackend(scope?: string): ScopeBackend;

package/dist/i18n/i18n-backend.js

@@ -0,0 +1,35 @@
+import { resolveMessage, subscribeI18n } from './registry.js';
+// A ScopeBackend that makes `$/t/<key>` resolve to the active locale's message
+// from the i18n registry — your `$translate -> $i18n/<locale>` alias, realized
+// through the backend seam. Read-only (translations are registered via
+// registerMessages, not store writes). No dictionary is copied into the store
+// tree; values resolve on read.
+//
+// On any registry change (locale switch OR new messages), the backend re-emits
+// the keys that have actually been READ (bound somewhere) so their store
+// subscribers refresh — bounded to live keys, not the whole dictionary.
+export function createI18nBackend(scope = 't') {
+    const accessed = new Set();
+    const keyOf = (segs) => segs.join('/');
+    return {
+        get(segs) {
+            const key = keyOf(segs);
+            accessed.add(key);
+            const v = resolveMessage(key);
+            return v === undefined ? { hasValue: false, value: undefined } : { hasValue: true, value: v };
+        },
+        set() {
+            /* translations are read-only via the store; use registerMessages */
+        },
+        delete() { },
+        clear() { },
+        attach(emit) {
+            const unsub = subscribeI18n(() => {
+                for (const key of accessed) {
+                    emit(`$/${scope}/${key}`, resolveMessage(key));
+                }
+            });
+            return { dispose: unsub };
+        },
+    };
+}