@softov/scena 0.1.2

package/dist/controls/manifest.js

@@ -0,0 +1,219 @@
+import { combineDisposables, disposableFrom } from '../core/disposable.js';
+import { isPermissionPath } from '../runtime/args-schema.js';
+// Validates an AuthorManifest. Returns a list of errors; empty = ok.
+//   - plugin component names must be `<slug>.<TypeName>`
+//   - plugin command ids must be `<slug>.<...>`
+//   - permission read/write paths must use `$/scope/...` syntax
+function validateManifest(manifest) {
+    const errors = [];
+    const slug = manifest.source.id;
+    const c = manifest.contributes;
+    for (const comp of c?.components ?? []) {
+        if (!comp.component.includes('.')) {
+            errors.push(`component "${comp.component}": plugin component names must be namespaced ` +
+                `(expected "${slug}.${comp.component}")`);
+        }
+        else if (!comp.component.startsWith(`${slug}.`)) {
+            errors.push(`component "${comp.component}": namespace must match plugin slug "${slug}"`);
+        }
+    }
+    for (const cmd of c?.commands ?? []) {
+        if (!cmd.id.startsWith(`${slug}.`)) {
+            errors.push(`command "${cmd.id}": id must be prefixed with plugin slug "${slug}"`);
+        }
+    }
+    for (const p of manifest.permissions?.read ?? []) {
+        if (!isPermissionPath(p)) {
+            errors.push(`permissions.read "${p}": not a valid path (expected "$/scope/...")`);
+        }
+    }
+    for (const p of manifest.permissions?.write ?? []) {
+        if (!isPermissionPath(p)) {
+            errors.push(`permissions.write "${p}": not a valid path`);
+        }
+    }
+    return errors;
+}
+export function createManifestAPI(deps) {
+    const loaded = new Map();
+    async function load(manifest, _loader) {
+        const sourceId = manifest.source.id;
+        if (loaded.has(sourceId)) {
+            throw new Error(`Manifest "${sourceId}" already loaded`);
+        }
+        const errors = validateManifest(manifest);
+        if (errors.length > 0) {
+            throw new Error(`Manifest "${sourceId}" rejected:\n  - ${errors.join('\n  - ')}`);
+        }
+        if (manifest.permissions) {
+            deps.permissions.grant(sourceId, manifest.permissions);
+        }
+        const subs = [];
+        const c = manifest.contributes;
+        const allowedSurfaces = manifest.permissions?.surfaces;
+        if (c) {
+            for (const def of c.components ?? [])
+                subs.push(deps.components.register(def));
+            for (const t of c.converters ?? [])
+                subs.push(deps.converters.register(t));
+            for (const dp of c.dataProviders ?? [])
+                subs.push(deps.store.registerDataProvider(dp));
+            for (const cp of c.computedPaths ?? [])
+                subs.push(deps.store.computed(cp.path, cp.def));
+            for (const cmd of c.commands ?? []) {
+                subs.push(deps.commands.register({
+                    id: cmd.id,
+                    title: cmd.title,
+                    category: cmd.category,
+                    icon: cmd.icon,
+                    keywords: cmd.keywords,
+                    slots: cmd.slots,
+                    args: cmd.args,
+                    dispatch: cmd.dispatch,
+                    run: undefined,
+                }));
+            }
+            for (const kb of c.keybindings ?? []) {
+                subs.push(deps.keybindings.register({
+                    keys: kb.keys,
+                    commandId: kb.commandId,
+                    args: kb.args,
+                    when: kb.when,
+                    scope: kb.scope,
+                }));
+            }
+            for (const ck of c.contextKeys ?? []) {
+                deps.store.set(ck.key, ck.value);
+            }
+            for (const view of c.views ?? []) {
+                if (allowedSurfaces && !allowedSurfaces.includes(view.surface)) {
+                    deps.events.emit('scena:permission:denied', {
+                        sourceId,
+                        kind: 'surface',
+                        path: view.surface,
+                    });
+                    continue;
+                }
+                const component = typeof view.component === 'string'
+                    ? {
+                        component: 'MissingComponent',
+                        reason: 'graph-module-not-resolved',
+                    }
+                    : view.component;
+                subs.push(deps.surfaces.mount({
+                    surface: view.surface,
+                    key: view.key,
+                    when: view.when,
+                    resource: component,
+                    policy: view.policy,
+                }));
+            }
+        }
+        const dispose = combineDisposables(...subs, disposableFrom(() => {
+            deps.permissions.revoke(sourceId);
+            loaded.delete(sourceId);
+            deps.events.emit('scena:plugin:unloaded', { sourceId });
+        }));
+        loaded.set(sourceId, { source: manifest.source, dispose });
+        deps.events.emit('scena:plugin:contributed', {
+            sourceId,
+            version: manifest.source.version,
+        });
+        return dispose;
+    }
+    // Bridges RuntimeManifestJSON → AuthorManifest by lifting module specifiers
+    // into lazy loader.resolve() calls, then delegates to load().
+    async function loadRuntime(manifest, loader) {
+        const c = manifest.contributes;
+        const components = (c?.components ?? []).map((rc) => {
+            if (rc.renderer.kind === 'template') {
+                return {
+                    component: rc.component,
+                    category: rc.category,
+                    propsSchema: rc.propsSchema,
+                    fallback: rc.fallback,
+                    renderer: { kind: 'template', template: rc.renderer.template },
+                };
+            }
+            if (rc.renderer.kind === 'react') {
+                const moduleSpec = rc.renderer.module;
+                return {
+                    component: rc.component,
+                    category: rc.category,
+                    propsSchema: rc.propsSchema,
+                    fallback: rc.fallback,
+                    renderer: {
+                        kind: 'react',
+                        load: async () => {
+                            const mod = await loader.resolve(moduleSpec, manifest.source);
+                            return mod;
+                        },
+                    },
+                };
+            }
+            const moduleSpec = rc.renderer.module;
+            return {
+                component: rc.component,
+                category: rc.category,
+                propsSchema: rc.propsSchema,
+                fallback: rc.fallback,
+                renderer: {
+                    kind: 'html',
+                    mount: (host, props) => {
+                        let disposed = false;
+                        let inner = null;
+                        void loader.resolve(moduleSpec, manifest.source).then((mod) => {
+                            if (disposed)
+                                return;
+                            const fn = mod.default ??
+                                mod;
+                            const result = fn(host, props);
+                            inner = result ?? null;
+                        });
+                        return disposableFrom(() => {
+                            disposed = true;
+                            inner?.dispose();
+                        });
+                    },
+                },
+            };
+        });
+        const bridged = {
+            source: manifest.source,
+            requires: manifest.requires,
+            engine: manifest.engine,
+            permissions: manifest.permissions,
+            contributes: c
+                ? {
+                    components,
+                    commands: c.commands?.map((cmd) => ({
+                        id: cmd.id,
+                        title: cmd.title,
+                        category: cmd.category,
+                        icon: cmd.icon,
+                        keywords: cmd.keywords,
+                        slots: cmd.slots,
+                        when: cmd.when,
+                        args: cmd.args,
+                        dispatch: cmd.dispatch,
+                        run: cmd.run,
+                    })),
+                    keybindings: c.keybindings,
+                    contextKeys: c.contextKeys,
+                    views: c.views,
+                }
+                : undefined,
+        };
+        return load(bridged, loader);
+    }
+    return {
+        load,
+        loadRuntime,
+        unload(sourceId) {
+            loaded.get(sourceId)?.dispose.dispose();
+        },
+        listSources() {
+            return [...loaded.values()].map((e) => e.source);
+        },
+    };
+}

