@nextclaw/ui 0.12.35-beta.2 → 0.12.35-beta.4

package/src/shared/components/doc-browser/stores/doc-browser.store.ts

@@ -0,0 +1,140 @@
+import { create } from 'zustand';
+import { createJSONStorage, persist } from 'zustand/middleware';
+import type {
+  DocBrowserMode,
+  DocBrowserState,
+  DocBrowserStateUpdate,
+  DocBrowserTab,
+} from '@/shared/components/doc-browser/types/doc-browser.types';
+import { createDefaultDocBrowserState } from '@/shared/components/doc-browser/utils/doc-browser-state.utils';
+
+const DOC_BROWSER_STORAGE_KEY = 'nextclaw.doc-browser.state';
+const DOC_BROWSER_STORAGE_VERSION = 1;
+const DOC_BROWSER_MAX_PERSISTED_TABS = 8;
+
+type PersistedDocBrowserState = Partial<DocBrowserState>;
+
+type DocBrowserStore = {
+  snapshot: DocBrowserState;
+  setSnapshot: (next: DocBrowserStateUpdate) => void;
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === 'object';
+}
+
+function isDocBrowserMode(value: unknown): value is DocBrowserMode {
+  return value === 'floating' || value === 'docked';
+}
+
+function normalizePersistedStringList(value: unknown, fallback: string): string[] {
+  if (!Array.isArray(value)) {
+    return [fallback];
+  }
+  const values = value.filter((item): item is string => typeof item === 'string' && item.trim().length > 0);
+  return values.length > 0 ? values : [fallback];
+}
+
+function normalizePersistedNumber(value: unknown, min: number, max: number, fallback: number): number {
+  return typeof value === 'number' && Number.isFinite(value)
+    ? Math.min(max, Math.max(min, value))
+    : fallback;
+}
+
+function normalizePersistedDocBrowserTab(value: unknown): DocBrowserTab | null {
+  if (
+    !isRecord(value)
+    || typeof value.id !== 'string'
+    || typeof value.kind !== 'string'
+    || typeof value.title !== 'string'
+    || typeof value.currentUrl !== 'string'
+    || value.currentUrl.trim().length === 0
+  ) {
+    return null;
+  }
+  const history = normalizePersistedStringList(value.history, value.currentUrl);
+  const historyIndex = normalizePersistedNumber(value.historyIndex, 0, history.length - 1, history.length - 1);
+  const navVersion = normalizePersistedNumber(value.navVersion, 0, Number.MAX_SAFE_INTEGER, 0);
+  const dedupeKey = typeof value.dedupeKey === 'string' && value.dedupeKey.trim().length > 0
+    ? value.dedupeKey
+    : undefined;
+
+  return {
+    id: value.id,
+    kind: value.kind,
+    title: value.title,
+    currentUrl: history[historyIndex] ?? value.currentUrl,
+    dedupeKey,
+    history,
+    historyIndex,
+    navVersion,
+  };
+}
+
+function normalizePersistedDocBrowserState(value: unknown): DocBrowserState | null {
+  if (!isRecord(value)) {
+    return null;
+  }
+  const tabs = Array.isArray(value.tabs)
+    ? value.tabs
+      .map(normalizePersistedDocBrowserTab)
+      .filter((tab): tab is DocBrowserTab => tab !== null)
+      .slice(-DOC_BROWSER_MAX_PERSISTED_TABS)
+    : [];
+  if (tabs.length === 0) {
+    return null;
+  }
+  const persistedActiveTabId = typeof value.activeTabId === 'string' ? value.activeTabId : null;
+  const activeTabId = tabs.some((tab) => tab.id === persistedActiveTabId)
+    ? persistedActiveTabId ?? tabs[0].id
+    : tabs[0].id;
+
+  return {
+    isOpen: value.isOpen === true,
+    mode: isDocBrowserMode(value.mode) ? value.mode : 'docked',
+    tabs,
+    activeTabId,
+  };
+}
+
+function resolveDocBrowserStateUpdate(prev: DocBrowserState, next: DocBrowserStateUpdate): DocBrowserState {
+  if (typeof next === 'function') {
+    return next(prev);
+  }
+  return next;
+}
+
+export const useDocBrowserStore = create<DocBrowserStore>()(
+  persist(
+    (set) => ({
+      snapshot: createDefaultDocBrowserState(),
+      setSnapshot: (next) => set((prev) => ({
+        snapshot: resolveDocBrowserStateUpdate(prev.snapshot, next),
+      })),
+    }),
+    {
+      name: DOC_BROWSER_STORAGE_KEY,
+      version: DOC_BROWSER_STORAGE_VERSION,
+      storage: createJSONStorage(() => window.localStorage),
+      partialize: (state): { snapshot: PersistedDocBrowserState } => ({
+        snapshot: {
+          isOpen: state.snapshot.isOpen,
+          mode: state.snapshot.mode,
+          tabs: state.snapshot.tabs.slice(-DOC_BROWSER_MAX_PERSISTED_TABS),
+          activeTabId: state.snapshot.activeTabId,
+        },
+      }),
+      merge: (persistedState, currentState) => {
+        const persistedSnapshot = isRecord(persistedState) ? persistedState.snapshot : null;
+        const normalizedSnapshot = normalizePersistedDocBrowserState(persistedSnapshot);
+        if (!normalizedSnapshot) {
+          return currentState;
+        }
+        return {
+          ...currentState,
+          snapshot: normalizedSnapshot,
+        };
+      },
+    },
+  ),
+);

