@softov/scena 0.1.2

package/dist/runtime/layout-commands.js

@@ -0,0 +1,548 @@
+import { combineDisposables } from '../core/disposable.js';
+import { translate } from '../i18n/registry.js';
+function joinAbs(root, rel) {
+    if (rel.startsWith('$/'))
+        return rel;
+    if (!root)
+        return (rel.startsWith('/') ? `$${rel}` : `$/${rel}`);
+    const base = root.endsWith('/') ? root.slice(0, -1) : root;
+    const tail = rel.startsWith('/') ? rel : `/${rel}`;
+    return `${base}${tail}`;
+}
+// Registers the mount-level / group-level / surface-level commands from
+// COMMANDS-list.md. Layouts inject `$/tab/*`, `$/group/*`, `$/surface/*`
+// capability paths when opening their context menus; these commands read
+// from those paths to find their targets. `when` clauses gate visibility
+// via commands.list({enabled: true}) — `when` is NOT checked at execute
+// time (decoupled in controls/command.ts), so the run body must be its
+// own last-mile guard if anything is required.
+export function registerLayoutCommands(scena) {
+    const subs = [];
+    // ── Helpers ──────────────────────────────────────────────────────────────
+    function ctxTab(ctx) {
+        return ctx.store.get('$/tab/key');
+    }
+    function ctxGroup(ctx) {
+        return ctx.store.get('$/group/key');
+    }
+    function ctxSurface(ctx) {
+        return (ctx.store.get('$/surface/name') ?? 'main');
+    }
+    function ctxTabIndex(ctx) {
+        return Number(ctx.store.get('$/tab/index') ?? 0);
+    }
+    // Read the surface's current state from layout. Most commands operate
+    // through `surfaces.close` / `surfaces.open`; only group-level tree
+    // mutations need the layout tree directly.
+    function surfaceState(ctx) {
+        const surface = ctxSurface(ctx);
+        return ctx.scena.layout.get().surfaces[surface];
+    }
+    function setTabPanelTree(ctx, tree) {
+        const surface = ctxSurface(ctx);
+        const cur = ctx.scena.layout.get().surfaces[surface];
+        ctx.scena.layout.setSurface(surface, {
+            ...cur,
+            tabPanel: tree ? { tree } : undefined,
+        });
+    }
+    // Set of pinned mount keys on the right-clicked surface. Bulk-close
+    // commands (closeOthers, closeToRight, ...) filter through this so pinned
+    // tabs survive "close all but me"-style operations — matches VS Code.
+    function pinnedKeys(ctx) {
+        const cur = surfaceState(ctx);
+        return new Set(cur?.split?.pinned ?? []);
+    }
+    // Pin / unpin a tab on the right-clicked surface. Pinned mount keys live
+    // in `state.split.pinned` so they persist with the layout; layouts swap
+    // the × close affordance for a pin icon when a tab is in this set.
+    function togglePinned(ctx, key, pin) {
+        const surface = ctxSurface(ctx);
+        const cur = ctx.scena.layout.get().surfaces[surface];
+        const current = new Set(cur?.split?.pinned ?? []);
+        if (pin)
+            current.add(key);
+        else
+            current.delete(key);
+        ctx.scena.layout.setSurface(surface, {
+            ...cur,
+            split: { ...(cur?.split ?? {}), pinned: [...current] },
+        });
+    }
+    // Walk the tab-panel tree to find a leaf by id; returns the leaf + the
+    // ordered list of tab keys in it (so commands can find siblings).
+    function findLeaf(tree, leafId) {
+        if (tree.kind === 'leaf')
+            return tree.id === leafId ? tree : null;
+        return findLeaf(tree.first, leafId) ?? findLeaf(tree.second, leafId);
+    }
+    // Collect all leaves so commands like `tab.moveToGroup` can list them.
+    function collectLeaves(tree, out = []) {
+        if (tree.kind === 'leaf') {
+            out.push(tree);
+            return out;
+        }
+        collectLeaves(tree.first, out);
+        collectLeaves(tree.second, out);
+        return out;
+    }
+    function replaceLeaf(node, leafId, replacement) {
+        if (node.kind === 'leaf')
+            return node.id === leafId ? replacement : node;
+        return {
+            ...node,
+            first: replaceLeaf(node.first, leafId, replacement),
+            second: replaceLeaf(node.second, leafId, replacement),
+        };
+    }
+    function mapLeaves(node, fn) {
+        if (node.kind === 'leaf')
+            return fn(node);
+        const first = mapLeaves(node.first, fn);
+        const second = mapLeaves(node.second, fn);
+        if (first && second)
+            return { ...node, first, second };
+        return first ?? second;
+    }
+    function newLeafId() {
+        return `g_${Math.random().toString(36).slice(2, 10)}`;
+    }
+    // ── Mount-level commands ─────────────────────────────────────────────────
+    subs.push(scena.commands.register({
+        id: 'tab.close',
+        title: () => translate('tabs/close', 'Close tab'),
+        icon: '✕',
+        color: 'red',
+        slots: ['tab:context', 'card:context'],
+        // Pinned tabs hide the close affordance entirely — the menu shows
+        // Unpin instead, and the user must unpin first to close. Matches
+        // VS Code-style pin semantics.
+        when: '$/tab/isPinned == false',
+        run: (ctx) => {
+            const key = ctxTab(ctx);
+            if (!key)
+                return;
+            ctx.store.set(joinAbs(ctx.dataContext, '/lastClosed'), String(key));
+            ctx.surfaces.close(key);
+            ctx.host?.closeMenu();
+        },
+    }), scena.commands.register({
+        id: 'tab.closeOthers',
+        // title: 'Close others',
+        title: () => translate('tabs/closeOthers', 'Close others'),
+        icon: '−',
+        color: 'orange',
+        slots: ['tab:context'],
+        when: '$/group/tabCount > 1',
+        run: (ctx) => {
+            const key = ctxTab(ctx);
+            const leafId = ctx.store.get('$/tab/leafId');
+            if (!key)
+                return;
+            const keys = tabsInLeafOrSurface(ctx, leafId);
+            const pinned = pinnedKeys(ctx);
+            for (const k of keys)
+                if (k !== key && !pinned.has(k))
+                    ctx.surfaces.close(k);
+            ctx.host?.closeMenu();
+        },
+    }), scena.commands.register({
+        id: 'tab.closeToRight',
+        title: () => translate('tabs/closeRight', 'Close to the right'),
+        icon: '⇥',
+        color: 'orange',
+        slots: ['tab:context'],
+        when: '$/group/tabCount > 1',
+        run: (ctx) => {
+            const key = ctxTab(ctx);
+            if (!key)
+                return;
+            const leafId = ctx.store.get('$/tab/leafId');
+            const keys = tabsInLeafOrSurface(ctx, leafId);
+            const idx = ctxTabIndex(ctx);
+            const pinned = pinnedKeys(ctx);
+            for (let i = idx + 1; i < keys.length; i++) {
+                const k = keys[i];
+                if (k && !pinned.has(k))
+                    ctx.surfaces.close(k);
+            }
+            ctx.host?.closeMenu();
+        },
+    }), scena.commands.register({
+        id: 'tab.closeToLeft',
+        title: () => translate('tabs/closeLeft', 'Close to the left'),
+        icon: '⇤',
+        color: 'orange',
+        slots: ['tab:context'],
+        when: '$/group/tabCount > 1 && $/tab/index > 0',
+        run: (ctx) => {
+            const leafId = ctx.store.get('$/tab/leafId');
+            const keys = tabsInLeafOrSurface(ctx, leafId);
+            const idx = ctxTabIndex(ctx);
+            const pinned = pinnedKeys(ctx);
+            for (let i = 0; i < idx; i++) {
+                const k = keys[i];
+                if (k && !pinned.has(k))
+                    ctx.surfaces.close(k);
+            }
+            ctx.host?.closeMenu();
+        },
+    }), scena.commands.register({
+        id: 'tab.pin',
+        title: () => translate('tabs/pin', 'Pin tab'),
+        icon: '📌︎',
+        color: 'amber',
+        slots: ['tab:context'],
+        // Only visible when this tab is NOT already pinned. The previous
+        // implementation wrote a global `/pinned = true` boolean via
+        // `joinAbs(ctx.dataContext, '/pinned')` — that affected nothing the
+        // layouts read. Per-tab pin state belongs in the surface's
+        // `state.split.pinned` array so it persists with the layout.
+        when: '$/tab/isPinned == false',
+        run: (ctx) => {
+            const key = ctxTab(ctx);
+            if (!key)
+                return;
+            togglePinned(ctx, key, true);
+            ctx.host?.closeMenu();
+        },
+    }), scena.commands.register({
+        id: 'tab.unpin',
+        title: () => translate('tabs/unpin', 'Unpin tab'),
+        icon: '📌︎',
+        color: 'amber',
+        slots: ['tab:context'],
+        when: '$/tab/isPinned == true',
+        run: (ctx) => {
+            const key = ctxTab(ctx);
+            if (!key)
+                return;
+            togglePinned(ctx, key, false);
+            ctx.host?.closeMenu();
+        },
+    }), scena.commands.register({
+        id: 'tab.copyKey',
+        title: () => translate('tabs/copyKey', 'Copy key'),
+        icon: '⎘',
+        color: 'sky',
+        slots: ['tab:context', 'card:context'],
+        run: (ctx) => {
+            const key = ctxTab(ctx);
+            if (!key)
+                return;
+            void navigator.clipboard?.writeText(key);
+            ctx.host?.closeMenu();
+        },
+    }), scena.commands.register({
+        id: 'tab.openToRight',
+        title: () => translate('tabs/openToRight', 'Open to the right'),
+        icon: '⇨',
+        color: 'blue',
+        slots: ['tab:context'],
+        when: '$/tab/canSplit == true',
+        run: (ctx) => splitTabIntoNewLeaf(ctx, 'right'),
+    }), scena.commands.register({
+        id: 'tab.openToBottom',
+        title: () => translate('tabs/openToBottom', 'Open to the bottom'),
+        icon: '⇩',
+        color: 'blue',
+        slots: ['tab:context'],
+        when: '$/tab/canSplit == true',
+        run: (ctx) => splitTabIntoNewLeaf(ctx, 'bottom'),
+    }), scena.commands.register({
+        id: 'tab.openToLeft',
+        title: () => translate('tabs/openToLeft', 'Open to the left'),
+        icon: '⇦',
+        color: 'blue',
+        slots: ['tab:context'],
+        when: '$/tab/canSplit == true',
+        run: (ctx) => splitTabIntoNewLeaf(ctx, 'left'),
+    }), scena.commands.register({
+        id: 'tab.openToTop',
+        title: () => translate('tabs/openToTop', 'Open to the top'),
+        icon: '⇧',
+        color: 'blue',
+        slots: ['tab:context'],
+        when: '$/tab/canSplit == true',
+        run: (ctx) => splitTabIntoNewLeaf(ctx, 'top'),
+    }));
+    // ── Group-level commands ─────────────────────────────────────────────────
+    subs.push(scena.commands.register({
+        id: 'group.closeAll',
+        title: () => translate('tabs/closeAll', 'Close all in group'),
+        icon: '✖',
+        color: 'red',
+        slots: ['tab:context', 'tab-group:context'],
+        when: '$/group/tabCount > 0',
+        run: (ctx) => {
+            const leafId = ctxGroup(ctx);
+            const keys = tabsInLeafOrSurface(ctx, leafId);
+            const pinned = pinnedKeys(ctx);
+            for (const k of keys)
+                if (!pinned.has(k))
+                    ctx.surfaces.close(k);
+            ctx.host?.closeMenu();
+        },
+    }), scena.commands.register({
+        id: 'group.splitRight',
+        title: () => translate('tabs/splitRight', 'Split group right'),
+        icon: '⇨',
+        color: 'blue',
+        slots: ['tab-group:context'],
+        when: '$/tab/canSplit == true',
+        run: (ctx) => splitGroup(ctx, 'row', 'second'),
+    }), scena.commands.register({
+        id: 'group.splitDown',
+        title: () => translate('tabs/splitDown', 'Split group down'),
+        icon: '⇩',
+        color: 'blue',
+        slots: ['tab-group:context'],
+        when: '$/tab/canSplit == true',
+        run: (ctx) => splitGroup(ctx, 'column', 'second'),
+    }), scena.commands.register({
+        id: 'group.splitLeft',
+        title: () => translate('tabs/splitLeft', 'Split group left'),
+        icon: '⇦',
+        color: 'blue',
+        slots: ['tab-group:context'],
+        when: '$/tab/canSplit == true',
+        run: (ctx) => splitGroup(ctx, 'row', 'first'),
+    }), scena.commands.register({
+        id: 'group.splitUp',
+        title: () => translate('tabs/splitUp', 'Split group up'),
+        icon: '⇧',
+        color: 'blue',
+        slots: ['tab-group:context'],
+        when: '$/tab/canSplit == true',
+        run: (ctx) => splitGroup(ctx, 'column', 'first'),
+    }), 
+    // scena.commands.register({
+    //   id: 'group.closeOthersInGroup',
+    //   title: () => translate('tabs/closeOthersInGroup', 'Close others (except active)'),
+    //   icon: '✖',
+    //   color: 'red',
+    //   slots: ['tab-group:context'],
+    //   when: '$/group/tabCount > 1',
+    //   run: (ctx) => {
+    //     const leafId = ctxGroup(ctx);
+    //     const state = surfaceState(ctx);
+    //     const activeKey = state?.activeContainerKey;
+    //     const keys = tabsInLeafOrSurface(ctx, leafId);
+    //     const pinned = pinnedKeys(ctx);
+    //     for (const k of keys) if (k !== activeKey && !pinned.has(k)) ctx.surfaces.close(k);
+    //     ctx.host?.closeMenu();
+    //   },
+    // }),
+    scena.commands.register({
+        id: 'group.closeOtherGroups',
+        title: () => translate('tabs/closeOtherGroups', 'Close others (except active group)'),
+        icon: '✖',
+        color: 'red',
+        slots: ['tab-group:context'],
+        // when: '$/surface/layoutId == "tab-panel"',
+        run: (ctx) => {
+            const leafId = ctxGroup(ctx);
+            const state = surfaceState(ctx);
+            const tree = state?.tabPanel?.tree;
+            if (!tree || !leafId)
+                return;
+            const target = findLeaf(tree, leafId);
+            if (!target)
+                return;
+            // Close every tab not in target leaf, except pinned ones.
+            const keep = new Set(target.tabs);
+            const pinned = pinnedKeys(ctx);
+            const others = [];
+            for (const leaf of collectLeaves(tree)) {
+                if (leaf.id === leafId)
+                    continue;
+                for (const k of leaf.tabs)
+                    if (!keep.has(k) && !pinned.has(k))
+                        others.push(k);
+            }
+            for (const k of others)
+                ctx.surfaces.close(k);
+            // Drop all other leaves from the tree. Pinned tabs in those leaves
+            // were skipped above and remain in the registry — they'll get
+            // re-homed into the surviving target leaf by TabPanelLayout's
+            // orphan-reattach logic on the next render.
+            const next = mapLeaves(tree, (l) => (l.id === leafId ? l : null));
+            setTabPanelTree(ctx, next);
+            ctx.host?.closeMenu();
+        },
+    }), scena.commands.register({
+        id: 'group.close',
+        title: () => translate('tabs/closeGroup', 'Close group'),
+        icon: '✖',
+        color: 'red',
+        slots: ['tab-group:context'],
+        when: '$/group/canClose == true',
+        run: (ctx) => {
+            const leafId = ctxGroup(ctx);
+            const state = surfaceState(ctx);
+            const tree = state?.tabPanel?.tree;
+            if (!tree || !leafId)
+                return;
+            const target = findLeaf(tree, leafId);
+            if (!target)
+                return;
+            const pinned = pinnedKeys(ctx);
+            for (const k of target.tabs)
+                if (!pinned.has(k))
+                    ctx.surfaces.close(k);
+            const next = mapLeaves(tree, (l) => (l.id === leafId ? null : l));
+            setTabPanelTree(ctx, next);
+            ctx.host?.closeMenu();
+        },
+    }));
+    // ── Surface-level commands ───────────────────────────────────────────────
+    subs.push(scena.commands.register({
+        id: 'surface.closeAll',
+        title: () => translate('tabs/closeAll', 'Close all'),
+        icon: '✖',
+        color: 'red',
+        slots: ['surface:context'],
+        when: '$/surface/mountCount > 0',
+        run: (ctx) => {
+            const surface = ctxSurface(ctx);
+            const mounts = ctx.scena.surfaces.listAt(surface);
+            const pinned = pinnedKeys(ctx);
+            for (const m of mounts)
+                if (!pinned.has(m.key))
+                    ctx.surfaces.close(m.key);
+            ctx.host?.closeMenu();
+        },
+    }), ...layoutSwitchCommands(scena));
+    // Prune stale entries from every surface's `state.split.pinned` whenever
+    // a mount closes — covers the bulk-close commands above AND any other
+    // close path (× button, programmatic close, etc.). Without this, closing
+    // a pinned tab leaves its key in the array, so re-opening the same key
+    // later would resurrect a phantom pinned state.
+    subs.push(scena.events.on('scena:mount:closed', (raw) => {
+        const ev = raw;
+        const layout = scena.layout.get();
+        for (const [surface, st] of Object.entries(layout.surfaces)) {
+            const pinned = st?.split?.pinned;
+            if (!pinned || !pinned.includes(ev.key))
+                continue;
+            scena.layout.setSurface(surface, {
+                ...st,
+                split: { ...st.split, pinned: pinned.filter((k) => k !== ev.key) },
+            });
+        }
+    }));
+    return combineDisposables(...subs);
+    // ── Internal helpers (closures over the helpers above) ───────────────────
+    function tabsInLeafOrSurface(ctx, leafId) {
+        const surface = ctxSurface(ctx);
+        if (leafId) {
+            const state = ctx.scena.layout.get().surfaces[surface];
+            const tree = state?.tabPanel?.tree;
+            if (tree) {
+                const leaf = findLeaf(tree, leafId);
+                if (leaf)
+                    return [...leaf.tabs];
+            }
+        }
+        return ctx.scena.surfaces.listAt(surface).map((m) => m.key);
+    }
+    // For TabPanelLayout: split the right-clicked leaf, moving the right-clicked
+    // tab into a new sibling leaf on the given side. Wires the new leaf into
+    // the tree via replaceLeaf. The drag-drop equivalent of this lives in
+    // TabPanelLayout's splitLeafOnDrop — same shape.
+    function splitTabIntoNewLeaf(ctx, side) {
+        const key = ctxTab(ctx);
+        const leafId = ctx.store.get('$/tab/leafId');
+        if (!key || !leafId)
+            return;
+        const state = surfaceState(ctx);
+        const tree = state?.tabPanel?.tree;
+        if (!tree)
+            return;
+        const sourceLeaf = findLeaf(tree, leafId);
+        if (!sourceLeaf)
+            return;
+        // Remove the tab from its source leaf.
+        const remaining = sourceLeaf.tabs.filter((k) => k !== key);
+        const sourceUpdated = {
+            ...sourceLeaf,
+            tabs: remaining,
+            activeKey: remaining.includes(sourceLeaf.activeKey ?? '')
+                ? sourceLeaf.activeKey
+                : remaining[0],
+        };
+        const newLeaf = {
+            kind: 'leaf',
+            id: newLeafId(),
+            tabs: [key],
+            activeKey: key,
+        };
+        const direction = side === 'left' || side === 'right' ? 'row' : 'column';
+        const first = side === 'left' || side === 'top' ? newLeaf : sourceUpdated;
+        const second = side === 'left' || side === 'top' ? sourceUpdated : newLeaf;
+        const split = {
+            kind: 'split',
+            direction,
+            ratio: 0.5,
+            first,
+            second,
+        };
+        const next = replaceLeaf(tree, leafId, split);
+        setTabPanelTree(ctx, next);
+        ctx.host?.closeMenu();
+    }
+    // For TabPanelLayout: split the right-clicked GROUP (leaf), placing the
+    // existing leaf on one side and an empty leaf on the other.
+    function splitGroup(ctx, direction, newSide) {
+        const leafId = ctxGroup(ctx);
+        if (!leafId)
+            return;
+        const state = surfaceState(ctx);
+        const tree = state?.tabPanel?.tree;
+        if (!tree)
+            return;
+        const leaf = findLeaf(tree, leafId);
+        if (!leaf)
+            return;
+        const empty = {
+            kind: 'leaf',
+            id: newLeafId(),
+            tabs: [],
+            activeKey: undefined,
+        };
+        const split = {
+            kind: 'split',
+            direction,
+            ratio: 0.5,
+            first: newSide === 'first' ? empty : leaf,
+            second: newSide === 'first' ? leaf : empty,
+        };
+        const next = replaceLeaf(tree, leafId, split);
+        setTabPanelTree(ctx, next);
+        ctx.host?.closeMenu();
+    }
+}
+// Returns the layout-switch commands as a flat array so they can be spread
+// into the main subs list.
+function layoutSwitchCommands(scena) {
+    const targets = [
+        { id: 'surface.setLayout.tab', title: 'Layout: Tabs', layoutId: 'tab' },
+        { id: 'surface.setLayout.tabPanel', title: 'Layout: Tab groups', layoutId: 'tab-panel' },
+        { id: 'surface.setLayout.split', title: 'Layout: Split', layoutId: 'split' },
+        { id: 'surface.setLayout.spatial', title: 'Layout: Spatial', layoutId: 'spatial' },
+        { id: 'surface.setLayout.stack', title: 'Layout: Stack', layoutId: 'stack' },
+        { id: 'surface.setLayout.single', title: 'Layout: Single', layoutId: 'single' },
+    ];
+    return targets.map((t) => scena.commands.register({
+        id: t.id,
+        title: t.title,
+        slots: ['surface:context'],
+        when: `$/surface/layoutId != "${t.layoutId}"`,
+        run: (ctx) => {
+            const surface = (ctx.store.get('$/surface/name') ?? 'main');
+            const cur = ctx.scena.layout.get().surfaces[surface];
+            ctx.scena.layout.setSurface(surface, { ...cur, layout: t.layoutId });
+            ctx.host?.closeMenu();
+        },
+    }));
+}

