@vertesia/ui 1.5.0-dev.20260826.064249Z → 1.5.0-dev.20260901.033115Z

package/src/i18n/locales/zh.json

@@ -1018,20 +1018,55 @@
     "intakePolicy.field.updateProperties": "更新属性",
     "intakePolicy.field.useVision": "使用视觉",
     "intakePolicy.field.windowPages": "每个窗口的页数",
+    "intakePolicy.help.contactSheetDetail": "每张缩略图页数。页数越少，图块越大越易读。",
+    "intakePolicy.help.coverageThreshold": "当某页的引用覆盖率低于此值时进行审核，这表明可能有内容被遗漏。",
     "intakePolicy.help.defaultView": "此类型对象首选的初始视图。",
+    "intakePolicy.help.distinguishFrom": "容易与此类型混淆的其他类型。",
     "intakePolicy.help.embeddings": "可选的按类型文本、图像和属性嵌入开关。",
     "intakePolicy.help.examples": "此内容类型中经人工确认的示例对象 ID。",
+    "intakePolicy.help.extractionInteraction": "用你自己的交互替代内置提取器。",
+    "intakePolicy.help.extractionMaxPages": "进入提取环节的页数上限。",
     "intakePolicy.help.extractionSource": "选择用于提取的文本、视觉或组合证据。",
+    "intakePolicy.help.forceOcr": "对每一页执行 OCR，包括已有文本层的页面。",
+    "intakePolicy.help.forceReview": "无论难度分值如何，都审核每一份文档。",
     "intakePolicy.help.grounding": "为属性提取创建区块级引用和带批注的证据。",
+    "intakePolicy.help.hardnessThreshold": "达到或超过该分值时改用难读内容模型。",
     "intakePolicy.help.identification": "提取前自动选择类型的说明。",
     "intakePolicy.help.identificationGuidance": "描述此内容类型及应选择它的情形。",
     "intakePolicy.help.locateInstructions": "设置此项可在转换和提取前识别相关页面。",
+    "intakePolicy.help.locateMinPages": "文档短于此页数时跳过页面定位。",
+    "intakePolicy.help.maxImageTokens": "真正起作用的预算：每次调用的预估图像令牌数。",
+    "intakePolicy.help.maxPayloadMb": "这是传输上限，不是质量设置。",
+    "intakePolicy.help.method": "文本来自内置解析、模型，还是你自己的交互。",
+    "intakePolicy.help.minCitationDensity": "每个提取值的引用过少时，该轮会重试。",
     "intakePolicy.help.mode": "默认使用程序化采集；智能体采集将编排委派给智能体。",
+    "intakePolicy.help.omitBlockBoxes": "从提示中去掉区块边框。仅在启用视觉时才安全。",
     "intakePolicy.help.pageRanges": "包含起始页和结束页。负值从文档末尾开始计数。",
+    "intakePolicy.help.pageScope": "全部页面，或仅定位器选出的页面。",
+    "intakePolicy.help.refreshOcr": "重新运行 OCR，而不是复用已存储的 OCR 结果。",
+    "intakePolicy.help.renderDpi": "为模型渲染每一页时的分辨率。150 几乎适用于所有情况，仅在字迹极小时才调高。",
     "intakePolicy.help.renderingTemplate": "用于将提取属性呈现为对象文本的 Handlebars 模板。",
     "intakePolicy.help.review": "对困难或低覆盖率页面进行可选的模型审核。",
+    "intakePolicy.help.section.classification": "Vertesia 如何识别此类型，以及其对象默认以何种方式打开。",
+    "intakePolicy.help.section.conversion": "在提取任何内容之前，先把源文件转换为可读文本。",
+    "intakePolicy.help.section.conversionModel": "负责将页面转为文本的模型，通常比提取模型更便宜。",
+    "intakePolicy.help.section.customConversion": "用你自己的交互或智能体替代内置转换器。",
+    "intakePolicy.help.section.embeddings": "哪些内容会被编入搜索索引，以及是否生成目录。",
+    "intakePolicy.help.section.extraction": "此类型的架构属性如何从文档中填充。",
+    "intakePolicy.help.section.extractionModel": "负责读取文档并填充属性的模型。",
+    "intakePolicy.help.section.grounding": "将每个提取值追溯到其来源页面上的区块或视觉位置。",
+    "intakePolicy.help.section.locate": "在正式处理前，用低成本的视觉扫描找出重要页面。",
+    "intakePolicy.help.section.models": "根据文档页面的阅读难度选择使用的模型。",
+    "intakePolicy.help.section.pageRanges": "要转换的固定页面。设置后优先于页面范围；负值从末尾开始计数。",
+    "intakePolicy.help.section.rendering": "将提取的属性转换为对象正文的模板。",
+    "intakePolicy.help.section.review": "对引用稀少或难以阅读的页面追加一轮处理。",
+    "intakePolicy.help.section.visionBudget": "单次提取调用可携带的页面图像量。",
     "intakePolicy.help.textConversion": "控制提取和嵌入前的 Markdown 或文本生成。",
     "intakePolicy.help.title": "字段指南",
