@forgeax/interface 0.4.1

package/dist/package/node/core/app-shell/catalog-page-extensions.js

@@ -0,0 +1,234 @@
+import { createElement } from 'react';
+import { encodePageKey, qualifyContributionId, resolveContributionRef, } from '@forgeax/types';
+import { listExtensions, listExtensionsShared, } from '../../lib/extension-api.js';
+import { ExtensionHostPanel } from '../../components/DockShell/ExtensionHostPanel.js';
+import { isExtensionHostExtension } from '../../components/DockShell/extensionRuntime.js';
+import { getLocale } from '../../i18n/index.js';
+function title(value) {
+    if (typeof value === 'string')
+        return value;
+    const locale = getLocale();
+    return value[locale] ?? value.en ?? value.zh ?? value.ja ?? '';
+}
+export function catalogExtensionItems(payload) {
+    if (!payload || typeof payload !== 'object')
+        return [];
+    const items = payload.items;
+    return Array.isArray(items) ? items : [];
+}
+export function extensionPane(initialProps) {
+    const pane = initialProps?.pane;
+    return pane === 'left' || pane === 'center' ? pane : undefined;
+}
+/** Adapt scanner-normalized panel types into Page runtime registrations. */
+function extensionHostPanelRegistration(item, panelTypeId) {
+    return {
+        id: panelTypeId,
+        runtime: {
+            kind: 'inline',
+            render: (context) => createElement(ExtensionHostPanel, {
+                extensionId: item.id,
+                pane: extensionPane(context.initialProps),
+            }),
+        },
+        ...(item.entry?.standalone && !isExtensionHostExtension(item.id)
+            ? {
+                windowing: {
+                    createTarget: (context) => {
+                        const pane = extensionPane(context.initialProps);
+                        return {
+                            surface: {
+                                kind: 'plugin',
+                                id: item.id,
+                                ...(pane ? { pane } : {}),
+                                instance: `${encodePageKey(context.pageKey)}::${context.placementId}`,
+                            },
+                            title: title(item.displayName),
+                            width: 960,
+                            height: 720,
+                            dockBehavior: 'keep-anchor',
+                        };
+                    },
+                },
+            }
+            : {}),
+    };
+}
+export function catalogPanelTypeRegistrations(item) {
+    const byId = new Map();
+    for (const panel of item.contributes?.panelTypes ?? []) {
+        const id = qualifyContributionId(item.id, 'panel', panel.id);
+        byId.set(id, extensionHostPanelRegistration(item, id));
+    }
+    for (const page of item.contributes?.pages ?? []) {
+        for (const placement of page.panels ?? []) {
+            const id = resolveContributionRef(item.id, 'panel', placement.panelType);
+            if (!byId.has(id))
+                byId.set(id, extensionHostPanelRegistration(item, id));
+        }
+    }
+    return [...byId.values()];
+}
+/** Browser-side activation of scanner-normalized page contributions. Hosts may
+ * override an extension with a richer in-process implementation by using the
+ * same extension id; those ids are filtered before this adapter runs. */
+export function catalogPageExtensions(items, overriddenIds) {
+    return items.flatMap((item) => {
+        const contributes = item.contributes;
+        if (!contributes?.pages?.length || overriddenIds.has(item.id))
+            return [];
+        const panelTypes = catalogPanelTypeRegistrations(item);
+        const pages = contributes.pages.map((page) => {
+            const placements = (page.panels ?? []).map((placement) => ({
+                id: placement.id,
+                panelTypeId: resolveContributionRef(item.id, 'panel', placement.panelType),
+                title: placement.title ? title(placement.title) : undefined,
+                optional: placement.optional,
+                initialProps: placement.initialProps,
+            }));
+            return {
+                id: qualifyContributionId(item.id, 'page', page.id),
+                title: title(page.title),
+                cardinality: page.cardinality,
+                restorePolicy: page.restorePolicy,
+                layoutVersion: page.layoutVersion,
+                panels: placements,
+                layout: page.layout,
+            };
+        });
+        const activities = (contributes.activities ?? []).map((activity) => ({
+            id: qualifyContributionId(item.id, 'activity', activity.id),
+            title: title(activity.title),
+            titleI18n: typeof activity.title === 'string' ? undefined : activity.title,
+            description: item.description ? title(item.description) : undefined,
+            descriptionI18n: item.description && typeof item.description !== 'string'
+                ? item.description
+                : undefined,
+            icon: activity.icon,
+            category: activity.category,
+            order: activity.order,
+            // Host-injected source layer — scanner-loaded extensions are all
+            // installed-tier, so they sort AFTER builtin core nav regardless of the
+            // `order` they declare (or omit). Never taken from the manifest.
+            sourceLayer: 'installed',
+            pageTypeId: activity.pageType
+                ? resolveContributionRef(item.id, 'page', activity.pageType)
+                : undefined,
+            commandId: activity.commandId,
+        }));
+        const resourceEditors = (contributes.resourceEditors ?? []).map((editor) => ({
+            id: qualifyContributionId(item.id, 'resource-editor', editor.id),
+            selector: editor.selector,
+            pageTypeId: resolveContributionRef(item.id, 'page', editor.pageType),
+            priority: editor.priority,
+            sourceLayer: 'installed',
+        }));
+        return [{
+                id: item.id,
+                version: item.version,
+                requires: ['pages'],
+                contributes: { panelTypes, pages, activities, resourceEditors },
+            }];
+    });
+}
+export async function loadCatalogPageExtensions(overriddenIds) {
+    try {
+        const response = await listExtensionsShared();
+        return catalogPageExtensions(catalogExtensionItems(response), overriddenIds);
+    }
+    catch {
+        return [];
+    }
+}
+function catalogItemSignature(item) {
+    if (!item)
+        return '';
+    const { registryGeneration: _registryGeneration, ...content } = item;
+    return JSON.stringify(content);
+}
+/** Registry-generation-driven lifecycle for scanner contributions. It only
+ * owns catalog Page/Panel/Activity registrations; product overrides and
+ * in-process extension setup remain under the main ExtensionLoader. */
+export function createCatalogPageExtensionRuntime(options) {
+    // Reload events are authoritative: neither a short-lived cache nor an older
+    // request from another consumer may swallow the only change notification.
+    // This runtime already serializes its own reads through the refresh chain.
+    const load = options.load ?? (() => listExtensions());
+    const onError = options.onError ?? ((error, extensionId, phase) => {
+        console.error(`[forgeax:extension-catalog] ${phase} failed for "${extensionId}"`, error);
+    });
+    const active = new Map();
+    let generation;
+    let events;
+    let chain = Promise.resolve();
+    let disposed = false;
+    const reconcile = async (response) => {
+        if (generation !== undefined && response.generation === generation)
+            return;
+        const itemsById = new Map(response.items.map((item) => [item.id, item]));
+        const next = new Map(catalogPageExtensions(response.items, options.overriddenIds)
+            .map((extension) => [extension.id, extension]));
+        for (const [id, record] of [...active]) {
+            const item = itemsById.get(id);
+            const signature = catalogItemSignature(item);
+            if (!next.has(id) || signature !== record.signature) {
+                try {
+                    await record.cleanup();
+                    active.delete(id);
+                }
+                catch (error) {
+                    onError(error, id, 'cleanup');
+                }
+            }
+        }
+        for (const [id, extension] of next) {
+            if (active.has(id))
+                continue;
+            const contributes = extension.contributes;
+            try {
+                const cleanup = options.control.contributePagePlatform(id, {
+                    pageTypes: contributes?.pages,
+                    panelTypes: contributes?.panelTypes,
+                    activities: contributes?.activities,
+                    resourceEditors: contributes?.resourceEditors,
+                });
+                active.set(id, { signature: catalogItemSignature(itemsById.get(id)), cleanup });
+            }
+            catch (error) {
+                onError(error, id, 'register');
+            }
+        }
+        generation = response.generation;
+    };
+    const refresh = () => {
+        chain = chain.catch(() => undefined).then(async () => {
+            if (!disposed)
+                await reconcile(await load());
+        });
+        return chain;
+    };
+    return {
+        refresh,
+        async start() {
+            await refresh().catch(() => undefined);
+            if (!disposed) {
+                try {
+                    events = new EventSource('/api/events/stream?topic=plugin.reloaded');
+                    events.addEventListener('event', () => { void refresh().catch(() => undefined); });
+                }
+                catch {
+                    // EventSource is optional in non-browser/test hosts.
+                }
+            }
+        },
+        async dispose() {
+            disposed = true;
+            events?.close();
+            events = undefined;
+            await chain.catch(() => undefined);
+            for (const record of [...active.values()].reverse())
+                await record.cleanup();
+            active.clear();
+        },
+    };
+}