package/dist/controls/session.d.ts

@@ -0,0 +1,16 @@
+import type { EventBus } from '../types/events.js';
+import type { ReactiveStore } from '../types/reactive-store.js';
+import type { MountSurfaceRegistry } from '../types/mount-surface.js';
+import type { SessionAPI, SessionStorage } from '../types/session.js';
+import type { ComponentRegistry } from '../types/component-registry.js';
+interface Deps {
+    events: EventBus;
+    store: ReactiveStore;
+    surfaces: MountSurfaceRegistry;
+    components: ComponentRegistry;
+    storage?: SessionStorage;
+}
+export declare function createSessionAPI(deps: Deps): SessionAPI & {
+    setStorage(s: SessionStorage | null): void;
+};
+export {};

package/dist/controls/session.js

@@ -0,0 +1,95 @@
+import { disposableFrom } from '../core/disposable.js';
+const ALL_SURFACES = [
+    'titlebar',
+    'activitybar',
+    'sidebar:left',
+    'sidebar:right',
+    'main',
+    'panel:bottom',
+    'statusbar',
+    'overlay',
+    'detached',
+];
+export function createSessionAPI(deps) {
+    const { events, surfaces, components } = deps;
+    let storage = deps.storage ?? null;
+    let autoPersistTimer = null;
+    let autoPersistSub = null;
+    function snapshot() {
+        const mounts = [];
+        for (const surface of ALL_SURFACES) {
+            for (const m of surfaces.listAt(surface)) {
+                mounts.push({
+                    key: m.key,
+                    surface: m.surface,
+                    component: m.component,
+                    state: {},
+                    openedAt: m.openedAt,
+                });
+            }
+        }
+        return {
+            version: 1,
+            capturedAt: Date.now(),
+            mounts,
+            surfaces: {},
+        };
+    }
+    async function restore(snap) {
+        const restored = [];
+        const skipped = [];
+        for (const sm of snap.mounts) {
+            if (!components.get(sm.component.component)) {
+                skipped.push(sm);
+                events.emit('scena:session:skipped', {
+                    key: sm.key,
+                    surface: sm.surface,
+                    reason: `component "${sm.component.component}" not registered`,
+                });
+                continue;
+            }
+            restored.push(surfaces.open({
+                surface: sm.surface,
+                key: sm.key,
+                resource: sm.component,
+            }));
+        }
+        return { restored, skipped };
+    }
+    async function save() {
+        if (!storage)
+            return;
+        await storage.save(snapshot());
+    }
+    function enableAutoPersist(opts) {
+        const debounce = opts?.debounceMs ?? 1000;
+        const schedule = () => {
+            if (autoPersistTimer)
+                clearTimeout(autoPersistTimer);
+            autoPersistTimer = setTimeout(() => {
+                autoPersistTimer = null;
+                void save();
+            }, debounce);
+        };
+        autoPersistSub?.dispose();
+        autoPersistSub = events.on('scena:mount:opened', schedule);
+        const closedSub = events.on('scena:mount:closed', schedule);
+        return disposableFrom(() => {
+            autoPersistSub?.dispose();
+            closedSub.dispose();
+            autoPersistSub = null;
+            if (autoPersistTimer)
+                clearTimeout(autoPersistTimer);
+            autoPersistTimer = null;
+        });
+    }
+    return {
+        snapshot,
+        restore,
+        save,
+        enableAutoPersist,
+        setStorage(s) {
+            storage = s;
+        },
+    };
+}