+    "intakePolicy.help.updateProperties": "将带依据的结果写回对象属性。",
+    "intakePolicy.help.useVision": "将带批注的页面图像与文本一起发送。",
+    "intakePolicy.help.visionDetail": "此类型可使用的图像质量配置。配置本身由平台定义。",
+    "intakePolicy.help.windowPages": "拆分前，单次依据调用处理的页数。",
     "intakePolicy.option.agentic": "智能体",
     "intakePolicy.option.all": "所有页面",
     "intakePolicy.option.auto": "自动",

package/src/router/RouteComponent.test.tsx

@@ -0,0 +1,139 @@
+import { act, cleanup, render, screen, waitFor } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { prefetchLazyRoutes, RouteComponent } from './RouteComponent';
+import { type LazyRouteModule, useNavigate } from './Router';
+import { RouterProvider } from './RouterProvider';
+
+/**
+ * Lazy routes resolve their module asynchronously, which opens two windows for showing the wrong
+ * page: reusing the state of the previous lazy route while the next import is in flight, and a
+ * slower earlier import landing after a newer navigation already resolved. Both were real —
+ * RouteComponent now remounts per path and drops stale module resolutions.
+ */
+
+function deferredModule(text: string) {
+    let resolve!: (module: LazyRouteModule) => void;
+    const promise = new Promise<LazyRouteModule>((r) => {
+        resolve = r;
+    });
+    return {
+        promise,
+        resolve: () => resolve({ default: () => <div>{text}</div> }),
+    };
+}
+
+let navigateFn: ReturnType<typeof useNavigate>;
+function CaptureNavigate() {
+    navigateFn = useNavigate();
+    return null;
+}
+
+describe('RouteComponent lazy routes', () => {
+    beforeEach(() => {
+        window.history.pushState({}, '', '/a');
+    });
+
+    afterEach(() => {
+        cleanup();
+        window.history.pushState({}, '', '/');
+    });
+
+    it('stops showing the previous lazy route while the next one loads', async () => {
+        const pageA = deferredModule('Page A');
+        const pageB = deferredModule('Page B');
+        const routes = [
+            { path: '/a', LazyComponent: () => pageA.promise },
+            { path: '/b', LazyComponent: () => pageB.promise },
+        ];
+        render(
+            <RouterProvider routes={routes}>
+                <CaptureNavigate />
+                <RouteComponent spinner={<div>loading</div>} />
+            </RouterProvider>,
+        );
+        await act(async () => pageA.resolve());
+        await waitFor(() => expect(screen.getByText('Page A')).toBeDefined());
+
+        await act(async () => navigateFn('/b'));
+        // The old page must not linger while B's import is still pending.
+        expect(screen.queryByText('Page A')).toBeNull();
+        expect(screen.getByText('loading')).toBeDefined();
+
+        await act(async () => pageB.resolve());
+        await waitFor(() => expect(screen.getByText('Page B')).toBeDefined());
+    });
+
+    it('ignores a slow import that resolves after a newer navigation', async () => {
+        const pageA = deferredModule('Page A');
+        const pageB = deferredModule('Page B');
+        const routes = [
+            { path: '/a', LazyComponent: () => pageA.promise },
+            { path: '/b', LazyComponent: () => pageB.promise },
+        ];
+        render(
+            <RouterProvider routes={routes}>
+                <CaptureNavigate />
+                <RouteComponent />
+            </RouterProvider>,
+        );
+        // Navigate away from /a before its import resolves.
+        await act(async () => navigateFn('/b'));
+        await act(async () => pageB.resolve());
+        await waitFor(() => expect(screen.getByText('Page B')).toBeDefined());
+
+        // A's import resolving late must not replace the current page.
+        await act(async () => pageA.resolve());
+        expect(screen.queryByText('Page A')).toBeNull();
+        expect(screen.getByText('Page B')).toBeDefined();
+    });
+
+    it('renders a previously resolved lazy route synchronously on revisit', async () => {
+        const pageA = deferredModule('Page A');
+        const pageB = deferredModule('Page B');
+        const routes = [
+            { path: '/a', LazyComponent: () => pageA.promise },
+            { path: '/b', LazyComponent: () => pageB.promise },
+        ];
+        render(
+            <RouterProvider routes={routes}>
+                <CaptureNavigate />
+                <RouteComponent spinner={<div>loading</div>} />
+            </RouterProvider>,
+        );
+        await act(async () => pageA.resolve());
+        await waitFor(() => expect(screen.getByText('Page A')).toBeDefined());
+        await act(async () => navigateFn('/b'));
+        await act(async () => pageB.resolve());
+        await waitFor(() => expect(screen.getByText('Page B')).toBeDefined());
+
+        // Back to /a: its module is cached, so not even one spinner frame may show.
+        act(() => navigateFn('/a'));
+        expect(screen.getByText('Page A')).toBeDefined();
+        expect(screen.queryByText('loading')).toBeNull();
+    });
+
+    it('prefetched lazy routes render without a spinner on first navigation', async () => {
+        const pageA = deferredModule('Page A');
+        const pageB = deferredModule('Page B');
+        const routes = [
+            { path: '/a', LazyComponent: () => pageA.promise },
+            { path: '/b', LazyComponent: () => pageB.promise },
+            { path: '/c', Component: () => <div>Page C</div> },
+        ];
+        pageA.resolve();
+        pageB.resolve();
+        await prefetchLazyRoutes(routes);
+
+        render(
+            <RouterProvider routes={routes}>
+                <CaptureNavigate />
+                <RouteComponent spinner={<div>loading</div>} />
+            </RouterProvider>,
+        );
+        // Even the initial mount renders from the prefetch cache.
+        expect(screen.getByText('Page A')).toBeDefined();
+        act(() => navigateFn('/b'));
+        expect(screen.getByText('Page B')).toBeDefined();
+        expect(screen.queryByText('loading')).toBeNull();
+    });
+});

