@forgeax/interface 0.4.1

package/dist/package/browser/core/app-shell/types.d.ts

@@ -0,0 +1,176 @@
+import type { ExtensionManifest, Cleanup } from '../extension-foundation';
+import type { EventBus } from '../extension-foundation/bus';
+import type { CommandsRegistry, CommandDescriptor } from '../extension-foundation/commands';
+import type { ContextKeysApi } from '../extension-foundation/context-keys';
+import type { StorageApi } from '../extension-foundation/storage';
+import type { ContextualKeybindingsApi } from '../contextual-keybindings';
+import type { PanelRenderers } from '../../components/DockShell/panelRenderers';
+import type { PanelActionContribution, PanelActionsApi, PanelControlContribution, PanelControlsApi, StatusItemContribution } from '../panels';
+import type { PagePlatformContribution, PagePort, PageRegistry, PageTypeRegistration, PanelTypeRegistration, ActivityRegistration, ResourceEditorRegistration, ActivityRegistry, ResourceEditorResolver } from '../page-platform';
+export type AppShellPillKind = 'file' | 'dir' | 'agent' | 'tool' | 'game' | 'log' | 'entity' | 'paste' | 'skill' | 'command';
+export interface AppShellPillPayload {
+    kind: AppShellPillKind;
+    display: string;
+    icon?: string;
+    detail: string;
+    tooltip: {
+        title: string;
+        lines: string[];
+    };
+}
+/**
+ * A request to LOCATE something in the Content Browser (navigate to its parent
+ * folder + select + scroll into view). Neutral interface-level contract: the
+ * trigger (any app, e.g. an editor page tab) emits `content-browser:reveal`
+ * with this payload and the mounted Content Browser resolves it — neither side
+ * imports the other. The CB owns the actual navigation/selection writes (through
+ * its own gateway door), so this carries only the target identity.
+ */
+export interface ContentBrowserRevealTarget {
+    /** Asset identity (scene / mesh / material / texture …). */
+    readonly guid?: string;
+    /** Game-relative pack path — folder fallback when `guid` isn't in the catalog
+     *  yet, and the SelectedAsset packPath. */
+    readonly packPath?: string;
+    /** Source file / folder path (non-asset targets). */
+    readonly path?: string;
+    /** Whether `path` is a directory or a file (drives the selection kind). */
+    readonly pathKind?: 'dir' | 'file';
+    /** Asset kind, forwarded into the selection (best-effort). */
+    readonly assetKind?: string;
+    /** Display name, forwarded into the selection (best-effort). */
+    readonly name?: string;
+    /** Game-relative author source path (imported `.glb` / `.fbx` …), when known. */
+    readonly sourcePath?: string;
+}
+export interface AppBusEventMap extends Record<string, unknown> {
+    'panel:open': {
+        id: string;
+        source?: string;
+    };
+    'panel:focus': {
+        id: string;
+    };
+    /** Reveal a panel wherever it lives: activate it in the grid, reopen it if
+     *  closed, or expand its edge/footer drawer. Superset of `panel:open`. */
+    'panel:reveal': {
+        id: string;
+    };
+    'panel:close': {
+        id: string;
+    };
+    /** Locate a target in the Content Browser (see ContentBrowserRevealTarget). */
+    'content-browser:reveal': {
+        target: ContentBrowserRevealTarget;
+    };
+    'dock:reset': Record<string, never>;
+    'dock:layout-toggle': {
+        pageId?: string;
+        rect?: {
+            top: number;
+            bottom: number;
+            left: number;
+            right: number;
+        };
+    };
+    'anim:handoff': {
+        fromSurface: string;
+        toSurface: string;
+    };
+    'chat:pill': {
+        pill: AppShellPillPayload;
+    };
+    /** Host-command handoffs; domain owners may subscribe without importing UI. */
+    'files:reveal': {
+        path: string;
+    };
+    'build:create': {
+        version: string;
+    };
+    'build:play': {
+        version: string;
+    };
+    'iframe:navigate': {
+        extensionId: string;
+        url?: string;
+    };
+    'capability:added': {
+        capability: string;
+        provider: string;
+    };
+    'capability:removed': {
+        capability: string;
+        provider: string;
+    };
+}
+export type HostCapability = 'commands' | 'keybindings' | 'bus' | 'storage' | 'panels' | 'panelActions' | 'panelControls' | 'contextKeys' | 'pages' | 'activities' | 'resourceEditors' | 'session' | 'observability' | 'editor' | (string & {});
+export interface AppLogger {
+    debug(message: string, ...rest: unknown[]): void;
+    info(message: string, ...rest: unknown[]): void;
+    warn(message: string, ...rest: unknown[]): void;
+    error(message: string, ...rest: unknown[]): void;
+}
+export interface AppHostBase {
+    readonly commands: CommandsRegistry;
+    readonly keybindings: ContextualKeybindingsApi;
+    readonly bus: EventBus<AppBusEventMap>;
+    readonly storage: StorageApi;
+    readonly contextKeys: ContextKeysApi;
+    readonly panels: PanelRenderers;
+    readonly panelActions: PanelActionsApi;
+    readonly panelControls: PanelControlsApi;
+    readonly pages: PagePort;
+    readonly pageRegistry: PageRegistry;
+    readonly activities: ActivityRegistry;
+    readonly resourceEditors: ResourceEditorResolver;
+    readonly capabilities: ReadonlySet<HostCapability>;
+    extend<K extends HostCapability>(capability: K, api: unknown): void;
+    /** ADR-0030 §2.2 — imperative, RUNTIME status-item registration. The
+     *  single-truth successor to the retired module-level statusBarStore: writes
+     *  through the same panels contribution registry (host.panels.stripItems),
+     *  so it is owner-neutral yet reversible via the returned Cleanup. Use for
+     *  chips whose existence is decided at runtime; boot-time-known chips should
+     *  prefer declarative `contributes.panels.stripItems`. */
+    contributeStatusItem(item: StatusItemContribution): Cleanup;
+}
+/** Consumers narrow optional fields with `if (host.session) {...}`. */
+export interface AppHost extends AppHostBase {
+    readonly session?: unknown;
+    readonly agentCatalog?: unknown;
+    readonly projects?: unknown;
+    readonly builds?: unknown;
+    readonly observability?: unknown;
+    readonly editor?: unknown;
+    readonly [extension: string]: unknown;
+}
+export interface AppExtensionContext {
+    readonly host: AppHost;
+    readonly bus: EventBus<AppBusEventMap>;
+    readonly storage: StorageApi;
+    readonly log: AppLogger;
+    registerCommand(cmd: CommandDescriptor): Cleanup;
+    contributePanels(patch: Partial<PanelRenderers>): Cleanup;
+    contributePanelActions(actions: readonly PanelActionContribution[]): Cleanup;
+    contributePanelControls(controls: readonly PanelControlContribution[]): Cleanup;
+    contributePagePlatform(contribution: PagePlatformContribution): Cleanup;
+}
+/** ADR 0025 M2 — declarative contributions. Applied by the bootstrap glue
+ *  before setup() runs and removed with the extension's cleanup; a pure-UI
+ *  extension is just data (no setup at all). */
+export interface AppExtensionContributes {
+    readonly panels?: Partial<PanelRenderers>;
+    readonly panelActions?: readonly PanelActionContribution[];
+    readonly panelControls?: readonly PanelControlContribution[];
+    readonly pages?: readonly PageTypeRegistration[];
+    readonly panelTypes?: readonly PanelTypeRegistration[];
+    readonly activities?: readonly ActivityRegistration[];
+    readonly resourceEditors?: readonly ResourceEditorRegistration[];
+}
+/** An app-shell extension manifest. Unlike the domain-agnostic
+ *  ExtensionManifest, `setup` is OPTIONAL here — contributes-only extensions
+ *  need no imperative code; the bootstrap wrap supplies the loader-required
+ *  setup shim (see appHostBootstrap.ts). */
+export type AppExtension = Omit<ExtensionManifest<HostCapability, AppExtensionContext>, 'setup'> & {
+    readonly setup?: ExtensionManifest<HostCapability, AppExtensionContext>['setup'];
+    readonly contributes?: AppExtensionContributes;
+};

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

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