package/dist/runtime/opener-commands.d.ts

@@ -0,0 +1,17 @@
+import type { Scena } from '../types/scena.js';
+import type { Disposable } from '../types/disposable.js';
+import type { CommandContext } from '../types/command.js';
+import type { ComponentDefinition } from '../types/component-registry.js';
+import type { SurfaceName } from '../types/mount-surface.js';
+export interface RegisterOpenerCommandsOptions {
+    resourceKind: string;
+    slots?: string[];
+    category?: string;
+    commandIdPrefix?: string;
+    surface?: SurfaceName;
+    mountKey?: (resourceId: string, viewerComponent: string) => string;
+    resourceProps?: (resourceId: string) => Record<string, unknown>;
+    resourceTitle?: (resourceId: string) => string;
+    onOpen?: (ctx: CommandContext, viewer: ComponentDefinition, resourceId: string) => void;
+}
+export declare function registerOpenerCommands(scena: Scena, opts: RegisterOpenerCommandsOptions): Disposable;

package/dist/runtime/opener-commands.js

@@ -0,0 +1,96 @@
+import { disposableFrom } from '../core/disposable.js';
+import { resolveLabel } from '../core/label.js';
+import { translate } from '../i18n/registry.js';
+export function registerOpenerCommands(scena, opts) {
+    const slots = opts.slots ?? ['file:context'];
+    const category = opts.category ?? 'Open with';
+    const surface = opts.surface ?? 'main';
+    const mountKey = opts.mountKey ?? ((id, comp) => `${opts.resourceKind}:${comp}:${id}`);
+    const commandIdPrefix = opts.commandIdPrefix ?? `openWith.${opts.resourceKind}`;
+    const resourceProps = opts.resourceProps ?? ((id) => ({ path: id }));
+    const resourceTitle = opts.resourceTitle ?? ((id) => id);
+    const kindGuard = `$/resource/kind == "${opts.resourceKind}"`;
+    // viewer component id → disposable of its generated command. Used both
+    // to dispose departed viewers' commands and to skip re-registering ones
+    // that are still around on resync.
+    const active = new Map();
+    function registerFor(def) {
+        // ComponentOpensSpec.selector is a WhenClause (`/...` paths). The when
+        // engine reads `$/...` paths, so we rewrite the leading `/` to `$/` if
+        // the caller didn't already use the absolute form. A prior version
+        // also rewrote later embedded paths but accidentally double-prefixed
+        // the leading `$/` to `$$/`, which the when parser couldn't resolve —
+        // breaking single-path selectors like `/resource/ext == "md"`.
+        const sel = def.opens?.selector;
+        const selWhen = typeof sel === 'string' ? (sel.startsWith('$/') ? sel : sel.replace(/^\//, '$/')) : null;
+        const when = selWhen ? `${kindGuard} && ${selWhen}` : kindGuard;
+        const sub = scena.commands.register({
+            id: `${commandIdPrefix}.${def.component}`,
+            title: resolveLabel(def.opens?.title ?? def.component, {
+                get: (path) => {
+                    // Expose the resource's properties for label resolution (e.g.
+                    // `{ path }` bindings in the title can read `$/resource/path`).
+                    if (path.startsWith('$/'))
+                        return scena.store.get(path);
+                    return undefined;
+                },
+                translate: (key) => translate(key),
+            }) ?? def.component,
+            icon: def.opens?.icon,
+            color: def.opens?.color,
+            category,
+            slots,
+            when,
+            run: (ctx) => {
+                const id = ctx.store.get('$/resource/id');
+                if (!id)
+                    return;
+                ctx.scena.surfaces.open({
+                    surface,
+                    key: mountKey(id, def.component),
+                    resource: { component: def.component, ...resourceProps(id) },
+                    // Tab/section header gets the resource's display name + the
+                    // viewer's own icon/color so e.g. a Markdown-opened .md file
+                    // tab shows the filename in violet with the memo glyph.
+                    props: {
+                        title: resourceTitle(id),
+                        icon: def.opens?.icon,
+                        color: def.opens?.color,
+                    },
+                });
+                opts.onOpen?.(ctx, def, id);
+                ctx.host?.closeMenu();
+            },
+        });
+        active.set(def.component, sub);
+    }
+    function sync() {
+        const present = new Set();
+        for (const def of scena.components.findOpeners(opts.resourceKind)) {
+            present.add(def.component);
+            if (active.has(def.component))
+                continue; // already registered
+            registerFor(def);
+        }
+        // Dispose commands for viewers no longer present.
+        for (const [comp, sub] of active) {
+            if (present.has(comp))
+                continue;
+            sub.dispose();
+            active.delete(comp);
+        }
+    }
+    // Initial pass, then subscribe to component-registry changes.
+    sync();
+    const sub = scena.events.on('scena:registry:changed', (payload) => {
+        if (payload.registry !== 'components')
+            return;
+        sync();
+    });
+    return disposableFrom(() => {
+        sub.dispose();
+        for (const s of active.values())
+            s.dispose();
+        active.clear();
+    });
+}

package/dist/runtime/surface-bridge.d.ts

@@ -0,0 +1,15 @@
+import type { Disposable } from '../types/disposable.js';
+import type { EventBus } from '../types/events.js';
+import type { ReactiveStore, SocketBridge } from '../types/reactive-store.js';
+import type { MountSurfaceRegistry, SurfaceName } from '../types/mount-surface.js';
+import type { ConverterRegistry } from '../types/converter-registry.js';
+interface Deps {
+    store: ReactiveStore;
+    surfaces: MountSurfaceRegistry;
+    converters: ConverterRegistry;
+    socket: SocketBridge;
+    events: EventBus;
+    defaultSurface?: SurfaceName;
+}
+export declare function createSurfaceBridge(deps: Deps): Disposable;
+export {};