@nocobase/plugin-flow-engine 2.2.0-beta.1 → 2.2.0-beta.11

package/dist/server/flow-surfaces/types.d.ts

@@ -45,7 +45,8 @@ export type FlowSurfaceConfigureOption = {
     type: FlowSurfaceConfigureOptionValueType;
     description?: string;
     enum?: Array<string | number | boolean>;
-    example?: any;
+    example?: unknown;
+    default?: unknown;
     supportsFlowContext?: boolean;
 };
 export type FlowSurfaceConfigureOptions = Record<string, FlowSurfaceConfigureOption>;

package/dist/server/variables/records.js

@@ -63,9 +63,14 @@ function mergeFieldsWithExtras(fields, extras = []) {
   if (!Array.isArray(fields) || fields.length === 0 || extras.length === 0) return fields;
   return uniqStrings([...fields, ...extras]);
 }
+function toJsonRecord(record) {
+  if (!record || typeof record !== "object") return record;
+  const toJSON = record.toJSON;
+  return typeof toJSON === "function" ? toJSON.call(record) : record;
+}
 function toJsonArray(rows) {
   if (!Array.isArray(rows)) return [];
-  return rows.map((r) => (r == null ? void 0 : r.toJSON) ? r.toJSON() : r);
+  return rows.map(toJsonRecord);
 }
 function reorderRecordsByFilterByTk(records, filterByTk, options) {
   if (!Array.isArray(filterByTk) || filterByTk.length === 0) return records;
@@ -110,7 +115,7 @@ async function fetchRecordOrRecordsJson(repo, params) {
   const rec = await repo.findOne(
     preferFullRecord ? { filterByTk } : { filterByTk, fields, appends }
   );
-  return rec ? rec.toJSON() : void 0;
+  return rec ? toJsonRecord(rec) : void 0;
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/server/variables/registry.js

@@ -89,6 +89,9 @@ class VariableRegistry {
 }
 const GLOBAL_KEY = "__ncbVarRegistry__";
 const g = typeof globalThis !== "undefined" ? globalThis : global;
+if (g[GLOBAL_KEY] && typeof g[GLOBAL_KEY] === "object") {
+  Object.setPrototypeOf(g[GLOBAL_KEY], VariableRegistry.prototype);
+}
 if (!g[GLOBAL_KEY]) {
   g[GLOBAL_KEY] = new VariableRegistry();
 }

package/dist/swagger/flow-surfaces.d.ts

@@ -2635,6 +2635,10 @@ declare const _default: {
             FlowSurfaceApplyBlueprintNavigation: {
                 type: string;
                 properties: {
+                    layoutUid: {
+                        type: string;
+                        description: string;
+                    };
                     group: {
                         $ref: string;
                     };
@@ -3148,6 +3152,10 @@ declare const _default: {
                 type: string;
                 required: string[];
                 properties: {
+                    layoutUid: {
+                        type: string;
+                        description: string;
+                    };
                     title: {
                         type: string;
                     };
@@ -3270,6 +3278,10 @@ declare const _default: {
             FlowSurfaceCreatePageRequest: {
                 type: string;
                 properties: {
+                    layoutUid: {
+                        type: string;
+                        description: string;
+                    };
                     menuRouteId: {
                         oneOf: {
                             type: string;
@@ -5763,6 +5775,186 @@ declare const _default: {
                 };
                 additionalProperties: boolean;
             };
+            FlowSurfaceExportBlueprintUnsupportedPolicy: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            FlowSurfaceExportBlueprintUnsupportedItem: {
+                type: string;
+                required: string[];
+                properties: {
+                    kind: {
+                        type: string;
+                        enum: string[];
+                    };
+                    use: {
+                        type: string;
+                        example: string;
+                    };
+                    type: {
+                        type: string;
+                        example: string;
+                    };
+                    path: {
+                        type: string;
+                        example: string;
+                    };
+                    reasonCode: {
+                        type: string;
+                        example: string;
+                    };
+                    manualAction: {
+                        type: string;
+                        example: string;
+                    };
+                };
+                additionalProperties: boolean;
+            };
+            FlowSurfaceExportBlueprintTarget: {
+                oneOf: ({
+                    type: string;
+                    required: string[];
+                    properties: {
+                        uid: {
+                            type: string;
+                        };
+                        pageSchemaUid?: undefined;
+                        tabSchemaUid?: undefined;
+                        routeId?: undefined;
+                    };
+                    additionalProperties: boolean;
+                } | {
+                    type: string;
+                    required: string[];
+                    properties: {
+                        pageSchemaUid: {
+                            type: string;
+                        };
+                        uid?: undefined;
+                        tabSchemaUid?: undefined;
+                        routeId?: undefined;
+                    };
+                    additionalProperties: boolean;
+                } | {
+                    type: string;
+                    required: string[];
+                    properties: {
+                        tabSchemaUid: {
+                            type: string;
+                        };
+                        uid?: undefined;
+                        pageSchemaUid?: undefined;
+                        routeId?: undefined;
+                    };
+                    additionalProperties: boolean;
+                } | {
+                    type: string;
+                    required: string[];
+                    properties: {
+                        routeId: {
+                            type: string;
+                        };
+                        uid?: undefined;
+                        pageSchemaUid?: undefined;
+                        tabSchemaUid?: undefined;
+                    };
+                    additionalProperties: boolean;
+                })[];
+                description: string;
+            };
+            FlowSurfaceExportBlueprintRequest: {
+                type: string;
+                required: string[];
+                properties: {
+                    target: {
+                        $ref: string;
+                    };
+                    options: {
+                        type: string;
+                        properties: {
+                            unsupported: {
+                                $ref: string;
+                            };
+                        };
+                        additionalProperties: boolean;
+                    };
+                };
+                additionalProperties: boolean;
+            };
+            FlowSurfaceExportBlueprintSource: {
+                type: string;
+                required: string[];
+                properties: {
+                    target: {
+                        $ref: string;
+                    };
+                    pageTitle: {
+                        type: string;
+                    };
+                };
+                additionalProperties: boolean;
+            };
+            FlowSurfaceExportBlueprintDocument: {
+                type: string;
+                required: string[];
+                description: string;
+                properties: {
+                    version: {
+                        type: string;
+                        enum: string[];
+                    };
+                    mode: {
+                        type: string;
+                        enum: string[];
+                    };
+                    target: {
+                        $ref: string;
+                    };
+                    page: {
+                        $ref: string;
+                    };
+                    tabs: {
+                        type: string;
+                        minItems: number;
+                        items: {
+                            $ref: string;
+                        };
+                    };
+                    assets: {
+                        $ref: string;
+                    };
+                    reaction: {
+                        $ref: string;
+                    };
+                };
+                additionalProperties: boolean;
+            };
+            FlowSurfaceExportBlueprintResponse: {
+                type: string;
+                required: string[];
+                properties: {
+                    document: {
+                        $ref: string;
+                    };
+                    source: {
+                        $ref: string;
+                    };
+                    warnings: {
+                        type: string;
+                        items: {
+                            type: string;
+                        };
+                    };
+                    unsupported: {
+                        type: string;
+                        items: {
+                            $ref: string;
+                        };
+                    };
+                };
+                additionalProperties: boolean;
+            };
             FlowSurfaceMutateWriteTarget: {
                 type: string;
                 required: string[];
@@ -5922,6 +6114,7 @@ declare const _default: {
                         };
                     };
                     example: {};
+                    default: {};
                     supportsFlowContext: {
                         type: string;
                     };

package/dist/swagger/flow-surfaces.examples.d.ts

@@ -28,6 +28,14 @@ export declare const flowSurfaceExamples: {
             expectedKind: string;
         }[];
     };
+    exportBlueprint: {
+        target: {
+            pageSchemaUid: string;
+        };
+        options: {
+            unsupported: string;
+        };
+    };
     applyBlueprint: {
         version: string;
         mode: string;
@@ -660,6 +668,7 @@ export declare const flowSurfaceExamples: {
                 title: string;
                 description: string;
                 className: string;
+                showBlockCard: boolean;
                 version: string;
                 code: string;
             };
@@ -756,6 +765,7 @@ export declare const flowSurfaceExamples: {
             title: string;
             description: string;
             className: string;
+            showBlockCard: boolean;
             version: string;
             code: string;
         };
@@ -1060,6 +1070,7 @@ export declare const flowSurfaceExamples: {
         settings: {
             title: string;
             description: string;
+            showBlockCard: boolean;
             version: string;
             code: string;
         };

package/dist/swagger/flow-surfaces.examples.js

@@ -106,6 +106,14 @@ const flowSurfaceExamples = {
       }
     ]
   },
+  exportBlueprint: {
+    target: {
+      pageSchemaUid: "employees-page-schema"
+    },
+    options: {
+      unsupported: "error"
+    }
+  },
   applyBlueprint: {
     version: "1",
     mode: "create",
@@ -885,6 +893,7 @@ const flowSurfaceExamples = {
           title: "Custom hero",
           description: "Rendered by JS block runtime",
           className: "hero-shell",
+          showBlockCard: true,
           version: "1.0.0",
           code: "ctx.render('<div>Hello from JS block</div>');"
         }
@@ -988,6 +997,7 @@ const flowSurfaceExamples = {
       title: "Users hero",
       description: "Rendered from FlowSurfaces configure",
       className: "users-hero",
+      showBlockCard: true,
       version: "1.0.1",
       code: "ctx.render('<div>Users hero</div>');"
     }
@@ -1333,6 +1343,7 @@ const flowSurfaceExamples = {
     settings: {
       title: "Users banner",
       description: "Custom JS rendered banner",
+      showBlockCard: true,
       version: "1.0.0",
       code: "ctx.render('<div>Users banner</div>');"
     }

package/dist/swagger/flow-surfaces.js

@@ -141,7 +141,11 @@ const APPLY_BLUEPRINT_BLOCK_TYPE_ENUM = [
   "jsBlock",
   "tree"
 ];
-const APPROVAL_BLUEPRINT_BLOCK_TYPE_ENUM = [...import_catalog_specs.APPROVAL_BLOCK_PUBLIC_KEYS];
+const APPROVAL_BLUEPRINT_GENERIC_BLOCK_TYPE_ENUM = ["markdown", "jsBlock"];
+const APPROVAL_BLUEPRINT_BLOCK_TYPE_ENUM = [
+  ...import_catalog_specs.APPROVAL_BLOCK_PUBLIC_KEYS,
+  ...APPROVAL_BLUEPRINT_GENERIC_BLOCK_TYPE_ENUM
+];
 const COMPOSE_BLOCK_TYPE_ENUM = [...APPLY_BLUEPRINT_BLOCK_TYPE_ENUM, ...import_catalog_specs.APPROVAL_BLOCK_PUBLIC_KEYS];
 const RELATION_FIELD_TYPE_ENUM = [
   "text",
@@ -496,7 +500,7 @@ function buildReactionCapabilitySchema(kind, ruleSchemaName, extraProperties = {
     additionalProperties: false
   };
 }
-const FLOW_SURFACES_READ_ACL_NOTE = "Read actions (`get` / `describeSurface` / `catalog` / `context` / `getReactionMeta` / `getEventFlowMeta` / `listTemplates` / `getTemplate`) are open to `loggedIn` by default. Write actions still require the `ui.flowSurfaces` snippet.";
+const FLOW_SURFACES_READ_ACL_NOTE = "Read actions (`get` / `describeSurface` / `exportBlueprint` / `catalog` / `context` / `getReactionMeta` / `getEventFlowMeta` / `listTemplates` / `getTemplate`) are open to `loggedIn` by default. Write actions still require the `ui.flowSurfaces` snippet.";
 const templateActionDocs = (0, import_flow_surfaces2.createFlowSurfaceTemplateActionDocs)({
   tag: FLOW_SURFACES_TAG,
   readAclNote: FLOW_SURFACES_READ_ACL_NOTE,
@@ -606,11 +610,20 @@ const actionDocs = {
     requestBody: requestBody("FlowSurfaceDescribeSurfaceRequest", import_flow_surfaces.flowSurfaceExamples.describeSurface),
     responses: responses("FlowSurfaceDescribeSurfaceResponse")
   },
+  exportBlueprint: {
+    tags: [FLOW_SURFACES_TAG],
+    summary: "Export one root Modern page as an applyBlueprint replace document",
+    description: valuesCompatibilityNote(
+      `Exports an existing root flow page into a v1 \`FlowSurfaceApplyBlueprintDocument\` that can be sent back to \`flowSurfaces:applyBlueprint\` for same-instance \`replace\`. The request body uses \`{ target, options }\` and does not change the \`flowSurfaces:get\` GET query-locator contract. v1 only supports root page export; block, field, action, tab, and \`tabSchemaUid\` subtree targets return HTTP 400. The exported document intentionally omits \`navigation\` and does not expose raw \`tree\`, \`nodeMap\`, node uid, internal refs, or internal metadata. \`document.target.pageSchemaUid\` is retained for same-instance replace. ${FLOW_SURFACES_READ_ACL_NOTE}`
+    ),
+    requestBody: requestBody("FlowSurfaceExportBlueprintRequest", import_flow_surfaces.flowSurfaceExamples.exportBlueprint),
+    responses: responses("FlowSurfaceExportBlueprintResponse")
+  },
   applyBlueprint: {
     tags: [FLOW_SURFACES_TAG],
     summary: "Apply a page blueprint to create or replace one Modern page",
     description: valuesCompatibilityNote(
-      `Accepts one simplified JSON page blueprint and compiles it to internal flow-surface operations. The public blueprint describes page structure (\`create\` or \`replace\`, page metadata, ordered tabs, blocks, fields, actions, inline popups, optional reusable assets) and optional top-level \`reaction.items[]\` for whole-page interaction authoring. Each reaction item targets an explicit local key / bind key produced by the same blueprint run. Only explicitly listed reaction items are written. \`rules: []\` clears the targeted slot. Repeating the same \`(type, target)\` reaction slot in one blueprint is invalid. In \`replace\`, reaction targets always bind to the newly produced blueprint result, not historical nodes from the previous page version; if a slot must exist in the resulting surface, include it explicitly instead of relying on omission. Localized reaction edits on an existing surface should use \`getReactionMeta\` + \`set*Rules\` instead of applying a whole page blueprint again. The request body is that page-document JSON object itself and must not be JSON-stringified. Wrong: \`{ "requestBody": "{\\"version\\":\\"1\\"}" }\`. Internal planning details stay hidden. In \`create\`, \`navigation.group.routeId\` has the highest priority when targeting an existing menu group. If \`routeId\` is present, applyBlueprint ignores \`title\`, \`icon\`, \`tooltip\`, and \`hideInMenu\` on \`navigation.group\`; applyBlueprint create mode does not mutate existing group metadata, so callers should use \`updateMenu\` separately when that is required. When \`routeId\` is omitted and \`navigation.group.title\` is provided, applyBlueprint reuses one existing same-title group when it is unique, creates a new group when none exists, and rejects ambiguous multi-match cases. Metadata such as \`icon\`, \`tooltip\`, and \`hideInMenu\` is used only when a new group is created and is ignored when an existing group is reused. \`replace\` uses \`target.pageSchemaUid\`, updates only the explicit page-level fields provided in \`page\`, maps blueprint tabs to existing route-backed tab slots by index, rewrites each slot in order, removes trailing old tabs, and appends extra new tabs when needed. Tab and block keys are optional in the public blueprint; omit them unless custom layout or cross-block targeting needs a stable in-document identifier. \`layout\` is only allowed on tabs and inline popup documents; blocks themselves do not accept a \`layout\` property. Public applyBlueprint blocks do not support generic \`form\`; use \`editForm\` or \`createForm\`. AI employee actions use \`type: "aiEmployee"\` plus public \`settings.username\`, \`workContext\`, \`tasks\`, \`auto\`, and \`style\`; work context may target \`self\` or a same-blueprint block key and is persisted as real Flow Model \`uid\` values. For JS blocks/fields/actions, \`script\` is a non-empty string asset key into \`assets.scripts\`; put inline JS in \`settings.code\` and \`settings.version\`. Direct \`table\` / \`list\` / \`gridCard\` / \`calendar\` / \`kanban\` blocks may omit \`defaultFilter\`; the backend generates one from live metadata with up to 4 scalar/filterable fields. Explicit values must contain at least the smaller of 3 and the collection eligible-field count, and values with more than 4 fields are truncated before persistence. A valid explicit or generated block-level value backfills the default \`filter\` action \`settings.defaultFilter\`; explicit filter-action \`settings.defaultFilter\` still wins. ${TREE_TABLE_RECORD_ACTION_DEFAULTS_NOTE} ${APPLY_BLUEPRINT_TREE_TABLE_TITLE_FIELD_NOTE} Inline popup documents may set \`popup.tryTemplate=true\` to ask the backend for the best compatible popup template before falling back to local popup content. Inline popup documents may also combine \`popup.tryTemplate\` with \`popup.saveAsTemplate={ name, description, local? }\`: a hit binds the matched template immediately and lets later inline popups in the same blueprint reuse that final bound template through \`popup.template={ local, mode }\`, while a miss requires explicit local \`popup.blocks\` so the fallback popup can be saved and reused. Custom \`edit\` popups that provide \`popup.blocks\` must include exactly one \`editForm\` block; that \`editForm\` may omit \`resource\` and then inherits the opener's current-record context. When layout is omitted, applyBlueprint auto-generates a simple top-to-bottom layout. When a \`replace\` run expands a page to multiple tabs while the current page still has \`enableTabs=false\`, callers must set \`page.enableTabs=true\` explicitly. The response hides execution internals and returns only the resolved page target and final surface readback.`
+      `Accepts one simplified JSON page blueprint and compiles it to internal flow-surface operations. The public blueprint describes page structure (\`create\` or \`replace\`, page metadata, ordered tabs, blocks, fields, actions, inline popups, optional reusable assets) and optional top-level \`reaction.items[]\` for whole-page interaction authoring. Each reaction item targets an explicit local key / bind key produced by the same blueprint run. Only explicitly listed reaction items are written. \`rules: []\` clears the targeted slot. Repeating the same \`(type, target)\` reaction slot in one blueprint is invalid. In \`replace\`, reaction targets always bind to the newly produced blueprint result, not historical nodes from the previous page version; if a slot must exist in the resulting surface, include it explicitly instead of relying on omission. Localized reaction edits on an existing surface should use \`getReactionMeta\` + \`set*Rules\` instead of applying a whole page blueprint again. The request body is that page-document JSON object itself and must not be JSON-stringified. Wrong: \`{ "requestBody": "{\\"version\\":\\"1\\"}" }\`. Internal planning details stay hidden. In \`create\`, \`navigation.layoutUid\` optionally scopes menu group reuse, duplicate page identity checks, and newly created routes to an enabled UI layout such as \`admin-layout-model\` or \`mobile-layout-model\`; when the target layout type is mobile, applyBlueprint ignores \`navigation.group\` and creates a root-level mobile tab page. When \`layoutUid\` is omitted, routes keep the existing admin/default inheritance behavior. In non-mobile \`create\`, \`navigation.group.routeId\` has the highest priority when targeting an existing menu group. If \`routeId\` is present, applyBlueprint ignores \`title\`, \`icon\`, \`tooltip\`, and \`hideInMenu\` on \`navigation.group\`; applyBlueprint create mode does not mutate existing group metadata, so callers should use \`updateMenu\` separately when that is required. When \`routeId\` is omitted and \`navigation.group.title\` is provided, applyBlueprint reuses one existing same-title group in the target layout when it is unique, creates a new group when none exists, and rejects ambiguous multi-match cases. Metadata such as \`icon\`, \`tooltip\`, and \`hideInMenu\` is used only when a new group is created and is ignored when an existing group is reused. \`replace\` uses \`target.pageSchemaUid\`, updates only the explicit page-level fields provided in \`page\`, maps blueprint tabs to existing route-backed tab slots by index, rewrites each slot in order, removes trailing old tabs, and appends extra new tabs when needed. Tab and block keys are optional in the public blueprint; omit them unless custom layout or cross-block targeting needs a stable in-document identifier. \`layout\` is only allowed on tabs and inline popup documents; blocks themselves do not accept a \`layout\` property. Public applyBlueprint blocks do not support generic \`form\`; use \`editForm\` or \`createForm\`. AI employee actions use \`type: "aiEmployee"\` plus public \`settings.username\`, \`workContext\`, \`tasks\`, \`auto\`, and \`style\`; work context may target \`self\` or a same-blueprint block key and is persisted as real Flow Model \`uid\` values. For JS blocks/fields/actions, \`script\` is a non-empty string asset key into \`assets.scripts\`; put inline JS in \`settings.code\` and \`settings.version\`. Direct \`table\` / \`list\` / \`gridCard\` / \`calendar\` / \`kanban\` blocks may omit \`defaultFilter\`; the backend generates one from live metadata with up to 4 scalar/filterable fields. Explicit values must contain at least the smaller of 3 and the collection eligible-field count, and values with more than 4 fields are truncated before persistence. A valid explicit or generated block-level value backfills the default \`filter\` action \`settings.defaultFilter\`; explicit filter-action \`settings.defaultFilter\` still wins. ${TREE_TABLE_RECORD_ACTION_DEFAULTS_NOTE} ${APPLY_BLUEPRINT_TREE_TABLE_TITLE_FIELD_NOTE} Inline popup documents may set \`popup.tryTemplate=true\` to ask the backend for the best compatible popup template before falling back to local popup content. Inline popup documents may also combine \`popup.tryTemplate\` with \`popup.saveAsTemplate={ name, description, local? }\`: a hit binds the matched template immediately and lets later inline popups in the same blueprint reuse that final bound template through \`popup.template={ local, mode }\`, while a miss requires explicit local \`popup.blocks\` so the fallback popup can be saved and reused. Custom \`edit\` popups that provide \`popup.blocks\` must include exactly one \`editForm\` block; that \`editForm\` may omit \`resource\` and then inherits the opener's current-record context. When layout is omitted, applyBlueprint auto-generates a simple top-to-bottom layout. When a \`replace\` run expands a page to multiple tabs while the current page still has \`enableTabs=false\`, callers must set \`page.enableTabs=true\` explicitly. The response hides execution internals and returns only the resolved page target and final surface readback.`
     ),
     requestBody: {
       required: true,
@@ -641,7 +654,7 @@ const actionDocs = {
     tags: [FLOW_SURFACES_TAG],
     summary: "Apply an approval blueprint to initiator, approver, or task-card surfaces",
     description: valuesCompatibilityNote(
-      "Builds workflow-approval configuration surfaces through the existing flowSurfaces orchestration layer instead of a separate approval resource. This is the preferred whole-surface bootstrap / replace entry for approval initiator, approver, and task-card UIs. Unlike route-backed `applyBlueprint`, this action targets approval-bound FlowModel roots stored on approval workflow trigger config (`workflow.config.approvalUid` / `workflow.config.taskCardUid`) or approval node config (`node.config.approvalUid` / `node.config.taskCardUid`). The backend creates or reuses the correct approval root automatically, rewrites the binding uid, applies a `replace` blueprint to that root, and reconciles approval runtime config derived from approval actions such as withdraw / approve / reject / return / delegate / add-assignee. `surface='initiator'` requires `workflowId` and writes page-like `blocks + layout` into `TriggerChildPageModel -> TriggerChildPageTabModel -> TriggerBlockGridModel`. `surface='approver'` requires `nodeId` and writes page-like `blocks + layout` into `ApprovalChildPageModel -> ApprovalChildPageTabModel -> ApprovalBlockGridModel`. Page-like `blocks[]` may either declare a concrete `type` or reuse a saved block template through `template: { uid, mode }`. `surface='taskCard'` requires exactly one of `workflowId` or `nodeId` and writes `fields + layout` into `ApplyTaskCardDetailsModel` or `ApprovalTaskCardDetailsModel`. This v1 action does not cover legacy schema-config wiring; it focuses on approval FlowModel construction, binding persistence, and approval runtime-config synchronization. When `layout` is omitted, the backend generates a simple top-to-bottom layout for the resulting blocks or fields."
+      "Builds workflow-approval configuration surfaces through the existing flowSurfaces orchestration layer instead of a separate approval resource. This is the preferred whole-surface bootstrap / replace entry for approval initiator, approver, and task-card UIs. Unlike route-backed `applyBlueprint`, this action targets approval-bound FlowModel roots stored on approval workflow trigger config (`workflow.config.approvalUid` / `workflow.config.taskCardUid`) or approval node config (`node.config.approvalUid` / `node.config.taskCardUid`). The backend creates or reuses the correct approval root automatically, rewrites the binding uid, applies a `replace` blueprint to that root, and reconciles approval runtime config derived from approval actions such as withdraw / approve / reject / return / delegate / add-assignee. `surface='initiator'` requires `workflowId` and writes page-like `blocks + layout` into `TriggerChildPageModel -> TriggerChildPageTabModel -> TriggerBlockGridModel`. `approvalInitiator` creates `approvalSubmit` by default; do not include `approvalSubmit` in `blocks[].actions`, otherwise authoring validation returns aggregate `errors[]` and the same write must be retried after removing it. `surface='approver'` requires `nodeId` and writes page-like `blocks + layout` into `ApprovalChildPageModel -> ApprovalChildPageTabModel -> ApprovalBlockGridModel`. Page-like `blocks[]` may declare approval-specific block types, fixed generic block types (`markdown`, `jsBlock`), or reuse a saved block template through `template: { uid, mode }`. `surface='taskCard'` requires exactly one of `workflowId` or `nodeId` and writes `fields + layout` into `ApplyTaskCardDetailsModel` or `ApprovalTaskCardDetailsModel`. This v1 action does not cover legacy schema-config wiring; it focuses on approval FlowModel construction, binding persistence, and approval runtime-config synchronization. When `layout` is omitted, the backend generates a simple top-to-bottom layout for the resulting blocks or fields."
     ),
     requestBody: {
       required: true,
@@ -796,7 +809,7 @@ const actionDocs = {
     tags: [FLOW_SURFACES_TAG],
     summary: "Create a group menu or a bindable V2 menu item",
     description: valuesCompatibilityNote(
-      'Creates a FlowSurfaces menu node. `type="group"` creates a menu group. `type="item"` creates a menu item that can be bound to a modern page (v2), and automatically fills in the flowPage route, the default hidden tab route, and the RootPageModel anchor.'
+      'Creates a FlowSurfaces menu node. `type="group"` creates a menu group. `type="item"` creates a menu item that can be bound to a modern page (v2), and automatically fills in the flowPage route, the default hidden tab route, and the RootPageModel anchor. Optional `layoutUid` scopes the route to an enabled UI layout; omitted values keep the existing parent/default admin layout inheritance.'
     ),
     requestBody: requestBody("FlowSurfaceCreateMenuRequest", import_flow_surfaces.flowSurfaceExamples.createMenu),
     responses: responses("FlowSurfaceCreateMenuResult")
@@ -814,7 +827,7 @@ const actionDocs = {
     tags: [FLOW_SURFACES_TAG],
     summary: "Initialize a modern page for an existing bindable menu item",
     description: valuesCompatibilityNote(
-      "Initializes a modern page (v2) for an existing bindable menu item through `menuRouteId` first, and fills in the default BlockGridModel. In compatibility mode, if `menuRouteId` is omitted, the old behavior still applies and a top-level menu plus page will be created automatically. Before initialization, do not call page/tab lifecycle actions such as `addTab`, `updateTab`, `moveTab`, `removeTab`, or `destroyPage`."
+      "Initializes a modern page (v2) for an existing bindable menu item through `menuRouteId` first, and fills in the default BlockGridModel. Optional `layoutUid` asserts that the existing menu route belongs to the target UI layout; omitted values keep the existing parent/default admin layout inheritance. In compatibility mode, if `menuRouteId` is omitted, the old behavior still applies and a top-level menu plus page will be created automatically. Before initialization, do not call page/tab lifecycle actions such as `addTab`, `updateTab`, `moveTab`, `removeTab`, or `destroyPage`."
     ),
     requestBody: requestBody("FlowSurfaceCreatePageRequest", import_flow_surfaces.flowSurfaceExamples.createPage),
     responses: responses("FlowSurfaceCreatePageResult")
@@ -1345,6 +1358,149 @@ const schemas = {
     },
     additionalProperties: false
   },
+  FlowSurfaceExportBlueprintUnsupportedPolicy: {
+    type: "string",
+    enum: ["error", "warn"],
+    description: "`error` rejects visible nodes the v1 mapper cannot express. `warn` skips them and reports warnings/unsupported items."
+  },
+  FlowSurfaceExportBlueprintUnsupportedItem: {
+    type: "object",
+    required: ["kind", "path", "reasonCode", "manualAction"],
+    properties: {
+      kind: {
+        type: "string",
+        enum: ["page", "tab", "block", "field", "action", "recordAction", "reaction", "layout", "popup"]
+      },
+      use: {
+        type: "string",
+        example: "UnknownModel"
+      },
+      type: {
+        type: "string",
+        example: "unknown"
+      },
+      path: {
+        type: "string",
+        example: "$.tabs[0].blocks[2]"
+      },
+      reasonCode: {
+        type: "string",
+        example: "unsupported-node"
+      },
+      manualAction: {
+        type: "string",
+        example: "Recreate this block manually or add mapper support."
+      }
+    },
+    additionalProperties: false
+  },
+  FlowSurfaceExportBlueprintTarget: {
+    oneOf: [
+      {
+        type: "object",
+        required: ["uid"],
+        properties: {
+          uid: { type: "string" }
+        },
+        additionalProperties: false
+      },
+      {
+        type: "object",
+        required: ["pageSchemaUid"],
+        properties: {
+          pageSchemaUid: { type: "string" }
+        },
+        additionalProperties: false
+      },
+      {
+        type: "object",
+        required: ["tabSchemaUid"],
+        properties: {
+          tabSchemaUid: { type: "string" }
+        },
+        additionalProperties: false
+      },
+      {
+        type: "object",
+        required: ["routeId"],
+        properties: {
+          routeId: { type: "string" }
+        },
+        additionalProperties: false
+      }
+    ],
+    description: "Exactly one root locator. v1 accepts pageSchemaUid, routeId, or a uid that resolves to the root page. tabSchemaUid and non-root uid targets return HTTP 400."
+  },
+  FlowSurfaceExportBlueprintRequest: {
+    type: "object",
+    required: ["target"],
+    properties: {
+      target: ref("FlowSurfaceExportBlueprintTarget"),
+      options: {
+        type: "object",
+        properties: {
+          unsupported: ref("FlowSurfaceExportBlueprintUnsupportedPolicy")
+        },
+        additionalProperties: false
+      }
+    },
+    additionalProperties: false
+  },
+  FlowSurfaceExportBlueprintSource: {
+    type: "object",
+    required: ["target"],
+    properties: {
+      target: ref("FlowSurfaceApplyBlueprintTarget"),
+      pageTitle: {
+        type: "string"
+      }
+    },
+    additionalProperties: false
+  },
+  FlowSurfaceExportBlueprintDocument: {
+    type: "object",
+    required: ["version", "mode", "target", "tabs", "assets"],
+    description: "Prepared v1 applyBlueprint document in replace mode. It intentionally omits navigation and retains target.pageSchemaUid for same-instance replace.",
+    properties: {
+      version: {
+        type: "string",
+        enum: ["1"]
+      },
+      mode: {
+        type: "string",
+        enum: ["replace"]
+      },
+      target: ref("FlowSurfaceApplyBlueprintTarget"),
+      page: ref("FlowSurfaceApplyBlueprintPage"),
+      tabs: {
+        type: "array",
+        minItems: 1,
+        items: ref("FlowSurfaceApplyBlueprintTab")
+      },
+      assets: ref("FlowSurfaceApplyBlueprintAssets"),
+      reaction: ref("FlowSurfaceApplyBlueprintReaction")
+    },
+    additionalProperties: false
+  },
+  FlowSurfaceExportBlueprintResponse: {
+    type: "object",
+    required: ["document", "source", "warnings", "unsupported"],
+    properties: {
+      document: ref("FlowSurfaceExportBlueprintDocument"),
+      source: ref("FlowSurfaceExportBlueprintSource"),
+      warnings: {
+        type: "array",
+        items: {
+          type: "string"
+        }
+      },
+      unsupported: {
+        type: "array",
+        items: ref("FlowSurfaceExportBlueprintUnsupportedItem")
+      }
+    },
+    additionalProperties: false
+  },
   FlowSurfaceMutateWriteTarget: {
     type: "object",
     required: ["uid"],
@@ -1486,6 +1642,7 @@ const schemas = {
         }
       },
       example: {},
+      default: {},
       supportsFlowContext: {
         type: "boolean"
       }
@@ -4010,11 +4167,11 @@ const schemas = {
     properties: {
       routeId: {
         ...STRING_OR_INTEGER_SCHEMA,
-        description: "Preferred existing menu-group route id. When present, routeId has the highest priority and title/icon/tooltip/hideInMenu are ignored. applyBlueprint create mode does not mutate existing group metadata; use low-level updateMenu separately when needed."
+        description: "Preferred existing menu-group route id for non-mobile create mode. When present, routeId has the highest priority and title/icon/tooltip/hideInMenu are ignored. Ignored when navigation.layoutUid targets a mobile layout because mobile pages are created as root tabs. applyBlueprint create mode does not mutate existing group metadata; use low-level updateMenu separately when needed."
       },
       title: {
         type: "string",
-        description: "Group title for create mode. When `routeId` is omitted, applyBlueprint reuses a same-title group if the match is unique, creates one when no group exists, and rejects ambiguous multi-match cases. If an existing group is reused, group metadata is ignored; use low-level updateMenu to change existing group metadata."
+        description: "Group title for non-mobile create mode. When `routeId` is omitted, applyBlueprint reuses a same-title group if the match is unique, creates one when no group exists, and rejects ambiguous multi-match cases. Ignored when navigation.layoutUid targets a mobile layout because mobile pages are created as root tabs. If an existing group is reused, group metadata is ignored; use low-level updateMenu to change existing group metadata."
       },
       icon: {
         type: "string",
@@ -4034,6 +4191,10 @@ const schemas = {
   FlowSurfaceApplyBlueprintNavigation: {
     type: "object",
     properties: {
+      layoutUid: {
+        type: "string",
+        description: "Optional enabled UI layout uid that scopes create-mode route lookup and newly created routes. Use `mobile-layout-model` for mobile pages; mobile layouts ignore navigation.group and create a root-level tab page. When omitted, the server preserves the existing parent/default admin layout behavior."
+      },
       group: ref("FlowSurfaceApplyBlueprintNavigationGroup"),
       item: {
         type: "object",
@@ -4249,7 +4410,7 @@ const schemas = {
   FlowSurfaceApplyBlueprintRequest: {
     type: "object",
     required: ["mode", "tabs"],
-    description: `Simplified page-structure request object for applyBlueprint. \`version\` may be omitted and defaults to '1'. Runtime validation enforces mode-specific rules: create does not accept target, while replace requires target.pageSchemaUid and does not use navigation. For JS blocks/fields/actions, \`script\` is a non-empty string asset key into \`assets.scripts\`, and referenced script assets must provide non-empty \`code\`; put inline JS in \`settings.code\` and \`settings.version\`. ${TREE_TABLE_RECORD_ACTION_DEFAULTS_NOTE} ${APPLY_BLUEPRINT_TREE_TABLE_TITLE_FIELD_NOTE} \`defaults.collections\` may provide main data-source collection-level fieldGroups, popup metadata with required \`name\` and \`description\`, and formBehavior for generated default add/edit popup forms; use \`defaults.dataSources.<dataSourceKey>.collections\` for external data sources. v1 does not support \`defaults.blocks\`.`,
+    description: `Simplified page-structure request object for applyBlueprint. \`version\` may be omitted and defaults to '1'. Runtime validation enforces mode-specific rules: create does not accept target, while replace requires target.pageSchemaUid and does not use navigation. In create mode, \`navigation.layoutUid\` scopes menu group reuse, duplicate page identity, and newly created routes to the target layout; use \`mobile-layout-model\` for mobile pages, where \`navigation.group\` is ignored and the page is created as a root tab, and omit it for default admin behavior. For JS blocks/fields/actions, \`script\` is a non-empty string asset key into \`assets.scripts\`, and referenced script assets must provide non-empty \`code\`; put inline JS in \`settings.code\` and \`settings.version\`. ${TREE_TABLE_RECORD_ACTION_DEFAULTS_NOTE} ${APPLY_BLUEPRINT_TREE_TABLE_TITLE_FIELD_NOTE} \`defaults.collections\` may provide main data-source collection-level fieldGroups, popup metadata with required \`name\` and \`description\`, and formBehavior for generated default add/edit popup forms; use \`defaults.dataSources.<dataSourceKey>.collections\` for external data sources. v1 does not support \`defaults.blocks\`.`,
     properties: {
       version: {
         type: "string",
@@ -4336,7 +4497,7 @@ const schemas = {
   FlowSurfaceApplyApprovalBlueprintRequest: {
     type: "object",
     required: ["surface"],
-    description: "Simplified approval-surface blueprint request for workflow approval UIs. This is the preferred bootstrap / replace route for approval initiator, approver, and task-card surfaces. `version` may be omitted and defaults to '1'. `mode` may be omitted and defaults to `replace`; v1 only supports `replace`. Runtime validation enforces binding rules: `initiator` requires `workflowId`, `approver` requires `nodeId`, and `taskCard` requires exactly one of `workflowId` or `nodeId`. Page-like surfaces (`initiator`, `approver`) accept `blocks + layout`; each block may declare `type` directly or reuse `template: { uid, mode }`. `taskCard` accepts `fields + layout`. This route does not perform schema wiring, but it does persist binding fields and reconcile approval runtime config from approval actions.",
+    description: "Simplified approval-surface blueprint request for workflow approval UIs. This is the preferred bootstrap / replace route for approval initiator, approver, and task-card surfaces. `version` may be omitted and defaults to '1'. `mode` may be omitted and defaults to `replace`; v1 only supports `replace`. Runtime validation enforces binding rules: `initiator` requires `workflowId`, `approver` requires `nodeId`, and `taskCard` requires exactly one of `workflowId` or `nodeId`. Page-like surfaces (`initiator`, `approver`) accept `blocks + layout`; each block may declare approval-specific types, fixed generic types (`markdown`, `jsBlock`), or reuse `template: { uid, mode }`. `approvalInitiator` creates `approvalSubmit` by default, so callers should only add optional initiator actions such as `approvalSaveDraft` or `approvalWithdraw`. `taskCard` accepts `fields + layout`. This route does not perform schema wiring, but it does persist binding fields and reconcile approval runtime config from approval actions. Authoring validation failures use the same aggregate `errors[]` retry contract as `applyBlueprint`.",
     properties: {
       version: {
         type: "string",
@@ -4421,6 +4582,10 @@ const schemas = {
     type: "object",
     required: ["title"],
     properties: {
+      layoutUid: {
+        type: "string",
+        description: "Optional enabled UI layout uid for the created menu route, for example `mobile-layout-model`. When omitted, the route inherits its parent layout or the default admin layout."
+      },
       title: {
         type: "string"
       },
@@ -4517,6 +4682,10 @@ const schemas = {
   FlowSurfaceCreatePageRequest: {
     type: "object",
     properties: {
+      layoutUid: {
+        type: "string",
+        description: "Optional enabled UI layout uid. With `menuRouteId`, the existing route must already belong to this layout. Without `menuRouteId`, the compatibility create-menu fallback creates the route in this layout."
+      },
       menuRouteId: STRING_OR_INTEGER_SCHEMA,
       pageSchemaUid: {
         type: "string"