@forgeax/interface 0.4.1

package/dist/package/browser/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/browser/core/panels/panel-control-registry.d.ts

@@ -0,0 +1,6 @@
+import type { Cleanup } from '../extension-foundation/types';
+import type { PanelControlContribution, PanelControlsApi } from './types';
+export interface PanelControlRegistry extends PanelControlsApi {
+    contribute(owner: string, controls: readonly PanelControlContribution[]): Cleanup;
+}
+export declare function createPanelControlRegistry(): PanelControlRegistry;

package/dist/package/browser/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/browser/core/panels/resolve-panel-action-state.d.ts

@@ -0,0 +1,10 @@
+import type { ContextKeysApi } from '../extension-foundation/context-keys';
+import type { ResolvedPanelActionState } from './types';
+interface ActionStateSource {
+    readonly when?: string;
+    readonly enablement?: string;
+    readonly activeWhen?: string;
+    readonly highlightWhen?: string;
+}
+export declare function resolvePanelActionState(action: ActionStateSource, contextKeys: ContextKeysApi): ResolvedPanelActionState;
+export {};

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

@@ -0,0 +1,9 @@
+import { evaluateContextExpression } from './context-expression';
+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/browser/core/panels/strip.d.ts

@@ -0,0 +1,40 @@
+import type { ReactNode } from 'react';
+/** Strip locations exposed by the footer StripHostView. `center` is the flex
+ *  spacer between the left/right chip groups (content is flex-end aligned so a
+ *  lone chip pins to the far right — matches the legacy status bar layout). */
+export type StripLocationId = 'statusbar.left' | 'statusbar.center' | 'statusbar.right';
+export declare const STRIP_LOCATIONS: readonly ["statusbar.left", "statusbar.center", "statusbar.right"];
+export type StatusItemBody = 
+/** Static / derived text. */
+{
+    readonly type: 'text';
+    readonly text: string;
+    readonly tooltip?: string;
+}
+/** Icon/label button; clicking runs `command` through host.commands. */
+ | {
+    readonly type: 'button';
+    readonly label?: string;
+    /** lucide icon name (resolved by StripHostView), optional. */
+    readonly icon?: string;
+    readonly tooltip?: string;
+    readonly command: string;
+    readonly args?: unknown;
+}
+/** In-process live chip. The render owns its own subscriptions/polling. */
+ | {
+    readonly type: 'custom';
+    readonly render: () => ReactNode;
+};
+export interface StatusItemContribution {
+    readonly kind?: 'status-item';
+    /** Stable id; collisions overwrite (later contribution wins per key). */
+    readonly id: string;
+    readonly location: StripLocationId;
+    /** Higher = more permanent (anchored); lower = rotates in the carousel when
+     *  the slot overflows. Default 0. */
+    readonly priority?: number;
+    /** Conditional visibility. Missing = always visible. */
+    readonly when?: () => boolean;
+    readonly item: StatusItemBody;
+}

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

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

package/dist/package/browser/core/panels/types.d.ts