package/src/shared/components/doc-browser/types/doc-browser.types.ts

@@ -0,0 +1,47 @@
+export type DocBrowserMode = 'floating' | 'docked';
+export type DocBrowserTabKind = 'docs' | 'content' | (string & {});
+
+export type DocBrowserTab = {
+  id: string;
+  kind: DocBrowserTabKind;
+  title: string;
+  currentUrl: string;
+  dedupeKey?: string;
+  history: string[];
+  historyIndex: number;
+  /** Increments on parent-initiated navigation to trigger iframe remount */
+  navVersion: number;
+};
+
+export type DocBrowserOpenOptions = {
+  activate?: boolean;
+  dedupeKey?: string;
+  newTab?: boolean;
+  title?: string;
+  kind?: DocBrowserTabKind;
+};
+
+export type DocBrowserState = {
+  isOpen: boolean;
+  mode: DocBrowserMode;
+  tabs: DocBrowserTab[];
+  activeTabId: string;
+};
+
+export type DocBrowserStateUpdate = DocBrowserState | ((prev: DocBrowserState) => DocBrowserState);
+
+export type DocBrowserActions = {
+  open: (url?: string, options?: DocBrowserOpenOptions) => void;
+  close: () => void;
+  toggleMode: () => void;
+  navigate: (url: string) => void;
+  syncUrl: (url: string) => void;
+  goBack: () => void;
+  goForward: () => void;
+  closeTab: (tabId: string) => void;
+  setActiveTab: (tabId: string) => void;
+};
+
+export type DocBrowserContextValue = DocBrowserState & DocBrowserActions & {
+  currentTab?: DocBrowserTab;
+};

package/src/shared/components/doc-browser/utils/doc-browser-state.utils.ts

@@ -0,0 +1,47 @@
+import type {
+  DocBrowserState,
+  DocBrowserTab,
+  DocBrowserTabKind,
+} from '@/shared/components/doc-browser/types/doc-browser.types';
+import {
+  getDefaultDocsUrl,
+  inferTabTitle,
+} from './doc-browser-url.utils';
+
+let tabCounter = 0;
+
+function nextTabId(): string {
+  tabCounter += 1;
+  return `doc-tab-${Date.now()}-${tabCounter}`;
+}
+
+export function createDocBrowserTab(
+  url: string,
+  kind: DocBrowserTabKind,
+  title?: string,
+  dedupeKey?: string,
+): DocBrowserTab {
+  const tabTitle = title?.trim() || inferTabTitle(url, kind, kind === 'docs' ? 'Docs' : 'Detail');
+
+  return {
+    id: nextTabId(),
+    kind,
+    title: tabTitle,
+    currentUrl: url,
+    dedupeKey,
+    history: [url],
+    historyIndex: 0,
+    navVersion: 0,
+  };
+}
+
+export function createDefaultDocBrowserState(): DocBrowserState {
+  const initialUrl = getDefaultDocsUrl();
+  const initialTab = createDocBrowserTab(initialUrl, 'docs', 'Docs');
+  return {
+    isOpen: false,
+    mode: 'docked',
+    tabs: [initialTab],
+    activeTabId: initialTab.id,
+  };
+}