package/dist/package/node/core/app-shell/derive-panel-renderers.js

@@ -0,0 +1,17 @@
+// packages/interface/src/core/app-shell/derive-panel-renderers.ts
+//
+// The fold from contribution entries to the PanelRenderers view — ADR 0025
+// M2's "manifestToPanelRenderers" direction: the ContributionRegistry is the
+// SSOT; host.panels is a memoized snapshot of this pure function.
+//
+// Merge semantics are owned by the public @forgeax/app-shell contract:
+//   - object fields (overlays / surfaces / chrome / detached / slots /
+//     extensionTransport / panels / extensionPanels / editor / builtinPageLayouts):
+//     one-level sub-merge — later patches win per sub-key, siblings preserved
+//   - array fields (editorPanelIds): whole-value REPLACE
+//   - undefined patch fields: skipped
+//   - `base` and patch objects are never mutated (copy-on-write per field)
+import { deriveShellSnapshot } from '@forgeax/app-shell';
+export function derivePanelRenderers(base, patches) {
+    return deriveShellSnapshot(base, patches);
+}

package/dist/package/node/core/app-shell/host.js

@@ -0,0 +1,188 @@
+// packages/interface/src/core/app-shell/host.ts
+import { createCommandsRegistry, } from '../extension-foundation/commands.js';
+import { EventBus } from '../extension-foundation/bus.js';
+import { createContextKeys } from '../extension-foundation/context-keys.js';
+import { createStorageApi } from '../extension-foundation/storage.js';
+import { createCapabilityRegistry } from '../extension-foundation/capabilities.js';
+import { createContributionRegistry } from '../extension-foundation/contribution-registry.js';
+import { ExtensionConflictError } from '../extension-foundation/errors.js';
+import { createPanelActionRegistry, createPanelControlRegistry } from '../panels/index.js';
+import { createPageRegistry, createPageSession, createActivityRegistry, createResourceEditorResolver, } from '../page-platform/index.js';
+import { consoleLogger } from './logger.js';
+import { derivePanelRenderers } from './derive-panel-renderers.js';
+import { DEFAULT_PANEL_RENDERERS } from '../../components/DockShell/panelRenderers.js';
+import { installPageNavigation } from '../page-navigation.js';
+import { createContextualKeybindings } from '../contextual-keybindings.js';
+const BUILT_IN_CAPS = [
+    'commands', 'keybindings', 'bus', 'storage', 'panels', 'panelActions', 'panelControls', 'contextKeys', 'pages',
+    'activities', 'resourceEditors',
+];
+export function createAppHost(deps = {}) {
+    const log = deps.log ?? consoleLogger;
+    const caps = createCapabilityRegistry();
+    for (const c of BUILT_IN_CAPS)
+        caps.add(c);
+    const commands = createCommandsRegistry();
+    const keybindings = createContextualKeybindings(commands, {
+        onCommandError(error, commandId) {
+            log.error(`[app-shell] keybinding command "${commandId}" failed`, error);
+        },
+    });
+    const bus = new EventBus();
+    const storage = createStorageApi(log);
+    const contextKeys = createContextKeys();
+    const panelActions = createPanelActionRegistry();
+    const panelControls = createPanelControlRegistry();
+    // Page Types and Panel Types share one owner-tagged contribution bundle.
+    // A bundle publish is one registry change, so the PageRegistry never exposes
+    // a page without the panel types activated in the same extension setup.
+    const pageContributions = createContributionRegistry();
+    const pageRegistry = createPageRegistry(pageContributions);
+    const pageSession = createPageSession(pageRegistry);
+    const activities = createActivityRegistry(pageContributions, pageSession, commands);
+    const resourceEditors = createResourceEditorResolver(pageContributions, pageSession);
+    // ADR 0025 M2: the ContributionRegistry is the SSOT; host.panels is a
+    // memoized DERIVED snapshot (new identity per registry version — App.tsx
+    // reads it through useSyncExternalStore, so post-boot contributions and
+    // cleanups re-render the shell). deps.initialPanels joins as the host-owned
+    // baseline contribution.
+    const panelsRegistry = createContributionRegistry();
+    if (deps.initialPanels)
+        panelsRegistry.contribute('(host)', deps.initialPanels);
+    let panelsCache = null;
+    const panelsSnapshot = () => {
+        const v = panelsRegistry.version();
+        if (panelsCache?.v === v)
+            return panelsCache.snap;
+        const snap = derivePanelRenderers(DEFAULT_PANEL_RENDERERS, panelsRegistry.entries().map((e) => e.item));
+        panelsCache = { v, snap };
+        return snap;
+    };
+    const extensions = [];
+    const extensionFields = {};
+    let activeSetup = null;
+    const base = {
+        commands, keybindings, bus, storage, contextKeys,
+        get panels() { return panelsSnapshot(); },
+        panelActions,
+        panelControls,
+        pages: pageSession,
+        pageRegistry,
+        activities,
+        resourceEditors,
+        get capabilities() { return caps.snapshot(); },
+        extend(capability, api) {
+            if (activeSetup === null) {
+                throw new Error(`[app-shell] host.extend("${String(capability)}") called outside plugin setup`);
+            }
+            if (!activeSetup.provides?.includes(capability)) {
+                throw new ExtensionConflictError({
+                    id: String(capability), subRegistryName: 'host.extend',
+                    existingOwner: '(none)', newOwner: activeSetup.id,
+                });
+            }
+            if (extensionFields[capability] !== undefined) {
+                const orig = extensions.find((e) => e.capability === capability);
+                throw new ExtensionConflictError({
+                    id: String(capability), subRegistryName: 'host.extend',
+                    existingOwner: orig?.owner ?? '(unknown)', newOwner: activeSetup.id,
+                });
+            }
+            if (BUILT_IN_CAPS.includes(capability)) {
+                throw new ExtensionConflictError({
+                    id: String(capability), subRegistryName: 'host.extend',
+                    existingOwner: '(built-in)', newOwner: activeSetup.id,
+                });
+            }
+            extensionFields[capability] = api;
+            extensions.push({ capability, owner: activeSetup.id });
+            caps.add(capability);
+            bus.emit('capability:added', { capability: String(capability), provider: activeSetup.id });
+        },
+        contributeStatusItem(item) {
+            // Runtime imperative registration routed through the ONE panels channel
+            // (owner '(runtime)' is never batch-removed by removeExtensionsByOwner;
+            // lifecycle is the returned Cleanup — unmount/dispose removes this entry).
+            return panelsRegistry.contribute('(runtime)', { stripItems: { [item.id]: item } });
+        },
+    };
+    const host = new Proxy(base, {
+        get(target, prop, receiver) {
+            if (prop in target)
+                return Reflect.get(target, prop, receiver);
+            if (typeof prop === 'string' && prop in extensionFields)
+                return extensionFields[prop];
+            return undefined;
+        },
+        has(target, prop) {
+            return prop in target || (typeof prop === 'string' && prop in extensionFields);
+        },
+        set() { throw new TypeError('[app-shell] host is read-only; use host.extend'); },
+        defineProperty() { throw new TypeError('[app-shell] host is read-only; use host.extend'); },
+        deleteProperty() { throw new TypeError('[app-shell] host is read-only; use control.removeExtensionsByOwner'); },
+        ownKeys(target) {
+            return Reflect.ownKeys(target).concat(Object.keys(extensionFields).filter((k) => !Reflect.has(target, k)));
+        },
+        getOwnPropertyDescriptor(target, prop) {
+            const own = Reflect.getOwnPropertyDescriptor(target, prop);
+            if (own)
+                return own;
+            if (typeof prop === 'string' && prop in extensionFields) {
+                return { value: extensionFields[prop], enumerable: true, configurable: true, writable: false };
+            }
+            return undefined;
+        },
+    });
+    const removePageNavigation = installPageNavigation(host);
+    const control = {
+        beginSetup(m) {
+            if (activeSetup !== null) {
+                throw new Error(`[app-shell] beginSetup("${m.id}") while "${activeSetup.id}" still active`);
+            }
+            activeSetup = m;
+        },
+        endSetup() { activeSetup = null; },
+        capabilities: caps,
+        contributePanels(owner, patch) { return panelsRegistry.contribute(owner, patch); },
+        contributePanelActions(owner, actions) { return panelActions.contribute(owner, actions); },
+        contributePanelControls(owner, controls) { return panelControls.contribute(owner, controls); },
+        contributePagePlatform(owner, contribution) {
+            pageRegistry.validateContribution(owner, contribution);
+            const removeContribution = pageContributions.contribute(owner, contribution);
+            let removed = false;
+            return async () => {
+                if (removed)
+                    return;
+                // The registry still knows the owner while controllers preflight close.
+                // A dirty/vetoed page rejects cleanup and leaves the contribution live.
+                await pageSession.closeOwnedBy(owner);
+                removeContribution();
+                removed = true;
+            };
+        },
+        onPanelsChange(listener) { return panelsRegistry.onChange(listener); },
+        removeExtensionsByOwner(ownerId) {
+            const indices = [];
+            for (let i = extensions.length - 1; i >= 0; i--) {
+                if (extensions[i]?.owner === ownerId)
+                    indices.push(i);
+            }
+            for (const i of indices) {
+                const rec = extensions[i];
+                if (!rec)
+                    continue;
+                bus.emit('capability:removed', { capability: String(rec.capability), provider: rec.owner });
+                delete extensionFields[rec.capability];
+                caps.remove(rec.capability);
+                extensions.splice(i, 1);
+            }
+        },
+        async dispose() {
+            removePageNavigation();
+            await pageSession.dispose();
+            keybindings.dispose();
+            bus.destroy();
+        },
+    };
+    return { host, control };
+}