@@ -0,0 +1,143 @@
+import type { Cleanup } from '../extension-foundation/types';
+import type { ReactNode } from 'react';
+export type PanelActionLocation = 'header/left' | 'header/center' | 'header/right' | 'context';
+export type PanelActionContribution = PanelCommandActionContribution | PanelMenuActionContribution | PanelControlActionContribution;
+export interface PanelCommandActionContribution {
+    readonly kind?: 'command';
+    readonly id: string;
+    readonly panelId: string;
+    readonly command: string;
+    readonly title: string;
+    readonly label?: string;
+    readonly icon?: string;
+    readonly testId?: string;
+    readonly order?: number;
+    readonly location?: PanelActionLocation;
+    readonly group?: string;
+    /** Lower value folds into the overflow flyout first. Defaults to `order`. */
+    readonly overflowPriority?: number;
+    /** When true, never folds into the overflow flyout. */
+    readonly pinned?: boolean;
+    /** When true, folding drops the action instead of moving it into the flyout. */
+    readonly hideOnOverflow?: boolean;
+    readonly when?: string;
+    readonly enablement?: string;
+    readonly activeWhen?: string;
+    readonly highlightWhen?: string;
+    readonly args?: unknown;
+}
+export interface PanelMenuActionContribution {
+    readonly kind: 'menu';
+    readonly id: string;
+    readonly panelId: string;
+    readonly title: string;
+    readonly label?: string;
+    readonly labelContextKey?: string;
+    readonly icon?: string;
+    readonly testId?: string;
+    readonly order?: number;
+    readonly location?: Exclude<PanelActionLocation, 'context'>;
+    readonly group?: string;
+    readonly when?: string;
+    readonly enablement?: string;
+    readonly activeWhen?: string;
+    readonly highlightWhen?: string;
+    readonly items: readonly PanelMenuItemContribution[];
+    readonly itemsContextKey?: string;
+    /** Lower value folds into the overflow flyout first. Defaults to `order`. */
+    readonly overflowPriority?: number;
+    /** When true, never folds into the overflow flyout. */
+    readonly pinned?: boolean;
+    /** When true, folding drops the action instead of moving it into the flyout. */
+    readonly hideOnOverflow?: boolean;
+}
+export interface PanelControlActionContribution {
+    readonly kind: 'control';
+    readonly id: string;
+    readonly panelId: string;
+    readonly control: string;
+    readonly order?: number;
+    readonly location?: Exclude<PanelActionLocation, 'context'>;
+    readonly group?: string;
+    readonly when?: string;
+    readonly enablement?: string;
+    /** Lower value folds into the overflow flyout first. Defaults to `order`. */
+    readonly overflowPriority?: number;
+    /** When true, never folds into the overflow flyout. */
+    readonly pinned?: boolean;
+    /** When true, folding drops the action instead of moving it into the flyout. */
+    readonly hideOnOverflow?: boolean;
+}
+export type PanelMenuItemContribution = PanelCommandMenuItemContribution | PanelSeparatorMenuItemContribution;
+export interface PanelCommandMenuItemContribution {
+    readonly kind?: 'command';
+    readonly id: string;
+    readonly command: string;
+    readonly title: string;
+    readonly icon?: string;
+    readonly checkable?: boolean;
+    readonly tone?: 'default' | 'reset';
+    readonly order?: number;
+    readonly when?: string;
+    readonly enablement?: string;
+    readonly activeWhen?: string;
+    readonly highlightWhen?: string;
+    readonly args?: unknown;
+}
+export interface PanelSeparatorMenuItemContribution {
+    readonly kind: 'separator';
+    readonly id: string;
+    readonly order?: number;
+    readonly when?: string;
+}
+export interface PanelActionInvokeContext {
+    readonly panelId: string;
+    readonly actionId: string;
+    readonly source: 'panel-header' | 'panel-context-menu';
+    readonly args?: unknown;
+}
+export interface ResolvedPanelActionState {
+    readonly visible: boolean;
+    readonly enabled: boolean;
+    readonly active: boolean;
+    readonly highlighted: boolean;
+}
+export interface PanelActionsApi {
+    contribute(owner: string, actions: readonly PanelActionContribution[]): Cleanup;
+    list(panelId: string): readonly PanelActionContribution[];
+    all(): readonly PanelActionContribution[];
+    onChange(listener: () => void): Cleanup;
+    version(): number;
+}
+export interface PanelControlRenderContext {
+    readonly panelId: string;
+    readonly actionId: string;
+}
+export interface PanelControlContribution {
+    readonly id: string;
+    readonly render: (ctx: PanelControlRenderContext) => ReactNode;
+}
+export interface PanelControlsApi {
+    contribute(owner: string, controls: readonly PanelControlContribution[]): Cleanup;
+    get(id: string): PanelControlContribution | undefined;
+    list(): readonly PanelControlContribution[];
+    onChange(listener: () => void): Cleanup;
+    version(): number;
+}
+export interface PanelHeaderDefinition {
+    readonly visible?: boolean;
+    readonly showTitle?: boolean;
+    readonly subtitle?: string;
+    readonly badges?: readonly PanelBadgeDefinition[];
+}
+export interface PanelContentDefinition {
+    readonly padding?: 'none' | 'sm' | 'md';
+    readonly scroll?: 'none' | 'auto';
+    readonly tone?: 'default' | 'surface' | 'tool';
+}
+export interface PanelBadgeDefinition {
+    readonly id: string;
+    readonly label: string;
+    readonly tone?: 'neutral' | 'info' | 'warning' | 'danger' | 'success';
+    readonly when?: string;
+}

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

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

