// ── Shared interfaces ─────────────────────────────────────────────────────────

/** Describes a single auto-listener entry stored in `__listeners`. */
interface JawListenerEntry {
	context?: string;
	handler: ((...args: any[]) => any) | string;
	originalHandler?: string;
	target: "DOM" | "controller" | "component";
	type: "autoListener";
	smartUnlisten?: boolean;
}

/** Describes an item used in array-form calls to `set()`. */
interface JawSetItem {
	name: string;
	value: any;
}

/** Describes an entry in the `__validMethodList` built by `_extractValidMethodList`. */
interface JawValidMethod {
	handlerName: string;
	handlerHolder: Jaw;
	_from?: string;
	depthList?: number[];
	minDepth?: number;
	targetType?: "singleNode" | "multiNode" | "manager";
}


// ── Jaw ───────────────────────────────────────────────────────────────────────

/**
 * Represents an element of the MVC model (View or Controller).
 * Extends the native `EventTarget` and adds Shark-specific methods.
 */
export declare class Jaw extends EventTarget {
	/** Read-only identifier for this Jaw instance. Set from `jawId` in the constructor. */
	readonly className: string;

	/** Read-only identifier alias for `className`. */
	readonly id: string;

	/** If the routing method is set to "url", this will be the URL displayed when this Jaw is active. */
	route: string | null;

	/** Whether this Jaw has been initialized via `init()`. */
	isInitialized: boolean;

	/** The options object used in the most recent open operation. */
	currentOpenOptions: Record<string, any>;

	/**
	 * Reactive proxy over `__store`. Properties defined here trigger auto-render when changed,
	 * if `Shark.settings.enableJawStoreAutoRender` is enabled.
	 */
	$store: Record<string, any>;

	/** @internal Internal data store, backing `$store` and `get()`/`set()`. */
	protected __store: Record<string, any>;

	/** @internal Fields registered for auto-rendering. */
	protected __renderFields: string[];

	/** @internal Map of child templates used during rendering. */
	protected __childTemplates: Record<string, string>;

	/** @internal Map of dynamic data bindings. */
	protected __dynamicDataBindings: Record<string, any>;

	/** @internal Registry of event listeners assigned by `smartListen`. */
	protected __listeners: Record<string, Record<string, JawListenerEntry>>;

	/** @internal Named methods added to this Jaw. */
	protected __methods: Record<string, any>;

	/** @internal View binding map (primary). */
	protected __viewBinds: Record<string, any>;

	/** @internal View binding map (secondary). */
	protected __viewBinds2: Record<string, any>;

	/** @internal Hash map used for change-detection in `__singleSet`. */
	protected __storeHashMap: Map<string, any>;

	/** @internal List of valid handler methods built by `smartListen`. */
	protected __validMethodList?: JawValidMethod[];

	/**
	 * The list of Components currently active on this Jaw.
	 * Use `addComponent` / `addComponents` to modify it.
	 */
	readonly activeComponents: Jaw[];

	/**
	 * Creates a new Jaw instance.
	 *
	 * @param jawId - The identifier for this Jaw. If omitted/null/empty, defaults to the
	 *                camelCase class name of the subclass.
	 */
	constructor(jawId?: string | null);

	/**
	 * @deprecated Pass only `jawId`. The `jawDefinition` parameter will be removed in a future version.
	 */
	// eslint-disable-next-line @typescript-eslint/unified-signatures
	constructor(jawId: string | null | undefined, jawDefinition: object);

	/**
	 * Add a single Component to this Jaw.
	 *
	 * @param component - The Component to add, either as a string ID or a Component instance.
	 *                    Passing a string is deprecated; prefer passing the instance directly.
	 * @returns The updated list of active Components.
	 */
	addComponent(component: Jaw | string): Jaw[];

	/**
	 * Add multiple Components to this Jaw.
	 *
	 * @param components - Array of Components to add (as instances or string IDs).
	 * @returns The updated list of active Components.
	 */
	addComponents(components: (Jaw | string)[]): Jaw[];

	/**
	 * Retrieve one or more values from the internal data store.
	 *
	 * - Called with no arguments: returns the entire `__store` object.
	 * - Called with a string: returns the value for that key.
	 * - Called with an array of strings: returns an array of the corresponding values.
	 */
	get(itemName?: string): any;
	get(itemName: string[]): any[];
	get(itemName: undefined): Record<string, any>;

	/** Called when this Jaw is used for the first time. Override in subclasses. */
	init(): void;

	/** @internal Extracts valid `*Handler` methods from a list of Components, recursively. */
	protected _extractComponentsValidMethodList(
		componentList: Jaw[],
		processedComponentList: string[],
		notProcessedComponentList: string[]
	): JawValidMethod[];

	/** @internal Extracts valid `*Handler` methods from a target object and its prototype chain. */
	protected _extractValidMethodList(targetObject: Jaw): JawValidMethod[];

