@forgeax/interface 0.4.1

package/dist/package/node/core/page-platform/resource-editor.js

@@ -0,0 +1,74 @@
+import { PagePlatformError } from './types.js';
+const ASSOCIATIONS_KEY = 'forgeax.resource-editor-associations.v1';
+const layerRank = { builtin: 0, installed: 1, project: 2, user: 3 };
+function matches(editor, resource) {
+    const selector = editor.selector;
+    let scheme;
+    try {
+        scheme = new URL(resource.uri).protocol.replace(/:$/u, '');
+    }
+    catch { /* path-like URI */ }
+    const path = (resource.displayPath ?? resource.uri).split(/[?#]/u, 1)[0] ?? '';
+    const leaf = path.slice(path.lastIndexOf('/') + 1);
+    const extension = leaf.includes('.') ? leaf.slice(leaf.lastIndexOf('.') + 1).toLowerCase() : '';
+    return Boolean((scheme && selector.schemes?.includes(scheme))
+        || (extension && selector.extensions?.map((value) => value.replace(/^\./u, '').toLowerCase()).includes(extension))
+        || (resource.mime && selector.mimeTypes?.includes(resource.mime))
+        || (resource.kind && selector.kinds?.includes(resource.kind)));
+}
+function byRank(a, b) {
+    return layerRank[b.sourceLayer ?? 'installed'] - layerRank[a.sourceLayer ?? 'installed']
+        || Number(b.priority === 'default') - Number(a.priority === 'default')
+        || a.id.localeCompare(b.id);
+}
+function readAssociations() {
+    try {
+        const parsed = JSON.parse(localStorage.getItem(ASSOCIATIONS_KEY) ?? '{}');
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function writeAssociations(value) {
+    try {
+        localStorage.setItem(ASSOCIATIONS_KEY, JSON.stringify(value));
+    }
+    catch { /* unavailable */ }
+}
+export function createResourceEditorResolver(contributions, pages) {
+    const sortedCandidates = (resource) => {
+        const all = contributions.entries().flatMap(({ item }) => item.resourceEditors ?? []);
+        // A fallback selector carries no matchers (schema-enforced mutual exclusion),
+        // so `matches` never admits it here — targeted editors form a strictly
+        // higher tier than default editors regardless of layer or priority.
+        const targeted = all.filter((editor) => matches(editor, resource)).sort(byRank);
+        const fallbacks = all.filter((editor) => editor.selector.fallback === true).sort(byRank);
+        const preferred = readAssociations()[resource.canonicalId];
+        // Stable sort, so an explicit user association is the only thing that can
+        // lift a default editor above a targeted one.
+        return [...targeted, ...fallbacks]
+            .sort((a, b) => Number(b.id === preferred) - Number(a.id === preferred));
+    };
+    return {
+        list: sortedCandidates,
+        resolve(resource) {
+            return sortedCandidates(resource)[0];
+        },
+        async open(resource) {
+            const editor = this.resolve(resource);
+            if (!editor) {
+                throw new PagePlatformError('RESOURCE_EDITOR_NOT_FOUND', `no resource editor matches "${resource.uri}"`, { canonicalId: resource.canonicalId, uri: resource.uri });
+            }
+            return pages.open({ typeId: editor.pageTypeId, resource });
+        },
+        setUserAssociation(resource, editorId) {
+            const next = readAssociations();
+            if (editorId)
+                next[resource.canonicalId] = editorId;
+            else
+                delete next[resource.canonicalId];
+            writeAssociations(next);
+        },
+    };
+}

package/dist/package/node/core/page-platform/session.js

@@ -0,0 +1,327 @@
+import { decodePageKey, encodePageKey, } from '@forgeax/types';
+import { PagePlatformError } from './types.js';
+import { getCurrentProject, subscribeCurrentProject } from '../../lib/project-context.js';
+const inertController = {
+    prepareClose: () => ({ status: 'ready' }),
+    dispose: () => undefined,
+};
+function normalizeKey(key) {
+    return typeof key === 'string' ? decodePageKey(key) : key;
+}
+export function createPageSession(registry, options = {}) {
+    const createInstanceId = options.createInstanceId ?? (() => crypto.randomUUID());
+    const now = options.now ?? (() => Date.now());
+    const entries = new Map();
+    // Controller-reflected live titles, keyed by encoded key — merged into the
+    // snapshot so the instance record stays immutable while the tab label can
+    // change. `titleSubs` holds the matching `subscribeTitle` unsubscribe fns.
+    const titles = new Map();
+    const titleSubs = new Map();
+    const listeners = new Set();
+    let generation = 0;
+    let activeKey;
+    let snapshot = { generation, instances: [] };
+    let registryUnsubscribe = () => undefined;
+    let projectUnsubscribe = () => undefined;
+    let restoring = false;
+    const recentKey = (policy) => policy === 'project'
+        ? `forgeax:project:${getCurrentProject()}:recent-page`
+        : 'forgeax:session:recent-page';
+    const persistRecent = () => {
+        if (typeof localStorage === 'undefined')
+            return;
+        if (!activeKey)
+            return;
+        const entry = entries.get(activeKey);
+        if (!entry)
+            return;
+        const resolved = registry.get(entry.instance.typeId);
+        if (!resolved || resolved.status !== 'available')
+            return;
+        const policy = resolved.definition.restorePolicy ?? 'never';
+        if (policy === 'never')
+            return;
+        const request = {
+            typeId: entry.instance.typeId,
+            ...(entry.instance.resource ? { resource: entry.instance.resource } : {}),
+            ...(Object.keys(entry.instance.context).length > 0 ? { context: entry.instance.context } : {}),
+        };
+        try {
+            localStorage.setItem(recentKey(policy), JSON.stringify(request));
+        }
+        catch { /* quota/private mode */ }
+    };
+    const publish = () => {
+        generation++;
+        snapshot = {
+            generation,
+            ...(activeKey ? { activeKey } : {}),
+            instances: [...entries.entries()].map(([encoded, entry]) => titles.has(encoded) ? { ...entry.instance, title: titles.get(encoded) } : entry.instance),
+        };
+        for (const listener of [...listeners])
+            listener();
+    };
+    // Reflect a controller's reactive title (getTitle + subscribeTitle) into the
+    // `titles` overlay. Reads the initial value synchronously (so the first
+    // snapshot already carries it) and republishes on every change event.
+    const bindTitle = (encoded, controller) => {
+        const read = () => {
+            const next = controller.getTitle?.();
+            const current = titles.get(encoded);
+            if (next === current)
+                return;
+            if (next === undefined)
+                titles.delete(encoded);
+            else
+                titles.set(encoded, next);
+            if (entries.has(encoded))
+                publish();
+        };
+        const initial = controller.getTitle?.();
+        if (initial !== undefined)
+            titles.set(encoded, initial);
+        if (controller.subscribeTitle) {
+            titleSubs.set(encoded, controller.subscribeTitle(() => read()));
+        }
+    };
+    const unbindTitle = (encoded) => {
+        titleSubs.get(encoded)?.();
+        titleSubs.delete(encoded);
+        titles.delete(encoded);
+    };
+    const requireEntry = (key) => {
+        const normalized = normalizeKey(key);
+        const encoded = encodePageKey(normalized);
+        const entry = entries.get(encoded);
+        if (!entry) {
+            throw new PagePlatformError('PAGE_INSTANCE_NOT_FOUND', `page instance "${encoded}" is not open`, { key: encoded });
+        }
+        return { encoded, entry };
+    };
+    const resolvePreparation = async (entry, reason, decision) => {
+        const preparation = await entry.controller.prepareClose(reason);
+        if (preparation.status === 'ready')
+            return;
+        if (preparation.status === 'vetoed') {
+            throw new PagePlatformError('PAGE_CLOSE_VETOED', preparation.message ?? 'page refused to close', {
+                key: entry.instance.encodedKey,
+                reason,
+            });
+        }
+        if (!decision || decision === 'cancel') {
+            throw new PagePlatformError('PAGE_CLOSE_REQUIRES_DECISION', preparation.message ?? 'page has unsaved changes', { key: entry.instance.encodedKey, reason });
+        }
+        if (decision === 'save') {
+            if (!entry.controller.save) {
+                throw new PagePlatformError('PAGE_CLOSE_VETOED', 'page cannot save its dirty state', {
+                    key: entry.instance.encodedKey,
+                    reason,
+                });
+            }
+            await entry.controller.save();
+        }
+        else {
+            if (!entry.controller.discard) {
+                throw new PagePlatformError('PAGE_CLOSE_VETOED', 'page cannot discard its dirty state', {
+                    key: entry.instance.encodedKey,
+                    reason,
+                });
+            }
+            await entry.controller.discard();
+        }
+    };
+    const session = {
+        async open(request) {
+            const resolved = registry.get(request.typeId);
+            if (!resolved) {
+                throw new PagePlatformError('PAGE_TYPE_NOT_FOUND', `page type "${request.typeId}" is not registered`, {
+                    typeId: request.typeId,
+                });
+            }
+            if (resolved.status === 'unavailable') {
+                throw new PagePlatformError('PAGE_TYPE_UNAVAILABLE', `page type "${request.typeId}" is unavailable`, {
+                    typeId: request.typeId,
+                    reason: resolved.reason,
+                    missingPanelTypeIds: resolved.missingPanelTypeIds,
+                });
+            }
+            let key;
+            if (resolved.definition.cardinality === 'singleton') {
+                if (request.resource || request.instanceId) {
+                    throw new PagePlatformError('PAGE_CARDINALITY_MISMATCH', 'singleton page does not accept resource or instance identity');
+                }
+                key = { cardinality: 'singleton', typeId: request.typeId };
+            }
+            else if (resolved.definition.cardinality === 'resource') {
+                if (!request.resource || request.instanceId) {
+                    throw new PagePlatformError('PAGE_CARDINALITY_MISMATCH', 'resource page requires exactly one resource identity');
+                }
+                key = { cardinality: 'resource', typeId: request.typeId, resourceId: request.resource.canonicalId };
+            }
+            else {
+                if (request.resource) {
+                    throw new PagePlatformError('PAGE_CARDINALITY_MISMATCH', 'multi-instance page does not accept a resource identity');
+                }
+                key = {
+                    cardinality: 'multi-instance',
+                    typeId: request.typeId,
+                    instanceId: request.instanceId ?? createInstanceId(),
+                };
+            }
+            const encoded = encodePageKey(key);
+            if (entries.has(encoded)) {
+                if (activeKey !== encoded) {
+                    activeKey = encoded;
+                    publish();
+                }
+                return key;
+            }
+            const context = request.context ?? {};
+            const controller = await resolved.definition.createController?.({
+                key,
+                context,
+                ...(request.resource ? { resource: request.resource } : {}),
+            }) ?? inertController;
+            const instance = {
+                key,
+                encodedKey: encoded,
+                typeId: request.typeId,
+                context,
+                ...(request.resource ? { resource: request.resource } : {}),
+                openedAt: now(),
+                closable: resolved.definition.closable !== false,
+            };
+            entries.set(encoded, { instance, controller });
+            bindTitle(encoded, controller);
+            activeKey = encoded;
+            publish();
+            persistRecent();
+            return key;
+        },
+        async focus(key) {
+            const { encoded } = requireEntry(key);
+            if (activeKey === encoded)
+                return;
+            activeKey = encoded;
+            publish();
+            persistRecent();
+        },
+        getContextMenuItems(key) {
+            const { entry } = requireEntry(key);
+            return entry.controller.getContextMenuItems?.() ?? [];
+        },
+        reorder(key, toIndex) {
+            const { encoded } = requireEntry(key);
+            const order = [...entries.keys()];
+            const from = order.indexOf(encoded);
+            const to = Math.max(0, Math.min(toIndex, order.length - 1));
+            if (from === to)
+                return;
+            order.splice(to, 0, order.splice(from, 1)[0]);
+            // Rebuild the Map in the new order so the derived snapshot (which reads
+            // insertion order) reflects the move without a parallel ordering field.
+            const moved = order.map((k) => [k, entries.get(k)]);
+            entries.clear();
+            for (const [k, entry] of moved)
+                entries.set(k, entry);
+            publish();
+        },
+        async close(key, request = {}) {
+            const { encoded, entry } = requireEntry(key);
+            const reason = request.reason ?? 'user';
+            if (!entry.instance.closable && reason === 'user') {
+                throw new PagePlatformError('PAGE_CLOSE_VETOED', 'page is permanent and cannot be closed', { key: encoded });
+            }
+            await resolvePreparation(entry, reason, request.decision);
+            await entry.controller.dispose();
+            entries.delete(encoded);
+            unbindTitle(encoded);
+            if (activeKey === encoded)
+                activeKey = [...entries.keys()].at(-1);
+            publish();
+            if (activeKey)
+                persistRecent();
+        },
+        getSnapshot() {
+            return snapshot;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        async closeOwnedBy(owner, reason = 'extension-disabled', decision) {
+            const owned = [...entries.values()].filter((entry) => registry.ownerOf(entry.instance.typeId) === owner);
+            for (const entry of owned)
+                await resolvePreparation(entry, reason, decision);
+            for (const entry of owned)
+                await entry.controller.dispose();
+            if (owned.length === 0)
+                return;
+            const ownedKeys = new Set(owned.map((entry) => entry.instance.encodedKey));
+            for (const key of ownedKeys) {
+                entries.delete(key);
+                unbindTitle(key);
+            }
+            if (activeKey && ownedKeys.has(activeKey))
+                activeKey = [...entries.keys()].at(-1);
+            publish();
+        },
+        async dispose() {
+            const all = [...entries.values()];
+            for (const entry of all)
+                await resolvePreparation(entry, 'host-dispose', 'discard');
+            for (const entry of all)
+                await entry.controller.dispose();
+            for (const encoded of [...titleSubs.keys()])
+                unbindTitle(encoded);
+            entries.clear();
+            titles.clear();
+            activeKey = undefined;
+            if (all.length > 0)
+                publish();
+            listeners.clear();
+            registryUnsubscribe();
+            projectUnsubscribe();
+        },
+    };
+    const tryRestoreRecent = async () => {
+        if (restoring || entries.size > 0 || typeof localStorage === 'undefined')
+            return;
+        for (const policy of ['project', 'session']) {
+            const key = recentKey(policy);
+            const raw = localStorage.getItem(key);
+            if (!raw)
+                continue;
+            let request;
+            try {
+                request = JSON.parse(raw);
+            }
+            catch {
+                localStorage.removeItem(key);
+                continue;
+            }
+            const resolved = registry.get(request.typeId);
+            if (!resolved)
+                continue;
+            if (resolved.status !== 'available' || (resolved.definition.restorePolicy ?? 'never') !== policy) {
+                localStorage.removeItem(key);
+                continue;
+            }
+            restoring = true;
+            try {
+                await session.open(request);
+            }
+            catch {
+                localStorage.removeItem(key);
+            }
+            finally {
+                restoring = false;
+            }
+            return;
+        }
+    };
+    registryUnsubscribe = registry.subscribe(() => { void tryRestoreRecent(); });
+    projectUnsubscribe = subscribeCurrentProject(() => { void tryRestoreRecent(); });
+    void tryRestoreRecent();
+    return session;
+}

package/dist/package/node/core/page-platform/types.js

@@ -0,0 +1,10 @@
+export class PagePlatformError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = 'PagePlatformError';
+        this.code = code;
+        this.details = details;
+    }
+}

package/dist/package/node/core/panels/context-expression.js

@@ -0,0 +1 @@
+export { evaluateContextExpression, getContextExpressionKeys } from '@forgeax/extension-platform/platform';

package/dist/package/node/core/panels/drawer.js

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

package/dist/package/node/core/panels/index.js

@@ -0,0 +1,7 @@
+export * from './types.js';
+export * from './strip.js';
+export * from './drawer.js';
+export * from './context-expression.js';
+export * from './panel-action-registry.js';
+export * from './panel-control-registry.js';
+export * from './resolve-panel-action-state.js';

package/dist/package/node/core/panels/panel-action-registry.js

@@ -0,0 +1,62 @@
+export function createPanelActionRegistry() {
+    const entries = [];
+    const listeners = new Set();
+    let cache = null;
+    let version = 0;
+    const emit = () => {
+        cache = null;
+        version++;
+        for (const listener of [...listeners])
+            listener();
+    };
+    // Batch-deferred notification: data mutations (push/splice) happen
+    // immediately so reads (list/all) always return fresh data, but listener
+    // notifications are deferred to a microtask. This avoids triggering
+    // forceStoreRerender (useSyncExternalStore) during React 19's commit
+    // phase, which otherwise causes "Maximum update depth exceeded".
+    let emitScheduled = false;
+    const scheduleEmit = () => {
+        cache = null;
+        if (emitScheduled)
+            return;
+        emitScheduled = true;
+        queueMicrotask(() => {
+            emitScheduled = false;
+            emit();
+        });
+    };
+    const all = () => {
+        if (cache)
+            return cache;
+        cache = entries.flatMap((entry) => entry.actions).sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+        return cache;
+    };
+    return {
+        contribute(owner, actions) {
+            const entry = { owner, actions };
+            entries.push(entry);
+            scheduleEmit();
+            let removed = false;
+            return () => {
+                if (removed)
+                    return;
+                removed = true;
+                const index = entries.indexOf(entry);
+                if (index >= 0)
+                    entries.splice(index, 1);
+                scheduleEmit();
+            };
+        },
+        list(panelId) {
+            return all().filter((action) => action.panelId === panelId);
+        },
+        all,
+        onChange(listener) {
+            listeners.add(listener);
+            return () => { listeners.delete(listener); };
+        },
+        version() {
+            return version;
+        },
+    };
+}

package/dist/package/node/core/panels/panel-control-registry.js

@@ -0,0 +1,54 @@
+export function createPanelControlRegistry() {
+    const entries = [];
+    const listeners = new Set();
+    let version = 0;
+    const emit = () => {
+        version++;
+        for (const listener of [...listeners])
+            listener();
+    };
+    // Batch-deferred notification: data mutations (push/splice) happen
+    // immediately so reads (list/get) always return fresh data, but listener
+    // notifications are deferred to a microtask. This avoids triggering
+    // forceStoreRerender (useSyncExternalStore) during React 19's commit
+    // phase, which otherwise causes "Maximum update depth exceeded".
+    let emitScheduled = false;
+    const scheduleEmit = () => {
+        if (emitScheduled)
+            return;
+        emitScheduled = true;
+        queueMicrotask(() => {
+            emitScheduled = false;
+            emit();
+        });
+    };
+    const list = () => entries.flatMap((entry) => entry.controls);
+    return {
+        contribute(owner, controls) {
+            const entry = { owner, controls };
+            entries.push(entry);
+            scheduleEmit();
+            let removed = false;
+            return () => {
+                if (removed)
+                    return;
+                removed = true;
+                const index = entries.indexOf(entry);
+                if (index >= 0)
+                    entries.splice(index, 1);
+                scheduleEmit();
+            };
+        },
+        get(id) {
+            return list().find((control) => control.id === id);
+        },
+        list,
+        onChange(listener) {
+            listeners.add(listener);
+            return () => { listeners.delete(listener); };
+        },
+        version() {
+            return version;
+        },
+    };
+}

package/dist/package/node/core/panels/resolve-panel-action-state.js

@@ -0,0 +1,9 @@
+import { evaluateContextExpression } from './context-expression.js';
+export function resolvePanelActionState(action, contextKeys) {
+    return {
+        visible: evaluateContextExpression(action.when, contextKeys, true),
+        enabled: evaluateContextExpression(action.enablement, contextKeys, true),
+        active: evaluateContextExpression(action.activeWhen, contextKeys, false),
+        highlighted: evaluateContextExpression(action.highlightWhen, contextKeys, false),
+    };
+}

package/dist/package/node/core/panels/strip.js

@@ -0,0 +1 @@
+export const STRIP_LOCATIONS = ['statusbar.left', 'statusbar.center', 'statusbar.right'];

package/dist/package/node/core/panels/types.js

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