package/dist/package/browser/core/contextual-keybindings.d.ts

@@ -0,0 +1,71 @@
+import type { CommandsRegistry } from './extension-foundation/commands';
+import type { Cleanup } from './extension-foundation/types';
+export type KeybindingPlatform = 'mac' | 'windows' | 'linux';
+export type KeybindingPreventDefault = 'whenHandled' | 'always' | 'never';
+export declare const APPLICATION_KEYBINDING_SCOPE = "application";
+export interface KeybindingContext {
+    readonly event: KeyboardEvent;
+    readonly scopes: readonly string[];
+}
+export interface KeybindingContribution {
+    readonly commandId: string;
+    readonly keys: string | readonly string[];
+    /** A registered DOM scope id, or the application fallback scope. */
+    readonly scope: string;
+    readonly priority?: number;
+    readonly when?: (context: KeybindingContext) => boolean;
+    readonly preventDefault?: KeybindingPreventDefault;
+    readonly allowInEditable?: boolean;
+    readonly allowDuringComposition?: boolean;
+}
+export interface RegisteredKeybinding extends KeybindingContribution {
+    readonly registrationOrder: number;
+}
+export interface NormalizedKeyEvent {
+    readonly key: string;
+    readonly editable: boolean;
+    readonly composing: boolean;
+}
+export type KeybindingResolution = {
+    readonly status: 'passthrough';
+    readonly reason: 'editable' | 'composition';
+} | {
+    readonly status: 'unclaimed';
+} | {
+    readonly status: 'claimed-disabled';
+    readonly binding: RegisteredKeybinding;
+} | {
+    readonly status: 'matched';
+    readonly binding: RegisteredKeybinding;
+};
+export type KeybindingHandleResult = Exclude<KeybindingResolution, {
+    readonly status: 'matched';
+}> | {
+    readonly status: 'handled';
+    readonly binding: RegisteredKeybinding;
+};
+export interface ResolveKeybindingInput {
+    readonly event: KeyboardEvent;
+    readonly normalized: NormalizedKeyEvent;
+    readonly scopes: readonly string[];
+    readonly bindings: readonly RegisteredKeybinding[];
+    readonly platform: KeybindingPlatform;
+    readonly isCommandEnabled: (commandId: string) => boolean;
+}
+export interface ContextualKeybindingsApi {
+    register(binding: KeybindingContribution): Cleanup;
+    registerScope(element: Element, scopeId: string): Cleanup;
+    resolve(event: KeyboardEvent): KeybindingResolution;
+    handle(event: KeyboardEvent): KeybindingHandleResult;
+    dispose(): void;
+}
+export declare function detectKeybindingPlatform(): KeybindingPlatform;
+export declare function normalizeKeybinding(keys: string, platform: KeybindingPlatform): string;
+export declare function isEditableEventTarget(target: EventTarget | null): boolean;
+export declare function normalizeKeyboardEvent(event: KeyboardEvent, platform?: KeybindingPlatform): NormalizedKeyEvent;
+export declare function matchesKeybinding(event: NormalizedKeyEvent, keys: string, platform: KeybindingPlatform): boolean;
+export declare function resolveKeybinding(input: ResolveKeybindingInput): KeybindingResolution;
+export declare function createContextualKeybindings(commands: CommandsRegistry, options?: {
+    readonly platform?: KeybindingPlatform;
+    readonly onCommandError?: (error: unknown, commandId: string) => void;
+}): ContextualKeybindingsApi;