	/** @internal Initialises Components, calling `init()` on each if not already done. */
	protected _initComponents(componentList?: Jaw[] | null, processedComponentList?: string[]): void;

	/**
	 * Store one or more values in this Jaw's internal data store.
	 *
	 * Accepted signatures:
	 * - `set(name, value)` — set a single named value.
	 * - `set(object)` — merge all properties of the object into the store.
	 * - `set(array)` — each item must have `{ name, value }`.
	 */
	set(nameOrItems: string, value: any): void;
	set(nameOrItems: Record<string, any>): void;
	set(nameOrItems: JawSetItem[]): void;

	/** @internal Sets a single key on the store, returns `1` if the value changed, `0` otherwise. */
	protected __singleSet(name: string, value: any): 0 | 1;

	/**
	 * Dispatch an event from this Jaw using jQuery's `.trigger()`.
	 */
	emit(eventName: string, eventData?: any): JQuery;

	/**
	 * Remove an event listener from this Jaw using jQuery's `.off()`.
	 */
	off(eventName: string, eventHandler: (...args: any[]) => any): JQuery;

	/**
	 * Attach an event listener to this Jaw using jQuery's `.on()`.
	 */
	on(eventName: string, eventHandler: (...args: any[]) => any): JQuery;

	/**
	 * Automatically match and assign DOM and controller event listeners based on the
	 * naming convention `selectorOrControllerName_eventNameHandler`.
	 *
	 * @param container - Optional CSS selector or jQuery selection to restrict parsing scope.
	 * @param selfAssign - If `true`, the container itself is treated as a potential target.
	 */
	smartListen(container?: string | JQuery, selfAssign?: boolean): void;

	/** @internal Experimental v2 of `smartListen`. Work in progress. */
	smartListen2(container?: string | JQuery, selfAssign?: boolean): void;

	/**
	 * Remove all listeners previously assigned by `smartListen`.
	 */
	smartUnlisten(container?: string | JQuery): void;

	/**
	 * Internal tracing utility. Delegates to `Shark.trace` if available.
	 */
	trace(message: any, level?: string): void;

	/**
	 * Update the DOM portions bound to a reference model path after the model's dirty
	 * properties have changed.
	 */
	updateDisplay(referenceModelPath: string, sourceEvent?: Event): void;

	/** @internal Utility to compute the DOM depth of a node (distance from BODY). */
	static __getNodeDepth(node: Node): number;
}


// ── RenderableJaw ─────────────────────────────────────────────────────────────

/**
 * The base class for View, Component and PageTemplate.
 * Adds template management on top of Jaw.
 */
export declare class RenderableJaw extends Jaw {
	/** The default template HTML string (raw, before parsing). */
	templateContent: string;

	/** The type identifier for this class (overridden in subclasses). */
	type: string;

	/**
	 * Map of all registered templates, keyed by name.
	 * Each entry contains `{ content, parsed, parsedContent }`.
	 * The default template is stored under the key `"__default__"`.
	 * Non-configurable, non-writable (contents are mutable).
	 */
	readonly templates: Record<string, { content: string; parsed: boolean; parsedContent: string }>;

	/**
	 * Map of fully-expanded template strings keyed by name.
	 * Populated by `parseTemplates()`. The default template is under `"__default__"`.
	 * Non-configurable, non-writable (contents are mutable).
	 */
	readonly parsedTemplates: Record<string, string>;

	/**
	 * The parsed default template string.
	 * @deprecated Prefer `parsedTemplates["__default__"]`. Kept for back-compat.
	 */
	protected __parsedTemplate: string | null;

	/**
	 * `true` after `parseTemplates()` has run at least once.
	 * @deprecated Prefer checking `templates["__default__"].parsed`. Kept for back-compat.
	 */
	protected __templatesParsed?: boolean;

	/** @internal Raw template map (legacy). Prefer `templates`. */
	protected __templates: Record<string, string>;

	constructor(jawId?: string | null);

	/** @deprecated Pass only `jawId`. */
	// eslint-disable-next-line @typescript-eslint/unified-signatures
	constructor(jawId: string | null | undefined, jawDefinition: object);

	/**
	 * Add a named HTML template to this RenderableJaw.
	 *
	 * @param name - Template name. Pass `""` to register the default template (only one allowed).
	 *               Cannot be `"__default__"` (reserved) or contain spaces.
	 * @param content - The raw HTML template string.
	 * @returns The internal `__templates` map, or `undefined` if validation failed.
	 */
	addTemplate(name: string, content: string): Record<string, string> | undefined;

	/**
	 * Set the default HTML template for this RenderableJaw.
	 * Shorthand for `addTemplate("", content)`.
	 *
	 * @param content - The raw HTML template string.
	 * @returns The internal `__templates` map, or `undefined` if validation failed.
	 */
	setTemplate(content: string): Record<string, string> | undefined;