package/dist/controls/shell.d.ts

@@ -0,0 +1,8 @@
+import type { EventBus } from '../types/events.js';
+import type { ShellRegistry } from '../types/shell.js';
+interface Deps {
+    events: EventBus;
+    initialId?: string;
+}
+export declare function createShellRegistry(deps: Deps): ShellRegistry;
+export {};

package/dist/controls/shell.js

@@ -0,0 +1,48 @@
+import { disposableFrom } from '../core/disposable.js';
+export function createShellRegistry(deps) {
+    const { events } = deps;
+    const shells = new Map();
+    let activeId = deps.initialId ?? null;
+    function announce() {
+        events.emit('scena:registry:changed', { registry: 'shells' });
+    }
+    return {
+        register(def) {
+            shells.set(def.id, def);
+            if (!activeId) {
+                activeId = def.id;
+                events.emit('scena:shell:changed', { shellId: def.id });
+            }
+            announce();
+            return disposableFrom(() => {
+                if (shells.get(def.id) === def) {
+                    shells.delete(def.id);
+                    if (activeId === def.id)
+                        activeId = null;
+                    announce();
+                }
+            });
+        },
+        unregister(id) {
+            if (shells.delete(id)) {
+                if (activeId === id)
+                    activeId = null;
+                announce();
+            }
+        },
+        list() {
+            return [...shells.values()];
+        },
+        setActive(id) {
+            if (!shells.has(id))
+                throw new Error(`Shell "${id}" not registered`);
+            if (activeId === id)
+                return;
+            activeId = id;
+            events.emit('scena:shell:changed', { shellId: id });
+        },
+        getActive() {
+            return activeId ? shells.get(activeId) ?? null : null;
+        },
+    };
+}