package/dist/package/node/core/app-shell/index.js

@@ -0,0 +1,8 @@
+// packages/interface/src/core/app-shell/index.ts
+export * from './types.js';
+export * from './host.js';
+export * from './logger.js';
+export { HostProvider, useHost, useCommand, useContextKey, useKeybindingScope } from './react/HostProvider.js';
+export * from '../contextual-keybindings.js';
+export * from '../page-platform/index.js';
+export { APP_SHELL_OWNERSHIP } from './ownership.js';

package/dist/package/node/core/app-shell/logger.js

@@ -0,0 +1,6 @@
+export const consoleLogger = {
+    debug: (m, ...r) => console.debug(`[app-shell] ${m}`, ...r),
+    info: (m, ...r) => console.info(`[app-shell] ${m}`, ...r),
+    warn: (m, ...r) => console.warn(`[app-shell] ${m}`, ...r),
+    error: (m, ...r) => console.error(`[app-shell] ${m}`, ...r),
+};

package/dist/package/node/core/app-shell/ownership.js

@@ -0,0 +1,7 @@
+export const APP_SHELL_OWNERSHIP = {
+    source: 'forgeax-interface',
+    owner: 'forgeax-extension-platform',
+    destination: '@forgeax/app-shell',
+    status: 'migration-candidate',
+    rule: 'generic composition only; domain features remain outside this package',
+};

