cabloy 5.1.172 → 5.1.174

package/zova/src/suite/cabloy-basic/modules/basic-button/src/component/button/controller.tsx

@@ -0,0 +1,39 @@
+import type { ButtonHTMLAttributes } from 'vue';
+import type { IComponentOptions } from 'zova';
+
+import { BeanControllerBase } from 'zova';
+import { Controller } from 'zova-module-a-bean';
+
+import type { IBehaviorOptionsPerform, TypeBehaviorOnError } from '../../bean/behavior.perform.jsx';
+
+export interface ControllerButtonProps extends Omit<ButtonHTMLAttributes, 'onError'> {
+  loading?: boolean;
+  onPerform?: (e: MouseEvent) => Promise<void> | void;
+  onError?: TypeBehaviorOnError;
+}
+
+@Controller()
+export class ControllerButton extends BeanControllerBase {
+  static $propsDefault = {};
+  static $componentOptions: IComponentOptions = { inheritAttrs: false };
+
+  protected async __init__() {}
+
+  protected render() {
+    const { loading, onError, onPerform, ...props } = this.$props as ControllerButtonProps;
+    const behaviorPerformOptions: IBehaviorOptionsPerform = {
+      isLoading: loading,
+      onError,
+      onPerform,
+    };
+    return (
+      <button
+        {...props}
+        type={props.type ?? 'button'}
+        bs-basic-button-perform={behaviorPerformOptions}
+      >
+        {this.$slotDefault?.()}
+      </button>
+    );
+  }
+}

package/zova/src/suite/cabloy-basic/modules/basic-button/src/index.ts

@@ -0,0 +1 @@
+export * from './.metadata/index.js';

package/zova/src/suite/cabloy-basic/modules/basic-button/tsconfig.build.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.base",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "declaration": true,
+    "declarationMap": true,
+    "emitDeclarationOnly": true,
+    "allowImportingTsExtensions": true,
+    "noEmit": false
+  },
+  "include": ["src", "src/.metadata/**/*"]
+}

package/zova/src/suite/cabloy-basic/modules/basic-button/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.base",
+  "compilerOptions": {},
+  "include": ["src", "src/.metadata/**/*"]
+}

package/zova/src/suite/cabloy-basic/modules/basic-details/package.json

@@ -51,7 +51,8 @@
   "title": "basic-details",
   "zovaModule": {
     "dependencies": {
-      "basic-app": "5.0.0"
+      "basic-app": "5.0.0",
+      "basic-button": "5.0.0"
     }
   }
 }

package/zova/src/suite/cabloy-basic/modules/basic-details/src/bean/tableCell.actionDelete.tsx

@@ -8,6 +8,7 @@ import type {
 import { BeanBase } from 'zova';
 import { ZIcon } from 'zova-module-a-icon';
 import { TableCell } from 'zova-module-a-table';
+import { ZButton } from 'zova-module-basic-button';
 
 import { ICommandOptionsDelete } from './command.delete.jsx';
 
@@ -30,10 +31,9 @@ export class TableCellActionDelete extends BeanBase implements ITableCellRender
   ) {
     const { $host } = renderContext;
     return (
-      <button
+      <ZButton
         class={options.class}
-        type="button"
-        onClick={async () => {
+        onPerform={async () => {
           const confirmed = await $host.$performCommand('basic-commands:confirm', {
             text: this.scope.locale.DeleteConfirm(),
           });
@@ -46,7 +46,7 @@ export class TableCellActionDelete extends BeanBase implements ITableCellRender
         }}
       >
         <ZIcon name="::delete" width={24}></ZIcon>
-      </button>
+      </ZButton>
     );
   }
 }

package/zova/src/suite/cabloy-basic/modules/basic-page/src/component/blockPage/controller.tsx

@@ -58,7 +58,11 @@ export class ControllerBlockPage<TData extends {} = {}> extends BeanControllerBa
     pageSize: 20,
   };
 
-  static $componentOptions: IComponentOptions = { inheritAttrs: false, deepExtendDefault: true };
+  static $componentOptions: IComponentOptions = {
+    inheritAttrs: false,
+    deepExtendDefault: true,
+    boundary: { retry: true },
+  };
 
   tableRef: BeanControllerTableBase<TData> | undefined;
   private _tableMetaRefreshPending = false;

package/zova/src/suite/cabloy-basic/modules/basic-pageentry/src/component/blockPageEntry/controller.tsx

