circuit-json 0.0.521 → 0.0.523

package/dist/index.mjs

@@ -4508,10 +4508,72 @@ var cad_cable = z199.object({
 );
 expectTypesMatch(true);
 
-// src/simulation/simulation_voltage_source.ts
+// src/cad/cad_reference_surface.ts
 import { z as z200 } from "zod";
-var wave_shape = z200.enum(["sinewave", "square", "triangle", "sawtooth"]);
-var percentage = z200.union([z200.string(), z200.number()]).transform((val) => {
+var FRAME_TOLERANCE = 1e-6;
+var unitDirection = z200.object({
+  x: z200.number().finite(),
+  y: z200.number().finite(),
+  z: z200.number().finite()
+}).refine(
+  (v) => Math.abs(Math.hypot(v.x, v.y, v.z) - 1) <= FRAME_TOLERANCE,
+  "Reference surface directions must be unit vectors"
+);
+var extent = distance.pipe(z200.number().finite().positive());
+var cad_reference_surface = z200.object({
+  type: z200.literal("cad_reference_surface"),
+  cad_reference_surface_id: z200.string().min(1),
+  source_component_id: z200.string().min(1).describe(
+    "Owning assembly part's source component ID. The part may have no CAD geometry."
+  ),
+  name: z200.string().trim().min(1).describe(
+    "Reference name, unique within the owning part, e.g. shade in STEM.shade."
+  ),
+  shape: z200.literal("rect"),
+  center: point3.refine(
+    (p) => [p.x, p.y, p.z].every(Number.isFinite),
+    "Reference surface centers must be finite"
+  ).describe(
+    "Resolved surface center in right-handed circuit-world XYZ, millimeters: +X right, +Y top, +Z above. An absolute point after assembly placement."
+  ),
+  normal: unitDirection.describe(
+    "Outward unit normal in circuit-world XYZ. Dimensionless direction; transform with the part's rotation, without translation."
+  ),
+  x_axis: unitDirection.describe(
+    "In-plane unit X direction in circuit-world XYZ, perpendicular to normal. The second tangent is normal cross x_axis, giving a right-handed frame."
+  ),
+  width: extent.optional().describe(
+    "Rectangular extent along x_axis in millimeters. Supply together with height. Omission leaves the surface's display size unspecified."
+  ),
+  height: extent.optional().describe(
+    "Rectangular extent along normal cross x_axis in millimeters. Supply together with width."
+  ),
+  subcircuit_id: z200.string().optional()
+}).superRefine((surface, ctx) => {
+  if (surface.width === void 0 !== (surface.height === void 0))
+    ctx.addIssue({
+      code: z200.ZodIssueCode.custom,
+      path: ["width"],
+      message: "Provide width and height together"
+    });
+  const { normal: n, x_axis: x } = surface;
+  if (Math.abs(n.x * x.x + n.y * x.y + n.z * x.z) > FRAME_TOLERANCE)
+    ctx.addIssue({
+      code: z200.ZodIssueCode.custom,
+      path: ["x_axis"],
+      message: "x_axis must be perpendicular to normal"
+    });
+}).describe(
+  "A named assembly mounting surface with a resolved world-space frame. Reference geometry for optional visualization; does not add solid material or electrical connectivity. The producer resolves part placement independently of CAD-model offsets; renderers consume the world frame without reapplying the owning model's transform."
+);
+expectTypesMatch(
+  true
+);
+
+// src/simulation/simulation_voltage_source.ts
+import { z as z201 } from "zod";
+var wave_shape = z201.enum(["sinewave", "square", "triangle", "sawtooth"]);
+var percentage = z201.union([z201.string(), z201.number()]).transform((val) => {
   if (typeof val === "string") {
     if (val.endsWith("%")) {
       return parseFloat(val.slice(0, -1)) / 100;
@@ -4520,32 +4582,32 @@ var percentage = z200.union([z200.string(), z200.number()]).transform((val) => {
   }
   return val;
 }).pipe(
-  z200.number().min(0, "Duty cycle must be non-negative").max(1, "Duty cycle cannot be greater than 100%")
+  z201.number().min(0, "Duty cycle must be non-negative").max(1, "Duty cycle cannot be greater than 100%")
 );
-var simulation_dc_voltage_source = z200.object({
-  type: z200.literal("simulation_voltage_source"),
+var simulation_dc_voltage_source = z201.object({
+  type: z201.literal("simulation_voltage_source"),
   simulation_voltage_source_id: getZodPrefixedIdWithDefault(
     "simulation_voltage_source"
   ),
-  is_dc_source: z200.literal(true).optional().default(true),
-  positive_source_port_id: z200.string().optional(),
-  negative_source_port_id: z200.string().optional(),
-  positive_source_net_id: z200.string().optional(),
-  negative_source_net_id: z200.string().optional(),
+  is_dc_source: z201.literal(true).optional().default(true),
+  positive_source_port_id: z201.string().optional(),
+  negative_source_port_id: z201.string().optional(),
+  positive_source_net_id: z201.string().optional(),
+  negative_source_net_id: z201.string().optional(),
   voltage,
   ac_magnitude: voltage.optional(),
   ac_phase: rotation.optional()
 }).describe("Defines a DC voltage source for simulation");
-var simulation_ac_voltage_source = z200.object({
-  type: z200.literal("simulation_voltage_source"),
+var simulation_ac_voltage_source = z201.object({
+  type: z201.literal("simulation_voltage_source"),
   simulation_voltage_source_id: getZodPrefixedIdWithDefault(
     "simulation_voltage_source"
   ),
-  is_dc_source: z200.literal(false),
-  terminal1_source_port_id: z200.string().optional(),
-  terminal2_source_port_id: z200.string().optional(),
-  terminal1_source_net_id: z200.string().optional(),
-  terminal2_source_net_id: z200.string().optional(),
+  is_dc_source: z201.literal(false),
+  terminal1_source_port_id: z201.string().optional(),
+  terminal2_source_port_id: z201.string().optional(),
+  terminal1_source_net_id: z201.string().optional(),
+  terminal2_source_net_id: z201.string().optional(),
   voltage: voltage.optional(),
   frequency: frequency.optional(),
   peak_to_peak_voltage: voltage.optional(),
@@ -4560,14 +4622,14 @@ var simulation_ac_voltage_source = z200.object({
   ac_magnitude: voltage.optional(),
   ac_phase: rotation.optional()
 }).describe("Defines an AC voltage source for simulation");
-var simulation_voltage_source = z200.union([simulation_dc_voltage_source, simulation_ac_voltage_source]).describe("Defines a voltage source for simulation");
+var simulation_voltage_source = z201.union([simulation_dc_voltage_source, simulation_ac_voltage_source]).describe("Defines a voltage source for simulation");
 expectTypesMatch(true);
 expectTypesMatch(true);
 expectTypesMatch(true);
 
 // src/simulation/simulation_current_source.ts
-import { z as z201 } from "zod";
-var percentage2 = z201.union([z201.string(), z201.number()]).transform((val) => {
+import { z as z202 } from "zod";
+var percentage2 = z202.union([z202.string(), z202.number()]).transform((val) => {
   if (typeof val === "string") {
     if (val.endsWith("%")) {
       return parseFloat(val.slice(0, -1)) / 100;
@@ -4576,32 +4638,32 @@ var percentage2 = z201.union([z201.string(), z201.number()]).transform((val) =>
   }
   return val;
 }).pipe(
-  z201.number().min(0, "Duty cycle must be non-negative").max(1, "Duty cycle cannot be greater than 100%")
+  z202.number().min(0, "Duty cycle must be non-negative").max(1, "Duty cycle cannot be greater than 100%")
 );
-var simulation_dc_current_source = z201.object({
-  type: z201.literal("simulation_current_source"),
+var simulation_dc_current_source = z202.object({
+  type: z202.literal("simulation_current_source"),
   simulation_current_source_id: getZodPrefixedIdWithDefault(
     "simulation_current_source"
   ),
-  is_dc_source: z201.literal(true).optional().default(true),
-  positive_source_port_id: z201.string().optional(),
-  negative_source_port_id: z201.string().optional(),
-  positive_source_net_id: z201.string().optional(),
-  negative_source_net_id: z201.string().optional(),
+  is_dc_source: z202.literal(true).optional().default(true),
+  positive_source_port_id: z202.string().optional(),
+  negative_source_port_id: z202.string().optional(),
+  positive_source_net_id: z202.string().optional(),
+  negative_source_net_id: z202.string().optional(),
   current,
   ac_magnitude: current.optional(),
   ac_phase: rotation.optional()
 }).describe("Defines a DC current source for simulation");
-var simulation_ac_current_source = z201.object({
-  type: z201.literal("simulation_current_source"),
+var simulation_ac_current_source = z202.object({
+  type: z202.literal("simulation_current_source"),
   simulation_current_source_id: getZodPrefixedIdWithDefault(
     "simulation_current_source"
   ),
-  is_dc_source: z201.literal(false),
-  terminal1_source_port_id: z201.string().optional(),
-  terminal2_source_port_id: z201.string().optional(),
-  terminal1_source_net_id: z201.string().optional(),
-  terminal2_source_net_id: z201.string().optional(),
+  is_dc_source: z202.literal(false),
+  terminal1_source_port_id: z202.string().optional(),
+  terminal2_source_port_id: z202.string().optional(),
+  terminal1_source_net_id: z202.string().optional(),
+  terminal2_source_net_id: z202.string().optional(),
   current: current.optional(),
   frequency: frequency.optional(),
   peak_to_peak_current: current.optional(),
@@ -4611,58 +4673,59 @@ var simulation_ac_current_source = z201.object({
   ac_magnitude: current.optional(),
   ac_phase: rotation.optional()
 }).describe("Defines an AC current source for simulation");
-var simulation_current_source = z201.union([simulation_dc_current_source, simulation_ac_current_source]).describe("Defines a current source for simulation");
+var simulation_current_source = z202.union([simulation_dc_current_source, simulation_ac_current_source]).describe("Defines a current source for simulation");
 expectTypesMatch(true);
 expectTypesMatch(true);
 expectTypesMatch(true);
 
 // src/simulation/simulation_experiment.ts
-import { z as z203 } from "zod";
+import { z as z204 } from "zod";
 
 // src/simulation/simulation_units.ts
-import { z as z202 } from "zod";
-var simulation_dc_sweep_unit = z202.custom(
+import { z as z203 } from "zod";
+var simulation_dc_sweep_unit = z203.custom(
   (dcSweepUnit) => dcSweepUnit === "V" || dcSweepUnit === "A"
 );
-var simulation_parameter_unit = z202.custom(
+var simulation_parameter_unit = z203.custom(
   (parameterUnit) => parameterUnit === "\u03A9" || parameterUnit === "F" || parameterUnit === "H" || parameterUnit === "V" || parameterUnit === "A"
 );
 
 // src/simulation/simulation_experiment.ts
-var experiment_type = z203.union([
-  z203.literal("spice_dc_sweep"),
-  z203.literal("spice_dc_operating_point"),
-  z203.literal("spice_transient_analysis"),
-  z203.literal("spice_ac_analysis")
+var experiment_type = z204.union([
+  z204.literal("spice_dc_sweep"),
+  z204.literal("spice_dc_operating_point"),
+  z204.literal("spice_transient_analysis"),
+  z204.literal("spice_ac_analysis"),
+  z204.literal("pcb_return_current")
 ]);
-var spice_simulation_options = z203.object({
-  method: z203.enum(["trap", "gear"]).optional(),
-  reltol: z203.union([z203.number(), z203.string()]).optional(),
-  abstol: z203.union([z203.number(), z203.string()]).optional(),
-  vntol: z203.union([z203.number(), z203.string()]).optional()
+var spice_simulation_options = z204.object({
+  method: z204.enum(["trap", "gear"]).optional(),
+  reltol: z204.union([z204.number(), z204.string()]).optional(),
+  abstol: z204.union([z204.number(), z204.string()]).optional(),
+  vntol: z204.union([z204.number(), z204.string()]).optional()
 }).describe("SPICE solver options for a simulation experiment");
-var simulation_experiment = z203.object({
-  type: z203.literal("simulation_experiment"),
+var simulation_experiment = z204.object({
+  type: z204.literal("simulation_experiment"),
   simulation_experiment_id: getZodPrefixedIdWithDefault(
     "simulation_experiment"
   ),
-  name: z203.string(),
+  name: z204.string(),
   experiment_type,
   time_per_step: duration_ms.optional(),
   start_time_ms: ms.optional(),
   end_time_ms: ms.optional(),
   spice_options: spice_simulation_options.optional(),
-  dc_sweep_voltage_source_id: z203.string().optional(),
-  dc_sweep_current_source_id: z203.string().optional(),
-  dc_sweep_start: z203.number().optional(),
-  dc_sweep_stop: z203.number().optional(),
-  dc_sweep_step: z203.number().refine((dcSweepStep) => dcSweepStep !== 0).optional(),
+  dc_sweep_voltage_source_id: z204.string().optional(),
+  dc_sweep_current_source_id: z204.string().optional(),
+  dc_sweep_start: z204.number().optional(),
+  dc_sweep_stop: z204.number().optional(),
+  dc_sweep_step: z204.number().refine((dcSweepStep) => dcSweepStep !== 0).optional(),
   dc_sweep_unit: simulation_dc_sweep_unit.optional(),
-  ac_sweep_type: z203.enum(["linear", "decade", "octave"]).optional(),
-  ac_samples_per_interval: z203.number().int().positive().optional(),
-  ac_sample_count: z203.number().int().positive().optional(),
-  ac_start_frequency_hz: z203.number().positive().optional(),
-  ac_stop_frequency_hz: z203.number().positive().optional()
+  ac_sweep_type: z204.enum(["linear", "decade", "octave"]).optional(),
+  ac_samples_per_interval: z204.number().int().positive().optional(),
+  ac_sample_count: z204.number().int().positive().optional(),
+  ac_start_frequency_hz: z204.number().positive().optional(),
+  ac_stop_frequency_hz: z204.number().positive().optional()
 }).superRefine((experiment, context) => {
   if (experiment.experiment_type === "spice_dc_sweep") {
     const requiredFields = [
@@ -4674,7 +4737,7 @@ var simulation_experiment = z203.object({
     for (const field of requiredFields) {
       if (experiment[field] === void 0) {
         context.addIssue({
-          code: z203.ZodIssueCode.custom,
+          code: z204.ZodIssueCode.custom,
           path: [field],
           message: `${field} is required for a DC sweep`
         });
@@ -4684,7 +4747,7 @@ var simulation_experiment = z203.object({
     const hasCurrentSource = experiment.dc_sweep_current_source_id !== void 0;
     if (hasVoltageSource === hasCurrentSource) {
       context.addIssue({
-        code: z203.ZodIssueCode.custom,
+        code: z204.ZodIssueCode.custom,
         path: ["dc_sweep_voltage_source_id"],
         message: "Exactly one DC sweep voltage or current source ID is required"
       });
@@ -4693,35 +4756,35 @@ var simulation_experiment = z203.object({
   if (experiment.experiment_type === "spice_ac_analysis") {
     if (experiment.ac_sweep_type === void 0) {
       context.addIssue({
-        code: z203.ZodIssueCode.custom,
+        code: z204.ZodIssueCode.custom,
         path: ["ac_sweep_type"],
         message: "ac_sweep_type is required for an AC analysis"
       });
     }
     if (experiment.ac_start_frequency_hz === void 0) {
       context.addIssue({
-        code: z203.ZodIssueCode.custom,
+        code: z204.ZodIssueCode.custom,
         path: ["ac_start_frequency_hz"],
         message: "ac_start_frequency_hz is required for an AC analysis"
       });
     }
     if (experiment.ac_stop_frequency_hz === void 0) {
       context.addIssue({
-        code: z203.ZodIssueCode.custom,
+        code: z204.ZodIssueCode.custom,
         path: ["ac_stop_frequency_hz"],
         message: "ac_stop_frequency_hz is required for an AC analysis"
       });
     }
     if (experiment.ac_sweep_type === "linear" && experiment.ac_sample_count === void 0) {
       context.addIssue({
-        code: z203.ZodIssueCode.custom,
+        code: z204.ZodIssueCode.custom,
         path: ["ac_sample_count"],
         message: "ac_sample_count is required for a linear AC analysis"
       });
     }
     if ((experiment.ac_sweep_type === "decade" || experiment.ac_sweep_type === "octave") && experiment.ac_samples_per_interval === void 0) {
       context.addIssue({
-        code: z203.ZodIssueCode.custom,
+        code: z204.ZodIssueCode.custom,
         path: ["ac_samples_per_interval"],
         message: "ac_samples_per_interval is required for decade and octave AC analyses"
       });
@@ -4731,87 +4794,87 @@ var simulation_experiment = z203.object({
 expectTypesMatch(true);
 
 // src/simulation/simulation_transient_voltage_graph.ts
-import { z as z205 } from "zod";
+import { z as z206 } from "zod";
 
 // src/simulation/simulation_parameter_sweep_coordinate.ts
-import { z as z204 } from "zod";
-var simulation_parameter_sweep_coordinate = z204.object({
-  simulation_parameter_sweep_id: z204.string(),
-  sweep_index: z204.number().int().nonnegative(),
-  parameter_value: z204.number(),
+import { z as z205 } from "zod";
+var simulation_parameter_sweep_coordinate = z205.object({
+  simulation_parameter_sweep_id: z205.string(),
+  sweep_index: z205.number().int().nonnegative(),
+  parameter_value: z205.number(),
   parameter_unit: simulation_parameter_unit
 });
 expectTypesMatch(true);
 
 // src/simulation/simulation_transient_voltage_graph.ts
-var simulation_transient_voltage_graph = z205.object({
-  type: z205.literal("simulation_transient_voltage_graph"),
+var simulation_transient_voltage_graph = z206.object({
+  type: z206.literal("simulation_transient_voltage_graph"),
   simulation_transient_voltage_graph_id: getZodPrefixedIdWithDefault(
     "simulation_transient_voltage_graph"
   ),
-  simulation_experiment_id: z205.string(),
+  simulation_experiment_id: z206.string(),
   simulation_parameter_sweep_coordinate: simulation_parameter_sweep_coordinate.optional(),
-  timestamps_ms: z205.array(z205.number()).optional(),
-  voltage_levels: z205.array(z205.number()),
-  source_component_id: z205.string().optional(),
-  subcircuit_connectivity_map_key: z205.string().optional(),
+  timestamps_ms: z206.array(z206.number()).optional(),
+  voltage_levels: z206.array(z206.number()),
+  source_component_id: z206.string().optional(),
+  subcircuit_connectivity_map_key: z206.string().optional(),
   time_per_step: duration_ms,
   start_time_ms: ms,
   end_time_ms: ms,
-  name: z205.string().optional(),
-  color: z205.string().optional()
+  name: z206.string().optional(),
+  color: z206.string().optional()
 }).describe("Stores voltage measurements over time for a simulation");
 expectTypesMatch(true);
 
 // src/simulation/simulation_transient_current_graph.ts
-import { z as z206 } from "zod";
-var simulation_transient_current_graph = z206.object({
-  type: z206.literal("simulation_transient_current_graph"),
+import { z as z207 } from "zod";
+var simulation_transient_current_graph = z207.object({
+  type: z207.literal("simulation_transient_current_graph"),
   simulation_transient_current_graph_id: getZodPrefixedIdWithDefault(
     "simulation_transient_current_graph"
   ),
-  simulation_experiment_id: z206.string(),
+  simulation_experiment_id: z207.string(),
   simulation_parameter_sweep_coordinate: simulation_parameter_sweep_coordinate.optional(),
-  timestamps_ms: z206.array(z206.number()).optional(),
-  current_levels: z206.array(z206.number()),
-  source_component_id: z206.string().optional(),
-  subcircuit_connectivity_map_key: z206.string().optional(),
+  timestamps_ms: z207.array(z207.number()).optional(),
+  current_levels: z207.array(z207.number()),
+  source_component_id: z207.string().optional(),
+  subcircuit_connectivity_map_key: z207.string().optional(),
   time_per_step: duration_ms,
   start_time_ms: ms,
   end_time_ms: ms,
-  name: z206.string().optional(),
-  color: z206.string().optional()
+  name: z207.string().optional(),
+  color: z207.string().optional()
 }).describe("Stores current measurements over time for a simulation");
 expectTypesMatch(true);
 
 // src/simulation/simulation_switch.ts
-import { z as z207 } from "zod";
-var simulation_switch = z207.object({
-  type: z207.literal("simulation_switch"),
+import { z as z208 } from "zod";
+var simulation_switch = z208.object({
+  type: z208.literal("simulation_switch"),
   simulation_switch_id: getZodPrefixedIdWithDefault("simulation_switch"),
-  source_component_id: z207.string().optional(),
+  source_component_id: z208.string().optional(),
   closes_at: ms.optional(),
   opens_at: ms.optional(),
-  starts_closed: z207.boolean().optional(),
+  starts_closed: z208.boolean().optional(),
   switching_frequency: frequency.optional()
 }).describe("Defines a switch for simulation timing control");
 expectTypesMatch(true);
 
 // src/simulation/simulation_voltage_probe.ts
-import { z as z208 } from "zod";
-var simulation_voltage_probe = z208.object({
-  type: z208.literal("simulation_voltage_probe"),
+import { z as z209 } from "zod";
+var simulation_voltage_probe = z209.object({
+  type: z209.literal("simulation_voltage_probe"),
   simulation_voltage_probe_id: getZodPrefixedIdWithDefault(
     "simulation_voltage_probe"
   ),
-  source_component_id: z208.string().optional(),
-  name: z208.string().optional(),
-  signal_input_source_port_id: z208.string().optional(),
-  signal_input_source_net_id: z208.string().optional(),
-  reference_input_source_port_id: z208.string().optional(),
-  reference_input_source_net_id: z208.string().optional(),
-  subcircuit_id: z208.string().optional(),
-  color: z208.string().optional()
+  source_component_id: z209.string().optional(),
+  name: z209.string().optional(),
+  signal_input_source_port_id: z209.string().optional(),
+  signal_input_source_net_id: z209.string().optional(),
+  reference_input_source_port_id: z209.string().optional(),
+  reference_input_source_net_id: z209.string().optional(),
+  subcircuit_id: z209.string().optional(),
+  color: z209.string().optional()
 }).describe(
   "Defines a voltage probe for simulation. If a reference input is not provided, it measures against ground. If a reference input is provided, it measures the differential voltage between two points."
 ).superRefine((data, ctx) => {
@@ -4821,20 +4884,20 @@ var simulation_voltage_probe = z208.object({
     const has_nets = !!data.signal_input_source_net_id || !!data.reference_input_source_net_id;
     if (has_ports && has_nets) {
       ctx.addIssue({
-        code: z208.ZodIssueCode.custom,
+        code: z209.ZodIssueCode.custom,
         message: "Cannot mix port and net connections in a differential probe."
       });
     } else if (has_ports) {
       if (!data.signal_input_source_port_id || !data.reference_input_source_port_id) {
         ctx.addIssue({
-          code: z208.ZodIssueCode.custom,
+          code: z209.ZodIssueCode.custom,
           message: "Differential port probe requires both signal_input_source_port_id and reference_input_source_port_id."
         });
       }
     } else if (has_nets) {
       if (!data.signal_input_source_net_id || !data.reference_input_source_net_id) {
         ctx.addIssue({
-          code: z208.ZodIssueCode.custom,
+          code: z209.ZodIssueCode.custom,
           message: "Differential net probe requires both signal_input_source_net_id and reference_input_source_net_id."
         });
       }
@@ -4842,7 +4905,7 @@ var simulation_voltage_probe = z208.object({
   } else {
     if (!!data.signal_input_source_port_id === !!data.signal_input_source_net_id) {
       ctx.addIssue({
-        code: z208.ZodIssueCode.custom,
+        code: z209.ZodIssueCode.custom,
         message: "A voltage probe must have exactly one of signal_input_source_port_id or signal_input_source_net_id."
       });
     }
@@ -4851,20 +4914,20 @@ var simulation_voltage_probe = z208.object({
 expectTypesMatch(true);
 
 // src/simulation/simulation_current_probe.ts
-import { z as z209 } from "zod";
-var simulation_current_probe = z209.object({
-  type: z209.literal("simulation_current_probe"),
+import { z as z210 } from "zod";
+var simulation_current_probe = z210.object({
+  type: z210.literal("simulation_current_probe"),
   simulation_current_probe_id: getZodPrefixedIdWithDefault(
     "simulation_current_probe"
   ),
-  source_component_id: z209.string().optional(),
-  name: z209.string().optional(),
-  positive_source_port_id: z209.string().optional(),
-  negative_source_port_id: z209.string().optional(),
-  positive_source_net_id: z209.string().optional(),
-  negative_source_net_id: z209.string().optional(),
-  subcircuit_id: z209.string().optional(),
-  color: z209.string().optional()
+  source_component_id: z210.string().optional(),
+  name: z210.string().optional(),
+  positive_source_port_id: z210.string().optional(),
+  negative_source_port_id: z210.string().optional(),
+  positive_source_net_id: z210.string().optional(),
+  negative_source_net_id: z210.string().optional(),
+  subcircuit_id: z210.string().optional(),
+  color: z210.string().optional()
 }).describe(
   "Defines a current probe for simulation. It measures current flowing from the positive endpoint to the negative endpoint."
 ).superRefine((data, ctx) => {
@@ -4876,7 +4939,7 @@ var simulation_current_probe = z209.object({
   const hasNets = hasPositiveNet || hasNegativeNet;
   if (hasPorts && hasNets) {
     ctx.addIssue({
-      code: z209.ZodIssueCode.custom,
+      code: z210.ZodIssueCode.custom,
       message: "Cannot mix port and net connections in a current probe."
     });
     return;
@@ -4884,7 +4947,7 @@ var simulation_current_probe = z209.object({
   if (hasPorts) {
     if (!hasPositivePort || !hasNegativePort) {
       ctx.addIssue({
-        code: z209.ZodIssueCode.custom,
+        code: z210.ZodIssueCode.custom,
         message: "Current probe using source ports requires both positive_source_port_id and negative_source_port_id."
       });
     }
@@ -4893,71 +4956,71 @@ var simulation_current_probe = z209.object({
   if (hasNets) {
     if (!hasPositiveNet || !hasNegativeNet) {
       ctx.addIssue({
-        code: z209.ZodIssueCode.custom,
+        code: z210.ZodIssueCode.custom,
         message: "Current probe using source nets requires both positive_source_net_id and negative_source_net_id."
       });
     }
     return;
   }
   ctx.addIssue({
-    code: z209.ZodIssueCode.custom,
+    code: z210.ZodIssueCode.custom,
     message: "A current probe must have either positive/negative source port ids or positive/negative source net ids."
   });
 });
 expectTypesMatch(true);
 
 // src/simulation/simulation_unknown_experiment_error.ts
-import { z as z210 } from "zod";
+import { z as z211 } from "zod";
 var simulation_unknown_experiment_error = base_circuit_json_error.extend({
-  type: z210.literal("simulation_unknown_experiment_error"),
+  type: z211.literal("simulation_unknown_experiment_error"),
   simulation_unknown_experiment_error_id: getZodPrefixedIdWithDefault(
     "simulation_unknown_experiment_error"
   ),
-  error_type: z210.literal("simulation_unknown_experiment_error").default("simulation_unknown_experiment_error"),
-  simulation_experiment_id: z210.string().optional(),
-  subcircuit_id: z210.string().optional()
+  error_type: z211.literal("simulation_unknown_experiment_error").default("simulation_unknown_experiment_error"),
+  simulation_experiment_id: z211.string().optional(),
+  subcircuit_id: z211.string().optional()
 }).describe("An unknown error occurred during the simulation experiment.");
 expectTypesMatch(true);
 
 // src/simulation/simulation_parameter_sweep.ts
-import { z as z211 } from "zod";
-var simulation_parameter_type = z211.enum([
+import { z as z212 } from "zod";
+var simulation_parameter_type = z212.enum([
   "resistance",
   "capacitance",
   "inductance",
   "voltage",
   "current"
 ]);
-var simulation_parameter_sweep_base = z211.object({
-  type: z211.literal("simulation_parameter_sweep"),
+var simulation_parameter_sweep_base = z212.object({
+  type: z212.literal("simulation_parameter_sweep"),
   simulation_parameter_sweep_id: getZodPrefixedIdWithDefault(
     "simulation_parameter_sweep"
   ),
-  simulation_experiment_id: z211.string(),
-  name: z211.string().optional(),
-  parameter_values: z211.array(z211.number()).min(1),
+  simulation_experiment_id: z212.string(),
+  name: z212.string().optional(),
+  parameter_values: z212.array(z212.number()).min(1),
   parameter_unit: simulation_parameter_unit
 });
-var simulation_parameter_sweep = z211.discriminatedUnion("parameter_type", [
+var simulation_parameter_sweep = z212.discriminatedUnion("parameter_type", [
   simulation_parameter_sweep_base.extend({
-    parameter_type: z211.literal("resistance"),
-    resistor_source_component_id: z211.string()
+    parameter_type: z212.literal("resistance"),
+    resistor_source_component_id: z212.string()
   }),
   simulation_parameter_sweep_base.extend({
-    parameter_type: z211.literal("capacitance"),
-    capacitor_source_component_id: z211.string()
+    parameter_type: z212.literal("capacitance"),
+    capacitor_source_component_id: z212.string()
   }),
   simulation_parameter_sweep_base.extend({
-    parameter_type: z211.literal("inductance"),
-    inductor_source_component_id: z211.string()
+    parameter_type: z212.literal("inductance"),
+    inductor_source_component_id: z212.string()
   }),
   simulation_parameter_sweep_base.extend({
-    parameter_type: z211.literal("voltage"),
-    source_net_id: z211.string()
+    parameter_type: z212.literal("voltage"),
+    source_net_id: z212.string()
   }),
   simulation_parameter_sweep_base.extend({
-    parameter_type: z211.literal("current"),
-    current_source_component_id: z211.string()
+    parameter_type: z212.literal("current"),
+    current_source_component_id: z212.string()
   })
 ]).describe("Repeats a simulation experiment over component parameter values");
 expectTypesMatch(
@@ -4965,52 +5028,52 @@ expectTypesMatch(
 );
 
 // src/simulation/simulation_dc_operating_point_voltage.ts
-import { z as z212 } from "zod";
-var simulation_dc_operating_point_voltage = z212.object({
-  type: z212.literal("simulation_dc_operating_point_voltage"),
+import { z as z213 } from "zod";
+var simulation_dc_operating_point_voltage = z213.object({
+  type: z213.literal("simulation_dc_operating_point_voltage"),
   simulation_dc_operating_point_voltage_id: getZodPrefixedIdWithDefault(
     "simulation_dc_operating_point_voltage"
   ),
-  simulation_experiment_id: z212.string(),
+  simulation_experiment_id: z213.string(),
   simulation_parameter_sweep_coordinate: simulation_parameter_sweep_coordinate.optional(),
-  simulation_voltage_probe_id: z212.string(),
-  voltage: z212.number(),
-  name: z212.string().optional(),
-  color: z212.string().optional()
+  simulation_voltage_probe_id: z213.string(),
+  voltage: z213.number(),
+  name: z213.string().optional(),
+  color: z213.string().optional()
 });
 expectTypesMatch(true);
 
 // src/simulation/simulation_dc_operating_point_current.ts
-import { z as z213 } from "zod";
-var simulation_dc_operating_point_current = z213.object({
-  type: z213.literal("simulation_dc_operating_point_current"),
+import { z as z214 } from "zod";
+var simulation_dc_operating_point_current = z214.object({
+  type: z214.literal("simulation_dc_operating_point_current"),
   simulation_dc_operating_point_current_id: getZodPrefixedIdWithDefault(
     "simulation_dc_operating_point_current"
   ),
-  simulation_experiment_id: z213.string(),
+  simulation_experiment_id: z214.string(),
   simulation_parameter_sweep_coordinate: simulation_parameter_sweep_coordinate.optional(),
-  simulation_current_probe_id: z213.string(),
-  current: z213.number(),
-  name: z213.string().optional(),
-  color: z213.string().optional()
+  simulation_current_probe_id: z214.string(),
+  current: z214.number(),
+  name: z214.string().optional(),
+  color: z214.string().optional()
 });
 expectTypesMatch(true);
 
 // src/simulation/simulation_dc_sweep_voltage_graph.ts
-import { z as z214 } from "zod";
-var simulation_dc_sweep_voltage_graph = z214.object({
-  type: z214.literal("simulation_dc_sweep_voltage_graph"),
+import { z as z215 } from "zod";
+var simulation_dc_sweep_voltage_graph = z215.object({
+  type: z215.literal("simulation_dc_sweep_voltage_graph"),
   simulation_dc_sweep_voltage_graph_id: getZodPrefixedIdWithDefault(
     "simulation_dc_sweep_voltage_graph"
   ),
-  simulation_experiment_id: z214.string(),
+  simulation_experiment_id: z215.string(),
   simulation_parameter_sweep_coordinate: simulation_parameter_sweep_coordinate.optional(),
-  simulation_voltage_probe_id: z214.string(),
-  sweep_values: z214.array(z214.number()),
+  simulation_voltage_probe_id: z215.string(),
+  sweep_values: z215.array(z215.number()),
   sweep_unit: simulation_dc_sweep_unit,
-  voltage_levels: z214.array(z214.number()),
-  name: z214.string().optional(),
-  color: z214.string().optional()
+  voltage_levels: z215.array(z215.number()),
+  name: z215.string().optional(),
+  color: z215.string().optional()
 }).refine(
   (graph) => graph.sweep_values.length === graph.voltage_levels.length,
   {
@@ -5020,20 +5083,20 @@ var simulation_dc_sweep_voltage_graph = z214.object({
 expectTypesMatch(true);
 
 // src/simulation/simulation_dc_sweep_current_graph.ts
-import { z as z215 } from "zod";
-var simulation_dc_sweep_current_graph = z215.object({
-  type: z215.literal("simulation_dc_sweep_current_graph"),
+import { z as z216 } from "zod";
+var simulation_dc_sweep_current_graph = z216.object({
+  type: z216.literal("simulation_dc_sweep_current_graph"),
   simulation_dc_sweep_current_graph_id: getZodPrefixedIdWithDefault(
     "simulation_dc_sweep_current_graph"
   ),
-  simulation_experiment_id: z215.string(),
+  simulation_experiment_id: z216.string(),
   simulation_parameter_sweep_coordinate: simulation_parameter_sweep_coordinate.optional(),
-  simulation_current_probe_id: z215.string(),
-  sweep_values: z215.array(z215.number()),
+  simulation_current_probe_id: z216.string(),
+  sweep_values: z216.array(z216.number()),
   sweep_unit: simulation_dc_sweep_unit,
-  current_levels: z215.array(z215.number()),
-  name: z215.string().optional(),
-  color: z215.string().optional()
+  current_levels: z216.array(z216.number()),
+  name: z216.string().optional(),
+  color: z216.string().optional()
 }).refine(
   (graph) => graph.sweep_values.length === graph.current_levels.length,
   {
@@ -5043,29 +5106,29 @@ var simulation_dc_sweep_current_graph = z215.object({
 expectTypesMatch(true);
 
 // src/simulation/simulation_ac_sweep_voltage_graph.ts
-import { z as z217 } from "zod";
+import { z as z218 } from "zod";
 
 // src/simulation/simulation_complex_sample.ts
-import { z as z216 } from "zod";
-var simulation_complex_sample = z216.object({
-  re: z216.number(),
-  im: z216.number()
+import { z as z217 } from "zod";
+var simulation_complex_sample = z217.object({
+  re: z217.number(),
+  im: z217.number()
 });
 expectTypesMatch(true);
 
 // src/simulation/simulation_ac_sweep_voltage_graph.ts
-var simulation_ac_sweep_voltage_graph = z217.object({
-  type: z217.literal("simulation_ac_sweep_voltage_graph"),
+var simulation_ac_sweep_voltage_graph = z218.object({
+  type: z218.literal("simulation_ac_sweep_voltage_graph"),
   simulation_ac_sweep_voltage_graph_id: getZodPrefixedIdWithDefault(
     "simulation_ac_sweep_voltage_graph"
   ),
-  simulation_experiment_id: z217.string(),
+  simulation_experiment_id: z218.string(),
   simulation_parameter_sweep_coordinate: simulation_parameter_sweep_coordinate.optional(),
-  simulation_voltage_probe_id: z217.string(),
-  frequencies_hz: z217.array(z217.number()),
-  complex_voltages: z217.array(simulation_complex_sample),
-  name: z217.string().optional(),
-  color: z217.string().optional()
+  simulation_voltage_probe_id: z218.string(),
+  frequencies_hz: z218.array(z218.number()),
+  complex_voltages: z218.array(simulation_complex_sample),
+  name: z218.string().optional(),
+  color: z218.string().optional()
 }).refine(
   (graph) => graph.frequencies_hz.length === graph.complex_voltages.length,
   {
@@ -5075,19 +5138,19 @@ var simulation_ac_sweep_voltage_graph = z217.object({
 expectTypesMatch(true);
 
 // src/simulation/simulation_ac_sweep_current_graph.ts
-import { z as z218 } from "zod";
-var simulation_ac_sweep_current_graph = z218.object({
-  type: z218.literal("simulation_ac_sweep_current_graph"),
+import { z as z219 } from "zod";
+var simulation_ac_sweep_current_graph = z219.object({
+  type: z219.literal("simulation_ac_sweep_current_graph"),
   simulation_ac_sweep_current_graph_id: getZodPrefixedIdWithDefault(
     "simulation_ac_sweep_current_graph"
   ),
-  simulation_experiment_id: z218.string(),
+  simulation_experiment_id: z219.string(),
   simulation_parameter_sweep_coordinate: simulation_parameter_sweep_coordinate.optional(),
-  simulation_current_probe_id: z218.string(),
-  frequencies_hz: z218.array(z218.number()),
-  complex_currents: z218.array(simulation_complex_sample),
-  name: z218.string().optional(),
-  color: z218.string().optional()
+  simulation_current_probe_id: z219.string(),
+  frequencies_hz: z219.array(z219.number()),
+  complex_currents: z219.array(simulation_complex_sample),
+  name: z219.string().optional(),
+  color: z219.string().optional()
 }).refine(
   (graph) => graph.frequencies_hz.length === graph.complex_currents.length,
   {
@@ -5097,52 +5160,52 @@ var simulation_ac_sweep_current_graph = z218.object({
 expectTypesMatch(true);
 
 // src/simulation/simulation_op_amp.ts
-import { z as z219 } from "zod";
-var simulation_op_amp = z219.object({
-  type: z219.literal("simulation_op_amp"),
+import { z as z220 } from "zod";
+var simulation_op_amp = z220.object({
+  type: z220.literal("simulation_op_amp"),
   simulation_op_amp_id: getZodPrefixedIdWithDefault("simulation_op_amp"),
-  source_component_id: z219.string().optional(),
-  inverting_input_source_port_id: z219.string(),
-  non_inverting_input_source_port_id: z219.string(),
-  output_source_port_id: z219.string(),
-  positive_supply_source_port_id: z219.string(),
-  negative_supply_source_port_id: z219.string()
+  source_component_id: z220.string().optional(),
+  inverting_input_source_port_id: z220.string(),
+  non_inverting_input_source_port_id: z220.string(),
+  output_source_port_id: z220.string(),
+  positive_supply_source_port_id: z220.string(),
+  negative_supply_source_port_id: z220.string()
 }).describe("Defines a simple ideal operational amplifier for simulation");
 expectTypesMatch(true);
 
 // src/simulation/simulation_spice_subcircuit.ts
-import { z as z220 } from "zod";
-var simulation_spice_subcircuit = z220.object({
-  type: z220.literal("simulation_spice_subcircuit"),
+import { z as z221 } from "zod";
+var simulation_spice_subcircuit = z221.object({
+  type: z221.literal("simulation_spice_subcircuit"),
   simulation_spice_subcircuit_id: getZodPrefixedIdWithDefault(
     "simulation_spice_subcircuit"
   ),
-  source_component_id: z220.string(),
-  spice_pin_to_source_port_map: z220.record(z220.string(), z220.string()),
-  subcircuit_source: z220.string()
+  source_component_id: z221.string(),
+  spice_pin_to_source_port_map: z221.record(z221.string(), z221.string()),
+  subcircuit_source: z221.string()
 }).describe("Defines a custom SPICE subcircuit model for simulation");
 expectTypesMatch(
   true
 );
 
 // src/simulation/simulation_oscilloscope_trace.ts
-import { z as z221 } from "zod";
+import { z as z222 } from "zod";
 var hasValue = (value) => value !== void 0;
-var simulation_oscilloscope_trace = z221.object({
-  type: z221.literal("simulation_oscilloscope_trace"),
+var simulation_oscilloscope_trace = z222.object({
+  type: z222.literal("simulation_oscilloscope_trace"),
   simulation_oscilloscope_trace_id: getZodPrefixedIdWithDefault(
     "simulation_oscilloscope_trace"
   ),
-  simulation_transient_voltage_graph_id: z221.string().optional(),
-  simulation_transient_current_graph_id: z221.string().optional(),
-  simulation_voltage_probe_id: z221.string().optional(),
-  simulation_current_probe_id: z221.string().optional(),
-  display_name: z221.string().optional(),
-  color: z221.string().optional(),
-  display_center_value: z221.number().optional(),
-  display_center_offset_divs: z221.number().optional(),
-  volts_per_div: z221.number().positive().optional(),
-  amps_per_div: z221.number().positive().optional()
+  simulation_transient_voltage_graph_id: z222.string().optional(),
+  simulation_transient_current_graph_id: z222.string().optional(),
+  simulation_voltage_probe_id: z222.string().optional(),
+  simulation_current_probe_id: z222.string().optional(),
+  display_name: z222.string().optional(),
+  color: z222.string().optional(),
+  display_center_value: z222.number().optional(),
+  display_center_offset_divs: z222.number().optional(),
+  volts_per_div: z222.number().positive().optional(),
+  amps_per_div: z222.number().positive().optional()
 }).describe(
   "Defines how a simulation measurement is rendered as an oscilloscope-style trace."
 ).superRefine((data, ctx) => {
@@ -5156,28 +5219,316 @@ var simulation_oscilloscope_trace = z221.object({
   ].filter(hasValue).length;
   if (voltageReferences + currentReferences !== 1) {
     ctx.addIssue({
-      code: z221.ZodIssueCode.custom,
+      code: z222.ZodIssueCode.custom,
       message: "An oscilloscope trace must reference exactly one voltage graph, current graph, voltage probe, or current probe."
     });
   }
   if (voltageReferences > 0 && data.amps_per_div !== void 0) {
     ctx.addIssue({
-      code: z221.ZodIssueCode.custom,
+      code: z222.ZodIssueCode.custom,
       message: "Voltage oscilloscope traces must use volts_per_div, not amps_per_div."
     });
   }
   if (currentReferences > 0 && data.volts_per_div !== void 0) {
     ctx.addIssue({
-      code: z221.ZodIssueCode.custom,
+      code: z222.ZodIssueCode.custom,
       message: "Current oscilloscope traces must use amps_per_div, not volts_per_div."
     });
   }
 });
 expectTypesMatch(true);
 
+// src/simulation/simulation_return_current_contact.ts
+import { z as z223 } from "zod";
+var contact_position = z223.object({
+  x: z223.number().finite(),
+  y: z223.number().finite(),
+  layer: layer_ref
+});
+var simulation_return_current_contact = z223.discriminatedUnion("contact_type", [
+  contact_position.extend({
+    contact_type: z223.literal("pcb_port"),
+    pcb_port_id: z223.string().min(1)
+  }),
+  contact_position.extend({
+    contact_type: z223.literal("pcb_via"),
+    pcb_via_id: z223.string().min(1)
+  }),
+  contact_position.extend({
+    contact_type: z223.literal("pcb_copper_pour"),
+    pcb_copper_pour_id: z223.string().min(1)
+  })
+]).describe("Identifies the reference conductor at a return-current contact");
+expectTypesMatch(true);
+
+// src/simulation/simulation_terminal_port.ts
+import { z as z224 } from "zod";
+var simulation_terminal_port = z224.object({
+  signal_pcb_port_id: z224.string().min(1),
+  reference_pcb_port_id: z224.string().min(1).optional(),
+  reference_layer: layer_ref,
+  resistance: z224.number().finite().positive()
+}).describe(
+  "A two-terminal return-current excitation port with resistance in ohms"
+);
+expectTypesMatch(true);
+
+// src/simulation/simulation_return_current_excitation.ts
+import { z as z225 } from "zod";
+var simulation_return_current_excitation = z225.object({
+  type: z225.literal("simulation_return_current_excitation"),
+  simulation_return_current_excitation_id: getZodPrefixedIdWithDefault(
+    "simulation_return_current_excitation"
+  ),
+  simulation_experiment_id: z225.string().min(1),
+  pcb_trace_id: z225.string().min(1),
+  ground_source_net_id: z225.string().min(1),
+  current: z225.number().finite(),
+  return_source: simulation_return_current_contact,
+  return_sink: simulation_return_current_contact,
+  source_port: simulation_terminal_port.optional(),
+  load_port: simulation_terminal_port.optional()
+}).describe(
+  "Excites a signal trace with signed current in amperes, peak for AC; return_source is near the load and return_sink near the driver for positive current"
+);
+expectTypesMatch(true);
+
+// src/simulation/simulation_pcb_return_current_result.ts
+import { z as z226 } from "zod";
+var simulation_pcb_return_current_result = z226.object({
+  type: z226.literal("simulation_pcb_return_current_result"),
+  simulation_pcb_return_current_result_id: getZodPrefixedIdWithDefault(
+    "simulation_pcb_return_current_result"
+  ),
+  simulation_experiment_id: z226.string().min(1),
+  pcb_board_id: z226.string().min(1),
+  simulation_return_current_excitation_ids: z226.array(z226.string().min(1)).min(1).refine(
+    (ids) => new Set(ids).size === ids.length,
+    "Excitation IDs must be unique"
+  ),
+  frequency_hz: z226.number().finite().positive().optional()
+}).describe(
+  "A PCB return-current result at one frequency, or a frequency-independent result when frequency_hz is absent"
+);
+expectTypesMatch(true);
+
+// src/simulation/simulation_return_current_asset.ts
+import { z as z227 } from "zod";
+function createSimulationReturnCurrentAssetSchema(mimetypes) {
+  return asset.extend({
+    project_relative_path: z227.string().min(1),
+    url: z227.string().url()
+  }).superRefine((value, context) => {
+    if (!mimetypes.includes(value.mimetype)) {
+      context.addIssue({
+        code: z227.ZodIssueCode.custom,
+        path: ["mimetype"],
+        message: `Expected one of: ${mimetypes.join(", ")}`
+      });
+    }
+    if (value.url.startsWith("data:")) {
+      const mediaType = /^data:([^;,]*)(?:;[^,]*)?,/i.exec(value.url)?.[1];
+      if (mediaType?.toLowerCase() !== value.mimetype) {
+        context.addIssue({
+          code: z227.ZodIssueCode.custom,
+          path: ["url"],
+          message: "Data URL media type must match asset.mimetype"
+        });
+      }
+    }
+  });
+}
+var simulation_return_current_field_asset = createSimulationReturnCurrentAssetSchema([
+  "application/json",
+  "application/gzip"
+]);
+var simulation_return_current_image_asset = createSimulationReturnCurrentAssetSchema(["image/png", "image/webp"]);
+
+// src/simulation/simulation_pcb_return_current_field.ts
+import { z as z228 } from "zod";
+var simulation_pcb_return_current_field = z228.object({
+  type: z228.literal("simulation_pcb_return_current_field"),
+  simulation_pcb_return_current_field_id: getZodPrefixedIdWithDefault(
+    "simulation_pcb_return_current_field"
+  ),
+  simulation_pcb_return_current_result_id: z228.string().min(1),
+  layer: layer_ref,
+  source_net_id: z228.string().min(1),
+  field_type: z228.enum(["real", "complex_phasor"]),
+  min_x: z228.number().finite(),
+  min_y: z228.number().finite(),
+  columns: z228.number().int().positive().safe(),
+  rows: z228.number().int().positive().safe(),
+  cell_width: z228.number().finite().positive(),
+  cell_height: z228.number().finite().positive(),
+  copper_thickness: z228.number().finite().positive(),
+  data_format: z228.literal("simulation_return_current_grid_json_v1"),
+  field_asset: simulation_return_current_field_asset
+}).superRefine((field, context) => {
+  if (!Number.isSafeInteger(field.columns * field.rows)) {
+    context.addIssue({
+      code: z228.ZodIssueCode.custom,
+      path: ["columns"],
+      message: "The grid cell count must be a safe integer"
+    });
+  }
+}).describe(
+  "A sampled sheet-current field in A/mm, using plain or gzipped JSON Asset URLs; dimensions are PCB millimeters"
+);
+expectTypesMatch(true);
+
+// src/simulation/simulation_return_current_grid_json.ts
+import { z as z229 } from "zod";
+var channel = z229.array(z229.number().finite().nullable()).min(1);
+var simulation_return_current_grid_json = z229.discriminatedUnion("field_type", [
+  z229.object({
+    field_type: z229.literal("real"),
+    sheet_current_x: channel,
+    sheet_current_y: channel
+  }),
+  z229.object({
+    field_type: z229.literal("complex_phasor"),
+    sheet_current_x_real: channel,
+    sheet_current_x_imag: channel,
+    sheet_current_y_real: channel,
+    sheet_current_y_imag: channel
+  })
+]).superRefine((grid, context) => {
+  const channels = grid.field_type === "real" ? [grid.sheet_current_x, grid.sheet_current_y] : [
+    grid.sheet_current_x_real,
+    grid.sheet_current_x_imag,
+    grid.sheet_current_y_real,
+    grid.sheet_current_y_imag
+  ];
+  const first = channels[0];
+  if (channels.some((values) => values.length !== first.length)) {
+    context.addIssue({
+      code: z229.ZodIssueCode.custom,
+      message: "Current channels must have equal lengths"
+    });
+    return;
+  }
+  for (let index = 0; index < first.length; index++) {
+    const masked = first[index] === null;
+    if (channels.some((values) => values[index] === null !== masked)) {
+      context.addIssue({
+        code: z229.ZodIssueCode.custom,
+        message: `Cell ${index} must be null in every channel or finite in every channel`
+      });
+      return;
+    }
+  }
+}).describe(
+  "Decoded real or complex sheet-current arrays with a shared conductor mask"
+);
+expectTypesMatch(true);
+function getSimulationReturnCurrentGridJsonSchema(field) {
+  const count = field.columns * field.rows;
+  if (!Number.isSafeInteger(field.columns) || field.columns <= 0 || !Number.isSafeInteger(field.rows) || field.rows <= 0 || !Number.isSafeInteger(count))
+    throw new Error("Grid dimensions must be positive safe integers");
+  return simulation_return_current_grid_json.superRefine((grid, context) => {
+    if (grid.field_type !== field.field_type) {
+      context.addIssue({
+        code: z229.ZodIssueCode.custom,
+        path: ["field_type"],
+        message: "Decoded field_type must match the parent field"
+      });
+    }
+    const first = grid.field_type === "real" ? grid.sheet_current_x : grid.sheet_current_x_real;
+    if (first.length !== count) {
+      context.addIssue({
+        code: z229.ZodIssueCode.custom,
+        message: `Each current channel must have ${count} entries (columns * rows)`
+      });
+    }
+  });
+}
+
+// src/simulation/simulation_pcb_return_current_heatmap.ts
+import { z as z230 } from "zod";
+var simulation_pcb_return_current_heatmap = z230.object({
+  type: z230.literal("simulation_pcb_return_current_heatmap"),
+  simulation_pcb_return_current_heatmap_id: getZodPrefixedIdWithDefault(
+    "simulation_pcb_return_current_heatmap"
+  ),
+  simulation_pcb_return_current_result_id: z230.string().min(1),
+  layer: layer_ref,
+  source_net_id: z230.string().min(1),
+  min_x: z230.number().finite(),
+  min_y: z230.number().finite(),
+  max_x: z230.number().finite(),
+  max_y: z230.number().finite(),
+  image_asset: simulation_return_current_image_asset
+}).superRefine((heatmap, context) => {
+  for (const axis of ["x", "y"]) {
+    if (heatmap[`max_${axis}`] <= heatmap[`min_${axis}`]) {
+      context.addIssue({
+        code: z230.ZodIssueCode.custom,
+        path: [`max_${axis}`],
+        message: "Heatmap bounds must have positive width and height"
+      });
+    }
+  }
+}).describe(
+  "A transparent PNG/WebP current-density overlay in A/mm\xB2; the top-left pixel maps to (min_x, max_y)"
+);
+expectTypesMatch(true);
+
+// src/simulation/simulation_pcb_return_current_marker.ts
+import { z as z231 } from "zod";
+var marker_base = z231.object({
+  type: z231.literal("simulation_pcb_return_current_marker"),
+  simulation_pcb_return_current_marker_id: getZodPrefixedIdWithDefault(
+    "simulation_pcb_return_current_marker"
+  ),
+  simulation_pcb_return_current_result_id: z231.string().min(1),
+  role: z231.enum([
+    "signal_source",
+    "signal_load",
+    "return_source",
+    "return_sink",
+    "signal_transition",
+    "return_transition"
+  ]),
+  label: z231.string().optional(),
+  label_x: z231.number().finite().optional(),
+  label_y: z231.number().finite().optional()
+});
+var simulation_pcb_return_current_marker = z231.discriminatedUnion("target_type", [
+  marker_base.extend({
+    target_type: z231.literal("pcb_port"),
+    pcb_port_id: z231.string().min(1),
+    layer: layer_ref
+  }),
+  marker_base.extend({
+    target_type: z231.literal("pcb_via"),
+    pcb_via_id: z231.string().min(1),
+    from_layer: layer_ref,
+    to_layer: layer_ref
+  })
+]).superRefine((marker, context) => {
+  if (marker.label_x === void 0 !== (marker.label_y === void 0)) {
+    context.addIssue({
+      code: z231.ZodIssueCode.custom,
+      path: ["label_x"],
+      message: "label_x and label_y must be provided together"
+    });
+  }
+  if (marker.target_type === "pcb_via" && marker.from_layer === marker.to_layer) {
+    context.addIssue({
+      code: z231.ZodIssueCode.custom,
+      path: ["to_layer"],
+      message: "A via transition must connect distinct layers"
+    });
+  }
+}).describe(
+  "A signal/return port or via highlight; markers do not assert measured via-transfer currents"
+);
+expectTypesMatch(true);
+
 // src/any_circuit_element.ts
-import { z as z222 } from "zod";
-var any_circuit_element = z222.union([
+import { z as z232 } from "zod";
+var any_circuit_element = z232.union([
   source_runtime_error,
   source_trace,
   source_bus,
@@ -5336,10 +5687,16 @@ var any_circuit_element = z222.union([
   schematic_table_cell,
   cad_component,
   cad_cable,
+  cad_reference_surface,
   cad_collision_error,
   simulation_voltage_source,
   simulation_current_source,
   simulation_experiment,
+  simulation_return_current_excitation,
+  simulation_pcb_return_current_result,
+  simulation_pcb_return_current_field,
+  simulation_pcb_return_current_heatmap,
+  simulation_pcb_return_current_marker,
   simulation_transient_voltage_graph,
   simulation_transient_current_graph,
   simulation_dc_operating_point_voltage,
@@ -5375,6 +5732,7 @@ export {
   cad_component,
   cad_model_axis_directions,
   cad_model_formats,
+  cad_reference_surface,
   capacitance,
   circle_shape,
   circuit_json_footprint_load_error,
@@ -5385,6 +5743,7 @@ export {
   external_footprint_load_error,
   frequency,
   getRotationBetweenPcbPin1Locations,
+  getSimulationReturnCurrentGridJsonSchema,
   getZodPrefixedIdWithDefault,
   inductance,
   insertionDirectionToCanonical,
@@ -5591,8 +5950,18 @@ export {
   simulation_parameter_sweep_coordinate,
   simulation_parameter_type,
   simulation_parameter_unit,
+  simulation_pcb_return_current_field,
+  simulation_pcb_return_current_heatmap,
+  simulation_pcb_return_current_marker,
+  simulation_pcb_return_current_result,
+  simulation_return_current_contact,
+  simulation_return_current_excitation,
+  simulation_return_current_field_asset,
+  simulation_return_current_grid_json,
+  simulation_return_current_image_asset,
   simulation_spice_subcircuit,
   simulation_switch,
+  simulation_terminal_port,
   simulation_transient_current_graph,
   simulation_transient_voltage_graph,
   simulation_unknown_experiment_error,