package/dist/package/browser/core/contextual-keybindings.js

@@ -0,0 +1,198 @@
+export const APPLICATION_KEYBINDING_SCOPE = 'application';
+function normalizeKey(key) {
+    if (!key)
+        return '';
+    if (key === ' ')
+        return 'Space';
+    if (key.length === 1)
+        return key.toUpperCase();
+    const aliases = {
+        Esc: 'Escape',
+        Del: 'Delete',
+        Left: 'ArrowLeft',
+        Right: 'ArrowRight',
+        Up: 'ArrowUp',
+        Down: 'ArrowDown',
+    };
+    return aliases[key] ?? key;
+}
+/** Some browsers omit `event.key` after autocomplete/history selection (e.g. Space). */
+function readKeyboardEventKey(event) {
+    if (typeof event.key === 'string' && event.key.length > 0) {
+        return event.key;
+    }
+    switch (event.code) {
+        case 'Space': return ' ';
+        case 'Enter': return 'Enter';
+        case 'Escape': return 'Escape';
+        case 'Backspace': return 'Backspace';
+        case 'Delete': return 'Delete';
+        case 'Tab': return 'Tab';
+        case 'ArrowUp': return 'ArrowUp';
+        case 'ArrowDown': return 'ArrowDown';
+        case 'ArrowLeft': return 'ArrowLeft';
+        case 'ArrowRight': return 'ArrowRight';
+        default:
+            if (event.code.startsWith('Key'))
+                return event.code.slice(3);
+            if (event.code.startsWith('Digit'))
+                return event.code.slice(5);
+            return event.code;
+    }
+}
+export function detectKeybindingPlatform() {
+    if (typeof navigator === 'undefined')
+        return 'linux';
+    const platform = navigator.platform.toLowerCase();
+    if (platform.includes('mac'))
+        return 'mac';
+    if (platform.includes('win'))
+        return 'windows';
+    return 'linux';
+}
+export function normalizeKeybinding(keys, platform) {
+    const parts = keys.split('+').map((part) => part.trim()).filter(Boolean);
+    const key = parts.pop();
+    if (!key)
+        return '';
+    const modifiers = new Set();
+    for (const modifier of parts) {
+        const lower = modifier.toLowerCase();
+        if (lower === 'mod')
+            modifiers.add(platform === 'mac' ? 'Meta' : 'Ctrl');
+        else if (lower === 'cmd' || lower === 'command' || lower === 'meta')
+            modifiers.add('Meta');
+        else if (lower === 'ctrl' || lower === 'control')
+            modifiers.add('Ctrl');
+        else if (lower === 'alt' || lower === 'option')
+            modifiers.add('Alt');
+        else if (lower === 'shift')
+            modifiers.add('Shift');
+    }
+    const ordered = ['Ctrl', 'Meta', 'Alt', 'Shift'].filter((modifier) => modifiers.has(modifier));
+    return [...ordered, normalizeKey(key)].join('+');
+}
+export function isEditableEventTarget(target) {
+    if (!(target instanceof Element))
+        return false;
+    if (target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement || target instanceof HTMLSelectElement) {
+        return true;
+    }
+    return target.closest('[contenteditable]:not([contenteditable="false"]),[role="textbox"]') !== null;
+}
+export function normalizeKeyboardEvent(event, platform = detectKeybindingPlatform()) {
+    const modifiers = [
+        event.ctrlKey ? 'Ctrl' : '',
+        event.metaKey ? 'Meta' : '',
+        event.altKey ? 'Alt' : '',
+        event.shiftKey ? 'Shift' : '',
+    ].filter(Boolean);
+    return {
+        key: [...modifiers, normalizeKey(readKeyboardEventKey(event))].join('+'),
+        editable: isEditableEventTarget(event.composedPath()[0] ?? event.target),
+        composing: event.isComposing || event.keyCode === 229,
+    };
+}
+export function matchesKeybinding(event, keys, platform) {
+    return event.key === normalizeKeybinding(keys, platform);
+}
+function bindingMatches(binding, normalized, platform) {
+    const keys = typeof binding.keys === 'string' ? [binding.keys] : binding.keys;
+    return keys.some((key) => matchesKeybinding(normalized, key, platform));
+}
+export function resolveKeybinding(input) {
+    const scopeOrder = [...input.scopes, APPLICATION_KEYBINDING_SCOPE];
+    const context = { event: input.event, scopes: input.scopes };
+    for (const scope of scopeOrder) {
+        const candidates = input.bindings
+            .filter((binding) => binding.scope === scope)
+            .filter((binding) => bindingMatches(binding, input.normalized, input.platform))
+            .filter((binding) => !binding.when || binding.when(context))
+            .filter((binding) => !input.normalized.editable || binding.allowInEditable)
+            .filter((binding) => !input.normalized.composing || binding.allowDuringComposition)
+            .sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0)
+            || b.registrationOrder - a.registrationOrder);
+        const binding = candidates[0];
+        if (!binding)
+            continue;
+        if (!input.isCommandEnabled(binding.commandId)) {
+            return { status: 'claimed-disabled', binding };
+        }
+        return { status: 'matched', binding };
+    }
+    if (input.normalized.composing)
+        return { status: 'passthrough', reason: 'composition' };
+    if (input.normalized.editable)
+        return { status: 'passthrough', reason: 'editable' };
+    return { status: 'unclaimed' };
+}
+export function createContextualKeybindings(commands, options = {}) {
+    const platform = options.platform ?? detectKeybindingPlatform();
+    const bindings = new Set();
+    const scopes = new WeakMap();
+    let registrationOrder = 0;
+    const scopePath = (event) => {
+        const result = [];
+        for (const target of event.composedPath()) {
+            if (!(target instanceof Element))
+                continue;
+            const scopeId = scopes.get(target);
+            if (scopeId && !result.includes(scopeId))
+                result.push(scopeId);
+        }
+        return result;
+    };
+    const resolve = (event) => {
+        const normalized = normalizeKeyboardEvent(event, platform);
+        return resolveKeybinding({
+            event,
+            normalized,
+            scopes: scopePath(event),
+            bindings: Array.from(bindings),
+            platform,
+            isCommandEnabled(commandId) {
+                const command = commands.get(commandId);
+                if (!command)
+                    return false;
+                try {
+                    return !command.when || command.when();
+                }
+                catch {
+                    return false;
+                }
+            },
+        });
+    };
+    return {
+        register(binding) {
+            const registered = { ...binding, registrationOrder: registrationOrder++ };
+            bindings.add(registered);
+            return () => { bindings.delete(registered); };
+        },
+        registerScope(element, scopeId) {
+            scopes.set(element, scopeId);
+            return () => {
+                if (scopes.get(element) === scopeId)
+                    scopes.delete(element);
+            };
+        },
+        resolve,
+        handle(event) {
+            const result = resolve(event);
+            if (result.status !== 'matched' && result.status !== 'claimed-disabled')
+                return result;
+            if (result.binding.preventDefault !== 'never')
+                event.preventDefault();
+            event.stopImmediatePropagation();
+            if (result.status === 'claimed-disabled')
+                return result;
+            void commands.execute(result.binding.commandId).catch((error) => {
+                options.onCommandError?.(error, result.binding.commandId);
+            });
+            return { status: 'handled', binding: result.binding };
+        },
+        dispose() {
+            bindings.clear();
+        },
+    };
+}