	/**
	 * Parse all registered templates, resolving:
	 * - PageTemplate slot injection (`<shark-template>`)
	 * - Component expansion (`<shark-xxx-component>`) including named slot content and `prop-*` attributes
	 * - `data-sh-model` → `data-shguid` binding
	 * - Auto-bound Shark `$store` properties
	 * - `SmartModel` bound properties
	 * - Dynamic sections (`<shark-section>`)
	 * - `[[renderer.field]]` syntax
	 *
	 * This is a no-op if the template has already been parsed, unless `force: true` is passed.
	 * Called automatically by `PreactRenderer.render()` before the first render.
	 *
	 * @param options.force - If `true`, re-parses even already-parsed templates. Default: `false`.
	 * @param options.sharkModelGuidPlaceHolder - Placeholder for `data-shguid` on Mustache model refs.
	 *   Default: `"__ph__"`.
	 */
	parseTemplates(options?: { force?: boolean; sharkModelGuidPlaceHolder?: string }): void;
}


// ── Component ─────────────────────────────────────────────────────────────────

/**
 * The class to extend to create Component classes.
 * Components are sub-parts of a View, used to render and manage portions of the UI.
 *
 * A Component's HTML template can contain:
 * - `<slot name="..."></slot>` placeholders, filled at the call site with named slot content.
 * - `{{props.xxx}}` placeholders, filled with values passed via `prop-xxx="value"` attributes.
 */
export declare class Component extends RenderableJaw {
	/** Always `"component"` — non-writable and non-configurable. */
	readonly type: "component";

	/**
	 * Props passed to this component instance at the call site via `prop-*` attributes.
	 * Populated at render time; writable.
	 */
	props: Record<string, any>;

	/**
	 * Creates a new Component instance and automatically registers it with Shark
	 * via `Shark.registerComponent()`.
	 *
	 * @param jawId - Identifier for this Component. Defaults to the camelCase subclass name.
	 */
	constructor(jawId?: string | null);

	/** @deprecated Pass only `jawId`. */
	// eslint-disable-next-line @typescript-eslint/unified-signatures
	constructor(jawId: string | null | undefined, jawDefinition: object);
}


// ── Controller ────────────────────────────────────────────────────────────────

/**
 * The class to extend to create Controller classes.
 * Controllers manage application logic and are registered globally with Shark.
 */
export declare class Controller extends Jaw {
	/** Always `"controller"` — non-writable and non-configurable. */
	readonly type: "controller";

	/**
	 * Creates a new Controller instance and automatically registers it with Shark
	 * via `Shark.registerController()`.
	 *
	 * @param jawId - Identifier for this Controller. Defaults to the camelCase subclass name.
	 */
	constructor(jawId?: string | null);

	/** @deprecated Pass only `jawId`. */
	// eslint-disable-next-line @typescript-eslint/unified-signatures
	constructor(jawId: string | null | undefined, jawDefinition: object);
}


// ── PageTemplate ──────────────────────────────────────────────────────────────

/**
 * The class to extend to create PageTemplate classes.
 * A PageTemplate defines a shared layout shell with named `<slot>` placeholders
 * that individual Views fill via `<shark-template name="..." slot="...">`.
 *
 * PageTemplates can only have a single template — use `setTemplate()`.
 * Calling `addTemplate()` throws an error.
 */
export declare class PageTemplate extends RenderableJaw {
	/** Always `"pageTemplate"` — non-writable and non-configurable. */
	readonly type: "pageTemplate";

	/**
	 * Creates a new PageTemplate instance.
	 *
	 * @param jawId - Identifier for this PageTemplate. Defaults to the camelCase subclass name.
	 */
	constructor(jawId?: string | null);

	/**
	 * @throws Always throws — PageTemplates support only one template. Use `setTemplate()`.
	 */
	addTemplate(name: string, content: string): never;
}


// ── View ──────────────────────────────────────────────────────────────────────

/**
 * The class to extend to create View classes.
 * A View can only have a single template; use `setTemplate()` to set it.
 */
export declare class View extends RenderableJaw {
	/**
	 * The main route associated with this View.
	 * @deprecated In favour of the SwimWay router.
	 */
	$mainRoute: string;

	/** Always `"view"` — non-writable and non-configurable. */
	readonly type: "view";

	/**
	 * Creates a new View instance and automatically registers it with Shark
	 * via `Shark.registerView()`.
	 *
	 * @param jawId - Identifier for this View. Defaults to the camelCase subclass name.
	 */
	constructor(jawId?: string | null);

	/** @deprecated Pass only `jawId`. */
	// eslint-disable-next-line @typescript-eslint/unified-signatures
	constructor(jawId: string | null | undefined, jawDefinition: object);