package/src/router/RouteComponent.tsx

@@ -1,5 +1,41 @@
 import { useEffect, useState } from 'react';
-import { type ComponentRoute, type LazyComponentRoute, type LazyRouteModule, useRouterContext } from './Router';
+import {
+    type ComponentRoute,
+    type LazyComponentRoute,
+    type LazyRouteModule,
+    type Route,
+    useRouterContext,
+} from './Router';
+
+// Resolved lazy modules, keyed by the route's LazyComponent function (a stable identity: route
+// tables are declared once). A revisited lazy route renders synchronously from this cache instead
+// of unmounting to the spinner for the async import() round-trip — without it, every navigation
+// between two lazy routes blanks the page for at least a frame, even when the module is loaded.
+const resolvedComponents = new Map<LazyComponentRoute['LazyComponent'], LazyRouteModule['default']>();
+
+function resolveLazyRoute(route: LazyComponentRoute): Promise<LazyRouteModule['default']> {
+    return route.LazyComponent().then((module) => {
+        if (!module.default) {
+            throw new Error(`Lazy module for ${route.path} does not have a default export`);
+        }
+        resolvedComponents.set(route.LazyComponent, module.default);
+        return module.default;
+    });
+}
+
+/**
+ * Start loading the given routes' lazy modules ahead of navigation (non-lazy routes are ignored).
+ * Call it during idle time after first paint: the first navigation to a prefetched route then
+ * renders synchronously instead of flashing the spinner while its chunk downloads. Failures are
+ * swallowed — navigation retries the import and reports the error the normal way.
+ */
+export function prefetchLazyRoutes(routes: Route[]): Promise<unknown> {
+    return Promise.allSettled(
+        routes
+            .filter((route): route is LazyComponentRoute => !!(route as LazyComponentRoute).LazyComponent)
+            .map((route) => resolveLazyRoute(route)),
+    );
+}
 
 interface RouteComponentProps {
     spinner?: React.ReactNode;
@@ -12,7 +48,9 @@ export function RouteComponent({ spinner }: RouteComponentProps) {
         const Component = (route as ComponentRoute).Component;
         return <Component {...ctx.params} />;
     } else if ((route as LazyComponentRoute).LazyComponent) {
-        return <LazyRouteComponent route={route as LazyComponentRoute} spinner={spinner} />;
+        // Keyed per path so navigating between two lazy routes remounts: a reused instance would
+        // keep rendering the previous route's component while the next import resolves.
+        return <LazyRouteComponent key={route.path} route={route as LazyComponentRoute} spinner={spinner} />;
     } else {
         throw new Error(`Invalid route for ${route.path}. Either Component or LazyCOmponent must be specified.`);
     }
@@ -23,16 +61,23 @@ interface LazyRouteComponentProps {
     spinner?: React.ReactNode;
 }
 function LazyRouteComponent({ route, spinner }: LazyRouteComponentProps) {
-    const [Component, setComponent] = useState<LazyRouteModule['default'] | null>(null);
+    const [Component, setComponent] = useState<LazyRouteModule['default'] | null>(
+        () => resolvedComponents.get(route.LazyComponent) ?? null,
+    );
     useEffect(() => {
-        void route.LazyComponent().then((module) => {
-            if (!module.default) {
-                throw new Error(`Lazy module for ${route.path} does not have a default export`);
+        // A slow import must not land after this instance moved on (unmount, or a route object
+        // swap without a path change): the stale module would overwrite the current one.
+        let stale = false;
+        void resolveLazyRoute(route).then((component) => {
+            if (!stale) {
+                // we need to wrap the component type in an arrow function
+                // otherwise the setState function will execute the function as a state update function
+                setComponent(() => component);
             }
-            // we need to wrap the component type in an arrow function
-            // otherwise the setState function will execute the function as a state update function
-            setComponent(() => module.default);
         });
+        return () => {
+            stale = true;
+        };
     }, [route]);
 
     return Component ? <Component /> : spinner || null;

package/src/session/UserSessionProvider.tsx

@@ -12,7 +12,7 @@ import {
     resolveAuthSelection,
     UserNotFoundError,
 } from './auth/composable';
-import { authReturnUrl, shouldRedirectToCentralAuth } from './auth/domainRouting';
+import { authReturnUrl, centralAuthRedirectUrl, shouldRedirectToCentralAuth } from './auth/domainRouting';
 import { getFirebaseAuth } from './auth/firebase';
 import { useAuthState } from './auth/useAuthState';
 import { UserSession, UserSessionContext } from './UserSession';
@@ -110,13 +110,14 @@ export function UserSessionProvider({ children, loadOnboardingStatus = true }: U
         return true;
     };
 
-    const redirectToCentralAuth = (projectId?: string, accountId?: string) => {
-        const url = new URL(`${CENTRAL_AUTH_REDIRECT}?sts=${Env.endpoints.sts ?? 'https://sts.vertesia.io'}`);
-        const currentUrl = authReturnUrl();
-        if (projectId) currentUrl.searchParams.set('p', projectId);
-        if (accountId) currentUrl.searchParams.set('a', accountId);
-        url.searchParams.set('redirect_uri', currentUrl.toString());
-        url.searchParams.set('state', generateState());
+    const redirectToCentralAuth = (selection: { accountId?: string; projectId?: string }) => {
+        const url = centralAuthRedirectUrl({
+            centralAuthUrl: CENTRAL_AUTH_REDIRECT,
+            stsEndpoint: Env.endpoints.sts ?? 'https://sts.vertesia.io',
+            returnUrl: authReturnUrl(),
+            state: generateState(),
+            ...selection,
+        });
         location.replace(url.toString());
     };
 
@@ -171,7 +172,7 @@ export function UserSessionProvider({ children, loadOnboardingStatus = true }: U
                         state: state,
                     },
                 });
-                redirectToCentralAuth();
+                redirectToCentralAuth({ accountId: selectedAccount, projectId: selectedProject });
             } else {
                 clearState();
             }
@@ -191,7 +192,7 @@ export function UserSessionProvider({ children, loadOnboardingStatus = true }: U
                             error: err,
                         },
                     });
-                    redirectToCentralAuth();
+                    redirectToCentralAuth({ accountId: selectedAccount, projectId: selectedProject });
                 });
             return;
         }
