export type BlenderOperatorPropertyType = "boolean" | "number" | "enum" | "string" | "pointer" | "collection" | "number-array" | "boolean-array" | "enum-set";

/** Local embedded-bpy pointer input, including nested dictionary/collection fields.
 * `$rna` is a native RNA path relative to bpy.data (default) or the selected
 * bpy.context after editor/mode override. It is not a Python expression.
 * The tag distinguishes references from literal PropertyGroup dictionaries.
 * Existing string and {name, type?} ID references remain supported.
 */
export interface BlenderOperatorRNAReference {
  $rna: string;
  root?: "data" | "context";
  type?: string;
}

export type BlenderOperatorPropertyValue = string | number | boolean | null | number[] | boolean[] | string[] | Record<string, unknown> | Array<Record<string, unknown>>;

export interface BlenderOperatorEnumItem {
  value: string;
  label: string;
}

export interface BlenderOperatorPropertySpec {
  name: string;
  type: BlenderOperatorPropertyType;
  required: boolean;
  label?: string;
  description?: string;
  defaultValue?: BlenderOperatorPropertyValue;
  min?: number;
  max?: number;
  integer?: boolean;
  arrayLength?: number;
  pointerType?: string;
  pointerValueKind?: "reference" | "properties";
  collectionItemType?: string;
  /** Live RNA fields of a property dictionary or one collection item. */
  properties?: BlenderOperatorPropertySpec[];
  subtype?: string;
  unit?: string;
  enumItems?: BlenderOperatorEnumItem[];
}

export interface BlenderOperatorDescriptor {
  id: string;
  label: string;
  description?: string;
  family: string;
  context: "scene" | "object" | "main";
  backgroundSafe: true;
  properties: BlenderOperatorPropertySpec[];
}

export interface BlenderServerOperatorSchema {
  operator: BlenderOperatorDescriptor;
  blenderBuild: { version: string; buildSha256: string };
}

export interface BlenderOperatorInvocation {
  operator: string;
  properties?: Record<string, BlenderOperatorPropertyValue>;
  baseRevision?: number;
}

export type BlenderFeatureRoute = "WEB_MAIN" | "SERVER_NATIVE" | "BROWSER_EQUIVALENT" | "UNAVAILABLE";

/** Browser-owned replacements for desktop context/window operators. */
export type BlenderBrowserActionGroup = "OPEN" | "SAVE" | "AUTOSAVE" | "RECOVERY" | "LAST_SESSION" | "WORKSPACE" | "SELECTION" | "VIEW" | "EDITOR";

export interface BlenderBrowserEquivalentInvocation {
  command: "invokeBrowserEquivalent";
  route: string;
  actionGroup: BlenderBrowserActionGroup;
  browserCommand: string;
}

export interface BlenderFeatureRouteRuntimeAudit {
  command: "featureRouteRuntimeAudit";
  status: "PASS" | "FAILED" | "STATIC_DECLARATION";
  behavioralEvidence: { separate: true };
}

export interface BlenderFeatureRouteLocation {
  path: string;
  line?: number;
  evidence?: string;
}

/** Source-unit route metadata used by the F3 feature palette. */
export interface BlenderFeatureRouteEntry {
  id: string;
  kind: string;
  identifier: string;
  family: string;
  route: BlenderFeatureRoute;
  reason: string;
  /** HTTP provider used by SERVER_NATIVE routes. */
  httpRoute?: string;
  /** Existing browser workflow used by BROWSER_EQUIVALENT routes. */
  browserActionGroup?: BlenderBrowserActionGroup;
  label?: string;
  description?: string;
  properties?: BlenderOperatorPropertySpec[];
  locations?: BlenderFeatureRouteLocation[];
}

export interface BlenderFeatureRouteInvocation {
  route: BlenderFeatureRouteEntry;
  properties?: Record<string, BlenderOperatorPropertyValue>;
  baseRevision?: number;
}

/** SERVER_NATIVE accepts bounded scalars, fixed RNA arrays and enum flag sets. */
export const BLENDER_OPERATOR_BACKGROUND_CONTEXT = "BACKGROUND" as const;

export type BlenderMacroStepKind = "MAIN_COMMAND" | "SERVER_NATIVE" | "CONTEXT_DEPENDENT";

export interface BlenderMacroStep {
  id: string;
  kind: BlenderMacroStepKind;
  context: "MAIN" | "BACKGROUND" | "UI";
  operator?: string;
  command?: Record<string, unknown>;
  source: BlenderFeatureRouteLocation[];
}

/** A bounded, source-backed native plan assembled from Blender operator units. */
export interface BlenderMacroDescriptor {
  id: string;
  label: string;
  description?: string;
  family: string;
  route: BlenderFeatureRoute;
  contextDependent: boolean;
  source: BlenderFeatureRouteLocation[];
  steps: BlenderMacroStep[];
  properties?: BlenderOperatorPropertySpec[];
}

export interface BlenderMacroInvocation {
  macro: string;
  properties?: Record<string, BlenderOperatorPropertyValue>;
  baseRevision?: number;
  serverJob?: Record<string, unknown>;
}