	/**
	 * @deprecated Views support only one template. Use `setTemplate()` instead.
	 * This override ignores `name` and delegates to `setTemplate(content)`.
	 */
	addTemplate(name: string, content: string): Record<string, string> | undefined;
}


// ── Shark ─────────────────────────────────────────────────────────────────────

export declare class Shark {
	// ── Trace level constants ─────────────────────────────────────────────────
	static readonly TRACE_ERROR: "error";
	static readonly TRACE_INFO: "info";
	static readonly TRACE_LOG: "log";
	static readonly TRACE_NONE: "none";
	static readonly TRACE_WARN: "warn";

	// ── Global state ──────────────────────────────────────────────────────────

	/** The global reactive store. Properties set here trigger auto-render on bound Views. */
	static $store: Record<string, any>;

	/** The currently active page descriptor. */
	static activePage: { id: string };

	/** Application-level data bag. */
	static appData: Record<string, any>;

	/** Whether Shark has been initialized. */
	static isInitialized: boolean;

	/** Localization labels. */
	static labels: Record<string, any>;

	/** Registered page templates, keyed by name. */
	static pageTemplates: Record<string, PageTemplate>;

	/** Current trace level. Defaults to `TRACE_WARN`. */
	static traceLevel: string;

	// ── Lifecycle ─────────────────────────────────────────────────────────────

	/**
	 * Initialize the Shark framework.
	 *
	 * @param options.labels - Localization labels object.
	 * @param options.remoteCallTimeOutDuration - Milliseconds before aborting remote calls. Default: 15000.
	 * @param options.templateRenderer - Renderer class to use. Default: PreactRenderer.
	 * @param forceReinit - If `true`, re-runs initialization even if already done.
	 */
	static init(options?: {
		labels?: Record<string, any>;
		remoteCallTimeOutDuration?: number;
		templateRenderer?: any;
		[key: string]: any;
	}, forceReinit?: boolean): void;

	/**
	 * Render the given jaw (or the current active View if omitted) to the screen.
	 *
	 * @param currJaw - The jaw to render. Defaults to the currently active View.
	 * @param options - Renderer options passed through to the active renderer.
	 */
	static render(currJaw?: Jaw, options?: Record<string, any>): boolean;

	// ── Navigation ────────────────────────────────────────────────────────────

	/**
	 * Open a registered View, making it the active page.
	 *
	 * @param pageIdOrJaw - The View instance or its string ID.
	 * @param options - Options forwarded to the View's `open()` / `init()` lifecycle.
	 */
	static openPage(pageIdOrJaw: string | Jaw, options?: Record<string, any>): boolean;

	/**
	 * Activate a View without necessarily making it the visible page.
	 */
	static activateView(pageIdOrJaw: string | Jaw, options?: Record<string, any>): boolean;

	/**
	 * Navigate to a SwimWay route.
	 *
	 * @param route - The route string or SwimRoute object to navigate to.
	 */
	static navigateToRoute(route: string | object): void;

	/**
	 * Parse the current `document.location` and return the View name encoded in the URL.
	 */
	static parseRequestedViewFromLocation(): string;

	// ── Store ─────────────────────────────────────────────────────────────────

	/**
	 * Retrieve one or more values from the global store.
	 *
	 * @param itemName - Key name or array of key names. If omitted, returns the whole store.
	 */
	static get(itemName?: string | string[]): any;

	/**
	 * Set one or more values on the global store.
	 * Triggers auto-render on any Views that reference the changed keys.
	 *
	 * @param nameOrObject - Property name or plain object of `{ name: value }` pairs.
	 * @param value - Value to assign (only used when `nameOrObject` is a string).
	 */
	static set(nameOrObject: string | Record<string, any>, value?: any): any;

	// ── Registration ──────────────────────────────────────────────────────────

	/** Register a Component so it can be referenced in templates. */
	static registerComponent(jaw: Component): void;

	/** Register a Controller. */
	static registerController(jaw: Controller): void;

	/** Register a SmartModel class under a given name. */
	static registerModel(modelName: string, modelClass: typeof SmartModel): void;

	/**
	 * Register a PageTemplate so Views can reference it by name.
	 * Call this after `setTemplate()` on the PageTemplate instance.
	 */
	static registerPageTemplate(jaw: PageTemplate): void;

	/** Register a View so it can be opened via `openPage()`. */
	static registerView(jaw: View): void;

	// ── Model helpers ─────────────────────────────────────────────────────────

	/**
	 * Return a new instance of a registered model, optionally pre-populated with data.
	 *
	 * @param modelNameOrClass - The registered name string or the model class itself.
	 * @param modelData - Data to import into the new instance.
	 */
	static getInstance(modelNameOrClass: string | typeof SmartModel, modelData?: object): SmartModel;

	/**
	 * Return an array of model instances from an array of data objects.
	 */
	static getInstanceList(modelNameOrClass: string | typeof SmartModel, dataList: object[]): SmartModel[];