package/dist/package/browser/core/extension-foundation/bus.d.ts

@@ -0,0 +1,2 @@
+export { EventBus } from '@forgeax/extension-platform/base';
+export type { EventBusOptions } from '@forgeax/extension-platform/base';

package/dist/package/browser/core/extension-foundation/bus.js

@@ -0,0 +1,3 @@
+// Thin re-export shell — implementation lives in
+// @forgeax/extension-platform (ADR 0026).
+export { EventBus } from '@forgeax/extension-platform/base';

package/dist/package/browser/core/extension-foundation/capabilities.d.ts

@@ -0,0 +1,2 @@
+export { CapabilityRegistry, createCapabilityRegistry, } from '@forgeax/extension-platform/platform';
+export type { CapabilityEventName } from '@forgeax/extension-platform/platform';

package/dist/package/browser/core/extension-foundation/capabilities.js

@@ -0,0 +1,3 @@
+// Thin re-export shell — implementation lives in
+// @forgeax/extension-platform (ADR 0026).
+export { CapabilityRegistry, createCapabilityRegistry, } from '@forgeax/extension-platform/platform';

package/dist/package/browser/core/extension-foundation/commands.d.ts

@@ -0,0 +1,2 @@
+export { createCommandsRegistry } from '@forgeax/extension-platform/platform';
+export type { CommandDescriptor, CommandsRegistry, } from '@forgeax/extension-platform/platform';