package/dist/package/browser/i18n/index.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Lightweight i18n core for the Studio interface.
+ *
+ * Design principles:
+ *   - English is the SOURCE OF TRUTH. `locales/en.json` holds the English UI
+ *     copy; reading it ≈ reading the English UI. Keys are English semantic
+ *     identifiers. AI / developers read English everywhere; other languages are
+ *     a user-facing overlay only.
+ *   - Zero external deps. The public API is deliberately shaped like
+ *     `react-i18next` (`useTranslation() → { t }`, `t(key, vars)`,
+ *     `changeLanguage`, `{{var}}` interpolation) so it feels familiar and could
+ *     be swapped for the real library later with near-zero churn.
+ *   - Module-level store + `useSyncExternalStore`, matching this repo's
+ *     hand-rolled store style (see StatusBar/store.ts, SettingsPanel/store.ts).
+ *
+ * Lookup order for any key: current locale → English → the key string itself.
+ */
+export type Locale = 'en' | 'zh';
+export interface LocaleMeta {
+    /** BCP-47-ish code used as the locale id + persisted value + <html lang>. */
+    code: Locale;
+    /** English label (for code/AI-facing contexts). */
+    label: string;
+    /** Endonym shown to the user in the language picker. */
+    nativeLabel: string;
+}
+/** Adding a language = append here + drop a sibling JSON in ./locales. */
+export declare const SUPPORTED_LOCALES: readonly LocaleMeta[];
+export declare const DEFAULT_LOCALE: Locale;
+export declare function initI18n(): void;
+export declare function getLocale(): Locale;
+/** Subscribe to host locale changes (same-tab; storage events don't fire locally). */
+export declare function subscribeLocale(listener: (locale: Locale) => void): () => void;
+export declare function setLocale(next: Locale, opts?: {
+    persist?: boolean;
+}): void;
+/** react-i18next-compatible alias. */
+export declare function changeLanguage(next: Locale): void;
+export declare function subscribe(fn: () => void): () => void;
+export type TFunction = (key: string, vars?: Record<string, string | number>) => string;
+/** Locale-agnostic translate. Falls back current → en → key. */
+export declare function t(key: string, vars?: Record<string, string | number>): string;
+/** react-i18next-compatible hook. Re-renders the caller on language change. */
+export declare function useTranslation(): {
+    t: TFunction;
+    i18n: {
+        language: Locale;
+        changeLanguage: (l: Locale) => void;
+    };
+};

package/dist/package/browser/i18n/index.js