	/**
	 * Retrieve a model instance registered in the global store by dot-notation path.
	 */
	static getReferenceModel(path: string): SmartModel | null;

	// ── Utilities ─────────────────────────────────────────────────────────────

	/** Bind a View's DOM to a model using a CSS container selector. */
	static bindViewToModel(containerCSSSelector: string): void;

	/** Generate a UUID string. */
	static generateUUID(): string;

	/**
	 * Emit a trace message if the current `traceLevel` allows it.
	 *
	 * @param args - Message and optional data to log.
	 */
	static trace(...args: any[]): void;

	/**
	 * Return `true` if the given level should be emitted at the current `traceLevel`.
	 */
	static shouldTrace(level: string): boolean;

	/**
	 * Update URLSearchParams in the current URL without adding a browser history entry.
	 */
	static setURLSearchParams(
		urlSearchParams: string | object | URLSearchParams | null,
		replace?: boolean,
		routeObject?: object | null
	): void;
}


// ── SmartModel ────────────────────────────────────────────────────────────────

/** Describes a single dirty property entry, tracking the original value before changes. */
interface SmartModelDirtyEntry {
	property: string;
	originalValue: any;
}

/** Options accepted by `export` / `__export`. */
interface SmartModelExportOptions {
	/** If provided, only the listed property names will be exported. */
	fields?: string[];
}

/** Options accepted by `import` / `__import`. */
interface SmartModelImportOptions {
	/** If `true`, properties present in `data` but missing on the model will be created. Default: `false`. */
	createMissingProperties?: boolean;
	/** If `true`, empty/falsy values in `data` are still matched onto the model. Default: `true`. */
	matchEmptyParameters?: boolean;
}

/** Options accepted by `importField`. */
interface SmartModelImportFieldOptions {
	/** If `true`, `undefined`/`null` values are accepted. Default: `false`. */
	acceptUndefined?: boolean;
	/** Explicit data type for parsing. `"auto"` performs no conversion. Default: `"auto"`. */
	dataType?: "auto" | "boolean" | "date" | "number";
	/** Fallback value used when the parsed number is `NaN`. Only for `dataType: "number"`. */
	defaultValue?: number;
	/** If `true`, date values are parsed as UTC and converted to local time. Default: `true`. */
	useUTC?: boolean;
}

/**
 * Payload dispatched with `"dataChanged"` and `"<propertyName>Changed"` events.
 */
interface SmartModelChangeEventData {
	/** The `__modelName` of the model that triggered the change. */
	modelName: string | undefined;
	/** The new value assigned to the property. */
	newValue: any;
	/** The previous value of the property before the change. */
	oldValue: any;
	/** The dot-notation path of the property that changed. */
	property: string;
}

/** Describes an item used in array-form calls to `set()`. */
interface SmartModelSetItem {
	name: string;
	value: any;
}

/** Inferred type map produced by `SmartModel.inferTypes()`. */
type SmartModelInferredTypes = Record<
	string,
	"number" | "datetime" | "boolean" | "string" | "array" | "object" | typeof SmartModel
>;

/**
 * Base class for reactive data models in the Shark MVC framework.
 *
 * @fires SmartModel#dataChanged - Emitted whenever a property changes value.
 * @fires SmartModel#<propertyName>Changed - Emitted for the specific changed property.
 */
export declare class SmartModel extends EventTarget {
	/** Unique GUID assigned at construction. Non-writable. */
	readonly __shguid: string;

	/** Whether any property of this model differs from its original/cleaned value. */
	__isDirty: boolean;

	/** List of properties that have changed since the last `clean()` call. */
	__dirtyProperties: SmartModelDirtyEntry[];

	/** Auto-bound property names (reserved for internal use). */
	__boundProperties: string[];

	/** The model structure passed at construction, if any. */
	__modelStructure: object | undefined;

	/** The renderer instance associated with this model. */
	__renderer: any;

	// ── Private methods exposed via Object.defineProperty ────────────────────

	protected readonly __clean: (properties?: string[]) => SmartModelDirtyEntry[];
	protected readonly __export: (options?: SmartModelExportOptions) => Record<string, any>;
	protected readonly __import: (data: object, options?: SmartModelImportOptions) => any;
	protected readonly __restore: (properties?: string[]) => void;
	protected readonly __setPropertyDirtiness: (propertyName: string, eventData: SmartModelChangeEventData) => void;
	protected readonly __toJSON: (forcePrivateProperties?: boolean) => Record<string, any>;

	/**
	 * Creates a new SmartModel instance.
	 */
	constructor(data?: object, options?: SmartModelImportOptions, modelStructure?: object);

	/** Replace the renderer instance for this model. */
	addRenderer(renderer: { setModel(model: SmartModel): void; [key: string]: any }): void;