package/dist/package/browser/core/extension-foundation/commands.js

@@ -0,0 +1,3 @@
+// Thin re-export shell — implementation lives in
+// @forgeax/extension-platform (ADR 0026).
+export { createCommandsRegistry } from '@forgeax/extension-platform/platform';

package/dist/package/browser/core/extension-foundation/context-keys.d.ts

@@ -0,0 +1,2 @@
+export { createContextKeys } from '@forgeax/extension-platform/platform';
+export type { ContextKeysApi } from '@forgeax/extension-platform/platform';

package/dist/package/browser/core/extension-foundation/context-keys.js

@@ -0,0 +1,3 @@
+// Thin re-export shell — implementation lives in
+// @forgeax/extension-platform (ADR 0026).
+export { createContextKeys } from '@forgeax/extension-platform/platform';

package/dist/package/browser/core/extension-foundation/contribution-registry.d.ts

@@ -0,0 +1,2 @@
+export { createContributionRegistry } from '@forgeax/extension-platform/platform';
+export type { ContributionEntry, ContributionRegistry, } from '@forgeax/extension-platform/platform';

package/dist/package/browser/core/extension-foundation/contribution-registry.js

@@ -0,0 +1,3 @@
+// Thin re-export shell — implementation lives in
+// @forgeax/extension-platform (ADR 0026).
+export { createContributionRegistry } from '@forgeax/extension-platform/platform';