package/dist/package/node/core/app-shell/react/HostProvider.js

@@ -0,0 +1,35 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// Compatibility adapter while Interface consumers migrate to
+// @forgeax/app-shell/application. The provider delegates to App Shell so every
+// product shares one React context identity; the local hooks retain Interface's
+// narrower host type until its remaining product shell is retired.
+import { useCallback, useEffect, useState } from 'react';
+import { HostProvider as ApplicationHostProvider, useHost as useApplicationHost, } from '@forgeax/app-shell/application';
+export const HostProvider = ({ value, children }) => (_jsx(ApplicationHostProvider, { value: value, children: children }));
+export function useHost() {
+    return useApplicationHost();
+}
+export function useCommand(id) {
+    const host = useHost();
+    return useCallback((args) => host.commands.execute(id, args), [host, id]);
+}
+export function useContextKey(key) {
+    const host = useHost();
+    const [value, setValue] = useState(() => host.contextKeys.get(key));
+    useEffect(() => {
+        setValue(host.contextKeys.get(key));
+        const dispose = host.contextKeys.onChange(key, (next) => setValue(next));
+        return () => { void dispose(); };
+    }, [host, key]);
+    return value;
+}
+export function useKeybindingScope(ref, scopeId) {
+    const host = useHost();
+    useEffect(() => {
+        const element = ref.current;
+        if (!element)
+            return;
+        const dispose = host.keybindings.registerScope(element, scopeId);
+        return () => { void dispose(); };
+    }, [host, ref, scopeId]);
+}