	/**
	 * Clear dirty state for all properties, or only the specified ones.
	 * After this call, `__isDirty` is recomputed.
	 */
	clean(properties?: string[]): SmartModelDirtyEntry[];

	/** Dispatch an event from this model using jQuery's `.trigger()`. */
	emit(eventName: string, eventData?: any): JQuery;

	/**
	 * Export all public, non-function properties to a plain object.
	 * Properties starting with `__` or `jQuery` are excluded by default.
	 */
	export(options?: SmartModelExportOptions): Record<string, any>;

	/** Export an array field as a JSON string. */
	exportArrayField(field: string, format?: "JSON"): string;
	protected __exportArrayField(field: string, format?: "JSON"): string;

	/** Export a boolean field as a number (`1`/`0`) or string. */
	exportBooleanField(field: string, format?: "number" | "string"): number | string;
	protected __exportBooleanField(field: string, format?: "number" | "string"): number | string;

	/** Export a date field as a formatted string. */
	exportDateField(field: string, format?: "ISO", useUTC?: boolean): string;
	protected __exportDateField(field: string, format?: "ISO", useUTC?: boolean): string;

	/** Export a numeric field, parsing strings to floats if necessary. */
	exportNumberField(field: string, format?: string): number;
	protected __exportNumberField(field: string, format?: string): number;

	/** Export an object field as a JSON string. */
	exportObjectField(field: string, format?: "JSON"): string;
	protected __exportObjectField(field: string, format?: "JSON"): string;

	/** Import data from a plain object onto this model. */
	import(data: object, options?: SmartModelImportOptions): any;

	/** Import and parse a boolean field from a raw value. */
	importBooleanField(field: string, value: any): boolean;
	protected __importBooleanField(field: string, value: any): boolean;

	/** Import and parse a date field, converting it to a `moment` object. */
	importDateField(field: string, value: any, useUTC?: boolean): boolean;
	protected __importDateField(field: string, value: any, useUTC?: boolean): boolean;

	/** Import and parse a numeric field. */
	importNumberField(field: string, value: any, defaultValue?: number): boolean;
	protected __importNumberField(field: string, value: any, defaultValue?: number): boolean;

	/**
	 * Unified import helper that dispatches to the correct typed import method
	 * based on `options.dataType`.
	 */
	importField(field: string, value: any, options?: SmartModelImportFieldOptions): boolean;

	/**
	 * Inspect an instance of this model class and infer the data type of each public property.
	 * Results are also logged to the console.
	 */
	static inferTypes(): void;

	/**
	 * Check whether this model has unsaved/unclean property changes.
	 *
	 * @param properties - A single property path or array of paths to check.
	 * @param mode - `"any"` (default): `true` if at least one listed property is dirty.
	 *               `"all"`: `true` only if every listed property is dirty.
	 */
	isDirty(properties?: string | string[] | null, mode?: "any" | "all"): boolean;

	/** Remove an event listener from this model using jQuery's `.off()`. */
	off(eventName: string, eventHandler: (...args: any[]) => any): JQuery;

	/** Attach an event listener to this model using jQuery's `.on()`. */
	on(eventName: string, eventHandler: (...args: any[]) => any): JQuery;

	/**
	 * Register a property as bound to a View (called internally by `parseTemplates`).
	 *
	 * @param propertyName - The model property name.
	 * @param viewClassName - The `className` of the View that references this property.
	 */
	registerBoundProperty(propertyName: string, viewClassName: string): void;

	/** Restore dirty properties to their original values and reset `__isDirty` to `false`. */
	restore(properties?: string[]): void;

	protected __singleSet(name: string, value: any, eventTargetNode?: Element | null): void;

	/**
	 * Assign a value to one or more model properties.
	 *
	 * @fires SmartModel#dataChanged
	 * @fires SmartModel#<propertyName>Changed
	 */
	set(name: string, value: any, eventTargetNode?: Element | null): void;
	set(name: Record<string, any>, eventTargetNode?: Element | null): void;
	set(name: SmartModelSetItem[], eventTargetNode?: Element | null): void;

	/** Serialize this model to a plain object. */
	toJSON(forcePrivateProperties?: boolean): Record<string, any>;

	/** Serialize this model to a JSON string. */
	toString(forcePrivateProperties?: boolean): string;

	/** @experimental Sync a single property value to all matching `[data-sh-prop]` DOM elements. */
	updateScreenWithModelValue(
		name: string,
		eventTargetNode: Element | null,
		value: any,
		eventData: SmartModelChangeEventData | string
	): void;

	/** @experimental @dangerous Sync all public properties to their matching `[data-sh-prop]` DOM elements. */
	updateScreenWithModelValues(): void;

	// ── Optional lifecycle hooks ──────────────────────────────────────────────

	/** Called whenever any property changes. Override in subclasses. */
	onDataChanged?(eventData: SmartModelChangeEventData): void;