package/dist/package/browser/core/extension-foundation/errors.d.ts

@@ -0,0 +1,2 @@
+export { ExtensionConflictError, ExtensionSetupError, } from '@forgeax/extension-platform/platform';
+export type { ExtensionConflictErrorInfo, ExtensionSetupErrorInfo, } from '@forgeax/extension-platform/platform';

package/dist/package/browser/core/extension-foundation/errors.js

@@ -0,0 +1,3 @@
+// Thin re-export shell — implementation lives in
+// @forgeax/extension-platform (ADR 0026).
+export { ExtensionConflictError, ExtensionSetupError, } from '@forgeax/extension-platform/platform';

package/dist/package/browser/core/extension-foundation/index.d.ts

@@ -0,0 +1,8 @@
+export * from './types';
+export * from './errors';
+export * from './bus';
+export * from './commands';
+export * from './context-keys';
+export * from './storage';
+export * from './capabilities';
+export * from './loader';

package/dist/package/browser/core/extension-foundation/index.js

@@ -0,0 +1,9 @@
+// packages/interface/src/core/extension-foundation/index.ts
+export * from './types';
+export * from './errors';
+export * from './bus';
+export * from './commands';
+export * from './context-keys';
+export * from './storage';
+export * from './capabilities';
+export * from './loader';

package/dist/package/browser/core/extension-foundation/loader.d.ts

@@ -0,0 +1,2 @@
+export { ExtensionLoader, createExtensionLoader, } from '@forgeax/extension-platform/extensions';
+export type { ExtensionLoaderOptions } from '@forgeax/extension-platform/extensions';

package/dist/package/browser/core/extension-foundation/loader.js

@@ -0,0 +1,3 @@
+// Thin re-export shell — implementation lives in
+// @forgeax/extension-platform (ADR 0026).
+export { ExtensionLoader, createExtensionLoader, } from '@forgeax/extension-platform/extensions';

package/dist/package/browser/core/extension-foundation/storage.d.ts

@@ -0,0 +1,2 @@
+export { createStorageApi } from '@forgeax/extension-platform/platform';
+export type { StorageApi } from '@forgeax/extension-platform/platform';

package/dist/package/browser/core/extension-foundation/storage.js

@@ -0,0 +1,3 @@
+// Thin re-export shell — implementation lives in
+// @forgeax/extension-platform (ADR 0026).
+export { createStorageApi } from '@forgeax/extension-platform/platform';

package/dist/package/browser/core/extension-foundation/types.d.ts

@@ -0,0 +1,2 @@
+export type { BusEvent, Cleanup, EventMap, Listener, ListenerErrorHandler, Middleware, SetupReturn, } from '@forgeax/extension-platform/base';
+export type { ExtensionManifest } from '@forgeax/extension-platform/extensions';

package/dist/package/browser/core/extension-foundation/types.js

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

package/dist/package/browser/core/extensions/builtin-commands.d.ts

@@ -0,0 +1,2 @@
+import type { AppExtension } from '../app-shell/types';
+export declare const builtinCommandsExtension: AppExtension;