@@ -42,7 +42,11 @@ export interface ControllerBlockPageEntryProps extends IResourceBlockOptionsBase
 @Controller()
 export class ControllerBlockPageEntry<TData extends {} = {}> extends BeanControllerBase {
   static $propsDefault = { pageTitleKey: 'name' };
-  static $componentOptions: IComponentOptions = { inheritAttrs: false, deepExtendDefault: true };
+  static $componentOptions: IComponentOptions = {
+    inheritAttrs: false,
+    deepExtendDefault: true,
+    boundary: { retry: true },
+  };
 
   entryIdCreated?: TableIdentity;
 

package/zova/src/suite/cabloy-basic/modules/basic-table/package.json

@@ -51,7 +51,8 @@
   "title": "basic-table",
   "zovaModule": {
     "dependencies": {
-      "basic-app": "5.0.0"
+      "basic-app": "5.0.0",
+      "basic-button": "5.0.0"
     }
   }
 }

package/zova/src/suite/cabloy-basic/modules/basic-table/src/bean/tableCell.actionDelete.tsx

@@ -8,6 +8,7 @@ import type {
 import { BeanBase } from 'zova';
 import { ZIcon } from 'zova-module-a-icon';
 import { TableCell } from 'zova-module-a-table';
+import { ZButton } from 'zova-module-basic-button';
 
 declare module 'zova-module-a-openapi' {
   export interface IResourceTableActionRowRecord {
@@ -28,10 +29,9 @@ export class TableCellActionDelete extends BeanBase implements ITableCellRender
   ) {
     const { $host } = renderContext;
     return (
-      <button
+      <ZButton
         class={options.class}
-        type="button"
-        onClick={async () => {
+        onPerform={async () => {
           const confirmed = await $host.$performCommand('basic-commands:confirm', {
             text: this.scope.locale.DeleteConfirm(),
           });
@@ -40,7 +40,7 @@ export class TableCellActionDelete extends BeanBase implements ITableCellRender
         }}
       >
         <ZIcon name="::delete" width={24}></ZIcon>
-      </button>
+      </ZButton>
     );
   }
 }

package/zova/src/suite/cabloy-basic/modules/basic-table/src/component/actionRefresh/controller.tsx

@@ -6,6 +6,8 @@ import type {
 
 import { BeanControllerBase, Use } from 'zova';
 import { Controller } from 'zova-module-a-bean';
+import { ZIcon } from 'zova-module-a-icon';
+import { ZButton } from 'zova-module-basic-button';
 
 declare module 'zova-module-a-openapi' {
   export interface IResourceTableActionBulkRecord {
@@ -26,17 +28,17 @@ export class ControllerActionRefresh extends BeanControllerBase {
   protected render() {
     const disabled = this.$props.disabled === true || this.$props.dynamicDisabled === true;
     return (
-      <button
-        class={this.$props.class}
-        type="button"
+      <ZButton
+        class={[this.$props.class, 'btn-square']}
         disabled={disabled}
-        onClick={async () => {
-          if (disabled) return;
-          await this.$$renderContext.$$page.queryData.refetch();
+        aria-label={this.scope.locale.Refresh()}
+        title={this.scope.locale.Refresh()}
+        onPerform={async () => {
+          await this.$$renderContext.$$page.queryData.refetch({ throwOnError: true });
         }}
       >
-        {this.scope.locale.Refresh() as string}
-      </button>
+        <ZIcon name="::arrow-repeat" width={20}></ZIcon>
+      </ZButton>
     );
   }
 }

package/zova/src/suite/cabloy-basic/package.json

@@ -9,6 +9,7 @@
   "dependencies": {
     "zova-module-basic-adapter": "^5.0.5",
     "zova-module-basic-app": "^5.0.0",
+    "zova-module-basic-button": "^5.0.0",
     "zova-module-basic-captcha": "^5.0.8",
     "zova-module-basic-commands": "^5.1.15",
     "zova-module-basic-commandssync": "^5.0.5",

package/zova/src/suite-vendor/a-cabloy/modules/a-layoutprofile/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zova-module-a-layoutprofile",
-  "version": "5.0.2",
+  "version": "5.0.3",
   "description": "",
   "keywords": [
     "Zova Module"

package/zova/src/suite-vendor/a-cabloy/modules/a-layoutprofile/src/model/layoutprofile.ts

@@ -36,9 +36,6 @@ export class ModelLayoutProfile extends BeanModelBase {
           query: { layoutKey: this.layoutKey },
         });
       },
-      meta: {
-        disableErrorEffect: true,
-      },
     });
   }
 

package/zova/src/suite-vendor/a-cabloy/modules/rest-resource/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zova-module-rest-resource",
-  "version": "5.1.54",
+  "version": "5.1.55",
   "gitHead": "4dece229b6d3f4735930e833afcb4b95ec51bf86",
   "description": "",
   "keywords": [

package/zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/.metadata/page/resource.ts

@@ -9,4 +9,9 @@ export namespace NSControllerPageResource {
   export type ParamsOutput = z.output<typeof ControllerPageResourceSchemaParams>;
 }
 
-export const ZPageResource = createZovaComponentPage(ControllerPageResource, undefined, undefined);
+export const ZPageResource = createZovaComponentPage(
+  ControllerPageResource,
+  undefined,
+  undefined,
+  ControllerPageResource.$componentOptions,
+);

package/zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/model/resource.ts

@@ -28,7 +28,6 @@ interface IModelResourceQueryItemOptions<TData> {
   queryFn: () => Promise<TData>;
   meta?: {
     disableSuspenseOnInit?: boolean;
-    disableErrorEffect?: boolean;
     persister?: QueryMetaPersister | boolean;
   };
 }

package/zova/src/suite-vendor/a-cabloy/modules/rest-resource/src/page/resource/controller.tsx

@@ -1,6 +1,6 @@
 import { VNode } from 'vue';
 import { z } from 'zod';
-import { BeanControllerPageBase, deepExtend, Use, usePrepareArg } from 'zova';
+import { BeanControllerPageBase, deepExtend, IComponentOptions, Use, usePrepareArg } from 'zova';
 import { ZovaJsx } from 'zova-jsx';
 import { Controller } from 'zova-module-a-bean';
 import { $QueryEnsureLoaded } from 'zova-module-a-model';
@@ -14,6 +14,10 @@ export const ControllerPageResourceSchemaParams = z.object({
 
 @Controller()
 export class ControllerPageResource extends BeanControllerPageBase {
+  static $componentOptions: IComponentOptions = {
+    boundary: { retry: true },
+  };
+
   jsxZova: ZovaJsx;
 
   @Use({ beanFullName: 'rest-resource.model.resource' })

package/zova/src/suite-vendor/a-cabloy/package.json

@@ -1,15 +1,15 @@
 {
   "name": "zova-suite-a-cabloy",
-  "version": "5.1.56",
+  "version": "5.1.57",
   "gitHead": "4dece229b6d3f4735930e833afcb4b95ec51bf86",
   "description": "",
   "author": "",
   "files": [],
   "type": "module",
   "dependencies": {
-    "zova-module-a-layoutprofile": "^5.0.2",
+    "zova-module-a-layoutprofile": "^5.0.3",
     "zova-module-a-rbac": "^5.0.1",
-    "zova-module-rest-resource": "^5.1.54"
+    "zova-module-rest-resource": "^5.1.55"
   },
   "title": "a-cabloy"
 }

package/zova/src/suite-vendor/a-zova/modules/a-bean/cli/controller/metadata/generateFilePage.ts

@@ -22,6 +22,7 @@ export async function generateFilePage(
     importStyleFirst,
     hasStyleFirst,
     classNameStyleFirst,
+    hasComponentOptions,
   } = controllerInfo;
   const { nameSchemaParams, hasSchemaParams, nameSchemaQuery, hasSchemaQuery } = controllerInfo;
   const contentImports: string[] = [];
@@ -68,7 +69,8 @@ export async function generateFilePage(
     }`);
   }
   // page
-  const contentPage = `export const ZPage${nameCapitalize} = createZovaComponentPage(${className}, ${hasRenderFirst ? classNameRenderFirst : undefined}, ${hasStyleFirst ? classNameStyleFirst : undefined});`;
+  const componentOptions = hasComponentOptions ? `${className}.$componentOptions` : undefined;
+  const contentPage = `export const ZPage${nameCapitalize} = createZovaComponentPage(${className}, ${hasRenderFirst ? classNameRenderFirst : undefined}, ${hasStyleFirst ? classNameStyleFirst : undefined}${componentOptions ? `, ${componentOptions}` : ''});`;
   // content
   const content = `${contentImports.join('\n')}
   ${combineContentRenderAndStyle(controllerInfo, moduleName, className, '', '')}

package/zova/src/suite-vendor/a-zova/modules/a-bean/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zova-module-a-bean",
-  "version": "5.1.35",
+  "version": "5.1.36",
   "gitHead": "09d901d17140a80ee0764211b441cda72fd94663",
   "description": "",
   "keywords": [

package/zova/src/suite-vendor/a-zova/modules/a-model/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zova-module-a-model",
-  "version": "5.1.36",
+  "version": "5.1.37",
   "gitHead": "09d901d17140a80ee0764211b441cda72fd94663",
   "description": "core",
   "keywords": [

package/zova/src/suite-vendor/a-zova/modules/a-model/src/bean/bean.model/bean.model.useMutation.ts

@@ -41,17 +41,7 @@ export class BeanModelUseMutation extends BeanModelUseStateGeneral {
     mutationKey = this.self._forceQueryKeyPrefix(mutationKey);
     const mutationHash = hashKey(mutationKey);
     if (!this[SymbolUseMutations][mutationHash]) {
-      const optionsDefault: any = {};
-      if (!cast(mutationOptions).meta?.disableErrorEffect) {
-        optionsDefault.onError = (error, variables, context) => {
-          let errorInfo = cast(mutationOptions).meta?.errorInfo;
-          if (typeof errorInfo === 'function') {
-            errorInfo = errorInfo(error, variables, context);
-          }
-          this.$errorHandler(error, errorInfo ?? 'useMutationData');
-        };
-      }
-      mutationOptions = Object.assign(optionsDefault, mutationOptions, { mutationKey });
+      mutationOptions = Object.assign({}, mutationOptions, { mutationKey });
       this[SymbolUseMutations][mutationHash] = this.$useMutation(mutationOptions, queryClient);
     }
     return this[SymbolUseMutations][mutationHash] as UnwrapNestedRefs<

package/zova/src/suite-vendor/a-zova/modules/a-model/src/bean/bean.model/bean.model.useQuery.ts

@@ -1,8 +1,6 @@
 import type { DefaultError, QueryClient, QueryKey, UseQueryOptions } from '@tanstack/vue-query';
 
-import { checkErrorJwtExpired } from '@cabloy/utils';
 import { useQuery } from '@tanstack/vue-query';
-import { cast } from 'zova';
 
 import type {
   DefinedInitialQueryOptions,
@@ -45,21 +43,7 @@ export class BeanModelUseQuery extends BeanModelQuery {
   $useQuery(options, queryClient) {
     const queryKey = this.self._forceQueryKeyPrefix(options.queryKey);
     const persister = this._createPersister(options.meta?.persister);
-    const optionsDefault: any = {};
-    if (!cast(options).meta?.disableErrorEffect) {
-      optionsDefault.throwOnError = (error: Error, query) => {
-        let errorInfo = cast(options).meta?.errorInfo;
-        if (typeof errorInfo === 'function') {
-          errorInfo = errorInfo(error, query);
-        }
-        if (!error.message.includes('useQuery:') && !checkErrorJwtExpired(error)) {
-          error.message = `useQuery: [${queryKey.join(', ')}]: ${error.message}`;
-        }
-        this.$errorHandler(error, errorInfo ?? 'useQuery');
-        return false;
-      };
-    }
-    options = Object.assign(optionsDefault, options, { queryKey, persister });
+    options = Object.assign({}, options, { queryKey, persister });
     // staleTime
     const sync = typeof options.meta?.persister === 'object' && options.meta?.persister?.sync;
     if (sync !== true) {

package/zova/src/suite-vendor/a-zova/modules/a-model/src/lib/utils.ts

@@ -68,7 +68,8 @@ async function _QueryEnsureLoadedInner<T = any>(fn?: TypeQueryEnsureLoadedFn<T>)
   if (!fn) return;
   const query = fn();
   if (query && query.data === undefined) {
-    await query.suspense();
+    const result = await query.suspense();
+    if (result.error) throw result.error;
   }
   return query;
 }

package/zova/src/suite-vendor/a-zova/modules/a-model/src/types/query.ts

@@ -59,17 +59,12 @@ export interface MyQueryMetaBase extends Record<string, unknown> {
   defaultData?: (() => any) | any;
   ssr?: QueryMetaSSR;
   persister?: QueryMetaPersister | boolean;
-  disableErrorEffect?: boolean;
   disableSuspenseOnInit?: boolean;
 }
 
-export interface MyQueryMeta extends MyQueryMetaBase {
-  errorInfo?: ((error, query) => string) | string;
-}
+export interface MyQueryMeta extends MyQueryMetaBase {}
 
-export interface MyMutationMeta extends MyQueryMetaBase {
-  errorInfo?: ((error, variables, context) => string) | string;
-}
+export interface MyMutationMeta extends Record<string, unknown> {}
 
 export interface QueryMetaSSR {
   /** default is true */

package/zova/src/suite-vendor/a-zova/modules/a-model/test/lib/mutation.types.ts

@@ -0,0 +1,14 @@
+import type { MutationObserverOptions } from '@tanstack/vue-query';
+
+import type { MyMutationMeta } from '../../src/types/query.ts';
+
+const mutationOptions: MutationObserverOptions<number, Error, { id: number }> = {
+  mutationKey: ['test:mutation'],
+  mutationFn: async variables => variables.id,
+  onError: (_error, _variables, _context) => {},
+};
+
+const mutationMeta: MyMutationMeta = { source: 'test' };
+
+void mutationOptions;
+void mutationMeta;

package/zova/src/suite-vendor/a-zova/modules/a-model/test/lib/queryEnsureLoaded.test.ts

@@ -0,0 +1,56 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { $QueryEnsureLoaded } from '../../src/lib/utils.js';
+
+type QueryResult<T> = {
+  data: T | undefined;
+  error: Error | null;
+};
+
+function createQuery<T>(data: T | undefined, result: QueryResult<T>) {
+  let suspenseCalls = 0;
+  const query = {
+    data,
+    suspense: async () => {
+      suspenseCalls++;
+      return result;
+    },
+  };
+  return {
+    query,
+    get suspenseCalls() {
+      return suspenseCalls;
+    },
+  };
+}
+
+test('QueryEnsureLoaded throws an initial query error', async () => {
+  const error = new Error('Initial query load failed');
+  const fixture = createQuery(undefined, { data: undefined, error });
+
+  await assert.rejects(
+    $QueryEnsureLoaded(() => fixture.query as never),
+    caught => caught === error,
+  );
+  assert.equal(fixture.suspenseCalls, 1);
+});
+
+test('QueryEnsureLoaded accepts cached data when a background refresh has failed', async () => {
+  const error = new Error('Background refresh failed');
+  const fixture = createQuery({ value: 'cached' }, { data: { value: 'cached' }, error });
+
+  const result = await $QueryEnsureLoaded(() => fixture.query as never);
+
+  assert.equal(result, fixture.query);
+  assert.equal(fixture.suspenseCalls, 0);
+});
+
+test('QueryEnsureLoaded returns a query after an initial successful load', async () => {
+  const fixture = createQuery(undefined, { data: { value: 'loaded' }, error: null });
+
+  const result = await $QueryEnsureLoaded(() => fixture.query as never);
+
+  assert.equal(result, fixture.query);
+  assert.equal(fixture.suspenseCalls, 1);
+});

package/zova/src/suite-vendor/a-zova/modules/a-router/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zova-module-a-router",
-  "version": "5.1.37",
+  "version": "5.1.38",
   "gitHead": "09d901d17140a80ee0764211b441cda72fd94663",
   "description": "router",
   "keywords": [

package/zova/src/suite-vendor/a-zova/modules/a-router/src/monkey.ts

@@ -238,6 +238,9 @@ export class Monkey
   private _ssrErrorHandler() {
     if (!process.env.CLIENT) return;
     this.app.meta.event.on('app:errorHandler', (data, next) => {
+      if (_isLoadErrorHandledClient(data)) {
+        data.load!.disposition = 'handled';
+      }
       const err = next();
       if (!err || !(err instanceof Error)) return err;
       return this._errorHandlerDefaultClient(err, data);
@@ -265,3 +268,8 @@ export class Monkey
     return err;
   }
 }
+
+function _isLoadErrorHandledClient(data: IErrorHandlerEventData) {
+  if (data.load?.kind !== 'controller-load') return false;
+  return [301, 302, 401, 600].includes(Number((data.err as ErrorSSR).code));
+}

package/zova/src/suite-vendor/a-zova/modules/a-ssr/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zova-module-a-ssr",
-  "version": "5.1.39",
+  "version": "5.1.40",
   "gitHead": "09d901d17140a80ee0764211b441cda72fd94663",
   "description": "",
   "keywords": [

package/zova/src/suite-vendor/a-zova/modules/a-ssr/src/lib/ssr.ts

@@ -1,5 +1,5 @@
 import type { ComponentInternalInstance, Ref, VNode } from 'vue';
-import type { Functionable, ILocaleRecord, ZovaContext } from 'zova';
+import type { Functionable, IControllerLoadEvent, ILocaleRecord, ZovaContext } from 'zova';
 
 import { RouteLocationNormalizedGeneric, RouteLocationResolvedGeneric } from '@cabloy/vue-router';
 import { includeBooleanAttr, isBooleanAttr, isString, stringifyStyle } from '@vue/shared';
@@ -14,6 +14,7 @@ import type {
   OnHydratePropHasMismatch,
   OnHydratePropHasMismatchResult,
   SSRContext,
+  SSRControllerLoadErrorSnapshot,
   TypeSsrProfile,
   TypeSsrSitePerformAction,
 } from '../types/ssr.js';
@@ -40,6 +41,7 @@ export class CtxSSR extends BeanSimple {
 
   private [SymbolHydratingCounter]: number = 0;
   private [SymbolServerContexts]: Set<ZovaContext> = new Set();
+  private _controllerLoadSequence: Record<string, number> = {};
 
   public metaStore: CtxSSRMetaStore;
 
@@ -132,6 +134,53 @@ export class CtxSSR extends BeanSimple {
     }
   }
 
+  /** @internal */
+  public controllerLoad(event: IControllerLoadEvent) {
+    if (event.phase === 'prepare') {
+      if (process.env.SERVER) {
+        event.ctx.meta.state.controllerLoadKey = this._allocateControllerLoadKey(event);
+        return;
+      }
+      if (!process.env.CLIENT || !this.isRuntimeSsrPreHydration) return;
+      const key = this._allocateControllerLoadKey(event);
+      const snapshot = this.stateDefer.controllerLoad?.[key];
+      if (
+        !snapshot ||
+        snapshot.version !== 1 ||
+        snapshot.controllerBeanName !== event.controllerBeanName
+      ) {
+        return;
+      }
+      delete this.stateDefer.controllerLoad![key];
+      event.replayError = _createControllerLoadError(snapshot);
+      event.replayControllerRecorded = snapshot.controllerRecorded;
+      return;
+    }
+    if (event.phase !== 'fallback' || !process.env.SERVER || !event.error) return;
+    const key = event.ctx.meta.state.controllerLoadKey;
+    if (!key) return;
+    const controllerLoad = (this.stateDefer.controllerLoad ??= {});
+    controllerLoad[key] = _createControllerLoadErrorSnapshot(event);
+  }
+
+  private _allocateControllerLoadKey(event: IControllerLoadEvent) {
+    const instance = event.ctx.instance;
+    const parts: string[] = [];
+    let current: ComponentInternalInstance | null = instance;
+    while (current) {
+      const componentType = current.type as any;
+      const name =
+        componentType.__file ?? componentType.name ?? componentType.__name ?? 'anonymous';
+      const key = current.vnode.key ?? '';
+      parts.unshift(`${name}:${String(key)}`);
+      current = current.parent;
+    }
+    const structuralKey = parts.join('/');
+    const occurrence = this._controllerLoadSequence[structuralKey] ?? 0;
+    this._controllerLoadSequence[structuralKey] = occurrence + 1;
+    return `${structuralKey}#${occurrence}:${event.controllerBeanName ?? ''}`;
+  }
+
   get profile(): TypeSsrProfile {
     return resolveSsrProfile(this.state.ssrProfile, this.sys.env.SSR_PROFILE);
   }
@@ -367,3 +416,38 @@ export class CtxSSR extends BeanSimple {
     this._serverContextsDispose();
   }
 }
+
+function _createControllerLoadErrorSnapshot(
+  event: IControllerLoadEvent,
+): SSRControllerLoadErrorSnapshot {
+  const error = event.error! as any;
+  const snapshot: SSRControllerLoadErrorSnapshot = {
+    version: 1,
+    controllerBeanName: event.controllerBeanName,
+    name: error.name || 'Error',
+    message: error.message || String(error),
+    controllerRecorded: event.controllerRecorded === true,
+  };
+  for (const key of ['code', 'status']) {
+    if (typeof error[key] === 'number' || typeof error[key] === 'string') {
+      snapshot[key] = error[key];
+    }
+  }
+  for (const key of ['pagePath', 'url']) {
+    if (typeof error[key] === 'string') {
+      snapshot[key] = error[key];
+    }
+  }
+  return snapshot;
+}
+
+function _createControllerLoadError(snapshot: SSRControllerLoadErrorSnapshot) {
+  const error = new Error(snapshot.message);
+  error.name = snapshot.name;
+  for (const key of ['code', 'status', 'pagePath', 'url']) {
+    if (snapshot[key] !== undefined) {
+      (error as any)[key] = snapshot[key];
+    }
+  }
+  return error;
+}