	/** Catch-all index signature for dynamic `on<PropertyName>Changed` hooks. */
	[key: string]: any;
}


// ── SwimRoute ─────────────────────────────────────────────────────────────────

/** Data object accepted by the `SwimRoute` constructor. */
interface SwimRouteData {
	/** Route pattern, optionally containing dynamic segments prefixed with `:` (e.g. `"/user/:id"`). */
	route: string;
	/** The View instance or class associated with this route. */
	view: any;
}

/**
 * Represents a single application route, pairing a URL pattern with a View
 * and providing dynamic parameter extraction.
 */
export declare class SwimRoute {
	/** The route pattern string (e.g. `"/user/:id/orders/:orderId"`). */
	route: string;

	/** The View instance or class associated with this route. */
	view: any;

	/** The last matched URL for this route. */
	url: string;

	/** The dynamic parameters extracted from the last successful `extractRouteParams()` call. */
	readonly params: Record<string, string>;

	constructor(data: SwimRouteData);

	/**
	 * Match a URL against this route's pattern and extract any dynamic segment values.
	 *
	 * @param url - The URL to match. Falls back to `this.url` if omitted.
	 */
	extractRouteParams(url?: string): void;
}


// ── SwimWay ───────────────────────────────────────────────────────────────────

/**
 * The basic router for the Shark environment.
 * Fun Fact: "SwimWay" is the name given by researchers to a route followed in the ocean by sharks.
 */
export declare class SwimWay {
	/**
	 * @param routingMethod - One of `"pathname"` (default), `"url"`, or `"hash"`.
	 */
	constructor(routingMethod?: "pathname" | "url" | "hash");

	/** Add a single route. Returns the new total number of routes. */
	addRoute(route: SwimRouteData | SwimRoute): number;

	/** Add multiple routes at once. Returns the new total number of routes. */
	addRoutes(routes: (SwimRouteData | SwimRoute)[]): number;

	/** Navigate to a route by path string or SwimRoute object. */
	navigateTo(route: string | SwimRoute): boolean;

	/**
	 * Parse `document.location` and return the View name encoded in the current URL.
	 */
	getRequestedViewFromLocation(): string;

	/**
	 * Update URLSearchParams in the current URL without creating a new browser history entry.
	 *
	 * @param urlSearchParams - A string, plain object, or `URLSearchParams` instance.
	 */
	setURLSearchParams(urlSearchParams: string | object | URLSearchParams): void;
}


// ── Utils ─────────────────────────────────────────────────────────────────────

export declare class Utils {
	/**
	 * Return a random number between 0 and `max`, or between `minOrMax` and `max`.
	 */
	static betterRandom(minOrMax: number, max?: number): number;

	/**
	 * Return a random integer between 0 and `max`, or between `minOrMax` and `max`.
	 */
	static betterRandomInt(minOrMax: number, max?: number): number;

	/** Convert a camelCase string to dash-separated lowercase words. */
	static camelToDashed(inputString: string): string;

	/** Compute a simple numeric hash of any serializable value. */
	static computeHash(value: any): number;

	/** Convert a dash-separated string to camelCase. */
	static dashedToCamel(inputString: string): string;

	/** Decode common HTML entities in a string. */
	static decodeHtmlEntities(str: string): string;

	/** Deep-merge any number of objects into a new object. */
	static deepMerge(...objects: object[]): object;

	/** Return an object containing only the properties that differ between two objects. */
	static extractDifferentProperties(firstObject: object, secondObject: object): object;

	/**
	 * Parse the attributes of an HTML opening tag string into a plain object.
	 *
	 * - `data-*` attributes are grouped under `result.dataset` (camelCase keys, no `data-` prefix).
	 * - `prop-*` attributes are grouped under `result.props` (camelCase keys, no `prop-` prefix).
	 *   These are **not** passed to the HTML tag root; they are used exclusively for `{{props.xxx}}`
	 *   interpolation in component templates.
	 * - All other attributes are returned as camelCase top-level keys.
	 */
	static extractPropertiesFromHTMLString(html: string): {
		dataset?: Record<string, any>;
		props?: Record<string, any>;
		[key: string]: any;
	};

	/**
	 * Extract all top-level `<shark-xxx>` component tags from a template string.
	 *
	 * Unlike a simple regex, this function correctly handles nested shark components
	 * by counting open/close depth, so slot content containing other `<shark-yyy>` tags
	 * is never truncated.
	 *
	 * @param template - The HTML template string to scan.
	 * @returns Array of full tag strings for every top-level shark component found.
	 */
	static extractSharkComponentTags(template: string): string[];

	/** Flatten a nested object into a single-level object (non-recursive values only). */
	static flatten(objectToFlatten: object): object;

	/** Generate a random GUID string, optionally with a prefix and/or suffix. */
	static generateGUID(prefix?: string, suffix?: string): string;