package/dist/package/node/core/app-shell/surface-extension.js

@@ -0,0 +1,33 @@
+import { createElement } from 'react';
+/** Compose product-owned React surfaces into the shell without pretending they
+ * are marketplace manifests. Extension manifests contribute Pages and Panels;
+ * this adapter is only for Studio's in-process application assembly. */
+export function createAppSurfaceExtension(input) {
+    const surface = input.surface ?? 'dock';
+    let panels;
+    if (surface === 'detached' || surface === 'chrome') {
+        panels = { [surface]: { ...input.components } };
+    }
+    else if (surface === 'overlay') {
+        panels = { overlays: { ...input.components } };
+    }
+    else if (surface === 'slot') {
+        panels = { slots: { ...input.components } };
+    }
+    else {
+        const Component = Object.values(input.components)[0];
+        const panelId = input.panelId ?? input.id;
+        panels = {
+            panels: {
+                [panelId]: {
+                    title: input.title,
+                    order: input.order,
+                    icon: input.icon,
+                    ...(input.singleTab ? { dockChrome: { singleTab: input.singleTab } } : {}),
+                    render: () => createElement(Component),
+                },
+            },
+        };
+    }
+    return { id: input.id, version: input.version ?? '1.0.0', contributes: { panels } };
+}

package/dist/package/node/core/app-shell/types.js

@@ -0,0 +1 @@
+export {};