package/dist/controls/storage/layout-local.d.ts

@@ -0,0 +1,6 @@
+import type { LayoutStorage } from '../../types/layout.js';
+export interface LocalStorageLayoutStorageOptions {
+    key?: string;
+}
+export declare function createLocalStorageLayoutStorage(opts?: LocalStorageLayoutStorageOptions): LayoutStorage;
+export declare function createNoopLayoutStorage(): LayoutStorage;

package/dist/controls/storage/layout-local.js

@@ -0,0 +1,47 @@
+// Browser localStorage-backed LayoutStorage. Pass to createScena
+// via opts.layoutStorage. Falls back to a no-op store on environments
+// where localStorage is unavailable (e.g., SSR).
+export function createLocalStorageLayoutStorage(opts = {}) {
+    const key = opts.key ?? 'scena.layout';
+    const available = typeof localStorage !== 'undefined';
+    return {
+        async load() {
+            if (!available)
+                return null;
+            const raw = localStorage.getItem(key);
+            if (!raw)
+                return null;
+            try {
+                return JSON.parse(raw);
+            }
+            catch {
+                return null;
+            }
+        },
+        async save(layout) {
+            if (!available)
+                return;
+            try {
+                localStorage.setItem(key, JSON.stringify(layout));
+            }
+            catch {
+                // Quota or permission error — silently drop. Step 5 doesn't surface this;
+                // an alerter / metrics hook can be added later.
+            }
+        },
+        async clear() {
+            if (!available)
+                return;
+            localStorage.removeItem(key);
+        },
+    };
+}
+export function createNoopLayoutStorage() {
+    return {
+        async load() {
+            return null;
+        },
+        async save() { },
+        async clear() { },
+    };
+}

package/dist/controls/storage/session-local.d.ts

@@ -0,0 +1,5 @@
+import type { SessionStorage } from '../../types/session.js';
+export interface LocalStorageSessionStorageOptions {
+    key?: string;
+}
+export declare function createLocalStorageSessionStorage(opts?: LocalStorageSessionStorageOptions): SessionStorage;

package/dist/controls/storage/session-local.js

@@ -0,0 +1,38 @@
+// Browser localStorage-backed SessionStorage. Pass to createScena via
+// opts.sessionStorage, then drive restore()/enableAutoPersist() from the app
+// once components are registered. Falls back to a no-op on environments where
+// localStorage is unavailable (e.g., SSR).
+export function createLocalStorageSessionStorage(opts = {}) {
+    const key = opts.key ?? 'scena.session';
+    const available = typeof localStorage !== 'undefined';
+    return {
+        async load() {
+            if (!available)
+                return null;
+            const raw = localStorage.getItem(key);
+            if (!raw)
+                return null;
+            try {
+                return JSON.parse(raw);
+            }
+            catch {
+                return null;
+            }
+        },
+        async save(snapshot) {
+            if (!available)
+                return;
+            try {
+                localStorage.setItem(key, JSON.stringify(snapshot));
+            }
+            catch {
+                // Quota or permission error — silently drop, matching the layout store.
+            }
+        },
+        async clear() {
+            if (!available)
+                return;
+            localStorage.removeItem(key);
+        },
+    };
+}

package/dist/controls/when.d.ts

@@ -0,0 +1,7 @@
+import type { ReactiveStore } from '../types/reactive-store.js';
+import type { WhenEngine } from '../types/when.js';
+interface Deps {
+    store: ReactiveStore;
+}
+export declare function createWhenEngine(deps: Deps): WhenEngine;
+export {};