	/**
	 * Get a property value from an object by dot-notation path.
	 * Returns `undefined` if the path does not exist.
	 */
	static getDeepProperty(object: object, path: string): any;

	/**
	 * Cross-reference `sourceList` items against named lookup lists, attaching matched
	 * objects as `__<propertyName>` properties (looks for `*Guid` properties as foreign keys).
	 */
	static matchLists(sourceList: any[], matchLists: Record<string, any[]>, options?: object): void;

	/**
	 * Copy properties from `sourceObject` onto `targetObject`, with configurable rules
	 * for missing properties, empty values, and undefined values.
	 */
	static matchProperties(
		targetObject: object,
		sourceObject: object,
		options?: {
			createMissingProperties?: boolean;
			matchEmptyParameters?: boolean;
			matchUndefinedParameters?: boolean;
			exclude?: string[];
		}
	): void;

	/**
	 * Merge the attributes of `includeTag` onto the root element of `templateHtml`.
	 *
	 * - `class` values are concatenated.
	 * - `style` values are merged (includeTag wins on conflicts).
	 * - `data-*` attributes are merged (includeTag wins on conflicts).
	 * - `prop-*` attributes are **excluded** — they are never serialized onto the HTML tag.
	 * - All other attributes are overwritten by `includeTag`.
	 */
	static mergeAttributes(templateHtml: string, includeTag: string): string;

	/** Merge two inline style strings, with `includeStyle` winning on conflicts. */
	static mergeStyle(templateStyle: string, includeStyle: string): string;

	/** Move the caret to the end of an input or textarea element. */
	static moveCaretToEnd(target: HTMLInputElement | HTMLTextAreaElement): void;

	/** Flatten a (possibly nested) object into an array of dot-notation property paths. */
	static objectToFlatMap(object: object, parent?: string): string[];

	/** Safely parse a JSON string, returning a typed fallback on failure. */
	static parseJSON(data: string, expectedType?: "array" | "object" | string): any;

	/** Add `_index` and `_displayIndex` properties to every item in an array (mutates in place). */
	static reindexList(list: any[]): void;

	/**
	 * Replace `null` or `undefined` values in an object or array with `replaceVal` (mutates in place).
	 */
	static replaceNullValue(objectToParse: object | any[], replaceVal: any): void;

	/**
	 * Resolve named slot content and `prop-*` interpolation for a component template.
	 *
	 * Given the component's own template HTML and the full usage tag from the parent
	 * template, this function:
	 * 1. Extracts `<slot name="...">content</slot>` children from the usage tag and
	 *    substitutes them into matching `<slot name="..."></slot>` placeholders in the
	 *    component template.
	 * 2. Extracts `prop-*` attributes from the usage tag and substitutes them into
	 *    `{{props.xxx}}` placeholders in the component template.
	 *
	 * Unmatched slots and unmatched `{{props.xxx}}` placeholders are left unchanged
	 * as implicit fallback content.
	 *
	 * @param componentTemplate - The component's own HTML template string.
	 * @param componentUsageTag - The full usage tag as written in the parent template,
	 *   e.g. `<shark-foo prop-id="bar"><slot name="title">Hi</slot></shark-foo>`.
	 * @returns The resolved template string.
	 */
	static resolveComponentSlots(componentTemplate: string, componentUsageTag: string): string;

	/** JSON-stringify a value, safely handling circular references and `Map` instances. */
	static safeStringify(sourceValue: any): string;

	/**
	 * Shorthand for `searchArrayForProperty`.
	 */
	static safp(
		list: any[],
		property: string,
		value: any,
		searchType?: boolean | "first" | "all" | "index"
	): object | any[] | number | null;

	/**
	 * Search an array for the first object (or all objects) whose named property equals `value`.
	 *
	 * @param searchType - `"first"` (default): return the first match.
	 *                     `"all"`: return an array of all matches.
	 *                     `"index"`: return the index of the first match.
	 *                     Passing `true` is equivalent to `"first"`; `false` to `"all"`.
	 */
	static searchArrayForProperty(
		list: any[],
		property: string,
		value: any,
		searchType?: boolean | "first" | "all" | "index"
	): object | any[] | number | null;

	/**
	 * Assign a value to a property on an object, creating intermediate objects as needed.
	 */
	static setDeepProperty(object: object, path: string, value: any, depth?: number): object;

	/** Legacy trace utility. Prefer `Shark.trace()`. */
	static trace(content: string): void;

	/** Lowercase the first character of a string. */
	static toCamelCase(value: string): string;

	/** Uppercase the first character of a string, optionally lowercasing the rest. */
	static toTitleCase(value: string, forceLowerCase?: boolean): string;

	/** Pad a number with leading zeros to a given total length. */
	static zeroFill(number: number, length: number): string;
}