package/src/shared/components/doc-browser/utils/doc-browser-url.utils.ts

@@ -0,0 +1,95 @@
+import { getLanguage, type I18nLanguage } from '@/shared/lib/i18n';
+import type { DocBrowserTabKind } from '@/shared/components/doc-browser/types/doc-browser.types';
+
+const DOCS_PRIMARY_DOMAIN = 'docs.nextclaw.io';
+const DOCS_PAGES_DEV = 'nextclaw-docs.pages.dev';
+const DOCS_HOSTS = new Set([
+  DOCS_PRIMARY_DOMAIN,
+  `www.${DOCS_PRIMARY_DOMAIN}`,
+  DOCS_PAGES_DEV,
+  `www.${DOCS_PAGES_DEV}`,
+]);
+
+export const DOCS_DEFAULT_BASE_URL = `https://${DOCS_PRIMARY_DOMAIN}`;
+const DOCS_DEFAULT_GUIDE_PATH = '/guide/getting-started';
+
+function toDocsLocale(language: I18nLanguage): 'en' | 'zh' {
+  return language === 'zh' ? 'zh' : 'en';
+}
+
+function ensureLocalizedDocsPath(pathname: string, locale: 'en' | 'zh'): string {
+  const normalized = pathname.startsWith('/') ? pathname : `/${pathname}`;
+
+  if (normalized === '/' || normalized === '') {
+    return `/${locale}/`;
+  }
+
+  if (/^\/(en|zh)(\/|$)/.test(normalized)) {
+    return normalized;
+  }
+
+  return `/${locale}${normalized}`;
+}
+
+function resolveLocalizedDocsUrl(url: string): string {
+  const locale = toDocsLocale(getLanguage());
+
+  try {
+    const parsed = new URL(url, DOCS_DEFAULT_BASE_URL);
+    if (!DOCS_HOSTS.has(parsed.hostname)) {
+      return parsed.toString();
+    }
+
+    parsed.pathname = ensureLocalizedDocsPath(parsed.pathname, locale);
+    return parsed.toString();
+  } catch {
+    return new URL(`/${locale}${DOCS_DEFAULT_GUIDE_PATH}`, DOCS_DEFAULT_BASE_URL).toString();
+  }
+}
+
+export function getDefaultDocsUrl(): string {
+  return resolveLocalizedDocsUrl(DOCS_DEFAULT_GUIDE_PATH);
+}
+
+export function normalizeDocUrl(url: string): string {
+  try {
+    return new URL(url).pathname.replace(/\.html$/, '').replace(/\/$/, '');
+  } catch {
+    return url;
+  }
+}
+
+export function inferTabTitle(url: string, kind: DocBrowserTabKind, fallback = 'Docs'): string {
+  try {
+    const parsed = new URL(url, DOCS_DEFAULT_BASE_URL);
+    if (parsed.protocol === 'data:') {
+      return kind === 'docs' ? fallback : 'Detail';
+    }
+
+    const segments = parsed.pathname.split('/').filter(Boolean);
+    const leaf = segments[segments.length - 1] ?? fallback;
+    return decodeURIComponent(leaf).replace(/[-_]/g, ' ').slice(0, 40) || fallback;
+  } catch {
+    return fallback;
+  }
+}
+
+export function isDocsUrl(url: string): boolean {
+  try {
+    const parsed = new URL(url, window.location.origin);
+    return DOCS_HOSTS.has(parsed.hostname);
+  } catch {
+    return false;
+  }
+}
+
+export function inferTabKind(url: string): DocBrowserTabKind {
+  return isDocsUrl(url) ? 'docs' : 'content';
+}
+
+export function normalizeUrlByKind(url: string, kind: DocBrowserTabKind): string {
+  if (kind === 'docs') {
+    return resolveLocalizedDocsUrl(url);
+  }
+  return url;
+}

