@pylonts/dsl 1.1.4 → 1.1.6

package/src/dto.ts

@@ -1,7 +1,8 @@
 import { BaseField, CollectionSchemaBase, Field, Operator, SchemaBase } from './dsl.js';
 import { TableSchema } from './db.js';
 import type { ImportBase } from './import-base.js';
-import { toCamelCase } from './utils.js';
+import type { ThirdMethodSchema } from './third-service.js';
+import { toCamelCase } from '@pylonts/core';
 
 // Interface (DTO) field definitions.
 // Naming convention: all DTO types and builders use the Dto prefix.
@@ -227,22 +228,37 @@ export function buildPk(name: string, fields: Record<string, DtoField>, descript
   for (const field of Object.values(message.fields)) {
     if (field.optional !== undefined) continue;
     const f = field.field as Field;
-    const table = f.schema as TableSchema | undefined;
+    const table = f.schema?.type === 'table' ? (f.schema as TableSchema) : undefined;
     field.optional = table !== undefined && table.isPk(f) ? false : true;
   }
   return message;
 }
 
-/** Pick columns from a built table and wrap them as DTO fields (aligned with dto.from). */
-export function from(table: TableSchema, fields: Field[]): Record<string, DtoField> {
+/** Field-collection source a DTO can project from: a DB table or a third-party method message. */
+export type DtoFieldSource = TableSchema | ThirdMethodSchema;
+
+// Type guard instead of a plain discriminant check: TableSchema.type is declared
+// as a class property, so TS widens it to string and cannot narrow the union.
+function isThirdMethod(source: DtoFieldSource): source is ThirdMethodSchema {
+  return source.type === 'thirdMethod';
+}
+
+function ownsField(source: DtoFieldSource, field: Field): boolean {
+  if (isThirdMethod(source)) return Object.values(source.fields).includes(field);
+  return Object.values(source.columns).includes(field);
+}
+
+/** Project fields from a field-collection source (table or third-party method
+ *  message) and wrap them as DTO fields (aligned with dto.from). */
+export function from(source: DtoFieldSource, fields: Field[]): Record<string, DtoField> {
   const out: Record<string, DtoField> = {};
   for (const field of fields) {
-    if (field.schema !== table) {
-      throw new Error(`dto.from(${table.name}): field ${field.name} does not belong to this table`);
+    if (!ownsField(source, field)) {
+      throw new Error(`dto.from(${source.name}): field ${field.name} does not belong to this ${source.type}`);
     }
-    // DTO field name is camelCase (mer_id → merId); the underlying field.name
-    // stays snake_case (DB column).
-    out[toCamelCase(field.name)] = dtoField(field);
+    // DB columns map to camelCase interface names (mer_id → merId); wire-format
+    // names are protocol names themselves and stay untouched.
+    out[isThirdMethod(source) ? field.name : toCamelCase(field.name)] = dtoField(field);
   }
   return out;
 }

package/src/endpoint.ts

@@ -0,0 +1,18 @@
+import { SchemaBase } from './dsl.js';
+import type { DtoMessage } from './dto.js';
+
+/** Shared API call signature: one request DTO in, one response shape out.
+ *  Referenced by both backend controller methods and frontend page providers —
+ *  both sides must use the exact same instance, so drift is impossible. */
+export interface EndpointSchema extends SchemaBase {
+  type: 'endpoint';
+  args: DtoMessage;
+  results: DtoMessage | number | boolean | string;
+}
+
+export function defineEndpoint(
+  name: string,
+  options: { args: DtoMessage; results: DtoMessage | number | boolean | string; description?: string },
+): EndpointSchema {
+  return { type: 'endpoint', name, args: options.args, results: options.results, description: options.description };
+}

package/src/event.ts

@@ -1,12 +1,12 @@
-import type { CollectionSchemaBase } from './dsl.js';
-import type { DtoField } from './dto.js';
-
-/** Data carried by a component event (e.g. e.detail from a Tab onChange). */
-export interface EventDataSchema extends CollectionSchemaBase {
-  type: 'event';
-  fields: Record<string, DtoField>;
-}
-
-export function defineEventData(name: string, fields: Record<string, DtoField>): EventDataSchema {
-  return { name, type: 'event', fields };
-}
+import type { CollectionSchemaBase } from './dsl.js';
+import type { DtoField } from './dto.js';
+
+/** Data carried by a component event (e.g. e.detail from a Tab onChange). */
+export interface EventDataSchema extends CollectionSchemaBase {
+  type: 'event';
+  fields: Record<string, DtoField>;
+}
+
+export function defineEventData(name: string, fields: Record<string, DtoField>): EventDataSchema {
+  return { name, type: 'event', fields };
+}

package/src/exception.ts

@@ -0,0 +1,28 @@
+import type { SchemaBase } from './dsl.js';
+import type { ImportBase } from './import-base.js';
+
+// Exception declarations (logic-flatten-spec §5.3): each method declares the
+// exceptions it throws, with retryability. The runtime class is referenced by
+// import location — never loaded by the DSL.
+
+/** Describes an exception a method can throw. */
+export interface ExceptionSchema extends SchemaBase, Omit<ImportBase, 'type'> {
+  type: 'exception';
+  /** Whether the caller may safely retry after catching this exception. */
+  retryable: boolean;
+}
+
+export function defineException(options: {
+  name: string;
+  from: string;
+  retryable: boolean;
+  description?: string;
+}): ExceptionSchema {
+  return {
+    type: 'exception',
+    name: options.name,
+    from: options.from,
+    retryable: options.retryable,
+    description: options.description,
+  };
+}

package/src/field-rule.ts

@@ -0,0 +1,47 @@
+import type { SchemaBase } from './dsl.js';
+
+// Field rules: the third semantic dimension of a Field. A rule is a named
+// transformation between two ends — scale (fen↔yuan), encrypt/decrypt,
+// mask/unmask. The rule owns both ends; a binding says which field plays
+// which end. Rules are unique per semantic name (checked at definition).
+
+/** One end of a field rule (e.g. 'fen' / 'yuan', 'plain' / 'cipher', 'raw' / 'masked'). */
+export interface FieldRuleEnd {
+  /** End name — written back by defineFieldRule from the ends map key. */
+  name: string;
+  description?: string;
+}
+
+/** A semantic transformation rule between two field representations. */
+export interface FieldRuleSchema extends SchemaBase {
+  type: 'fieldRule';
+  /** Rule name — the semantic uniqueness key. */
+  name: string;
+  /** The two ends of the rule, keyed by end name. */
+  ends: Record<string, FieldRuleEnd>;
+}
+
+/** One rule per semantic name. Defining the same name twice throws. */
+const ruleRegistry = new Map<string, FieldRuleSchema>();
+
+export function defineFieldRule(options: {
+  name: string;
+  ends: Record<string, Omit<FieldRuleEnd, 'name'>>;
+  description?: string;
+}): FieldRuleSchema {
+  if (ruleRegistry.has(options.name)) {
+    throw new Error(`fieldRule '${options.name}' is already defined — one rule per semantic`);
+  }
+  const ends: Record<string, FieldRuleEnd> = {};
+  for (const key of Object.keys(options.ends)) {
+    ends[key] = { name: key, description: options.ends[key].description };
+  }
+  const rule: FieldRuleSchema = {
+    type: 'fieldRule',
+    name: options.name,
+    description: options.description,
+    ends,
+  };
+  ruleRegistry.set(options.name, rule);
+  return rule;
+}

package/src/flow.ts

@@ -1,104 +1,144 @@
-import { SchemaBase } from './dsl.js';
-
-// Flow model: nodes and edges are separate entities. A FlowNode is a plain
-// named step; a FlowEdge references its start/end node objects directly (no
-// ids). Because a node object may appear in many edges, the graph can share
-// nodes, merge branches, and form cycles (e.g. poll-and-retry loops).
-
-export interface FlowNode extends SchemaBase {
-  /** Optional sub-flow. When present, entering this node runs the sub-flow;
-   *  after the sub-flow reaches any terminal node, the outer flow continues
-   *  via this node's outgoing edges. Sub-flows nest recursively. */
-  flow?: FlowSchema;
-}
-
-export interface FlowEdge extends SchemaBase {
-  /** Trigger condition; undefined = default path (success/normal). */
-  when?: string;
-  start: FlowNode;
-  end: FlowNode;
-}
-
-export interface FlowSchema extends SchemaBase {
-  /** Entry node. */
-  start: FlowNode;
-  /** All nodes, collected from edges (deduplicated by object identity). */
-  nodes: FlowNode[];
-  /** Independent edges; a node may be start of many edges, so cycles are expressible. */
-  edges: FlowEdge[];
-}
-
-export function node(name: string, flow?: FlowSchema, description?: string): FlowNode {
-  return { name, flow, description };
-}
-
-export function edge(start: FlowNode, end: FlowNode, when?: string, description?: string): FlowEdge {
-  // Auto name for uniformity with SchemaBase; `when` stays the branch marker.
-  return { name: `${start.name}->${end.name}`, start, end, when, description };
-}
-
-export function defineFlow(
-  name: string,
-  schema: {
-    start: FlowNode;
-    edges: FlowEdge[];
-    description?: string;
-  },
-): FlowSchema {
-  const seen = new Set<FlowNode>();
-  const nodes: FlowNode[] = [];
-  for (const e of schema.edges) {
-    for (const n of [e.start, e.end]) {
-      if (!seen.has(n)) {
-        seen.add(n);
-        nodes.push(n);
-      }
-    }
-  }
-  if (!seen.has(schema.start)) {
-    seen.add(schema.start);
-    nodes.push(schema.start);
-  }
-  const flow: FlowSchema = { name, description: schema.description, start: schema.start, nodes, edges: schema.edges };
-  validate(flow);
-  return flow;
-}
-
-// Nodes that never appear as an edge start are terminals. Reverse BFS from all
-// terminals marks every node that can reach a terminal; unmarked nodes sit on
-// a path that never ends (e.g. a cycle without an exit) — reject them at
-// definition time.
-function validate(schema: FlowSchema): void {
-  const starts = new Set<FlowNode>();
-  for (const e of schema.edges) starts.add(e.start);
-
-  const reverse = new Map<FlowNode, FlowNode[]>();
-  for (const n of schema.nodes) reverse.set(n, []);
-  for (const e of schema.edges) {
-    reverse.get(e.end)!.push(e.start);
-  }
-
-  const reached = new Set<FlowNode>();
-  const queue: FlowNode[] = [];
-  for (const n of schema.nodes) {
-    if (!starts.has(n)) {
-      reached.add(n);
-      queue.push(n);
-    }
-  }
-  while (queue.length > 0) {
-    const cur = queue.shift()!;
-    for (const prev of reverse.get(cur)!) {
-      if (!reached.has(prev)) {
-        reached.add(prev);
-        queue.push(prev);
-      }
-    }
-  }
-
-  for (const n of schema.nodes) {
-    if (!reached.has(n)) {
-      throw new Error(`flow ${schema.name}: node "${n.name}" cannot reach a terminal`);
-    }
-  }
+import { SchemaBase } from './dsl.js';
+import type { MethodSchema } from './method.js';
+import type { ConvertSchema } from './convert.js';
+import type { DaoMethodSchema } from './dao.js';
+import type { ServiceMethodSchema } from './service.js';
+import type { ThirdServiceMethodSchema } from './third-service.js';
+import type { UtilsMethodSchema } from './utils.js';
+
+// Flow model: nodes and edges are separate entities. A FlowNode is a plain
+// named step; a FlowEdge references its start/end node objects directly (no
+// ids). Because a node object may appear in many edges, the graph can share
+// nodes, merge branches, and form cycles (e.g. poll-and-retry loops).
+
+/** A method a flow node can invoke: contract references, or a pure descriptor
+ *  (MethodSchema) for the period before the contract file exists. */
+export type FlowMethodRef =
+  | MethodSchema
+  | ConvertSchema
+  | DaoMethodSchema
+  | ServiceMethodSchema
+  | ThirdServiceMethodSchema
+  | UtilsMethodSchema;
+
+export interface FlowNode extends SchemaBase {
+  /** Optional sub-flow. When present, entering this node runs the sub-flow;
+   *  after the sub-flow reaches any terminal node, the outer flow continues
+   *  via this node's outgoing edges. Sub-flows nest recursively. */
+  flow?: FlowSchema;
+  /** Methods this node invokes — contract references or pure descriptors
+   *  (rendered under the node label). */
+  methods?: FlowMethodRef[];
+}
+
+export interface FlowEdge extends SchemaBase {
+  /** Trigger condition; undefined = default path (success/normal). */
+  when?: string;
+  start: FlowNode;
+  end: FlowNode;
+  /** Exception path (rendered dashed); defaults to normal. */
+  exception?: boolean;
+}
+
+export interface FlowSchema extends SchemaBase {
+  /** Entry node. */
+  start: FlowNode;
+  /** All nodes, collected from edges (deduplicated by object identity). */
+  nodes: FlowNode[];
+  /** Independent edges; a node may be start of many edges, so cycles are expressible. */
+  edges: FlowEdge[];
+}
+
+export function node(
+  name: string,
+  options: { flow?: FlowSchema; description?: string; methods?: FlowMethodRef[] } = {},
+): FlowNode {
+  return {
+    name,
+    flow: options.flow,
+    description: options.description,
+    methods: options.methods,
+  };
+}
+
+export function edge(
+  start: FlowNode,
+  end: FlowNode,
+  options: { when?: string; description?: string; exception?: boolean } = {},
+): FlowEdge {
+  // Auto name for uniformity with SchemaBase; `when` stays the branch marker.
+  return {
+    name: `${start.name}->${end.name}`,
+    start,
+    end,
+    when: options.when,
+    description: options.description,
+    exception: options.exception,
+  };
+}
+
+export function defineFlow(
+  name: string,
+  schema: {
+    start: FlowNode;
+    edges: FlowEdge[];
+    description?: string;
+  },
+): FlowSchema {
+  const seen = new Set<FlowNode>();
+  const nodes: FlowNode[] = [];
+  for (const e of schema.edges) {
+    for (const n of [e.start, e.end]) {
+      if (!seen.has(n)) {
+        seen.add(n);
+        nodes.push(n);
+      }
+    }
+  }
+  if (!seen.has(schema.start)) {
+    seen.add(schema.start);
+    nodes.push(schema.start);
+  }
+  const flow: FlowSchema = { name, description: schema.description, start: schema.start, nodes, edges: schema.edges };
+  validate(flow);
+  return flow;
+}
+
+// Nodes that never appear as an edge start are terminals. Reverse BFS from all
+// terminals marks every node that can reach a terminal; unmarked nodes sit on
+// a path that never ends (e.g. a cycle without an exit) — reject them at
+// definition time.
+function validate(schema: FlowSchema): void {
+  const starts = new Set<FlowNode>();
+  for (const e of schema.edges) starts.add(e.start);
+
+  const reverse = new Map<FlowNode, FlowNode[]>();
+  for (const n of schema.nodes) reverse.set(n, []);
+  for (const e of schema.edges) {
+    reverse.get(e.end)!.push(e.start);
+  }
+
+  const reached = new Set<FlowNode>();
+  const queue: FlowNode[] = [];
+  for (const n of schema.nodes) {
+    if (!starts.has(n)) {
+      reached.add(n);
+      queue.push(n);
+    }
+  }
+  while (queue.length > 0) {
+    const cur = queue.shift()!;
+    for (const prev of reverse.get(cur)!) {
+      if (!reached.has(prev)) {
+        reached.add(prev);
+        queue.push(prev);
+      }
+    }
+  }
+
+  for (const n of schema.nodes) {
+    if (!reached.has(n)) {
+      throw new Error(`flow ${schema.name}: node "${n.name}" cannot reach a terminal`);
+    }
+  }
 }

package/src/index.ts

@@ -22,7 +22,12 @@ export * from './convert.js';
 export * from './ref.js';
 export * from './route.js';
 export * from './service.js';
+export * from './controller.js';
+export * from './endpoint.js';
 export * from './dao.js';
+export * from './third-service.js';
+export * from './field-rule.js';
+export * from './exception.js';
 export * from './page.js';
 export * from './curd.js';
 export * from './page-flow.js';
@@ -30,4 +35,9 @@ export * from './provider.js';
 export * from './page-def.js';
 export * from './mermaid-driver.js';
 export * from './navigation.js';
-export * from './popup.js';
+export * from './popup.js';
+export * from './method.js';
+
+// Naming conversions moved to @pylonts/core; re-exported for compatibility
+// with packages that import them from @pylonts/dsl.
+export { toCamelCase, toPascalCase, toKebabCase } from '@pylonts/core';

package/src/mermaid-driver.ts

@@ -1,4 +1,5 @@
 import { FlowEdge, FlowNode, FlowSchema } from './flow.js';
+import type { FlowMethodRef } from './flow.js';
 import { Page } from './page.js';
 import { PageEdge, PageFlow } from './page-flow.js';
 
@@ -24,14 +25,19 @@ export function renderFlowMermaid(schema: FlowSchema): string {
 
 function renderFlow(schema: FlowSchema, prefix: string, lines: string[], ids: Map<FlowNode, string>): void {
   schema.nodes.forEach((n, i) => ids.set(n, `${prefix}${i}`));
+  const outgoing = new Map<FlowNode, FlowEdge[]>();
+  for (const n of schema.nodes) outgoing.set(n, []);
+  for (const e of schema.edges) outgoing.get(e.start)!.push(e);
+
   for (const n of schema.nodes) {
     const id = ids.get(n)!;
     if (n.flow) {
-      lines.push(`    subgraph ${id}["${escapeLabel(n.name)}"]`);
+      lines.push(`    subgraph ${id}["${escapeLabel(renderNodeLabel(n))}"]`);
       renderFlow(n.flow, `${id}_`, lines, ids);
       lines.push('    end');
     } else {
-      lines.push(`    ${id}["${escapeLabel(n.name)}"]`);
+      const shape = renderShape(n, schema, outgoing.get(n)!);
+      lines.push(`    ${id}${shape.open}${escapeLabel(renderNodeLabel(n))}${shape.close}`);
     }
   }
   for (const e of schema.edges) {
@@ -39,9 +45,31 @@ function renderFlow(schema: FlowSchema, prefix: string, lines: string[], ids: Ma
   }
 }
 
+/** Node label: name on the first line, method references on the second. */
+function renderNodeLabel(n: FlowNode): string {
+  if (n.methods === undefined || n.methods.length === 0) return n.name;
+  return `${n.name}\n${n.methods.map((m: FlowMethodRef) => renderMethodRef(m)).join(' | ')}`;
+}
+
+/** Display form: owner.name for descriptors and container methods, bare name for converts. */
+function renderMethodRef(m: FlowMethodRef): string {
+  if ('owner' in m) return `${m.owner}.${m.name}`;
+  if ('schema' in m) return `${m.schema.name}.${m.name}`;
+  return m.name;
+}
+
+/** Shape derived from topology: start and terminals rounded, branching nodes diamond, else rect.
+ *  Exception edges do not count as branches. */
+function renderShape(n: FlowNode, schema: FlowSchema, outgoing: FlowEdge[]): { open: string; close: string } {
+  if (n === schema.start || outgoing.length === 0) return { open: '(["', close: '"])' };
+  const normal = outgoing.filter((e) => e.exception !== true).length;
+  return normal >= 2 ? { open: '{"', close: '"}' } : { open: '["', close: '"]' };
+}
+
 function renderEdge(e: FlowEdge, ids: Map<FlowNode, string>): string {
+  const arrow = e.exception === true ? '-.->' : '-->';
   const label = e.when ? `|"${escapeLabel(e.when)}"|` : '';
-  return `    ${ids.get(e.start)} -->${label} ${ids.get(e.end)}`;
+  return `    ${ids.get(e.start)} ${arrow}${label} ${ids.get(e.end)}`;
 }
 
 // Page-driven flow renderer: groups pages by their app into swimlane

package/src/method.ts

@@ -0,0 +1,20 @@
+import type { SchemaBase } from './dsl.js';
+
+// A pure descriptor of one method invocation (e.g. payDao.insert).
+// No args/results — the invocation stays natural language for now.
+// SequenceSchema is the ordered list of such invocations.
+
+export interface MethodSchema extends SchemaBase {
+  /** Owning schema name, e.g. 'payDao'. */
+  owner: string;
+}
+
+export type SequenceSchema = MethodSchema[];
+
+export function defineMethod(options: {
+  name: string;
+  owner: string;
+  description?: string;
+}): MethodSchema {
+  return { name: options.name, owner: options.owner, description: options.description };
+}

package/src/mock.ts

@@ -1,12 +1,12 @@
-/**
- * Pure-data mock descriptor. Stored on DTO fields, consumed by pylonts lint mock
- * or MockRegistry.resolve. No function references — serializable and gen-readable.
- *
- * @example { fn: 'abc', count: 20 }
- * @example { fn: 'amt', min: 10, max: 500 }
- * @example { fn: 'phone' }
- */
-export interface MockDescriptor {
-  fn: string;
-  [args: string]: unknown;
-}
+/**
+ * Pure-data mock descriptor. Stored on DTO fields, consumed by pylonts lint mock
+ * or MockRegistry.resolve. No function references — serializable and gen-readable.
+ *
+ * @example { fn: 'abc', count: 20 }
+ * @example { fn: 'amt', min: 10, max: 500 }
+ * @example { fn: 'phone' }
+ */
+export interface MockDescriptor {
+  fn: string;
+  [args: string]: unknown;
+}

package/src/mysql-driver.ts

@@ -1,4 +1,4 @@
-import { Field } from './dsl.js';
+import { Field, rateScale } from './dsl.js';
 import { ForeignKey, Index, TableSchema } from './db.js';
 
 // MySQL driver: converts a TableSchema into a CREATE TABLE statement.
@@ -21,6 +21,8 @@ function columnType(field: Field): string {
       return 'BIGINT';
     case 'decimal':
       return `DECIMAL(${field.precision}, ${field.scale})`;
+    case 'rate':
+      return `DECIMAL(5, ${rateScale(field.unit)})`;
     case 'boolean':
       return 'TINYINT(1)';
     case 'date':
@@ -34,6 +36,10 @@ function columnType(field: Field): string {
       return field.enum.valueType === 'integer' ? 'TINYINT' : 'VARCHAR(20)';
     case 'json':
       return 'JSON';
+    case 'array':
+    case 'object':
+      // Nested fields are wire-format only (third-party messages); table columns cannot nest.
+      throw new Error(`field ${field.name} (${field.type}): nested fields are not supported on table columns`);
   }
 }
 
@@ -43,7 +49,7 @@ function renderDefault(field: Field): string {
   // NULL, etc.) — render bare, no quotes.
   if (/^[A-Z]/.test(field.default)) return ` DEFAULT ${field.default}`;
   // Numeric columns take a bare literal, not a quoted one.
-  if (field.type === 'integer' || field.type === 'bigint' || field.type === 'decimal' || field.type === 'boolean') {
+  if (field.type === 'integer' || field.type === 'bigint' || field.type === 'decimal' || field.type === 'rate' || field.type === 'boolean') {
     return ` DEFAULT ${field.default}`;
   }
   return ` DEFAULT '${field.default}'`;

package/src/navigation.ts

@@ -1,29 +1,29 @@
-import type { RouteDataSchema } from './route.js';
-import type { ActionSchema } from './action.js';
-import { PageSchema } from './page.js';
-
-/** Navigation primitives: front-end routing actions that are not provider calls. */
-export interface NavigationAction extends ActionSchema {
-  type: 'navigation';
-  method: 'back' | 'push' | 'popup' | 'home';
-  /** Target page for push navigation. */
-  target?: PageSchema;
-  /** Route params type for push navigation. Auto-derived from target.params if omitted. */
-  params?: RouteDataSchema;
-}
-
-export const navigation = {
-  back(description?: string): NavigationAction {
-    return { name: 'back', type: 'navigation', method: 'back', description };
-  },
-  push(options: { target: PageSchema; params?: RouteDataSchema; description?: string }): NavigationAction {
-    const { target, params, description } = options;
-    return { name: 'push', type: 'navigation', method: 'push', target, params: params ?? target.params, description };
-  },
-  popup(description?: string): NavigationAction {
-    return { name: 'popup', type: 'navigation', method: 'popup', description };
-  },
-  home(description?: string): NavigationAction {
-    return { name: 'home', type: 'navigation', method: 'home', description };
-  },
+import type { RouteDataSchema } from './route.js';
+import type { ActionSchema } from './action.js';
+import { PageSchema } from './page.js';
+
+/** Navigation primitives: front-end routing actions that are not provider calls. */
+export interface NavigationAction extends ActionSchema {
+  type: 'navigation';
+  method: 'back' | 'push' | 'popup' | 'home';
+  /** Target page for push navigation. */
+  target?: PageSchema;
+  /** Route params type for push navigation. Auto-derived from target.params if omitted. */
+  params?: RouteDataSchema;
+}
+
+export const navigation = {
+  back(description?: string): NavigationAction {
+    return { name: 'back', type: 'navigation', method: 'back', description };
+  },
+  push(options: { target: PageSchema; params?: RouteDataSchema; description?: string }): NavigationAction {
+    const { target, params, description } = options;
+    return { name: 'push', type: 'navigation', method: 'push', target, params: params ?? target.params, description };
+  },
+  popup(description?: string): NavigationAction {
+    return { name: 'popup', type: 'navigation', method: 'popup', description };
+  },
+  home(description?: string): NavigationAction {
+    return { name: 'home', type: 'navigation', method: 'home', description };
+  },
 };