@@ -217,7 +218,7 @@ export function UserSessionProvider({ children, loadOnboardingStatus = true }: U
                             project_id: selectedProject,
                         },
                     });
-                    redirectToCentralAuth();
+                    redirectToCentralAuth({ accountId: selectedAccount, projectId: selectedProject });
                     return; // Don't register onAuthStateChanged listener when redirecting
                 }
 

package/src/session/auth/domainRouting.test.ts

@@ -1,5 +1,10 @@
 import { afterEach, describe, expect, it } from 'vitest';
-import { mountRootUrl, shouldRedirectToCentralAuth, shouldUseFirebaseAuth } from './domainRouting';
+import {
+    centralAuthRedirectUrl,
+    mountRootUrl,
+    shouldRedirectToCentralAuth,
+    shouldUseFirebaseAuth,
+} from './domainRouting';
 
 // Stub document.baseURI to simulate the served `<base href>` (deep gateway mount) or its absence.
 function setBaseURI(baseURI: string) {
@@ -30,6 +35,24 @@ describe('domainRouting', () => {
         expect(shouldRedirectToCentralAuth()).toBe(true);
     });
 
+    it('carries the selected account and project through central auth for a gateway-mounted app', () => {
+        const redirect = centralAuthRedirectUrl({
+            centralAuthUrl: 'https://internal-auth.vertesia.app/',
+            stsEndpoint: 'https://sts.example.test',
+            returnUrl: new URL('https://apps.example.test/tenants/t/apps/a/versions/v/app/?view=grid'),
+            state: 'state-1',
+            accountId: 'account-1',
+            projectId: 'project-1',
+        });
+        const returnUrl = new URL(redirect.searchParams.get('redirect_uri') || '');
+
+        expect(redirect.searchParams.get('sts')).toBe('https://sts.example.test');
+        expect(redirect.searchParams.get('state')).toBe('state-1');
+        expect(returnUrl.toString()).toBe(
+            'https://apps.example.test/tenants/t/apps/a/versions/v/app/?view=grid&p=project-1&a=account-1',
+        );
+    });
+
     describe('mountRootUrl', () => {
         it('returns the deep gateway mount root (dropping any deep route / query / hash)', () => {
             const mount = 'https://gw.example.com/tenants/05948c_5ed5f4/apps/furniture-catalog/versions/v1/app/';

package/src/session/auth/domainRouting.ts

@@ -12,6 +12,35 @@ export function shouldRedirectToCentralAuth(_hostname?: string) {
     return !shouldUseFirebaseAuth();
 }
 
+interface CentralAuthRedirectOptions {
+    centralAuthUrl: string;
+    stsEndpoint: string;
+    returnUrl: URL;
+    state: string;
+    accountId?: string;
+    projectId?: string;
+}
+
+/** Build a central-auth round trip without losing the app's requested account/project selection. */
+export function centralAuthRedirectUrl({
+    centralAuthUrl,
+    stsEndpoint,
+    returnUrl,
+    state,
+    accountId,
+    projectId,
+}: CentralAuthRedirectOptions): URL {
+    const selectedReturnUrl = new URL(returnUrl);
+    if (projectId) selectedReturnUrl.searchParams.set('p', projectId);
+    if (accountId) selectedReturnUrl.searchParams.set('a', accountId);
+
+    const url = new URL(centralAuthUrl);
+    url.searchParams.set('sts', stsEndpoint);
+    url.searchParams.set('redirect_uri', selectedReturnUrl.toString());
+    url.searchParams.set('state', state);
+    return url;
+}
+
 /**
  * The page URL to return to after a central-auth round-trip (`redirect_uri`).
  *

package/src/session/useUXTracking.tsx

@@ -23,7 +23,12 @@ export function useUXTracking() {
             console.debug('track event', eventName, eventProperties);
         }
 
-        //GA via firebase
+        // GA via firebase — needs a complete Firebase config. A partial one (no apiKey, as in
+        // central-auth deployments and local setups) would make the Installations SDK log an
+        // async FirebaseError on every event, so analytics is a no-op there.
+        if (!Env.firebase?.apiKey) {
+            return;
+        }
         logEvent(getFirebaseAnalytics(), eventName, { ...eventProperties, debug_mode: !Env.isProd });
     };