package/src/shared/lib/api/managers/client.manager.ts

@@ -11,11 +11,12 @@ import { appClient } from '@/shared/lib/transport';
 import type { ApiResponse } from '@/shared/lib/api/types';
 
 const nextclawUiTransport: NextClawTransport = {
-  request: async <T>({ body, method, path, query, signal, timeoutMs }: NextClawTransportRequestInput): Promise<T> => {
+  request: async <T>({ body, headers, method, path, query, signal, timeoutMs }: NextClawTransportRequestInput): Promise<T> => {
     return await appClient.request({
       method,
       path: appendQueryToPath(path, serializeQuery(query)),
       ...(body !== undefined ? { body } : {}),
+      ...(headers ? { headers } : {}),
       ...(signal ? { signal } : {}),
       ...(timeoutMs !== undefined ? { timeoutMs } : {})
     });

package/src/shared/lib/i18n/runtime/doc-browser-labels.utils.ts

@@ -10,6 +10,7 @@ export const DOC_BROWSER_LABELS = {
   docBrowserNewTab: { zh: '新建标签', en: 'New Tab' },
   docBrowserCloseTab: { zh: '关闭标签', en: 'Close Tab' },
   docBrowserTabUntitled: { zh: '未命名', en: 'Untitled' },
+  appsTitle: { zh: '应用', en: 'Apps' },
   panelAppsTitle: { zh: '面板应用', en: 'Panel Apps' },
   panelAppsLoading: { zh: '加载面板应用中...', en: 'Loading panel apps...' },
   panelAppsLoadFailed: { zh: '面板应用加载失败', en: 'Failed to load panel apps' },
@@ -26,4 +27,34 @@ export const DOC_BROWSER_LABELS = {
   panelAppsUnfavorite: { zh: '取消收藏面板应用', en: 'Unfavorite panel app' },
   panelAppsLastOpened: { zh: '上次打开', en: 'Last opened' },
   panelAppsUpdated: { zh: '更新于', en: 'Updated' },
+  serviceAppsTitle: { zh: '服务应用', en: 'Service Apps' },
+  serviceAppsLoading: { zh: '加载服务应用中...', en: 'Loading service apps...' },
+  serviceAppsLoadFailed: { zh: '服务应用加载失败', en: 'Failed to load service apps' },
+  serviceAppsEmpty: { zh: '暂无服务应用', en: 'No service apps yet' },
+  serviceAppsRefresh: { zh: '刷新服务应用', en: 'Refresh service apps' },
+  serviceAppsDiscoverActions: { zh: '发现运行时动作', en: 'Discover runtime actions' },
+  serviceAppsRestart: { zh: '重启服务应用', en: 'Restart service app' },
+  serviceAppsGrantedTo: { zh: '已授权给', en: 'Granted to' },
+  serviceAppsRevokeGrant: { zh: '撤销授权', en: 'Revoke grant' },
+  serviceAppsRuntimeState_matched: { zh: '已匹配', en: 'Matched' },
+  serviceAppsRuntimeState_missing: { zh: '运行时缺失', en: 'Missing' },
+  serviceAppsRuntimeState_undeclared: { zh: '未声明', en: 'Undeclared' },
+  serviceAppsCommand: { zh: '命令', en: 'Command' },
+  serviceAppsCwd: { zh: '工作目录', en: 'Working directory' },
+  serviceAppsManifest: { zh: 'Manifest', en: 'Manifest' },
+  serviceAppsLastStarted: { zh: '上次启动', en: 'Last started' },
+  serviceAppsLastReady: { zh: '上次就绪', en: 'Last ready' },
+  serviceAppsLastFailed: { zh: '上次失败', en: 'Last failed' },
+  serviceActionAuthorizationTitle: { zh: '授权服务动作', en: 'Authorize service action' },
+  serviceActionAuthorizationDescription: {
+    zh: '此面板应用正在请求调用本地服务应用动作。允许后，同一动作会为该面板应用记住授权。',
+    en: 'This panel app is requesting a local service action. If allowed, this action will stay granted for this panel app.',
+  },
+  serviceActionAuthorizationSource: { zh: '来源', en: 'Source' },
+  serviceActionAuthorizationAction: { zh: '动作', en: 'Action' },
+  serviceActionAuthorizationPurpose: { zh: '用途', en: 'Purpose' },
+  serviceActionAuthorizationRisk: { zh: '风险', en: 'Risk' },
+  serviceActionAuthorizationInput: { zh: '输入', en: 'Input' },
+  serviceActionAuthorizationReject: { zh: '拒绝', en: 'Reject' },
+  serviceActionAuthorizationAllow: { zh: '允许', en: 'Allow' },
 } as const;

package/src/shared/lib/transport/local-transport.service.ts

@@ -6,9 +6,25 @@ import { resolveTransportWebSocketUrl } from './transport-websocket-url.utils';
 
 type EventHandler = (event: AppEvent) => void;
 
-function createTransportError(response: { ok: boolean; error?: { message?: string } }, fallback: string): Error {
+function createTransportError(
+  response: {
+    ok: boolean;
+    error?: {
+      code?: string;
+      message?: string;
+      details?: Record<string, unknown>;
+    };
+  },
+  fallback: string
+): Error {
   if (!response.ok) {
-    return new Error(response.error?.message || fallback);
+    const error = new Error(response.error?.message || fallback) as Error & {
+      code?: string;
+      details?: Record<string, unknown>;
+    };
+    error.code = response.error?.code;
+    error.details = response.error?.details;
+    return error;
   }
   return new Error(fallback);
 }

package/src/shared/lib/transport/remote-transport.service.ts

@@ -1,4 +1,4 @@
-import type { ApiError } from '@nextclaw/server';
+import type { ApiError } from '@nextclaw/client-sdk';
 import type { AppEvent, AppTransport, RemoteRuntimeInfo, RequestInput, StreamInput, StreamSession } from './transport.types';
 import { resolveTransportWebSocketUrl } from './transport-websocket-url.utils';
 
@@ -6,6 +6,7 @@ type RemoteTarget = {
   method: string;
   path: string;
   body?: unknown;
+  headers?: Record<string, string>;
 };
 
 type RemoteBrowserFrame =
@@ -40,7 +41,15 @@ function normalizeApiError(body: unknown, status: number, fallback: string): Err
   if (typeof body === 'object' && body && 'ok' in body) {
     const typed = body as { ok?: boolean; error?: ApiError; data?: unknown };
     if (typed.ok === false && typed.error?.message) {
-      return new Error(typed.error.message);
+      const error = new Error(typed.error.message) as Error & {
+        code?: string;
+        details?: Record<string, unknown>;
+        status?: number;
+      };
+      error.code = typed.error.code;
+      error.details = typed.error.details;
+      error.status = status;
+      return error;
     }
     if (typed.ok === true) {
       return new Error(fallback);
@@ -56,7 +65,13 @@ function unwrapApiBody<T>(body: unknown): T {
   if (typeof body === 'object' && body && 'ok' in body) {
     const typed = body as { ok?: boolean; error?: ApiError; data?: T };
     if (typed.ok === false) {
-      throw new Error(typed.error?.message ?? 'Remote request failed.');
+      const error = new Error(typed.error?.message ?? 'Remote request failed.') as Error & {
+        code?: string;
+        details?: Record<string, unknown>;
+      };
+      error.code = typed.error?.code;
+      error.details = typed.error?.details;
+      throw error;
     }
     if (typed.ok === true) {
       return typed.data as T;
@@ -108,6 +123,7 @@ export class RemoteSessionMultiplexTransport implements AppTransport {
         target: {
           method: input.method,
           path: input.path,
+          ...(input.headers ? { headers: input.headers } : {}),
           ...(input.body !== undefined ? { body: input.body } : {})
         }
       });

package/src/shared/lib/transport/request-raw-api-response.utils.ts

@@ -1,4 +1,4 @@
-import type { ApiResponse } from '@nextclaw/server';
+import type { ApiResponse } from '@nextclaw/client-sdk';
 import { systemStatusManager } from '@/features/system-status';
 
 function compactSnippet(text: string) {