@@ -0,0 +1,207 @@
+/**
+ * Lightweight i18n core for the Studio interface.
+ *
+ * Design principles:
+ *   - English is the SOURCE OF TRUTH. `locales/en.json` holds the English UI
+ *     copy; reading it ≈ reading the English UI. Keys are English semantic
+ *     identifiers. AI / developers read English everywhere; other languages are
+ *     a user-facing overlay only.
+ *   - Zero external deps. The public API is deliberately shaped like
+ *     `react-i18next` (`useTranslation() → { t }`, `t(key, vars)`,
+ *     `changeLanguage`, `{{var}}` interpolation) so it feels familiar and could
+ *     be swapped for the real library later with near-zero churn.
+ *   - Module-level store + `useSyncExternalStore`, matching this repo's
+ *     hand-rolled store style (see StatusBar/store.ts, SettingsPanel/store.ts).
+ *
+ * Lookup order for any key: current locale → English → the key string itself.
+ */
+import { useSyncExternalStore } from 'react';
+import { installCustomEventObservation, installStorageObservation, } from '@forgeax/app-shell/react';
+import en from './locales/en.json';
+import zh from './locales/zh.json';
+import { STORAGE_KEYS } from '../lib/storageKeys';
+import { flushBrowserPrefs } from '../lib/browser-prefs-sync';
+/** Same-FRAME broadcast event. Injected editor panels (@forgeax/editor-panels)
+ *  render in THIS frame but read their copy from @forgeax/editor-core/i18n — a
+ *  SEPARATE store instance. It listens for this window event to re-read the
+ *  locale, so a switch here live-updates the editor panels too. Must match
+ *  editor-core's LOCALE_CHANGED_EVENT. (`storage` never fires in the document
+ *  that wrote it, and the extension postMessage only reaches iframes, so this
+ *  window event is the only same-frame channel.) */
+const LOCALE_CHANGED_EVENT = 'forgeax:locale-changed';
+/** Adding a language = append here + drop a sibling JSON in ./locales. */
+export const SUPPORTED_LOCALES = [
+    { code: 'en', label: 'English', nativeLabel: 'English' },
+    { code: 'zh', label: 'Chinese', nativeLabel: '简体中文' },
+];
+export const DEFAULT_LOCALE = 'en';
+const CATALOGS = { en: en, zh: zh };
+// ── store ──────────────────────────────────────────────────────────────────
+let current = DEFAULT_LOCALE;
+const listeners = new Set();
+function broadcastLocaleToExtensions(locale) {
+    if (typeof window === 'undefined')
+        return;
+    const msg = { type: 'forgeax:locale-changed', locale };
+    for (const iframe of document.querySelectorAll('iframe')) {
+        try {
+            iframe.contentWindow?.postMessage(msg, '*');
+        }
+        catch {
+            /* cross-origin or detached */
+        }
+    }
+}
+function emit() {
+    broadcastLocaleToExtensions(current);
+    for (const fn of listeners)
+        fn();
+}
+function isLocale(v) {
+    return typeof v === 'string' && SUPPORTED_LOCALES.some((l) => l.code === v);
+}
+/** Read the persisted locale (no side effects). Falls back to the configured
+ *  product default on first run (no stored value). English is the source UI;
+ *  an explicit user selection is persisted and continues to win. */
+function readPersisted() {
+    if (typeof window === 'undefined')
+        return DEFAULT_LOCALE;
+    try {
+        const raw = window.localStorage.getItem(STORAGE_KEYS.locale);
+        if (isLocale(raw))
+            return raw;
+    }
+    catch {
+        /* private mode */
+    }
+    return DEFAULT_LOCALE;
+}
+/**
+ * Initialize locale from persisted prefs. Call once, early, in main.tsx.
+ * Safe to call again (idempotent) — restored prefs sync may re-trigger it.
+ */
+let storageWired = false;
+export function initI18n() {
+    setLocale(readPersisted(), { persist: false });
+    // Cross-document/tab sync: the `storage` event fires in OTHER same-origin
+    // documents when localStorage changes. The editor runs same-origin (proxied
+    // at /editor/), so switching language in the host live-updates the editor
+    // shell (and vice-versa), plus multi-tab stays in sync. Apply with
+    // persist:false to avoid a write-loop.
+    if (!storageWired && typeof window !== 'undefined') {
+        storageWired = true;
+        const onLocaleStorage = (e) => {
+            if (!e.key || e.key === STORAGE_KEYS.locale)
+                setLocale(readPersisted(), { persist: false });
+        };
+        void installStorageObservation({ target: window, onStorage: onLocaleStorage });
+        // Symmetric same-frame sync: if the editor-core store initiates a switch it
+        // dispatches this window event; pick it up so the shell follows. persist:false
+        // + readPersisted() makes our own re-broadcast a no-op (no change → no
+        // re-emit), so there is no feedback loop.
+        const onLocaleChanged = (event) => {
+            const detail = event.detail;
+            setLocale(isLocale(detail) ? detail : readPersisted(), { persist: false });
+        };
+        void installCustomEventObservation({
+            target: window,
+            eventType: LOCALE_CHANGED_EVENT,
+            onEvent: onLocaleChanged,
+        });
+    }
+}
+export function getLocale() {
+    return current;
+}
+/** Subscribe to host locale changes (same-tab; storage events don't fire locally). */
+export function subscribeLocale(listener) {
+    const wrapped = () => listener(current);
+    listeners.add(wrapped);
+    return () => listeners.delete(wrapped);
+}
+export function setLocale(next, opts = {}) {
+    const persist = opts.persist ?? true;
+    if (!isLocale(next))
+        return;
+    const changed = next !== current;
+    current = next;
+    if (typeof document !== 'undefined') {
+        document.documentElement.lang = next;
+    }
+    if (persist && typeof window !== 'undefined') {
+        try {
+            window.localStorage.setItem(STORAGE_KEYS.locale, next);
+            // Same-tab localStorage writes don't fire the `storage` event the prefs
+            // sync listens to, so push immediately — otherwise a quick reload would
+            // restore a stale server snapshot and revert the language.
+            if (changed)
+                void flushBrowserPrefs();
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    if (changed) {
+        emit();
+        // Notify the same-frame editor-core i18n store (see LOCALE_CHANGED_EVENT).
+        // Runs AFTER the localStorage write so the listener's readPersisted() sees
+        // the new value.
+        if (typeof window !== 'undefined') {
+            try {
+                window.dispatchEvent(new CustomEvent(LOCALE_CHANGED_EVENT, { detail: next }));
+            }
+            catch { /* ignore */ }
+        }
+    }
+}
+/** react-i18next-compatible alias. */
+export function changeLanguage(next) {
+    setLocale(next);
+}
+export function subscribe(fn) {
+    listeners.add(fn);
+    return () => {
+        listeners.delete(fn);
+    };
+}
+// ── lookup ───────────────────────────────────────────────────────────────────
+function resolve(catalog, key) {
+    // Support both flat keys ("settings.title" as a literal property) and nested
+    // objects ({ settings: { title } }). Try flat first, then walk the path.
+    const flat = catalog[key];
+    if (typeof flat === 'string')
+        return flat;
+    let node = catalog;
+    for (const part of key.split('.')) {
+        if (node && typeof node === 'object' && part in node) {
+            node = node[part];
+        }
+        else {
+            return undefined;
+        }
+    }
+    return typeof node === 'string' ? node : undefined;
+}
+function interpolate(tpl, vars) {
+    if (!vars)
+        return tpl;
+    // Supports {{name}} (i18next style) and {name} (terse).
+    return tpl.replace(/\{\{?\s*(\w+)\s*\}?\}/g, (m, name) => name in vars ? String(vars[name]) : m);
+}
+/** Locale-agnostic translate. Falls back current → en → key. */
+export function t(key, vars) {
+    const hit = resolve(CATALOGS[current], key) ??
+        (current !== 'en' ? resolve(CATALOGS.en, key) : undefined) ??
+        key;
+    return interpolate(hit, vars);
+}
+// ── React binding ────────────────────────────────────────────────────────────
+const getSnapshot = () => current;
+/** react-i18next-compatible hook. Re-renders the caller on language change. */
+export function useTranslation() {
+    const language = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+    // Return the module-level `t` (stable identity). It already reads `current`
+    // at call time, so a new closure per render is unnecessary and breaks any
+    // useEffect/useMemo that lists `t` as a dependency (infinite re-render loops).
+    return { t, i18n: { language, changeLanguage } };
+}